909 Commits
Author SHA1 Message Date
Susana Ferreira 8705d80fe0 feat: add provider, model, and client spend to the AI spend users endpoint (#32330)
## Description

Extends the experimental `GET
/api/experimental/organizations/{organization}/ai/spend/users` endpoint
with the per-user details behind the AI spend overview and the detailed
report. Each user now returns their spend per provider, model, and
client, and whether each has unpriced usage.

## Changes

- Rewrite `ListOrganizationAISpendUsers` with `GROUPING SETS`, returning
one row per user and provider, model, or client:
  - Adds the `user_ids` and `group_id` filters.
  - Pages, counts, and totals users, not their rows.
- Reads the provider display name, icon, and type from `ai_providers`,
including deleted providers. The live provider wins when a name was
reused, like `GetAIProviderFilterOptions`.
- Update the SDK and handler:
- Each user returns `provider_spend`, `model_spend`, and `client_spend`,
most expensive first, each with `has_unpriced_usage`.
  - `totals` returns `has_unpriced_usage`.
- Remove the `providers`, `clients`, and `models` name arrays and
`unpriced_usage_count`.
  - Accept `user_ids` (comma-separated, maximum 100) and `group_id`.
- Return more than 100 `user_ids` on the group members AI spend endpoint
as a validation error, like `/ai/spend/users`.
- Switch the Spend page to the new fields, with no UI changes.
- Update the query and handler tests.

<details>
<summary>Dogfood performance</summary>

- Benchmarked on **dogfood**, comparing the existing query on **main**
with the updated query in **this PR**.
- Tested **1, 7, 15 and 30-day windows**, ending at **November 18, 2026,
00:00 UTC**, exclusive.
- Each query ran **five times per window**, one at a time, with query
order and window order rotated across rounds to reduce ordering bias.

The table shows PostgreSQL execution time in **seconds, average
(min-max)**.

| Days | Main | This PR |
|------|-----:|--------:|
| 1 | 0.288 (0.199-0.501) | 0.223 (0.184-0.275) |
| 7 | 11.413 (4.076-40.003) | 4.107 (3.529-4.828) |
| 15 | 9.961 (8.053-16.917) | 7.253 (6.873-7.736) |
| 30 | 14.979 (12.276-23.177) | 8.499 (7.813-9.169) |

All five runs are included. Main's first seven-day run took **40.003s**
with unusually high read I/O time, which raises its average. Cache and
concurrent load can affect these results.

</details>

Closes AIGOV-734

> [!NOTE]
> Generated by Coder Agents on behalf of @ssncferreira.
2026-11-19 14:59:20 +00:00
Ben Potter 690d107fdb docs: explain how to keep a workspace running without a connection (#32315)
The answer to "how do I keep a workspace up while a long job or coding
agent runs?" only lived in the [reference
page](https://coder.com/docs/reference/#workspace-agents), which is hard
to find. This adds a **Keep a workspace running without a connection**
section to the scheduling page under Activity detection:

- Background processes (Claude Code in `tmux`, Herdr, `nohup` jobs)
don't count as activity.
- `coder schedule extend` from the CLI, and `PUT /extend` from a script
with a user token.
- **Keep coding agents running:** template examples for Claude Code and
Herdr. A `coder_script` uses the owner's build session token once to
mint a token scoped to `workspace:read` + `workspace:update` and
allow-listed to the workspace. It also installs a `coder-keepalive`
helper. Claude Code calls the helper from `managed_settings` hooks, and
Herdr calls it from a `post_start_script` loop. Neither needs a module
change. Matching README examples: coder/registry#1262.

This deliberately avoids app status / AgentAPI reporting.

<details>
<summary>Validation</summary>

On a local v2.38.8 deployment, I used three Docker workspaces with no
IDE, SSH, or terminal connection. Autostop was 2m, and Claude Code went
through dogfood's AI Gateway running about 30 sequential tool calls over
about 11 minutes. The template used the snippets from this page
verbatim, with the unmodified modules from registry `main`.

| Workspace | Result |
| --- | --- |
| Control (no keep-alive) | Stopped about 1 minute after its deadline
while Claude worked |
| Claude Code hooks | Deadline moved to now + 1h at 13:32, and again at
13:43. No changes after Claude finished |
| Herdr loop | Deadline moved to now + 1h at 13:32. No changes after the
agent went idle |

The scoped token from inside the workspace: `PUT /extend` returns 200.
Stopping or deleting the workspace returns 403. Other workspaces,
`/users/me`, and token creation return 404. A full `GET
/workspaces/{id}` is forbidden with the allow list, which is why the
helper uses `?include_related=latest_build`.

</details>

---

🤖 Generated with Coder Agents using Claude.
2026-11-19 07:46:47 -06:00
Molly Fraser 4bccdc4ed6 feat: show and filter by organization in AI Gateway sessions API (#32057)
Adds an `organization` filter to `GET /api/v2/ai-gateway/sessions` (and
its `/api/v2/aibridge/sessions` alias) and returns the organization an
interception was attributed to, and how it was chosen, on sessions,
threads and agentic actions, as proposed in the surface definitions on
AIGOV-754. No migration: `aibridge_interceptions.organization_id` and
`organization_source` already exist (000634).

The filter accepts an organization name or ID and keeps sessions with at
least one interception in that organization; the count uses the same
rule so pagination totals match. Each session, on the list and detail
responses, lists the organizations its interceptions were attributed to,
ordered by name, with the distinct sources used for each, or `[]` when
none was stored. Each thread carries the organization of its root
interception and each agentic action carries its own, or null when none
was stored. The new filter is listed in the AI Gateway monitoring docs.

Refs AIGOV-754

## Open questions for reviewers

- **Multi-org sessions** (AIGOV-776): the filter is row-level, like
provider and model. A session spanning two orgs is listed under each
org's filter, and with the filter on, `threads`, `started_at` and
`ended_at` only cover the matching interceptions, while providers,
models, tokens and `organizations` cover the whole session. Is that the
desired behavior?
- **Unknown org ID:** an unknown org name returns 400, but an unknown
org ID returns an empty page, because `parseOrganization` does not look
up UUIDs. This matches workspaces and templates, but the spec says 400.

## Notes for reviewers
- `aiBridgeSessionOrganizations` returns an empty list if the
organizations JSON from the query can’t be decoded, rather than failing
the whole request. The field is supplementary, so a decoding problem
shouldn’t take down the sessions list, but it does mean a SQL bug here
would show up as empty data rather than an error. The alternative is to
log the error before returning the empty list.
- A thread’s organization is taken from its root interception only. If
later requests in the same thread were attributed to a different
organization, that shows on each agentic action’s own organization
field.

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

- `coderd/database/queries/aibridge.sql`:
- `@organization_id` filter in `CountAIBridgeSessions` and the
`session_page` CTE of `ListAIBridgeSessions`.
- New `sorg` lateral in `ListAIBridgeSessions` that groups the session's
interceptions by organization, collects distinct sources, joins
`organizations` (deleted orgs still resolve) and returns a JSON array.
- `ListAIBridgeSessionThreads` resolves the organization name, display
name and icon through a `LEFT JOIN LATERAL` in the final `SELECT`. A
plain join on `organizations` is not safe there: the query has two
`@authorize_filter` placeholders, and the injected filter can reference
a bare `id`, which would be ambiguous next to `organizations.id`. The
lateral only exposes the three selected columns. This answers the
authorize-filter open question from the surface proposal.
- `coderd/database/modelqueries.go`: the hand-written
`ListAuthorizedAIBridgeSessions`, `CountAuthorizedAIBridgeSessions` and
`ListAuthorizedAIBridgeSessionThreads` gain the new argument and scan
columns. The compiler does not catch a mismatch here; it fails at
runtime.
- `enterprise/coderd/aibridge.go`: pass `OrganizationID` into
`CountAIBridgeSessionsParams`, which is built field by field, and list
the `organization` key in `@Param q`.
- `coderd/searchquery/search.go`: `organization` key via
`parseOrganization`.
- `codersdk/aibridge.go`: `AIBridgeInterceptionOrganizationSource` enum,
`AIBridgeInterceptionOrganization`, `AIBridgeSessionOrganization`, new
response fields and `AIBridgeListSessionsFilter.Organization`, per the
proposed Go definitions.
- `coderd/database/db2sdk/db2sdk.go`: decode the session organizations
JSON, never returning nil; `AIBridgeInterceptionOrganizationSource`
converter; build one organization per interception while grouping thread
rows, and use it for the thread (root interception) and each agentic
action.
- `site/`: add `organizations: []` to two frontend mocks, now that the
field is required in the generated types.
- `docs/ai-governance/ai-gateway/monitoring.md`: `organization` added to
the sessions API query filters.
- Tests: `TestAIBridgeSessions` (name and ID parsing),
`TestAIBridgeListSessions/Filters` (by name and ID, checks count and
page), `FilterErrors/UnknownOrganization`,
`TestAIBridgeListSessions/Organizations` (multi-org ordering and
sources, no-org session returns `[]`, filtering by either org returns
the multi-org session and never the no-org one),
`TestAIBridgeGetSessionThreads/Organizations` (thread uses the root's
org, each action its own, null when none, session `organizations` on the
detail endpoint), and `TestAIBridgeInterceptionOrganizationSource`
(every database source maps to an SDK value).
- Remaining files are generated by `make gen`.

</details>

---

Code written by @mollymaefraser, with Coder Agents used as a guide:
explaining the existing code path, reviewing each step, and running
tests.
2026-11-19 09:07:56 +00:00
Taruj Goyal 734a0cae07 feat: scope browser-only connections to a template (#30578)
Add per-template `browser_only` enforcement while preserving `CODER_BROWSER_ONLY` as a deployment-wide override.

Refs #29157. Supersedes #29204 (closed by stale bot). Rebased onto current `main`, with migration renumbered to `000643`.

### Changes

- Add `templates.browser_only` (default `false`) to the database, SDK, and template create/update APIs.
- Require the `browser_only` entitlement to enable the setting, but allow disabling and continue enforcement after license expiry.
- Reject agent coordinate connections with 409 and enforce per-template tunnel restrictions through `AuthorizeTunnel`.
- Return non-fatal tunnel policy errors in both AGPL coordinator and pgcoord, preserving other active tunnels on shared connections.
- Exclude browser-only workspaces from Desktop workspace updates and enforce the restriction in MCP agent connections.
- Fix `TestMigration000617ConnectionLogsMethod` to use raw SQL, avoiding schema compatibility issues.

### Open questions

- **Naming:** Keep `browser_only` or use `require_browser_connections`?
- **Performance:** `AuthorizeTunnel` adds a database query under the coordinator mutex. Consider a narrower query if needed.
- **Feature reporting:** Should the feature report as enabled when any template uses it?

### Out of scope

Dashboard UI, CLI flag, and Terraform provider support (requires a separate `coder/terraform-provider-coderd` change).

### Verification

- Relevant unit and integration tests passed, including coordinate rejection, tunnel isolation, workspace filtering, and non-fatal policy errors in both coordinators.
- `golangci-lint` passed with no issues.
- Regenerated database, SDK TypeScript, Swagger/API reference, and audit-log artifacts.
- Not manually verified with Coder Desktop, multi-node deployments, workspace proxies, or UI.

### AI disclosure

Most changes and the rebase were completed with Claude Code (Opus 5/5.5), following the [AI contribution guidelines](https://coder.com/docs/about/contributing/AI_CONTRIBUTING).
2026-11-18 22:07:12 +00:00
Nick Vigilanteandcoder[bot] 579b9995e8 fix: document WebSocket routes as 101 responses in the Swagger spec (#30125)
Six WebSocket routes were documented as `200` responses: `chats/watch`,
`chats/{chat}/stream`, `chats/{chat}/stream/git`,
`chats/{chat}/stream/parts`, `workspaces/{workspace}/watch-ws`, and
`workspaceagents/{workspaceagent}/watch-metadata-ws`.

Mark them `@Success 101`, matching the other WebSocket routes, and
describe each message. `chats/{chat}/stream` and `stream/parts` send a
JSON array batch of events per message, so they keep `{array}`; the
others send one event per message.

Also document that the previous template version route returns `204`
with no body when there is no previous version.

Part of DOCS-1122, split from #30121.

<details>
<summary>CI flakes unrelated to this change</summary>

On `d23267b7c3`, two checks failed in code this PR does not touch.

-
[`TestChatTurnStopsAtStepLimit/Default`](https://github.com/coder/coder/actions/runs/40809166900/job/123235512188)
in `coderd/x/chatd` (test-go-pg, ubuntu): this PR changes only Swagger
comment annotations and generated docs, and does not touch the `chatd`
package.
-
[`updateWorkspace.spec.ts:76`](https://github.com/coder/coder/actions/runs/40809166900/job/123235512158)
(test-e2e): this PR changes no UI code, and the test exercises workspace
parameter updates.

</details>

---
🤖 Built with AI assistance.

---------

Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com>
2026-11-18 14:05:18 -05:00
Jaayden Halko 17a2b62205 feat: add an API to attach templates to chat projects (#30754)
Adds the API for attaching workspace templates to a chat project, on the
schema and queries in #32309. A project can attach templates, turn on a
limit that restricts its chats to them, and set a default template with
either a default preset or default parameter values. Attaching a
template never grants access to it: every reader is checked against the
template's own sharing. This PR stores and returns `limit_templates`;
#32310 enforces it.

- The limit is opt-in. `limit_templates` is off unless a request turns
it on, which is what every existing project gets.
- Templates are attached and detached one at a time with `PUT` and
`DELETE /chats/projects/{project}/templates/{template}`, so a caller
never replaces a list they can only partly see. Attaching needs project
`update` and template `use`. Detaching needs project `update` and
template `read`, and a template the caller cannot read is reported as
not found. `POST /chats/projects` accepts `template_ids`,
`limit_templates`, and `default_template` for the new project.
- `PATCH /chats/projects/{project}` sets `limit_templates` and
`default_template`, and no longer changes which templates are attached.
The default must be an attached template the caller can read, and its
preset must belong to the template's active version. Default parameter
names and values are checked against that version for templates on the
classic parameter flow; dynamic parameters are checked when a workspace
is built. Detaching the default template clears the default.
- Project responses list only the attached templates the caller can
read, as `templates`, and count the rest as `hidden_template_count`.
`default_template` is omitted when the caller cannot read it. Deleted,
deprecated, and agent-disabled templates are left out and are not
counted as hidden.
- Editing uses `chat_project:update`, which the project owner and the
project `admin` ACL role have.
- Attaching and detaching are audited as writes to the project, with the
template list before and after, including the templates attached while
creating a project. Changes to `limit_templates` and the default
template are part of the project's own audit diff.

Not included: showing which project members lack access to an attached
template, and MCP server attachments.

Stack (merge top to bottom):
- #32309
- #30754 👈
- #32310
- #30755
- #32371
- #32372
- #30756
- #32373
- #32374
- #32375
- #30898
- #32376
- #32377
- #32378
- #32379
2026-11-18 20:36:34 +07:00
7c7e2e73cf feat: honor disable-model-invocation in uploaded skill content (#31159)
Addresses @ethanndickson's [review comment on
#30882](https://github.com/coder/coder/pull/30882#discussion_r4344815088):
the same `SKILL.md` file could be manual-only in Claude Code and the
project dialog but automatic in Coder, because the server and the
browser each handled `disable-model-invocation` in their own way.

The server now owns the key for personal, organization, and project
skills:

- When a create or update request leaves `model_invocable` unset,
`disable-model-invocation: true` in the content turns automatic use off,
and `false` turns it back on. The key is read with the function
workspace skills use, so a file gets the same setting in both places.
Only YAML booleans count, so a quoted `"true"` is ignored.
- An explicit `model_invocable` in the request always wins.
- New content without the key leaves the setting unchanged, so editing
text never turns it back on.
- Content is stored as uploaded. Every API response returns content
whose key agrees with `model_invocable`: when the stored file says
otherwise, the server replaces the value of the key or adds the key
before the first one, and leaves every other byte alone.
- **Download** and **Export all** save the content the API returns, so
the browser no longer edits the file. `withDisabledModelInvocation` is
removed.
- An upload is rejected with a 400 when the key holds a value the server
can't replace with a boolean, such as a list. A later change to
`model_invocable` can then always reach the file.

Two edges:

- Adding the key makes the returned file about 30 bytes larger, so a
file at the 64 KB upload limit can be too large to upload again.
- A skill stored before the upload check with a value the server can't
replace is returned as stored.

Workspace skills already honor the key since #31147.

#31160, the frontend PR on top of this one, adds the switch to the
personal and organization skill editors.

> Generated by an agent on behalf of the user

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Nick Vigilante <nickvigilante@users.noreply.github.com>
2026-11-18 14:04:49 +07:00
Ben Potter ed9e9a84ec docs: add sandbox agents guide and startup time tips (#32280)
Adds a "Sandbox agents" guide under Extending templates, and adds
startup time tips from the [Improving Coder Workspace Startup
Times](https://www.youtube.com/watch?v=-xcVJQWVCxs) livestream to the
speed-up templates guide.

**Sandbox agents**
(`docs/templates/extending-templates/sandbox-agents.md`) is organized
around three traits: kernel, network, and secrets isolation, plus fast
startup. Each trait has a short methods table with tradeoffs, plus
examples and references.

- Starts with the coder-labs registry templates (agent-sandbox, Plain
Sandbox, OpenShell) that implement all three, and calls out
[agent-sandbox](https://agent-sandbox.sigs.k8s.io/).
- Explains what the sandbox covers for CLI Agents, Coder Agents, and
Agent Relay.
- Shows how to define sandbox profiles as immutable parameters with one
preset each, and how to control which profile an agent gets.
- Kernel: gVisor, Kata, and EKS Nitro Sandboxes (`isolated-sandbox`
RuntimeClass in EKS Auto Mode).
- Network: separate proxy Pod vs. sidecar, example rules using an
internal GitHub and artifact store, and a cloud firewall layer (AWS
Network Firewall, Route 53 Resolver DNS Firewall) that also limits DNS.
- Secrets: `api_key_scope = "no_user_data"`, a scoped AI Gateway token
(skipped for prebuilds, optional `lifetime`), per-workspace EKS Pod
Identity, and just-in-time credentials from Vault.

**Speed up templates** (`docs/workspaces/speed-up-templates.md`) gets
new sections for pre-warming Kubernetes nodes (with GKE, EKS, and AKS
alternatives), building tools into the image, prebuilt workspaces
(including one preset for each configuration), and skipping the
Kubernetes rollout wait (with coder-logstream-kube to surface Pods that
can't start). It links the
[fast-workspaces-lab](https://github.com/coder-contrib/fast-workspaces-lab)
repo for the sample base image, node schedule, and prebuild templates.

**Agent Firewall** gets a notice on its index page and in the glossary
that it is being phased out, pointing to the sandbox guide. The sandbox
guide doesn't mention Agent Firewall.

Two diagrams in the speed-up templates guide come from the talk's slide
deck, cropped to the diagram.

Notes for reviewers:

- The scoped AI Gateway token (`user:read_personal`) isn't tied to a
workspace, so with several organizations, AI Gateway uses the user's
effective group for budgets. The page doesn't mention this.
- The Nitro (coder/registry#1253) and Cilium (coder/registry#1254)
registry templates are still open, so they aren't linked yet.

<details>
<summary>Decisions and checks</summary>

- **Structure:** three traits, several ways to get each, and simple
tradeoffs.
- **Sysbox** is not listed as kernel isolation, because system calls
still reach the node's kernel.
- **Deployments** stay the recommendation over bare Pods, because
`wait_for_rollout` and coder-logstream-kube cover the startup and error
cases.
- **Token lifetime** is left commented out in the example: Coder can't
revoke the token at stop, and a lifetime shorter than autostop breaks
running workspaces.
- **Process logging** wording: the eBPF sidecar runs inside the sandbox
with gVisor, Kata, or Nitro, so the page asks readers to test it.
- **"CLI Agents"** is kept as the term for agents that run fully in the
workspace.
- **Verified in code:**
- `mutable = false` is enforced on later builds
(`coderd/dynamicparameters/resolver.go`).
- Presets match by subset, also without a `preset_id`
(`coderd/database/queries/prebuilds.sql`, `coderd/workspaces.go`).
- `no_user_data` blocks the Git SSH key and external auth
(`coderd/gitsshkey_test.go`, `coderd/externalauth_test.go`).
- Token creation is rejected for the prebuilds system user
(`coderd/apikey.go`), and the default token lifetime is 7 days
(`codersdk/deployment.go`).
- No Coder code sets `CODER_SESSION_TOKEN` in a workspace; registry
modules such as `coder-login` do.
- **Checks run:** `make lint/emdash`, `make lint/docs-html`, `make
lint/docs-manifest`, markdownlint, markdown-table-formatter, Vale (0
errors), and the pre-commit hook.

</details>

🤖 This PR was generated by Coder Agents on behalf of @bpmct.
2026-11-17 13:52:32 -06:00
Nick Vigilanteandcoder[bot] da64286fe3 docs: fix GerundHeading, Semicolons, and UnitSpacing findings (#31990)
Fixes the `warning`-level findings that the Vale findings spike review
marked valid:

- **`Coder.GerundHeading`**: `docs/.style/styles/Coder/README.md`,
"Authoring a new rule" is now "Author a new rule". Nothing links to the
old anchor.
- **`Coder.Semicolons`**:
`templates/extending-templates/docker-in-workspaces.md`. Each semicolon
is now a sentence break, with the new sentence on its own line.
- **`Coder.UnitSpacing`**: added `&nbsp;` between number and unit in
`get-started/index.md` (10 minutes), `mcp-server.md` (5 minutes),
`ai-governance/ai-gateway/setup.md` (60 days), and
`reference/feature-stages.md` (60 seconds).

These three rules now have 0 findings in `vale docs/`, and the changed
files have no new findings from other rules.

---
AI-generated by Superblink on behalf of @nickvigilante.


Supersedes #31877, reopened under a human author for attribution.

Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com>
2026-11-17 13:17:25 -05:00
Susana Ferreira 3211ca066e feat: add organization unpriced AI models endpoint (#31753)
## Description

Adds the experimental `GET
/api/experimental/organizations/{organization}/ai/model-prices/unpriced`
endpoint behind the "N models not set up" warning on the organization AI
spend page
([Figma](https://www.figma.com/design/6TkixpkUIM5Qv6I7qhM3xZ/AI-Gov---user-spend?node-id=70-11964&t=KQwENGjcQvVT9qkh-4)).
It lists the models used in the period that still hold no price in the
organization, using the query from this stack.

## Changes

- Add the `organizationUnpricedAIModels` handler and
`ExperimentalClient.OrganizationUnpricedAIModels`:
- Reuses `aiSpendRetainedPeriod`, since token usage is subject to data
retention.
- Returns the applied period, `count`, and `models` (provider name,
display name, icon and type, model, token count), most unpriced tokens
first.
- Requires read on the organization's model prices (owners and
organization admins), so the UI only requests it for users who can set
prices.
- Add handler tests for the response, period validation, organization
scoping and role access.

Note: pagination will be added in a follow-up.

Closes AIGOV-730

> [!NOTE]
> Generated by Coder Agents on behalf of @ssncferreira.
2026-11-17 15:34:04 +00:00
Jaayden Halko 4866d0fb1f feat: add display names to project skill actions (#31747)
closes CODAGT-1506

Project skill action chips show the skill's slug (`deploy-bot`,
`security-review`), because skill names must be kebab-case. This adds an
optional display name that labels the chip instead.

Project skills get a `display_name` column, set through `display_name`
on the create and update requests. It is limited to project skills (the
same rule as `action`), trimmed, single line, and at most 64 Unicode
code points. The chip, its tooltip, and the "More" menu show the display
name, sort by it, and fall back to the skill name when it is empty. When
a display name is set, the tooltip and the menu item also show the
`/name` slash command, so actions that share a display name stay
distinguishable. Clicking an action still inserts `/name`, and the `/`
menu is unchanged.

The project skill editor shows a **Display name** field under **Show as
action** only while that switch is on. Turning the switch off hides the
field but keeps its value, and saves omit `display_name` while the
action is off, so the stored value stays. The display name lives in the
database rather than SKILL.md frontmatter, so downloading and
re-importing a skill does not carry it.

To share the code-point length check with the editor, `countCharacters`
and `maxCharacters` move from `ChatProjectDialog.tsx` into
`site/src/utils/formUtils.ts`.

<img width="637" alt="Project skill editor with the Display name field
under Show as action"
src="https://raw.githubusercontent.com/coder/coder/assets/pr-skill-action-display-name/pr/edit.png"
/>

<img width="520" alt="Action chips labeled with display names, with the
tooltip open"
src="https://raw.githubusercontent.com/coder/coder/assets/pr-skill-action-display-name/pr/chips.png"
/>

Refs CODAGT-1506
2026-11-17 17:55:35 +07:00
Nick Vigilante 6e2ff20d00 docs: document patch release and backport policy (#31993) 2026-11-16 20:00:39 -05:00
Ethan 3795d72713 fix: search AI Gateway models and clients by substring (#32159)
Closes AIGOV-801

Typing `hai` into the model filter on the AI Gateway sessions page shows
the haiku models for a moment, then "No models found". Whilst the
debounced request is pending, the menu filters the options it already
has by a case-insensitive substring, but `GET /api/v2/ai-gateway/models`
only matched a case-sensitive prefix, and Bedrock identifiers start with
`anthropic.`. The client filter matched the same way, so it had the same
problem.

To fix, both endpoints now match a case-insensitive substring.

This needed one change to the model menu. When the page loads with a
model already in the filter, the menu used to look that model up on the
server, by searching for its name and taking the first result. That's
the same pattern as the user filter, where the lookup fetches the
avatar, but a model option needs nothing from the server, so all it did
was check that the model exists. With a substring search, the first
result for `claude-3-5-sonnet-20241022` can be
`anthropic.claude-3-5-sonnet-20241022-v2:0`, so the check would fail for
a model that does exist. The menu now skips the lookup and just shows
the model from the filter as selected. The only visible difference is
that a model name in the URL that doesn't exist now shows as selected,
instead of "All models". The client menu has the same lookup, which
still works, as no client name contains another, so I've left it alone.

The prefix match was added in #22230 (models) and #22694 (clients) so
the queries could use the B-tree indexes. That only works on a C
collation database, and only for models, as the clients query wraps the
column in `COALESCE`. On an `en_US.utf8` database it's a plain filter
either way. On a C collation database a model search with no matches
does get slower, from instant to a few seconds with 5M synthetic rows,
but I think that's worth it for a search that works.
2026-11-17 11:52:12 +11:00
McKayla はな 0be6e7a034 feat: add a setting for web terminal font size (#32027) 2026-11-16 15:03:30 -07:00
Jon Ayers 96e91a4d6a chore(docs): update release docs for v2.37.14 (#32250) 2026-11-16 00:27:10 -06:00
Jon Ayers 0d53f090d0 chore(docs): update release docs for v2.34.21 (#32249) 2026-11-16 00:26:43 -06:00
Jon Ayers 75e2519022 chore(docs): update release docs for v2.39.4 (#32246) 2026-11-16 00:26:26 -06:00
Jon Ayers 5645e68015 chore(docs): update release docs for v2.38.10 (#32247) 2026-11-16 00:18:41 -06:00
Jon Ayers e45fe9d8dc chore(docs): update release docs for v2.29.29 (#32248)
Automated docs update for v2.29.29 release.

Created by `releasetui`.
2026-11-16 01:17:42 -05:00
Jon Ayers 6f169d86a9 chore(docs): update release docs for v2.29.28 (#32234)
Automated docs update for v2.29.28 release.

Created by `releasetui`.
2026-11-16 00:20:08 -05:00
Nick VigilanteandBen Potter 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>
2026-11-13 21:34:59 +00:00
Nick Vigilante bd268cb28d feat: add output formats to coder organizations members edit-roles (#30145)
Uses the `cliui` output helpers from #30508.

`coder organizations members edit-roles` printed only `Member roles
updated to [...]`, while `members list` supports `-o table|json` and
`-c`.

It now accepts `-o text|table|json` and `-c`.
Table and JSON show the updated member using the `members list` row type
and columns.

**Behavior change:** Additive.
Default text output is unchanged.
The command now fetches the member after updating roles, on every
invocation; if that read fails, it exits with an error even though the
roles were already updated.

<details>
<summary>Decisions</summary>

- The update endpoint doesn't return user data, so the member is re-read
to build the table and JSON rows.

</details>

Closes [CLI-27](https://linear.app/codercom/issue/CLI-27)

_This PR was generated by Coder Agents on behalf of @nickvigilante._
2026-11-13 14:33:32 -05:00
Nick Vigilante 32e1f2502f feat: add JSON output to coder tokens create (#30135)
Uses the `cliui` output helpers from #30508.

`coder tokens create` printed only the new token's secret, so scripts
had to call `tokens view` afterwards to get the token's ID, expiry, and
scopes.

This adds `-o/--output` with `text` (default) and `json`.
The JSON document contains the token's metadata from `APIKeyByID` plus
the one-time `key`.

**Behavior change:** Additive.
The default output is still just the secret, so `$(coder tokens create
...)` keeps working.
The command now makes one extra API call after creating the token; if it
fails, the command prints a warning to stderr and still outputs the
secret rather than exiting with an error.

<details>
<summary>Decisions</summary>

- The metadata lookup uses the key ID parsed from the `<id>-<secret>`
token, the same convention `tokens view` and `tokens remove` use.
- A failed metadata lookup never fails the command, because the token
already exists and the secret can't be shown again.

</details>

Closes [CLI-14](https://linear.app/codercom/issue/CLI-14)

_This PR was generated by Coder Agents on behalf of @nickvigilante._
2026-11-13 12:45:32 -05:00
Spike Curtis 4f6a56427e feat: report pubsub health from the pubsub backend (#31621)
Fills in the `pubsub` section of the deployment health report on the
server. Stacked on #31620.

- New `pubsub.ReportingPubsub` interface: `Pubsub` plus
`HealthReport(ctx) healthsdk.PubsubReport`. The `Pubsub` interface
itself is unchanged.
- The PostgreSQL, NATS and in-memory backends implement it. Each reports
its backend name (`postgres`, `nats` or `memory`) and its connection
state:
- **PostgreSQL:** tracks the `pq` listener's connected state from its
event callback. When it's not connected, the report has severity
`warning` and `EPS01`.
- **NATS:** warns with `EPS02` if the embedded server isn't `Running()`,
and with `EPS01` for each publish or subscribe connection whose
`Status()` isn't `CONNECTED`.
  - **In-memory:** always `ok`.
- `coderd.Options.Pubsub` is now a `ReportingPubsub`.
`ReplicaSyncPubsub` stays a plain `Pubsub`.
- `coderd/healthcheck` has a new `Pubsub` check, which counts toward
`healthy` and the overall severity like the other sections.
`formatHealthcheck` applies the dismissed setting for it.
- New health codes `EPS01` (not connected) and `EPS02` (embedded NATS
server not running), documented in
`docs/admin/monitoring/health-check.md`.
- Test helpers follow the type change: `coderdtest.Options.Pubsub` and
the pubsub returned by `dbtestutil.NewDB` are now `ReportingPubsub`, and
a few test wrappers embed `ReportingPubsub` instead of `Pubsub`.

<details>
<summary>Decision log</summary>

- `HealthReport` returns a `healthsdk.PubsubReport` rather than filling
one in place. This matches the `healthcheck.Checker` methods. `ctx` is
unused for now.
- The healthcheck layer sets `Dismissed`, so backends don't need to know
about health settings.
- Problems are reported as warnings, not errors, so they show on the
health page without marking the deployment unhealthy. Both backends
reconnect on their own.
- Postgres connection state comes from the listener event callback, not
from `pq.Listener.Ping`, so the health check doesn't do database I/O.
Closing the pubsub also marks it disconnected.
- NATS `conn` gains `Status()`, which `*natsgo.Conn` already implements.
The pools are immutable after construction, so `HealthReport` reads them
without locking.
- The docs say the pubsub section appears in the JSON response, because
the health UI doesn't show it until a later PR in this stack.
- psmock is not regenerated: none of its users pass it to coderd.

</details>

---
Generated by Coder Agents on behalf of @spikecurtis.
2026-11-13 17:20:31 +01:00
Spike Curtis 2187ecd37e feat: add PubsubReport to healthsdk HealthcheckReport (#31620)
Adds pubsub to the deployment health report types in `healthsdk`:

- New top-level `pubsub` section (`PubsubReport`) in
`HealthcheckReport`. It embeds `BaseReport` and adds one field,
`backend` (string).
- New `HealthSectionPubsub` constant, added to `HealthSections` so the
section can be dismissed.
- `HealthcheckReport.Summarize` includes pubsub errors and warnings,
which `coder support bundle` prints.

This is the first PR in a stack for GRU-100. It only changes the SDK and
the files generated from it (Swagger, API docs, `typesGenerated.ts`),
plus the two frontend health mocks that need the new required field. The
server does not fill in this section yet. That comes in a follow-up PR.

<details>
<summary>Plan</summary>

- Add `PubsubReport { BaseReport; Backend string }` to
`codersdk/healthsdk`.
- Add `Pubsub PubsubReport \`json:"pubsub"\`` to `HealthcheckReport`.
- Add `HealthSectionPubsub` and include it in `HealthSections`.
- Include `Pubsub` in `HealthcheckReport.Summarize`, with test coverage.
- Regenerate TS types, Swagger and API docs.
- Follow-up PRs: populate the report in `coderd/healthcheck` (including
severity and dismissal handling) and update the health UI.

</details>

---
Generated by Coder Agents on behalf of @spikecurtis.
2026-11-13 17:20:31 +01:00
J. Scott MillerandGarrett Delfosse 38e74c4506 feat: add agent-plugins experiment and Agent API v2.17 plugin messages (#29320)
Linear:
[CODAGT-1101](https://linear.app/codercom/issue/CODAGT-1101/agent-plugins-read-only-support-behind-the-agent-plugins-experiment)

**tl;dr:** Adds the `agent-plugins` experiment and the Agent API v2.17
messages that carry Agent Plugins data from the agent to coderd. First
of eight stacked PRs adding read-only [Agent
Plugins](https://agent-plugins.org/) v1.0.0 support.

A plugin is a directory with a `plugin.json` manifest, skills under
`skills/`, and an optional `mcp.json`. Across the stack, the agent
discovers plugins in `plugins/` and `.agents/plugins/` under its scan
roots (for example `~/.coder/plugins/<name>`), chatd lists their skills
with plugin attribution, the agent runs the MCP servers of plugins in
the workspace working directory, and the Agents page shows plugin
attribution in the chat context. Hooks, commands, agents, install flows,
and org-managed plugins are out of scope. Background:
[research/agent-plugins-standard.md](https://github.com/coder/scott-misc/blob/main/research/agent-plugins-standard.md)
(internal).

This PR adds `codersdk.ExperimentAgentPlugins` and a `PluginBody` oneof
variant on `ContextResource` (tag 18) that carries the validated
manifest fields and nests the plugin's skills and MCP servers.
`Manifest` gains `agent_plugins_enabled` (field 23), which coderd sets
when the experiment is enabled; the agent discovers plugins only then.
coderd stores each nested resource as its own row with the plugin's name
in a new `plugin_name` column (migration 000642), which the hydrate, MCP
sync, and re-pin queries copy. With the experiment off,
`PushContextState` drops plugin resources and everything nested in them.
Otherwise it rejects pushes with plugin names that fail
`workspacesdk.ValidatePluginName` (the spec's name grammar, shared by
agent and coderd), OK plugins without a name or with a duplicate name, a
non-OK plugin that nests resources, nested entries of the wrong kind,
plugin skill sources outside `<plugin source>/skills/`, and plugin MCP
servers with an empty `server_name` or a source other than `<plugin
name>/<server_name>`. Nested resources count toward the 1000-resource
cap.

Agents now dial v2.17, so a new agent needs a coderd that supports it,
as with every Agent API minor. Turning the experiment off does not
remove plugin data already pinned to existing chats.

<!-- pr-map:start -->
<details><summary>PR map</summary>

`main..4b0cfc9657`

| Category | Files | + | - |
|---|---:|---:|---:|
| prod (backend) | 15 | 342 | 78 |
| test (backend) | 9 | 534 | 3 |
| migrations | 2 | 14 | 0 |
| generated (backend) | 7 | 1216 | 1027 |
| generated (frontend) | 1 | 2 | 0 |
| **Total** | 34 | 2108 | 1108 |

1. `coderd/agentapi/context.go` (+211/-51, API): drops plugin resources
when the experiment is off; otherwise validates plugin names and
nesting, and stores each nested skill and MCP server as its own row with
the plugin's name.
2. `agent/proto/agent.proto` (+39/-9, API): `PluginBody` with nested
`skills` and `mcp_servers`, and `Manifest.agent_plugins_enabled`.
3. `codersdk/workspacesdk/frontmatter.go` (+31/-0): `ValidatePluginName`
and `MaxPluginNameLength` (manifest name grammar).
4. `coderd/database/queries/chats.sql`, `workspaceagentcontext.sql`,
migration 000642 (+28/-7, DB): the `plugin_name` column on both context
resource tables, copied by the hydrate, MCP sync, and re-pin queries.
5. `codersdk/agentsdk/agentsdk.go`, `agent/agent.go` (+18/-4, API):
`Manifest.AgentPluginsEnabled` and `ConnectRPC217WithRole`; the agent
dials v2.17.
6. `coderd/agentapi/api.go`, `manifest.go` (+4): the manifest flag
follows the experiment.
7. `tailnet/proto/version.go` (+8/-1, API): Agent API v2.17.
8. `codersdk/deployment.go` (+4, API): the `agent-plugins` experiment.

</details>
<!-- pr-map:end -->

---

This PR was generated by Coder Agents on behalf of @jscottmiller.

Co-authored-by: Garrett Delfosse <delfossegarrett@gmail.com>
2026-11-13 10:39:16 -05:00
Mathias Fredriksson d639ced1e0 fix: send only changed chat history over the stream (#29662)
A client could resume the chat stream only with after_id, a message
ID. A message ID does not identify what a client has received. A
reconnect could skip a message that another client sent, send no
history_reset for an edit the client missed, or resend the whole
history.

A client can now resume with the chat's snapshot_version, which the
newest messages page returns and the stream's events then include.
The stream sends what changed at that version or later. For an edit
it sends the ID of the edited message and the messages written
since, not the whole history. A stream opened without
snapshot_version sends the same events as before.

A write outside a chat state transition does not increase
snapshot_version, and a stream can miss it. The queries that only
tests used for such writes are removed.

When the stream cannot be set up, the server now returns 500 before
the WebSocket upgrade. It used to upgrade and send an error event,
which the web client shows as a chat error.

The Tasks to Chats migration guide told clients to reconnect with
after_id. It now describes snapshot_version.
2026-11-13 13:02:38 +02:00
Susana Ferreira 30abd0593c feat: add organization AI spend overview endpoint (#31709)
## Description

Adds the experimental `GET
/api/experimental/organizations/{organization}/ai/spend` endpoint that
backs the new Overview tab of the organization AI spend page ([Figma
design](https://www.figma.com/design/6TkixpkUIM5Qv6I7qhM3xZ/AI-Gov---user-spend?node-id=12-5152&t=YlCC7RGSMNrzMxVo-4)).
It returns the organization's spend summary, daily spend, and a page of
users with their per-group spend, using the queries from #31711.

## Changes

- Add the `organizationAISpend` handler and
`ExperimentalClient.OrganizationAISpend`:
- Reuses the period handling of `/ai/spend/users`: `period_start` and
`period_end` must be provided together and span at most 31 days, and the
default is the current budget period.
- Also requires both bounds at 00:00:00 UTC, since the daily spend
aggregate holds whole UTC days.
- Is not limited by the AI Gateway data retention window, since the
daily spend aggregate is not purged. `/ai/spend/users` and the export
keep the retention check, now in `aiSpendRetainedPeriod`.
- Returns `count`, `totals` (`spend_micros`, `median_spend_micros`),
`intervals` (daily spend, one interval per UTC day, zeros included), and
`users` (paginated with `limit`/`offset`, most spend first, with
per-group spend).
- Echoes the applied period, and reads every value in one read-only
repeatable-read transaction so the values agree.
- Extract `parseOrganizationAISpendPage`, shared with `/ai/spend/users`.
- Add handler tests.

Closes AIGOV-728

> [!NOTE]
> Generated by Coder Agents on behalf of @ssncferreira.
2026-11-13 10:02:58 +00:00
Nick VigilanteandJeremy Ruppel 3def3bf5a3 feat: add JSON output to coder provisioner keys create (#30152)
Uses the `cliui` output helpers from #30508.

`coder provisioner keys create` printed the new key's secret as prose,
so scripts provisioning external provisioners had to scrape it and look
up the key's ID and tags separately.

It now accepts `-o text|json`.
JSON is the key as `provisioner keys list` shows it (ID, name,
organization, tags, created at) plus the one-time `key`.

**Behavior change:** Additive.
Default text output is unchanged.
The command now fetches the new key's metadata with the returned secret
(`GET /api/v2/provisionerkeys/{key}`). If that fails, it prints a
warning to stderr, falls back to the name, organization and tags it sent
(leaving `id` and `created_at` unset), and still outputs the secret.

<details>
<summary>Decisions</summary>

- `CreateProvisionerKey` only returns the secret, so the key's metadata
comes from `GetProvisionerKey(secret)`, the same lookup `coder
provisioner start` uses. This replaced an earlier list-and-match-by-name
approach, per review.
- A failed lookup never fails the command, because the key already
exists and the secret can't be shown again.

</details>

Closes [CLI-36](https://linear.app/codercom/issue/CLI-36)

_This PR was generated by Coder Agents on behalf of @nickvigilante._

---------

Co-authored-by: Jeremy Ruppel <jeremyruppel@users.noreply.github.com>
2026-11-12 08:58:37 -05:00
Thomas Kosiewski e307f1d5cf feat: add the user-scoped chat-automations experiment (#32064)
## Why

The Automations RFC controls availability with one user-scoped
experiment. Its text: "The user-scoped `chat-automations` experiment
controls availability. Operators configure defaults with `--experiments`
and can change per-user rules while Coder is running. Each surface
checks the relevant caller or automation's owner, and experiment
evaluation fails closed." The later backend PRs (management routes, the
`manage_automations` tool, `Publish`) need that check first. This PR
registers the experiment and proves the per-user, fail-closed check.
Nothing consumes it yet.

Part of CODAGT-1135

## What changed

- Registers `chat-automations` in `ExperimentsKnown` and
`ExperimentsUserScoped`. An earlier experiment with this name was
removed in #30412, and this PR restores none of its consumers.
- Keeps it out of `ExperimentsSafe`, so `--experiments=*` does not turn
it on. Automations act with their owner's authority, and a test pins the
choice.
- Adds the name to the `userScopedExperimentStaticCheck` ruleguard rule,
so server code cannot decide it from the static list.
`TestExperimentsUserScopedRuleguard` keeps the rule in step with
`ExperimentsUserScoped`.
- Regenerates the swagger files, `docs/reference/api/schemas.md` and
`typesGenerated.ts`.
- Adds tests for the real experiment name. The evaluator tests cover the
startup default, stored `on`, `off` and condition rules for two users,
and an off decision on a rules read error, a malformed rule, an unknown
mode, an attribute read error, a condition error and a nil subject. A
coderd test with a real database checks the same per-user behavior
through `api.ExperimentEvaluator` and `GET /api/v2/experiments`.

## Scope

No routes, tool, UI or chatd change. I added no helper:
`Evaluator.Enabled(ctx, userID, ex)` already decides per user and fails
closed, and API handlers reach it through `api.ExperimentEvaluator`.
chatd has no evaluator handle on main, because #31327 removed the unused
field. The first chatd consumer adds it together with its read.

## Blast radius

With the experiment off, which is the default, behavior on main does not
change. Two things become visible. `GET
/api/experimental/experiments/rules` and `coder exp experiment-rules
list` show a `chat-automations` row, and an administrator can store a
rule for it. A deployment that already passes
`--experiments=chat-automations` sees three small differences: the
startup log reports an opted-in hidden experiment where it reported an
unknown one, the deployment Overview page stops flagging the name as
invalid, and the rules row shows the static default as on. Nothing reads
the experiment yet, so no feature turns on.

## Live check

A local `./scripts/develop.sh` deployment built from this head ran with
no flag, with `--experiments=*` and with
`--experiments=chat-automations`. `GET /api/v2/experiments` lists
`chat-automations` for the owner and for a member only when the startup
list or a rule turns it on, and `--experiments=*` does not turn it on. A
condition rule `user.username == "member"` turned it on for the member
and off for the owner without a restart, and `reset` restored the
startup default.

---
_Generated with [`xum`](https://github.com/coder/xum) • Model:
`anthropic:claude-sonnet-5-5` • Thinking: `xhigh`_
2026-11-11 23:54:05 +01:00
Ehab Younes 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
2026-11-11 15:02:18 +00:00
Molly Fraser 0a7ef88af9 feat: add option to disable the embedded AI Gateway (#31967)
Adds `--ai-gateway-embedded-enabled` /
`CODER_AI_GATEWAY_EMBEDDED_ENABLED` (default `true`) so standalone-only
deployments can stop `coderd` from starting the in-memory AI Gateway.

`CODER_AI_GATEWAY_ENABLED` stays the global switch: the AI Gateway
entitlement, `/api/v2/ai-gateway/serve`, and cost-control metrics still
depend only on it. The embedded daemon now starts only when both options
are `true`.

| `ENABLED` | `EMBEDDED_ENABLED` | Result |
|---|---|---|
| `true` | `true` | Unchanged |
| `true` | `false` | No embedded gateway; standalone gateways keep
working |
| `false` | any | No AI Gateway |

Refs AIGOV-514

## Open questions for reviewers

- **Coder Agents does not work with the embedded gateway disabled.**
`chatd` still starts, but model calls fail with "AI Gateway transport
factory is not configured" because there is no in-process transport.
AIGOV-597 (routing Agents through standalone gateways) was canceled. The
docs and option help state that Agents requires the embedded gateway. Is
that acceptable, or should `chatd` also be turned off in this mode?
- **Option name:** the ticket proposed
`CODER_AI_GATEWAY_EMBEDDED_ENABLED` tentatively. OK to keep?

## Verification

```
$ go test ./cli/ -run 'TestServer_AIGateway' -count=1
ok      github.com/coder/coder/v2/cli   0.518s
$ go test ./enterprise/coderd/ -run 'TestAIGatewayServe' -count=1
ok      github.com/coder/coder/v2/enterprise/coderd     0.755s
```

`TestServer_AIGatewayEmbedded` fails when the new check is removed.

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

- `codersdk/deployment.go`: new option and
`AIBridgeConfig.EmbeddedEnabled` field; updated `--ai-gateway-enabled`
description.
- `cli/server.go`: outer `if Enabled` sets up cost-control metrics and
the blocked-users collector (the standalone `/serve` endpoint uses these
too). Inner `if EmbeddedEnabled` creates the daemon, registers the
in-memory handler, and adds its cleanup.
- `cli/server_test.go`: `TestServer_AIGatewayEmbedded` covers the three
modes by checking for the embedded daemon's startup log.
- `enterprise/coderd/aibridgeserve_test.go`:
`TestAIGatewayServeEmbeddedDisabled` checks the entitlement and `/serve`
still work with embedded disabled.
- `docs/ai-governance/ai-gateway/standalone.md`: new "Disable the
embedded gateway" section.
- Remaining files are generated by `make gen`.
- Found during review: keeping metrics inside the embedded check would
have dropped cost-control metrics for standalone gateways.

</details>

---

Generated with Coder Agents; reviewed, revised, and verified by
@mollymaefraser.
2026-11-11 11:50:16 +00:00
Dean Sheather fb12d6018f fix!: redact agent environment variable values in API responses (#31932)
Workspace, build, and agent API responses (`/workspaces`,
`/workspacebuilds/{id}`, `/workspaceagents/{id}`, and so on) returned
agent environment variable values in plain text. Template authors often
pass credentials such as API tokens through `coder_env`, so anyone who
could read the workspace could read those secrets.

`db2sdk.WorkspaceAgent` now replaces every non-empty value with
`***REDACTED***` and keeps the keys. This is the same marker the support
bundle (`sanitizeEnv`) and the agent `/debug/manifest` endpoint already
use. The agent still gets the real values through its manifest
(`db2sdk.WorkspaceAgentEnvironment`), and nothing in the CLI or frontend
reads these values from the API.

Every value is redacted because neither `coder_env` nor
`coder_agent.env` in the Terraform provider has a sensitive flag, and
`proto.Env` has no field to carry one. Selective redaction would need
changes to the provider, the proto, and the database.

## For changelog

- Agent environment variable values are redacted in API responses
(#31932)

> Workspace, workspace build, workspace agent, and template version API
responses now return `***REDACTED***` for every non-empty agent
`environment_variables` value. Keys and empty values are unchanged. The
agent still receives the real values, so workspaces behave as before.
  >
> Migration: Update scripts and integrations that read agent environment
variable values from the API or from `coder list -o json`. Read the
values inside the workspace instead.

Closes ENG-1505 (coder/security#51)

<details>
<summary>Decision log</summary>

- Confirmed the leak on `main` (e1c3a21d05): `db2sdk.WorkspaceAgent`
copied `dbAgent.EnvironmentVariables` straight into
`codersdk.WorkspaceAgent.EnvironmentVariables`. Every API path that
returns an agent goes through this function.
- Redact all non-empty values, not just some. There is no secret or
non-secret marker in `terraform-provider-coder` v2.20.0 (`coder_env` has
only `agent_id`, `name`, `value`, `merge_strategy`; `coder_agent.env` is
a plain map), and name heuristics fail in both directions.
- Use `***REDACTED***` to match the existing support bundle and
`/debug/manifest` redaction. Empty values are kept, which also matches
existing behavior.
- Redact in the SDK converter only, so the agent manifest path is
unaffected.
- Regression test `TestWorkspaceAgent/RedactsEnvironmentVariables`
covers the workspace, workspace agent, and workspace build endpoints. It
fails without the fix.

</details>

> Generated by Coder Agents on behalf of @deansheather.
2026-11-11 16:51:20 +11:00
Nick Vigilante 7301cee2c4 fix: list every enum value the API can return in the Swagger spec (#30122)
The API reference is generated from Swagger comments and struct tags,
and several `enums:"..."` tags narrowed a named enum type, so the docs
omitted values the server returns. For example, `User.status` listed
only `active` and `suspended`, not `dormant`, and
`TemplateVersion.warnings` listed `DEPRECATED_PARAMETERS`, which is not
a value of the type.

Remove 34 `enums` tags that narrow or duplicate a named type so the
referenced type's full value list is used. Tags that describe an
intentional subset stay: ACL role fields (which omit the `""` deleted
sentinel used only in update requests), `APIKey.scope`, and plain-string
fields. `Template.provisioner` keeps its tag because `.swaggo` replaces
`ProvisionerType` with `string`.

Also fix enum defects that break code generators:

- The provisioner jobs and daemons `status` query parameters listed
their enum twice (Swagger 2.0 requires unique `enum` items) or with the
wrong type. Both are now `[]codersdk.ProvisionerJobStatus` and
`[]codersdk.ProvisionerDaemonStatus`, matching what each handler parses,
including comma-separated values. The daemons route previously
documented job statuses, which the handler rejects with a 500.
- Replace the `_` zero placeholder of `WatchErrorCode` with `iota + 1`,
so the spec no longer lists 0 or `x-enum-varnames: ["_", ...]`. Wire
values are unchanged.

Where the narrowed tag hid values the server returns, the SDK type now
includes them: `LoginTypeOAuth2ProviderApp`, `BuildReasonAutodelete`,
and `MissingTemplateParameter` widen the generated TypeScript unions.
The dashboard attributes `autodelete` builds to Coder like other system
builds. `APIKey.login_type` and `AuthorizationCheck.action` set explicit
examples so the generated samples stay representative.

`TestSwaggerEnumsNotNarrowed` fails when a property's enum list drops
values of its named type (other than the 15 allowlisted intentional
subsets), lists a value the type lacks, or repeats a value.

Part of DOCS-1122, split from #30121.

---
🤖 Built with AI assistance.
2026-11-10 17:42:30 -05:00
Michael SuchaczandEthan Dickson 082668fbc1 feat: run computer use on OpenAI-compatible AI providers (#31895)
Computer use only ran on Anthropic and OpenAI AI providers. Chatd
derives the tool flavor from the AI provider type, and `openai-compat`
had no flavor, so every self-hosted model was marked unavailable for
`type=computer_use`, including the model a single-provider deployment
already uses for chat.

Hosted computer tools are not an option on those servers: an
OpenAI-compatible endpoint accepts a `computer_20250124` tool over
`/v1/messages` and a `computer-use-preview` tool over `/v1/responses`
and then drops both, so the model never sees a way to act. Computer use
is now declared as an ordinary function tool for those providers. The
model sends one action per call and every call answers with a fresh
screenshot, which is the shape these models already handle through the
shared action runner. The tool omits `zoom`, which the agent desktop
cannot perform. The desktop clamps a point outside the screen to its
edge, so the tool rejects a coordinate outside the declared screenshot
with an error that states the valid range, and a model that aims off the
screen learns that it missed. Media tool results reach the model because
the pinned fantasy fork promotes them to user-role messages, so no
dependency changed.

Coder can't verify an arbitrary OpenAI-compatible model, so those models
keep the unverified warning icon in the admin UI. The virtual desktop
docs, the Coder Agents index, the chatd architecture doc, and the
organization model settings copy now list OpenAI-compatible providers as
supported, and the docs say what to check before using one.

Three shared behaviors needed fixing to make this usable. A coordinate
of `[0,0]` is the top-left pixel and decoded as an omitted field, so the
desktop rejected those clicks with a missing-coordinate error;
coordinates now decode by key presence, which also keeps an absent
coordinate absent. A `scroll_amount` of zero or less, or a key `repeat`
of zero, was also forwarded as omitted, so the desktop scrolled its
default of three clicks or pressed the key once; the runner now rejects
both, and the function tool declares a minimum of 1 for each. And
because a chat completions model sends one action per call, it plans
every call of a step against one screen, so a failed action now halts
the later calls of that step, as it already did for Anthropic. The
hosted OpenAI flavor still differs here on purpose: it delivers an array
of actions in one call. Halting would strand a mouse press whose release
was planned for a later call, so the function tool offers
`left_click_drag` instead of separate press and release actions, and
rejects any action it does not declare.

Provider types that reuse the chat completions client without being
OpenAI-compatible (Azure, Google, OpenRouter, Vercel, Copilot) stay
unsupported until each is verified.

> [!NOTE]
> `coderd/apidoc/docs.go`, `coderd/apidoc/swagger.json`,
`docs/reference/api/schemas.md` and `site/src/api/typesGenerated.ts` are
hand-edited to match the new enum value, because the environment that
prepared this change had no pnpm to re-run the generators. The same
environment had no node, so `pnpm run typecheck`, biome and prettier did
not run locally; CI is the validator for the `site/` change and the
generated files.

> [!NOTE]
> Prepared by Xum, Mike's coding agent, from the measurement that showed
an OpenAI-compatible server dropping both hosted computer tools.

---------

Co-authored-by: Ethan Dickson <ethanndickson@gmail.com>
2026-11-09 17:26:10 +11:00
Ethan 9fa68ac013 feat: hold every steer message while one is under edit (#31748)
Whilst a steer message is under edit, every steer message now waits, not
just the one under edit and the ones behind it.

Say Next step holds A, B and C, and you edit B. Before this, A went to
the agent at the next model call whilst B and C waited. Now nothing goes
out until the edit ends, then A, B and C go in together. If the turn
ends whilst a steer message is under edit, the chat pauses, the same as
it already does for a queue message. `GetChatQueuedMessageHead` now
returns a steer message under edit first, so the paused check still
finds it when it isn't the first row.

Queue messages are unchanged: editing one holds it and the messages
behind it.

On the site, every other row shows "Waiting" whilst a steer message is
under edit, and Enter on an empty composer won't send the first held
message whilst it's waiting on an edit. The docs are updated to match.

The first version of this PR refused edits on steer messages instead,
following [Mathias's review of
#30074](https://github.com/coder/coder/pull/30074#pullrequestreview-5352986208).
Mathias has since suggested holding the whole steer lane, so the agent
never starts working on part of what you sent.

Part of CODAGT-1140
2026-11-09 15:55:18 +11:00
Ethan a0be9d0e1d feat: make message_agent always steer (#31175)
`message_agent` no longer takes an `interrupt` flag, and always steers.
If the child is busy, it gets the message before its next model call and
keeps working. To correct or redirect a busy child, the parent just
calls `message_agent`, and `interrupt_agent` only stops it, which is the
same split the API has after #31174. The tool result also drops
`interrupted`, as it was just whether the child was running before the
send.

That was the last caller of the interrupt busy behaviour, so chatd and
chatstate drop it too. `SendMessage` never interrupts now. On a busy
chat it only ever adds the message to a lane, so the sends that moved a
running chat to interrupting, or a `requires_action` chat back to
running, are gone, along with the send's inline interruption finish for
chats with no worker. Most of the diff is deleted tests.

A steer send to a paused chat, or to an errored chat whose next message
is being edited, no longer fails with a 429 at the queue limit when it's
delivered straight away, which is whenever the message being edited is a
queue message.

Part of CODAGT-1140
2026-11-09 15:55:17 +11:00
Ethan a40ff12c8c feat!: steer chat messages by default and remove the interrupt busy behavior (#31174)
Breaking API Change for changelog:

> `POST /api/v2/chats/{chat}/messages` now steers by default. If the
chat is busy, the message is delivered before the agent's next model
call, instead of after the turn ends. `busy_behavior` accepts `steer` or
`queue`, and `interrupt` now returns a 400. To redirect the agent, just
send a message, and only call `POST /api/v2/chats/{chat}/interrupt` to
stop it. Queued messages now include their `busy_behavior`.

This is where steering becomes the default for API clients. A send
without a `busy_behavior` used to wait for the turn to end, and now it
goes in the steer lane, so the agent sees it before its next model call
and keeps going. `queue` still waits for the turn to end.

Interrupt isn't a busy behaviour any more. Since #31155 it just meant
"interrupt, then steer", so the API now returns a 400 for it, and
`codersdk.ChatBusyBehaviorInterrupt` is gone. `coder_send_chat_message`
in the MCP server gets the same default and enum. A steer message
already corrects a busy agent, and combining it with an interrupt goes
wrong in either order, so the docs and the MCP tool descriptions now say
to send a message to redirect the agent, and to interrupt only to stop
it.

Queued messages now report their `busy_behavior`, and the queue lists
the steer lane first, so clients can show which messages go in at the
next step and which wait for the turn to end. A message moved with Send
now reports `steer`.

The site doesn't send a `busy_behavior`, so its sends start steering
with this PR, but its queue UI doesn't know about the steer lane until
#31173. chatd still accepts `interrupt` internally, as `message_agent`
uses it, and #31175 removes both.

Part of CODAGT-1140
2026-11-09 15:55:17 +11:00
Kyle CarberryandJon Ayers b798061108 perf: reuse import-time lock file and cache terraform version (#29825)
Workspace builds now reuse the lock file that `terraform init` wrote
during template import, which takes a minimal Docker build from about
3.1s to 1.65s, measured from build created to agent connected.

---------

Co-authored-by: Jon Ayers <jon@coder.com>
2026-11-06 19:32:46 -06:00
coder[bot] 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>
2026-11-06 17:17:35 -05:00
coder[bot] a84f567959 docs: cut Coder.AbbreviationFirstUse false positives (#31874)
Addresses the `Coder.AbbreviationFirstUse` rows from the Vale findings
spike review. Only rows that got a verdict or a note are acted on.

## Rule exceptions

Added to `docs/.style/styles/Coder/AbbreviationFirstUse.yml`:

| Terms | Why |
|---|---|
| UUID, TTL, UTC, CI, GPU, LLM, SSO | Marked false positive:
industry-standard terms |
| JWT, RFC, NTP | Marked unsure, leaning toward an exception (NTP is
also linked out on its page) |
| DERP, OIDC, STUN | "Define it once globally": the glossary now defines
all three (added a STUN entry) |
| EC2, RDS | AWS product names (Amazon RDS is also linked out) |

The style guide's abbreviation section now says glossary-defined terms
can join the list.

## Docs fixes

- Expanded on first use: MCP (`bring-your-own-mcp-servers.md`,
`migrate-from-ona.md`), SCIM, CA, IAM (`migrate-from-ona.md`), SIEM
(`agent-relay/monitoring/index.md`), RBAC (`agent-relay/setup.md`).
- `agent-relay/claude-code.md`: "a Slack DM with Claude" is now "a
direct message to Claude in Slack". I didn't use plain "Slack message"
because a channel tag is also a Slack message, and the docs treat that
as a different session type.

## Not changed

Rows marked unsure without a note: DM on `agent-relay/slack.md` (6) and
`agent-relay/troubleshooting.md` (1), and VPC on `migrate-from-ona.md`.
Those 8 findings still fire.

`vale docs/` for this rule goes from 70 warnings to 8. The changed pages
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>
2026-11-06 16:52:01 -05:00
Ethan f8ab27ff7c feat: allow computer use on Claude models from AWS Bedrock AI providers (#31745)
Closes
https://linear.app/codercom/issue/CODAGT-1525/allow-computer-use-with-claude-models-from-aws-bedrock-ai-providers

Computer use was only available on models from Anthropic and OpenAI AI
providers, as we decided support from the AI provider type alone, in
five separate places (spawn, turn setup, override validation, telemetry
and the settings UI). A Bedrock AI provider serves Claude models over
the Anthropic Messages API though, and chatd already routes those
through the Anthropic fantasy client, so there's no reason computer use
shouldn't work on them.

To fix, there's now a single rule,
`chatprovider.ComputerUseProvider(providerType, model)`, derived from
the client chatd builds for the model (`chatprovider.ClientProvider`,
previously `aibridgeClientProvider`). If the model uses the Anthropic
client, it gets the Anthropic computer use tool. The OpenAI tool is
still only offered on OpenAI AI providers, as I haven't tested it
against Bedrock Mantle, and I couldn't find anyone else doing it either.
All five places now call this function.

The UI can't re-derive Bedrock routing without duplicating the model ID
heuristic, so `ChatModel` gets a read-only `computer_use_provider` field
(`anthropic`, `openai`, or omitted when computer use isn't supported).
The computer use model override endpoint now accepts Bedrock Claude
models, and its 400 message has changed.

Whilst in here I also fixed a latent bug where the default model
credential check looked up the user's keys under the tool flavour
(`anthropic`) instead of the provider type (`bedrock`).

One caveat: on a Bedrock AI provider using InvokeModel, AI Gateway runs
the provider's configured model rather than the chat model, whilst we
pick the computer use tool version from the chat model ID. It's not
specific to computer use, and should go away with
[AIGOV-747](https://linear.app/codercom/issue/AIGOV-747/deprecate-the-bedrock-invokemodel-protocol-with-model-translation).
In the meantime, #30752 warns when an InvokeModel provider ignores the
chat model identifier.
2026-11-06 13:12:49 +11:00
Nick Vigilante 6de3d92883 fix: correct invalid and nonexistent Swagger parameters (#30124)
Several parameter annotations produced a wrong or invalid spec.

- `GET /api/v2/settings/idpsync/available-fields` and `field-values`
documented a required `organization` path parameter that their URLs do
not contain. The annotations were copied from the organization-scoped
routes.
- `format(uuid)` on the `ids` array query parameter of the provisioner
jobs and daemons routes put `format: uuid` on the array rather than its
items. swag cannot set an item format, so the description now says the
IDs are UUIDs.
- Swagger 2.0 does not allow `example` on header parameters, which
failed strict validation. The `Authorization` and `Content-Disposition`
examples move to `x-example` vendor extensions, which Swagger 2.0 allows
on parameters and the docs generator uses for the curl samples.
- `TestSwaggerParametersValid` reads every path in the generated spec
and fails on a non-body parameter with `example`, an array parameter
with `format`, or a path parameter missing from its route.

Part of DOCS-1122, split from #30121.

---
🤖 Built with AI assistance.
2026-11-05 14:22:30 -05:00
Nick Vigilante 585485c8bf fix: document raw JSON as objects and byte fields as base64 strings (#30123)
Swagger renders `json.RawMessage` and `[]byte` fields as integer arrays,
so the API reference showed chat tool calls as `"args": [0]` even though
tool arguments and results are JSON values.

Render every `json.RawMessage` as an object with one `.swaggo` replace
rule, and tag `[]byte` fields, which JSON-encode as base64,
`swaggertype:"string" format:"byte"`. This covers
`ChatMessagePart.args`, `.result`, `.data`, `ToolResult.output`,
`DynamicTool.input_schema`, both workspace build `state` fields,
`TemplateBuilderModuleVariable.default`, and
`CreateTestAuditLogRequest.additional_fields`.

`ChatMessagePart.provider_metadata` is internal only, so it is hidden
with `swaggerignore:"true"` like its siblings. `ChatMessagePart.result`
and `ToolResult.output` can hold any JSON value, and
`TemplateBuilderModuleVariable.default` holds a string, number, or
boolean, so `object` is an approximation for all three and the field
comments say so. swag rejects an untyped `.swaggo` override for
`json.RawMessage`.

Part of DOCS-1122, split from #30121.

---
🤖 Built with AI assistance.
2026-11-05 13:15:40 -05:00
Atif Ali fb6d287528 fix: write agent host entries with config-ssh --no-wildcard (#31192)
`coder config-ssh --no-wildcard` writes one `Host` entry per workspace
and none per agent. OpenSSH only applies exact `Host` matches, so with
`--no-wildcard` (and without Coder Desktop):

- `ssh <agent>.<workspace>.<owner>.coder`, the hostname the dashboard's
**Connect via SSH** button shows and Coder Connect serves, doesn't
resolve.
- Agents in multi-agent workspaces can't be reached with plain `ssh`;
`ssh <workspace>.coder` hits "multiple agents found".

Before wildcard hosts (#14986), `config-ssh` wrote an entry per agent.
`--no-wildcard` (#26753) brought back per-workspace entries only.

## Change

With `--no-wildcard`, also write an `<agent>.<workspace>.<owner>` entry
for each agent, using the same prefix/suffix as workspace entries:

```
Host dogfood.coder                        # unchanged
Host coder.dogfood.matifali.coder         # new
Host dev.dogfood.matifali.coder           # new
```

`coder ssh --stdio` already parses `agent.workspace.owner`, so no
ProxyCommand changes are needed.

- **Non-breaking**: existing `<workspace>` entries are unchanged; agent
entries are added after them. Without `--no-wildcard` the config is
unchanged.
- **Workspaces without agents on their latest build** (stopped, or a
start that is pending or failed): known agents come from that
workspace’s most recent successful start using the same template
version, not template-import defaults. Lookups are cached per workspace
and bounded to eight concurrent requests. Missing or incompatible
history leaves only the workspace entry; lookup failures also produce a
warning.
- **Devcontainers**: while a workspace runs, its sub-agents get entries
too.
- **Validation**: workspace and owner names retain `codersdk.NameValid`
checks. Agent components permit safe ASCII letters, digits, underscores
and hyphens, preserving Terraform-precreated names such as `dev_box`
while rejecting SSH syntax, leading options and doubled-hyphen
delimiters. Workspace entries are written as before, including legacy
names (related: SEC-378).

The flag description, generated CLI reference/help, and workspace access
and Gateway tips describe known agents. The guide explains when stopped
workspaces have only a workspace entry and how to populate their agent
entries.

## Verification

`TestConfigSSH_NoWildcard` verifies two stopped workspaces sharing a
template version but having different actual agents, import defaults
that differ from both, a precreated `dev_box` agent, and injection
rejection. History tests cover pagination, failed/newer builds, version
changes and request failures. Regression controls failed before the
fixes and passed afterward. Race tests, strict Go lint and docs checks
pass on the refreshed stack.

<details>
<summary>Validation commands</summary>

Latest rebase preserves the implementation and carries the docs edits to
main’s renamed `docs/workspaces/` paths. The SSHButton documentation
links and preview URL use the new routes. Revalidated the full
SSH/ping/config CLI race suite, strict lint, 25 frontend tests, 53
stories, and docs/manifest/redirect checks. The local shell’s Oh My Zsh
update prompt interrupted the first race run; the unchanged suite passed
with `DISABLE_AUTO_UPDATE=true` scoped to the test process.

Review decision: use workspace-specific build history because template
imports cannot represent chosen workspace parameters. Preserve the
last-start template-version boundary rather than inventing agents when
no compatible history exists. Both stack branches are rebased onto
`main` at `63b5c4d64a`.

```sh
go test -race -tags=testsmallbatch ./cli -run 'TestConfigSSH|Test_noWildcardHostNames|Test_previousStartResources|TestCommandHelp' -count=1 -parallel=4
GOMEMLIMIT=6GiB make lint/go/new-code GO_LINT_CONCURRENCY=4
```

Docs validation also passed emdash, HTML-table and manifest checks,
targeted markdownlint, table formatting and Vale.

</details>

Fixes
[CLI-68](https://linear.app/codercom/issue/CLI-68/config-ssh-no-wildcard-does-not-write-host-entries-for-workspace).
#31188 is stacked on this PR.

Preview:
https://coder.com/docs/@fix%2Fconfig-ssh-no-wildcard-agents/workspaces/workspace-access

> 🤖 This PR was created with the help of Coder Agents, and has been
reviewed by my human. 🧑💻
2026-11-05 10:01:33 +05:00
coder[bot]andNick Vigilante 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>
2026-11-04 17:41:22 -05:00
coder[bot]andNick Vigilante 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>
2026-11-04 17:30:25 -05:00
coder[bot]andNick Vigilante 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>
2026-11-04 17:15:42 -05:00
coder[bot]andNick Vigilante 9aa8b973cd docs: point download links to coder.com/downloads (#31205)
We launched a dedicated downloads page at https://coder.com/downloads
with the latest mainline and stable builds for every OS and
architecture, Coder Desktop installers, Helm charts, and checksums. This
points the docs' "go download Coder" links there instead of GitHub
releases.

**Updated to the downloads page**

- `install/cli.md`, `user-guides/workspace-access/zed.md`: alternate
install methods and the Windows installer. Also fixes the Windows file
types: the installer is `.exe` and the standalone binary ships as a
`.zip` (not `.msi`/`.exe`). Drops "from GitHub" from the `cli.md`
section heading (no in-repo links used that anchor).
- `get-started/index.md`: alternate install methods.
- `install/operate/upgrade.md`: Windows upgrade download.
- `install/operate/provisioners/index.md`: "full Coder binary" link.
- `install/server/rpm.md`: RPM download, with GitHub releases kept for
older versions.
- `install/prepare/airgap.md`: Helm chart download (downloads page plus
GitHub releases).
- `user-guides/desktop/index.md`: macOS and Windows Coder Desktop manual
installs.
- `reference/releases.md`: latest stable/mainline from the downloads
page, specific versions from GitHub releases.

**Left on GitHub on purpose**

- Version-specific tag links and the release table in
`reference/releases.md`.
- "Review the release notes" links, the update-check description, and
the air-gapped docs bundle (`coder_docs_<version>.tgz` isn't on the
downloads page).
- VS Code extension `.vsix` links (not on the downloads page).
- `admin/users/index.md`: that block is literal `coder users create`
output, so it should change with `cli/usercreate.go` in a follow-up, not
here.

External links in the docs already open in a new tab on coder.com/docs
(`DocsHTMLRenderer` adds `target="_blank" rel="noopener"`), so plain
Markdown links are enough. No CTA button in this PR.

Vale, markdownlint, and `scripts/docshtmlcheck` pass on the changed
files. The only Vale warning is one that was already in
`get-started/index.md`.

Created on behalf of @nickvigilante

Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com>
Co-authored-by: Nick Vigilante <nick.vigilante@coder.com>
2026-11-04 21:22:17 +00:00
Denis AfonsoandClaude a9772b9c5e docs: add the 2.40 Not Released row and trim 2.33 from the calendar (#31750)
Follow-up to #31715, which merged before this landed on its branch.
Applies the calendar rotation convention the docs-check bot flagged on
#31716: when mainline advances, append the next minor as Not Released
and trim the oldest Not Supported row, as the v2.38 rotation did with
2.39 and 2.32.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude  <noreply@anthropic.com>
2026-11-04 12:04:36 +00:00