GeezerVison

Summary

First of three stacked PRs for the docs IA overhaul (Proposal 1, section 3). This PR dissolves docs/ai-coder/ into four top-level sidebar sections, in this order, where "Run AI coding agents in Coder" used to be: Coder Agents, AI Governance (with Agent Firewall and AI Gateway nested under it), Agent Relay, and MCP server.

• Files move with git mv, so git log --follow keeps their history. The move includes every file in the moved folders, including pages that are not in the sidebar, such as agent-firewall/example-policy.md, and pages added to main after the first version of this PR, such as agents/projects.md (docs(docs): add Coder Agents projects page #30684) and agents/acp-subagents.md (docs: document ACP subagents #31430).
• docs/ai-coder/index.md, best-practices.md, and ide-agents.md are deleted. Each has a redirect (see below).
• docs/manifest/ mirrors the new folders: coder-agents.yml (+ coder-agents/), ai-governance.yml (+ ai-governance/), agent-relay.yml, and mcp-server.yml. ai-coder.yml is deleted. The Projects and ACP subagents entries from main move with Coder Agents.
• Every relative link and image path is fixed, both in the moved pages (their base directory changed) and in pages that link to them. This was done in one scripted pass from a clean main checkout. Every link was then checked to resolve on disk.
• Commit 2, chore: point in-product docs links at the new docs paths, updates docs URLs outside docs/: site/ docs() links, Go error strings and comments, README.md, server.json, templatebuilder modules, and the doc-check skill. Commit 4 reverts the unversioned https://coder.com/docs/... URLs among them (see below), so after this PR only these differ from main outside docs/: the site/ docs() links, the versioned cli/cliui troubleshooting links, and repo file paths in comments and the doc-check skill's examples (docs/coder-agents/..., docs/templates/...). You can drop commit 2; the redirects cover the old URLs.
• docs: promote Templates to a top-level sidebar section #31646 (Templates) was squash-merged into this branch as 98377a3a3b. This PR now also carries the Templates move (docs/admin/templates/** → docs/templates/**, plus template-from-scratch.md and testing-templates.md) and its chore changes. Refer to docs: promote Templates to a top-level sidebar section #31646 for that part's move map, redirects, and review.
• Commit 4, fix: keep docs links healthy before the release, keeps links working on the live site until a release that includes this stack becomes the default docs version:
  • Hand-written pages that linked to moved pages with absolute https://coder.com/docs/... URLs now use relative links, anchors kept. The new paths 404 on the live site today, but relative links resolve for every version and are checked locally.
  • Hardcoded, unversioned https://coder.com/docs/<new path> URLs outside docs/ that the chore commits introduced (Go strings including the prebuilds metric help, CLI help, the agentFallbackTroubleshootingURL default, README.md, server.json, examples, templatebuilder files, and one site/ constant) go back to their current paths. Then make gen regenerated the generated table in docs/admin/integrations/prometheus.md, scripts/metricsdocgen/generated_metrics, the CLI golden files, and docs/reference/cli/templates/{create,edit}.md. See "Post-release follow-up".
  • The site/ docs() changes and the cli/cliui links stay, because those URLs are versioned (/docs/@vX.Y.Z/...) and resolve once the release ships.
• Commit 5, docs: prefix relative links in the moved pages with ./, adds ./ to 13 relative links that the move script wrote without it, in docs/mcp-server.md and three Templates pages.
  They resolved, but every other relative link in the docs starts with ./ or ../.
• Commit 6, docs: keep the coding agent module guidance in the templates docs, adds an AI agent modules section to docs/templates/extending-templates/modules.md.
  Deleting docs/ai-coder/index.md removed the only instructions for adding a terminal coding agent to a template with a registry module.
  The example (registry.coder.com/coder/claude-code/coder, version = "~> 5.2") passes terraform validate, and the Template Builder labels it cites match site/src/pages/TemplateBuilder/ModuleSelectStep.tsx.

Stack: this PR (with #31646 squash-merged in) → docs/ia-tutorials-nav (#31647, Tutorials + nav renames) → docs/ia-workspaces-folder (#31650, folder rename).

Refs: Linear DOCS-1154, DOCS-1179, and DOCS-1479 for the coder.com and router redirect fix.

Move map

Redirects added

Appended to docs/redirects.json, using the absolute /docs/... format that main validates today. Wildcards cover every page under each moved folder, including pages that are not in the sidebar and the pages added to main since the first version of this PR.

None of the 3 existing rules in docs/redirects.json points into ai-coder/, so no destinations needed updating.

coder.com and router static redirects.
coder.com applies its own redirects.json and the rules it generates from this file before it hands /docs to the docs-engine router, which applies its own static redirects.json before the page.
Three older static rules in both repos send /docs/templates, /docs/templates/open-in-coder, and /docs/templates/troubleshooting to /docs/admin/templates/..., and the /docs/admin/templates/:path* rule here sends them back, so each loops once a release with this layout is the docs mainline.
A static /docs/workspaces rule would also hide the new docs/workspaces/index.md page from #31650.
coder/coder.com#1201 and coder/docs-engine#304 (draft, DOCS-1479) remove those rules; they must merge when that release becomes the mainline, not before, because the old-layout mainline still needs them.
A chain simulation of every page and static source on each branch of this stack finds no other loops or hidden pages.
The /docs/ai-coder/... and other legacy rules there still work; some now take two redirects.

Deviations from the proposal

• Glossary "IDE agent" entry. The proposal says to remove this link and leave plain text. I pointed it at Access your workspace (docs/user-guides/workspace-access/index.md) instead, the same page the ide-agents redirect uses, because "Refer to IDE agents." with no link reads as a dead end. The "Coding agent" entry now links to Coder Agents, as the proposal says.
• Top-level icons. The new sections need icons. I chose wand.svg (Coder Agents, the old ai-coder icon), ai_intelligence.svg (AI Governance), link.svg (Agent Relay), and plug.svg (MCP server).
• Coding agent module guidance. Kept on the Reuse template code page (commit 6) instead of deleted with docs/ai-coder/index.md. The best-practices and IDE-agent pages are deleted as proposed.
• Order relative to Administration. In this PR the four sections sit where ai-coder was, after Administration. PR C moves Administration after MCP server to reach the final order.
• docs/mcp-server.md repo link. A relative link to codersdk/toolsdk/toolsdk.go, outside docs/, was re-based for the new depth.
• Left unchanged on purpose:
  • Database migrations and the notification .golden files rendered from them still contain coder.com/docs/ai-coder/... URLs. Existing migrations can't be edited, so those links rely on the redirects.
  • aibridge/client/client.go links to a commit-pinned GitHub permalink, which still resolves.
  • Test fixtures in scripts/docsredirectscheck and .github/workflows/test-docs-preview-mapper.sh use ai-coder as sample data.
  • site/src/pages/AgentsPage/components/ChatElements/tools/Tool.stories.tsx uses https://coder.com/docs/ai-coder/ai-gateway as a sample web search result. Changing it would only change a visual snapshot.

Open questions for Nick

1. Do you agree with the three redirect targets for the deleted pages above?
2. Should the "IDE agent" glossary entry link to Access your workspace (current) or be plain text (proposal)?
3. Are the icons for the new top-level sections OK?
4. Open PRs that touch the moved files, checked with git merge-tree against this branch. I didn't change them.
   • docs(docs/ai-coder): configure Claude API key helpers for AI Gateway #31169 merges cleanly: Git's rename detection carries its edit to docs/ai-governance/ai-gateway/clients/claude-code.md, and its new relative link still resolves at the new path.
   • docs(docs/ai-coder/ai-gateway): document Responses WebSocket mode #30262 now targets tk/ai-gateway-responses-ws-endpoint and conflicts with main in 21 files. Against this branch it conflicts in the same 21 files, with codex.md at its new path, so this PR doesn't add new conflicts. Its new relative links still resolve after the move.
   • ci: make docs redirects relative and block removed routes #30805 conflicts in docs/redirects.json. It already conflicts with main there, because main added the /docs/about/screenshots and /docs/install/cli rules.

Release

No backport to release/2.39 for now; Nick may apply it by hand later.
A cherry-pick of this branch onto release/2.39 conflicts in 25 files, and #31647 and #31650 would need the same treatment to keep the stack together.
coder/coder.com#1201 and coder/docs-engine#304 merge when the first release line that carries this layout becomes the docs mainline (2.38 today).

Known limitations

• CLI newer than its server. The cli/cliui troubleshooting links append /templates/troubleshooting#... to the server's versioned docs URL.
  A CLI from this release against an older server prints /docs/@v2.38.x/templates/troubleshooting#....
  The router's static /docs/templates/:page(open-in-coder|troubleshooting) rule redirects that to the old page today, but coder/docs-engine#304 removes that rule to fix the loop, so after the cutover that case gets the version's not-found page.

Post-release follow-up

After a release that includes this stack becomes the default docs version on coder.com, point these hardcoded URLs at the new paths. They work today and redirect after the release, so nothing breaks in the meantime. Anchors are unchanged. Rerun make gen afterward to update docs/admin/integrations/prometheus.md, scripts/metricsdocgen/generated_metrics, the CLI golden files, and docs/reference/cli/templates/{create,edit}.md.

Validation run

• make gen/docs-manifest: clean diff afterward.
• make lint/docs-manifest, lint/docs-redirects (go run ./scripts/docsredirectscheck -base origin/main: 15 rules OK, no removed-route warning), lint/docs-html, lint/emdash: pass.
• pnpm check-docs (markdownlint + table formatter): pass.
• Vale (vale --no-exit docs/): the same 12 warnings and 1 error as main, all pre-existing. Suggestions drop from 646 to 645; the one removed was in the deleted ide-agents.md.
• Local relative-link check over docs/**/*.md: 0 unresolved links or images (also 0 on main).
• Pre-commit hook: make pre-commit-light on the docs commit, and the full make pre-commit (gen, fmt, lint/go, lint/ts, build, and others) on the chore commit. Both passed.
• Targeted tests:
  • Go: go test ./coderd/x/chatd/chattool/... ./codersdk/toolsdk/... ./coderd/templatebuilder/....
  • Site: Vitest for the touched directories (107 files, 1879 tests), and the story tests for CoderAgentsProductCard, GroupSettingsPageView, GatewayKeysPageView, and ModelForm (4 files, 63 tests).
• Every docs() path and anchor in the site/ and Go diff resolves to a page and heading in this branch.
• Frontend deep review (all 8 roles) on the site/ diff of PRs A and B: no blocking or should-fix findings. Nits on existing code that this PR only touched, not changed here: a single-use docsLink constant in ChatAccessDeniedAlert.tsx, and assertion-only play functions in the GatewayKeysPageView, ModelForm, CoderAgentsProductCard, and GroupSettingsPageView stories.
• Page counts: docs/**/*.md (excluding .style) 490 → 487; manifest.json routes 495 → 492. With docs: promote Templates to a top-level sidebar section #31646 squash-merged in, the counts don't change, because the Templates move only moves files.
• Link health (commit 4):
  • linkspector 0.5.6 with .github/.linkspector.yml over all of docs/, like the weekly docs job (umbrelladocs/action-linkspector, reporter: local, filter_mode: nofilter). I ran it locally with Chrome in --no-sandbox mode.
  • origin/main: 0 errors. Before the fix (17e54ad555): 6 errors, all https://coder.com/docs/<new path> 404s (shared-workspaces.md:19, esr-2.24-2.29-upgrade.md:80-82, tasks-to-chats-migration.md:73, prometheus.md:298). After the fix (def074caab): 0 errors. A first run after the fix also flagged a Red Hat URL in install/server/openshift.md. That URL is unchanged from main, and it passed on a rerun, so the failure was transient.
  • After the fix: make gen/docs-manifest (clean), lint/docs-manifest, lint/docs-redirects (15 rules OK against origin/main), lint/docs-html, lint/emdash, pnpm check-docs, and the relative-link check (0 unresolved in 3416 links) pass. The full make pre-commit, including make gen, passed on the commit.
  • Tests after the fix:
    • Go: go test ./cli -run 'TestCommandHelp|TestServerYAMLConfig', ./enterprise/cli -run TestEnterpriseCommandHelp, ./coderd/render, ./agent/agentscripts, ./coderd/prebuilds, ./enterprise/coderd/prebuilds, ./coderd/x/chatd/chattool/..., ./codersdk/toolsdk/..., ./coderd/templatebuilder/....
    • Site: Vitest for src/pages/TemplateBuilder (7 files, 67 tests).
• After the rebase onto ccf5ec74ae (commits 5 and 6 included): make gen/docs-manifest (clean), lint/docs-manifest, lint/docs-redirects (15 rules OK), lint/docs-html, lint/emdash, pnpm check-docs, and a relative-link and anchor check over the changed pages pass.
  The only unresolved anchor, docs/ai-governance/ai-gateway/cost-controls.md → enterprise.md#list-organization-ai-spend-by-user, is also broken on main.
  The pre-commit hook (make pre-commit-light, because both new commits touch only docs/) passed on commits 5 and 6. The rebased code commits rely on CI for Go and TypeScript checks.
• Redirect chains: a Node simulation of coder.com's static rules, its generated rules from this branch's docs/redirects.json, the router's static rules, the page, then this branch's rules on a miss, over every page and exact static source, reports the 3 loops above and nothing else new; with coder/coder.com#1201 and coder/docs-engine#304 applied, 0.
• Skipped: the docs-engine sync check, which was not available in this environment.