Commit Graph
299 Commits
Author SHA1 Message Date
dfa72df9aa docs: remove references to unsupported SAML authentication (#30507)
## Summary

Coder doesn't support SAML, but a few docs pages implied it did.
This PR removes those mentions.

Resolves
[DOCS-1194](https://linear.app/codercom/issue/DOCS-1194/remove-saml-mentions-from-docs-coder-doesnt-support-saml).

## Changes

- `docs/install/index.md` and `docs/install/prepare/index.md`: "OIDC or
SAML application" is now "OIDC application".
- `docs/.style/style-guide/audience-and-scope.md`: the example snippets
no longer mention SAML or link to a `./saml.md` page that doesn't exist.
The hub-page example now lists headless authentication instead, and the
persona "Coder surface" lines say "OIDC" in place of "OIDC/SAML".

<details>
<summary>Evidence that Coder doesn't support SAML</summary>

Checked against `main`:

- No SAML library in `go.mod`, `go.sum`, or `site/package.json`.
- The `login_type` enum in `coderd/database/dump.sql` and
`codersdk.LoginType` only cover `password`, `github`, `oidc`, `token`,
`none`, and `oauth2_provider_app`.
- No SAML handlers, endpoints, or deployment options in `coderd/` or
`enterprise/`.
- The only code mention is a comment in `coderd/userauth.go` about
SAML-to-OIDC bridges sending `email_verified` as a string.

</details>

## Testing

- `pnpm run lint-docs`: 0 errors.
- The pre-commit hook passed.
- `git grep -i saml -- docs` returns nothing.

---

*Generated by Coder Agents on behalf of @nickvigilante.*

---------

Co-authored-by: Ben Potter <me@bpmct.net>
Co-authored-by: Ben Potter <ben@coder.com>
2026-10-11 08:36:17 -07:00
Andrew G. Dunn 020b437ec9 docs: document dropping capabilities for restricted Pod Security (#30271)
Following the suggestion in #22543 to have
`coder.securityContext.capabilities` in `values.yaml` without a default,
this adds it as a commented example, the same way `values.yaml` shows
`env` and `initContainers`, and adds one line to the Kubernetes Security
Reference. Existing deployments don't change on upgrade.

The chart's default security context passes every Pod Security Standards
`restricted` check except capabilities, so a namespace that enforces
`restricted` rejects the pod. Because the example is commented out, the
rendered chart is unchanged:

```console
$ diff main.yaml branch.yaml && echo "renders identical ($(wc -l < branch.yaml) lines)"
renders identical (208 lines)
```

Server-side dry runs of this branch's chart into a namespace labeled
`pod-security.kubernetes.io/enforce=restricted` (GKE, Kubernetes 1.35),
using the pod spec from the rendered Deployment, as is and with the
example uncommented:

```console
$ kubectl create --dry-run=server -n coder -f pod-branch.json
Error from server (Forbidden): error when creating "pod-branch.json": pods "pss-main-branch" is forbidden: violates PodSecurity "restricted:latest": unrestricted capabilities (container "coder" must set securityContext.capabilities.drop=["ALL"])
$ kubectl create --dry-run=server -n coder -f pod-branch-drop.json
pod/pss-main-branch-drop created (server dry run)
```

A v2.37.3 deployment with the value set runs in a `restricted`
namespace, ready with no restarts.

AI involvement: I used an AI assistant to draft this change, and
verified it with the commands above against a running cluster.
2026-10-07 23:18:04 +00:00
Ian Evans 21c1abe9ad docs(docs/install): reformat to one sentence per line (#30438)
Reformats every Markdown page under `docs/install` to the
[one-sentence-per-line
convention](https://github.com/coder/coder/blob/main/docs/.style/style-guide/formatting.md#one-sentence-per-line).
Addresses DOCS-668.

This is a source-layout change only: 28 of the 36 pages change, and
rendered HTML is identical for all of them except three wording fixes.
Three pre-existing em dashes sat on reflowed lines, which `lint/emdash`
flags as new, so they're rewritten with commas or a sentence break
(`operate/upgrade/esr-2.24-2.29-upgrade.md`,
`operate/upgrade/best-practices.md`).

Front matter, fenced code, tables, HTML blocks, and headings are
untouched.

`Coder.OneSentencePerLine` is not enabled for `docs/install` in
`.vale.ini`: the 39 remaining findings are all table rows or code, which
the guide puts out of scope, and enabling the rule would break the
zero-baseline doctrine.

<details>
<summary>Implementation and verification notes</summary>

**Approach.** A throwaway script reflowed each paragraph. Bullet items,
numbered entries, and blockquote lines (including `> [!NOTE]` callouts)
are each their own paragraph; extra sentences in a list item continue on
indented lines, matching `docs/.style/content-guidelines.md`. Sentence
breaks are never inserted inside inline code, link text, URLs, or HTML
tags, and abbreviations such as `e.g.` and `etc.` don't count as
sentence ends. Images that started their own source line stay on their
own line. The script is idempotent: a second pass produces no changes.

**Merge with main.** `main` restructured `docs/install` into plan,
prepare, server, validate, and operate sections after this branch was
cut. The merge takes `main`'s tree and re-runs the reflow over every
page now under `docs/install`, so the branch diff against `main` is
reflow only. `releases/index.md` and `releases/feature-stages.md` moved
out of `docs/install` on `main` and are no longer in scope.

**Verification.**

- Rendered every page with `marked` from `main` and from this branch and
compared normalized HTML: identical except the three em-dash rewrites.
- Vale with `Coder.OneSentencePerLine` forced on for `docs/install`: 277
findings on `main`, 39 on this branch, all in table rows or fenced code.
- A broader sweep for mid-line sentence boundaries and for false splits
(lines starting lowercase, lines ending in an abbreviation) found no
prose hits.
- `markdownlint-cli2`, `markdown-table-formatter --check`, `make
lint/emdash`, and `make pre-commit-light` pass.

</details>

---

*Generated by Coder Agents on behalf of @ianjevans.*
2026-10-06 13:31:35 -07:00
Nick Vigilante 28cf704f27 chore: update references to the relocated install docs paths (#30380)
The Install docs moved into the five-phase spine in #29304, but several
references outside `docs/` still point at the pre-move URLs.
`docs/redirects.json` is empty, so those URLs 404 rather than
forwarding.
The release note generators are the user-visible ones: every generated
release note links `coder.com/docs/install/releases` and
`coder.com/docs/install/upgrade`.

| Reference | Was | Now |
|---|---|---|
| Release schedule links in release notes | `/docs/install/releases` |
`/docs/reference/releases` |
| Upgrade link in release notes | `/docs/install/upgrade` |
`/docs/install/operate/upgrade` |
| README sizing link |
`/docs/admin/infrastructure/validated-architectures` |
`/docs/install/plan/sizing` |
| Provisioner tag table comments | `docs/admin/provisioners/index.md` |
`docs/install/operate/provisioners/index.md` |
| FAQ provenance comment | `docs/admin/licensing/index.md` |
`docs/install/prepare/licensing.md` |
| ESR 2.24-2.29 upgrade table | `/docs/admin/provisioners` |
`/docs/install/operate/provisioners` |
| Helm provisioner README, `NOTES.txt`, and `values.yaml` |
`/docs/admin/provisioners` | `/docs/install/operate/provisioners` |
| Helm Coder chart README | `/docs/install/kubernetes` |
`/docs/install/server/kubernetes` |
| `workspace-tags` example README |
`/docs/admin/provisioners#external-provisioners` |
`/docs/install/operate/provisioners#types-of-provisioners` |
| `kubernetes-envbox` example README |
`/docs/admin/infrastructure/architecture#agents` |
`/docs/install/plan/architecture#agents` |

`scripts/releaser/docs.go` was already updated in #29304; this covers
what that pass missed.

Two notes on anchors:

- The `#external-provisioners` anchor was already dead before #29304, so
it now points at `#types-of-provisioners`, the section covering
external, organization-scoped, and user-scoped provisioners.
- Every other anchor was verified to still exist on its new page.

One link left alone: `provisionerd/provisionerd.go` references
`docs/admin/provisioners.md` through a pinned-commit GitHub permalink,
which still resolves and shouldn't be rewritten.

## Verification

- `go test ./scripts/release/...` passes, including the release note
golden strings.
- `go build ./scripts/releaser/` succeeds.
- `make pre-commit` passes.
- Markdown table padding reflowed with `markdown-table-formatter`;
`markdownlint` reports no new findings.

<sub>Opened by Coder Agents on behalf of @nickvigilante.</sub>
2026-10-05 22:28:54 +00:00
Nick Vigilante 3f408825b5 docs: add playback controls and descriptions to autoplaying videos (#30263)
## Summary

Four docs pages embed autoplaying, looping screencasts with no controls,
so readers cannot pause them (WCAG 2.2.2, Level A). This adds `controls`
and `muted` to each `<video>` and a one-sentence text description after
each video. The renderer-side companion for the beta docs is
coder/docs-engine#203.

## Changes

- Add `controls` and `muted` to the `<video autoplay playsinline loop>`
tag in `external-auth.md`, `open-in-coder.md`,
`ai-coder/agents/index.md`, and `compute-engine.md`. `autoplay`,
`playsinline`, and `loop` stay.
- Add a one-sentence description of each screencast directly below it.
- `extending-templates/external-auth.md` is not in `docs/manifest.json`,
so it is unpublished. It is fixed for consistency.

## Testing

- `pnpm lint-docs` (markdownlint-cli2): 0 errors across 519 files.
- `make lint/emdash`, `go run ./scripts/docshtmlcheck`, `go run
./scripts/styleclaims`: pass.
- The repo pre-commit hook passed.
- Not run: rendering the pages in a browser. The descriptions are
inferred from the surrounding prose and file names, not from watching
the videos.

Linear: [DOCS-1050](https://linear.app/codercom/issue/DOCS-1050)

_Generated by Coder Agents on behalf of @nickvigilante._
2026-10-05 09:35:36 -04:00
Matt Vollmer eae031d483 docs: remove AI Governance usage row from air-gapped comparison (#30202)
Removes the "AI Governance Usage Count" row from the public vs.
air-gapped comparison table in `docs/install/prepare/airgap.md`. The
rest of the table is reformatted by `markdown-table-formatter` because
the removed row set the first column width.

Supersedes #30201.

> Generated by Coder Agents on behalf of @mattvollmer.
2026-09-30 19:05:49 +00:00
Nick Vigilante 1fd383e4fd docs: flatten lone index pages to single files (#30129)
The beta docs engine turns a directory that holds only an `index.md`
into an empty collapsible section in the sidebar. Two pages on `main`
have that shape: `docs/admin/external-auth/index.md` and
`docs/ai-coder/agents/tools/index.md`. docs-engine is handling the shape
in its own code (the sidebar render fix in
https://github.com/coder/docs-engine/pull/196 and the sync-side handling
in https://github.com/coder/docs-engine/pull/195), and this change
removes it at the source by moving each page to a flat file:
`docs/admin/external-auth.md` and `docs/ai-coder/agents/tools.md`. Both
directories held only `index.md`, with no images or other files.

The change updates the two `docs/manifest.json` paths, 29 inbound
relative links across 17 pages, and the relative links inside the moved
pages (three images and two page links in `external-auth.md`, one page
link in `tools.md`), which now resolve one directory up. The ESR upgrade
table in `docs/install/operate/upgrade/esr-2.29-2.34-upgrade.md` is
re-padded because its link cells shrank, which is why that file shows 28
changed lines. No generator under `scripts/`, the docs-preview workflow,
or `docs/.style` references either path.

Published URLs stay the same, so no redirect is needed. coder.com's
`convertPathToRoute` strips the `index.md` or `.md` suffix, the
docs-preview workflow's `map_doc_path` maps `<dir>/index.md` and
`<dir>.md` to the same route, and docs-engine's `mapMdPath` returns
`admin/external-auth` and `ai-coder/agents/tools` for both the old and
new paths.

For verification, `docs/manifest.json` parses and all 471 of its paths
exist. `make pre-commit-light` passes, which covers markdownlint, the
table formatter, typos, emdash, and shellcheck, and `go run
./scripts/docshtmlcheck` passes. A local script resolved all 306
relative links in the changed files, and every one that the move touched
points at an existing file and heading. linkspector runs on this PR in
CI. A backport PR for `release/2.37` moves the same two pages plus
`admin/licensing` and `install/other`:
https://github.com/coder/coder/pull/30130.

This change was prepared with AI assistance. The AI agent that prepared
it ran the checks described above.

---

🤖 Built with AI assistance.
2026-09-30 14:34:33 -04:00
Nick Vigilante 4a62b0fc9c docs: add YAML front matter to remaining pages (#30115)
## Summary

Add YAML front matter to the remaining published documentation pages so
all published pages expose a title through front matter.

## Changes

- Add front matter to the 13 published pages that were missing it.
- Preserve the page titles and feature states in the manifest.
- Remove duplicate H1 headings where the front matter supplies the page
title.

## Testing

- `pnpm check-docs` passed.
- Repository pre-commit checks passed.
- Verified all 439 published manifest route entries have YAML front
matter.

Depends on #30109.

Refs DOCS-1124.

This pull request was generated by Coder Agents.
2026-09-29 20:31:27 -04:00
Nick Vigilante d40e24cf7d docs: nest the CLI reference by subcommand (#29956)
## Summary

Nests the CLI reference by subcommand so the Command Line sidebar
collapses from 156 flat entries to 49 top-level verbs.
Each page's URL follows the invocation, its page title is the full
command as inline code, and its sidebar label is only its own verb as
inline code.

| | Before | After |
| --- | --- | --- |
| File | `docs/reference/cli/oauth2-provider_dcr_disable.md` |
`docs/reference/cli/oauth2-provider/dcr/disable.md` |
| URL | `/reference/cli/oauth2-provider_dcr_disable` |
`/reference/cli/oauth2-provider/dcr/disable` |
| Page title (front matter) | `oauth2-provider dcr disable` | `` `coder
oauth2-provider dcr disable` `` |
| Sidebar label (manifest) | `oauth2-provider dcr disable` | ``
`disable` `` |

Resolves DOCS-140 (coder/coder half). Also fixes the Makefile part of
DOCS-1073 / DOCS-912, which this change depends on.

## Changes

- `scripts/clidocgen`: pages nest by command path. A command with
visible subcommands becomes its directory's `index.md`, so
`oauth2-provider/index.md` and `oauth2-provider/dcr/index.md` sit above
`oauth2-provider/dcr/disable.md`. Subcommand table links are relative to
the parent page.
- `scripts/clidocgen`: the manifest "Command Line" section is built from
the command tree (nested, sorted by name, hidden commands skipped)
instead of a flat list. The redundant `coder` child that pointed back at
`reference/cli/index.md` is gone.
- `Makefile`: the CLI rule now replaces `docs/reference/cli/` wholesale,
so stale pages get removed. The manifest rule now runs `clidocgen
-manifest-only` on top of the API staging manifest, so the CLI nav is
generated instead of edited by hand. As a result, the nine pages that
had no nav entry (`ai-gateway*`, `secret enable/disable`, `server
fix-oidc-links`) now have one.
- `scripts/configdocgen` and 48 prose pages: links point at the new
paths (for example `reference/cli/server.md` is now
`reference/cli/server/index.md`).

## How to review/QA this PR

- `docs/reference/cli/**/*` (approximately 190 pages): Each of these
pages are generated automatically. Some pages appear deleted, and some
pages appear new. Every deleted page corresponds to a new page somewhere
else, so no information is being deleted. The docs in this section
should adhere to the following, so a test in the build preview for each
of these items should be satisfactory:
- [ ] Each subcommand of a command gets nested as a child instead of
being displayed as a flat list.
  - [ ] Each parent command is stored in an `index.md` file.
- [ ] The title of each page inside the page should now feature the full
`coder XYZ` command.
- [ ] The title of each page inside the page should now be formatted as
inline code.
- [ ] The title of each page in the sidebar should be the most granular
subcommand of the whole command string (if the page's title is `coder
ai-gateway keys create`, the sidebar label is `create`).
- [ ] The title of each page in the sidebar should now be formatted as
inline code.
  - [ ] The page slug for each page is now the most granular subcommand.
  - [ ] All links now point to the correct page.
- `docs/manifest.json`: The changes here reflect the updated structure
of the `docs/reference/cli` section.
- `docs/**/*.md` outside of `docs/reference/cli/**/*` (approximately 50
pages): The extent of the changes in these pages are just updating the
paths to point to the new page locations.
- [ ] The links on the page all point to the correct new path in
`docs/reference/cli`.
- `scripts/clidocgen` (4 files): This is the Go code responsible for
generating everything inside of `docs/reference/cli/**/*`. A typical
code review here should be satisfactory.
- `scripts/configdocgen` (2 files): these two files just have updates to
the raw `.md` path used by `docs/admin/setup/configuration-reference.md`
and updates the tests to reflect that.
- `Makefile`: This updates the `make` targets for generating the CLI
docs to fit the new structure.

## Merge ordering

Without the renderer PRs deployed, both docs sites show literal
backticks in titles and sidebar labels. Without the redirects, the old
flat URLs return 404.

1. Deploy before merging this PR: coder/docs-engine#176 (beta-docs
renders these titles as inline code) and coder/coder.com#1111 (classic
docs renders them as inline code). Both are safe to ship first, because
titles without backticks render as before.
2. Merge this PR.
3. Merge coder/coder.com#1112 (redirects from the old flat URLs) only
once this content reaches the mainline release branch that serves
unversioned `/docs`.

## Testing

- `go test ./scripts/clidocgen/ ./scripts/configdocgen/
./scripts/docshtmlcheck/`: pass. New tests cover page paths, subcommand
links, the nested manifest, and front matter quoting.
- `make docs/reference/cli/index.md docs/manifest.json
docs/admin/setup/configuration-reference.md`, then a forced rerun: the
second run produced no diff.
- Checked the manifest: all 164 CLI entries resolve to a file, no page
is missing a nav entry, and everything outside "Command Line" is
byte-identical.
- Relative `.md` links across `docs/`: 0 broken, same as `main`.
- `make pre-commit` and `make pre-push`: pass. On earlier pre-push
attempts, different unrelated vitest files timed out under host load.
Those files pass when run alone, and the final push passed with
`PARALLEL_JOBS=1`.

<details>
<summary>Implementation plan and decision log</summary>

**Goal (from DOCS-140 and the requester):** URLs follow the command
hierarchy. Pages are titled with the full command, and sidebar entries
with the last verb only. Both are formatted as inline code.

**Contract with the renderers:** a title wrapped entirely in one pair of
backticks (``^`[^`]+`$``) renders as inline code. Plain-text consumers
(`<title>`, meta, search, llms corpus) strip the backticks. Page title
comes from front matter `title`, and the sidebar label from the manifest
node `title`.

**Decisions**

- A parent command is `dir/index.md` rather than a sibling `dir.md`. The
root CLI page is already `index.md`, and both docs-engine and the legacy
coder.com renderer map `x/index.md` to `/x`.
- The manifest is built from the command tree, not from the written
files, so ordering is deterministic and the nesting matches the pages
exactly.
- The manifest discard bug (DOCS-1073 item 1) is fixed here, because
without that fix the generated nested manifest would never reach the
tree. DOCS-1073 items 2 through 4 (a prose fix and a hidden-command
policy) are out of scope.
- `-manifest-only` keeps the existing parallel `make gen` layout: the
API rule still owns `_gen/manifest-staging.json`, and CLI regeneration
doesn't retrigger swag.
- The renderer and redirect work lives in the companion PRs in
coder/docs-engine and coder/coder.com. It is linked above and not
duplicated here.

</details>

---

> [!NOTE]
> Generated by Coder Agents on behalf of @nickvigilante.
2026-09-28 15:44:10 -04:00
Nick Vigilante d43dd98baf docs: rewrite gerund-leading headings and page titles (#30049)
Rewrites the headings and page titles that `Coder.GerundHeading` flags
as gerund-leading, using the imperative for tasks and the noun form for
concepts.
This PR covers only changes that don't rename a page slug.

## Changes

- Rewrites 121 in-page headings, bringing `Coder.GerundHeading` findings
in `docs/` to zero.
- Adds an empty `<a id="old-slug"></a>` above each renamed heading, so
existing bookmarks and inbound deep links still land on the section.
The legacy IDs were computed with the same slugger the classic renderer
uses (`rehype-slug`), and all 115 that exist on production today match
the live `id` attributes; the other 6 are on pages not published yet.
- Updates the 18 in-docs links that targeted old anchors to use the new
slugs, and the link text that quoted the old heading.
- De-gerunds seven page titles (frontmatter and `manifest.json`) whose
slugs don't change, for example `Upgrading Best Practices` to `Upgrade
best practices`.
- Scopes a Vale exception around the glossary term `Coding agent`, where
"Coding" is an adjective.

## Not in this PR

- **Pages with gerund slugs** (`creating-templates`, `getting-started`,
`working-with-dev-containers`, `cloning-git-repositories`,
`configuring-okta`, and others) keep their current titles, so the title
and slug change together in the slug-rename PR.
  The redirects for those renames come in a third PR.
- **Links outside `docs/`** to old anchors (Go notification strings, an
applied SQL migration, golden files, and the generated `prometheus.md`)
still target old slugs.
They keep working through the legacy anchors, and updating them would
need code changes.

## Known limitation

`coder/docs-engine` prefixes raw-HTML `id` attributes with
`user-content-` (DOM-clobbering protection), and inbound deep links
aren't rewritten.
Once the docs move to docs-engine, these legacy anchors resolve only as
`#user-content-<old-slug>` unless docs-engine adds a fragment fallback.
They work on the current coder.com renderer and on GitHub.

## Testing

- `vale --filter='.Name=="Coder.GerundHeading"' docs`: zero findings,
down from 122.
- `make lint/markdown`, `make lint/docs-html`, `make lint/emdash`, and
the pre-commit hook: all pass.
- Scripted check that every relative `#fragment` link into a changed
file resolves to a heading slug or a legacy anchor (177 links).
- Scripted check that no legacy ID collides with a heading slug on the
same page, and that no untouched heading's duplicate-suffix slug
shifted.

<details>
<summary>Heading renames and legacy anchors (121)</summary>

| File | Old heading | New heading | Legacy anchor |
| --- | --- | --- | --- |
| `admin/integrations/opentofu.md` | Using a custom Terraform binary |
Use a custom Terraform binary | `#using-a-custom-terraform-binary` |
| `admin/monitoring/connection-logs.md` | Capturing/Exporting Connection
Logs | Capture and export connection logs |
`#capturingexporting-connection-logs` |
| `admin/monitoring/metrics.md` | Setting up metrics | Set up metrics |
`#setting-up-metrics` |
| `admin/networking/port-forwarding.md` | Accessing workspace ports |
Access workspace ports | `#accessing-workspace-ports` |
| `admin/networking/port-forwarding.md` | Sharing ports | Share ports |
`#sharing-ports` |
| `admin/networking/port-forwarding.md` | Configuring port protocol |
Configure port protocol | `#configuring-port-protocol` |
| `admin/networking/workspace-proxies.md` | Running on Kubernetes | Run
on Kubernetes | `#running-on-kubernetes` |
| `admin/networking/workspace-proxies.md` | Running on a VM | Run on a
VM | `#running-on-a-vm` |
| `admin/networking/workspace-proxies.md` | Running as a system service
| Run as a system service | `#running-as-a-system-service` |
| `admin/networking/workspace-proxies.md` | Running in Docker | Run in
Docker | `#running-in-docker` |
| `admin/networking/workspace-proxies.md` | Selecting a proxy | Select a
proxy | `#selecting-a-proxy` |
| `admin/security/audit-logs.md` | Capturing/Exporting Audit Logs |
Capture and export audit logs | `#capturingexporting-audit-logs` |
| `admin/security/audit-logs.md` | Purging Old Audit Logs | Purge old
audit logs | `#purging-old-audit-logs` |
| `admin/security/database-encryption.md` | Enabling encryption | Turn
on encryption | `#enabling-encryption` |
| `admin/security/database-encryption.md` | Rotating keys | Rotate keys
| `#rotating-keys` |
| `admin/security/database-encryption.md` | Disabling encryption | Turn
off encryption | `#disabling-encryption` |
| `admin/security/database-encryption.md` | Deleting Encrypted Data |
Delete encrypted data | `#deleting-encrypted-data` |
| `admin/security/secrets.md` | Displaying Secrets | Display secrets |
`#displaying-secrets` |
| `admin/setup/data-retention.md` | Keeping Data Indefinitely | Keep
data indefinitely | `#keeping-data-indefinitely` |
| `admin/setup/index.md` | Migrating from the built-in database to an
external database | Migrate from the built-in database to an external
database |
`#migrating-from-the-built-in-database-to-an-external-database` |
| `admin/setup/index.md` | Configuring Coder behind a proxy | Configure
Coder behind a proxy | `#configuring-coder-behind-a-proxy` |
| `admin/setup/telemetry.md` | Toggling | Turn telemetry on or off |
`#toggling` |
| `admin/templates/creating-templates.md` | Disabling the template
builder | Turn off the template builder |
`#disabling-the-template-builder` |
| `admin/templates/extending-templates/agent-metadata.md` | Managing the
database load | Manage the database load | `#managing-the-database-load`
|
| `admin/templates/extending-templates/docker-in-workspaces.md` |
Authenticating with a Private Registry | Authenticate with a private
registry | `#authenticating-with-a-private-registry` |
| `admin/templates/extending-templates/index.md` | Running scripts on
workspace lifecycle | Run scripts on workspace lifecycle events |
`#running-scripts-on-workspace-lifecycle` |
| `admin/templates/extending-templates/parameters.md` | Validating
parameters | Validate parameters | `#validating-parameters` |
| `admin/templates/extending-templates/prebuilt-workspaces.md` |
Invalidating prebuilds | Invalidate prebuilds |
`#invalidating-prebuilds` |
| `admin/templates/extending-templates/prebuilt-workspaces.md` |
Managing resource quotas | Manage resource quotas |
`#managing-resource-quotas` |
| `admin/templates/extending-templates/prebuilt-workspaces.md` |
Managing prebuild provisioning queues | Manage prebuild provisioning
queues | `#managing-prebuild-provisioning-queues` |
| `admin/templates/extending-templates/prebuilt-workspaces.md` |
Preventing resource replacement | Prevent resource replacement |
`#preventing-resource-replacement` |
| `admin/templates/extending-templates/prebuilt-workspaces.md` |
Preventing prebuild queue contention (recommended) | Prevent prebuild
queue contention (recommended) |
`#preventing-prebuild-queue-contention-recommended` |
| `admin/templates/extending-templates/process-logging.md` | Configuring
custom templates to use workspace process logging | Configure custom
templates to use workspace process logging |
`#configuring-custom-templates-to-use-workspace-process-logging` |
| `admin/templates/extending-templates/process-logging.md` | Viewing
workspace process logs | View workspace process logs |
`#viewing-workspace-process-logs` |
| `admin/templates/extending-templates/process-priority.md` | Verifying
the feature is enabled | Verify the feature is enabled |
`#verifying-the-feature-is-enabled` |
| `admin/templates/extending-templates/resource-metadata.md` | Hiding
resources in the dashboard | Hide resources in the dashboard |
`#hiding-resources-in-the-dashboard` |
| `admin/templates/extending-templates/resource-metadata.md` | Using a
custom resource icon | Use a custom resource icon |
`#using-a-custom-resource-icon` |
| `admin/templates/extending-templates/resource-ordering.md` | Using
"order" property | Use the "order" property | `#using-order-property` |
| `admin/templates/extending-templates/resource-persistence.md` |
Disabling persistence | Turn off persistence | `#disabling-persistence`
|
| `admin/templates/index.md` | Extending templates | Extend templates |
`#extending-templates` |
| `admin/templates/managing-templates/change-management.md` | Testing
and Publishing Coder Templates in CI/CD | Test and publish Coder
templates in CI/CD | `#testing-and-publishing-coder-templates-in-cicd` |
| `admin/templates/managing-templates/index.md` | Creating templates |
Create templates | `#creating-templates` |
| `admin/templates/managing-templates/index.md` | Editing templates |
Edit templates | `#editing-templates` |
| `admin/templates/managing-templates/index.md` | Updating templates |
Update templates | `#updating-templates` |
| `admin/templates/troubleshooting.md` | Debugging the startup script |
Debug the startup script | `#debugging-the-startup-script` |
| `admin/users/groups-roles.md` | Creating custom roles | Create custom
roles | `#creating-custom-roles` |
| `admin/users/index.md` | Configuring SSO | Configure SSO |
`#configuring-sso` |
| `admin/users/index.md` | Resetting a password on Kubernetes | Reset a
password on Kubernetes | `#resetting-a-password-on-kubernetes` |
| `admin/users/quotas.md` | Establishing Costs | Establish costs |
`#establishing-costs` |
| `admin/users/quotas.md` | Establishing Budgets | Establish budgets |
`#establishing-budgets` |
| `admin/users/sessions-tokens.md` | Creating tokens with scopes |
Create tokens with scopes | `#creating-tokens-with-scopes` |
| `ai-coder/agent-firewall/index.md` | Getting Started with Agent
Firewall | Get started with Agent Firewall |
`#getting-started-with-agent-firewall` |
| `ai-coder/agent-firewall/index.md` | Viewing Audit Logs | View audit
logs | `#viewing-audit-logs` |
| `ai-coder/agent-firewall/nsjail/k8s.md` | Running without user
namespaces | Run without user namespaces |
`#running-without-user-namespaces` |
| `ai-coder/agent-firewall/version.md` | Using Coder Before v2.30.0 with
Claude Code Module v4.7.0+ | Coder before v2.30.0 with Claude Code
module v4.7.0+ |
`#using-coder-before-v2300-with-claude-code-module-v470` |
| `ai-coder/agent-firewall/version.md` | Using Claude Code Module Before
v4.7.0 | Claude Code module before v4.7.0 |
`#using-claude-code-module-before-v470` |
| `ai-coder/agents/getting-started.md` | Providing feedback | Provide
feedback | `#providing-feedback` |
| `ai-coder/agents/models.md` | Managing personal API keys | Manage
personal API keys | `#managing-personal-api-keys` |
| `ai-coder/agents/models.md` | Removing a personal key | Remove a
personal key | `#removing-a-personal-key` |
| `ai-coder/agents/models.md` | Using an LLM proxy | Use an LLM proxy |
`#using-an-llm-proxy` |
| `ai-coder/agents/platform-controls/git-providers.md` | Checking logs |
Check logs | `#checking-logs` |
| `ai-coder/ai-gateway/audit.md` | Navigating the UI | Navigate the UI |
`#navigating-the-ui` |
| `ai-coder/ai-gateway/audit.md` | Conducting a forensic audit | Conduct
a forensic audit | `#conducting-a-forensic-audit` |
| `ai-coder/ai-gateway/clients/jetbrains.md` | Using the AI Assistant |
Use the AI Assistant | `#using-the-ai-assistant` |
| `install/operate/upgrade/best-practices.md` | Diagnosing liveness
probe issues | Diagnose liveness probe issues |
`#diagnosing-liveness-probe-issues` |
| `install/operate/upgrade/best-practices.md` | Recovering from failed
database migrations | Recover from failed database migrations |
`#recovering-from-failed-database-migrations` |
| `install/operate/upgrade/esr-2.24-2.29-upgrade.md` | Upgrading |
Upgrade recommendations | `#upgrading` |
| `install/operate/upgrade/esr-2.29-2.34-upgrade.md` | Upgrading |
Upgrade recommendations | `#upgrading` |
| `install/prepare/licensing.md` | Adding your license key | Add your
license key | `#adding-your-license-key` |
| `install/server/cloud/azure-vm.md` | Creating and Uploading Your First
Template | Create and upload your first template |
`#creating-and-uploading-your-first-template` |
| `install/server/cloud/compute-engine.md` | Configuring the control
plane | Configure the control plane | `#configuring-the-control-plane` |
| `reference/releases.md` | Installing stable | Install stable |
`#installing-stable` |
| `start/first-workspace.md` | Creating your first coder workspace |
Create your first Coder workspace |
`#creating-your-first-coder-workspace` |
| `start/local-deploy.md` | Setting up a Coder deployment | Set up a
Coder deployment | `#setting-up-a-coder-deployment` |
| `tutorials/best-practices/organizations.md` | Managing Organizations
at Scale | Manage organizations at scale |
`#managing-organizations-at-scale` |
| `tutorials/example-guide.md` | Adding Photos | Add photos |
`#adding-photos` |
| `tutorials/example-guide.md` | Setting the author data | Set the
author data | `#setting-the-author-data` |
| `tutorials/example-guide.md` | Setting up the routes | Set up the
routes | `#setting-up-the-routes` |
| `tutorials/persistent-shared-workspaces.md` | Finding shared
workspaces | Find shared workspaces | `#finding-shared-workspaces` |
| `tutorials/reverse-proxy-caddy.md` | Getting started | Get started |
`#getting-started` |
| `tutorials/reverse-proxy-caddy.md` | Generating wildcard certificates
| Generate wildcard certificates | `#generating-wildcard-certificates` |
| `tutorials/reverse-proxy-nginx.md` | Adding Coder deployment subdomain
| Add the Coder deployment subdomain |
`#adding-coder-deployment-subdomain` |
| `tutorials/testing-templates.md` | Creating the headless user | Create
the headless user | `#creating-the-headless-user` |
| `user-guides/desktop/desktop-connect-sync.md` | Accessing web apps in
a secure browser context | Access web apps in a secure browser context |
`#accessing-web-apps-in-a-secure-browser-context` |
| `user-guides/desktop/index.md` | Testing Your Connection | Test your
connection | `#testing-your-connection` |
| `user-guides/desktop/index.md` | Getting Help | Get help |
`#getting-help` |
| `user-guides/desktop/index.md` | Uninstalling | Uninstall Coder
Desktop | `#uninstalling` |
| `user-guides/devcontainers/index.md` | Getting started | Get started |
`#getting-started` |
| `user-guides/devcontainers/troubleshooting-dev-containers.md` |
Finding your dev container agent | Find your dev container agent |
`#finding-your-dev-container-agent` |
| `user-guides/devcontainers/troubleshooting-dev-containers.md` |
Getting more help | Get more help | `#getting-more-help` |
| `user-guides/devcontainers/working-with-dev-containers.md` | Using the
Coder CLI | Use the Coder CLI | `#using-the-coder-cli` |
| `user-guides/devcontainers/working-with-dev-containers.md` | Using
OpenSSH (config-ssh) | Use OpenSSH (config-ssh) |
`#using-openssh-config-ssh` |
| `user-guides/devcontainers/working-with-dev-containers.md` | Exposing
ports on the parent workspace | Expose ports on the parent workspace |
`#exposing-ports-on-the-parent-workspace` |
| `user-guides/devcontainers/working-with-dev-containers.md` |
Rebuilding dev containers | Rebuild dev containers |
`#rebuilding-dev-containers` |
| `user-guides/shared-workspaces.md` | Getting Started | Get started |
`#getting-started` |
| `user-guides/shared-workspaces.md` | Sharing your Workspace | Share
your workspace | `#sharing-your-workspace` |
| `user-guides/shared-workspaces.md` | Using a shared workspace | Use a
shared workspace | `#using-a-shared-workspace` |
| `user-guides/shared-workspaces.md` | Accessing workspace apps in
shared workspaces | Access workspace apps in shared workspaces |
`#accessing-workspace-apps-in-shared-workspaces` |
| `user-guides/workspace-access/emacs-tramp.md` | Connecting To A
Workspace | Connect to a workspace | `#connecting-to-a-workspace` |
| `user-guides/workspace-access/emacs-tramp.md` | Using SSH | Use SSH |
`#using-ssh` |
| `user-guides/workspace-access/index.md` | Running remote commands with
quoting | Run remote commands with quoting |
`#running-remote-commands-with-quoting` |
| `user-guides/workspace-access/jetbrains/gateway.md` | Configuring the
Gateway plugin to use internal certificates | Configure the Gateway
plugin to use internal certificates |
`#configuring-the-gateway-plugin-to-use-internal-certificates` |
| `user-guides/workspace-access/jetbrains/gateway.md` | Using an
existing JetBrains installation in the workspace | Use an existing
JetBrains installation in the workspace |
`#using-an-existing-jetbrains-installation-in-the-workspace` |
| `user-guides/workspace-access/port-forwarding.md` | Accessing
workspace ports | Access workspace ports | `#accessing-workspace-ports`
|
| `user-guides/workspace-access/port-forwarding.md` | Sharing ports |
Share ports | `#sharing-ports` |
| `user-guides/workspace-access/port-forwarding.md` | Configuring port
protocol | Configure port protocol | `#configuring-port-protocol` |
| `user-guides/workspace-access/vscode.md` | Using the public extensions
marketplaces | Use the public extensions marketplaces |
`#using-the-public-extensions-marketplaces` |
| `user-guides/workspace-access/vscode.md` | Adding extensions to custom
images | Add extensions to custom images |
`#adding-extensions-to-custom-images` |
| `user-guides/workspace-access/vscode.md` | Installing extensions using
its `vsix` file at the command line | Install extensions using a `vsix`
file at the command line |
`#installing-extensions-using-its-vsix-file-at-the-command-line` |
| `user-guides/workspace-access/vscode.md` | Installing from a
marketplace at the command line | Install from a marketplace at the
command line | `#installing-from-a-marketplace-at-the-command-line` |
| `user-guides/workspace-access/vscode.md` | Using VS Code Desktop | Use
VS Code Desktop | `#using-vs-code-desktop` |
| `user-guides/workspace-access/web-terminal.md` | Accessing the
Terminal | Access the terminal | `#accessing-the-terminal` |
| `user-guides/workspace-lifecycle.md` | Stopping workspaces | Stop
workspaces | `#stopping-workspaces` |
| `user-guides/workspace-lifecycle.md` | Deleting workspaces | Delete
workspaces | `#deleting-workspaces` |
| `user-guides/workspace-management.md` | Creating workspaces | Create
workspaces | `#creating-workspaces` |
| `user-guides/workspace-management.md` | Updating workspaces | Update
workspaces | `#updating-workspaces` |
| `user-guides/workspace-management.md` | Updating via the CLI | Update
with the CLI | `#updating-via-the-cli` |
| `user-guides/workspace-management.md` | Starting and stopping
workspaces | Start and stop workspaces |
`#starting-and-stopping-workspaces` |
| `user-guides/workspace-management.md` | Repairing workspaces | Repair
workspaces | `#repairing-workspaces` |
| `user-guides/workspace-scheduling.md` | Working hours | Work schedule
| `#working-hours` |
| `user-guides/workspace-scheduling.md` | Basing solely on activity
detection | Rely solely on activity detection |
`#basing-solely-on-activity-detection` |

</details>

<details>
<summary>Plan</summary>

The de-gerund work ships as three PRs:

1. This PR: in-page headings and page titles that do not require a page
slug rename.
1. Page slug renames for pages whose filenames are gerunds.
1. Redirects for the renamed slugs.

Heading rewrites follow the style guide section "No gerund-leading
headings": imperative for task headings, noun form for concept headings,
sentence case, and "turn on"/"turn off" instead of "enable"/"disable"
per word-choice guidance.
The legacy anchor sits on its own line above the heading (with a blank
line between) rather than inside the heading, so it does not leak into
heading text, TOC entries, or Fumadocs slugs.

</details>

---

_Generated by Coder Agents on behalf of @nickvigilante._
2026-09-28 13:40:07 -04:00
Nick Vigilante 88aa2cc373 feat: enable Coder.UnitSpacing (#29944)
## Summary

Adds `Coder.UnitSpacing`, a Vale rule that enforces the style guide's
[non-breaking space between number and
unit](https://github.com/coder/coder/blob/main/docs/.style/style-guide/numbers-units-and-dates.md#non-breaking-space-between-number-and-unit)
policy.
Until now, the guide pointed at `Google.Units (planned)`, but that rule
accepts a regular space, so it can't enforce the policy.

Resolves [DOCS-1072](https://linear.app/codercom/issue/DOCS-1072).

## Changes

- **Cleanup commit**: replaces the regular space (or missing space) with
`&nbsp;` in 189 prose findings across 55 files. One config default,
`(default: 15s)`, moves to code font instead, as the guide requires for
configuration values. One table row that was realigned also swaps a
pre-existing en dash for a hyphen, since `lint/emdash` checks changed
lines.
- **Enable commit**: adds `docs/.style/styles/Coder/UnitSpacing.yml` at
`warning`, updates the enforcement footer in
`numbers-units-and-dates.md`, and updates the coverage tables in the
style guide README.
- **Reflow commit**: every hard-wrapped paragraph the cleanup touched
(45 paragraphs in 29 files) is rewrapped to one sentence per line.
Joining lines exposed units split across a line break, which now use
`&nbsp;`, and two em dashes on rewritten lines are reworded.
- **Rule fix commit**: the token now matches ASCII whitespace, including
a newline, between the number and the unit, so a hard-wrapped paragraph
can't hide a missing `&nbsp;`. The class is spelled out because Vale's
`\s` is Unicode and would match U+00A0. Vale can't locate a match that
spans list indentation or a blockquote marker, so splits there still go
unreported.
- **Rule count sync**: the tooling paragraph in the style guide README
now reads 79 rules, 9 tool-checked, to match the coverage table. The 79
corrects drift already on `main` since #29758; the 9 is this PR's new
rule.
- `.vale.ini` turns the rule off for pages generated from Go source:
`docs/reference/{api,cli}/*.md`, `configuration-reference.md`, and
`prometheus.md`. That text comes from flag descriptions, Swagger
comments, and metric help text, which also render outside Markdown,
where `&nbsp;` would show up literally.

<details>
<summary>Rule design decisions</summary>

- An `existence` rule matches `\d+(\.\d+)?` followed by a regular space
or no space, then a unit from a curated list (time, data size,
bandwidth, frequency, vCPU/CPU/cores).
- Vale renders Markdown before matching, so `&nbsp;` and a literal
U+00A0 both pass. Code spans and fences are skipped.
- Hyphenated compound modifiers (`12-hour clock`) don't match, because
the token allows only a space or nothing between the number and the
unit.
- Exceptions cover HTTP status plurals (`413s`) and decades (`1990s`).
- Severity is `warning`, because the unit list is curated and a count
followed by a unit-like word can still be a judgment call.
- Alternative considered: a `BlockIgnores` pattern for the `<!-- Code
generated ... -->` regions. I didn't use it because it would silence
every rule in those regions, not just this one.

</details>

## Testing

- Ran the rule against fixtures: `30 seconds`, `150ms`, `4 vCPU` in a
table, and `16` / `GB` split across lines in a paragraph all flag.
`30&nbsp;seconds`, literal U+00A0, `12-hour`, `413s`, `1990s`, and ``
`30s` `` don't.
- `vale docs/` reports 0 `Coder.UnitSpacing` findings, and the counts
for every other rule match `main`.
- A scratch config with `Coder.OneSentencePerLine` turned on reports 0
findings on changed lines.
- `make lint/markdown`, `make lint/style-claims`, `make lint/emdash`,
and the `pre-commit-light` hook pass.

<details>
<summary>CI flake note</summary>

`Storybook` failed on b3c53b6874 after capturing all 3,421 snapshots,
when the Pixel build was marked `failed` during finalization. This PR
changes no files under `site/`. The re-run failed the same way, and
`Storybook` is failing in the same Pixel step on the latest `main`
commits, so this isn't caused by this PR.

</details>

---

*Generated by [Coder Agents](https://coder.com/docs/ai-coder/agents) on
behalf of @nickvigilante.*
2026-09-28 12:29:40 -04:00
Eric Paulsen aa87166c2f docs: fix step order and values.yaml in Azure App Gateway guide (#29927) 2026-09-25 18:07:17 +01:00
Nick Vigilante 9afdea4808 docs(docs): document RPM install on RHEL-family Linux (#29295)
## Summary

Coder ships `.rpm` assets with every release and `install.sh` routes the
RHEL family to `install_rpm()`, but no public page said so. The only
page that named RHEL was the uninstall page. This adds an RPM install
page for the control plane.

New page `docs/install/server/rpm.md`:

- Supported distribution matrix for RHEL 8/9/10, Rocky, AlmaLinux,
CentOS Stream, Amazon Linux, Fedora, and openSUSE, with the
`ID`/`ID_LIKE` detection that makes derivatives work.
- Install tabs for the install script, `dnf install`, and `rpm -U`.
- What the package lays down: `/usr/bin/coder`,
`/etc/coder.d/coder.env`, `coder.service`,
`coder-workspace-proxy.service`, and the unprivileged `coder` user.
- Configure-then-start ordering, because `coder.service` carries
`ConditionFileNotEmpty=/etc/coder.d/coder.env` and won't start against
an empty config.
- SELinux caveat for Docker/Podman inside workspaces on RHEL nodes,
linking the existing guidance instead of duplicating it.
- Iron Bank UBI9-minimal pointer for hardened environments, scoped
correctly as a container image rather than an RPM path.

Supporting edits: manifest entry under "3. Install the control plane"
between OpenShift and Cloud Providers, a row in the platform table on
`install/server/index.md`, and a pointer from `install/cli.md`.

## Placement

The page sits at `docs/install/server/rpm.md`, as a sibling of Docker,
Kubernetes, Rancher, and OpenShift, rather than under community install
methods: RPMs are officially built and shipped, not an unofficial
method. It is a control-plane deployment page, not CLI download content,
so it is out of scope for the CLI-retirement work.

## Verification

Claims on the page were checked against real RHEL-family images, not
just the install script:

| Check | Method | Result |
|-------|--------|--------|
| `ID` and `ID_LIKE` per distribution | `docker run <image> sh -c '.
/etc/os-release; ...'` across UBI 8/9/10, Rocky 9, Alma 9/10, CentOS
Stream 9/10, Amazon Linux 2/2023, Fedora, openSUSE Leap and Tumbleweed |
Every RHEL-family image lists `fedora` in `ID_LIKE`; both openSUSE
variants list `opensuse`. Matches the `distro()` branch in `install.sh`
|
| `dnf install ./coder_*.rpm` | Rocky Linux 9 container | Installs
cleanly |
| Package contents | `rpm -ql coder` | `/usr/bin/coder`,
`/etc/coder.d/coder.env`, `coder.service`,
`coder-workspace-proxy.service` |
| Service account and start condition | Installed unit file | Runs as
`coder:coder`; `ConditionFileNotEmpty=/etc/coder.d/coder.env` |
| Architectures | `.github/workflows/release.yaml` | `amd64`, `armv7`,
`arm64` |

Not verified: `systemctl enable --now coder` against a live database,
since the containers used for verification have no init system. The
`systemctl is-active` output on the page is standard systemd output,
flagged here for the reviewer.

Lint: `make lint/markdown`, `make lint/emdash`, and `make lint/prose`
all clean on the changed files; `pnpm run format-docs` applied.

<details>
<summary>Implementation plan and decision log</summary>

### Style guide application

The first revision of this page was drafted from sibling install pages
rather than from the style guide, and was rewritten against
[`docs/.style/content-guidelines.md`](https://github.com/coder/coder/blob/main/docs/.style/content-guidelines.md)
and the prose style guide. What changed: one sentence per source line,
declared audience and outcome in the opening paragraph, numbered
procedures with one instruction per step and conditions stated first,
`refer to` instead of `see`, `sh` fences instead of `shell`, H3 tab
headings, non-breaking space between number and unit, and `Learn more`
instead of `Next steps`.

### Decisions

- **No version numbers or FIPS certification claims for Iron Bank.** The
tags in `scripts/ironbank/hardening_manifest.yaml` are stale (`0.15.3`);
documenting them would re-create the drift. The page links the registry
and names the UBI9-minimal base only.
- **Iron Bank framed as a container path.** It is a container image, so
the page routes readers to Kubernetes/OpenShift rather than implying it
is an alternative to the RPM.
- **Dropped an unverified SELinux claim.** An earlier draft asserted
that the control plane runs under enforcing mode with no policy changes.
That was not tested, so it is gone. The section now covers only the
workspace container-runtime case, which links to existing verified
guidance.
- **`ID_LIKE` values kept out of the table.** They vary by version (RHEL
8/9 report `fedora`, RHEL 10 reports `centos fedora`), so the table
lists `ID` and the prose states the invariant the install script
actually matches on.
- **Minimal edit to `install/cli.md`.** That file is slated for deletion
in the Install restructure, so it gets a pointer and nothing more.

### Rebase onto the install spine restructure

The install spine restructure landed on `main` while this PR was open
and removed the install-method tabs on `install/index.md` that the first
revision pointed from. The branch was rebased and squashed onto it: the
page moved from `docs/install/rpm.md` to `docs/install/server/rpm.md`,
every relative link was repointed at the new locations
(`../plan/sizing/index.md`, `../prepare/airgap.md`,
`../operate/upgrade.md`, `../operate/uninstall.md`,
`./kubernetes/index.md`), the install script snippet picked up the
standardized `curl -fsSL` flags, and discovery moved from the removed
`install/index.md` tabs to the platform table on
`install/server/index.md`. The prose is otherwise unchanged.

### Follow-ups tracked elsewhere

The install spine has no other bare-host or Linux-package option under
platforms; every other entry is a container platform or a cloud VM. Open
question recorded on the IA proposal: whether this generalizes to a
single "Linux host (system packages)" page covering `.deb` and `.apk`
too.

</details>

---

Linear:
[DOCS-886](https://linear.app/codercom/issue/DOCS-886/document-support-for-running-coder-on-red-hat-linux)

🤖 Generated with Coder Agents on behalf of @nickvigilante.
2026-09-25 11:47:34 -04:00
Nick Vigilante 99a3425333 fix: advertise install.sh with curl -fsSL everywhere (#29801)
## Summary

The install one-liner is advertised as `curl -L` in most docs pages, the
README, and the CLI's default version-mismatch hint, while `install.sh`
itself and the deployment-local hint use `curl -fsSL`.
Without `-f`, curl writes an HTTP error body to stdout, and the
one-liner pipes that error page into `sh`.
This PR standardizes every `install.sh` invocation on `-fsSL` so a
failed download fails closed.

## Changes

- Docs: `install/cli.md`, `install/operate/upgrade.md` (twice),
`get-started/index.md`, `start/local-deploy.md`,
`install/operate/provisioners/index.md`,
`admin/templates/managing-templates/change-management.md` (twice),
`user-guides/workspace-access/zed.md`, and `README.md`.
- CLI: `defaultUpgradeMessage` in `cli/root.go` now prints `curl -fsSL`,
matching the deployment-local branch in the same function.
- `codersdk/deployment.go`: the `--cli-upgrade-message` description now
says `curl -fsSL`; the server help goldens, `server-config.yaml.golden`,
`docs/reference/cli/server.md`, and
`docs/admin/setup/configuration-reference.md` are regenerated to match.
- `install.sh`: the "To run" header comment now matches the script's own
usage text.
- Style guide: a new "Commands that pipe a download into a shell" rule
in `docs/.style/style-guide/formatting.md`, and the tabs example uses
`-fsSL`.

The coder.com download page already builds its command from `-fsSL` in
coder/coder.com#1093, and coder.com `main` has no other `install.sh`
one-liners outside test fixtures, so no coder.com change is needed.
DatoCMS content and a release verification page are not in this PR.

`main` since moved the upgrade and provisioner pages under
`docs/install/operate/` and removed the install one-liner from
`docs/install/index.md` in #29304, so that page no longer appears in
this diff.

## Testing

- `TZ=UTC go test ./cli
-run='Test(CommandHelp|ServerYAML|ErrorExamples|.*Golden)' -update` and
`go test ./enterprise/cli -run=TestEnterpriseCommandHelp -update` pass
and produce the committed golden diffs.
- `go test ./cli -run 'Test.*Version|TestWrapTransport'` passes,
including `Test_wrapTransportWithVersionCheck`.
- `go run ./scripts/configdocgen` output contains the new `curl -fsSL`
description.
- `markdownlint-cli2` on the edited style guide page reports 0 errors.
- `git grep` finds no remaining `curl -L …install.sh` outside the style
guide's **Don't** example.
- After merging `main`: `make pre-commit` passes, and `make test`, `make
test-js`, and `make site/out/index.html` pass.

Linear:
https://linear.app/codercom/issue/DOCS-964/standardize-installsh-curl-flags-on-fssl-across-docs-codercom-and-the

---
🤖 Built with AI assistance.
2026-09-24 18:23:54 +00:00
Nick Vigilante d5a6047879 docs: restructure Install into the five phase deployment spine (#29304)
Restructures the Install section into the five-phase deployment spine,
so the reading order matches the order a deployment actually happens:
**plan, prepare, install, validate, operate.** Today the first thing a
reader sees is a shell command, and architecture and sizing sit
downstream in Administration, after the point where they would have been
useful.

Resolves [DOCS-869](https://linear.app/codercom/issue/DOCS-869). Part of
[DOCS-685](https://linear.app/codercom/issue/DOCS-685) and
[DOCS-738](https://linear.app/codercom/issue/DOCS-738).

> [!IMPORTANT]
> **Stacked on [#28960](https://github.com/coder/coder/pull/28960)**
(DOCS-871, terminology). Base is that branch, not `main`. Retarget to
`main` after it merges.
>
> **Paired with coder/coder.com
[#1077](https://github.com/coder/coder.com/pull/1077)**, which must
merge **first**. Without it, every inbound link to a moved page 404s in
the gap.

## Deliberately mechanical

No prose changes. The only edits inside moved pages are relative link
and image path repairs, so the diff reads as renames. That is the point:
this is the highest link-breakage change in the project, and it should
be reviewable as such.

The prose work is [DOCS-868](https://linear.app/codercom/issue/DOCS-868)
(phase overview, architecture rewrite, sizing split, actor table) and
[DOCS-872](https://linear.app/codercom/issue/DOCS-872) (new pages).

## The new spine

```text
Install and deploy Coder            /install
├── Coder CLI                                   [unchanged, retired by DOCS-870]
├── 1. Plan your deployment
│   ├── Architecture and components             [from admin/infrastructure]
│   └── Coder Validated Architecture            [from admin/infrastructure]
│       └── 1k / 2k / 3k / 10k users
├── 2. Prepare prerequisites
│   ├── Licensing                               [from admin/licensing]
│   ├── Air-gapped deployments                  [from install/airgap]
│   └── Mirror images and registries            [from install/registry-mirror-artifactory]
├── 3. Install the control plane
│   ├── Docker / Kubernetes / Rancher / OpenShift
│   ├── Cloud marketplace and VM images
│   └── Unofficial install methods
├── 4. Validate your deployment
│   └── Scale testing                           [from admin/infrastructure]
│       ├── Scale test utility
│       └── Scaling best practices
└── 5. Operate and maintain
    ├── External provisioners                   [from admin/provisioners]
    ├── Upgrading (+ best practices, ESR guides)
    └── Uninstall
```

Leaving Install: release channels become `reference/releases`, feature
stages become `reference/feature-stages`.

`docs/admin/infrastructure/` is gone entirely, which is what DOCS-738
recommended.

## Numbers

- 31 pages moved, all as `git mv` renames.
- 1 page deleted: `admin/infrastructure/index.md`, whose content was a
one-line section blurb.
- 5 new placeholder index pages, one per phase, each a sentence of
orientation plus `<children></children>`. The nav schema requires a path
on every entry, so a phase cannot exist without one.
- 265 relative links and asset paths repaired across 57 files.
- `docs/manifest.json` restructured. Entry count goes 460 to 464: plus 5
stubs, minus the deleted Infrastructure entry.

## Reviewer attention, please

**The redirects PR repairs 19 existing redirects, not just adds new
ones.** This was the surprise. `redirects.json` already had entries
whose *destinations* pointed at pages this PR moves, so they would have
started redirecting to 404s. Examples:
`/docs/architecture/architecture`, `/docs/admin/architectures`,
`/docs/scaling/scale-testing`, `/docs/licensing`, `/docs/enterprise`,
`/docs/install/offline`, `/docs/platforms`, `/docs/install/1-click`,
`/docs/admin/upgrade`, `/docs/install/cloud/ec2`, and both
`feature-stages` aliases. All 19 are fixed in the paired PR.

**This PR touches `scripts/`, so it is not docs-only.** Two release
tools write to paths that moved and would have broken silently at
release time:

- `scripts/update-release-calendar.sh`: `DOCS_FILE` now points at
`docs/reference/releases.md`.
- `scripts/releaser/docs.go`: `releasesFile`, and also `kubernetesFile`
and `rancherFile`, which pointed at `docs/install/kubernetes.md` and
`docs/install/rancher.md`.

<details>
<summary>Deliberate scope decisions</summary>

- **Self-managed vs cloud grouping is flattened.** The reconciled IA
nested platform pages under a "Self-managed platforms" parent. That
would need two more placeholder index pages for groups with no content
yet, so the platform pages sit directly under Phase 3 and the grouping
lands with the DOCS-868 prose.
- **Release-notes URLs left alone.** `scripts/releaser/release.go` and
`scripts/release/generate_release_notes.sh` embed
`https://coder.com/docs/install/releases` and `/docs/install/upgrade` in
release-note templates. The redirects cover them, and changing the
strings would require updating Go test fixtures in
`scripts/release/main_internal_test.go`. Better as its own change.
- **In-product doc links left alone.** Several `site/src` pages link to
`coder.com/docs/admin/provisioners` and similar. Those are absolute
URLs, so the redirects cover them. Updating them is a frontend change
that would pull frontend review into a docs restructure.
- **`admin/security/audit-logs.md` line 237** is hand-written prose
below the generated table, and its `../licensing/index.md` link had to
move with the licensing page. Verified `make gen` does not revert it.
- **`reference/feature-stages.md`** has generated blocks whose relative
links changed depth with the move. The generator named in its own marker
comment (`scripts/release/docs_update_feature_stages.sh`) no longer
exists in the repo, so those links were repaired by hand and the file is
effectively hand-maintained. Worth its own issue.
- **`install/cli.md` keeps its nav slot** here. DOCS-870 retires it.

</details>

## Verification

| Check | Result |
|---|---|
| Broken relative link scan | 0 in `install/`, `admin/`, `reference/`.
21 remain, all pre-existing illustrative examples in
`docs/.style/style-guide/**` and one malformed URL in `docs/README.md` |
| `make gen` | clean, manifest not clobbered, phase structure intact |
| `make lint/markdown` | pass, 508 files, 0 errors |
| `make lint/emdash` | pass |
| `make lint/docs-html` | pass |
| `make lint/prose` | pass, 1 intentional demo error, no new findings |
| `make pre-commit` | pass, including `lint/go`, `lint/ts`,
`lint/shellcheck`, and a slim build |
| Manifest audit | every path resolves to a file on disk; entry-by-entry
diff shows only the expected moves |

Generated with Coder Agents on behalf of @nickvigilante.


<details>
<summary>CI note: doc-check failure is infrastructure, not this
PR</summary>

`Analyze PR for Documentation Updates Needed` fails before it reviews
anything: the Coder account behind `agents-chat-action` returns `User is
not active (status = "suspended")`. It isn't a required check.
`check-docs` (linkspector) and every other check pass on `58ed9e3e4b`.

_CI note added by Coder Agents on behalf of @nickvigilante._
</details>
2026-09-24 13:51:38 -04:00
Nick Vigilante eb893f536d docs: move section page to index.md (#29858) 2026-09-24 13:13:27 -04:00
Nick Vigilante 5e41baf73c docs: normalize control plane, coderd, and coder server terminology (#28960)
Normalizes the three overlapping names for the thing that serves the
Coder API and dashboard. This is step 1 of the Install/Deploy and
Administration refactor
([DOCS-685](https://linear.app/codercom/issue/DOCS-685),
[DOCS-738](https://linear.app/codercom/issue/DOCS-738)) and lands first
because every later page depends on settled terminology.

Resolves [DOCS-871](https://linear.app/codercom/issue/DOCS-871).

## The rule

| Term | Means | Use when |
|---|---|---|
| control plane | The component that serves the Coder API and dashboard,
brokers connections, and coordinates provisioners | Default in prose,
diagrams, planning, sizing, security |
| `coderd` | The process that implements it | Architecture internals,
metrics, logs, flags, troubleshooting |
| `coder server` | The literal CLI command | Only when the reader will
type it |

Retired: "the Coder server" as a name for the component, and "a service"
as a standalone description of it.

## What changed

- **`docs/.style/style-guide/word-choice.md`**: new "Naming Coder's
components" rule, with do/don't examples. Also fixes a "Do" example on
that page that itself used "the Coder server".
- **`docs/reference/glossary.md`**: rewrote `coderd` and Control plane,
added a `coder server` entry. The existing Control plane entry defined
it as "the collective term for `coderd`, its provisioners, and its
database", which made it indistinguishable from the Deployment entry two
sections later. Control plane is now the component; Deployment remains
the whole installation.
- **65 pages** across `docs/admin`, `docs/install`, `docs/get-started`,
`docs/tutorials`, `docs/user-guides`, `docs/ai-coder`, and `docs/about`:
roughly 154 component-sense "Coder server" usages, 21 bare "the server"
usages meaning the control plane, 3 "a service" descriptions, and 43
unbackticked `coderd` mentions in prose.
- One real bug caught in passing:
`docs/tutorials/best-practices/security-best-practices.md` documented
`coderd server --disable-path-apps`, which is not a command. Now `coder
server`.

Generated files were not touched: `configuration-reference.md`,
`prometheus.md`, `audit-logs.md`, `reference/cli/*`, `reference/api/*`,
and the generated blocks inside `feature-stages.md`. Those still contain
the retired term and need generator-side changes; see the deferred list
below.

## Reviewer attention, please

**Anchor changes.** 11 headings were renamed, so their fragments change.
No in-repo link targets any of them (the one internal link that did was
updated), but external deep links from tickets or blog posts would
break, and fragments cannot be fixed with a redirect. Happy to revert
any of these if you would rather they ride along with the page moves in
[DOCS-869](https://linear.app/codercom/issue/DOCS-869), which changes
those URLs anyway.

<details>
<summary>Renamed headings and their old fragments</summary>

| File | Old fragment | New heading |
|---|---|---|
| `admin/networking/index.md` | `#coder-server` | `## Control plane` |
| `install/index.md` | `#starting-the-coder-server` | `## Starting the
control plane` |
| `install/uninstall.md` | `#the-coder-server-binary-and-cli` | `## The
Coder binary and CLI` |
| `install/registry-mirror-artifactory.md` |
`#step-5-configure-coder-server-or-provisioners` | `## Step 5: Configure
the control plane or provisioners` |
| `install/cloud/compute-engine.md` | `#configuring-coder-server` | `##
Configuring the control plane` |
| `get-started/index.md` |
`#cant-start-coder-server-address-already-in-use` | ``### Can't start
`coder server`: Address already in use`` |
| `tutorials/external-database.md` |
`#coder-server-fails-startup-with-...` | ``### `coder server` fails
startup with ...`` |
| `tutorials/faqs.md` |
`#how-do-i-change-the-access-url-for-my-coder-server` | `## How do I
change the access URL for my control plane?` |
| `tutorials/best-practices/security-best-practices.md` |
`#coder-server` | `## Control plane` |
| `tutorials/best-practices/security-best-practices.md` |
`#server-logs-and-audit-logs` | `### Control plane logs and audit logs`
|
| `tutorials/best-practices/scale-coder.md` | `#coder-server`,
`#how-to-capture-coder-server-metrics-with-prometheus` | `## Control
plane`, `### How to capture control plane metrics with Prometheus` |

</details>

**One deliberate deviation from the issue.** DOCS-871 proposed reserving
"sub-agent" for the Coder Agents sense and using "devcontainer agent"
for the workspace sense. I did not make that change. The glossary
already disambiguates with "Sub-agent (Coder Agents)" and "Sub-agent
(dev containers)", and "devcontainer agent" would violate the existing
dev container spelling rule in the same style guide, which requires "dev
container" as two lowercase words. The current split reads correctly and
costs no churn. Happy to revisit if you disagree.

<details>
<summary>Deferred, with reasons</summary>

- **Generated content still says "Coder server".** `reference/cli/*`
comes from Go command help text, `configuration-reference.md` from
`configdocgen`, and `reference/api/*` from Swagger annotations. Fixing
those means changing Go source, which belongs in its own PR so a docs
review does not turn into a backend review.
- **`validated-architectures/index.md` "also known as `coderd`"** is
fixed here, but the page's larger problem is that it holds four
documents in one file. That split is
[DOCS-868](https://linear.app/codercom/issue/DOCS-868).
- **"server flag" phrasing** in `admin/users/idp-sync.md` and
`admin/users/oidc-auth/index.md` means `coder server` flags. Left alone;
rewording those sentences is a copy edit, not a substitution.
- **Metric and UI labels** such as "Dashboard-to-server latency" in
`admin/networking/index.md`. Renaming risks diverging from what the
dashboard shows.
- **Pre-existing `Coder.GerundHeading` warnings** on headings this PR
touches, and a "from from" typo in `scale-coder.md`. Out of scope for a
terminology pass.
- **Peer-sense "server"** in NAT traversal prose, where "client or
server" describes the connection roles rather than the control plane.
Needs restructuring, not substitution.

</details>

## Verification

| Check | Result |
|---|---|
| `make lint/emdash` | pass |
| `make lint/markdown` | pass, 504 files, 0 errors |
| `make lint/docs-html` | pass |
| `make lint/prose` | pass, findings identical to the `main` baseline (1
intentional demo error, 145 warnings, 1 suggestion; only Vale's file
ordering and one line-number shift in `glossary.md` differ) |
| `make gen` | clean, no drift |
| `make fmt/markdown` | applied |

No redirects needed: no page moved or was renamed in this PR.

<details>
<summary>Merged main, 2026-09-14</summary>

One conflict, in `docs/ai-coder/ai-gateway/providers.md`. Both hunks
were text this PR had edited and `main` had since deleted in #29053,
which removed env-based AI provider configuration:

- The deprecated provider seeding note, which held a `coderd` backtick
fix, is gone. Took `main`.
- The failure-mode table lost its env-drift row. Took `main`'s two rows
and reapplied the `coderd` logs wording.

`main` also landed new prose carrying the retired terms, so the pass was
extended to cover it:

- `docs/admin/integrations/oauth2-provider.md`: two "the server log(s)"
in the scope-enforcement sections added by #29144 are now "the `coderd`
log(s)"; "a `scope` the server will not grant" is now "the control
plane".
- `docs/reference/cli/index.md` gained "the server" from #29104, and
stays deferred as generated content.

The new `docs/ai-coder/agent-relay/claude-code.md` needed no change, and
no page `main` added links to a heading this PR renamed.

</details>

<details>
<summary>Decision log for the wider refactor</summary>

Agreed with @nickvigilante before implementation, recorded on DOCS-685
and in the Notion outline:

1. Feature stages and release channels move to Reference; ESR upgrade
guides move under Operate. No new top-level Releases section.
2. `data-retention.md` moves to Administration > Security;
`chat-lifecycle-hooks.md` moves into the Coder Agents docs.
`admin/setup/` therefore survives as "Deployment configuration" and
`configdocgen` is not touched.
3. Prepare is advisory, not a gate, framed as "don't know where to
start? Start here", with lead times and owners per item.
4. One actor table, on the Install overview, spanning all five phases,
noting that one person can be several actors and several people can be
one actor.
5. The quickstart stays independent and is mentioned once, on the
Install overview. The proposed `server/single-machine` page is dropped.
6. Coder Validated Architecture keeps its name in nav, defined in-page,
with a glossary entry.
7. PR 3 is split: moves only, then prose, so the riskiest change reads
as a pure rename diff.
8. For every PR that moves a page, the coder.com `redirects.json` change
merges first.
9. There is no Download section and no CLI page in docs. Per-OS CLI
steps live on coder.com/download and the Install overview links to it.

</details>

Generated with Coder Agents on behalf of @nickvigilante.
2026-09-22 15:18:40 -04:00
Ahson Shaikh c61ca62d64 docs: add Easypanel to alternate install methods (#29345)
Hi — this is Ahson Shaikh, DevOps Engineer at Easypanel.
[Easypanel](https://easypanel.io) is a self-hosted Docker deployment
platform, and Coder has a one-click deployment template on Easypanel:
https://easypanel.io/templates/coder

Per @nickvigilante's suggestion, moved this from docs/install/docker.md
to the community installation methods list
(docs/install/other/index.md), matching the existing
Railway/Render/Heroku row style.

Here's Coder running after a one-click deploy via the Easypanel template
- this is the Easypanel panel view, not Coder's own UI:

![Coder running in the Easypanel
panel](https://raw.githubusercontent.com/Ahson-Shaikh/coder/add-easypanel-deploy-docs/.github/easypanel-deploy-screenshot.png)
2026-09-16 15:33:34 +00:00
Bobby Ho a031db82de docs: replace the oauth2 experiment with CODER_OAUTH2_PROVIDER_ENABLE (#29268)
docs: update OAuth2 provider documentation for GA

- Replace the `oauth2` experiment with `CODER_OAUTH2_PROVIDER_ENABLE` in the provider, MCP server, and feature-stage docs. Remove experimental wording, document CLI/env/YAML/Helm configuration, and update 404 troubleshooting. MCP still requires `CODER_EXPERIMENTS=mcp-server-http`.
- Include a 2.38 release-note draft: the provider is GA but disabled by default. Deployments using `CODER_EXPERIMENTS=oauth2` must set `CODER_OAUTH2_PROVIDER_ENABLE=true` to avoid OAuth2 endpoint 404s after upgrading. The environment variable can be set before upgrading; older binaries reject the new CLI flag and YAML key. For Helm, use `coder.env`, not `coder.commandArgs`.
- Existing applications, secrets, and user authorizations are preserved and resume when enabled. Previously issued access tokens remain valid until expiry.

Docs only; completes [PLAT-492](https://linear.app/codercom/issue/PLAT-492). Stacked on #29267.
2026-09-15 09:15:19 -07:00
Atif Ali fdcc847ce2 chore: bump bundled terraform to 1.16.2 (#29331) 2026-09-15 06:15:48 +00:00
Marcin Tojek a763e2ea6a chore(docs): update release docs for v2.36.5 (#29177)
Automated docs update for v2.36.5 release.

Created by `releasetui`.
2026-09-10 16:15:56 +02:00
Nick Vigilante b23d73d501 docs: retire the generated feature stage lists (#29113)
## Problem

`docs/install/releases/feature-stages.md` advertised two generated
lists, and neither one earned its place:

- **Available early access features** rendered "Currently no
experimental features are available." The generator read
`ExperimentsSafe`, which is empty, while `ExperimentsKnown` in
`codersdk/deployment.go` defines fourteen experiments. The page told
readers no experimental features existed, which is false.
- **Available beta features** rendered a table built from `state: beta`
nodes in `docs/manifest.json`. It is only as accurate as those flags,
which are easy to forget when a feature graduates.

Both are drift surfaces that promise a completeness the docs cannot
maintain.

## Change

Retire the indexes rather than repair them:

- Delete `scripts/release/docs_update_feature_stages.sh`.
- Remove both generated sections from `feature-stages.md`, along with
their `BEGIN`/`END` markers and `DO NOT EDIT` banners.
- Drop the `docs/install/releases/feature-stages.md` Makefile target and
its two generated-files-list entries, so the page is no longer treated
as generated.

The page keeps everything that describes the stages themselves: the
stage comparison table, the early access / beta / GA guidance, and the
`--experiments` enabling instructions. Nothing else links to the removed
anchors.

## Verification

- `make gen` leaves no unstaged changes beyond the three intended edits.
- `pnpm run lint-docs` passes with 0 errors; `markdown-table-formatter`
reports no formatting to apply.
- `grep` confirms no remaining references to the deleted script, and no
inbound links to `#available-beta-features` or
`#available-early-access-features`.

## Context

Supersedes #28949, which took the opposite approach and generated the
experiments list from `ExperimentsKnown`. Following discussion with
David, the decision is not to advertise either list.

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

**Why not fix the experiments list instead?** That was #28949: a new
`scripts/experimentsdocgen` generator plus a committed
`docs/experiments.json`, generating the table from `ExperimentsKnown`
with descriptions parsed out of the constants' comments. It worked, but
it made the docs responsible for tracking an internal, unstable surface.
Experiments are by definition subject to removal or rename without
notice, and several of the constant comments are developer notes rather
than user-facing prose.

**Why remove the beta table too?** The original ask covered the
experiments list. The beta table shares the same failure mode: it is a
completeness claim maintained by proxy, through `state` flags in
`docs/manifest.json`, with nothing that fails when a feature ships to GA
and the flag is not updated. Deleting the script removes both, and David
confirmed retiring both lists.

**Why remove the Makefile target rather than leave a no-op?** With no
generated regions left in the file, keeping the target would mean the
`make -B gen` unstaged-files check still guards a page nothing
generates. Removing it lets the page be edited as ordinary prose.

**What was deliberately left alone.** The `state: beta` flags in
`docs/manifest.json` stay: they drive badges elsewhere in the docs and
are not part of this change. `ExperimentsSafe` and `ExperimentsKnown` in
`codersdk` are untouched. The feature-stage definitions and the
`--experiments` instructions stay, since readers still need to know what
the stages mean and how to opt in, and that content does not go stale as
features move between stages.

</details>

I have read the AI Contribution guidelines.

---

Linear:
[DOCS-878](https://linear.app/codercom/issue/DOCS-878/remove-the-feature-stages-generator-script-and-retire-the-generated)

🤖 Generated with Coder Agents on behalf of @nickvigilante.


<details>
<summary>CI note: unrelated flakes on the first run</summary>

The initial run of `test-go-pg-17` failed in `cli` and `coderd`:

-
`TestSSH_OneShotCommandMode/{ClosesStdinOnEOF,DoesNotRequestPTY,PropagatesExitCode,RequestsPTYWithFlag}`
-
`TestWorkspaceUpdateAutostart/{DST_start,friday_to_monday,monday_to_tuesday}`
- `TestWorkspaceFilterManual/FilterQueryHasAgentTimeout`
- The `cli` package then hit `panic: test timed out after 25m0s`.

This PR changes no Go code and no CI configuration; the diff is one
deleted shell script, one Markdown page, and the Makefile wiring between
them. Re-running the failed jobs turned everything green with no code
changes.

</details>
2026-09-09 09:44:20 -04:00
Nick Vigilante 7846490770 docs: reconcile H1/label mismatches into front-matter titles (Phase 3) (#28036)
## Summary

**Batch B of Phase 3** of the H1 → front-matter migration (`DOCS-484`;
parent `DOCS-477`), the editorial follow-up to Batch A (#28030). For the
**124** hand-authored pages whose leading body H1 differed from the
manifest nav label, this promotes the richer body H1 to the front-matter
**page title** and drops the duplicate H1, while keeping the short
manifest **label** as the sidebar entry.

Policy agreed with the docs owner:
- Short sidebar labels win. Duplicate sidebar labels are acceptable.
- Identical **page titles** across two pages are not. On a collision,
rename the non-generated page's title.

## Page-title collisions resolved

Promoting the H1 created 4 page-title collisions; each is disambiguated
by renaming the non-generated / secondary page (sidebar labels left
unchanged):

| page | sidebar label | body H1 | → page title |
|------|---------------|---------|--------------|
| `install/index.md` | Install | Installing Coder | **Install Coder in
your infrastructure** |
| `install/cli.md` | Coder CLI | Installing Coder | **Install the Coder
CLI** |
| `ai-gateway/clients/jetbrains.md` | JetBrains | JetBrains IDEs |
**JetBrains** |
| `workspace-access/web-ides.md` | Web IDEs and Coder Apps | Web IDEs |
Web IDEs *(kept — primary user guide)* |
| `extending-templates/web-ides.md` | Web IDEs and Coder Apps | Web IDEs
| **Web IDEs in templates** |
| `workspace-management.md` | Workspace Management | Workspaces |
**Manage workspaces** *(vs generated `api/workspaces.md`)* |

These titles are the only non-mechanical editorial calls in this PR.

## Deliberately excluded: generated pages

`admin/security/audit-logs.md` and
`admin/setup/configuration-reference.md` are `make gen` outputs
(`auditdocgen` / `configdocgen`) that Phase 2 did **not** update, so a
hand-added title would be reverted on the next generation. They're
excluded here and need their generators taught to emit front matter
first (Phase 2 pattern), tracked as `DOCS-631`. Batch A (#28030) had the
same issue for three other generated pages; it has been corrected there
too.

## Verification

AI was the primary author of this PR (see disclosure below); per the [AI
Contribution
Guidelines](https://coder.com/docs/about/contributing/AI_CONTRIBUTING)
here is the manual verification.

- Promote = set front-matter `title` to the body H1 (or the
disambiguated title above) and remove that one duplicate H1. No other
body prose is reflowed.
- Every added front-matter block parses as YAML; all files pass `pnpm
check-docs` (markdownlint-cli2 + table formatter): `Summary: 0
error(s)`.
- Removing the H1 orphaned one in-page fragment (`[MCP](#mcp)` in
`ai-gateway/mcp.md`), now repointed. A cross-file fragment audit into
the retitled pages found no real breakage.


Anchor-change note

Unlike Batch A (title unchanged, a rendered no-op), Batch B changes each
page's effective title from the manifest label to the body H1, so the
rendered H1 **anchor slug changes**. An audit of cross-file
`.md#fragment` links into these pages surfaced no links that break as a
result (the only hits were false positives against a still-present `##
TLS & Reverse Proxy` heading). Same-file fragments are enforced by
markdownlint MD051, which is green.

## Title casing (follow-up, DOCS-742)

A follow-up commit puts the promoted titles into sentence case and
removes leading gerunds (for example, `Managing workspace schedules` →
`Manage workspace schedules`): 57 of the 120 titles changed, the other
63 were already compliant. Proper nouns and branded names (Coder
Validated Architecture, JetBrains, File Browser, Dev Containers,
Island), acronyms (API, CLI, IDE, MCP, OIDC, URL, UI, CI/CD), the
Premium license tier, and maturity labels (Beta, Experimental) are
preserved. The four `Nk-users` pages become `Reference architecture: up
to N users` (lowercase, matching the CVA landing page's own usage); the
CVA landing page keeps its branded title. `pnpm check-docs`: `Summary: 0
error(s)`.

Linear: DOCS-484, DOCS-742

> This PR was created with AI assistance (Coder Agents).
2026-09-08 16:34:00 +00:00
Marcin Tojek ab1959d661 chore(docs): update release docs for v2.37.1 (#29076)
Automated docs update for v2.37.1 release.

Created by `releasetui`.
2026-09-08 11:08:50 +02:00
Marcin Tojek 1cd49cc7e4 chore(docs): update release docs for v2.34.10 (#28979)
Automated docs update for v2.34.10 release.

Created by `releasetui`.
2026-09-04 12:35:37 +02:00
Jeremy Ruppel 521c923ac3 docs(docs/install): add template builder registry URL to Artifactory mirror guide (#28904)
## Summary

Documents the Coder server environment variable needed to point the
in-product **template builder** at a JFrog Artifactory registry mirror,
and cross-links the two relevant install guides.

The Artifactory guide already covered mirroring the Coder Registry and
configuring the Terraform CLI on Coder, but it never mentioned
`CODER_TEMPLATE_BUILDER_REGISTRY_URL`, which the template builder needs
so it generates module source paths against the mirror instead of
`registry.coder.com`. This env var was only documented in the
[air-gapped deployments](https://coder.com/docs/install/airgap) guide.

## Changes

- `docs/install/registry-mirror-artifactory.md`: new **Step 6: Point the
template builder at your mirror**
- Documents
`CODER_TEMPLATE_BUILDER_REGISTRY_URL=<your-artifactory-host>` and the
accepted value format (bare host, optional port; scheme/trailing slash
stripped; path/query/fragment/credentials rejected at startup).
- Notes the `CODER_DISABLE_TEMPLATE_BUILDER=true` fallback for fully
air-gapped deployments.
  - Links to the air-gapped deployments doc's Template builder section.
- `docs/install/airgap.md`: the Template builder section now cross-links
to the Artifactory mirror guide.

## Validation

- `pnpm run format-docs` — no changes
- `pnpm run lint-docs` — 0 errors

---

This PR was generated by Coder Agents on behalf of @jeremyruppel.
2026-09-02 10:04:35 -04:00
Marcin Tojek fe545d5e3a chore(docs): update release docs for v2.37.0 (#28830) 2026-09-01 16:04:44 +02:00
Jeremy Ruppel c73f34c35d feat: honor the deployment registry mirror in template builder bases (#28727)
## Summary

Threads the deployment's configured module registry
(`CODER_TEMPLATE_BUILDER_REGISTRY_URL`) into template-builder **base**
rendering, so a base that embeds a catalog module (e.g. the quickstart
base's `git-clone`) resolves its `source` through a registry mirror the
same way wizard-composed modules already do. Previously base-embedded
module sources hardcoded `registry.coder.com`, so on a
mirror/private-registry deployment a base-embedded module reached the
public registry while wizard modules used the mirror.

Implements [DOCS-610](https://linear.app/codercom/issue/DOCS-610).

## What changed

* `BaseRenderContext.RegistryBase` (new field), mirroring
`ModuleRenderContext.RegistryBase`. `Compose` threads the deployment
registry through `renderBase` into the base render context, and the four
hardcoded base module sources (`quickstart` git-clone,
`azure-linux`/`gcp-linux`/`gcp-windows` region modules) now use `{{
.RegistryBase }}`. Because the value defaults back to
`registry.coder.com`, rendered sources stay byte-identical; the only
golden change is the removal of the now-stale quickstart "follow-up"
note.
* **Boot-time validation.**
`codersdk.ValidateTemplateBuilderRegistryURL` runs in
`DeploymentValues.Validate()`, gated on the builder being enabled,
matching the chat-hook precedent. A malformed value fails at server
start naming the option, instead of surfacing as a per-request error to
a template author who cannot fix it. It uses `net/url` in authority form
to reject a scheme, path, query, fragment, trailing slash, or
credentials and accept a bare `host[:port]`; it does not canonicalize
the host.
* `Compose` **trusts the validated value**, defaulting an unset one and
defensively rejecting a malformed one for direct callers that bypass
boot.

## Tests

* `codersdk`: validator accept/reject matrix (incl.
credentials-without-echo) and a `DeploymentValues.Validate` boundary
test with a disabled-skips-validation case.
* `templatebuilder`: a base honors the mirror and falls back to the
default when unset, plus a defensive-reject case; existing compose tests
updated to bare-host registry values.

<details><summary>Design decision log</summary>

This PR is a deliberately minimal reimplementation of the
[DOCS-610](https://linear.app/codercom/issue/DOCS-610/template-builder-base-embedded-modules-should-honor-the-deployment)
scope, started fresh from `main` rather than carrying forward an
earlier, larger draft (coder/coder#28480). Key decisions:

* **Scope kept to the ticket.** The ticket's fix is three bullets: add a
registry field to `BaseRenderContext`, thread the deployment
`RegistryURL` through `Compose` -> `renderBase`, and use it in base
module sources. Independent hardening explored in the earlier draft was
dropped as out of scope: `terraform-svchost`-based IDN/punycode/port
canonicalization, a rendered-HCL backstop with a 500 mapping, and HCL
module-source extraction helpers. Telemetry misclassification of mirror
modules is tracked separately
([DOCS-712](https://linear.app/codercom/issue/DOCS-712/telemetry-misclassifies-registry-mirror-modules-as-non-coder))
and is not addressed here.
* **Default lives in the render layer.**
`templatebuilder.DefaultRegistryBase` holds the fallback host;
`codersdk` keeps its own option-default literal. An earlier version
exported the constant from `codersdk`, which only emitted a dead
`typesGenerated.ts` entry that nothing in the frontend consumed, so it
was moved out. The `codersdk` validator is a function, so it generates
no TS type.
* **Validate at the config boundary, fail fast.** The repo convention is
to hard-fail structurally invalid config in
`DeploymentValues.Validate()` (access URL, OAuth lifetimes, chat hook
URL) and to warn only for functional-but-risky settings. A malformed
registry host is structurally invalid, so it fails at boot. This also
puts the error in front of the admin who set it, rather than a template
author hitting a per-request error they cannot fix.
* `net/url`**, not a regex.** The codebase validates identifiers/names
with regexes but host/URL-shaped config with `url.Parse` (chat hook URL,
OAuth redirect URIs, AI provider base URL). This value is host-shaped,
so it follows that convention. `url.Parse("//" + v)` with `u.Host == v`
rejects a scheme/path/query/fragment/trailing-slash in one check.

</details>

> This PR was created with AI assistance (Coder Agents).
2026-08-31 09:32:24 -04:00
Nick Vigilante bc77c40296 docs: add front-matter titles to mechanical and no-H1 pages (Phase 3) (#28030)
## Summary

**Batch A of Phase 3** of the H1 → front-matter migration (`DOCS-484`;
parent `DOCS-477`). Adds a front-matter `title` to every navigable docs
page whose title can be migrated **mechanically**, with no editorial
judgment.

This is the content step that Phase 1 (renderers prefer front-matter
title, `DOCS-482`) and Phase 2 (tooling + generators front-matter-aware,
`DOCS-483`) unblocked. Both are merged; coder.com #964/#974 are merged
and live.

**Rendered no-op.** The renderers already resolve the page title from
the manifest and hide the leading body H1 (Phase 1), so no page changes
visually. This just moves the title into front matter where Fumadocs and
the migrated tooling can read it.

## What's in this batch

Dry-run on `main` (464 navigable pages) splits into:

| category | count | this PR |
|----------|-------|---------|
| already has front-matter title (Reference, from Phase 2 generators) |
196 | skipped (idempotent) |
| **mechanical** — leading body H1 equals the manifest label | 138 | ✅
add front-matter `title`, drop the duplicate H1 |
| **no body H1** — renders under the manifest label only | 4 | ✅ add
front-matter `title` only |
| **mismatch** — body H1 differs from the manifest label | 126 | ⏭️
deferred (needs an editorial decision, see below) |

142 files changed, all under `docs/`.

## Deliberately out of scope: the 126 mismatches

Pages where the body H1 is richer than the short sidebar label (e.g.
label **Modules** / H1 *Contributing modules*, label **Install** / H1
*Installing Coder*) need a canonical-title decision, not a script. A few
even look like the body H1 is the redundant one (`install/cli.md` and
`install/index.md` both carry the H1 *Installing Coder*). These will
land in follow-up batches **by nav section** once the policy is set, so
each gets real review.

## Verification

AI was the primary author of this PR (see disclosure below); per the [AI
Contribution
Guidelines](https://coder.com/docs/about/contributing/AI_CONTRIBUTING)
here is the manual verification.

- Every added front-matter block parses as YAML and its `title`
round-trips to the manifest label (checked programmatically across all
142 files).
- Every removed line is a leading `# H1` that equalled the manifest
title; no body prose was reflowed. Front matter is correctly hoisted
above pre-existing `<!-- markdownlint-disable -->` comments on the two
pages that had them.
- `pnpm check-docs` (markdownlint-cli2 + table formatter) passes on the
changed set: `Summary: 0 error(s)`. `MD041` stays off (re-enabled in
Phase 4); `MD025` is not tripped because the duplicate body H1s are
removed.

```
$ pnpm exec markdownlint-cli2 $(git diff --name-only origin/main)
Linting: 142 file(s)
Summary: 0 error(s)
```

Linear: DOCS-484

> This PR was created with AI assistance (Coder Agents).
2026-08-27 12:34:13 -04:00
Nick VigilanteandIan Evans 47a77016c4 feat(docs/.style): enable Coder.SelectClick, use "select" over "click" (#28599)
Adds a Vale rule enforcing the existing "select, not click" style
guidance: "click" assumes the reader has a mouse, and touch, keyboard,
and assistive-technology users don't click.

`Coder.SelectClick` (warning severity) flags
`click`/`clicks`/`clicked`/`clicking` in prose, exempting:

- Literal mouse-button phrasing (`left-click`, `right-click`,
`middle-click`, `mouse click`, and combinations) — these name an actual
mouse action with no device-agnostic equivalent.
- `one-click`/`single-click` as a compound feature descriptor
("one-click install").

Reworded every existing instructional "click" in `docs/` to the matching
`select` form (`select`/`selects`/`selections`/`selected`/`selecting`)
so the rule ships with a clean baseline, per this repo's Vale-rule
doctrine.

Left alone, deliberately: two generated API reference pages
(`docs/reference/api/enterprise.md`, `schemas.md`) use "click" as an
analytics-event noun, tied to a Go source doc comment and an operation
ID (`report-a-premium-paywall-click`). Fixing those means editing
generated code and an API operation ID, which is out of scope for a
docs-style PR — see the rule's own comments for the reasoning. That
leaves 2 non-zero-baseline findings for this rule.

---
🤖 Built with AI assistance.

---------

Co-authored-by: Ian Evans <5760366+ianjevans@users.noreply.github.com>
2026-08-27 16:24:06 +00:00
Marcin Tojek 31a976b288 chore(docs): update release docs for v2.35.6 (#28577)
Automated docs update for v2.35.6 release.

Created by `releasetui`.
2026-08-25 18:33:58 +02:00
Paweł BanaszewskiandNick Vigilante 4ce8e8ed56 docs: address AI Gateway documentation review feedback (#28309)
Applies the review feedback from #27794. Prose only.

---------

Co-authored-by: Nick Vigilante <nickvigilante@users.noreply.github.com>
2026-08-23 19:42:48 +00:00
Marcin Tojek 2529a54cfc chore(docs): update release docs for v2.36.1 (#28357)
Automated docs update for v2.36.1 release.

Created by `releasetui`.
2026-08-20 10:01:27 +02:00
david-fraley 8203b2ebaf feat!: hide Coder Tasks behind the enable-ai-tasks flag (#28008) 2026-08-19 14:46:10 -05:00
Nick Vigilante 2ee6f459b2 docs: uppercase mixed-case GitHub-style callout markers [DOCS-681] (#28304)
## What

Uppercase the mixed-case GitHub-style callout markers in the docs corpus
to the canonical all-caps form.

- `docs/install/rancher.md`: `> [!Important]` -> `> [!IMPORTANT]`
- `docs/user-guides/shared-workspaces.md`: `> [!Important]` -> `>
[!IMPORTANT]`
- `docs/user-guides/workspace-access/index.md`: `> [!Note]` -> `>
[!NOTE]`

A full-corpus scan confirmed these were the only mixed-case markers.

## Why

GitHub alerts, the hosted docs (coder.com), and the offlinedocs Fumadocs
renderer all require all-caps alert types (`[!NOTE]`, `[!IMPORTANT]`,
and so on). The mixed-case form rendered as literal text instead of a
styled alert (on some pages directly next to a correctly-rendered
all-caps alert), so this is a genuine rendering fix on GitHub and
coder.com, not an offline-pipeline accommodation.

Surfaced by the offlinedocs Fumadocs migration review (CRF-60 on
#27390). Tracked separately from the space-after-`!` fix (DOCS-680), per
request.

Linear:
[DOCS-681](https://linear.app/codercom/issue/DOCS-681/uppercase-mixed-case-github-style-callout-markers-across-docs)

> This PR was created with AI assistance (Coder Agents).
2026-08-19 11:48:32 -04:00
Matt Vollmer 52bd05adb4 docs: remove AI Governance Add-On references (#28073)
## Summary

Replaces all remaining "AI Governance Add-On" references with language
consistent with AI Governance being included with a Premium license.

**`docs/ai-coder/ai-gateway/standalone.md`**

- Admonition: "AI Gateway requires the AI Governance Add-On...
deployments without the add-on will not be able to access" → "AI Gateway
requires a Premium license. Community deployments cannot access AI
Gateway."
- Requirements list: "A Coder license with the AI Governance Add-On" →
"A Premium license with AI Governance"

**`docs/install/airgap.md`**

- Table row: "deployments with the AI Governance Add On" → "deployments
with AI Governance"

**`docs/reference/glossary.md`**

- Agent Firewall, AI Gateway, AI Gateway Proxy entries: "This feature
requires the AI Governance Add-On" → "This feature requires a Premium
license"
- Agent Workspace Build entry: "the AI Governance Add-On expands the
allowance" → "a Premium license expands the allowance"
- Heading: "### AI Governance Add-On" → "### AI Governance"
- Definition: "A separate per-user license for Premium customers,
purchased on top of a Premium subscription..." → "Included with a
Premium license, AI Governance unlocks..."

**`docs/ai-coder/ai-governance.md`**

- Removed the "Identifying AI seat consumers" section (heading through
end of file), which described an "AI add-on column" in the UI

## Note

References to Agent Workspace Builds will be eliminated in a separate PR
that removes Coder Tasks from the docs.

---

PR generated with Coder Agents.
2026-08-12 11:35:36 -04:00
Matt VollmerandNick Vigilante 75e0790cd7 docs: remove beta references from Coder Agents docs and manifest (#27939)
Removes all references to "beta" from the Coder Agents documentation
under `docs/ai-coder/agents/` and the corresponding `"state": ["beta"]`
entries in `docs/manifest.json`. Also updates screenshots, video, and
hero image, and regenerates the auto-generated feature-stages table.

**Beta reference removal:**
- `getting-started.md`: Removed "Coder Agents is in Beta" from the top
note, "is in beta" from the Chats API note, and "during Beta" from the
feedback section. Removed the version/stability note pinning 2.33.1.
- `index.md`: Removed the "Product status" section that stated Coder
Agents is in Beta.
- `manifest.json`: Removed `"state": ["beta"]` from 17 entries for pages
under `docs/ai-coder/agents/`. Preserved all `premium` and `early
access` states.
- `feature-stages.md`: Regenerated the auto-generated beta features
table, which no longer lists Coder Agents.

**Asset updates:**
- `coder-agents-ui.mp4`: Updated demo video on the agents landing page.
- `llm-providers.png`: Updated LLM provider support screenshot.
- `models-list.png`: Updated models list screenshot.
- `models-add-model.png`: Updated add model form screenshot.
- `agents-hero-image.png`: Updated hero image on the `docs/ai-coder`
landing page.

Two references in `models.md` (`v1beta` in the Google Gemini API URL and
`anthropic-beta` in the Anthropic header name) were left unchanged as
they are provider API identifiers, not product status labels.

PR generated with Coder Agents

---------

Co-authored-by: Nick Vigilante <nickvigilante@users.noreply.github.com>
2026-08-11 08:57:57 -04:00
Marcin Tojek cfeae56bed chore(docs): update release docs for v2.35.4 (#27972)
Automated docs update for v2.35.4 release.

Created by `releasetui`.
2026-08-10 11:53:47 +02:00
Marcin Tojek 0414948454 chore(docs): update release docs for v2.34.8 (#27970)
Automated docs update for v2.34.8 release.

Created by `releasetui`.
2026-08-10 09:52:49 +02:00
Ben Potter 79723db2d2 docs: replace enterprise-base image references with example-base (#27025)
Follow-up to #27018, sweeping the remaining
`codercom/enterprise-base:ubuntu` references to
`codercom/example-base:ubuntu` and `coder/enterprise-images` links to
[coder/images](https://github.com/coder/images). The `example-` prefix
is the recommended one for new deployments per the coder/images README.

Covers the 11 docs pages flagged by doc-check on #27018 plus the
embedded `examples/templates/docker` and `examples/templates/kubernetes`
starter templates (image string only; the `image` variable lives in the
coder/registry templates, see coder/registry#943).

OpenShift imagestream names in `docs/install/openshift.md` keep the
`enterprise-base` local name; only the upstream image reference changed.

Part of DEVREL-201.

🤖 Generated with Coder Agents using Claude, on behalf of @bpmct
2026-08-04 13:47:55 -07:00
Marcin Tojek 866eb970a4 docs: correct 2.35 stable version to v2.35.3 (#27842)
## Summary

Follow-up to #27828, addressing review feedback from @matifali.

The automated `releasetui` update in #27828 promoted `2.36.0` to
Mainline but
left two stale references to the 2.35 stable channel:

- `docs/install/rancher.md`: **Stable** was left at `2.34.6` instead of
being
  promoted to the current 2.35 stable patch.
- `docs/install/releases/index.md`: the 2.35 row was marked **Stable**
but its
  latest release still pointed at `v2.35.2`.

The latest 2.35 patch is `v2.35.3` (see the `v2.35.3` release tag), so
both are
now updated accordingly.

## Changes

- `docs/install/rancher.md`: Stable `2.34.6` -> `2.35.3`
- `docs/install/releases/index.md`: 2.35 latest release `v2.35.2` ->
`v2.35.3`

<details>
<summary>Review comments addressed</summary>

- `docs/install/rancher.md` (matifali): "A bit late, but shouldn't the
stable be now 2.35.3?"
- `docs/install/releases/index.md` (matifali): "The latest stable is
2.35.3 and not 2.35.2"

</details>

> [!NOTE]
> This PR was generated by Coder Agents on behalf of @mtojek.
2026-08-04 15:09:05 +02:00
Marcin Tojek 11b38272f6 chore(docs): update release docs for v2.36.0 (#27828)
Automated docs update for v2.36.0 release.

Created by `releasetui`.
2026-08-04 12:54:59 +02:00
Steven Masley 52423eb87b feat: promote MinimumImplicitMember experiment to GA (#27472)
Promotes the `minimum-implicit-member` experiment to GA and removes it.

## What changes

- The `minimum-implicit-member` experiment constant, its
`RoleOptions.MinimumImplicitMember` toggle, and the global
`rbac.MinimumImplicitMember()` accessor are deleted. The minimal-member
behavior is now the only behavior: `organization-member` and
`organization-service-account` carry only the floor (read-self records,
notifications, and similar) and grant **no workspace permissions**.
Workspace access lives exclusively on the
`organization-workspace-access` role.
- The experiment gate on customizing `default_org_member_roles` (`PATCH
/organizations/{org}`) is removed; the built-in-roles-only validation
remains.
- The dashboard's Default Roles section and the implied-roles display on
the members page are no longer experiment-gated.
- Admin docs: new "Default member roles" section in
`docs/admin/users/organizations.md`, cross-linked from
`groups-roles.md`.

## Why this is safe for existing deployments

Migration `000516` (shipped earlier) backfilled
`default_org_member_roles` with `['organization-workspace-access']` on
every organization. Members therefore keep exactly the effective
permissions they had with the experiment off; the workspace elevation
flows through the default role instead of being baked into
`organization-member`.

**Rollback caveat:** rolling back past this release restores the bundled
elevation, silently re-granting workspace access to members of
organizations that cleared their default roles.

## Review

Deep-review R1 findings are addressed in `chore: address deep-review
findings` (copy fixes, read-only Default Roles for viewers, removable
overlapping explicit grants, RBAC prose restoration, test
de-tautologizing, docs). Point-by-point disposition is in the PR
comments.

---

Generated by Coder Agents on behalf of @Emyrk.
2026-08-03 15:56:56 -05:00
Marcin TojekandNick Vigilante 07073024ee docs: update 2.35 latest release to v2.35.3 (#27511)
Updates the release calendar in `docs/install/releases/index.md` so the
2.35 mainline row points at the latest patch release `v2.35.3` instead
of `v2.35.2`.

> [!NOTE]
> This PR was generated by Coder Agents on behalf of @mtojek.

---------

Co-authored-by: Nick Vigilante <nickvigilante@users.noreply.github.com>
2026-08-03 14:32:12 +00:00
Paweł BanaszewskiandCian Johnston 18128b7b52 docs: add standalone AI Gateway docs (#27592)
Documents standalone AI Gateway deployment, Gateway key authentication,
monitoring, and the updated embedded vs standalone topology in the AI
Gateway docs.

---------

Co-authored-by: Cian Johnston <cian@coder.com>
2026-07-29 19:38:22 +02:00
Matt Vollmer 4987afada7 docs: present AI Governance as included with Premium (#27545)
## Summary

AI Governance is now included with Premium licenses instead of being
sold as a separate per-user add-on. This updates `docs/` to describe the
new packaging, removes "Add-On" from AI Governance references, and
refreshes the editions architecture diagram.

## Changes

- **`docs/ai-coder/ai-governance.md`**: title is now "AI Governance";
rewrote the licensing statements (previously "a separate, per-user
license... not included with a Premium subscription and must be
purchased separately") to state it is included with Premium. The
usage-pool section now attributes the shared Agent Workspace Build pool
to Premium deployments.
- **Repeated admonition (28 files under `ai-coder/agent-firewall/` and
`ai-coder/ai-gateway/`)**: replaced "requires the AI Governance Add-On /
as of Coder v2.32, deployments without the add-on..." with "is part of
AI Governance, which is included with a Premium license." The v2.32
add-on gate no longer applies; the gate is now Premium vs. Community.
- **`docs/ai-coder/index.md`, `security.md`, `tasks.md`,
`usage-data-reporting.md`, `admin/licensing/index.md`,
`install/releases/esr-2.29-2.34-upgrade.md`,
`ai-gateway/ai-gateway-proxy/setup.md`,
`ai-gateway/clients/claude-code.md`**: reworded add-on references to
Premium inclusion.
- **`docs/manifest.json`**: nav title "AI Governance Add-On" → "AI
Governance", updated two descriptions, and swapped the 25 `"state": ["ai
governance add-on"]` badges to `["premium"]` so the sidebar badge reads
"Premium" instead of "AI Governance Add-On".
- **`docs/images/single-region-architecture.png`**: refreshed the
diagram in the **Community and Premium editions** tab on
[Architecture](https://coder.com/docs/admin/infrastructure/architecture).
Also deleted the unreferenced `single-region-architecture.svg` copy.

## Follow-ups outside this PR

- The `"ai governance add-on"` doc-state badge is defined in
`coder/coder.com` (`src/utils/docs/state.ts`). After this merges, no
manifest entry uses that key, so it becomes dead config and can be
removed there.
- `enterprise/coderd/license/license.go:564-572` still warns admins that
"The AI Governance add-on is required to use AI Gateway." That backend
string will contradict these docs once shipped.

## Verification

- `pnpm run lint-docs`: 0 errors across 504 files
- `make lint/emdash`: clean
- Vale on the changed Markdown files: 0 errors; remaining warnings are
pre-existing gerund headings on untouched lines
- `docs/manifest.json` validated as JSON
- Confirmed the deleted SVG had no references anywhere in the repo

---

PR generated with Coder Agents on behalf of @mattvollmer.
2026-07-29 08:45:20 -04:00
Marcin Tojek 3c61a9a939 chore(docs): update release docs for v2.34.7 (#27591)
Automated docs update for v2.34.7 release.

Created by `releasetui`.
2026-07-28 16:51:31 +01:00
Atif Ali 025ded0536 docs: remove beta labels from user secrets (#27510) 2026-07-27 19:34:29 +05:00
Nick Vigilante 73af2ca632 docs: audit and fix manifest.json page descriptions for SEO (#27267)
## What

Audit and fix the page `description` fields in `docs/manifest.json` so
each one is accurate, unique, and follows meta-description SEO best
practices, targeting 70-155 characters.

Tracking: DOCS-576

## Why

Many manifest descriptions were terse (243 of 272 hand-maintained
descriptions were under 70 characters), a few reused another page's
description (copy/paste errors), and one just repeated its own title.
These feed the per-page `<meta name="description">` on coder.com/docs,
so they matter for search snippets and click-through.

## What changed

The manifest diff is +244 / -244 lines, touching only `description`
string values (0 structural lines changed). A second commit regenerates
one downstream file (see Generated file below).

- **Fixed 5 copy/paste errors** where a page reused another page's
description:
  - `admin/monitoring/index.md` (had Security's text)
  - `admin/monitoring/metrics.md` (had Logs' text)
- `admin/templates/template-permissions.md` (had "Creating Templates"
text)
  - `admin/networking/stun.md` (had Port Forwarding's text)
- `admin/provisioners/manage-provisioner-jobs.md` (had the provisioners
index text)
- **Fixed `reference/index.md`**, whose description merely repeated the
title "Reference".
- **Corrected wording**: "Coderd API" to Coder REST API; "VSCode" to VS
Code; dropped the `&` shorthand on the AI Gateway index per the docs
style guide.
- **Corrected accuracy**: the AI landing page listed outdated example
agents (GPT-Code, OpenDevin, SWE-Agent); it now references agents used
elsewhere in the docs (Claude Code, Aider).
- **Expanded terse descriptions** into the 70-155 range with
active-voice, front-loaded phrasing.

## Generated file

`docs/install/releases/feature-stages.md` is generated by
`scripts/release/docs_update_feature_stages.sh`, which copies the beta
pages' manifest descriptions verbatim into the beta-features table.
Three rows (MCP Server, JetBrains Toolbox, Coder Agents) update to match
the new descriptions; User secrets is unchanged. Regenerated with `make
gen` so the generated-files check stays clean.

## Scope / exclusions

Auto-generated reference subtrees are intentionally left untouched,
since `make gen` rebuilds them from source and would revert hand edits
(and fail the generated-files check):

- `Reference > Command Line` children, from `scripts/clidocgen` (each
command's `Short` help)
- `Reference > REST API` children, from `scripts/apidocgen`
- `Reference > Agent API` children

The section index nodes themselves (Reference, REST API, Command Line,
Agent API) are hand-maintained and are in scope.

## Validation

- `docs/manifest.json` is valid JSON; diff touches only `description`
values.
- All 272 in-scope descriptions are now 70-155 characters, with 0
duplicates across distinct pages.
- No double quotes, backslashes, em/en dashes, or `&` / `<` / `>` in
descriptions.
- Biome 2.4.10 (`scripts/biome_format.sh`) is a no-op on the result.
- `scripts/check_emdash.sh` passes.

> This PR was created with AI assistance (Coder Agents).
2026-07-23 16:24:06 -05:00
Nick Vigilante c84aa564ba docs: normalize code-fence languages for Shiki compatibility (#27161)
Normalizes non-standard code-fence language tags across `docs/**` so a
strict highlighter (Shiki, used by Fumadocs) won't fail the build on an
unrecognized language, and unifies redundant synonym tags onto one
canonical form per language. The current renderer (Speed-Highlight)
detects the language from the code content, not the fence label, so this
drift wasn't visible until now.

## Changes

- `hcl` -> `tf` (199 fences, including indented ones nested in
numbered/bulleted lists). Shiki ships `hcl` and `terraform` as two
distinct grammars (not aliases); every `hcl`-tagged fence in `docs/**`
is actually Terraform resource/data/provider syntax, so the more
specific `terraform` grammar is correct for all of them. `tf` is Shiki's
own alias for that grammar, and it's also what GitHub's own markdown
renderer resolves to the same HCL/Terraform highlighting.
- `pwsh`/`powershell` -> `ps1`. Both `ps` and `ps1` are registered
PowerShell aliases in Shiki, but on GitHub's renderer only `.ps1` is a
registered file extension (`.ps` isn't), so `ps1` renders identically to
`powershell` there today while bare `ps` would silently lose
highlighting.
- `env` -> `dotenv` (a dedicated Shiki grammar for `KEY=VALUE` files)
- `text`/`output`/`none`/`url` -> `txt`. Same built-in plain-text
fallback either way, just shorter.
- `Dockerfile` -> `dockerfile` (lowercase)
- `bash`/`shell` -> `sh` (732 fences). Shiki and GitHub both alias all
three to a single shell grammar; this was already the style guide's
stated preference, just not enforced across the existing corpus until
now.
- `markdown` -> `md` (4 fences). Alias of the same grammar in both Shiki
and GitHub.
- `jsonc` -> `json` (1 fence). The block has no comments or trailing
commas, so it doesn't need the comments-capable grammar.
- `ts` -> `tsx` (2 fences, `docs/about/contributing/frontend.md`).
Verified the actual content tokenizes identically under both grammars,
and a sibling block in the same file already needs `tsx` for real JSX,
so unifying to one tag is safe for this file. Documented a caveat: `tsx`
mis-tokenizes the legacy angle-bracket type-assertion syntax
(`<Type>value`), which is invalid in real `.tsx` files anyway, so use
`value as Type` instead.
- `yml` -> `yaml` (1 fence)
- Updated `docs/.style/style-guide/formatting.md` to document all
canonical tags

`promql` (2 fences) and `caddyfile` (2 fences) are left as-is. Shiki
doesn't bundle a grammar for either, so they need a custom grammar
registration when the site adopts Shiki, rather than degrading to `txt`.
Tracked as follow-up work under DOCS-118 and
[DOCS-544](https://linear.app/codercom/issue/DOCS-544/vendor-a-local-promql-grammar-for-shiki-syntax-highlighting)
(promql).

Does not touch `offlinedocs/`.

Linear:
[DOCS-476](https://linear.app/codercom/issue/DOCS-476/normalize-docs-code-fence-languages-de-risk-shikifumadocs)

<details>
<summary>How the fence tags were verified</summary>

Each tag was tested against a real `shiki@latest` highlighter instance
(`codeToHtml`/`codeToTokens`) and cross-checked against GitHub's
`@wooorm/starry-night` grammar sources (the renderer that actually
displays these `.md` files today, in repo browsing and PR diffs), since
that's what determines whether brevity is safe before Shiki adoption:

```text
FAIL  env        -- Language `env` is not included in this bundle.
FAIL  Dockerfile -- Language `Dockerfile` is not included in this bundle.
FAIL  promql     -- Language `promql` is not included in this bundle.
FAIL  caddyfile  -- Language `caddyfile` is not included in this bundle.
FAIL  pwsh       -- Language `pwsh` is not included in this bundle.
FAIL  output     -- Language `output` is not included in this bundle.
```

`hcl` doesn't error in Shiki, since it's a real grammar, but that's
exactly the trap: it was silently rendering every fence with the generic
HCL grammar instead of the Terraform-specific one. Every `hcl`-tagged
fence in `docs/**` was manually checked against `origin/main` and is
genuinely Terraform content.

For `ts`/`tsx`, tokenizing the actual doc content confirmed identical
output under both grammars; a synthetic test with the legacy
angle-bracket cast syntax confirmed `tsx` degrades on that specific
construct, which the style guide now calls out.

The first normalization pass only matched fence tags at column 0
(`^```tag$`), missing tags indented inside numbered/bulleted lists. A
follow-up pass caught the remaining occurrences at any indentation
level.

</details>


---

*This PR description and the underlying changes were prepared with Coder
Agents assistance.*
2026-07-15 14:07:09 -04:00