Skip to content

ci: make docs redirects relative and block removed routes - #30805

Merged
nickvigilante merged 7 commits into
mainfrom
vigilante/docs-main-redirects
Nov 5, 2026
Merged

nickvigilante merged 7 commits into
mainfrom
vigilante/docs-main-redirects

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 14, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Moves docs/redirects.json to relative routes and makes lint/docs-redirects fail when a PR removes a live docs route without a redirect.
coder.com and docs-engine build each version's redirects from that branch's file, so this file becomes the only place contributors add docs redirects.

Part of DOCS-1290; tracked in DOCS-1296.

Changes

  • New rule format: {"source": "path/to/page", "destination": "path/to/another-page"}, relative to the docs root of the branch's version.
    Trailing /* is the only wildcard, / is the version's docs root, one #fragment is allowed on exact destinations, and external destinations are limited to https://github.com/coder/ and https://coder.com/.
    The old /docs/... form is rejected with the converted rule in the message.
  • Removed-route check now blocks.
    Every route in the base manifest, the live page list for the target branch (coder.com/beta-docs/<version>/llms.txt), and the base file's sources must be a page or resolve through a rule.
    The failure names the old file and prints a paste-ready rule, suggesting a renamed sibling, a page with the same last segment, or /.
    An unreadable live list exits 2 in CI; -offline skips it locally.
    Links under /docs count as well, so the check keeps working if the list URL redirects there after the move to /docs.
  • docs/redirects.json on main: 304 rules.
    It carries the coder.com docs rules that 404 under /docs/@main today, plus the 144 @main-only rules coder.com holds, with three sibling sets condensed into wildcards (networking/*, admin/notifications/*, guides/*).
  • README, content guidelines, and agent guidance describe the new format.

Testing

  • go test ./scripts/docsredirectscheck/... (also -race), golangci-lint, and the pre-commit hook.
  • go run ./scripts/docsredirectscheck -base origin/main -branch main online, after merging current main: 304 rules OK, 497 routes resolve.
  • Renaming admin/integrations/istio.md without a rule fails with {"source": "admin/integrations/istio", "destination": "admin/integrations/istio-mesh"}; adding that rule passes.
  • coder.com's generateRedirects with this file and main's manifest: 0 dropped; 336 of 336 sampled old URLs resolve to the expected page with Next's matcher.
  • curl on every destination under coder.com/docs/@main: all 200.
  • Live baseline before merge: 185 of 336 sampled /docs/@main URLs return 404.
  • The check runs on Linux in ci.yaml's lint job; the package's unit tests also run on macOS and Windows in test-go-pg.

Merge order

Merge after the coder.com generator (coder/coder.com, vigilante/docs-redirects-relative) is deployed, otherwise coder.com drops these rules with warnings until it is.
The docs-engine change (coder/docs-engine, vigilante/version-redirects) can land before or after.
Then merge the release/2.38 backport.

Contract shared by coder/coder, coder.com, and docs-engine

Docs redirects contract (coder/coder owns the data; coder.com and docs-engine consume it)

Ownership

  • Every redirect for a moved, renamed, or removed docs page lives in coder/coder docs/redirects.json, one file per branch (main, release/X.Y).
  • A branch's file applies only to that branch's version of the docs. main's file applies to @main; release/X.Y's file applies to vX.Y, and to unversioned /docs while X.Y is mainline.
  • URL-scheme rules (/docs/v1, /docs/v2/..., /docs/coder-oss/..., /docs/coder/..., /docs/code-server/..., classic /@v<line> forms) are not content moves. They stay in the consumer that owns the URL scheme, as code or a static engine-owned file.
  • Nobody adds content redirects in coder.com or docs-engine. Existing ones there are removed only after the matching coder/coder rules are verified live for that version (later phase, not this change).

File format

docs/redirects.json is a JSON array. Each entry is an object with exactly these fields:

Field Required Meaning
source yes A route relative to the docs root of this version
destination yes A route relative to the docs root, / for the docs root, or an allowed https:// URL
permanent no Boolean, default true. true answers 308, false answers 307

Unknown fields are an error.

Routes

  • A route is the URL path below /docs with no version, no leading slash, no trailing slash, and no .md: admin/templates/extending-templates.
  • A route is one or more segments joined by /. Each segment matches [A-Za-z0-9._-]+. Nothing else is allowed (no @, %, :, (, ?, #, spaces, empty segments, . or .. segments).
  • Routes are derived from docs/manifest.json the way the sites do today: strip a leading ./, then strip README.md, index.md, .md in that order as plain text, trim slashes. The empty result is the docs root.

Wildcards

  • A source may end in /*: ai-coder/ai-bridge/*. It matches the prefix itself and every route beneath it.
  • A destination may end in /* only when the source does. The part the source's * matched (possibly empty) replaces the destination's *; an empty match means the destination prefix itself (ai-coder/ai-gateway/* with an empty match is ai-coder/ai-gateway).
  • A wildcard source with a non-wildcard destination sends everything under the prefix to that one page.
  • No other pattern syntax exists. Consumers translate * into their own matcher. For Next.js that is :path([A-Za-z0-9._-]+)*, never (.*), .+, or a bare :name*.

Destinations

  • / is the docs root of the same version (/docs, /docs/@main, /beta-docs/v2.37, and so on). Pages with no suitable home redirect to /.
  • An internal destination always stays in the same version as the request.
  • A non-wildcard internal destination may end in one #fragment, where the fragment matches [A-Za-z0-9._-]+: user-guides/workspace-access#web-ides. The route part must still be a live route. A wildcard destination and / never carry a fragment.
  • An external destination is an https:// URL whose host and path start with an allowed prefix: https://github.com/coder/ or https://coder.com/. It contains no : after the scheme and no parameter. A * is not allowed in an external destination.

Order and precedence

  • Rules apply in file order; the first match wins.
  • A page always wins over a redirect: a rule only fires for a request that is not a live page of that version. The checker rejects any rule whose source matches a live route, so consumers that check redirects before pages (Next.js static redirects) behave the same as those that check on a miss.
  • Matching ignores one trailing slash on the request.
  • Consumers follow at most 3 chained hops and refuse loops. The checker rejects chains so a valid file never needs this.

Legacy entries

  • During migration, consumers also accept a source or destination that starts with /docs/ (or equals /docs) and treat it as the route after /docs/ (or / for /docs). A legacy :name* or :name(.*) trailing parameter is treated as /*. The coder/coder checker accepts only the new form.
  • A missing file and an empty array both mean no rules. A file that is not a JSON array is an error.

CI check (coder/coder scripts/docsredirectscheck)

Structural checks as today, adapted to the new form, plus a blocking removed-route check:

  1. Inventory. The set of routes that must keep working is the union of:
    • the base branch's docs/manifest.json routes,
    • every route in the live production page list for the PR's target branch, read from https://coder.com/beta-docs/<segment>/llms.txt where the segment is @main for main and vX.Y for release/X.Y, keeping only links under that segment,
    • every source in the base branch's docs/redirects.json (exact sources as-is; wildcard sources contribute the prefix).
  2. Resolution. Each inventory route must be a live route in the head manifest, or be resolved by the head rules (with wildcard substitution) to a live head route, /, or an allowed external URL.
  3. Failure message. Name the route, the file it came from on the base branch when known, and a ready-to-paste rule, for example {"source": "path/to/page", "destination": "path/to/another-page"}, pointing at / when no candidate is obvious.
  4. Live list failures. A network error, non-200, or a list with no routes is an infrastructure failure (exit 2) in CI, not a pass. Locally, -offline skips the live list and says so.
  5. Known engine difference. beta-docs currently serves dotted segments with hyphens (esr-2.24-2.29-upgrade is served as esr-2-24-2-29-upgrade). Until docs-engine fixes it, a live route that equals a head route with . replaced by - in each segment counts as present.

Consumers

  • coder.com classic (scripts/generate-docs-redirects.ts): reads main (scoped to /docs/@main/...) and the mainline release branch (unversioned /docs/...) as today, in the new format, and emits Next.js redirects. Version coverage beyond those two is out of scope.
  • docs-engine beta: each version's publish reads docs/redirects.json from the commit it builds, validates it, and stores the compiled rules with that version's archive. The router applies a version's own rules on a miss inside that version. Versions published before this change keep today's behavior.

🤖 Built with AI assistance.

@linear-code

linear-code Bot commented Oct 14, 2026 •

Copy link
Copy Markdown

DOCS-1290

DOCS-1296

@Katarinya Katarinya left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review

Verdict: OK to merge once findings 1 and 2 are decided. The other findings are small follow-ups.

Findings

# Finding Severity Location
1 A 404 on an unpublished version blocks CI. A new release/X.Y branch with no published beta-docs version makes every PR into that branch fail with exit 2, and the author can't fix it. The test at main_test.go:690 requires this behavior. Treat a 404 as "not published, skip with a note"; the base-branch comparison would still run. Medium inventory.go:137-158
2 Every PR's lint now depends on coder.com being up. make lint runs for nearly every PR into main, including ones that don't touch docs, so a coder.com outage blocks them all. Confirm this is accepted, or fetch the live list only when docs change. Medium (policy) main.go:236-260
3 Git errors are silently treated as "no base redirects file". Any git show failure drops the base redirect sources without a note, so a PR that deletes an existing redirect could pass. Tell "file not found" apart from other errors, or at least print a note. Low to medium main.go:310
4 The hop limit only applies when a chain ends on a page. z→a→b→c→end (4 hops) fails, but z→a→b→c→/ passes (confirmed with a throwaway test). Impact is low because chains are rejected elsewhere. Apply the limit to every destination type and add a test case. Low inventory.go:236
5 The &^1 assertion accepts exit 0 or 1. It only checks that the code isn't 2, and prGit(manifestBase[:0]) obscures that the run actually exits 1. Use require.NotEqual(t, 2, code), or give it a base with nothing removed and assert 0. Low (test clarity) main_test.go:1000

Security

No exploitable issues. Two optional hardening fixes:

  • https://github.com/coder/../other-org passes the external destination check. Parse the URL and reject .. segments. (rules.go:225-242)
  • One message prints a route from the head manifest without quoting it. Use %q like the rest of the file. (rules.go:475)

Go practices (optional)

  • segment is both a package-level regexp and a parameter name in three places. Rename the regexp to segmentRe. (rules.go:134; inventory.go:95, 137; main.go:241)
  • The context isn't passed down, and the retry wait uses time.Sleep, so cancelling can't stop it. (main.go:251, inventory.go:141)

Before merging

  • Confirm coder/coder.com#1153 is deployed, not just merged.
  • Decide how a 404 on an unpublished version should behave (finding 1).
  • Confirm the team accepts the dependency on coder.com (finding 2).

Note

Generated by Coder Agents on behalf of @Katarinya.

Rewrite docs/redirects.json in the relative route format (routes below
/docs, trailing /* wildcards, / for the docs root) with the rules that
cover pages retired from main, some of them non-permanent.

docsredirectscheck now enforces that format, rejects the old absolute
/docs/... form with the converted rule, and fails when a route from the
base manifest, the live page list for the target branch, or a base
redirect source no longer resolves. -offline skips the live list.

Generated with Coder Agents.
…check

Skip the live page list when it answers 404, so a new release branch
without published docs does not fail every pull request into it. Skip it
too when docs/manifest.json and docs/redirects.json match the base
branch, so a coder.com outage only blocks changes to those files.

Tell a missing base redirects file apart from other git failures, apply
the hop limit to every destination type, reject "\" and dot segments in
external destinations, quote the hidden route, rename the segment regexp,
and pass the context through so the retry wait can be cancelled.
@nickvigilante
nickvigilante force-pushed the vigilante/docs-main-redirects branch from 2c200f7 to f8ba5b9 Compare October 21, 2026 18:48
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

@Katarinya, thanks for the review.
All findings are addressed in f8ba5b9, and the branch is rebased onto main.

Pre-merge checklist

  • coder/coder.com#1153 is deployed.
    It merged on 2026-10-15 with green checks, and it reads the legacy /docs/... form too, so deploying it before this PR merges is safe.
    The deployment itself is not confirmed yet.
    I'll check it with the Vercel CLI and follow up here.
  • A 404 for an unpublished version (finding 1).
    A 404 is now "not published": the live page list is skipped with a note and is not retried, and the base-branch comparison still runs.
    Verified against the real site with -branch release/9.99.
  • The dependency on coder.com (finding 2).
    I took your second option.
    On a pull request, the live page list is fetched only when docs/manifest.json or docs/redirects.json differs from the base branch, because otherwise the change cannot affect the result.
    So a coder.com outage only blocks PRs that change those two files.
    The comparison ignores CRLF versus LF.

Other findings

# Change
3 Show wraps fs.ErrNotExist for a missing file (detected with git ls-tree, not git's localized error text). A missing base redirects file still means "no rules". Any other error prints a note and still reads the live list.
4 Every redirect counts as a hop, whatever its destination. Tests cover four-hop chains ending on / and on an external URL.
5 The &^1 assertion is gone. The test uses a base with nothing removed and asserts exit 0.
Security External destinations reject . and .. path segments, also percent-encoded, and \. The hidden-route message uses %q.
Go The regexp is segmentRe. main passes a signal-aware context down, and the retry wait returns when it is done.

Rebase

The rebase conflicted in docs/redirects.json.
I added main's one rule at the top, in the relative form: admin/templates/extending-templates/dynamic-parameters → admin/templates/extending-templates/parameters.
Against origin/main and the live @main list, the check reports 302 rules OK and 485 routes still resolve.
CI is green on Linux, macOS, and Windows.

Note

Generated by Coder Agents on behalf of @nickvigilante.

Main rewrote the doc-check skill; keep main's version and carry the
relative redirect format into its Repository facts entry.

Assisted-by: AI
The live list URL is under /beta-docs. When the docs move to /docs and
that URL redirects there, the list's links use /docs, the check would
find no pages, and every docs PR would fail with exit status 2. Accept
links under either base, preferring /beta-docs.

Also drop a stale "advisory check" reference in a comment.

Assisted-by: AI
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

@nickvigilante, the doc-check job on 33ef72af59 failed after a 2400s timeout while it waited for the review chat to finish. It reported no findings. The chat was still running and posted no review, so this is the review-outlasts-timeout case, not a docs issue. Re-run the job if you want a doc-check verdict on this head.

Generated by Coder Agents on behalf of @nickvigilante.

nickvigilante added a commit that referenced this pull request Nov 4, 2026
…idebar (#31645)

> [!NOTE]
> Generated by Coder Agents. The branch and this description were
written by an AI agent and need human review.

## 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` (#30684) and `agents/acp-subagents.md` (#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.
- **#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 #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

| Old | New |
| --- | --- |
| `docs/ai-coder/agents/**` (25 files) | `docs/coder-agents/**` |
| `docs/ai-coder/ai-governance.md` | `docs/ai-governance/index.md` |
| `docs/ai-coder/agent-firewall/**` (9 files) |
`docs/ai-governance/agent-firewall/**` |
| `docs/ai-coder/ai-gateway/**` (26 files) |
`docs/ai-governance/ai-gateway/**` |
| `docs/ai-coder/agent-relay/**` (3 files) | `docs/agent-relay/**` |
| `docs/ai-coder/mcp-server.md` | `docs/mcp-server.md` |
| `docs/ai-coder/index.md` | deleted |
| `docs/ai-coder/best-practices.md` | deleted |
| `docs/ai-coder/ide-agents.md` | deleted |

## 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.

| Source | Destination |
| --- | --- |
| `/docs/ai-coder` | `/docs/coder-agents` (deleted hub, **please
confirm**) |
| `/docs/ai-coder/best-practices` | `/docs/coder-agents` (deleted,
**please confirm**) |
| `/docs/ai-coder/ide-agents` | `/docs/user-guides/workspace-access`
(deleted, **please confirm**) |
| `/docs/ai-coder/ai-governance` | `/docs/ai-governance` |
| `/docs/ai-coder/mcp-server` | `/docs/mcp-server` |
| `/docs/ai-coder/agents/:path*` | `/docs/coder-agents/:path*` |
| `/docs/ai-coder/agent-firewall/:path*` |
`/docs/ai-governance/agent-firewall/:path*` |
| `/docs/ai-coder/ai-gateway/:path*` |
`/docs/ai-governance/ai-gateway/:path*` |
| `/docs/ai-coder/agent-relay/:path*` | `/docs/agent-relay/:path*` |

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.
- #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.
- #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.
- #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`.

| Current (old) URL | Post-release URL | Files |
| --- | --- | --- |
| `https://coder.com/docs/ai-coder/agents` |
`https://coder.com/docs/coder-agents` |
`.claude/skills/doc-check/output.md`, `README.md` |
| `https://coder.com/docs/ai-coder/agents/architecture` |
`https://coder.com/docs/coder-agents/architecture` |
`coderd/x/chatd/chattool/execute_test.go`,
`codersdk/toolsdk/workspacetools/execute.go` |
| `https://coder.com/docs/ai-coder/ai-gateway` |
`https://coder.com/docs/ai-governance/ai-gateway` | `README.md`,
`coderd/templatebuilder/modules/claude-code/module.json`,
`coderd/templatebuilder/modules/codex/module.json` |
| `https://coder.com/docs/ai-coder/mcp-server` |
`https://coder.com/docs/mcp-server` | `server.json` |
| `https://coder.com/docs/admin/templates` |
`https://coder.com/docs/templates` | `README.md` |
|
`https://coder.com/docs/admin/templates/extending-templates/docker-in-workspaces`
|
`https://coder.com/docs/templates/extending-templates/docker-in-workspaces`
| `examples/templates/docker-devcontainer/main.tf` |
|
`https://coder.com/docs/admin/templates/extending-templates/parameters`
| `https://coder.com/docs/templates/extending-templates/parameters` |
`examples/parameters-dynamic-options/README.md`,
`examples/parameters/README.md`, `examples/parameters/main.tf`,
`examples/templates/kubernetes-envbox/README.md`,
`examples/workspace-tags/README.md` |
|
`https://coder.com/docs/admin/templates/extending-templates/prebuilt-workspaces`
|
`https://coder.com/docs/templates/extending-templates/prebuilt-workspaces`
| `coderd/prebuilds/api.go`,
`enterprise/coderd/prebuilds/metricscollector.go` (metric help text) |
|
`https://coder.com/docs/admin/templates/extending-templates/workspace-tags`
| `https://coder.com/docs/templates/extending-templates/workspace-tags`
| `examples/workspace-tags/README.md` |
| `https://coder.com/docs/admin/templates/managing-templates` |
`https://coder.com/docs/templates/managing-templates` |
`cli/templatecreate.go`, `cli/templateedit.go` (CLI help) |
|
`https://coder.com/docs/admin/templates/managing-templates/image-management`
| `https://coder.com/docs/templates/managing-templates/image-management`
| `coderd/templatebuilder/bases/docker/README.md`,
`coderd/templatebuilder/bases/kubernetes/README.md` |
| `https://coder.com/docs/admin/templates/troubleshooting` |
`https://coder.com/docs/templates/troubleshooting` |
`agent/agentscripts/agentscripts.go`,
`coderd/render/escape_internal_test.go`, `codersdk/deployment.go`
(`agentFallbackTroubleshootingURL` default) |
| `https://coder.com/docs/tutorials/template-from-scratch` |
`https://coder.com/docs/templates/template-from-scratch` |
`site/src/pages/TemplateBuilder/TemplateAlternatives.tsx` |

## 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 #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.

<details>
<summary>Implementation notes</summary>

- Rebuilt on `main` at `ccf5ec74ae` (2026-11-03) to clear conflicts with
`main`, after an earlier rebase the same day onto `1a963c628d`. The
previous rebuild was on `9839406ff7` (2026-11-02), and the first version
on `9b8d880d63` (2026-10-23).
- Rebase conflicts with #31603, which added `target="_blank"
rel="noreferrer"` to docs links: 4 `site/` files in the chore commit and
5 in the Templates commit. Each kept `main`'s version of the link with
only the docs path changed. Vitest for the 7 affected page directories
(233 tests) and the story tests for the 8 changed or affected stories
(102 tests) pass, and every `docs()` path in `site/src` resolves except
the same 13 that are unresolved on `main`.
- Rebase conflict: `docs/manifest/coder-agents.yml`. `main` added
`docs/ai-coder/agents/bring-your-own-mcp-servers.md`; it moves to
`docs/coder-agents/` with its sidebar entry, and its
`../../user-guides/` links become `../user-guides/`.
- Folded into the Templates commit: a link that `main` added to
`docs/user-guides/workspace-dotfiles.md` (#31606) now points at
`../templates/extending-templates/environment-variables.md`.
- `git range-diff` against `def074caab`, the head before both rebases,
shows only those changes.
- The move script reads every page from the clean `main` checkout and
resolves each relative link (inline, reference-style, and HTML
`src`/`href`) against the page's **old** directory. It maps the target
through the move map and recomputes the link from the page's **new**
directory. It runs once and refuses to run on a dirty `docs/` tree, so
it can't apply the path math twice. It also rewrites absolute
`coder.com/docs/...` and
`github.com/coder/coder/(blob|edit|tree)/main/docs/...` URLs, and skips
fenced code blocks and inline code.
- Before reusing the script, I ran it on the old base and diffed the
result against the old commit. The only differences were the two
hand-edited glossary entries and table padding from the formatter, so
the rebuild applies the same changes to the current `main`.
- Afterward, `grep -r ai-coder docs/` finds matches only in
`docs/redirects.json`.
- Changes from the earlier version of this branch: 2 more pages move
(`agents/projects.md`, `agents/acp-subagents.md`) and their sidebar
entries move with them. The chore commit also updates
`SessionSummaryTable.tsx` (new on `main`) and the doc-check skill's
`output.md` (its examples moved there from `SKILL.md`). The
`AICostControl.tsx` anchor question is gone, because `main` fixed it.

</details>

---------

Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com>
Co-authored-by: Nick Vigilante <nick.vigilante@coder.com>

@ianjevans ianjevans left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

Resolve conflicts with the docs IA moves on main (templates, workspaces,
coder-agents, ai-governance, and the redistributed tutorials).

- Convert the redirects main added to the relative form.
- Point existing rules at the pages' new locations.
- Drop rules whose source is now a live page: templates,
  templates/open-in-coder, templates/troubleshooting, and workspaces.
- Replace guides/* -> tutorials/* with exact rules for the old guides
  pages and a guides/* -> / fallback, and send tutorials/ai-agents/* to
  coder-agents, because tutorials and ai-coder no longer have pages.
- Update the route examples in the checker README and the content
  guidelines to routes that exist.
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

Merged main into this branch in fe829e8 to resolve conflicts with the docs IA moves (#31645, #31647, #31650).

Resolution

  • docs/redirects.json: converted the 33 rules main added to the relative form, and repointed existing rules at the pages' new homes (templates/..., workspaces/..., coder-agents/..., ai-governance/...).
  • Dropped 4 rules whose source is now a live page: templates, templates/open-in-coder, templates/troubleshooting, workspaces.
  • tutorials and ai-coder no longer have pages, so two wildcards changed:
    • guides/* → tutorials/* became exact rules for the six old guides/ pages that still have a home, plus guides/* → /.
    • tutorials/ai-agents/* → ai-coder/* became tutorials/ai-agents/* → coder-agents.
  • scripts/docsredirectscheck/main_test.go: kept this branch's live.has(...) assertion; main only removed the /docs/about line, which this branch had already dropped.
  • Updated the route examples in the checker README and the content guidelines to routes that exist.

Checks

  • go run ./scripts/docsredirectscheck -base origin/main -branch main: 339 rules OK, 525 routes still resolve (also after merging the one newer main commit, docs: add migration guide from Ona (formerly Gitpod) to Coder #31204).
  • go test ./scripts/docsredirectscheck/... and the pre-commit hook pass.
  • coder.com's generateRedirects from main with this file and the merged manifest: 339 of 339 rules kept, no dead destinations.
  • coder/coder.com#1153 looks deployed: /docs/@main/user-guides/foo~bar returns 404 while user-guides/zzz-probe returns 308, which matches the restricted [A-Za-z0-9._-] wildcard the new generator emits.
  • CI is green except the AI doc-check, which hit the same 2400s timeout as on 33ef72af59 with the chat still running and no findings. The link check failed in Checkout and was re-run; it passed.

Still to do after this merges: the release/2.38 backport.

Note

Generated by Coder Agents on behalf of @nickvigilante.

@nickvigilante
nickvigilante merged commit c95b908 into main Nov 5, 2026
31 of 33 checks passed
@nickvigilante
nickvigilante deleted the vigilante/docs-main-redirects branch November 5, 2026 19:04
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 5, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants