mirror of
https://github.com/coder/coder.git
synced 2026-11-22 03:18:31 +08:00
feea5ab959f59cd2135443ed2a0c19bf7643db8f
160
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
d1a58b9f5d |
feat: add script to check for title case (#21484)
Historically, much of the UI used title case. This PR adds a lint check
that reports title case UI text so it can be converted to sentence case,
and converts the existing text.
- `site/scripts/check-sentence-case.mjs` runs as `pnpm
lint:sentence-case` and is part of `pnpm lint`. It reads JSX text and
string/template literals from the TypeScript AST and skips literals that
are code rather than UI text (imports, types, property names, tagged
templates, values of JSX attributes that are not displayed such as
`className` or `style`, and operands of `===`/`case` comparisons). JSX
text across inline elements and conditional JSX is checked as one
phrase. `--fix` lowercases the reported words. The checker is a
heuristic: it is not meant to model every code shape, so use a
`sentence-case-expect` comment where it guesses wrong.
- Proper nouns (Coder products, role names, third-party products,
protocols, font names) live in `PROPER_NOUNS`. For other deliberate
exceptions, a `sentence-case-expect` comment on the line above
suppresses the report and fails when that line no longer needs it.
- Existing UI text is converted to sentence case, and tests that assert
on it are updated.
- Deployment option lookups (`useDeploymentOptions`) now use CLI flags
instead of display names, so they do not depend on UI wording.
## Performance
`pnpm lint:sentence-case` takes **1.6 s** and is 2% to 4.5% of `pnpm
lint`. Measured on
|
||
|
|
1baff57cb0 |
fix: resolve docs and code conflicts found in the main docs audit (#32158)
## Summary Addresses 106 of the 113 conflicts between the docs and the code that the November audit of `main` found: 102 are fixed and 4 have an interim docs fix. Every finding was re-checked against the code before it was fixed. Most fixes are docs-only. Three are small code fixes where the docs described the intended behavior and the code was wrong, each in its own commits so it can be split out. No change in this PR alters template build or agent behavior. ## Changes Fixes by area (finding counts): templates 28, install 13, integrations and monitoring 13, auth and security 12, networking 11, Coder Agents 9, AI governance 7, reference 7, workspaces 6. Code fixes. Each needs a look from the code owner. If an owner prefers not to take one, drop its commits and I will change the docs to describe the current behavior instead. | Commits | Change | Risk to check | |---------|--------|---------------| | `fix: keep built-in listener defaults in packaged coder.env`, and three follow-up commits | `coder.env` comments out `CODER_HTTP_ADDRESS=` and the three `CODER_TLS_*` lines, so an untouched package install listens on `127.0.0.1:3000` as the docs say. Only the `CODER_HTTP_ADDRESS=` line changed behavior. The TLS options default to empty, so commenting them out is for consistency. The Lima examples rewrite the commented line and fail if the line is not found. A test compares every option that the file sets against the built-in defaults. | The deb and RPM packages were not built or installed. Every released package through v2.39.0 ships the empty line, and upgrades keep an existing file (`config\|noreplace`), so the upgrade pages now say how to fix it. | | `fix(cli/clilog): accept log sinks that are all disabled`, and three follow-up commits | `--log-human=/dev/null` with no other log location no longer fails with "no loggers provided". It is the documented way to disable logging. An empty location still fails with that error when no other sink is set, as before. | Behavior change: with `/dev/null`, the server and the provisioner daemon can start with no log output. | | `fix(cli): detect CODER_PROC_PRIO_MGMT by presence`, and a comment follow-up | Log line only. With the variable set to an empty value, the agent now logs that process priority management is enabled, which is what `agentexec` already does. No detection or behavior change. | Low. | Two option descriptions in `codersdk/deployment.go` are corrected, with the CLI reference, configuration reference, and golden files regenerated: the default quiet hours schedule (the max deadline is the quiet hours window on the next day that the template's autostop requirement applies) and `--experiments` (`*` opts in to the experiments marked safe, also in `enterprise/cli/provisionerdaemonstart.go`). ### Code fixes that were reverted after review Two code fixes from the first version of this PR are reverted in the branch. The net diff has no change under `agent/` or `coderd/`. The docs now describe what the code does, and both issues stay open for the owner. - **`error` merge strategy for `coder_env` (DOCS-1669).** The fix made `merge_strategy = "error"` fail whenever a name was set twice, whatever the resource order. Existing template versions that pair an `error` entry with a later `replace` or `append` entry would start to fail every build after `terraform apply`. That is a breaking change that needs its own PR and release note. The fix and its tests are in `dff8e7c6ce` and can be cherry-picked. `environment-variables.md` now says the check runs only when the `error` resource is processed. - **Nice value before the capability drop (DOCS-1687).** The fix let `coder agent-exec` apply a negative nice value by calling `setpriority` before it drops effective capabilities. The current order is deliberate: with the fix, any local process could run the agent binary with `--coder-nice=-20` when the binary has the `CAP_SYS_NICE` file capability. `process-priority.md` now says a nice value below the agent's own is not applied, and no longer tells admins to grant `CAP_SYS_NICE`. ## Not included Seven findings are left out. - DOCS-1629: covered by #31639. - DOCS-1703 and DOCS-1724: covered by #31980. - DOCS-1584, DOCS-1683, DOCS-1685, DOCS-1686: each needs an owner decision, and no neutral docs wording exists until that decision is made. The validation comment on each issue names the decision. Four fixes are interim, so their issues stay open: - DOCS-1600: the AI Gateway pages now agree that the legacy metric names are deprecated and "will be removed in a future release". The code still emits them, and its TODO names v2.37, which has shipped. The owner still needs to set the removal release. - DOCS-1689: the page now says **New Template** opens the builder only for users with the Owner role, because the page gates on read access to the deployment config. Whether Template Admins should get the builder is still open. - DOCS-1669 and DOCS-1687: docs-only for now. Refer to [Code fixes that were reverted after review](#code-fixes-that-were-reverted-after-review). ## Review notes - Claims that describe product intent and need an owner's yes: the Premium qualifier on per-organization workspace sharing (the API route has no license check, the dashboard needs multiple organizations), `organization` port sharing in OSS, the telemetry field list, and the `1-5` cron range in the prebuilds schedule example. - Not run end to end: the PostgreSQL TLS procedure on a cluster, the OpenShift and air-gapped examples, the BSD `date` and `tar` forms on macOS, the Windows command on the multiple Kubernetes clusters page, and the keep-alive script in `docs/reference/index.md` (only its comparison logic was run, against sample values). Nothing was checked on a live deployment. - Likely merge conflicts with open PRs: #31990 (`mcp-server.md`, `feature-stages.md`, `docker-in-workspaces.md`), #31982 (`workspace-management.md`), #31980 (`health-check.md`), #31977 (`manage-provisioner-jobs.md`), #31869 (`airgap.md`), #30486 (`add-envbuilder.md`), and #31326 and #31531 (`codersdk/deployment.go` and generated files). ## Testing - `make pre-commit` (gen, fmt, lint, slim build), before the PR opened and again after the review changes. - `go test` for `./cli/clilog/...`, `./codersdk/`, `./cli/` (`TestServer`, `TestAgent`, and golden files), and `./enterprise/cli/` (provisioner, server, and help golden files). `./agent/agentexec/...` and `./coderd/provisionerdserver/...` pass after the reverts. Linux only. CI covers macOS and Windows. - The `coder.env` test fails against the file on `main` and passes against the new one. It reads the file with `godotenv`, which accepts CRLF line endings. - An empty `CODER_HTTP_ADDRESS=` was confirmed end to end with a full build of the server (output below). - The new `sed` and `grep` lines in the Lima examples were run with GNU tools against the old and the new form of `coder.env`. The Lima VMs were not started. - `--log-human=/dev/null` and `CODER_LOGGING_HUMAN=` were confirmed with the same build (output below). - `coder agent-exec --coder-nice=-5 -- echo` from a full build, as a non-root user: `coder-agent: failed to adjust niceness to -5 ...: permission denied` on stderr, the command output on stdout, exit code 0. - `postgres-ssl.md` rendered with the GitHub Markdown API: two ordered lists with three and five items, where `main` has six lists. - markdownlint, the table formatter, `make lint/emdash`, `make lint/docs-html`, `make lint/docs-manifest`, `make lint/docs-redirects`, `make lint/style-claims`, and Vale on the changed lines. - A doc-check self-review of the docs diff by four independent reviewers. It found six problems, which are fixed. The accuracy and coverage lenses ran on every area. The language and structure lenses ran in full on only part of the diff. <details> <summary>Test and terminal output for the code fixes (Linux)</summary> ```console $ go test ./codersdk/ -run TestPackagedCoderEnvKeepsDefaults -count=1 -v --- PASS: TestPackagedCoderEnvKeepsDefaults (0.00s) ok github.com/coder/coder/v2/codersdk 0.071s $ go test ./cli/clilog/ -run TestBuilder -count=1 -v --- PASS: TestBuilder (0.00s) --- PASS: TestBuilder/NoSinks (0.00s) --- PASS: TestBuilder/NoSinks/JSONDevNull (0.00s) --- PASS: TestBuilder/NoSinks/StackdriverDevNull (0.00s) --- PASS: TestBuilder/NoSinks/NoConfiguration (0.00s) --- PASS: TestBuilder/NoSinks/HumanDevNull (0.00s) --- PASS: TestBuilder/WithHuman (0.00s) --- PASS: TestBuilder/WithFilter (0.00s) --- PASS: TestBuilder/WithJSON (0.00s) --- PASS: TestBuilder/Verbose (0.00s) --- PASS: TestBuilder/FromDeploymentValues (0.01s) --- PASS: TestBuilder/FromDeploymentValues/Defaults (0.00s) --- PASS: TestBuilder/FromDeploymentValues/EmptyHumanEnv (0.00s) --- PASS: TestBuilder/FromDeploymentValues/Override (0.00s) ok github.com/coder/coder/v2/cli/clilog 0.171s $ TMPDIR=$HOME/.cache/agentexec-tmp go test ./agent/agentexec/... ./coderd/provisionerdserver/... -count=1 ok github.com/coder/coder/v2/agent/agentexec 4.236s ok github.com/coder/coder/v2/coderd/provisionerdserver 2.404s # Full build of the server (go build ./cmd/coder). An empty value stops it before it connects to the database. $ CODER_HTTP_ADDRESS= coder server --postgres-url 'postgres://127.0.0.1:1/x?sslmode=disable' Encountered an error running "coder server", see "coder server --help" for more information error: TLS is disabled. Enable with --tls-enable or specify a HTTP address # With the variable unset, the server passes that check and goes on to the database. $ coder server --postgres-url 'postgres://127.0.0.1:1/x?sslmode=disable' 2026-11-13 02:19:41.901 [warn] ping postgres: retrying error="dial tcp 127.0.0.1:1: connect: connection refused" try=11 Encountered an error running "coder server", see "coder server --help" for more information error: connect to postgres: connect to postgres: unable to connect after 11 tries; last error: dial tcp 127.0.0.1:1: connect: connection refused # An empty log location with no other sink still stops the server. $ CODER_LOGGING_HUMAN= coder server --postgres-url 'postgres://127.0.0.1:1/x?sslmode=disable' Encountered an error running "coder server", see "coder server --help" for more information error: make logger: no loggers provided, use /dev/null to disable logging # /dev/null passes the logger check. The server prints no log lines and goes on to the database. $ coder server --log-human=/dev/null --postgres-url 'postgres://127.0.0.1:1/x?sslmode=disable' Encountered an error running "coder server", see "coder server --help" for more information error: connect to postgres: connect to postgres: unable to connect after 11 tries; last error: dial tcp 127.0.0.1:1: connect: connection refused ``` </details> ## Linear Fixes DOCS-1583, DOCS-1585, DOCS-1586, DOCS-1587, DOCS-1588, DOCS-1589, DOCS-1590, DOCS-1591, DOCS-1592, DOCS-1593, DOCS-1594, DOCS-1595, DOCS-1596, DOCS-1597, DOCS-1598, DOCS-1599, DOCS-1601, DOCS-1602, DOCS-1603, DOCS-1604, DOCS-1605, DOCS-1606, DOCS-1607, DOCS-1608, DOCS-1609, DOCS-1614, DOCS-1618, DOCS-1619, DOCS-1620, DOCS-1624, DOCS-1635, DOCS-1639, DOCS-1644, DOCS-1651, DOCS-1652, DOCS-1653, DOCS-1654, DOCS-1655, DOCS-1656, DOCS-1657, DOCS-1658, DOCS-1659, DOCS-1660, DOCS-1661, DOCS-1662, DOCS-1663, DOCS-1664, DOCS-1665, DOCS-1666, DOCS-1667, DOCS-1668, DOCS-1670, DOCS-1671, DOCS-1672, DOCS-1673, DOCS-1674, DOCS-1675, DOCS-1676, DOCS-1677, DOCS-1678, DOCS-1679, DOCS-1680, DOCS-1681, DOCS-1682, DOCS-1684, DOCS-1688, DOCS-1690, DOCS-1691, DOCS-1692, DOCS-1693, DOCS-1694, DOCS-1695, DOCS-1696, DOCS-1697, DOCS-1698, DOCS-1699, DOCS-1700, DOCS-1701, DOCS-1702, DOCS-1704, DOCS-1705, DOCS-1706, DOCS-1707, DOCS-1708, DOCS-1709, DOCS-1710, DOCS-1711, DOCS-1712, DOCS-1713, DOCS-1714, DOCS-1715, DOCS-1716, DOCS-1717, DOCS-1718, DOCS-1719, DOCS-1720, DOCS-1721, DOCS-1722, DOCS-1723, DOCS-1725, DOCS-1726, DOCS-1727 Part of DOCS-1600, DOCS-1689, DOCS-1669, DOCS-1687 <details> <summary>Decision log</summary> ### Scope - One PR for all findings, as agreed with the reviewer. The code fixes are separate commits so an owner can ask for any of them to move to its own PR. Nothing in the PR is a breaking change, so the title has no `!`. - A finding was skipped only when an open PR already covers it, or when every available wording would assert an undecided product behavior. - Each validation comment on the Linear issues records the evidence, the corrections to the original finding, and what was not verified. ### Docs or code - The default was a docs-only fix that describes what the code does. - A code fix was chosen when the docs describe a behavior the code plainly intended and the code change is small and testable: the packaged env file, the log sink check, and the log line for the environment variable presence check. - The `error` merge strategy and the nice value ordering started as code fixes and went back to docs-only after review. The first breaks existing template versions. The second weakens a deliberate security ordering. - The SCIM `userName` finding (DOCS-1609) took the docs path. The handler is unchanged. ### Wording choices worth a second look - `feature-stages.md` says `--experiments=*` enables only the experiments marked safe, and points to the "Get safe experiments" API. It does not list the other experiments, because the list would drift and those experiments are hidden on purpose. The `--experiments` flag help now says the same. - `agent-metadata.md` replaces the writes-per-second formula with a description of the batcher (each server replica writes one statement every 5 seconds, or sooner at 500 entries). - `extending-templates/index.md` no longer calls `startup_script` deprecated. The provider documents it as an alias for a `coder_script`. - `postgres-ssl.md` separates client verification from server verification, so the server verification steps work alone. - `rpm.md`, `upgrade.md`, and the 2.29 to 2.34 ESR upgrade page explain the empty `CODER_HTTP_ADDRESS=` line that older packages shipped, because upgrades keep the old file. The behavior changed in v2.34.0 with the serpent upgrade in #24926. - The keep-alive script in `docs/reference/index.md` reads the current deadline and skips the request when it is already later. The comparison is on text, so it applies only when the API returns a UTC timestamp, which needs the database to use the UTC time zone. Otherwise the script sets the deadline on every pass, as it did before, and the page says so. - `external-auth.md` anchors the new GitHub Enterprise regex example. The older unanchored examples on that page and on `git-providers.md` are not changed here. ### Self-review findings that were rejected - "The builder opens for Template Admins": the Templates page needs a successful deployment config read, which the Template Admin role does not have. - "Organization Admins can set AI model prices": the price write authorizes against a site-level object, which organization-scoped grants do not match. - "The provisioner chart sets no default resources": `helm/libcoder/templates/_coder.yaml` applies 2000m and 4096Mi when `coder.resources` is empty. ### Automated review, round 1 The `coder-agents-review` app left 45 findings on `8853332`. Fixed: the two reverts above, the anchored regex, the `coder.env` follow-ups (Lima examples, upgrade notes, a comment in the file, and a test that covers every option in the file), the clilog change, the two option descriptions, and the docs findings (CORS behavior, token lifetime example, keep-alive script, agent metadata, refresh token errors, `switch` form type, `dbcrypt` skip list, and a stray line in a YAML example). Declined, with the reason on each thread: - Refactoring the `agentexec` logging and renaming its log field: not related to a docs conflict. - Rewording the "process priority management not enabled (linux-only)" log message: the docs quote the message, and the wording predates this PR. - Problems in code and docs that this PR does not change (the `Capabilities` subtest, the Helm values comment, the AWS provider path in `airgap.md`, and others in the review's out-of-scope list). ### Automated review, round 2 The app left 14 new findings on `04925bd`, and accepted the three declined threads on `cli/agent.go`. All 14 are fixed. The main one: the round 1 change that removed the "no loggers provided" error went too far, because an empty log location would then start a server with no logs. The error is back for every case except `/dev/null`. Reported by the app as out of scope and not changed: the swagger annotation for `GET /api/v2/experiments/available` declares an array, but the handler returns an object with a `safe` array. Three Storybook fixtures keep the old `--experiments` description. ### Automated review, round 3 The app confirmed that all round 2 findings are fixed, and left 10 small findings on `f55cb6d` (8 P4, 2 Nit). All are fixed: the TLS condition and the release range in the `coder.env` notes, one place for the `/dev/null` rule in `clilog`, two test cases, a clearer test failure, and the CPU example in `agent-metadata.md`. ### Automated review, rounds 4 and 5 Round 4 left one P4 on `8fffb38` (name the `--trace` option in the logging note), which is fixed. Round 5 on `2ce754e` reports no new findings and says every earlier finding is fixed or closed. The app did not post an approval: it leaves its out-of-scope items and the code fixes to a human reviewer. Two threads on `cli/agent.go` stay open on purpose for the code owner. ### Doc-check review The doc-check workflow left 12 comments on `2ce754e` (10 blocking, 2 suggestions). All are fixed in `c888885`: "refer to" or "visit" in place of "see" for cross-references on the lines this PR added, the **New template** label as the dashboard shows it, one instruction per step in the server verification procedure of `postgres-ssl.md`, and two wording changes in `process-priority.md`. The `CAP_SYS_NICE` sentence keeps a short reason, which differs from the suggested text. The `coder-agents-review` app then reviewed that commit (rounds 6 and 7). Round 6 left two P4 findings, fixed in `30b2c79`: the `failed to adjust niceness` message is described once, in the troubleshooting entry, with where it appears, and the client verification steps in `postgres-ssl.md` render as one numbered list. Round 7 reports no new findings. `2a6035c` then softens one sentence from that fix, because the agent logs the stderr of devcontainer CLI commands. The app was not run again on that commit. ### Adjacent gaps found and not fixed here - `add-envbuilder.md` has the same `zip` command that `template-from-scratch.md` had. - `template-from-scratch.md` leaves the reader in `build/` after `cd $_`, before a step that runs from `template-tour`. </details> --- _Generated by Coder Agents on behalf of @nickvigilante._ --------- Co-authored-by: Ben Potter <me@bpmct.net> |
||
|
|
1126533c31 |
feat: export workspace last used time to Prometheus (#31346)
Add an opt-in coderd_workspace_last_used_timestamp_seconds gauge that reports workspaces.last_used_at, the value the dormancy threshold measures inactivity from. To enable it, set --prometheus-collect-workspace-stats or CODER_PROMETHEUS_COLLECT_WORKSPACE_STATS. A separate WorkspaceStats collector refreshes the gauge once a minute in the background from a new GetWorkspaceLastUsedForMetrics query. Each series has a workspace_id label, so a workspace that reuses a deleted workspace's name starts a new series. Workspaces owned by deleted users are excluded. Closes CLIENT-1065 |
||
|
|
3728e7a4e1 |
perf: use the build parameter index in GetTemplateParameterInsights (#31765)
Speeds up `GetTemplateParameterInsights`, which the insights collector runs every 5 minutes on every replica. The `@>` array join could only hash on `name`, so every run scanned all of `workspace_build_parameters`. Unnesting the build IDs and joining on `(workspace_build_id, name)` lets the existing unique index serve it, and the results don't change since each build ID shows up at most once per group. On 8.4M synthetic build parameters the collector's 5 minute window went from 5,193 ms to about 31 ms. `TestGetTemplateParameterInsights` is new and passes on both the old and new SQL. This also fixes the Prometheus docs example, which summed per-replica copies of the same metric. I split the `workspace_app_stats` index into #31766 so this one has no migration and can be backported to 2.34 through 2.39 (2.34 to 2.38 without the docs hunk). The pre-push hook skipped tests on this push because of a stale `origin/main` in my checkout. An earlier full run only failed in `agent/` and `site/`. Part of [CORE-439](https://linear.app/codercom/issue/CORE-439). |
||
|
|
155861f04e |
docs: replace ensure, should, and since per the Vale spike review (#31879)
Applies the Vale findings spike review's `ensure`, `should`, and `since` decisions, following `word-choice.md#choose-words-that-have-one-meaning`. ## `ensure`, `ensures`, `ensuring`: every row marked valid - 148 lines in 70 files. - Most became `make sure`, `makes sure`, or `making sure`. - When the subject isn't a person, I used a verb that reads better, such as `guarantees`, `keeps`, `prevents`, `maintains`, or `provides`. - `admin/monitoring/health-check.md:227`: "Make sure that" is now "Make sure", so the step stays within `Coder.StepLength`. - Left as-is: `admin/setup/configuration-reference.md:1339`, which is generated from `codersdk`. ## `should` and `since`: only rows with a verdict or a note - `.style/README.md`: "what should be routed elsewhere" is now "what to route elsewhere". - `.style/content-guidelines.md`: - "Avoid mixing those modes within a single page." - "Every page must be accurate" - "Check docs claims against the actual implementation" - "must include the documentation" - "Support owns the content they produce." - "because they don't change" - `.style/styles/Coder/README.md`: "must link to the matching section". - `admin/external-auth.md`: - "The redirect URI for Gitea is ..." - "Use custom authentication and token URLs ...", which is now active voice. - `envbuilder-releases-known-issues.md`: "so it's experimental and prone to breaking changes". Rows marked unsure with no note were left alone: `content-guidelines.md` lines 49, 330, and 405, and `envbuilder/index.md:24`. The changed files have no new findings from other rules. --- AI-generated by Superblink on behalf of @nickvigilante. --------- Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com> |
||
|
|
d91aa1bebd |
docs: replace may with can or might per the Vale spike review (#31878)
Replaces `may` with `can` (ability or permission) or `might` (possibility), following `word-choice.md#choose-words-that-have-one-meaning`. The Vale findings spike review marked every `may` row valid. - 247 lines in 110 files: 75 became `can` and 162 became `might`. The rest are small rewordings, such as "may wish" becoming "might want". - Applied the reviewer notes: - `.style/content-guidelines.md`: "docs may be written ahead" is now "you can write docs ahead", which also drops the passive voice. - `admin/external-auth.md`: now "You can grant access to a subset of repositories.", so the sentence doesn't end on a preposition. - Also fixed a typo in `gcp-to-aws.md`: "may needed" is now "might need". ## Left as-is - **`admin/setup/configuration-reference.md` (7 lines):** this page is generated from `codersdk` deployment options (`<!-- DO NOT EDIT | GENERATED CONTENT -->`), so the fix belongs in the Go option descriptions, followed by `make gen`. - **Text that quotes the product:** - `admin/monitoring/health-check.md:196` matches the derphealth message. - The heading at `templates/troubleshooting.md:45`, the first "may" on line 47, and the link on line 67 match the web terminal's "your workspace may be incomplete" warning and its anchor. - `admin/integrations/oauth2-provider/troubleshooting.md:269` quotes a server error. The changed files have no new findings from other rules. --- AI-generated by Superblink on behalf of @nickvigilante. --------- Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com> |
||
|
|
a988af518c |
docs: rename the user-guides folder to workspaces (#31650)
> [!NOTE]
> Generated by Coder Agents. The branch and this description were
written by an AI agent and need human review.
## Summary
Fourth stacked PR for the docs IA overhaul. PR C renamed the User guides
sidebar section to **Workspaces**. This PR renames its folder to match,
so the folder tree and the sidebar agree (DOCS-1154). The section's
title, position, and contents don't change.
- `docs/user-guides/**` moves to `docs/workspaces/**` with `git mv`: 33
files. That includes pages that are not in the sidebar and the three
pages PR C moved in (`persistent-shared-workspaces.md`,
`cloning-git-repositories.md`, `speed-up-templates.md`).
- `docs/manifest/user-guides.yml` and `docs/manifest/user-guides/` (4
files) move to `docs/manifest/workspaces.yml` and
`docs/manifest/workspaces/`, and `index.yml` lists `workspaces.yml` in
the same position.
- Every relative link and image path is fixed, in moved pages and in
pages that link to them. This was done in one scripted pass from a clean
tree. `docs/images/` stays where it is, so images under
`docs/images/user-guides/` keep their names; only the relative paths
that point at them change.
- Commit 2, `chore: point in-product docs links at the new docs paths`,
updates docs URLs outside `docs/`, then regenerates the files built from
them with `make gen`. You can drop that commit; the redirects cover the
old URLs.
- Updated sources: `site/` `docs()` links and hardcoded docs URLs,
`cli/sharing.go` help text, `README.md`, `examples/templates/` READMEs
and `docker/main.tf`, templatebuilder base READMEs, and the doc-check
skill's audience persona.
- Regenerated files: the `coder sharing add/remove` CLI golden files,
`docs/reference/cli/sharing/{add,remove}.md`, and
`examples/examples.gen.json`.
- Commit 3, `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:
- In hand-written pages, the docs commit's rewrite left 4 absolute
`https://coder.com/docs/workspaces/...` URLs. They are now relative
links, anchors kept: `admin/networking/wildcard-access-url.md`,
`install/operate/upgrade/esr-2.24-2.29-upgrade.md` (2 links), and
`workspaces/workspace-access/jetbrains/gateway.md`.
- Every hardcoded, unversioned `https://coder.com/docs/workspaces/...`
URL that commit 2 introduced outside `docs/` goes back to
`https://coder.com/docs/user-guides/...`. That covers 32 URLs in
`README.md`, `cli/sharing.go`, the examples and templatebuilder READMEs,
`examples/templates/docker/main.tf`, the `UserDropdownContent.tsx`
constant and its story assertion, and a JSDoc link in
`site/src/api/queries/workspaces.ts`. `make gen` then regenerated the
CLI golden files, `docs/reference/cli/sharing/{add,remove}.md`, and
`examples/examples.gen.json`. See "Post-release follow-up".
- The `site/` `docs()` changes stay, because those URLs are versioned
(`/docs/@vX.Y.Z/...`) and resolve once the release ships.
Stack: `docs/ia-ai-sections` (#31645, with Templates squash-merged in
#31646) → `docs/ia-tutorials-nav` (#31647) → **this PR**.
Refs: Linear DOCS-1154, DOCS-1179.
## Move map
| Old | New |
| --- | --- |
| `docs/user-guides/**` (33 files) | `docs/workspaces/**` |
| `docs/manifest/user-guides.yml` | `docs/manifest/workspaces.yml` |
| `docs/manifest/user-guides/**` (4 files) |
`docs/manifest/workspaces/**` |
## Redirects added
| Source | Destination |
| --- | --- |
| `/docs/user-guides` | `/docs/workspaces` |
| `/docs/user-guides/:path*` | `/docs/workspaces/:path*` |
Updated existing rules so none of them chain through the new wildcard:
| Source | Old destination | New destination |
| --- | --- | --- |
| `/docs/ai-coder/ide-agents` | `/docs/user-guides/workspace-access` |
`/docs/workspaces/workspace-access` |
| `/docs/tutorials/best-practices/speed-up-templates` |
`/docs/user-guides/speed-up-templates` |
`/docs/workspaces/speed-up-templates` |
| `/docs/tutorials/cloning-git-repositories` |
`/docs/user-guides/cloning-git-repositories` |
`/docs/workspaces/cloning-git-repositories` |
| `/docs/tutorials/persistent-shared-workspaces` |
`/docs/user-guides/persistent-shared-workspaces` |
`/docs/workspaces/persistent-shared-workspaces` |
**coder.com and router static redirects:** a chain simulation of
coder.com's and the router's static rules together with this branch's
`docs/redirects.json` finds one problem from this PR. The static
`/docs/workspaces` → `/docs/user-guides/workspace-management` rule in
both repos would hide the new `docs/workspaces/index.md` behind a
redirect to `/docs/workspaces/workspace-management`.
coder/coder.com#1201 and coder/docs-engine#304 remove it, together with
the Templates loops from #31645, once a release with this layout is the
docs mainline. If this PR ships in a later release than #31645, drop the
`/docs/workspaces` part of those PRs until then. The other static
`/docs/user-guides/...` destinations there still work; each now takes
two redirects.
## Deviations from the proposal
- **Not in Proposal 1.** The proposal only renamed the sidebar title.
This folder rename was requested afterward so the folder-driven renderer
shows the same name.
- **Generated files belong to commit 2.** Commit 1 doesn't edit
generated docs. They change only through their sources and `make gen`.
- **Left unchanged on purpose:**
- `docs/images/user-guides/` keeps its name, as requested.
- `.github/workflows/test-docs-preview-mapper.sh` uses
`docs/user-guides/...` as synthetic fixture paths.
- `docs/templates/extending-templates/jetbrains-airgapped.md` has a
"file a GitHub issue" link whose URL-encoded body names
`coder.com/docs/user-guides/workspace-access/jetbrains/jetbrains-airgapped`.
That URL was already wrong before this PR (the page lives under
`templates/`), and it only pre-fills an issue body, so I left it.
- Database migrations and notification golden files: none of them
contain `user-guides` links.
## Open questions for Nick
1. Should `docs/images/user-guides/` be renamed to
`docs/images/workspaces/` in a follow-up, or stay as is?
2. Frontend review nits on existing code that this PR only touched; I
didn't change them:
- `UserDropdownContent.tsx` defines `CODER_DESKTOP_DOCS_URL` as a
hardcoded `https://coder.com/docs/...` URL instead of
`docs("/workspaces/desktop")`, which `SSHButton.tsx` uses for the same
page.
- The `UserDropdown` and `SecretsPageView` stories' `play` functions
only assert link attributes.
## 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. Anchors are unchanged. Rerun
`make gen` afterward to update the CLI golden files,
`docs/reference/cli/sharing/{add,remove}.md`, and
`examples/examples.gen.json`.
| Current (old) URL | Post-release URL | Files |
| --- | --- | --- |
| `https://coder.com/docs/user-guides/desktop` |
`https://coder.com/docs/workspaces/desktop` |
`site/src/modules/dashboard/Navbar/UserDropdown/UserDropdownContent.tsx`,
`UserDropdown.stories.tsx` |
| `https://coder.com/docs/user-guides/devcontainers` |
`https://coder.com/docs/workspaces/devcontainers` | `README.md` |
| `https://coder.com/docs/user-guides/shared-workspaces` |
`https://coder.com/docs/workspaces/shared-workspaces` | `cli/sharing.go`
(CLI help, 2 places) |
| `https://coder.com/docs/user-guides/workspace-access` |
`https://coder.com/docs/workspaces/workspace-access` | `README.md` |
|
`https://coder.com/docs/user-guides/workspace-access/jetbrains/toolbox`
| `https://coder.com/docs/workspaces/workspace-access/jetbrains/toolbox`
| `examples/templates/docker/main.tf` |
| `https://coder.com/docs/user-guides/workspace-dotfiles` |
`https://coder.com/docs/workspaces/workspace-dotfiles` |
`coderd/templatebuilder/bases/{azure-linux,docker,kubernetes}/README.md`,
`examples/templates/{azure-linux,docker,kubernetes}/README.md` |
| `https://coder.com/docs/user-guides/workspace-management` |
`https://coder.com/docs/workspaces/workspace-management` | `README.md`,
`coderd/templatebuilder/bases/{aws-linux,aws-windows,azure-linux,digitalocean-linux,docker,kubernetes}/README.md`,
`examples/templates/{aws-linux,aws-windows,azure-linux,azure-windows,digitalocean-linux,docker-devcontainer,docker-envbuilder,docker,kubernetes-devcontainer,kubernetes,nomad-docker}/README.md`,
`site/src/api/queries/workspaces.ts` (JSDoc) |
## Validation run
- `make gen/docs-manifest`: clean diff afterward.
- `make lint/docs-manifest`, `lint/docs-redirects` (`-base
docs/ia-tutorials-nav`: 36 rules OK), `lint/docs-html`, `lint/emdash`:
pass.
- `pnpm check-docs` (markdownlint + table formatter): pass.
- Vale over `docs/`: identical to `docs/ia-tutorials-nav` (12 warnings,
1 error, 645 suggestions, all pre-existing).
- Local relative-link check over `docs/**/*.md`: 0 unresolved (3410
links and images in 498 files).
- `grep -rn user-guides docs/` finds only `docs/redirects.json`, image
paths under `docs/images/user-guides/`, and the issue link above.
- 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. `make gen` left a clean tree.
- Targeted tests:
- Go: `go test ./cli -run TestCommandHelp`, `./examples/...`,
`./coderd/templatebuilder/...`.
- Site: Vitest for the touched directories (22 files, 409 tests), and
the `UserDropdown` and `SecretsPageView` story tests (2 files, 59
tests).
- Every `docs()` path and `coder.com/docs` URL in the chore diff
resolves to a page and heading in this branch.
- Frontend deep review (all 8 roles) on the `site/` diff: no blocking or
should-fix findings; the nits are in question 2.
- Restacked on the rebased `docs/ia-tutorials-nav` (on `main` at
`ccf5ec74ae`). After the restack, `make gen/docs-manifest` (clean),
`lint/docs-manifest`, `lint/docs-redirects` (36 rules OK),
`lint/docs-html`, `lint/emdash`, `pnpm check-docs`, and the
relative-link and anchor check over the changed pages pass.
- Page counts: `docs/**/*.md` (excluding `.style`) 485 → 485;
`manifest.json` routes 482 → 482 (moves only).
- **Link health (commit 3):**
- linkspector 0.5.6 with `.github/.linkspector.yml` over all of `docs/`,
like the weekly docs job, run locally.
- `origin/main`: 0 errors. Before the fix (`7382a41faa`): 11 errors. 10
were `https://coder.com/docs/<new path>` 404s: the 6 from #31645 plus 4
`workspaces/...` URLs. The 11th was a transient Red Hat URL failure in
`install/server/openshift.md`, which is unchanged from `main` and passed
on reruns. After the fix (`c1f287fc1b`): 0 errors. Nothing is new
compared with `main`.
- After the fix: `make gen/docs-manifest` (clean), `lint/docs-manifest`,
`lint/docs-redirects` (36 rules OK against `docs/ia-tutorials-nav`),
`lint/docs-html`, `lint/emdash`, `pnpm check-docs`, and the
relative-link check (0 unresolved in 3419 links) pass. The full `make
pre-commit`, including `make gen`, passed on the commit.
- Outside `docs/`, no line in this stack adds an unversioned
`coder.com/docs` URL compared with `main`.
- Tests after the fix:
- Go: `go test ./cli -run 'TestCommandHelp|TestServerYAMLConfig'`,
`./examples/...`, `./coderd/templatebuilder/...`, `./cli/cliui`.
- Site: Vitest for the touched directories (21 files, 404 tests), and
the `UserDropdown` story tests (28 tests).
- **Skipped:** the docs-engine sync check, which was not available in
this environment.
<details>
<summary>Implementation notes</summary>
- Same one-shot move script as PRs A to C, with a single rule,
`docs/user-guides/` → `docs/workspaces/`. It resolves each relative link
against the page's old directory, maps the target through the move,
recomputes it from the new directory, and also rewrites
`coder.com/docs/...` and
`github.com/coder/coder/(blob|edit|tree)/main/docs/...` URLs. It skips
fenced code blocks and inline code, and refuses to run on a dirty
`docs/` tree.
- After #31645 and #31647 got their link-health fixes, a plain rebase of
this branch conflicted in `esr-2.24-2.29-upgrade.md`, where both changed
the same table rows. Instead of resolving by hand, I rebuilt the docs
and chore commits from the fixed `docs/ia-tutorials-nav` with the same
scripts. The resulting docs commit differs from the earlier one only by
#31645's fix, and the chore commit touches the same 36 files.
- No hand edits were needed in the docs commit. The sidebar sources were
renamed with `git mv` and their `path`/`include` prefixes rewritten.
- The redirect script repointed every existing destination under
`/docs/user-guides` before appending the two new rules.
- Restacked on 2026-11-03 onto `docs/ia-tutorials-nav` at `76aed1a618`.
The chore commit conflicted with #31603 in
`site/src/pages/WorkspacesPage/WorkspaceHelpPopover.tsx`; both links
keep `main`'s `target="_blank" rel="noreferrer"` with only the path
changed, and the `WorkspacesPage` Vitest suite (24 tests) passes. Folded
into the docs commit: the `../user-guides/` links in
`docs/coder-agents/bring-your-own-mcp-servers.md`, a page `main` added,
now point at `../workspaces/`.
</details>
---------
Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com>
Co-authored-by: Nick Vigilante <nick.vigilante@coder.com>
|
||
|
|
f97eee3c49 |
docs: redistribute tutorials and rename top-level sidebar sections (#31647)
> [!NOTE] > Generated by Coder Agents. The branch and this description were written by an AI agent and need human review. ## Summary Third of three stacked PRs for the docs IA overhaul (Proposal 1, sections 1 and 4). This PR dissolves Tutorials and finishes the top-level nav. - **Tutorials redistribution.** Every remaining `docs/tutorials/` page moves to the section it belongs to (`git mv`, table below). The `tutorials/index.md` and `tutorials/best-practices/index.md` hub pages are deleted, so `docs/tutorials/` no longer exists. That matters for the folder-driven beta renderer: no stray "Tutorials" group is left. `example-guide.md` was already deleted on `main` in #30711. - **Duplicate Tutorials entries are dropped.** Each of these pages stays in the sidebar at its real location: Quickstart, Image management, JFrog Artifactory, Island browser integration, Deploy Coder on Azure with an Application Gateway, Pre-install JetBrains IDEs, and JetBrains IDEs air-gapped. Scale Coder was also a duplicate, already listed under Install > Validate > Scale testing, and it stays there. - **Istio** (`admin/integrations/istio.md`) gets its sidebar entry under Administration > Integrations, after Island. Before this PR, only Tutorials linked to it. - **Nav renames.** - About becomes **Home**, with no children; `about.yml` is renamed `home.yml`. A third commit, `docs: title the docs landing page Home`, changes the `docs/README.md` front matter title from About to Home and deletes the stale HTML comment that said the first section must be titled About. - Quickstart becomes **Get started**. - User guides becomes **Workspaces**. - **Support** (with Support bundle) becomes a top-level section and goes last; `about/support.yml` moves to `support.yml`. - **Screenshots.** Nothing to do here: #31465 already deleted `about/screenshots.md` on `main` and added its redirect. - **Final top-level order:** Home, Get started, Install, Templates, Workspaces, Coder Agents, AI Governance, Agent Relay, MCP server, Administration, Reference, Support. - Commit 2, `chore: point in-product docs links at the new docs paths`, makes two edits outside `docs/`. You can drop it. - `README.md`: the `docs/about#why-coder` link now points to `docs#why-coder`. - `cli/server.go`: the built-in PostgreSQL error message now links to `install/server/external-database`. - The last commit, `fix: keep docs links healthy before the release`, reverts both of those back to the URLs that are live today (`https://coder.com/docs/about#why-coder` and `https://coder.com/docs/tutorials/external-database`). Both are hardcoded, unversioned `https://coder.com/docs/...` URLs, and the new paths 404 on the live site until a release that includes this stack becomes the default. See "Post-release follow-up". No hand-written page in this PR's moves had an absolute `coder.com/docs` link to a moved page, so `docs/` needed no changes. Net, this PR changes nothing outside `docs/`. Stack: `docs/ia-ai-sections` (with Templates squash-merged in #31646) → **this PR** → `docs/ia-workspaces-folder` (folder rename). Refs: Linear DOCS-1154, DOCS-1179. ## Move map | Old | New | Sidebar position | | --- | --- | --- | | `tutorials/configuring-okta.md` | `admin/users/oidc-auth/configuring-okta.md` | Administration > Users > OpenID Connect (last) | | `tutorials/best-practices/organizations.md` | `admin/users/organizations-best-practices.md` | Administration > Users, after Organizations | | `tutorials/best-practices/security-best-practices.md` | `admin/security/security-best-practices.md` | Administration > Security (last) | | `tutorials/reverse-proxy-apache.md` | `admin/networking/reverse-proxy-apache.md` | Administration > Networking, before Troubleshooting | | `tutorials/reverse-proxy-caddy.md` | `admin/networking/reverse-proxy-caddy.md` | same | | `tutorials/reverse-proxy-nginx.md` | `admin/networking/reverse-proxy-nginx.md` | same | | `tutorials/gcp-to-aws.md` | `install/operate/gcp-to-aws.md` | Install > Operate, before Uninstall | | `tutorials/azure-federation.md` | `install/operate/azure-federation.md` | same | | `tutorials/image-pull-secret.md` | `install/operate/image-pull-secret.md` | same | | `tutorials/postgres-ssl.md` | `install/server/postgres-ssl.md` | Install > Install the control plane (last) | | `tutorials/external-database.md` | `install/server/external-database.md` | same (**deviation**, see below) | | `tutorials/best-practices/scale-coder.md` | `install/validate/scale-coder.md` | unchanged: Install > Validate > Scale testing | | `tutorials/faqs.md` | `reference/faqs.md` | Reference (last) | | `tutorials/persistent-shared-workspaces.md` | `user-guides/persistent-shared-workspaces.md` | Workspaces, after Shared workspaces | | `tutorials/cloning-git-repositories.md` | `user-guides/cloning-git-repositories.md` | Workspaces (end) | | `tutorials/best-practices/speed-up-templates.md` | `user-guides/speed-up-templates.md` | Workspaces (end) | | `tutorials/index.md` | deleted | | | `tutorials/best-practices/index.md` | deleted | | All paths are relative to `docs/`. Every relative link and image path is fixed, in moved pages and in pages that link to them, including the `github.com/coder/coder/edit/main/docs/...` link in the FAQ page and the link to the build timeline in `templates/extending-templates/script-ordering.md`, which is new on `main`. ## Redirects added | Source | Destination | | --- | --- | | `/docs/tutorials/azure-federation` | `/docs/install/operate/azure-federation` | | `/docs/tutorials/best-practices/organizations` | `/docs/admin/users/organizations-best-practices` | | `/docs/tutorials/best-practices/scale-coder` | `/docs/install/validate/scale-coder` | | `/docs/tutorials/best-practices/security-best-practices` | `/docs/admin/security/security-best-practices` | | `/docs/tutorials/best-practices/speed-up-templates` | `/docs/user-guides/speed-up-templates` | | `/docs/tutorials/cloning-git-repositories` | `/docs/user-guides/cloning-git-repositories` | | `/docs/tutorials/configuring-okta` | `/docs/admin/users/oidc-auth/configuring-okta` | | `/docs/tutorials/external-database` | `/docs/install/server/external-database` | | `/docs/tutorials/faqs` | `/docs/reference/faqs` | | `/docs/tutorials/gcp-to-aws` | `/docs/install/operate/gcp-to-aws` | | `/docs/tutorials/image-pull-secret` | `/docs/install/operate/image-pull-secret` | | `/docs/tutorials/persistent-shared-workspaces` | `/docs/user-guides/persistent-shared-workspaces` | | `/docs/tutorials/postgres-ssl` | `/docs/install/server/postgres-ssl` | | `/docs/tutorials/reverse-proxy-apache` | `/docs/admin/networking/reverse-proxy-apache` | | `/docs/tutorials/reverse-proxy-caddy` | `/docs/admin/networking/reverse-proxy-caddy` | | `/docs/tutorials/reverse-proxy-nginx` | `/docs/admin/networking/reverse-proxy-nginx` | | `/docs/tutorials/best-practices` | `/docs` (deleted hub, **please confirm**) | | `/docs/tutorials` | `/docs` (deleted hub, **please confirm**) | | `/docs/about` | `/docs` | Exact rules are used instead of a `/docs/tutorials/:path*` wildcard, because the pages went to many different sections. The `/docs/about` rule stays: classic coder.com adds the `/docs/about` alias only when the first section is titled About, so after the rename that URL needs the redirect. `/docs/about/screenshots` → `/docs` is already on `main` (#31465), so this PR doesn't add it. **coder.com and router static redirects:** a chain simulation of coder.com's and the router's static rules together with this branch's `docs/redirects.json` finds no loops or hidden pages from this PR. The static `/docs/tutorials/...` and `/docs/about` rules there still work; some now take two redirects. The only loops in the stack come from the Templates move; see #31645, coder/coder.com#1201, and coder/docs-engine#304. ## Deviations from the proposal - **`external-database.md` goes to `install/server/`, not `templates/`.** The page covers the control plane's PostgreSQL database, so it sits next to `postgres-ssl.md`. - **Dead links to the Tutorials hub.** - `admin/index.md` linked to "Tutorials and FAQs"; it now links to the FAQs only. - The style guide's link-wording examples in `docs/.style/style-guide/word-choice.md` linked "Quickstart" to `tutorials/index.md`; they now link to `get-started/index.md`. - **Support icon.** Top-level sections have icons, so Support gets `info.svg`. - **Home title.** Titling the first section Home was checked against both renderers. Classic coder.com renders `/docs` from its own landing component, and docs-engine maps `README.md` to the root page and already titles it Home. `docs/README.md` stays in place, because classic serves `/docs.md` from it and docs-preview references it. Its front matter title is now Home, and the warning comment about the About title is gone. - **Other page titles not changed.** Only the sidebar titles changed. The front matter titles of `get-started/index.md` and `user-guides/index.md` stay as they are. - **Proposal page count.** The proposal expected 469 pages, measured against an older `main`. Current `main` already differs, so I report counts below instead of matching that number. ## Open questions for Nick 1. Confirm the redirect targets for the two deleted hubs (both `/docs`). 2. `speed-up-templates.md` lands in Workspaces, as the proposal says, but it is mostly about template build performance. Should it go to Templates instead? 3. Confirm `external-database.md` under Install (see PR B). 4. The sidebar sources still live under `docs/manifest/`, mirroring the new folders (`home.yml`, `support.yml`, and so on). Moving them next to the Markdown files is the follow-up PR waiting on the naming decision (DOCS-1154). ## 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. | Current (old) URL | Post-release URL | Files | | --- | --- | --- | | `https://coder.com/docs/about#why-coder` | `https://coder.com/docs#why-coder` | `README.md` | | `https://coder.com/docs/tutorials/external-database` | `https://coder.com/docs/install/server/external-database` | `cli/server.go` (built-in PostgreSQL error message) | ## Validation run - `make gen/docs-manifest`: clean diff afterward. - `make lint/docs-manifest`, `lint/docs-redirects` (`-base docs/ia-templates`: 34 rules OK), `lint/docs-html`, `lint/emdash`: pass. - `pnpm check-docs` (markdownlint + table formatter): pass. - Vale over `docs/`: the same 12 warnings and 1 error as `main`, all pre-existing (suggestions: 645, the same as PRs A and B). - Local relative-link check over `docs/**/*.md`: 0 unresolved. - Pre-commit hook: `make pre-commit-light` on both docs commits, and the full `make pre-commit` on the chore commit. `make gen` left a clean tree. - After the Home title commit, the full docs lint set above was re-run and passed again (34 redirect rules OK, 0 unresolved links). Vale on `docs/README.md` shows only its pre-existing alert. - Restacked on the rebased `docs/ia-ai-sections` (on `main` at `ccf5ec74ae`). After the restack, `make gen/docs-manifest` (clean), `lint/docs-manifest`, `lint/docs-redirects` (34 rules OK), `lint/docs-html`, `lint/emdash`, `pnpm check-docs`, and the relative-link and anchor check over the changed pages pass. - **Link health (fix commit):** - linkspector 0.5.6 with `.github/.linkspector.yml` over all of `docs/`, like the weekly docs job, run locally. - `origin/main`: 0 errors. This branch before the fix (`5fe2b627df`, on the pre-fix `docs/ia-ai-sections`): the same 6 `https://coder.com/docs/<new path>` 404s as #31645, plus a transient Red Hat URL failure in `install/server/openshift.md`. That URL is unchanged from `main`, and it passed on reruns. After rebasing onto the fixed `docs/ia-ai-sections` and adding this fix (`c664641e1e`): 0 errors. Nothing is new compared with `main`. - After the fix: `make gen/docs-manifest` (clean), `lint/docs-manifest`, `lint/docs-redirects` (34 rules OK against `docs/ia-ai-sections`), `lint/docs-html`, `lint/emdash`, `pnpm check-docs`, and the relative-link check (0 unresolved) pass. The full `make pre-commit` passed on the commit. - Page counts across the stack: | | `main` | after A | after B | after C | | --- | --- | --- | --- | --- | | `docs/**/*.md` (excl. `.style`) | 490 | 487 | 487 | 485 | | `manifest.json` routes | 495 | 492 | 492 | 482 | The 10 routes removed in C are the 2 Tutorials hubs, 7 duplicate Tutorials entries, and the duplicate Scale Coder entry. The Istio entry moved, so it nets to zero. - **Skipped:** the docs-engine sync check, which was not available in this environment. <details> <summary>Implementation notes</summary> - Rebuilt on the new `docs/ia-templates`, which is based on `main` at `9839406ff7` (2026-11-02). After #31646 squash-merged PR B into `docs/ia-ai-sections`, this branch was rebased onto it with `git rebase --onto`; the tree didn't change. It was rebased again onto `docs/ia-ai-sections` after #31645's link-health fix commit (`def074caab`), which applied cleanly. - Restacked on 2026-11-03 onto `docs/ia-ai-sections` at `4c356c6314`, after #31645 was rebased onto `main` at `ccf5ec74ae`. The restack applied cleanly. Folded into the docs commit: the links between `shared-workspaces.md` and `persistent-shared-workspaces.md` that `main` added in #31152 now resolve from the moved page. `git range-diff` against the previous head (`c664641e1e`) shows only those changes and the sidebar entry `main` added for Bring your own MCP servers. - The same one-shot move script as PRs A and B did the move and link pass from a clean tree. Run on the old base, it reproduced the old commit except for the three hand edits listed under Deviations (dead Tutorials hub links), which were reapplied by hand. - The sidebar changes were applied with a three-way merge of each YAML file from the earlier version of this branch onto the current files, so entries added on `main` since then (for example Nix(OS) under Integrations) stay in place. - Changes from the earlier version of this branch: the Screenshots page and its redirect are gone from this PR, because #31465 did both on `main`. `admin/index.md` was reworded on `main`, and the Tutorials hub link was removed from the new wording. One more page link is fixed (`script-ordering.md`). </details> <details> <summary>CI flake on <code>70232dbbfb</code></summary> The `fmt` job failed because GitHub canceled the step on the Depot runner, before any formatting ran. A rerun of the failed jobs passed. </details> --------- Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com> Co-authored-by: Nick Vigilante <nick.vigilante@coder.com> |
||
|
|
a7f3e3b685 |
docs: promote the AI sections and Templates to the top level of the sidebar (#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> |
||
|
|
16551fd67f |
feat: enable Coder.AbbreviationFirstUse (#30878)
Adds `Coder.AbbreviationFirstUse`, a Vale rule that requires each abbreviation to be expanded on its first use on a page, in the form "Expanded Form (ABBR)". It supports [WCAG 2.2 Level AAA Success Criterion 3.1.4 (Abbreviations)](https://www.w3.org/TR/WCAG22/#abbreviations). Following the "Adding a Vale rule" pattern in `docs/.style/README.md`, the PR has two commits: the cleanup first, then the enable. ## Cleanup commit 431 first uses expanded across 167 pages, so the rule ships with zero findings across `docs/`, excluding `docs/.style/style-guide/`. The branch was rebuilt on current `main`, so pages added or moved since the first draft are covered. - Where the first use is a bold UI label (**CA Path**, **Add redirect URI**, **Redirect URI**), the label stays as the UI shows it and the expansion goes elsewhere in the same paragraph or list item. - Reversed forms such as "PKCE (Proof Key for Code Exchange)" are flipped to the expanded-first form. - A few sentences took a small rewording to fit the expansion: list steps that would pass the 20-word limit (`Coder.StepLength`), and spots where the expansion would nest parentheses. - MITM is expanded as "machine-in-the-middle" rather than "man-in-the-middle". Every use describes the AI Gateway Proxy intercepting traffic on purpose, so "on-path attacker" doesn't fit. The inclusive-language table on `accessibility-and-inclusion.md` gains the substitution: "on-path attacker" for the attack, "machine-in-the-middle" for the feature. - Unrelated fixes on lines already being edited: `DERP MAP` → `DERP map`, and `ENV` → "environment variable" in `faqs.md`. ## Enable commit **Rule design.** The rule is a `conditional`. `first` matches 2 to 6 capitals, each optionally followed by digits (`EC2`, `P2P`), and a lookahead lets a plural `s` count as a use of the singular. `second` captures the abbreviation in `word (ABBR)`, including `(CI/CD)` and `(PCI DSS)` pairs. Vale collects the captures across the page's blocks in document order, so a later expansion doesn't cover an earlier use. Within a single paragraph, list item, or table cell, an expansion anywhere in the block counts. **Scope.** `scope: ~heading` skips headings, because a page title often names an abbreviation that the first paragraph then expands. Vale already skips front matter, code blocks, inline code, and link URLs. `.vale.ini` turns the rule off for the pages generated from Go source that `Coder.UnitSpacing` already skips: `docs/reference/{api,cli}/*.md`, `configuration-reference.md`, and `prometheus.md`. **Severity: `warning`.** Whether an abbreviation is familiar enough to skip is a judgment call, so this is guidance with legitimate exceptions, not hard policy. **Exceptions**, each group commented in the rule file: | Group | Entries | Reason | | --- | --- | --- | | Known to every reader | AI, API, AWS, CLI, CPU, DNS, GCP, HTTP(S), ID, IDE, IP, JSON, OS, PR, RAM, SDK, SQL, SSH, TLS, UI, URL, VM, YAML | Abbreviations every reader of the docs knows. Plurals such as VMs and SDKs pass too | | Units, clock times, file and package formats | GB, KB, MB, AM, PM, CSV, GIF, JPEG, PDF, PNG, RPM, SVG, VSIX, ZIP | Readers know these by the abbreviation, not the expansion | | Not abbreviations | NOTE, TIP, OK, README, SKILL, ALL, AND, ANY, ERROR, MUST, NOT, ON, OR, DELETE, GET, POST, PUT, ILIKE, VACUUM, LOGIN, PLAIN, NUL, CRON, TERM, DOCS, `DOC\d+`, `RFC\d+`, TL, DR | Alert labels, file names, emphasis in capitals, HTTP methods, SQL keywords, SMTP auth mechanisms, rule labels in `docs/AGENTS.md`, RFC numbers, TL;DR | | Names written in capitals | VS, IDEA, IU, NGINX, SUSE, GNU, XFCE, DX, IBM, DCV, TRAMP, MSYS2, NET, VSX, ARM, AMD, GPT, AES, GCM, HMAC, HS256, RSA, SHA, SHA256 | The capitals are the product, company, or algorithm name (VS Code, IntelliJ IDEA, .NET, Open VSX, Amazon DCV, AMD) | The "known to every reader" group is the list that needs judgment, and it's the one to push back on. The other groups only stop the regex from treating words and names as abbreviations. **Documentation.** A new "Expand abbreviations on first use" section on `accessibility-and-inclusion.md`, and the style guide README's checks table, coverage table, and rule counts (90 → 91 rules, 22 → 23 tool-checked). ## Known limits - The rule checks that an expansion exists, not that it's correct: any word followed by `(ABBR)` satisfies it. - An abbreviation in an image's alt text is checked before the paragraph around it, so one alt text (`aws-marketplace.md`) carries its own expansion. - Some expansions read heavily in dense table cells and inline lists, for example the four Kubernetes services in `docker-in-workspaces.md`. They're correct, but a reviewer may prefer adding a specific abbreviation to the exceptions instead. ## Testing - `vale docs/` (Vale 3.7.1 through mise): zero `Coder.AbbreviationFirstUse` findings. Findings from every other rule match `main` file for file. - `pnpm run format-docs`, `pnpm run lint-docs`, `scripts/check_emdash.sh`, and `make lint/prose` run clean, and the repository pre-commit hooks (including `lint/style-claims`) pass on both commits. Linear: DOCS-1311 Generated by Coder Agents on behalf of @nickvigilante. |
||
|
|
c0f7663e95 |
feat: support editing queued chat messages (#29215)
The owner of a chat can edit a queued message through
`PATCH /api/v2/chats/{chat}/queue/{queuedMessage}`. chatd never sends
a row under edit (`editing_since`): rows ahead of it still send in
order, and a turn that ends at it puts the chat in the new `paused`
status. Ending the head's edit, deleting it, or promoting a queued row
continues the chat. Interrupting sends still run ahead of the queue.
The chat state machine classifies a queue whose head is under edit as
its own sub-state (R1P, I1P, A1P, E1P, XE1P, P), so every path to
`paused` is in the transition matrix. A chat whose family has a paused
member cannot be archived, and auto-archive skips that family. Queue
edit and delete are owner-only, because both can send the next message
with the owner's credentials.
`ChatQueuedMessage` gains `editing_since` and `reasoning_effort`, and
`ChatStatus` gains `paused`.
Closes CODAGT-1028
Refs CODAGT-971
|
||
|
|
2255794d65 | feat: add response_size_bytes metric to chatd (#29816) | ||
|
|
21471da74c |
feat: enable Coder.Semicolons Vale rule (#30787)
Depends on #30782. Adds `Coder.Semicolons`, a Vale rule that flags a semicolon in prose. It enforces [No semicolons in prose](https://github.com/coder/coder/blob/main/docs/.style/style-guide/capitalization-and-punctuation.md#no-semicolons-in-prose). - Severity: `warning`. - Scope: paragraphs, list items, headings, and blockquotes in `docs/**` except `docs/.style/style-guide/**`. Table cells, code spans, and code blocks keep their semicolons. - Baseline: 137 findings. The cleanup commit fixes 112 of them across 61 files by splitting sentences, or by using a comma or a connecting word where a split reads badly. - Excluded in `.vale.ini`: `docs/reference/{api,cli}/*.md` and `docs/admin/setup/configuration-reference.md`. Their text is generated from Go source (CLI flag help, Swagger comments), and 25 findings live there. Fixing them means editing Go and regenerating, so I used a commented exclusion like `Coder.UnitSpacing` does. Say so if you prefer the Go fix. - Result: `vale --output=line docs/` reports 0 `Coder.Semicolons` findings outside the style guide. - Three headings lost a semicolon, so their anchors changed. I updated the links in `docs/.style/` and in `.claude/` (`DOCS_STYLE_GUIDE.md`, the `write-docs` and `doc-check` skills). Linear: DOCS-1261 <details><summary>Decision log</summary> - Scope list is `paragraph`, `list`, `heading`, `blockquote`. Without `blockquote`, a semicolon in a `>` quote goes unreported, which I checked. Table cells are outside those scopes, so they stay exempt without extra config. - Token is `(?<!TL);(?!DR)`. `TL;DR` in `telemetry.md` is an abbreviation, not punctuation. - ` ` entities and `style="a: b;"` attributes don't match. Vale can report a real semicolon on the wrong line of a paragraph that contains an entity or raw HTML (for example, `modules.md:69` pointed at a semicolon on line 71), so cleanup used a paragraph-wide search instead of trusting reported lines. - A semicolon inside a fenced block in a blockquote (`ai-gateway/monitoring.md:105`, a YAML comment) isn't reported and stays. - Cleanup default: `; x` becomes `. X`, then I reviewed the diff and hand-fixed list fragments, parentheticals, and headings. Each new sentence sits on its own line, outside table cells. The hand-written part of `prometheus.md` is also reformatted to one sentence per line. - Heading rewrites: `Verify against the code and document exact values`, `Evidence justifies a claim and does not belong in the claim`, `STUN returned different addresses and you may be behind a hard NAT`. - `prometheus.md` is in the generated-page exclusion for `Coder.UnitSpacing` but not here. Its semicolon was in hand-written prose, so I fixed it. - Enable commit updates the footer, the checks table (scope text matches `.vale.ini`), the coverage counts (Capitalization and punctuation 3/7 to 4/6, total 20 to 21 tool-checked and 25 to 24 planned), and the "What the tooling checks" counts. Tests (fixtures in `/tmp`, not committed), each run with LF and CRLF files: - Flagged: paragraph, list item, ordered list item, heading, blockquote. - Not flagged: table cell, code span, fenced block, ` ` and `&`, an HTML `style` attribute, and `TL;DR`. - `go run ./scripts/styleclaims`, `make lint/emdash`, and the pre-commit hook (markdown, typos, style-claims) pass. </details> *Generated by [Coder Agents](https://coder.com/docs/ai-coder/agents) on behalf of @nickvigilante.* |
||
|
|
3ed2dfd8ca |
docs: promote usage of Nix(OS) and discourage use of envbuilder (#31141)
Adds a **Nix(OS)** docs page (`docs/admin/integrations/nixos.md`) presenting Nix flakes as an alternative to dev containers. It covers both Nix on an existing distribution (e.g. a Debian image, via the [Nix(OS) module](https://registry.coder.com/modules/coder-labs/nix)'s `nix develop` mode) and full NixOS workspaces (the [AWS EC2 (NixOS)](https://registry.coder.com/templates/coder-labs/aws-nixos) template). Both work in containers or VMs. The page is added to the sidebar under Integrations, after Dev Containers. Other pages get one-line links to it: - Dev Containers overview (`admin/integrations/devcontainers/index.md`) - Image management, "Let developers customize their own environment" - Templates overview, Best Practices - Managing templates, Next steps - Extending templates, Dev Containers - Envbuilder (managing templates) - Dev Containers user guide intro --- Generated with [Xum](https://mux.coder.com/) using Claude --------- Co-authored-by: Nick Vigilante <nickvigilante@users.noreply.github.com> |
||
|
|
28192213ab |
feat!: label the VS Code family and report built-in app usage per app (#29906)
The session banner now labels the VS Code family "VS Code Family", so it isn't confused with the VS Code editor. coderd_insights_applications_usage_seconds now reports built-in apps per app instead of per family. - Generate the frontend's family labels from the Go table in codersdk. - Add the connection_method label: workspace_app for template apps, and ssh, reconnecting_pty, or port_forwarding for built-in apps. - Rename the application_name label to display_name. For built-in apps it holds the registry name, "Unknown" for unknown, and "Other apps" for overflow. - Built-in apps get one series per app name, only for apps used in the window. The series limit and the fold rule are shared with the template insights API. - Breaking: selectors with a value for application_name, or with slug="", match nothing. The Prometheus docs map each old series to its new one. Closes #29940 Closes CLIENT-1034 Closes CLIENT-1036 |
||
|
|
81c40579dc |
feat: enable Coder.StepLength Vale rule (#30791)
Adds `Coder.StepLength`, a Vale `script` rule for [Keep steps short](https://github.com/coder/coder/blob/main/docs/.style/style-guide/procedural-writing.md#keep-steps-short). It flags an ordered-list step whose instruction, the step's first paragraph, has more than 20 words, counted as [How to count words](https://github.com/coder/coder/blob/main/docs/.style/style-guide/voice-and-tone.md#how-to-count-words) describes. Paragraphs below the instruction explain the step and aren't counted. - Severity: `warning`. - Scope: `docs/**` except `docs/.style/style-guide/**`. - Baseline: 124 findings in 60 hand-written files. The cleanup shortens each long instruction, moves its explanation into one paragraph below it, or splits a step that holds several actions. After cleanup `vale docs/` reports 0 `Coder.StepLength` findings, and the other rules report no new findings on the changed files. - The guide section now says the limit covers the instruction, and that one action or one explanation must not be broken across paragraphs to meet it. - Generated pages (`docs/reference/{api,cli,agent-api}`, `configuration-reference.md`, `prometheus.md`): no findings, so no `.vale.ini` exclusion is needed. Linear: DOCS-1272 <details><summary>Decision log</summary> **Review change (Ian's review)** - The first version limited every paragraph of a step to 20 words. The cleanup for it chopped explanations into several short paragraphs, which made steps harder to read and sometimes changed their meaning. - The rule now counts only the first paragraph segment of each step. The content files were reset to `main` and the cleanup was redone against the narrower rule. - Cleanup preferences, in order: shorten the instruction; keep a short instruction and put the explanation, with its original wording, in one paragraph below it; split a step into one step for each action; for descriptive lists (such as "How it works"), keep each item one statement. - `docs/admin/users/oidc-auth/microsoft.md` keeps the split into separate steps, with Ian's wording suggestions applied. "click" became "select" in step 16 because `Coder.SelectClick` flags it. **Rule shape** - A `script` rule (Tengo) with `scope: raw`, because the count depends on Markdown structure that per-paragraph scopes hide. - A step is an ordered-list item with a `1.` or `1)` marker. A nested ordered item is its own step. Bullets, even under a step, are not steps. - The instruction ends at a blank line, a fence, a nested list, a table row, a blockquote, block-level HTML, or an explicit hard break (`<br>`, a trailing backslash, or two trailing spaces). - Fenced code blocks, HTML comments, tables, images, and nested bullets add no words. - CRLF: `\r` counts as whitespace, and offsets come from the raw text. **Counting approximations (also in the rule header)** - A code span and a `**bold**` or `__bold__` span are one word each. - Words split on whitespace, so a hyphenated compound and `30 seconds` are one word. - Link text counts word by word, destinations are skipped, images add no words, and `<https://...>` autolinks are one word. - A token with no letter or digit, such as the `>` in `**A** > **B**`, is not a word. - Tengo indexes strings by rune but measures them in bytes, so the script rewrites each non-ASCII rune to ASCII of the same byte length first. **Tests** (fixtures under `/tmp/sltest/`, not committed; run with the repo `.vale.ini`, LF and CRLF) - Flagged: a long instruction, a short action and a long result in one paragraph, a long nested ordered step. - Not flagged: a long paragraph below a short instruction, text after a `<br>` hard break, a long paragraph after a code block, a long nested bullet. - LF and CRLF output is identical. - Pre-commit hooks (`fmt/markdown`, `lint/markdown`, `lint/emdash`, `lint/style-claims`, `lint/typos`) pass. - Not run on Windows or macOS. The rule is plain text processing, and the CRLF cases simulate Windows line endings on Linux. </details> *Generated by [Coder Agents](https://coder.com/docs/ai-coder/agents) on behalf of @nickvigilante.* |
||
|
|
1aff810443 |
chore: sync fantasy with upstream v0.45.5 (#31288)
Moves the fantasy pin to the tip of `coder_2_33` (`85ffbbe`). That commit is coder/fantasy#72, which merges 87 upstream charmbracelet/fantasy commits, v0.40.0 to v0.45.5. Between the two pins 117 files change. Upstream's own v0.40.0 to v0.45.5 change, without tests, testdata, examples, `go.sum` and the kronk provider, is 43 files, +2271/−928. ## What reaches chatd chatd builds only the `anthropic`, `openai` and `openaicompat` fantasy clients (`chatprovider.ModelFromConfig`); other vendors reach it through the AI Gateway on one of those. So the upstream changes to the Google, Vercel, OpenRouter, Bedrock, Azure and kronk providers, and to the `fantasy.Agent` loop and its retries, do not run in chatd. These do: - **Chat Completions and openaicompat streams** keep reasoning on batched and DeepSeek-shaped chunks, keep `finish_reason: length` when tool calls are truncated, and stop sending empty reasoning fields. openaicompat drops assistant turns that hold only reasoning. - **Token usage.** When an OpenAI-shaped backend reports reasoning tokens apart from completion tokens (reasoning larger than output), output tokens now include them, so that backend's reported output tokens and cost rise. OpenAI's own shape, where reasoning is a subset, is unchanged. - **Responses.** A content-filtered turn no longer reads as a tool-call turn. - **Context overflow.** Baseten, Fireworks and Parasail prompt-length errors set `ContextTooLargeErr`, which compaction acts on. - **Anthropic.** Tool calls whose content block never closes are reported. For Claude 5 models, thinking defaults to `display: "summarized"` when the chat config sets none; a configured display still wins. `TestThinkingDropBlockModel_RetriesWithEffort` now expects the field in the retry body. - **Anthropic keepalives.** Fantasy forwards `message_start`, `message_delta` and unknown events as content-free `keepalive` parts. The first one arrives before any model output, so this PR makes `ttft_seconds` and the `time_to_first_token` stage skip them, as they skip warnings. They still reset the stream silence guard. `processStepStream` ignores them, and the debug recorder counts them in its part count but records no content. - **Tool-result media** now goes through upstream's shared `ToolRunBuffer`, which replaces coder/fantasy#64 and does the same thing. #72 keeps coder's anthropic-sdk-go and openai-go forks, Go 1.26 and kronk v1.31.5, so upstream's SDK and Go moves do not come along. `go mod tidy` raises the modules fantasy v0.45.5 requires, among them otel exporters v1.47, the AWS SDK, `google.golang.org/api` v0.307 and go-openapi v1. All are upgrades. The `go.mod` comment now names #72 as the upstream sync. coder/coder#29861 stacks on this PR to pin coder/fantasy#62. <details> <summary>Verification</summary> - `go build ./...`. - `go test` passes on every package that imports fantasy (`coderd/x/chatd/...`), and `go test ./coderd -run 'TestChat|TestExpChat|TestMCP|TestAIBridge'` passes. - `TestGuardedStreamTTFTStage/WarningsAndKeepalivesThenContentObservesOnce` fails without the TTFT change (TTFT observed 0s instead of 1s) and passes with it. - `make pre-commit` passes. The generated Prometheus docs pick up the metric help change. Not verified against live backends in this PR: the stream fixes, the token usage change and the context-overflow patterns have no coder test against a real provider. coder/fantasy#72 reports a local chatd run against the AI Gateway on Anthropic, Responses, OpenAI Chat and openaicompat. </details> > 🤖 This PR was created with the help of Coder Agents, and _will be_ reviewed by a human. 🏂🏻 |
||
|
|
7eacfe95b2 |
feat: enable Coder.LatinAbbreviations Vale rule (#30794)
Builds on #30782, which is merged; the branch now merges `main`. Adds `Coder.LatinAbbreviations`, a Vale rule that enforces [Latin abbreviations](https://github.com/coder/coder/blob/main/docs/.style/style-guide/accessibility-and-inclusion.md#latin-abbreviations). - Suggests "for example", "that is", and "and so on" for `e.g.`, `i.e.`, and `etc.`, including `eg.`, `ie.`, and a missing final period (`e.g`). - Severity: `suggestion`. Scope: `docs/**` except `docs/.style/style-guide/**`, limited to paragraphs, lists, headings, and blockquotes. Table cells and code are skipped. - Baseline: 170 findings in 91 files. The brief estimated 148. - Cleanup: 153 findings fixed across 81 hand-written pages, 0 left in linted pages. The count is lower than the original 158 because other PRs on `main` already rewrote or removed some of the lines, and `parameters.md` was deleted on `main`. - `vs.` and `et al.` aren't flagged. Commits: 1. `docs(docs): use English forms of Latin abbreviations` 2. `feat(docs/.style): enable Coder.LatinAbbreviations Vale rule` Generated pages: `.vale.ini` skips `docs/reference/{api,cli}/*.md` and `docs/admin/setup/configuration-reference.md` for this rule, as it does for `Coder.UnitSpacing`. Their prose comes from CLI flag help text and Swagger comments in Go source, and `make gen` rewrites them, so a hand edit fails the `gen` check (an earlier revision of this PR edited `configuration-reference.md` and failed `gen` for that reason). Cleaning them means editing Go and regenerating the help golden files and API docs, which is left for a follow-up. Linear: DOCS-450 <details> <summary>Decision log</summary> - `extends: substitution`, so the message names the replacement: "Consider 'for example' instead of 'e.g.'". - `scope: [paragraph, list, heading, blockquote]`. The single scope `paragraph` skips list items, blockquotes, and headings, so all four are listed. Table cells have their own scope and stay excluded. - Explicit `[Ee]` and `[Ii]` classes with `ignorecase: false`, so sentence-initial `E.g.,` still matches but the browser name `IE.` doesn't. - `eg.` and `ie.` require the trailing period so ordinary words and file extensions stay quiet. - Cleanup rules, applied by script and then reviewed line by line: - `e.g.` and `i.e.` become "for example," and "that is," (capitalized at the start of a sentence), with a comma added when the original had none. - `etc.` becomes "and so on", with the sentence-ending period kept when `etc.` closed the sentence. - Lines inside table rows, fenced blocks, and code spans are untouched, so are the style guide and the generated pages. - Hard-wrapped lines keep their wrapping, and CRLF files keep CRLF. - The rest of the Vale output is unchanged: the per-rule counts for every other rule match the pre-cleanup run. Test cases (fixtures under `/tmp/latin-test/`, not committed), run with LF and CRLF line endings: - Flagged (15 each): `e.g.,` in a paragraph, `i.e.,`, `etc.` at the end of a sentence and before a comma, `eg.`, `ie.`, `e.g` and `i.e` without the final period, `E.g.,`, `I.e.,`, `Etc.`, a blockquote, a list item, a numbered item, and a heading. - Not flagged: a table row with `e.g.,`, `i.e.,`, and `etc.`, code spans, a fenced block, "for example", "that is", "and so on", `IE.`, `genre`, `series`, `egg`, `tie`, `etcetera`, `vs.`, `et al.`. - Known edge case: a path-like token such as `path/i.e/x` outside code matches. It doesn't occur in the corpus. Checks: - `vale --output=line docs/`: 0 `Coder.LatinAbbreviations` findings. - `go run ./scripts/styleclaims` passes. - The pre-commit-light hook passes on both commits. </details> *Generated by [Coder Agents](https://coder.com/docs/ai-coder/agents) on behalf of @nickvigilante.* |
||
|
|
9edb2e388d |
feat: enable Coder.USSpelling Vale rule (#30790)
Depends on #30782. Adds `Coder.USSpelling` at `warning` severity. The rule flags an `-ise` family (`organise`, `initialise`, `authorisation`) and a list of British spellings (`behaviour`, `labelled`, `cancelled`, `analogue`, `whilst`, and others) and suggests the US form. It covers `docs/**` except `docs/.style/style-guide/**` and the generated `docs/reference/{api,cli}/*.md` pages. Baseline: 13 findings before cleanup, 0 after. The first commit fixes 11 of them: 10 in hand-written pages and 1 in the Prometheus metrics table, which comes from metric help text. Two findings sit in generated reference pages, which `.vale.ini` excludes for this rule: the CLI alias `favourite` and `amongst` in a Go comment from a vendored dependency (the DERP map schema). The metric help text comes from `querymetrics.go`, so the fix lands there and in `generated_metrics` and `prometheus.md`. Known false positive: Vale doesn't skip bold text, so a UI label in bold that keeps British spelling is flagged. The rule comment and the guide footer say to use a code span for such a label. Linear: DOCS-1280 <details> <summary>Decision log</summary> - **Rule type**: `substitution`, so each message names the US form. The `-ise` family can't name a specific replacement, so it suggests "the -ize form". - **`cancelled`**: the guide's "Use US spelling" section lists `canceled` and `canceling`. The rule flags the double-l verb forms and leaves `cancellation` alone, which Merriam-Webster spells with one `l`. - **Exceptions**: Vale applies an exception to the matched word, so each is anchored with `^` and `$` and case-insensitive. The list covers `-wise` words and stems for `advise`, `advertise`, `exercise`, `promise`, `premise`, `compromise`, `surprise`, `comprise`, `concise`, `precise`, `revise`, `supervise`, `televise`, `devise`, `improvise`, `franchise`, `merchandise`, `disguise`, `despise`, `paradise`, `cruise`, `noise`, `raise`, `rise`, `wise`, and others, each with the endings `e`, `es`, `ed`, `ing`, `er`, and `ers`. The `mise` tool is excepted by name. - **Extra British spellings** beyond the guide table: other doubled-`l` verbs (`signalled`, `levelled`), `metre`, `litre`, `fibre`, `theatre`, `calibre`, `offence`, `pretence`, `analyse`, `judgement`, `acknowledgement`, `ageing`, `artefact`, `sceptic`, `aluminium`, `practise`, `enrol`, `fulfil`, `instil`, `skilful`. None appears in the corpus today. - **Generated pages**: excluded for `docs/reference/{api,cli}/*.md`, as `Coder.UnitSpacing` does. Changing the `favourite` alias would change CLI behavior, and the `amongst` comment isn't ours to edit. - **Prometheus doc**: edited by hand with matching table padding because `go run ./scripts/metricsdocgen` already rewrites the whole table on the base branch, independent of this change. Test cases, run with `vale --config` against fixtures that are not committed, in LF and CRLF: - Positive: `organise`, `initialise`, `authorise`, `customisation`, `authorisation`, `organisations`, `Organised`, `initialising`, `recogniser`, `customisable`, every explicit list entry, and capitalized forms. - Negative: `advise`, `exercise`, `otherwise`, `Enterprise`, `premise`, `compromise`, `promise`, `surprise`, `precise`, `concise`, `expertise`, `revising`, `supervising`, `improvising`, `raise`, `noise`, `cruise`, `franchise`, `merchandise`, `disguise`, `despise`, `paradise`, `appraise`, `sunrise`, `arise`, `liaise`, `clockwise`, `cancellation`, `canceled`, `mise`. - Skipped: words in code spans and fenced code blocks, such as `cancelled`. - LF and CRLF results are identical. Checks: `vale --output=line docs/` reports 0 `Coder.USSpelling` findings, `make lint/style-claims` passes, and the pre-commit hooks pass on both commits. </details> *Generated by [Coder Agents](https://coder.com/docs/ai-coder/agents) on behalf of @nickvigilante.* |
||
|
|
78aa570078 |
feat(docs): enable Coder.CheckOut Vale rule (#31185)
> [!NOTE] > Recreated from #30793 under coder[bot] by Superblink, at the request of @nickvigilante, so he can review and merge it. An AI agent wrote the original, which was opened from his account. The diff is identical to #30793, squashed onto current `main`. Superblink reviewed it and ran Vale over `docs/` before opening this PR (no new warnings or errors). #30793 should be closed in favor of this one. > Stack: based on #31184 (#31180 → #31181 → #31182 → #31183 → #31184 → #31185). The diff matches #30793 except for the counters in `docs/.style/style-guide/README.md`, which build on the PRs below this one. `make lint/style-claims` passes at every level. Builds on #30782, which is merged; the branch now merges `main`. Adds `Coder.CheckOut`, a Vale rule that enforces [Refer to or visit, not see or check out](https://github.com/coder/coder/blob/main/docs/.style/style-guide/word-choice.md#refer-to-or-visit-not-see-or-check-out). It flips only `Coder.CheckOut` in the footer; `Coder.SeeAlternatives` stays planned. - Flags "check out" and its inflections (`checks out`, `checked out`, `checking out`) when used to point the reader at a page or site. - Severity: `warning`. Scope: `docs/**` except `docs/.style/style-guide/**`. - Baseline: 11 findings in 10 pages, 0 after cleanup. One of them (`docs/ai-coder/agent-firewall/index.md`) landed on `main` after the branch was cut. - Cleanup rewrites each to "refer to" (docs destinations) or "visit" (external destinations). - The Git sense is allowed and isn't flagged. Examples: "check out the branch", `git checkout`, "a source checkout". - Generated pages: no findings, so no `.vale.ini` change and no Go source change. Commits: 1. `docs(docs): refer to or visit instead of "check out"` 2. `feat(docs/.style): enable Coder.CheckOut Vale rule` Linear: DOCS-1260 <details> <summary>Decision log</summary> - Vale's `existence` rule can't do this. RE2 has no lookahead, so the rule can't say "check out, unless a Git object follows". A token that includes the following words also fails: Vale can't locate a match that spans link text (`check out [Dev Containers]` renders without the bracket), and it silently drops the finding. Those link-follows cases are the main true positives. - The rule is therefore `extends: script` (Tengo, supported by the pinned Vale 3.7.1) with `scope: text`. It finds each "check out" and reports only those two words. It skips the match when one of the next 3 words is a Git object, or when "and" follows directly. - Git objects skipped: branch, repo, repository, code, source, commit, tag, PR, pull request, fork, clone, worktree, file, revision, ref, master, main, trunk, submodule, sha, changes, release, version, folder, directory, dotfiles. A hyphenated name such as `code-marketplace` isn't a Git object. - The one-word "checkout" is never flagged. In this corpus it's a Git noun or command (`git checkout`, "source checkout") or the `actions/checkout` action. The brief mentions "checkout" as a possible verb, but I found no verb use, so I left it out rather than guess. - `warning`, because the rule can't tell the senses apart from text alone. Test cases (fixtures under `/tmp/checkout-test/`, not committed), run with LF and CRLF line endings: - Flagged (8 each): link follows ("Check out [Dev Containers integration]"), "check out our [module registry]", "check out HashiCorp's [Getting Started Guides]", "Checking out the [Quickstart]", "checked out" in a blockquote, "Checks out" in a list item, a heading ("Check out more"), a hard-wrapped "check out the\n[envbox docs]". - Not flagged (0 each): "check out the branch", "the repository", "the code", "a commit", "the tag", "the PR", "the pull request", "check out and install a dotfiles repository", "source checkout", "Git checkout", `git checkout main`, a `git checkout -b` fenced block, "Checkout repository" in a list item, "the checkout action", "check outputs", "check output". Known gaps: - False negative: a cross-reference that names a Git word right after the verb, such as "check out our code samples". - False positive risk: a Git sense with an object the list doesn't name. Checks: - `vale --output=line docs/` reports 0 `Coder.CheckOut` findings. - `go run ./scripts/styleclaims` passes. - The pre-commit-light hook passes on both commits. </details> *Generated by [Coder Agents](https://coder.com/docs/ai-coder/agents) on behalf of @nickvigilante.* Created on behalf of @nickvigilante --------- Co-authored-by: Nick Vigilante <nick.vigilante@coder.com> |
||
|
|
e5c5779a56 |
docs: fold dynamic parameters into a Parameters section (#30912)
Dynamic parameters are how every parameter works now (default since v2.25.0), but the docs still split the concept across two sibling sidebar pages, "Parameters" and "Dynamic parameters". That hides form types, conditional parameters, and identity-aware parameters behind a legacy feature name. This PR folds them into a single **Parameters** section under **Extend templates**, with one focused child page per concept. Every code example from both old pages is kept (33 of 33 fenced blocks, including the commented-out daisy-chaining example). ## New structure | Page | Contents | Came from | |---|---|---| | `parameters/index.md` (Parameters) | What parameters are, defining one, provider version, how Coder evaluates parameters (data source caching, no HTTP fetching), types, options, required/optional, mutability, ephemeral, URL autofill | `parameters.md` + intro/requirements/data-source sections of `dynamic-parameters.md` | | `parameters/form-types.md` | `form_type` table, `styling` table, an example for each form type | `dynamic-parameters.md` | | `parameters/validation.md` | Number and string validation, validation that depends on other parameters | `parameters.md` + "Dynamic Validation" | | `parameters/conditional-parameters.md` | Show/hide, defaults from other parameters | `dynamic-parameters.md` | | `parameters/identity-aware-parameters.md` (`state: [premium]`) | Role-aware options, group-aware regions, groups as namespaces | `dynamic-parameters.md` | | `parameters/workspace-presets.md` | Presets | `parameters.md` | | `parameters/compatibility-mode.md` | Find, upgrade, and revert compatibility-mode templates | `dynamic-parameters.md` | | `parameters/troubleshooting.md` | Known issues, template variables, registry modules, module-not-loaded errors | `dynamic-parameters.md` | `parameters.md` moves to `parameters/index.md`, so `/docs/admin/templates/extending-templates/parameters` (and `#ephemeral-parameters`, which the dashboard links to) keeps working. ## Other changes - `docs/redirects.json`: `/docs/admin/templates/extending-templates/dynamic-parameters` redirects to the Parameters section. - Dashboard `docs()` links that pointed at `dynamic-parameters` now point at `parameters`, or at `parameters/compatibility-mode` where the link is about compatibility mode (the Storybook assertion is updated to match). - Inbound doc links updated. Glossary gets a **Parameters** entry, and **Dynamic parameters** is kept as the former name. - Tabs on the old page are replaced with headed sections, per the style guide's rule against tabs for content every reader needs. Each form type and example now has its own anchor. - Small cleanups in moved prose: sentence-case headings, "Dynamic Parameters" product-name references removed, the stale "Later in 2025..." registry-module sentence and GA announcement copy dropped, "template creation links" corrected to "workspace creation links" for URL autofill. ## Not in this PR Dashboard UI copy still says "Dynamic Parameters" in a few tooltips and helper text (for example, `CreateWorkspacePageView.tsx` and `TemplateParametersPageView.tsx`). That's a product copy change and is better handled separately. ## Verification - `make gen/docs-manifest`, `make lint/docs-manifest`, `make lint/docs-redirects` (also with `-base origin/main`), `make lint/emdash`, `make lint/docs-html`: pass - `markdownlint-cli2` and `markdown-table-formatter --check` on changed docs: pass - Vale on the new pages: 0 errors, 0 warnings, 0 suggestions - `biome check` on the changed `site/` files: pass - A script compared every fenced code block in the old `parameters.md` and `dynamic-parameters.md` with the new pages: all 33 are present. - Relative links and anchors in all changed docs files resolve. The only failures are anchors that were already broken in `glossary.md` and `admin/templates/index.md`, which this PR doesn't touch. - Not done: a rendered preview on the docs site, and running the Storybook interaction test. This PR was drafted by Superblink (Coder's AI assistant) at the request of @stirby, who will review it and is accountable for it. --------- Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com> Co-authored-by: Nick Vigilante <nickvigilante@users.noreply.github.com> |
||
|
|
603dd420d1 |
feat: add ServerTailnet logs and metrics for unreachable agents (#30133)
Add default-level metrics and warn-level diagnostics to investigate ServerTailnet reachability failures causing agent-specific 502s, without restarting coderd or enabling debug logging. - Enrich request logs and PTY/chatd warnings with agent ID, failure reason, wait duration, coordinator state, WireGuard handshake and byte counts, and DERP regions. - Add metrics for unreachable attempts by reason, reachability latency, embedded DERP connections, and offline app/terminal requests. - Distinguish reachability failures from subsequent TCP dial failures, cap reverse proxy dials at one minute, and exclude expected chatd readiness polls and superseded-agent dials from unreachable counts. - Report missing handshakes as zero time instead of 1970, also fixing `coder ping`. Part of PLAT-680, a sub-issue of PLAT-360. |
||
|
|
1872b183ee |
docs(docs/admin): reformat setup and integrations docs to one sentence per line (#30704)
Reformats the setup and integrations docs under `docs/admin/setup` and `docs/admin/integrations` to one sentence per line, as the [docs style guide](https://github.com/coder/coder/blob/main/docs/.style/style-guide/formatting.md#one-sentence-per-line) requires. Hard-wrapped paragraphs are unwrapped and lines holding several sentences are split, so a later edit to one sentence shows up as a one-line diff. Apart from the exception below, only whitespace inside paragraphs and list items changes, and the rendered pages are the same. Comparing the changed files against `main` word for word, ignoring whitespace and blockquote `>` markers, finds differences only on the reworded lines. `git diff --word-diff` is easier to read than the line diff. 1 lines that already contained an em or en dash were reworded by hand, because `lint/emdash` treats every reflowed line as newly added. Each uses a parenthetical, a separate sentence, or a colon after a lead-in. Dashes on lines the reflow did not touch are left alone. Applied with an in-progress formatter, limited to pages listed in `docs/manifest.json` and excluding generated reference docs. This is one of a batch of PRs that split the docs by area (25 files changed, 380 insertions(+), 572 deletions(-)). --- 🤖 Built with AI assistance. |
||
|
|
2f2169ed19 |
fix: deduplicate template insights family metrics (#30497)
coderd_insights_applications_usage_seconds summed each family's per-app minutes, so a user with VS Code and Cursor open in the same minute was counted as two VS Code minutes. GetTemplateInsightsByTemplate now takes the registry's app-to-family mapping as jsonb, groups the raw agent stats by family, and counts each minute once per user and family. - Keep the metric's four built-in series (Visual Studio Code, JetBrains, Web Terminal, SSH) and their labels; only their values change. The HELP text now says built-in apps are grouped by family. - Add AppFamilyName.DisplayName() and remove the duplicate TemplateBuiltinAppDisplayName* constants from codersdk. The template insights handler returns the same display names. - Pin how the migration 000596 rollback approximates family minutes from per-app rows. Family values can drop wherever the old per-app sum double-counted overlapping apps. No migration or storage changes. |
||
|
|
261269aff0 |
fix: support path-aware OAuth discovery for remote MCP (#30168)
## Problem VS Code discovers Coder's MCP endpoint as a path-qualified OAuth resource, but Coder advertises the deployment root. Accepting MCP-bound tokens also requires keeping REST-backed tool calls within the originating MCP resource rather than granting those tokens direct REST access. ## Fix - Publish path-aware protected resource metadata and authentication challenges; keep authorization-server metadata at the root. - Validate the MCP audience and delegate tool requests through a private in-process transport that retains identity, scopes, expiry, revocation, and streaming cancellation. - Reject unsupported MCP path aliases and validate SDK path components before URL resolution. - Add discovery, audience, authorization, endpoint-isolation, and transport lifecycle regression tests and update integration docs. ## Validation VS Code completed OAuth and returned the authenticated user through a real MCP tool. Official MCP SDK 1.30.1 completed discovery, registration, PKCE, tool execution, and refresh. These live checks preceded the final path hardening; the hardened paths are covered by automated regressions. Affected Go package tests, targeted race tests, backend/SDK lint, and targeted documentation checks passed during self-review. The exact PR commit was also checked separately from the uncommitted consent-scope fix. > [!NOTE] > Tokens are MCP-audience-bound, but grants still include `coder:all`; least-privilege scopes remain a separate requirement ([PLAT-639](https://linear.app/codercom/issue/PLAT-639)). Preview: https://coder.com/docs/@fix/mcp-internal-delegation/ai-coder/mcp-server <details> <summary>Implementation decisions and review context</summary> 1. Treat `/api/experimental/mcp/http` and its single-trailing-slash form as supported MCP resource paths; reject other aliases and descendants before route authentication. 2. Preserve deployment-root discovery and authorization-server metadata for existing REST integrations. 3. Bind private delegation to the authenticated API-key ID. Revalidate the original credential and enforce normal RBAC/scopes on every internal REST request; do not derive delegation from HTTP headers. 4. Keep internal HTTP, streaming, and WebSocket traffic in-process with no network fallback. Close the transport on outer-request cancellation and normal completion. 5. Validate workspace owner/name path segments before SDK URL construction, including tool-level tests that malformed arguments cannot select a different REST endpoint. 6. Keep compatibility and delegated tool execution together: discovery-only changes would allow authentication while leaving real MCP tool calls broken. </details> > 🤖 This PR was created with the help of Coder Agents, and needs a human review. 🧑💻 |
||
|
|
fc01bee831 |
fix: keep new API keys within the caller's scopes and allow list (#30256)
A scoped key holding api_key:create could mint a broader key, e.g. a token scoped to [api_key:create user:read] could mint coder:all.
- New keys must be covered by the caller's scopes and allow list, and inherit them when none are requested
- Requests beyond the caller return 403
- New key expiry is capped at the caller's
- Covers POST /users/{user}/keys/tokens, POST /users/{user}/keys, app auth-redirect, and /oauth2/authorize (invalid_scope on excess grants or a restricted session allow list)
- coder:all sessions, including browser logins, behave as before
- Not addressed: workspace start still mints a coder:all key for the owner
|
||
|
|
149366a459 |
feat: validate documented experiment keys (DOCS-139) (#29316)
## Summary
The docs name specific experiment keys wherever an individual
experimental feature is documented, and nothing verifies those keys
still exist in the code.
When an experiment is renamed or graduated, the enablement example keeps
telling operators to set a key the server no longer accepts.
This adds `scripts/checkexperimentkeys`, which fails when a key named in
`docs/**` is absent from `codersdk.ExperimentsKnown`, and wires it into
`make lint` as `lint/check-experiment-keys`.
**The data flows one way.**
The check reads keys the docs already name and validates them against
code.
It does not generate a page, add a manifest route, or write any key into
`docs/`.
That is deliberate: #29113 retired the generated feature-stage lists
because the team decided not to advertise which features are currently
experimental or beta.
A guard against stale keys is compatible with that decision; an index is
not.
The five key references the check currently guards are the per-feature
ones that decision left in place: `chat-advisor`,
`chat-virtual-desktop`, `auto-fill-parameters`, `agent-lifecycle-hooks`,
and `mcp-server-http`.
### Recognition rules
Only explicit enablement forms are matched: `--experiments=<key-list>`
and `CODER_EXPERIMENTS=<key-list>`, including every key in a
comma-separated list.
Values may be single- or double-quoted.
Explicit shell line continuations are joined before matching, preserving
the first physical line for a finding.
Bare identifiers in prose are ignored on purpose.
A check that guesses at prose produces false positives, and a check with
false positives gets deleted by the first person it blocks.
`*`, `feature1`, `feature2`, and angle-bracketed values are recognized
placeholders.
The recognized forms are documented in the script's README.
Known gap: the space-separated `--experiments <key>` form is not
matched.
No prose uses it today, so this is latent rather than broken, and
closing it is a small follow-up if the form reappears.
### Also fixed
`ExperimentMCPToolSearch` had no case in `DisplayName()`, so it rendered
as a title-cased guess in the product UI as well as anywhere else
display names surface.
`TestExperimentDisplayNames` now pins the display name of every known
experiment against an expected map, with a length assertion, so a new
experiment cannot silently fall back to the title-cased key.
## Verification
- `go test ./scripts/checkexperimentkeys ./codersdk` passes.
Coverage includes known and unknown keys, quoted values, shell
continuations, placeholders, multi-key lists, bare-prose exclusion, and
failure-output formatting.
- `golangci-lint run ./scripts/checkexperimentkeys/... ./codersdk/...`
reports 0 issues.
- `make lint/check-experiment-keys` is clean against current `docs/`.
- Negative control: a fixture containing
`CODER_EXPERIMENTS=not-a-real-key` exits 1 with the expected finding.
- The full `pre-commit` hook passes, including
`lint/check-experiment-keys` inside aggregate `make lint`.
<details>
<summary>History: the deferred lint wiring, now resolved</summary>
This PR previously landed the tool and a standalone `make` target while
leaving the one-line addition to aggregate `make lint` for a follow-up,
and stayed draft, because three documented `oauth2` keys were stale and
owned by another PR:
- `docs/admin/integrations/oauth2-provider.md:34`
- `docs/ai-coder/mcp-server.md:108`
- `docs/ai-coder/mcp-server.md:114`
#29268 merged on 2026-09-15 and removed all three in favor of
`CODER_OAUTH2_PROVIDER_ENABLE`.
The branch is rebased onto that, the check is green against `main`, the
wiring is folded into this PR, and the merge-order constraint recorded
as CRF-5 no longer applies.
The rebase also collided with `DisplayName()`, which gained new cases on
`main`.
Resolved in favor of `main`'s switch rather than this branch's earlier
map refactor, keeping the production diff to the one missing case and
moving the exhaustiveness expectations into the test.
</details>
<details>
<summary>Why this replaced a generated reference page</summary>
DOCS-139 originally asked for a generated
`docs/reference/experiments.md` listing every key in `ExperimentsKnown`.
That was built and opened as #29311, then closed without merging.
Commit
|
||
|
|
72e31ffb4c |
fix: prevent Prometheus metrics reference drift (#29314)
## Summary The Prometheus metrics reference merged scanner output with a hand-maintained file, and changes to the hand-maintained half could not fail CI. 66 of the 76 static families had no scanner coverage: four files sat in a skip list pending `WrapRegistererWithPrefix` support, and the `aibridge/` tree was outside the scan roots entirely. Rename or add a metric in any of them and `make gen` regenerated the page unchanged, so `check_unstaged.sh` passed while the published table quietly went wrong. The scanner now resolves the prefixes a registerer applies: - Indexes `WrapRegistererWithPrefix` and `NewMetricAliasRegisterer` call sites, resolving the prefix from a string literal or an imported constant. - Maps that prefix to the package whose constructor receives the wrapped registerer, covering the two shapes the codebase uses: a constructor that **forwards** its registerer to another package (`aibridge.NewMetrics` to `aibridge/metrics.NewMetrics`), and a collector **registered directly** against the wrapped registerer (`gatewayRegisterer.MustRegister(keypool.NewStateCollector(...))`). - Indexes only the canonical prefix of an alias registerer. The legacy `coder_aibridged_` and `coder_aibridgeproxyd_` aliases are deprecated per AIGOV-447 and should not be taught in the reference. With prefixes resolved: skip list deleted, `aibridge` added to the scan roots, and all 29 `coder_ai_gateway_*` families removed from the static file, which now holds only genuine externals (`go_*`, `process_*`, and metrics built dynamically). `enterprise/scaletest/agentfake` is excluded deliberately: its fake-agent metrics are not part of a deployment's surface, so documenting them would send operators looking for series they will never see. **Also fixes two extraction and merge gaps.** Label lists written as `append(baseLabels, "status", "route")` now resolve, and any unresolvable element returns no labels rather than a partial list. Static runtime-label overrides now replace generated labels only: generated name, type, and HELP remain authoritative. ## Verification The prefix-scanning refactor itself preserves the existing AI Gateway rows. However, the page is **not byte-identical** to `main` because this round fixes two already-published stale HELP strings. Its SHA-256 changes from `7ced1e7e9f2d4caf5e3b5e484ef4af14f955b8b4cd1a14fe81360bbdd49bb150` to `a68774275a3b21d5bae65024cc8ee65b52c51e52786c9aea45e3981e4e7f1643`. | Metric | Before | After | | --- | --- | --- | | `coderd_agentstats_connection_median_latency_seconds` | The median agent connection latency | The median agent connection latency in seconds | | `coderd_agentstats_startup_script_seconds` | The number of seconds the startup script took to execute. | Amount of time taken to run the startup script in seconds. | - `go test ./scripts/metricsdocgen/...` covers prefix resolution from a literal and imported constant, alias-registerer argument selection, collector registration, forwarder propagation, scan-to-emit prefix application, all-or-nothing label extraction, static-label merging, and the exclusion predicate. - `golangci-lint run ./scripts/metricsdocgen/...` and full `make pre-commit` pass. ## What this does not fix Ten metrics are still skipped for having no `HELP` text, with a warning to stderr rather than an error. Making that fatal means writing accurate descriptions for ten metrics in the agent and SSH server packages, which is a behavioral claim I would rather not guess at. Follow-up filed as DOCS-906. The scanner still uses package-level syntactic prefix inference. Broader validation of prefix scan roots, mixed registration within a package, and parameter-passed registerers belongs in DOCS-908 rather than this focused drift fix. <details> <summary>Local pre-push note</summary> The pre-push hook cannot run in this workspace: GNU Make 4.4.1 segfaults on the repo's `.SHELLFLAGS = $@ -ceu` configuration for a target named `test`, tracked in DOCS-903 with a minimal reproduction. I verified with the package tests, `golangci-lint`, and full pre-commit, and disabled the hook for this worktree only through its documented `git config coder.pre-push` knob, restoring it right after the push. No `--no-verify`. </details> --- Generated with Coder Agents on behalf of @nickvigilante. Linear: [DOCS-897](https://linear.app/codercom/issue/DOCS-897/metricsdocgen-static-metrics-file-can-go-stale-without-failing-ci) |
||
|
|
1fd383e4fd |
docs: flatten lone index pages to single files (#30129)
The beta docs engine turns a directory that holds only an `index.md` into an empty collapsible section in the sidebar. Two pages on `main` have that shape: `docs/admin/external-auth/index.md` and `docs/ai-coder/agents/tools/index.md`. docs-engine is handling the shape in its own code (the sidebar render fix in https://github.com/coder/docs-engine/pull/196 and the sync-side handling in https://github.com/coder/docs-engine/pull/195), and this change removes it at the source by moving each page to a flat file: `docs/admin/external-auth.md` and `docs/ai-coder/agents/tools.md`. Both directories held only `index.md`, with no images or other files. The change updates the two `docs/manifest.json` paths, 29 inbound relative links across 17 pages, and the relative links inside the moved pages (three images and two page links in `external-auth.md`, one page link in `tools.md`), which now resolve one directory up. The ESR upgrade table in `docs/install/operate/upgrade/esr-2.29-2.34-upgrade.md` is re-padded because its link cells shrank, which is why that file shows 28 changed lines. No generator under `scripts/`, the docs-preview workflow, or `docs/.style` references either path. Published URLs stay the same, so no redirect is needed. coder.com's `convertPathToRoute` strips the `index.md` or `.md` suffix, the docs-preview workflow's `map_doc_path` maps `<dir>/index.md` and `<dir>.md` to the same route, and docs-engine's `mapMdPath` returns `admin/external-auth` and `ai-coder/agents/tools` for both the old and new paths. For verification, `docs/manifest.json` parses and all 471 of its paths exist. `make pre-commit-light` passes, which covers markdownlint, the table formatter, typos, emdash, and shellcheck, and `go run ./scripts/docshtmlcheck` passes. A local script resolved all 306 relative links in the changed files, and every one that the move touched points at an existing file and heading. linkspector runs on this PR in CI. A backport PR for `release/2.37` moves the same two pages plus `admin/licensing` and `install/other`: https://github.com/coder/coder/pull/30130. This change was prepared with AI assistance. The AI agent that prepared it ran the checks described above. --- 🤖 Built with AI assistance. |
||
|
|
fc0af7fbd8 |
feat: open a chat_turn span per prompt (#29771)
**TL;DR:** Wraps each prompt in a `chat_turn` root span with every lifecycle stage parented under it. The span records one outcome per turn (`completed`, `interrupted`, `error`, `abandoned`), and the new `coderd_chatd_turn_outcomes_total` counter counts those outcomes. Turns stay correct when tasks are canceled, replaced, or retried. Each prompt runs inside a `chat_turn` root span owned by the runner (`runnerTurnSpan`). The generation step, prepare, MCP connect, stream, TTFT, provider attempt, commit, thinking, tool call, compaction, and retry backoff stages are parented under it, activating the stages from #29770. `chat_turn` spans are standalone roots: the turn runs on a worker, often on another replica, and no trace context is persisted. **Lifecycle** - **Start.** Each generation loop iteration calls `Ensure`, which opens the turn if none is open and returns a `turnToken`. The span is backdated to the trigger: the latest of the last user prompt, a dynamic tool's result message after it, and a pending compaction request. An `acquisition` stage covers trigger to pickup. - **Stale trigger / takeover.** A trigger at or before the previous anchor opens the turn at now with no `acquisition` and counts `stale_anchor`. A runner that took the chat over from an owner with a stale heartbeat (`TakenOver`, from acquisition) opens its first turn at now with no `acquisition`, so the dead owner's run is not reported as pickup delay. - **Newer prompt.** `Ensure` on the current turn with a newer trigger closes it and opens a new one. The closed turn is `abandoned` unless the task that ran it records an outcome before releasing it. - **Finish.** After `FinishTurn` or `EnterRequiresAction` commits, the step calls `Complete`; `Settle` closes the span after the step's own stage ends, so the finishing step is inside the turn. A chat waiting in `requires_action` is outside any turn; the generation resumed by its tool results opens a new one. - **Emission.** Closing a turn fixes its end time; its span is emitted once every task that joined it (`Ensure` takes the task ID) has called `Release`, which `runTask` does after the task returns. A finishing task whose `FinishTurn` promoted a queued prompt therefore still counts its turn as `completed` even when the promoted task's `Ensure` runs before its `Complete`. `End` at runner exit emits whatever is left. - **Failure.** A step that commits `FinishError`, or fails closed, invalidates the turn as `error` after the commit. Errors the task runner retries, including task timeouts, keep the same turn open; an expected, non-retryable exit records no outcome and leaves the turn open until the interrupt task, a newer prompt, or runner exit closes it. A canceled generation task records no outcome and cannot obtain a turn token, so a replaced task never touches its successor's turn. - **Interrupt.** The interrupt task marks the open turn `interrupted` before `FinishInterruption` commits and closes it after. Only a stop (by the user or a parent agent) is `interrupted`; it ends with unset span status, since error status is reserved for `error` turns. runner shutdown, loss of ownership, and message edits close the turn as `abandoned` with unset status. - **Promotion.** Every promoting transition (`FinishTurn`, `FinishInterruption`, a send to an errored chat, `PromoteQueued`) returns the promoted message's queued time in its result, and one `recordQueueWait` helper records a standalone `queue_wait` to the promotion. The promoted turn opens at the promotion time. `chat_turn` is observed on `coderd_chatd_stage_duration_seconds` only for completed turns, so the histogram is completed-turn latency; every turn still emits its span. `coderd_chatd_turn_outcomes_total{outcome, chat_kind}` counts every closed turn exactly once (`completed`, `interrupted`, `error`, `abandoned`), matching the span's `turn_outcome`, under the `chat-stage-metrics` experiment. Turn time accounting is in draft #29772. **Stages and identity** - `tool_call` is a live stage around each local tool call in `chatloop`; the tool runs on its context, and it ends errored only when the tool fails to execute. Calls that never run (inactive, unknown, or rejected by policy) record no stage. - `mcp_connect` carries connected and failed server counts and ends errored only when servers were configured and none connected. - The compaction stage carries the model that runs the summary. - `withStageIdentity` puts scope and chat kind on the turn context. Detached background work runs in `background` scope as its own trace roots. - The `advisor` tool's nested model call appears only as its enclosing `tool_call`. ARCHITECTURE.md gains a "Lifecycle tracing" section. <details> <summary>Review decisions</summary> - Turn identity stays timestamp-based with targeted fixes (clamped acquisition, rotation on a newer trigger, invalidate after commit, fail-closed invalidation, settle closing invalidated turns) plus a takeover flag; keying turns on message IDs would not detect takeover and cannot express interrupted/abandoned outcomes. - Outcome classification: the interrupt task owns `interrupted`, and cancellation or a fence mismatch alone never records an outcome, so shutdown, ownership loss, and edits are `abandoned`. Only `error` turns set error span status. Remaining ordering races between a step and an interrupt are documented as known limitations in ARCHITECTURE.md. - Turns are emitted after the tasks that ran them return, not when they close, so an outcome a replaced task records while unwinding reaches its own turn; the successor task is not delayed. Chosen over an after-commit, pre-publish hook on `ChatMachine.Update`, which would fix only the `FinishTurn` ordering. - `requires_action` ends the turn rather than pausing it, so `chat_turn` measures chatd time; a prompt with client tools counts as several turns. - Promoted turns anchor at promotion time and `queue_wait` is always standalone, so `chat_turn` never includes time spent queued behind another turn. - The former `capacity_wait` stage (#29805) was dropped: it was a per-worker lower bound, excluded from accounting, and needed its own SQL and bookkeeping. #29805's remaining helpers are folded into this PR. </details> Supersedes #28972, #28973, and #29805. 🤖 This PR was generated by Coder Agents on behalf of @jscottmiller. |
||
|
|
e988ddb11d |
feat: trace chatd provider stages and count only output parts as first token (#29770)
**TL;DR:** Traces the model provider call: a `stream` stage, a nested `time_to_first_token` stage, and one `provider_attempt` per HTTP round trip, labelled with provider type and model. Behavior change: `coderd_chatd_ttft_seconds` now counts only a real output part as the first token, so error, warning, and finish parts no longer count. Instruments the provider call. **Stream and time to first token.** `GenerateAssistant` records a `stream` stage from stream open to close and a nested `time_to_first_token` stage. The TTFT window closes once, on the first streamed output part: any part other than warnings, finish, or error, including start markers such as `text_start`. A closed window observes the stage and the pre-existing `coderd_chatd_ttft_seconds` with the same elapsed time. A failed open, an error part, or a release without an output part ends the TTFT span with the error (a silence timeout is classified as such) and observes nothing. The `stream` span ends once, with the error `GenerateAssistant` returns, so content-filter and no-output attempts end errored. Failed `stream` windows are observed like successful ones. The attempt is released before the stream span ends, so the TTFT window always falls inside its stream. The compaction summary stream passes a nil tracer, so it records neither. Without #29771, production emits only `provider_attempt`; #29771 passes the tracer to `GenerateAssistant`. **Provider attempts.** The provider HTTP transport is wrapped in `stageSpanRoundTripper`, which emits one `provider_attempt` stage per round trip, so retries each get a span. The span closes on response headers; a status >= 400 marks it errored without changing what the client sees. `resolveModelCall` resolves the `StageModel` (wire provider, configured `provider_type`, model, effective reasoning effort) and threads it to the transport, so span attributes and labels match the call. `provider_type` is read from `ai_providers.type`, so types outside the fantasy set (copilot) keep their configured name. `chatd.New` builds the tracer with the server clock. **Behavior change to `coderd_chatd_ttft_seconds`:** only an output part counts as a first token. Error parts no longer close the window as a success, and warnings and finish parts are skipped; the help text says so. `StageSpan.End` returns the span's elapsed window, which `ttft_seconds` observes. Callers pass `Stages` and `StageModel` through `GenerateAssistantOptions`; a nil tracer discards (TTFT still records `ttft_seconds`). `Server` gains the `stages` tracer and a `TracerProvider` option, wired from `coderd`. <details> <summary>Review decisions</summary> - Start markers close the TTFT window: they are the first sign the model is producing output, and waiting for a delta would fold hidden reasoning time into TTFT. - Failed `stream` and `provider_attempt` windows are observed: that time was spent. TTFT is the exception because a first token that never arrived has no duration. - `http_host` was dropped from `provider_attempt`; every request goes through the local AI Gateway transport, so it was constant. - The advisor tool's nested model call is intentionally not instrumented as `stream`/TTFT. </details> Supersedes #28970 and #28971. 🤖 This PR was generated by Coder Agents on behalf of @jscottmiller. |
||
|
|
7a9442014e |
feat: add chatd lifecycle stage tracer (#29769)
**TL;DR:** Adds a stage tracer that turns each chat lifecycle stage into
both an OpenTelemetry span and a Prometheus histogram observation, so
traces and metrics always agree. The metrics are only registered with
the `chat-stage-metrics` experiment. Nothing calls the tracer until the
next PRs.
Adds `chatloop.StageTracer`, which emits each chat lifecycle stage as an
OpenTelemetry span and a `coderd_chatd_stage_duration_seconds{stage,
scope, chat_kind}` observation from one `End` call, so trace and metric
durations cannot disagree. The provider-bound stages (`stream`,
`provider_attempt`) are also observed on
`coderd_chatd_model_stage_duration_seconds{stage, provider_type,
chat_kind, model}`, the only family carrying `provider_type` and
`model`, and only for turn-scoped stages. Time to first token per model
stays on the existing `coderd_chatd_ttft_seconds`. Nothing calls the
tracer yet; the next PRs instrument the provider call and the runner.
- The families are registered only when the `chat-stage-metrics`
experiment is enabled (safe and known, so
`--experiments=chat-stage-metrics` or `--experiments=*` turns it on).
Spans are emitted regardless. `NewMetrics` leaves the families off;
`chatd.New` opts in from the experiment, and a test asserts the
experiment decides whether they reach the server's registry.
- `Stage`, `Scope`, `ChatKind`, and `StageAnomaly` are typed string
constants. `scope` separates latency attributable to a prompt (`turn`)
from detached `background` work; `chat_kind` is `root` or `subagent`,
empty without a known chat.
- `StageModel` carries the wire `provider`, `provider_type`, `model`,
and `reasoning_effort`. All are span attributes; only `provider_type`
and `model` are metric labels, on the model family. No family carries an
organization label.
- Observed stages: `chat_turn`, `queue_wait`, `acquisition`,
`mcp_connect`, `stream`, `time_to_first_token`, `provider_attempt`,
`tool_call`, `commit`, `retry_backoff`. `generation_step`, `prepare`,
`thinking`, and `compaction` are span-only. A test keeps the stage sets
and help text consistent.
- API: `Start` / `StartRootAt` for live spans (span timestamps come from
the tracer clock), `Record` for stages reconstructed from timestamps
(the scope comes from the context). `End` is idempotent;
`EndWithoutObservation` ends the span without a sample. A nil tracer,
provider, or metrics discards.
- `coderd_chatd_stage_anomalies_total{reason}` counts observations
dropped, adjusted, or inconsistent (`negative_elapsed`,
`inverted_window`, `missing_timestamp`, `future_start`, `stale_anchor`).
Span-only stages never feed it.
- Buckets are 12 round edges (`0.1 0.25 0.5 1 2.5 5 10 30 60 300 1800
3600`).
- Moves the body of the `for` loop in `StartGeneration` into
`runGenerationStep` so the step has a function boundary for a deferred
stage end. Control flow and error wrapping are unchanged.
<details>
<summary>Series cost (approximate, whole stack)</summary>
A histogram label set is 12 edges + `+Inf` + `_sum` + `_count`: 15
series. Per replica, each `chat_kind` costs about 150 stage series and 4
turn outcome counters; each `(chat_kind, model)` costs 30 (2 stages x
15). Both chat kinds on `M` models: about `308 + 60*M` per replica, plus
background-scope stage series.
Dogfood `main`, 3 replicas: ~3.4k `coderd_*` series per replica (~10.1k
total).
| Models used per replica | Added series (3 replicas) | vs. baseline |
|---:|---:|---:|
| 1 | ~1.1k | +11% |
| 5 | ~1.8k | +18% |
| 10 | ~2.7k | +27% |
| 35 | ~7.2k | +72% |
Most deployments run four or fewer models, so a typical replica adds
roughly 370 to 550 series. The experimental turn accounting in #29772
would add 88 more per replica (11 categories x 4 outcomes x 2 chat
kinds). Series appear lazily and do not grow with organizations.
</details>
<details>
<summary>Review decisions</summary>
- Experiment gate only; no deployment flag or metric levels. If the
experiment graduates, the families become always on like the other chatd
families; a flag is added then only if dogfood shows a cardinality
problem.
- Organization is on neither metrics nor spans, and `effort` is
span-only; `provider_type` (configured type), not the wire `provider`,
is the model-family label.
- `time_to_first_token` is not on the model family; per-model TTFT is
`ttft_seconds`, which observes the same measured window.
- The model family records only turn-scoped stages.
- Nil guards are kept so a nil or zero tracer is always safe to call.
- HTTP attribute keys stay snake_case like the rest of the chatd span
attributes.
</details>
Supersedes #28968 and #28969.
🤖 This PR was generated by Coder Agents on behalf of @jscottmiller.
|
||
|
|
4a62b0fc9c |
docs: add YAML front matter to remaining pages (#30115)
## Summary Add YAML front matter to the remaining published documentation pages so all published pages expose a title through front matter. ## Changes - Add front matter to the 13 published pages that were missing it. - Preserve the page titles and feature states in the manifest. - Remove duplicate H1 headings where the front matter supplies the page title. ## Testing - `pnpm check-docs` passed. - Repository pre-commit checks passed. - Verified all 439 published manifest route entries have YAML front matter. Depends on #30109. Refs DOCS-1124. This pull request was generated by Coder Agents. |
||
|
|
34db9ca638 |
feat: price AI Gateway token usage by provider model (#30090)
## Description When the requested model has no price, price AI Gateway token usage by the model the provider reports instead of leaving it unpriced. This covers providers that resolve an alias to a specific model, such as `codex-auto-review` served as `gpt-5.6-luna`. Stacked on #30086, which records the provider model. Closes https://linear.app/codercom/issue/AIGOV-650 ## Changes - Look up the price for the requested model first, then the provider model, preferring a custom price over the price book for each model. - Store the provider model and the model used for pricing (`priced_model`) on each token usage. - Add a `provider_model` label to `unpriced_token_usage_records_total`. - Document the lookup order and the new metric label. > [!NOTE] > Generated by Claude Code on behalf of @ssncferreira. |
||
|
|
d40e24cf7d |
docs: nest the CLI reference by subcommand (#29956)
## Summary Nests the CLI reference by subcommand so the Command Line sidebar collapses from 156 flat entries to 49 top-level verbs. Each page's URL follows the invocation, its page title is the full command as inline code, and its sidebar label is only its own verb as inline code. | | Before | After | | --- | --- | --- | | File | `docs/reference/cli/oauth2-provider_dcr_disable.md` | `docs/reference/cli/oauth2-provider/dcr/disable.md` | | URL | `/reference/cli/oauth2-provider_dcr_disable` | `/reference/cli/oauth2-provider/dcr/disable` | | Page title (front matter) | `oauth2-provider dcr disable` | `` `coder oauth2-provider dcr disable` `` | | Sidebar label (manifest) | `oauth2-provider dcr disable` | `` `disable` `` | Resolves DOCS-140 (coder/coder half). Also fixes the Makefile part of DOCS-1073 / DOCS-912, which this change depends on. ## Changes - `scripts/clidocgen`: pages nest by command path. A command with visible subcommands becomes its directory's `index.md`, so `oauth2-provider/index.md` and `oauth2-provider/dcr/index.md` sit above `oauth2-provider/dcr/disable.md`. Subcommand table links are relative to the parent page. - `scripts/clidocgen`: the manifest "Command Line" section is built from the command tree (nested, sorted by name, hidden commands skipped) instead of a flat list. The redundant `coder` child that pointed back at `reference/cli/index.md` is gone. - `Makefile`: the CLI rule now replaces `docs/reference/cli/` wholesale, so stale pages get removed. The manifest rule now runs `clidocgen -manifest-only` on top of the API staging manifest, so the CLI nav is generated instead of edited by hand. As a result, the nine pages that had no nav entry (`ai-gateway*`, `secret enable/disable`, `server fix-oidc-links`) now have one. - `scripts/configdocgen` and 48 prose pages: links point at the new paths (for example `reference/cli/server.md` is now `reference/cli/server/index.md`). ## How to review/QA this PR - `docs/reference/cli/**/*` (approximately 190 pages): Each of these pages are generated automatically. Some pages appear deleted, and some pages appear new. Every deleted page corresponds to a new page somewhere else, so no information is being deleted. The docs in this section should adhere to the following, so a test in the build preview for each of these items should be satisfactory: - [ ] Each subcommand of a command gets nested as a child instead of being displayed as a flat list. - [ ] Each parent command is stored in an `index.md` file. - [ ] The title of each page inside the page should now feature the full `coder XYZ` command. - [ ] The title of each page inside the page should now be formatted as inline code. - [ ] The title of each page in the sidebar should be the most granular subcommand of the whole command string (if the page's title is `coder ai-gateway keys create`, the sidebar label is `create`). - [ ] The title of each page in the sidebar should now be formatted as inline code. - [ ] The page slug for each page is now the most granular subcommand. - [ ] All links now point to the correct page. - `docs/manifest.json`: The changes here reflect the updated structure of the `docs/reference/cli` section. - `docs/**/*.md` outside of `docs/reference/cli/**/*` (approximately 50 pages): The extent of the changes in these pages are just updating the paths to point to the new page locations. - [ ] The links on the page all point to the correct new path in `docs/reference/cli`. - `scripts/clidocgen` (4 files): This is the Go code responsible for generating everything inside of `docs/reference/cli/**/*`. A typical code review here should be satisfactory. - `scripts/configdocgen` (2 files): these two files just have updates to the raw `.md` path used by `docs/admin/setup/configuration-reference.md` and updates the tests to reflect that. - `Makefile`: This updates the `make` targets for generating the CLI docs to fit the new structure. ## Merge ordering Without the renderer PRs deployed, both docs sites show literal backticks in titles and sidebar labels. Without the redirects, the old flat URLs return 404. 1. Deploy before merging this PR: coder/docs-engine#176 (beta-docs renders these titles as inline code) and coder/coder.com#1111 (classic docs renders them as inline code). Both are safe to ship first, because titles without backticks render as before. 2. Merge this PR. 3. Merge coder/coder.com#1112 (redirects from the old flat URLs) only once this content reaches the mainline release branch that serves unversioned `/docs`. ## Testing - `go test ./scripts/clidocgen/ ./scripts/configdocgen/ ./scripts/docshtmlcheck/`: pass. New tests cover page paths, subcommand links, the nested manifest, and front matter quoting. - `make docs/reference/cli/index.md docs/manifest.json docs/admin/setup/configuration-reference.md`, then a forced rerun: the second run produced no diff. - Checked the manifest: all 164 CLI entries resolve to a file, no page is missing a nav entry, and everything outside "Command Line" is byte-identical. - Relative `.md` links across `docs/`: 0 broken, same as `main`. - `make pre-commit` and `make pre-push`: pass. On earlier pre-push attempts, different unrelated vitest files timed out under host load. Those files pass when run alone, and the final push passed with `PARALLEL_JOBS=1`. <details> <summary>Implementation plan and decision log</summary> **Goal (from DOCS-140 and the requester):** URLs follow the command hierarchy. Pages are titled with the full command, and sidebar entries with the last verb only. Both are formatted as inline code. **Contract with the renderers:** a title wrapped entirely in one pair of backticks (``^`[^`]+`$``) renders as inline code. Plain-text consumers (`<title>`, meta, search, llms corpus) strip the backticks. Page title comes from front matter `title`, and the sidebar label from the manifest node `title`. **Decisions** - A parent command is `dir/index.md` rather than a sibling `dir.md`. The root CLI page is already `index.md`, and both docs-engine and the legacy coder.com renderer map `x/index.md` to `/x`. - The manifest is built from the command tree, not from the written files, so ordering is deterministic and the nesting matches the pages exactly. - The manifest discard bug (DOCS-1073 item 1) is fixed here, because without that fix the generated nested manifest would never reach the tree. DOCS-1073 items 2 through 4 (a prose fix and a hidden-command policy) are out of scope. - `-manifest-only` keeps the existing parallel `make gen` layout: the API rule still owns `_gen/manifest-staging.json`, and CLI regeneration doesn't retrigger swag. - The renderer and redirect work lives in the companion PRs in coder/docs-engine and coder/coder.com. It is linked above and not duplicated here. </details> --- > [!NOTE] > Generated by Coder Agents on behalf of @nickvigilante. |
||
|
|
631fe09e11 |
fix: narrow OAuth2 client registration scope to the catalog (#29952)
fix: filter unsupported scopes in OAuth2 dynamic client registration - Filter scopes against the external catalog during registration and RFC 7592 updates, storing and returning only supported names. - Reject non-empty lists with no supported scopes using `400 invalid_client_metadata` to avoid creating unrestricted allowlists. - Preserve legacy scope lists when resent unchanged; leave existing records and the admin app API unchanged. - Add filtering tests and verify stored scopes in registration tests. Not a security fix: authorization already rejects unsupported scopes. Closes PLAT-674. |
||
|
|
d43dd98baf |
docs: rewrite gerund-leading headings and page titles (#30049)
Rewrites the headings and page titles that `Coder.GerundHeading` flags as gerund-leading, using the imperative for tasks and the noun form for concepts. This PR covers only changes that don't rename a page slug. ## Changes - Rewrites 121 in-page headings, bringing `Coder.GerundHeading` findings in `docs/` to zero. - Adds an empty `<a id="old-slug"></a>` above each renamed heading, so existing bookmarks and inbound deep links still land on the section. The legacy IDs were computed with the same slugger the classic renderer uses (`rehype-slug`), and all 115 that exist on production today match the live `id` attributes; the other 6 are on pages not published yet. - Updates the 18 in-docs links that targeted old anchors to use the new slugs, and the link text that quoted the old heading. - De-gerunds seven page titles (frontmatter and `manifest.json`) whose slugs don't change, for example `Upgrading Best Practices` to `Upgrade best practices`. - Scopes a Vale exception around the glossary term `Coding agent`, where "Coding" is an adjective. ## Not in this PR - **Pages with gerund slugs** (`creating-templates`, `getting-started`, `working-with-dev-containers`, `cloning-git-repositories`, `configuring-okta`, and others) keep their current titles, so the title and slug change together in the slug-rename PR. The redirects for those renames come in a third PR. - **Links outside `docs/`** to old anchors (Go notification strings, an applied SQL migration, golden files, and the generated `prometheus.md`) still target old slugs. They keep working through the legacy anchors, and updating them would need code changes. ## Known limitation `coder/docs-engine` prefixes raw-HTML `id` attributes with `user-content-` (DOM-clobbering protection), and inbound deep links aren't rewritten. Once the docs move to docs-engine, these legacy anchors resolve only as `#user-content-<old-slug>` unless docs-engine adds a fragment fallback. They work on the current coder.com renderer and on GitHub. ## Testing - `vale --filter='.Name=="Coder.GerundHeading"' docs`: zero findings, down from 122. - `make lint/markdown`, `make lint/docs-html`, `make lint/emdash`, and the pre-commit hook: all pass. - Scripted check that every relative `#fragment` link into a changed file resolves to a heading slug or a legacy anchor (177 links). - Scripted check that no legacy ID collides with a heading slug on the same page, and that no untouched heading's duplicate-suffix slug shifted. <details> <summary>Heading renames and legacy anchors (121)</summary> | File | Old heading | New heading | Legacy anchor | | --- | --- | --- | --- | | `admin/integrations/opentofu.md` | Using a custom Terraform binary | Use a custom Terraform binary | `#using-a-custom-terraform-binary` | | `admin/monitoring/connection-logs.md` | Capturing/Exporting Connection Logs | Capture and export connection logs | `#capturingexporting-connection-logs` | | `admin/monitoring/metrics.md` | Setting up metrics | Set up metrics | `#setting-up-metrics` | | `admin/networking/port-forwarding.md` | Accessing workspace ports | Access workspace ports | `#accessing-workspace-ports` | | `admin/networking/port-forwarding.md` | Sharing ports | Share ports | `#sharing-ports` | | `admin/networking/port-forwarding.md` | Configuring port protocol | Configure port protocol | `#configuring-port-protocol` | | `admin/networking/workspace-proxies.md` | Running on Kubernetes | Run on Kubernetes | `#running-on-kubernetes` | | `admin/networking/workspace-proxies.md` | Running on a VM | Run on a VM | `#running-on-a-vm` | | `admin/networking/workspace-proxies.md` | Running as a system service | Run as a system service | `#running-as-a-system-service` | | `admin/networking/workspace-proxies.md` | Running in Docker | Run in Docker | `#running-in-docker` | | `admin/networking/workspace-proxies.md` | Selecting a proxy | Select a proxy | `#selecting-a-proxy` | | `admin/security/audit-logs.md` | Capturing/Exporting Audit Logs | Capture and export audit logs | `#capturingexporting-audit-logs` | | `admin/security/audit-logs.md` | Purging Old Audit Logs | Purge old audit logs | `#purging-old-audit-logs` | | `admin/security/database-encryption.md` | Enabling encryption | Turn on encryption | `#enabling-encryption` | | `admin/security/database-encryption.md` | Rotating keys | Rotate keys | `#rotating-keys` | | `admin/security/database-encryption.md` | Disabling encryption | Turn off encryption | `#disabling-encryption` | | `admin/security/database-encryption.md` | Deleting Encrypted Data | Delete encrypted data | `#deleting-encrypted-data` | | `admin/security/secrets.md` | Displaying Secrets | Display secrets | `#displaying-secrets` | | `admin/setup/data-retention.md` | Keeping Data Indefinitely | Keep data indefinitely | `#keeping-data-indefinitely` | | `admin/setup/index.md` | Migrating from the built-in database to an external database | Migrate from the built-in database to an external database | `#migrating-from-the-built-in-database-to-an-external-database` | | `admin/setup/index.md` | Configuring Coder behind a proxy | Configure Coder behind a proxy | `#configuring-coder-behind-a-proxy` | | `admin/setup/telemetry.md` | Toggling | Turn telemetry on or off | `#toggling` | | `admin/templates/creating-templates.md` | Disabling the template builder | Turn off the template builder | `#disabling-the-template-builder` | | `admin/templates/extending-templates/agent-metadata.md` | Managing the database load | Manage the database load | `#managing-the-database-load` | | `admin/templates/extending-templates/docker-in-workspaces.md` | Authenticating with a Private Registry | Authenticate with a private registry | `#authenticating-with-a-private-registry` | | `admin/templates/extending-templates/index.md` | Running scripts on workspace lifecycle | Run scripts on workspace lifecycle events | `#running-scripts-on-workspace-lifecycle` | | `admin/templates/extending-templates/parameters.md` | Validating parameters | Validate parameters | `#validating-parameters` | | `admin/templates/extending-templates/prebuilt-workspaces.md` | Invalidating prebuilds | Invalidate prebuilds | `#invalidating-prebuilds` | | `admin/templates/extending-templates/prebuilt-workspaces.md` | Managing resource quotas | Manage resource quotas | `#managing-resource-quotas` | | `admin/templates/extending-templates/prebuilt-workspaces.md` | Managing prebuild provisioning queues | Manage prebuild provisioning queues | `#managing-prebuild-provisioning-queues` | | `admin/templates/extending-templates/prebuilt-workspaces.md` | Preventing resource replacement | Prevent resource replacement | `#preventing-resource-replacement` | | `admin/templates/extending-templates/prebuilt-workspaces.md` | Preventing prebuild queue contention (recommended) | Prevent prebuild queue contention (recommended) | `#preventing-prebuild-queue-contention-recommended` | | `admin/templates/extending-templates/process-logging.md` | Configuring custom templates to use workspace process logging | Configure custom templates to use workspace process logging | `#configuring-custom-templates-to-use-workspace-process-logging` | | `admin/templates/extending-templates/process-logging.md` | Viewing workspace process logs | View workspace process logs | `#viewing-workspace-process-logs` | | `admin/templates/extending-templates/process-priority.md` | Verifying the feature is enabled | Verify the feature is enabled | `#verifying-the-feature-is-enabled` | | `admin/templates/extending-templates/resource-metadata.md` | Hiding resources in the dashboard | Hide resources in the dashboard | `#hiding-resources-in-the-dashboard` | | `admin/templates/extending-templates/resource-metadata.md` | Using a custom resource icon | Use a custom resource icon | `#using-a-custom-resource-icon` | | `admin/templates/extending-templates/resource-ordering.md` | Using "order" property | Use the "order" property | `#using-order-property` | | `admin/templates/extending-templates/resource-persistence.md` | Disabling persistence | Turn off persistence | `#disabling-persistence` | | `admin/templates/index.md` | Extending templates | Extend templates | `#extending-templates` | | `admin/templates/managing-templates/change-management.md` | Testing and Publishing Coder Templates in CI/CD | Test and publish Coder templates in CI/CD | `#testing-and-publishing-coder-templates-in-cicd` | | `admin/templates/managing-templates/index.md` | Creating templates | Create templates | `#creating-templates` | | `admin/templates/managing-templates/index.md` | Editing templates | Edit templates | `#editing-templates` | | `admin/templates/managing-templates/index.md` | Updating templates | Update templates | `#updating-templates` | | `admin/templates/troubleshooting.md` | Debugging the startup script | Debug the startup script | `#debugging-the-startup-script` | | `admin/users/groups-roles.md` | Creating custom roles | Create custom roles | `#creating-custom-roles` | | `admin/users/index.md` | Configuring SSO | Configure SSO | `#configuring-sso` | | `admin/users/index.md` | Resetting a password on Kubernetes | Reset a password on Kubernetes | `#resetting-a-password-on-kubernetes` | | `admin/users/quotas.md` | Establishing Costs | Establish costs | `#establishing-costs` | | `admin/users/quotas.md` | Establishing Budgets | Establish budgets | `#establishing-budgets` | | `admin/users/sessions-tokens.md` | Creating tokens with scopes | Create tokens with scopes | `#creating-tokens-with-scopes` | | `ai-coder/agent-firewall/index.md` | Getting Started with Agent Firewall | Get started with Agent Firewall | `#getting-started-with-agent-firewall` | | `ai-coder/agent-firewall/index.md` | Viewing Audit Logs | View audit logs | `#viewing-audit-logs` | | `ai-coder/agent-firewall/nsjail/k8s.md` | Running without user namespaces | Run without user namespaces | `#running-without-user-namespaces` | | `ai-coder/agent-firewall/version.md` | Using Coder Before v2.30.0 with Claude Code Module v4.7.0+ | Coder before v2.30.0 with Claude Code module v4.7.0+ | `#using-coder-before-v2300-with-claude-code-module-v470` | | `ai-coder/agent-firewall/version.md` | Using Claude Code Module Before v4.7.0 | Claude Code module before v4.7.0 | `#using-claude-code-module-before-v470` | | `ai-coder/agents/getting-started.md` | Providing feedback | Provide feedback | `#providing-feedback` | | `ai-coder/agents/models.md` | Managing personal API keys | Manage personal API keys | `#managing-personal-api-keys` | | `ai-coder/agents/models.md` | Removing a personal key | Remove a personal key | `#removing-a-personal-key` | | `ai-coder/agents/models.md` | Using an LLM proxy | Use an LLM proxy | `#using-an-llm-proxy` | | `ai-coder/agents/platform-controls/git-providers.md` | Checking logs | Check logs | `#checking-logs` | | `ai-coder/ai-gateway/audit.md` | Navigating the UI | Navigate the UI | `#navigating-the-ui` | | `ai-coder/ai-gateway/audit.md` | Conducting a forensic audit | Conduct a forensic audit | `#conducting-a-forensic-audit` | | `ai-coder/ai-gateway/clients/jetbrains.md` | Using the AI Assistant | Use the AI Assistant | `#using-the-ai-assistant` | | `install/operate/upgrade/best-practices.md` | Diagnosing liveness probe issues | Diagnose liveness probe issues | `#diagnosing-liveness-probe-issues` | | `install/operate/upgrade/best-practices.md` | Recovering from failed database migrations | Recover from failed database migrations | `#recovering-from-failed-database-migrations` | | `install/operate/upgrade/esr-2.24-2.29-upgrade.md` | Upgrading | Upgrade recommendations | `#upgrading` | | `install/operate/upgrade/esr-2.29-2.34-upgrade.md` | Upgrading | Upgrade recommendations | `#upgrading` | | `install/prepare/licensing.md` | Adding your license key | Add your license key | `#adding-your-license-key` | | `install/server/cloud/azure-vm.md` | Creating and Uploading Your First Template | Create and upload your first template | `#creating-and-uploading-your-first-template` | | `install/server/cloud/compute-engine.md` | Configuring the control plane | Configure the control plane | `#configuring-the-control-plane` | | `reference/releases.md` | Installing stable | Install stable | `#installing-stable` | | `start/first-workspace.md` | Creating your first coder workspace | Create your first Coder workspace | `#creating-your-first-coder-workspace` | | `start/local-deploy.md` | Setting up a Coder deployment | Set up a Coder deployment | `#setting-up-a-coder-deployment` | | `tutorials/best-practices/organizations.md` | Managing Organizations at Scale | Manage organizations at scale | `#managing-organizations-at-scale` | | `tutorials/example-guide.md` | Adding Photos | Add photos | `#adding-photos` | | `tutorials/example-guide.md` | Setting the author data | Set the author data | `#setting-the-author-data` | | `tutorials/example-guide.md` | Setting up the routes | Set up the routes | `#setting-up-the-routes` | | `tutorials/persistent-shared-workspaces.md` | Finding shared workspaces | Find shared workspaces | `#finding-shared-workspaces` | | `tutorials/reverse-proxy-caddy.md` | Getting started | Get started | `#getting-started` | | `tutorials/reverse-proxy-caddy.md` | Generating wildcard certificates | Generate wildcard certificates | `#generating-wildcard-certificates` | | `tutorials/reverse-proxy-nginx.md` | Adding Coder deployment subdomain | Add the Coder deployment subdomain | `#adding-coder-deployment-subdomain` | | `tutorials/testing-templates.md` | Creating the headless user | Create the headless user | `#creating-the-headless-user` | | `user-guides/desktop/desktop-connect-sync.md` | Accessing web apps in a secure browser context | Access web apps in a secure browser context | `#accessing-web-apps-in-a-secure-browser-context` | | `user-guides/desktop/index.md` | Testing Your Connection | Test your connection | `#testing-your-connection` | | `user-guides/desktop/index.md` | Getting Help | Get help | `#getting-help` | | `user-guides/desktop/index.md` | Uninstalling | Uninstall Coder Desktop | `#uninstalling` | | `user-guides/devcontainers/index.md` | Getting started | Get started | `#getting-started` | | `user-guides/devcontainers/troubleshooting-dev-containers.md` | Finding your dev container agent | Find your dev container agent | `#finding-your-dev-container-agent` | | `user-guides/devcontainers/troubleshooting-dev-containers.md` | Getting more help | Get more help | `#getting-more-help` | | `user-guides/devcontainers/working-with-dev-containers.md` | Using the Coder CLI | Use the Coder CLI | `#using-the-coder-cli` | | `user-guides/devcontainers/working-with-dev-containers.md` | Using OpenSSH (config-ssh) | Use OpenSSH (config-ssh) | `#using-openssh-config-ssh` | | `user-guides/devcontainers/working-with-dev-containers.md` | Exposing ports on the parent workspace | Expose ports on the parent workspace | `#exposing-ports-on-the-parent-workspace` | | `user-guides/devcontainers/working-with-dev-containers.md` | Rebuilding dev containers | Rebuild dev containers | `#rebuilding-dev-containers` | | `user-guides/shared-workspaces.md` | Getting Started | Get started | `#getting-started` | | `user-guides/shared-workspaces.md` | Sharing your Workspace | Share your workspace | `#sharing-your-workspace` | | `user-guides/shared-workspaces.md` | Using a shared workspace | Use a shared workspace | `#using-a-shared-workspace` | | `user-guides/shared-workspaces.md` | Accessing workspace apps in shared workspaces | Access workspace apps in shared workspaces | `#accessing-workspace-apps-in-shared-workspaces` | | `user-guides/workspace-access/emacs-tramp.md` | Connecting To A Workspace | Connect to a workspace | `#connecting-to-a-workspace` | | `user-guides/workspace-access/emacs-tramp.md` | Using SSH | Use SSH | `#using-ssh` | | `user-guides/workspace-access/index.md` | Running remote commands with quoting | Run remote commands with quoting | `#running-remote-commands-with-quoting` | | `user-guides/workspace-access/jetbrains/gateway.md` | Configuring the Gateway plugin to use internal certificates | Configure the Gateway plugin to use internal certificates | `#configuring-the-gateway-plugin-to-use-internal-certificates` | | `user-guides/workspace-access/jetbrains/gateway.md` | Using an existing JetBrains installation in the workspace | Use an existing JetBrains installation in the workspace | `#using-an-existing-jetbrains-installation-in-the-workspace` | | `user-guides/workspace-access/port-forwarding.md` | Accessing workspace ports | Access workspace ports | `#accessing-workspace-ports` | | `user-guides/workspace-access/port-forwarding.md` | Sharing ports | Share ports | `#sharing-ports` | | `user-guides/workspace-access/port-forwarding.md` | Configuring port protocol | Configure port protocol | `#configuring-port-protocol` | | `user-guides/workspace-access/vscode.md` | Using the public extensions marketplaces | Use the public extensions marketplaces | `#using-the-public-extensions-marketplaces` | | `user-guides/workspace-access/vscode.md` | Adding extensions to custom images | Add extensions to custom images | `#adding-extensions-to-custom-images` | | `user-guides/workspace-access/vscode.md` | Installing extensions using its `vsix` file at the command line | Install extensions using a `vsix` file at the command line | `#installing-extensions-using-its-vsix-file-at-the-command-line` | | `user-guides/workspace-access/vscode.md` | Installing from a marketplace at the command line | Install from a marketplace at the command line | `#installing-from-a-marketplace-at-the-command-line` | | `user-guides/workspace-access/vscode.md` | Using VS Code Desktop | Use VS Code Desktop | `#using-vs-code-desktop` | | `user-guides/workspace-access/web-terminal.md` | Accessing the Terminal | Access the terminal | `#accessing-the-terminal` | | `user-guides/workspace-lifecycle.md` | Stopping workspaces | Stop workspaces | `#stopping-workspaces` | | `user-guides/workspace-lifecycle.md` | Deleting workspaces | Delete workspaces | `#deleting-workspaces` | | `user-guides/workspace-management.md` | Creating workspaces | Create workspaces | `#creating-workspaces` | | `user-guides/workspace-management.md` | Updating workspaces | Update workspaces | `#updating-workspaces` | | `user-guides/workspace-management.md` | Updating via the CLI | Update with the CLI | `#updating-via-the-cli` | | `user-guides/workspace-management.md` | Starting and stopping workspaces | Start and stop workspaces | `#starting-and-stopping-workspaces` | | `user-guides/workspace-management.md` | Repairing workspaces | Repair workspaces | `#repairing-workspaces` | | `user-guides/workspace-scheduling.md` | Working hours | Work schedule | `#working-hours` | | `user-guides/workspace-scheduling.md` | Basing solely on activity detection | Rely solely on activity detection | `#basing-solely-on-activity-detection` | </details> <details> <summary>Plan</summary> The de-gerund work ships as three PRs: 1. This PR: in-page headings and page titles that do not require a page slug rename. 1. Page slug renames for pages whose filenames are gerunds. 1. Redirects for the renamed slugs. Heading rewrites follow the style guide section "No gerund-leading headings": imperative for task headings, noun form for concept headings, sentence case, and "turn on"/"turn off" instead of "enable"/"disable" per word-choice guidance. The legacy anchor sits on its own line above the heading (with a blank line between) rather than inside the heading, so it does not leak into heading text, TOC entries, or Fumadocs slugs. </details> --- _Generated by Coder Agents on behalf of @nickvigilante._ |
||
|
|
0058843a63 |
fix: ignore OAuth2 access tokens sent in the URL query string (#29878)
Ignore OAuth2 provider access tokens supplied only via `?access_token=` or `?coder_session_token=`, enforcing OAuth 2.1 §5.1 (D6-05). - Apply across all routes, including custom token readers. Protected routes return 401 with a Bearer challenge and no error code; optional-auth routes proceed unauthenticated. - Continue accepting tokens via `Authorization`, `Coder-Session-Token`, or session cookies, ignoring any query copy. - Log ignored tokens without updating `last_used` or `expires_at`. - Leave Coder session and API tokens unchanged, preserving dashboard WebSocket authentication. **Breaking:** OAuth2-authenticated embedded dashboards lose WebSocket access; the only known use was the VS Code chat sidebar, removed in vscode-coder v1.14.6. - Update docs and regression tests. No migration or new configuration. Fixes PLAT-603. |
||
|
|
88aa2cc373 |
feat: enable Coder.UnitSpacing (#29944)
## Summary
Adds `Coder.UnitSpacing`, a Vale rule that enforces the style guide's
[non-breaking space between number and
unit](https://github.com/coder/coder/blob/main/docs/.style/style-guide/numbers-units-and-dates.md#non-breaking-space-between-number-and-unit)
policy.
Until now, the guide pointed at `Google.Units (planned)`, but that rule
accepts a regular space, so it can't enforce the policy.
Resolves [DOCS-1072](https://linear.app/codercom/issue/DOCS-1072).
## Changes
- **Cleanup commit**: replaces the regular space (or missing space) with
` ` in 189 prose findings across 55 files. One config default,
`(default: 15s)`, moves to code font instead, as the guide requires for
configuration values. One table row that was realigned also swaps a
pre-existing en dash for a hyphen, since `lint/emdash` checks changed
lines.
- **Enable commit**: adds `docs/.style/styles/Coder/UnitSpacing.yml` at
`warning`, updates the enforcement footer in
`numbers-units-and-dates.md`, and updates the coverage tables in the
style guide README.
- **Reflow commit**: every hard-wrapped paragraph the cleanup touched
(45 paragraphs in 29 files) is rewrapped to one sentence per line.
Joining lines exposed units split across a line break, which now use
` `, and two em dashes on rewritten lines are reworded.
- **Rule fix commit**: the token now matches ASCII whitespace, including
a newline, between the number and the unit, so a hard-wrapped paragraph
can't hide a missing ` `. The class is spelled out because Vale's
`\s` is Unicode and would match U+00A0. Vale can't locate a match that
spans list indentation or a blockquote marker, so splits there still go
unreported.
- **Rule count sync**: the tooling paragraph in the style guide README
now reads 79 rules, 9 tool-checked, to match the coverage table. The 79
corrects drift already on `main` since #29758; the 9 is this PR's new
rule.
- `.vale.ini` turns the rule off for pages generated from Go source:
`docs/reference/{api,cli}/*.md`, `configuration-reference.md`, and
`prometheus.md`. That text comes from flag descriptions, Swagger
comments, and metric help text, which also render outside Markdown,
where ` ` would show up literally.
<details>
<summary>Rule design decisions</summary>
- An `existence` rule matches `\d+(\.\d+)?` followed by a regular space
or no space, then a unit from a curated list (time, data size,
bandwidth, frequency, vCPU/CPU/cores).
- Vale renders Markdown before matching, so ` ` and a literal
U+00A0 both pass. Code spans and fences are skipped.
- Hyphenated compound modifiers (`12-hour clock`) don't match, because
the token allows only a space or nothing between the number and the
unit.
- Exceptions cover HTTP status plurals (`413s`) and decades (`1990s`).
- Severity is `warning`, because the unit list is curated and a count
followed by a unit-like word can still be a judgment call.
- Alternative considered: a `BlockIgnores` pattern for the `<!-- Code
generated ... -->` regions. I didn't use it because it would silence
every rule in those regions, not just this one.
</details>
## Testing
- Ran the rule against fixtures: `30 seconds`, `150ms`, `4 vCPU` in a
table, and `16` / `GB` split across lines in a paragraph all flag.
`30 seconds`, literal U+00A0, `12-hour`, `413s`, `1990s`, and ``
`30s` `` don't.
- `vale docs/` reports 0 `Coder.UnitSpacing` findings, and the counts
for every other rule match `main`.
- A scratch config with `Coder.OneSentencePerLine` turned on reports 0
findings on changed lines.
- `make lint/markdown`, `make lint/style-claims`, `make lint/emdash`,
and the `pre-commit-light` hook pass.
<details>
<summary>CI flake note</summary>
`Storybook` failed on
|
||
|
|
5dde49dffb |
feat: add chat workspace file upload endpoint (#27079)
## What
Adds `POST /api/v2/chats/{chat}/workspace-files`, which streams the
request body to the chat's bound workspace agent and returns the final
path/name/size, plus the `workspace-file-reference` message part type
that carries the uploaded file's metadata through chat messages:
- `coderd/exp_chats.go`: owner-only middleware (chat RBAC update +
reject archived), workspace exec authorization (403/409 like the
existing chat exec paths), agent selection (prefer the chat's bound
agent, else deterministic `agentselect.FindChatAgent`, without
persisting a binding), 30s dial timeout, chat/ancestor tracking headers
on the agent connection, and agent error passthrough (agent HTTP status
preserved, 502 with a generic detail for transport failures; the real
error is logged). Deleted and non-running workspaces get a specific 409
("Workspace is stopped. Start the workspace before uploading files.")
before agent lookup. Each failed upload logs one structured warning, and
`coderd_chat_workspace_upload_total{status}` counts outcomes. The route
shares the files rate limit and documents its 429.
- Input validation: client-supplied `workspace-file-reference` parts
must point inside `/.coder/chats/<chat-id>/files/` with a matching
basename, non-negative size, and a `workspace_file_workspace_id` equal
to the chat's currently bound workspace (the upload response echoes it
as `workspace_id`). References uploaded before a workspace rebind are
rejected instead of silently sending the agent an unreadable path. The
file name must already be in sanitized form
(`SanitizeWorkspaceUploadName(name) == name`), and the cleaned path and
base media type are what gets persisted; message edits share the same
validation. Parts are rejected on chat creation (no chat ID exists yet).
- `coderd/x/chatd/chatprompt`: references render into the prompt as text
only, `[workspace file: <name> (<size>) at <path>]`; file bytes never
reach the LLM. Title derivation (`TitleText`) uses the bare file name,
so fallback titles carry no internal marker.
- `codersdk`: part-type constants/fields,
`ChatMessageWorkspaceFileReference` builder, and
`Client.UploadChatWorkspaceFile` (RFC 5987 filename in
`Content-Disposition`).
No DB migration: parts persist as JSON in `chat_messages.content`.
## Why
Bridges chat and the workspace filesystem for CODAGT-211: users drop a
file in chat, the bytes land where the agent's tools can operate on
them, and the model learns the path from the reference part.
## How tested
- `go test ./coderd -run 'WorkspaceFile|ChatInput|UploadChat'` including
an integration test that runs a real in-memory agent, uploads through
the coderd route, verifies bytes on disk, and exercises collision
suffixes.
- `go test ./codersdk ./coderd/x/chatd/...`, `make gen`
(swagger/types/docs), `make lint`.
- Rebased onto main 2026-09-21: the chat API moved from
`/api/experimental` to `/api/v2`, so the route is registered in
`coderd/chat_routes.go` and the SDK method lives on `codersdk.Client`.
## Follow-ups
- The files rate limit counts requests, not bytes or concurrency;
whether this route should use a per-user concurrency cap instead, and
whether the new-chat page should keep partial successes on a 429, is
still open
([CODAGT-1171](https://linear.app/codercom/issue/CODAGT-1171)).
Part of CODAGT-211. Stack: agent API -> coderd endpoint (this PR) -> UI.
> This PR was authored by Mux (AI) working on Mike's behalf.
|
||
|
|
b70702d50d |
docs: split OAuth2 provider page (#29778)
Split the OAuth2 provider documentation into seven focused pages. - Update navigation and inbound links, preserving compatibility anchors for moved headings. - Correct `DELETE /oauth2/tokens` documentation: it revokes only the calling user's tokens and codes, not every user's for the application. - Clarify client authentication and app creation, mention PKCE, and update callback UI references. - Remove contributor-only instructions and the feature-specific example from feature-stage docs; restore release and upgrade guidance in `security.md`. - Standardize formatting and verify internal anchors. Markdown and em-dash linting pass. Refs PLAT-659. |
||
|
|
d5a6047879 |
docs: restructure Install into the five phase deployment spine (#29304)
Restructures the Install section into the five-phase deployment spine, so the reading order matches the order a deployment actually happens: **plan, prepare, install, validate, operate.** Today the first thing a reader sees is a shell command, and architecture and sizing sit downstream in Administration, after the point where they would have been useful. Resolves [DOCS-869](https://linear.app/codercom/issue/DOCS-869). Part of [DOCS-685](https://linear.app/codercom/issue/DOCS-685) and [DOCS-738](https://linear.app/codercom/issue/DOCS-738). > [!IMPORTANT] > **Stacked on [#28960](https://github.com/coder/coder/pull/28960)** (DOCS-871, terminology). Base is that branch, not `main`. Retarget to `main` after it merges. > > **Paired with coder/coder.com [#1077](https://github.com/coder/coder.com/pull/1077)**, which must merge **first**. Without it, every inbound link to a moved page 404s in the gap. ## Deliberately mechanical No prose changes. The only edits inside moved pages are relative link and image path repairs, so the diff reads as renames. That is the point: this is the highest link-breakage change in the project, and it should be reviewable as such. The prose work is [DOCS-868](https://linear.app/codercom/issue/DOCS-868) (phase overview, architecture rewrite, sizing split, actor table) and [DOCS-872](https://linear.app/codercom/issue/DOCS-872) (new pages). ## The new spine ```text Install and deploy Coder /install ├── Coder CLI [unchanged, retired by DOCS-870] ├── 1. Plan your deployment │ ├── Architecture and components [from admin/infrastructure] │ └── Coder Validated Architecture [from admin/infrastructure] │ └── 1k / 2k / 3k / 10k users ├── 2. Prepare prerequisites │ ├── Licensing [from admin/licensing] │ ├── Air-gapped deployments [from install/airgap] │ └── Mirror images and registries [from install/registry-mirror-artifactory] ├── 3. Install the control plane │ ├── Docker / Kubernetes / Rancher / OpenShift │ ├── Cloud marketplace and VM images │ └── Unofficial install methods ├── 4. Validate your deployment │ └── Scale testing [from admin/infrastructure] │ ├── Scale test utility │ └── Scaling best practices └── 5. Operate and maintain ├── External provisioners [from admin/provisioners] ├── Upgrading (+ best practices, ESR guides) └── Uninstall ``` Leaving Install: release channels become `reference/releases`, feature stages become `reference/feature-stages`. `docs/admin/infrastructure/` is gone entirely, which is what DOCS-738 recommended. ## Numbers - 31 pages moved, all as `git mv` renames. - 1 page deleted: `admin/infrastructure/index.md`, whose content was a one-line section blurb. - 5 new placeholder index pages, one per phase, each a sentence of orientation plus `<children></children>`. The nav schema requires a path on every entry, so a phase cannot exist without one. - 265 relative links and asset paths repaired across 57 files. - `docs/manifest.json` restructured. Entry count goes 460 to 464: plus 5 stubs, minus the deleted Infrastructure entry. ## Reviewer attention, please **The redirects PR repairs 19 existing redirects, not just adds new ones.** This was the surprise. `redirects.json` already had entries whose *destinations* pointed at pages this PR moves, so they would have started redirecting to 404s. Examples: `/docs/architecture/architecture`, `/docs/admin/architectures`, `/docs/scaling/scale-testing`, `/docs/licensing`, `/docs/enterprise`, `/docs/install/offline`, `/docs/platforms`, `/docs/install/1-click`, `/docs/admin/upgrade`, `/docs/install/cloud/ec2`, and both `feature-stages` aliases. All 19 are fixed in the paired PR. **This PR touches `scripts/`, so it is not docs-only.** Two release tools write to paths that moved and would have broken silently at release time: - `scripts/update-release-calendar.sh`: `DOCS_FILE` now points at `docs/reference/releases.md`. - `scripts/releaser/docs.go`: `releasesFile`, and also `kubernetesFile` and `rancherFile`, which pointed at `docs/install/kubernetes.md` and `docs/install/rancher.md`. <details> <summary>Deliberate scope decisions</summary> - **Self-managed vs cloud grouping is flattened.** The reconciled IA nested platform pages under a "Self-managed platforms" parent. That would need two more placeholder index pages for groups with no content yet, so the platform pages sit directly under Phase 3 and the grouping lands with the DOCS-868 prose. - **Release-notes URLs left alone.** `scripts/releaser/release.go` and `scripts/release/generate_release_notes.sh` embed `https://coder.com/docs/install/releases` and `/docs/install/upgrade` in release-note templates. The redirects cover them, and changing the strings would require updating Go test fixtures in `scripts/release/main_internal_test.go`. Better as its own change. - **In-product doc links left alone.** Several `site/src` pages link to `coder.com/docs/admin/provisioners` and similar. Those are absolute URLs, so the redirects cover them. Updating them is a frontend change that would pull frontend review into a docs restructure. - **`admin/security/audit-logs.md` line 237** is hand-written prose below the generated table, and its `../licensing/index.md` link had to move with the licensing page. Verified `make gen` does not revert it. - **`reference/feature-stages.md`** has generated blocks whose relative links changed depth with the move. The generator named in its own marker comment (`scripts/release/docs_update_feature_stages.sh`) no longer exists in the repo, so those links were repaired by hand and the file is effectively hand-maintained. Worth its own issue. - **`install/cli.md` keeps its nav slot** here. DOCS-870 retires it. </details> ## Verification | Check | Result | |---|---| | Broken relative link scan | 0 in `install/`, `admin/`, `reference/`. 21 remain, all pre-existing illustrative examples in `docs/.style/style-guide/**` and one malformed URL in `docs/README.md` | | `make gen` | clean, manifest not clobbered, phase structure intact | | `make lint/markdown` | pass, 508 files, 0 errors | | `make lint/emdash` | pass | | `make lint/docs-html` | pass | | `make lint/prose` | pass, 1 intentional demo error, no new findings | | `make pre-commit` | pass, including `lint/go`, `lint/ts`, `lint/shellcheck`, and a slim build | | Manifest audit | every path resolves to a file on disk; entry-by-entry diff shows only the expected moves | Generated with Coder Agents on behalf of @nickvigilante. <details> <summary>CI note: doc-check failure is infrastructure, not this PR</summary> `Analyze PR for Documentation Updates Needed` fails before it reviews anything: the Coder account behind `agents-chat-action` returns `User is not active (status = "suspended")`. It isn't a required check. `check-docs` (linkspector) and every other check pass on `58ed9e3e4b`. _CI note added by Coder Agents on behalf of @nickvigilante._ </details> |
||
|
|
eb893f536d | docs: move section page to index.md (#29858) | ||
|
|
c95a87cea7 |
feat: warn before narrowing a self-registered OAuth2 app's scope allowlist (#29777)
- Warn rather than block when admins narrow a self-registered OAuth2 app's scope allowlist. Clients requesting all advertised scopes may receive `invalid_scope` on new authorizations; existing tokens retain their scopes. - Expose `dynamically_registered` in API responses and display registration type on the app page. - Show no warning for widening or clearing allowlists, or for admin-created apps. - Update scope and `invalid_scope` troubleshooting docs and remove the outdated note that the UI cannot set allowlists. Closes PLAT-664. |
||
|
|
bacb4fc6ed |
feat: expose per-app session counts (#29351)
Track individual applications across deployment statistics, Prometheus, telemetry, and the dashboard instead of exposing only fixed family totals. Preserve existing fields and gauges so current consumers can migrate without breaking. - Add per-app counts with normalized identifiers and registry-backed display names, families, and bundled icons. Unrecognized apps retain their identifiers. - Limit each statistics report to 64 distinct app names, combining excess names into an explicit overflow bucket. - Group dashboard connections by family, including an Other category, with alphabetical per-app tooltips and distinct loading and empty states. - Export app-keyed Prometheus counts separately from current family metadata, allowing queries to enrich historical counts without rewriting stored samples. - Document family queries with unknown fallback, deployment isolation, and replica handling, alongside collection behavior and migration guidance. - Include per-app counts in telemetry, update API schemas and documentation, and add regression coverage across collection, metrics, and dashboard behavior. Closes #27411 |
||
|
|
528dd3cc44 |
feat: edit an OAuth2 app's redirect URIs as an ordered list (#29603)
Completes PLAT-619, following #29440 and #29502. - Replace the OAuth2 app’s single callback field with an editable `redirect_uris` list supporting 1–32 entries, with the first labeled “Default callback.” - Show a `+N` badge for additional redirect URIs in the applications table. - Remove `omitempty` from request `redirect_uris` so explicit empty lists reach the server. - Add tests and stories for adding, editing, removing, and requiring at least one URI. |
||
|
|
395e8032dc |
fix: reject client_secret in the OAuth2 token and revocation URL (#29508)
Reject non-empty `client_secret` query parameters on token and revocation endpoints with `400 invalid_request`, enforcing OAuth 2.1 §2.4.1 (D6-04). - **Breaking:** Send secrets in the request body or `Authorization` header, and rotate any previously sent in URLs. Rejections consume nothing, so clients can retry without reauthorization. - Empty query secrets count as absent, but token requests also supplying a body secret still fail duplicate-parameter validation. Authorize ignores query secrets and logs a warning without the value. - Sanitize and cap revocation parse errors, correctly report repeated token parameters, and update tests and API docs. Refusal logs include the app ID, never the secret. - Other query parameters (`client_id`, `refresh_token`, `code`, and revocation tokens) remain accepted; body-only credential parsing is tracked in PLAT-660. No migration or new error codes. Refs PLAT-602. |
||
|
|
fc707a15d1 |
fix: rate limit the OAuth2 endpoints (#29510)
Apply the login rate limit to OAuth2 authorization, token, revocation, registration, client configuration, and discovery endpoints, closing the brute-force protection gap (D6-01) and bounding database work. - Limit requests per IP without a Coder session and per user otherwise. - Use independent, fixed-key endpoint buckets to prevent path-based bypasses; unmatched routes consume no budget. - Return HTTP 429 with `temporarily_unavailable` and a `message` matching `error_description` for dashboard/SDK compatibility. - Preserve `X-Coder-Bypass-Ratelimit` and `--dangerous-disable-rate-limits`. - Add documentation and tests for route coverage, variable paths, and endpoint/user isolation. No migrations or new configuration. Refs PLAT-624 |
||
|
|
83bef8a12d | fix: consolidate pg and nats pubsub metrics generation into one (#26843) | ||
|
|
5e41baf73c |
docs: normalize control plane, coderd, and coder server terminology (#28960)
Normalizes the three overlapping names for the thing that serves the Coder API and dashboard. This is step 1 of the Install/Deploy and Administration refactor ([DOCS-685](https://linear.app/codercom/issue/DOCS-685), [DOCS-738](https://linear.app/codercom/issue/DOCS-738)) and lands first because every later page depends on settled terminology. Resolves [DOCS-871](https://linear.app/codercom/issue/DOCS-871). ## The rule | Term | Means | Use when | |---|---|---| | control plane | The component that serves the Coder API and dashboard, brokers connections, and coordinates provisioners | Default in prose, diagrams, planning, sizing, security | | `coderd` | The process that implements it | Architecture internals, metrics, logs, flags, troubleshooting | | `coder server` | The literal CLI command | Only when the reader will type it | Retired: "the Coder server" as a name for the component, and "a service" as a standalone description of it. ## What changed - **`docs/.style/style-guide/word-choice.md`**: new "Naming Coder's components" rule, with do/don't examples. Also fixes a "Do" example on that page that itself used "the Coder server". - **`docs/reference/glossary.md`**: rewrote `coderd` and Control plane, added a `coder server` entry. The existing Control plane entry defined it as "the collective term for `coderd`, its provisioners, and its database", which made it indistinguishable from the Deployment entry two sections later. Control plane is now the component; Deployment remains the whole installation. - **65 pages** across `docs/admin`, `docs/install`, `docs/get-started`, `docs/tutorials`, `docs/user-guides`, `docs/ai-coder`, and `docs/about`: roughly 154 component-sense "Coder server" usages, 21 bare "the server" usages meaning the control plane, 3 "a service" descriptions, and 43 unbackticked `coderd` mentions in prose. - One real bug caught in passing: `docs/tutorials/best-practices/security-best-practices.md` documented `coderd server --disable-path-apps`, which is not a command. Now `coder server`. Generated files were not touched: `configuration-reference.md`, `prometheus.md`, `audit-logs.md`, `reference/cli/*`, `reference/api/*`, and the generated blocks inside `feature-stages.md`. Those still contain the retired term and need generator-side changes; see the deferred list below. ## Reviewer attention, please **Anchor changes.** 11 headings were renamed, so their fragments change. No in-repo link targets any of them (the one internal link that did was updated), but external deep links from tickets or blog posts would break, and fragments cannot be fixed with a redirect. Happy to revert any of these if you would rather they ride along with the page moves in [DOCS-869](https://linear.app/codercom/issue/DOCS-869), which changes those URLs anyway. <details> <summary>Renamed headings and their old fragments</summary> | File | Old fragment | New heading | |---|---|---| | `admin/networking/index.md` | `#coder-server` | `## Control plane` | | `install/index.md` | `#starting-the-coder-server` | `## Starting the control plane` | | `install/uninstall.md` | `#the-coder-server-binary-and-cli` | `## The Coder binary and CLI` | | `install/registry-mirror-artifactory.md` | `#step-5-configure-coder-server-or-provisioners` | `## Step 5: Configure the control plane or provisioners` | | `install/cloud/compute-engine.md` | `#configuring-coder-server` | `## Configuring the control plane` | | `get-started/index.md` | `#cant-start-coder-server-address-already-in-use` | ``### Can't start `coder server`: Address already in use`` | | `tutorials/external-database.md` | `#coder-server-fails-startup-with-...` | ``### `coder server` fails startup with ...`` | | `tutorials/faqs.md` | `#how-do-i-change-the-access-url-for-my-coder-server` | `## How do I change the access URL for my control plane?` | | `tutorials/best-practices/security-best-practices.md` | `#coder-server` | `## Control plane` | | `tutorials/best-practices/security-best-practices.md` | `#server-logs-and-audit-logs` | `### Control plane logs and audit logs` | | `tutorials/best-practices/scale-coder.md` | `#coder-server`, `#how-to-capture-coder-server-metrics-with-prometheus` | `## Control plane`, `### How to capture control plane metrics with Prometheus` | </details> **One deliberate deviation from the issue.** DOCS-871 proposed reserving "sub-agent" for the Coder Agents sense and using "devcontainer agent" for the workspace sense. I did not make that change. The glossary already disambiguates with "Sub-agent (Coder Agents)" and "Sub-agent (dev containers)", and "devcontainer agent" would violate the existing dev container spelling rule in the same style guide, which requires "dev container" as two lowercase words. The current split reads correctly and costs no churn. Happy to revisit if you disagree. <details> <summary>Deferred, with reasons</summary> - **Generated content still says "Coder server".** `reference/cli/*` comes from Go command help text, `configuration-reference.md` from `configdocgen`, and `reference/api/*` from Swagger annotations. Fixing those means changing Go source, which belongs in its own PR so a docs review does not turn into a backend review. - **`validated-architectures/index.md` "also known as `coderd`"** is fixed here, but the page's larger problem is that it holds four documents in one file. That split is [DOCS-868](https://linear.app/codercom/issue/DOCS-868). - **"server flag" phrasing** in `admin/users/idp-sync.md` and `admin/users/oidc-auth/index.md` means `coder server` flags. Left alone; rewording those sentences is a copy edit, not a substitution. - **Metric and UI labels** such as "Dashboard-to-server latency" in `admin/networking/index.md`. Renaming risks diverging from what the dashboard shows. - **Pre-existing `Coder.GerundHeading` warnings** on headings this PR touches, and a "from from" typo in `scale-coder.md`. Out of scope for a terminology pass. - **Peer-sense "server"** in NAT traversal prose, where "client or server" describes the connection roles rather than the control plane. Needs restructuring, not substitution. </details> ## Verification | Check | Result | |---|---| | `make lint/emdash` | pass | | `make lint/markdown` | pass, 504 files, 0 errors | | `make lint/docs-html` | pass | | `make lint/prose` | pass, findings identical to the `main` baseline (1 intentional demo error, 145 warnings, 1 suggestion; only Vale's file ordering and one line-number shift in `glossary.md` differ) | | `make gen` | clean, no drift | | `make fmt/markdown` | applied | No redirects needed: no page moved or was renamed in this PR. <details> <summary>Merged main, 2026-09-14</summary> One conflict, in `docs/ai-coder/ai-gateway/providers.md`. Both hunks were text this PR had edited and `main` had since deleted in #29053, which removed env-based AI provider configuration: - The deprecated provider seeding note, which held a `coderd` backtick fix, is gone. Took `main`. - The failure-mode table lost its env-drift row. Took `main`'s two rows and reapplied the `coderd` logs wording. `main` also landed new prose carrying the retired terms, so the pass was extended to cover it: - `docs/admin/integrations/oauth2-provider.md`: two "the server log(s)" in the scope-enforcement sections added by #29144 are now "the `coderd` log(s)"; "a `scope` the server will not grant" is now "the control plane". - `docs/reference/cli/index.md` gained "the server" from #29104, and stays deferred as generated content. The new `docs/ai-coder/agent-relay/claude-code.md` needed no change, and no page `main` added links to a heading this PR renamed. </details> <details> <summary>Decision log for the wider refactor</summary> Agreed with @nickvigilante before implementation, recorded on DOCS-685 and in the Notion outline: 1. Feature stages and release channels move to Reference; ESR upgrade guides move under Operate. No new top-level Releases section. 2. `data-retention.md` moves to Administration > Security; `chat-lifecycle-hooks.md` moves into the Coder Agents docs. `admin/setup/` therefore survives as "Deployment configuration" and `configdocgen` is not touched. 3. Prepare is advisory, not a gate, framed as "don't know where to start? Start here", with lead times and owners per item. 4. One actor table, on the Install overview, spanning all five phases, noting that one person can be several actors and several people can be one actor. 5. The quickstart stays independent and is mentioned once, on the Install overview. The proposed `server/single-machine` page is dropped. 6. Coder Validated Architecture keeps its name in nav, defined in-page, with a glossary entry. 7. PR 3 is split: moves only, then prose, so the riskiest change reads as a pure rename diff. 8. For every PR that moves a page, the coder.com `redirects.json` change merges first. 9. There is no Download section and no CLI page in docs. Per-OS CLI steps live on coder.com/download and the Install overview links to it. </details> Generated with Coder Agents on behalf of @nickvigilante. |