Hold until GA: repoint kagent.dev navigation from 0.x to 1.x

工作位于网站的源代码中，主要在 src/components/footer.tsx、src/app/page.tsx、src/components/key-components.tsx、src/app/agents/[agentId]/page.tsx 和博客 MDX 文件中。首先验证列出的行号和路径。对于每个链接，决定使用 1.x 映射或解决冲突/孤立链接的方案。为未版本化的链接添加显式的版本段。最后，审查 next.config.mjs 中的重定向逻辑，并记录关于 catch-all 的决定。

Do not action this before kagent 1.0 goes GA. kagent 1.0 is at a release candidate (v1.0.0-rc2), so kagent.dev's navigation deliberately keeps sending readers to the supported 0.x release. The links below look stale and are not. Repointing them early would land readers on prerelease documentation.

This issue exists so the pinning is not mistaken for an oversight, and so the mapping is worked out once rather than re-derived at GA. Paths and line numbers were re-verified against main (1a7a21e) on 2026-11-04.

1. Repoint the 16 hardcoded documentation links

Sixteen links across three components hardcode 0.x/. The information architecture changed between versions, so this is not a find-and-replace: each link needs a mapping, and four of the sixteen need a decision instead.

Each target in the table is a path under https://kagent.dev/docs/kagent/latest/, not under 1.x/, because 1.x/ is renamed to latest/ at release (section 4).

Every target in that table was confirmed to exist. Two groups need a judgement call rather than a path:

• quickstart and first-agent collapse into one 1.x page. 0.x ships Quick Start (install plus a first agent) and Creating your first agent (dashboard-based); 1.x ships only Your first agent. The footer lists both today. Either keep two entries, splitting them as setup/installation plus get-started/your-first-agent, or drop one.
• slack-a2a and discord-a2a have no 1.x equivalent at all. Either remove the two footer entries or leave them on 0.x deliberately.

2. Pin the unversioned links

src/app/agents/[agentId]/page.tsx:110 points at /docs/kagent/getting-started/quickstart with no version segment and reaches 0.x only through the catch-all redirect below. It is the only unversioned link in an app component.

Eleven more sit in blog content. Nine ride the catch-all redirect, and the two crewai-byo-agent.mdx tracing links ride the tracing redirect in section 3:

kagent-agent-substrate-sandboxes.mdx already links to 1.x/ explicitly and needs no change.

Blog links carry a different consideration from navigation links: a post describes the release it was written against, so pinning each to 0.x/ explicitly is likely to be more correct than repointing it to 1.x.

src/config/navigation.json is unversioned throughout, but it is consumed only by scripts/check-links.mjs and never imported by app code. It is a link-checker fixture rather than a rendered navigation tree, so treat it separately.

3. Decide what the catch-all redirect does

next.config.mjs:39-43 sends every legacy unversioned /docs/kagent/* URL to 0.x/. The recommendation is to leave it on 0.x: those URLs were 0.x content, and the 1.x information architecture does not match path-for-path, so retargeting would land readers on 404s or on the wrong page.

The same decision covers two further redirects at next.config.mjs:19-28. Both hardcode 0.x destinations, for /docs/getting-started/configuring-providers and /docs/kagent/getting-started/tracing, and both sit above the catch-all deliberately, because the pages they name also changed section.

4. Relabel the version switcher

At release, the version dropdown lists three entries, newest first:

• main (in development)
• 1.0.x (release). This label likely becomes 2026.11.1 when kagent moves to calendar versioning.
• 0.10.x

The dropdown is the versions list in docs-site/hugo.yaml:152-204, which has two entries today, 1.x (alpha) and 0.x (current). The same release edit moves latest: true from the 0.x entry to the 1.0.x entry, deletes the 1.x alpha banner, and replaces the 0.x banner with a superseded-version notice. The comments on those entries describe each step.

Decided: when 1.0 is cut, copy docs-site/content/kagent/1.x/ to main/, then rename 1.x/ to latest/. main carries main (in development), latest carries 1.0.x (release), and 0.x carries 0.10.x. Every "1.x target" in section 1 therefore lands under latest/. The rename has four knock-on edits:

• Redirect /docs/kagent/1.x/* to /docs/kagent/latest/*, because 1.x URLs are already published.
• Extend the catch-all's negative lookahead in next.config.mjs to exempt main and latest, or it redirects them into 0.x/.
• Repoint the hardcoded /docs/kagent/1.x/ links in docs-site/data/glossary.yaml.
• Check latest: true against the new linkVersion: "latest". The theme reads both as the latest-version signal, and the hugo.yaml comment warns that the noindex partial does nothing when two entries carry it.

Done when

• The 16 links resolve to 1.x, with the quickstart collision and the two orphaned examples decided rather than guessed
• src/app/agents/[agentId]/page.tsx:110 carries an explicit version segment
• The 11 blog links carry an explicit version segment, pinned to the release each post describes
• The catch-all and the two redirects above it have a recorded decision, whether or not that decision changes them
• 1.x/ is copied to main/ and renamed to latest/, with the 1.x redirect, the catch-all lookahead, and the glossary links updated
• The version switcher lists main (in development), 1.0.x (release), and 0.10.x, with latest and both banners updated
• No /docs/kagent/ link in src/ lacks a version segment, except the bare /docs/kagent version picker in navbar.tsx:42 and page.tsx:687