Commit Graph
81 Commits
Author SHA1 Message Date
Jakub Domeracki b4fb7901e6 docs: clarify that disable-password-auth also applies to owners (#30362)
The `--disable-password-auth` help text says owners can still sign in
with a password "to avoid potential lock out", and a comment in
`coderd/userauth.go` says the same. Neither is true. #6193 removed the
owner bypass on purpose, so the flag blocks password login for everyone.
The recovery advice was also wrong. It named a command that doesn't
exist (`create-admin`), and any admin that `create-admin-user` creates
while the flag is on still can't sign in.

This PR changes docs and comments only:
- Rewrites the flag description to say it applies to owners too and how
to recover access. Regenerated the CLI and config reference docs and the
golden files.
- Fixes the misleading comment in `coderd/userauth.go`.
- Adds the same warning and recovery steps to
`docs/admin/users/password-auth.md`.

> [!NOTE]
> Generated by Coder Agents on behalf of @jdomeracki-coder.
2026-10-07 19:03:46 +02:00
Ehab Younes fc01bee831 fix: keep new API keys within the caller's scopes and allow list (#30256)
A scoped key holding api_key:create could mint a broader key, e.g. a token scoped to [api_key:create user:read] could mint coder:all.

- New keys must be covered by the caller's scopes and allow list, and inherit them when none are requested
- Requests beyond the caller return 403
- New key expiry is capped at the caller's
- Covers POST /users/{user}/keys/tokens, POST /users/{user}/keys, app auth-redirect, and /oauth2/authorize (invalid_scope on excess grants or a restricted session allow list)
- coder:all sessions, including browser logins, behave as before
- Not addressed: workspace start still mints a coder:all key for the owner
2026-10-07 11:43:19 +03:00
Nick Vigilante 4a184ca54a feat: add generated API key scopes reference (DOCS-135) (#29307)
## Summary

Coder validates every requested API key scope against a curated public
catalog in `coderd/rbac`, but the docs never listed it. Readers had to
infer the requestable set from the `codersdk.APIKeyScope` enum, which is
a superset that includes internal scopes a token cannot carry.

This adds `scripts/scopesdocgen`, which renders
`docs/reference/api-key-scopes.md` from `rbac.ExternalScopeNames` and
the policy definitions behind it:

- built-in scopes (`coder:all`, `coder:application_connect`)
- composite `coder:*` scopes, each with the permissions it expands to
- low-level `resource:action` scopes, with the action descriptions the
policy declares
- the deprecated `all` / `application_connect` aliases and their
canonical spellings

The generator is wired into `make gen`, so CI fails when the scope
catalog and the page drift apart.

## Also in this change

- `coderd/apikey.go`: the unrequestable-scope `400` detail pointed at
`admin/users/sessions-tokens#api-key-scopes`, which only ever held a
partial list. It now points at the generated reference.
- `docs/admin/users/sessions-tokens.md`: the partial enumeration and the
"read the schema, but not all of it applies" caveat are replaced with a
link to the reference. The how-to content stays.

## Verification

- `go test ./scripts/scopesdocgen` covers the sentence formatting, the
scope partitioning, and a guard that every name in
`rbac.ExternalScopeNames()` appears on the rendered page.
- `go test ./coderd -run
'TestTokenScoped|TestCreateTokenScopes|TestExternalScopesAreStorable|TestTokenLegacySingularScopeCompat'`
passes, confirming the page's claims about the default scope and the
rejection of internal scopes.
- `make lint/emdash`, `make lint/docs-html`, `make lint/check-scopes`,
`pnpm run check-docs`, and Vale on the changed pages are clean. Full
`make pre-commit` passed.

<details>
<summary>Context and scope decisions</summary>

Part of the DOCS Automated reference documentation project, which tracks
generating reference pages from product source of truth instead of
maintaining them by hand. DOCS-135 is the first item: it was filed as
"wire up the existing generator," but `scripts/apikeyscopesgen` emits Go
(`codersdk/apikey_scopes_gen.go`), not documentation, so there was no
generator output to surface and this adds one.

Decisions made while implementing:

- **Placement.** `docs/reference/api-key-scopes.md`, as a direct child
of Reference rather than inside `docs/reference/api/`, because that
directory is owned by the swagger generator.
- **Page shape.** Follows the `scripts/docgenenv` convention for
generated reference pages: the generated marker and page metadata in
front matter, the generated-content banner in the body, and sections
starting at level two because the front-matter title renders as the page
heading.
- **Public scopes only.** The page lists what `rbac.IsExternalScope`
accepts. Internal `resource:action` pairs are deliberately excluded,
which is the distinction the old schema link failed to make.
- **Acronym handling.** Policy action descriptions are lowercase source
strings (`"ssh into a given workspace"`). The generator restores the
casing of a small set of leading acronyms rather than editing the RBAC
package, so the change stays inside the docs pipeline.

Sibling backlog items turned out to be already delivered and are being
rescoped separately: `metricsdocgen` and `auditdocgen` already write
into their docs pages, and `scripts/configdocgen` already generates the
configuration reference.

</details>

---

Generated with Coder Agents on behalf of @nickvigilante. Linear:
[DOCS-135](https://linear.app/codercom/issue/DOCS-135/wave-1-wire-up-api-key-scopes-reference-to-docs)


## Product UI impact, please read

This PR corrects three RBAC action description strings in
`coderd/rbac/policy/policy.go`:

| Action | Before | After |
|---|---|---|
| `workspace:start` | allows starting a workspace | start a workspace |
| `workspace:stop` | allows stopping a workspace | stop a workspace |
| `api_key:update` | update an api key, eg expires | update an api key,
for example its expiry |

These were internal-facing until this PR, which is what made them worth
fixing: the new reference page renders them verbatim to operators, and
"eg expires" is not decodable by a reader without codebase context.

**They are not docs-only.** `make gen` propagates them to
`coderd/rbac/object_gen.go` and
`site/src/api/rbacresourcesGenerated.ts`, and
`CreateEditRolePageView.tsx` renders the description next to each action
in the custom roles editor. So this changes admin UI copy, and
`CreateEditRolePageView.stories.tsx` means Pixel may now report a
genuine snapshot diff on that component rather than the pre-existing
failure noted below.

The new wording matches the convention the rest of the table already
follows (`ssh into a given workspace`, `create an AI Gateway key`), so
this makes the UI more internally consistent, not less. Flagging it
explicitly because a docs PR changing product copy deserves an owner's
eyes rather than a silent merge. Happy to split it out if RBAC or
frontend would rather own it, with the caveat that the reference page
would then publish `eg expires` in the meantime.

<details>
<summary>CI note: Storybook / Pixel failure</summary>

The `Storybook` check fails at its `Snapshot` step, and `Pixel / Review`
reports `build failed` with no snapshots processed.

**Updated:** this note originally said the branch touched no files under
`site/`. That is no longer true. Correcting the RBAC policy description
strings (CRF-24) required `make gen`, which regenerated
`site/src/api/rbacresourcesGenerated.ts` alongside
`coderd/rbac/object_gen.go`. That file is a generated string table with
no rendered component behind it, so it still cannot account for a
Storybook snapshot or Pixel build failure, but the original
justification no longer holds and is replaced by this one. The failure
predates that change: it was present when the branch genuinely had no
`site/` diff. Every other check passes.

</details>
2026-10-01 16:09:01 -04:00
Nick VigilanteandIan Evans c2d243891f docs: remove feature states from page titles (#30109)
## Summary

Remove feature-state suffixes from page titles and H1s, keeping
availability states in `docs/manifest.json` navigation metadata.

## Changes

- Remove Premium and Beta suffixes from eight page titles.
- Update the docs content guidelines and doc-check skill to require
state metadata instead of title suffixes.
- Preserve the existing `premium` and `beta` state values in
`docs/manifest.json`.

## Testing

- `pnpm check-docs` passed.
- Verified all eight affected manifest entries retain their feature
state and no affected title retains a state suffix.

Refs DOCS-1126.

This pull request was generated by Coder Agents.

---------

Co-authored-by: Ian Evans <5760366+ianjevans@users.noreply.github.com>
2026-09-29 20:13:02 -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
John T Skarbek 0733e8984c docs: use opencode auth login for OpenCode auth instead of editing auth.json (#30054)
OpenCode moved to an `opencode auth login` flow for storing provider
credentials rather than manually editing
`~/.local/share/opencode/auth.json`. Updates both the Centralized API
Key and BYOK sections of the OpenCode AI Gateway client docs to have
users run `opencode auth login`, select the provider, and paste the API
token/key they obtained in the earlier step.
2026-09-28 15:36:38 -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
Michael Suchacz 6826da9397 feat: restore agents-access as a default organization role (#30004)
Restores `agents-access` (**Coder Agents User**) as a built-in
organization role and adds it to every organization's
`default_org_member_roles`. Members keep Coder Agents by default, and
admins can now restrict it per organization by removing the role from
the defaults and granting it through IdP role sync or direct assignment.

Since #28186, chat permissions lived in the organization-member floor,
so the only way to limit Coder Agents was narrowing per-model access
lists, which did not hide the feature.

- Migration 000602 appends `agents-access` to every organization's
defaults, so upgrading keeps every member's access. New organizations
get it from `rbac.DefaultOrgMemberRoles()`.
- Service accounts do not inherit the role from the defaults
(`GetAuthorizationUserRoles`), so they still need an explicit grant for
chat.
- Owners and Organization Admins keep chat access regardless of
defaults. Chats shared with a user stay readable without the role.
- Role sync is unchanged. It does not store default roles, so after the
default is removed a mapped user gets `agents-access` at their next
sign-in.
- The retired-role mechanism (`IsRetiredRoleName`) is removed.
- `PATCH /api/v2/organizations/{organization}` rejects duplicate
`default_org_member_roles` entries (the CLI already de-duplicated them).
- Custom organization role requests treat built-in role names
case-insensitively, since custom role names are stored lowercase and
`Agents-Access` would otherwise become an undeletable shadow of the
built-in role.
- The Agents permission alert tells restricted members their chats are
kept, and the model selector for users without chat permission no longer
claims that no models are configured.

Docs add "Control who can use Coder Agents" to the Agents
getting-started guide.

**NOTE**: Migration 000602 deletes custom roles named `agents-access`,
which the built-in role would shadow. The down migration does not
restore them. Stored member grants of `agents-access` from the earlier
built-in role or a deleted custom role stay and now grant chat access.

## Validation

- Remote dogfood
[UAT](https://dogfood.cdr.dev/agents/e1c18dc6-f6f0-49a1-b6cd-6ce014b51a86)
passed on fb441dfae5, covering case variants of built-in role names on
create, update, delete, default roles, and member grants. The previous
round, on a6fef66b3f, passed the upgrade from main 5dde49dffb on a
fresh database. 6b7f107e0b only changes wording (docs, comments, UI
copy, CLI help) and did not go through UAT.
- Local: rbac, dbauthz, idpsync, migrations (chain including 000602 down
and up), querier, httpmw, provisionerdserver, coderd and enterprise
chat, role, and organization tests, chatd, toolsdk, CLI; frontend
vitest, story tests, biome, oxlint, tsc.

## Known issues (not changed here)

- Sending from a chat page that was already open when access was removed
shows a generic 404 panel until reload.
- The members page role editor is not locked for OIDC users under org
role sync; the API rejects the change with 400.
- Creating a custom role named after a system role
(`organization-member`, `organization-service-account`) returns 400 with
a raw database unique-constraint error.

<details>
<summary>Review record</summary>

- Remote UAT (UAT Critic sub-agent `6636c855ec`): round 1 on 8bec029d35
passed with issues, fixed in d7ba937a10 and e0f16e1a45f; round 2 on
a6fef66b3f passed; round 3 on fb441dfae5 passed.
- Codex: round 1 on a6fef66b3f found one P2 (case variants of built-in
role names), fixed in fb441dfae5 with a red-green test. Rounds 2 and 3
on fb441dfae5 found no major issues.
- mafredri on fb441dfae5 (PR text only): nine wording suggestions
applied in 6b7f107e0b9; NOTE extended for stored grants; description
trimmed.
- Frontend: FE1 to FE10 and coder-frontend-review checkpoints
self-audited.

</details>

> 🤖 This PR was opened by [Xum](https://mux.coder.com) on behalf of
@ibetitsmike.
2026-09-27 23:34:26 +02: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
陈志谦 442b08fee5 docs: drop duplicated 'the the' in scaletest flag help and OIDC docs (#29107)
Two doubled-word typos:

- `cli/exp_scaletest.go`: the `--connect-url` flag description shown by
`coder exp scaletest --help` read "inside **the the** workspace over
WireGuard"
- `docs/admin/users/oidc-auth/index.md`: "as **the the** username"

Docs/help text only.
2026-09-24 16:19:53 +00: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
Nick Vigilante 6dd2e95692 docs: describe organization roles and correct the roles permission claims (#29303)
## Summary

The roles reference documented deployment-wide roles only.
Organization-scoped roles were named in passing on three other pages but
defined nowhere, and two statements on the page contradicted the RBAC
code.

Closes
[DOCS-891](https://linear.app/codercom/issue/DOCS-891/organization-scoped-roles-are-defined-only-in-code-not-in-the-docs)

## Problem

`coderd/rbac/roles.go` and `coderd/rbac/rolestore/rolestore.go` define
eight organization-scoped roles. `docs/` defined none of them. Searching
`docs/` for `organization-auditor`, `organization-user-admin`,
`organization-service-account`, and
`organization-workspace-creation-ban` returns nothing, and
`organization-admin` appears only inside an IdP sync JSON example.

That produced three concrete defects:

- **Dead-end cross-reference.** The AI Gateway group budget prerequisite
named the Organization Admin and Organization User Admin roles and
linked to a page that defines neither.
- **Incorrect Member claim.** The page said all users hold an implicit
Member role "that may use personal workspaces." The site `member` role
grants no workspace permissions, and `OrgMemberPermissions` grants none
either. Workspace access comes from `organization-workspace-access`,
which organizations attach through their default member roles.
- **Unqualified Owner row.** The table asserts Owner can execute and use
all workspaces. `CODER_DISABLE_OWNER_WORKSPACE_ACCESS` removes SSH and
application access from the role, and the flag was documented only in
the generated CLI and configuration references.

## Fix

Adds an Organization roles section to the roles page covering the six
assignable organization roles, where to assign them, and the implicit
membership role the dashboard doesn't display. It also records that
Organization Admin excludes SSH, application, and terminal access to
other members' workspaces, which is the least discoverable part of the
model.

Corrects the Member and Owner statements, retargets the group budget
prerequisite at the new section, notes that the Disabled workspace
sharing policy overrides the sharing permission of any role an
organization member holds, and fixes the built-in roles and custom roles
glossary entries.

The deployment roles table is deliberately untouched.
[ENG-873](https://linear.app/codercom/issue/ENG-873/autogenerate-roles-documentation)
replaces it with a generated table, so correcting the Auditor row or
adding an organization matrix by hand now would be churn. The new
section is prose a generator won't emit, so the two changes compose.

<details>
<summary>Verification and scope notes</summary>

**Claims verified against source, not assumed:**

| Claim | Source |
|---|---|
| Six assignable organization roles and their display names |
`builtInRoles` in `coderd/rbac/roles.go` |
| Organization Admin lacks `ssh` and `application_connect` | `orgAdmin`
role, `slice.Omit(ResourceWorkspace.AvailableActions(), ...)` |
| Member role grants no workspace permissions | `memberRole.User`
excludes `ResourceWorkspace` with no add-back |
| Workspace access comes from the default member roles |
`DefaultOrgMemberRoles()` and `orgWorkspaceAccessMemberPerms()` |
| `organization-member` and `organization-service-account` have no
display name, so the dashboard never shows them | `systemRoles` in
`rolestore.go`, `DisplayName: ""` |
| Disabled sharing overrides other roles | org-level negative
`workspace:share` permission in `OrgMemberPermissions` |
| Roles are assigned on the organization Members page | `Edit roles`
action in `OrganizationMembersTable.tsx` |
| Flag, environment variable, and YAML names | `codersdk/deployment.go`
|

**Scoped out deliberately:**

- The Disabled-sharing note says "any role held by a member of that
organization" rather than naming Owner. The negation rides on the
organization membership role, so it doesn't reach an Owner who isn't a
member of that organization.
- Pre-existing gerund headings on the touched pages (`Creating custom
roles`, `Getting Started`, `Sharing your Workspace`, `Using a shared
workspace`, `Accessing workspace apps in shared workspaces`) are left
alone to keep the diff scoped. Vale reports them as warnings on `main`
today.
- `## Custom Roles` is retitled to sentence case. The GitHub anchor slug
is unchanged, so inbound links still resolve.

**Checks run:** `make fmt/markdown`, `make lint/markdown`, `make
lint/emdash`, and `vale` on the four changed files. Vale reports zero
findings from the new text. Every link added or changed was resolved to
its file and heading anchor.

**Also worth knowing:** three en dashes in the workspace sharing policy
list are replaced with colons. `scripts/check_emdash.sh` only scans
changed files, so they survived on `main` and would have failed this
PR's CI once the surrounding lines were touched.

</details>

---

Opened by Coder Agents on behalf of @nickvigilante.
2026-09-22 14:17:00 -04:00
Jake HowellandTyler 8a4f2f80fa refactor: implement standard IdP sync settings (#28935)
> 🤖 This PR was written by Coder Agents on behalf of Jake Howell.

Refactors the IdP sync settings pages to use the shared settings
patterns and make group and role mapping management clearer. It also
separates claim-value loading between the two tabs so each form
consistently reflects its configured sync field.

- reorganizes group and role sync controls into clearer settings
sections (standard components)
- preserves the group and role tabs while loading claim values
independently
- adds a typed confirmation dialog before deleting group mappings
- consolidates policy export and unseen-claim UI into shared components

| <img width="2880" height="1800" alt="idp-sync-group-settings"
src="https://github.com/user-attachments/assets/bc0cca7d-f56d-459b-a284-518a551386bb"
/> | <img width="2880" height="1800" alt="idp-sync-delete-dialog"
src="https://github.com/user-attachments/assets/702a8435-8f0c-4232-b515-1df4210f1500"
/> |
| --- | --- |

---------

Co-authored-by: Tyler <tyler.tate@coder.com>
2026-09-10 20:28:09 +10: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
Jake Howell 486d2faa81 refactor: modernize the create user page (#28894)
> 🤖 This PR was modified by Coder Agents on behalf of Jake Howell.

Redesigns the create user flow using the settings page layout and
renames it to "New user." The form includes clearer field guidance,
explicit authentication-method loading, error, and empty states, updated
documentation, and aligned end-to-end selectors.

| Old | New |
| --- | --- |
| <img width="2560" height="2516" alt="02-create-user"
src="https://github.com/user-attachments/assets/c79fb42b-3b0f-47fa-b03d-801c81584dba"/>
| <img width="2560" height="2748" alt="02-create-user-page"
src="https://github.com/user-attachments/assets/2d2dd777-3ae9-444d-9811-082f30eb8387"/>
|

Depends on #28893.

<details>
<summary>Stack</summary>

1. #28893 - Edit user page redesign
2. #28894 - Create user page redesign (this PR)

</details>
2026-09-09 00:35:42 +10:00
Jake Howell 3b1828db5b refactor: modernize the edit user page (#28893)
> 🤖 This PR was modified by Coder Agents on behalf of Jake Howell.

Redesigns the edit user page using the settings page layout, with
clearer field guidance, explicit loading and error states, documentation
and back links, and access to the shared user administration menu.

Successful updates refresh the page heading and query cache without
resetting an in-progress form during background refetches.

| Old | New |
| --- | --- |
| <img width="2560" height="1800" alt="03-edit-user-member"
src="https://github.com/user-attachments/assets/915434fe-9587-49e9-b962-cc1ebeca3ea4"
/> | <img width="2560" height="1800" alt="02-edit-user-page"
src="https://github.com/user-attachments/assets/2b188c26-4268-4498-96a0-4fd1825a6a49"
/> |
| `** didnt exist **` | <img width="2560" height="1800"
alt="03-edit-user-page-action-menu"
src="https://github.com/user-attachments/assets/1e657626-ab43-4d49-a375-414896728fb9"
/> |

<details>
<summary>Stack</summary>

1. #28893 - Edit user page redesign (this PR)
2. #28894 - Create user page redesign

</details>
2026-09-09 00:21:16 +10: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
Bobby HoandMcKayla はな c9fc5b7ea1 fix: canonicalize API key scope aliases at ingress (#28322)
`rbac.IsExternalScope` accepts `all` and `application_connect`, neither
of which is an `api_key_scope` enum member. The plural `Scopes` field
stored the name as given, so `{"scopes":["all"]}` passed validation and
then 500'd inside `apikey.Generate` with `invalid API key scope: "all"`.
Reachable from `coder tokens create --scope all`, from the spellings
`docs/admin/users/sessions-tokens.md` taught, and from the `codersdk`
constants exported for exactly this purpose.

- Canonicalize inside `apikey.Generate`, in the loop that already
validates each name. One statement covers every caller and all three
input paths: plural `Scopes`, deprecated singular `Scope`, and the
default. Replaces two open-coded switches and the handler's own
per-element copy, so one place decides the stored spelling and the
handler only decides what may be requested.
- Deduplicate in the same pass. An alias and its canonical spelling are
two names going in and one name in the column.
- `ExternalScopeNames()` lists every name `IsExternalScope` accepts,
instead of dropping catalog entries that fail to parse. A curated entry
that cannot be stored used to pass every test and 500 at runtime; it now
fails two.
- Split the 400. A misspelled name and an internal `api_key_scope`
member need different words, since no re-spelling makes the second
requestable. Both rejection sites share one helper that names the case
and links the docs.
- Add reject-path tests for `not_a_real_scope` and `debug_info:read`.
The second is a valid enum member the rbac catalog treats as internal,
so before this both handler guards could be deleted with the suite still
green. A further case pins that plural `Scopes` wins when a caller sets
both fields.
- `TestExternalScopesAreStorable` pins the class rather than the two
known instances: every public rbac scope name must be storable.
`coderd/rbac` cannot assert this itself, since `database` imports `rbac`
and not the reverse.
- Docs use the canonical spellings, link the `codersdk.APIKeyScope`
schema, and say which scopes a token cannot request.

Egress is unchanged: `convertAPIKey` still derives a legacy singular
name on the way out. `ExternalScopeNames()` returns the same 57 names as
before, and `codersdk/apikey_scopes_gen.go` regenerates identically.

`rbac.CanonicalScopeName` merged with #28167, so this applies to `main`
and reviews on its own. The OAuth2 provider ignores scopes entirely
today (`authorize.go:237`, `tokens.go:377`, `tokens.go:520`), so it is
unaffected until those TODOs resolve.

Deferred from review: PLAT-528, PLAT-529, PLAT-530, and PLAT-532.
PLAT-532 covers `{"scopes":[]}` and `{"allow_list":[]}` defaulting open,
which predates this PR.

---------

Co-authored-by: McKayla はな <mckayla@hey.com>
2026-08-25 17:12:51 -07:00
J. Scott Miller 76962273d8 feat: add coder organizations edit for default member roles (#28227)
`default_org_member_roles` was only settable through Terraform or a raw
`PATCH /api/v2/organizations/{organization}`. This adds a CLI
equivalent.

```console
coder organizations edit --org acme --default-org-member-roles organization-workspace-access,organization-template-admin
coder organizations edit --org acme --default-org-member-roles ""   # grant no roles
```

- The flag replaces the organization's current list rather than adding
to it. It accepts a comma-separated list, may be repeated, and
de-duplicates. An empty value removes every role.
- Removing a role prompts for confirmation, listing the roles being
removed, unless `-y` is passed. Adding roles applies without a prompt.
- The resulting set is printed, so no follow-up command is needed to
confirm what was applied.
- The organization is chosen with `-O/--org` or `$CODER_ORGANIZATION`,
and is implicit when the caller belongs to exactly one organization.

The org update endpoint is behind `FeatureMultipleOrganizations`, so the
command is enterprise/premium only. Non-built-in roles are rejected by
the server, and `dbauthz` already prevents a caller from setting a
default they could not assign to a member individually.

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

## Shape

`codersdk.UpdateOrganizationRequest.DefaultOrgMemberRoles *[]string` and
the enterprise `patchOrganization` handler already existed; only the CLI
was missing, and nothing in `cli/` called `UpdateOrganization` at all.
No server or SDK changes are needed.

`organizations edit` follows the partial-update pattern of `coder groups
edit`: check `ParsedFlags().Changed(...)`, populate only the fields the
user set, and leave the rest nil so the handler preserves them. Passing
no flags is an error.

Two earlier shapes were tried and dropped:

- **A `default-org-member-roles` entry in the `organizations settings`
registry.** Every sibling entry unmarshals an SDK type that maps 1:1 to
a dedicated endpoint; this field has no such endpoint. Reusing
`UpdateOrganizationRequest` for the piped JSON meant a stray `name`
field could rename the org, and the documented `show > file`, edit, `set
< file` workflow failed on the default organization, whose name is
reserved.
- **A `--default-org-member-roles` flag on `organizations create`.**
`create` cannot set display name, description, or icon either, so a
roles-only flag there is asymmetric. It would also require
`CreateOrganizationRequest` to grow the field plus server-side
validation.

## Known sharp edge

`serpent.StringArray` resets its slice when any flag value is empty, so
`--default-org-member-roles a --default-org-member-roles ""` clears the
list rather than keeping `a`. This is pinned by a test and called out in
a code comment. The confirmation prompt catches it interactively; a
script passing `-y` would not. A custom flag value that ignores empty
occurrences was prototyped and reverted as more machinery than the
behavior warranted.

## Validation

Manually verified against a local dev deployment with a premium license:
setting, adding, clearing, prompt accepted and declined, duplicate and
whitespace handling, invalid role rejection, and a plain member being
denied. Confirmed with `/authcheck` that a member loses workspace-create
access when the roles are cleared and regains it when restored, and that
the change is recorded in the audit log.

## Follow-ups worth considering

- `--name`, `--display-name`, `--description`, and `--icon` on
`organizations edit`; all already exist on `UpdateOrganizationRequest`.
Rename deserves its own discussion.
- Setting the defaults to `organization-admin` makes every member an org
admin, including the ability to edit the org further, and those users
still render as plain members in member listings. Reachable today via
the API, UI, and Terraform; a warning on privileged roles would help.
- `dbauthz.InsertOrganization` has no `canAssignRoles` check, unlike
`UpdateOrganization`. Harmless while the only caller passes the
deployment default constant.
- `docs/admin/users/organizations.md` still points users at the
dashboard or a raw `PATCH`.
</details>

---

Created by Coder Agents on behalf of @jscottmiller.
2026-08-24 09:41:21 -05:00
Wyatt FryandEthan Dickson a005e5cd22 feat: add username and email user search filters (#27922)
## Summary

User search can now resolve exact `email:` and `username:` terms through
`GET /api/v2/users` instead of only supporting fuzzy free-text matches.
The database query already had exact email and username filters; this
wires the public search parser and API handler to those filters so
clients can ask for a single user by email without fetching every user
or depending on substring matching.

This is the API half of coder/terraform-provider-coderd#403: that
provider PR adds `data.coderd_user.email`, and this PR gives it an
efficient exact lookup path.

## Testing

- `go test ./coderd/searchquery -run '^TestSearchUsers$' -count=1`
- `go test ./coderd -run '^TestGetUsersFilter$' -count=1`
- Live API test:
  - Built local enterprise Coder from this branch.
- Started Coder on `http://127.0.0.1:39991` against a clean Postgres
database.
  - Created `lookup-target@example.com`.
- Verified `GET /api/v2/users?q=email:LOOKUP-TARGET@EXAMPLE.COM&limit=2`
returned exactly one user:

```json
{
  "count": 1,
  "users": [
    {
      "id": "efc6f909-ce0a-4731-bd2f-6e4df417aaa7",
      "username": "lookup-target",
      "email": "lookup-target@example.com"
    }
  ]
}
```

---

![flow.ai](https://img.shields.io/badge/Built_with-flow.ai-6366f1)
![Codex](https://img.shields.io/badge/GPT--5-000000)

---------

Co-authored-by: Ethan Dickson <ethanndickson@gmail.com>
2026-08-16 18:18:02 +05:00
Nick Vigilante 58de9ab8f8 docs: correct broken CLI commands and flags from drift sweep (#28098)
## Summary

Corrects broken CLI commands and flags surfaced by the DOCS-637
full-corpus runtime drift sweep. Each fix was verified against the
generated CLI reference (`docs/reference/cli/*`) and, where relevant,
`codersdk` source.

## Changes

| Page | Fix |
|------|-----|
| `docs/user-guides/workspace-access/index.md` | `coder port forward` →
`coder port-forward` (the space form is unrecognized; the command is
hyphenated). |
| `docs/ai-coder/github-to-tasks.md` | Remove `coder templates list
--org your-org-name` in two spots — `templates list` has no `--org` flag
(`unknown flag: --org`). |
| `docs/admin/infrastructure/scale-utility.md` | `--cleanup-timeout
15min` → `15m` — Go durations reject the `min` unit (`invalid duration:
unknown unit "min"`). |
| `docs/admin/integrations/dx-data-cloud.md` | `coder users list >
users.csv` emitted a whitespace table, not CSV. Emit JSON and convert to
real CSV with `jq`, mirroring the API tab on the same page and using the
same columns as the default table view
(`username,email,created_at,status`). |

## Notes / judgment calls

- **dx-data-cloud (CSV):** the page genuinely needs CSV (the DX CSM
imports a CSV, and the API tab already produces one via `jq ... @csv`).
`coder users list` only supports `--output table|json`, so the CLI tab
now produces real CSV via `jq` rather than switching the page to JSON.
- **scale-utility `:109` left as-is:** `--target-users 0:100` is
prefixed with "For dashboard traffic:", which correctly scopes it to the
`scaletest dashboard` subcommand, so it is not drift.
- **Excluded — sessions-tokens `--lifetime=720h`:** the sweep flagged
this because the throwaway SUT capped token lifetime at 168h, but
`--max-token-lifetime` defaults to `876600h` (~100 years), so the
example is valid on a default deployment. The `CODER_MAX_TOKEN_LIFETIME`
dependency is also already documented in the page's "Set max token
length" section. No change needed.

Linear: https://linear.app/codercom/issue/DOCS-641

> This PR was created with AI assistance (Coder Agents).
2026-08-14 12:49:11 -04:00
Nick Vigilante 1d189cc204 docs: fix P2/P3 typos and syntax errors from drift sweep (#28101)
## Summary

High-confidence textual subset of the DOCS-637 **P2/P3** drift batch (31
findings total). These 8 fixes are pure typo / grammar / syntax
corrections verified directly against the doc source, so they carry no
risk of misreconstructed command output.

## Changes (6 files)

| Page | Fix |
|------|-----|
| `docs/admin/templates/extending-templates/variables.md` | Remove
doubled word: "file in in the template directory" → "file in the
template directory". |
| `docs/admin/networking/port-forwarding.md` | Grammar: heading "From an
coder_app resource" → "From a coder_app resource". |
| `docs/user-guides/workspace-access/index.md` | Malformed heading
"Through with the CLI" → "Through the CLI". |
| `docs/about/contributing/modules.md` | Conventional-commit example
missing the required space: `feat(git-clone):add` → `feat(git-clone):
add`. |
| `docs/ai-coder/tasks-migration.md` | Add missing closing double-quotes
on Terraform `source`/`version` in two snippets that would fail
`terraform` parsing. |
| `docs/admin/users/idp-sync.md` | Role Sync section said "group sync
settings" (copy-paste from the Group Sync section); remove an invalid
trailing comma from a JSON output example. |

## Deferred (remaining ~23 P2/P3 items, not in this PR)

The rest of the batch is stale **command-output** samples (column/schema
changes, sample values) and items that need a content decision (e.g.
`--psk` now deprecated in favor of `--key`; `--address` deprecated; an
undocumented retention flag). Those need live-output reconstruction or a
call on direction, so they're left for follow-up work, consistent with
the issue's "handle after the P0/P1 fixes land" guidance. One catalog
row (`reverse-proxy-nginx.md:57`, certbot `ws=apache`) is already
handled by #28086 and is excluded here.

Linear: https://linear.app/codercom/issue/DOCS-646

> This PR was created with AI assistance (Coder Agents).
2026-08-14 12:44:55 -04:00
Samuel Volin 50640063a2 feat: DEVEX-732 premium badging (#27847)
Premium badging and gating consistency

as a OSS user, I want to be upsold to premium, and tastefully

Summary

Standardize all base-Premium full-page gates and the two named inline
notices. Admins see an in-app “Learn about Premium” path; non-admins are
told to contact their deployment administrator.
* DEVEX-732
* updates for premium docs pages for consistency
* updates for premium badging and paywall components
* updates implemented uses of premium badge and premiumpaywall


| Before | After |
| --- | ----------- |
| <img width="1271" height="564" alt="Screenshot 2026-08-04 at 3 02
32 PM"
src="https://github.com/user-attachments/assets/027d4bca-3e34-40b2-ad69-28dbaa4a004b"
/> | <img width="1273" height="600" alt="Screenshot 2026-08-04 at 3 26
37 PM"
src="https://github.com/user-attachments/assets/321083c0-7a4c-4c7e-a19c-059807018d3b"
/> |

| Before | After |
| --- | ----------- |
| <img width="1084" height="672" alt="image"
src="https://github.com/user-attachments/assets/741e6bd9-93b0-4ae0-97df-027e8aba5716"
/> | <img width="1289" height="622" alt="Screenshot 2026-08-04 at 3 20
07 PM"
src="https://github.com/user-attachments/assets/b3a8c169-ca6e-439b-8752-9209131fc097"
/> |

| Before | After |
| --- | ----------- |
| <img width="1091" height="865" alt="image (1)"
src="https://github.com/user-attachments/assets/f7cd92dd-a975-4db0-bc2a-af092ba783ce"
/> | <img width="1268" height="680" alt="Screenshot 2026-08-04 at 3 37
06 PM"
src="https://github.com/user-attachments/assets/8af8081a-0ec9-4fd3-921c-470127f2328b"
/> |
2026-08-06 12:13:12 -06: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
ba4779fc87 docs: lead with env vars in admin docs and add configuration reference (#26824)
## What & why

Admin/setup docs lead with `coder server --flag` examples, but most
operators configure Coder through `CODER_*` environment variables
(system service, container, or Helm chart). There is no single page
mapping a setting to its env var, CLI flag, YAML key, and default, so
searching the docs for an env var name such as `CODER_PG_CONNECTION_URL`
returns nothing.

This adds a generated configuration reference and begins shifting admin
docs to lead with the environment-variable form.

## Changes

- **Generated configuration reference**
(`docs/admin/setup/configuration-reference.md`): a searchable,
per-setting list of every visible deployment option. Each option is a
heading (grouped and nested by serpent group) followed by its
description and the environment variable, CLI flag, YAML key, and
default that apply to it. Generated from `codersdk.DeploymentValues` so
it stays in sync.
- **Generator + `make gen` wiring** (`scripts/configdocgen/`): new
binary plus a Makefile target and `GEN_FILES` entry, mirroring the
existing `clidocgen` / `auditdocgen` pattern. Output is host-independent
(same env normalization as `clidocgen`).
- **Demo conversion** (`docs/admin/users/github-auth.md`): inverted to
lead with the `/etc/coder.d/coder.env` env-var form; the CLI-flag form
becomes a closing note that links to the reference. H2 slugs preserved.
- **Style guide** (`.claude/docs/DOCS_STYLE_GUIDE.md`): documents the
env-var-first convention for admin/setup docs.
- **Navigation**: manifest entry under Administration → Setup, plus a
TIP callout on the setup index.

## Risk

Docs + gen pipeline only; no runtime change. The page is regenerated by
`make gen`; the `gen` and `check-docs` CI checks pass.

## Follow-up

Several other admin pages still lead with flag walls. Recommend sweeping
them incrementally in separate PRs rather than expanding scope here.

<details>
<summary>Implementation notes (provenance, conflict resolution,
verification)</summary>

- Continues prior work by @aslilac and @bpmct from the
`kayla/docs-env-vars-first` branch. Both original commits are
cherry-picked here with authorship preserved.
- Rebased onto current `main`. Resolved two `Makefile` conflicts where
`main` had since added the `feature-stages.md` gen target at the same
locations; kept both targets (union) in `GEN_FILES`, `gen/mark-fresh`,
and the recipe block.
- The original branch's checked-in page predated recent
`codersdk.DeploymentValues` changes, so it was **regenerated** against
current `main` (adds `CODER_SCIM_USE_LEGACY`, the `Networking / Cluster`
section with `CODER_CLUSTER_HOST`, `CODER_BOUNDARY_LOG_RETENTION`, and
the AI Gateway description rename). The `gen` CI check enforces this
stays current.
- Fixed flag-link anchors for short-form flags (`--config`,
`--log-filter`): the generator derives the anchor from `FlagShorthand`
to match `clidocgen`'s heading (e.g. `#-l---log-filter`).
- `linkspector` ignores the AWS Bedrock base URL that appears as an
illustrative `<region>` placeholder in an option description, consistent
with the existing `openai.com` ignore patterns.

</details>

<details>
<summary>Configuration reference layout (2026-07-08 update)</summary>

Reworked the reference from a wide table into a nested, per-setting list
so it fits without horizontal scrolling and stops repeating the group
name in every heading:

- **List, not table.** Each option renders as a heading, its
description, and a bullet list of only the configuration methods that
apply to it (non-applicable methods are omitted instead of shown as
`-`).
- **Nested sections.** Sections nest by the serpent group hierarchy, so
`Email / Email Authentication` becomes `Email` (h2) with an `Email
authentication` (h3) subsection instead of a redundant flat title.
- **Shorter, sentence-case headings.** The redundant group prefix is
stripped from each option name and the remainder is lowercased to
sentence case, preserving acronyms and mixed-case tokens (`URL`, `TLS`,
`OAuth2`, `GitHub`) plus a small proper-noun allowlist (`Coder`,
`Terraform`, `Honeycomb`, `Anthropic`, `Bedrock`, ...). Example: `AI
Gateway Send Actor Headers` becomes `Send actor headers`.
- **Deprecated options** sort to the end of each section and lead with
an emphasized **Deprecated** marker. Headings stay clean (no
`(deprecated)` suffix) so their anchors remain stable.
- **Section intros** render from a group's `Description` when the source
defines one (e.g. DERP); no hand-maintained prose or links are
introduced.

All transformations run in pure Go at `make gen` time (no AI at
generation time). Generation is idempotent, and `markdownlint` and
`golangci-lint` both pass.

</details>

---

🤖 Opened by Coder Agents on behalf of @nickvigilante. Continues work by
@aslilac and @bpmct.

---------

Co-authored-by: Kayla (via Coder Agents) <kayla@coder.com>
Co-authored-by: Coder Agents <noreply@coder.com>
Co-authored-by: Ben Potter <me@bpmct.net>
2026-08-03 14:33:01 -04: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
Andrew Aquino 09a69e624a feat: search users by display name (#27398)
Free-text member search previously matched only username and email, so
typing a person's display name returned no results even though the UI
shows the display name as the primary label. This broadens the free-text
`@search` filter to also match `users.name`.

The change is in three queries: `GetUsers`,
`PaginatedOrganizationMembers`, and `GetGroupMembersByGroupIDPaginated`.
This covers every server-filtered surface: the Users page, the
Organization Members page, the Group Members page, and the
`UserAutocomplete` / `WorkspaceUserAutocomplete` pickers (which query
`GetUsers` with `q`). The org member picker (`MemberAutocomplete`)
filters client-side via cmdk, so display name is added to its
`keywords`.

Explicit filters (`name:`, `username`/`email`) and pagination counts are
unchanged; the group members count still comes from the filtered
`COUNT(*) OVER()` in the same query.

Refs DEVEX-484
Refs DEVEX-565

<details>
<summary>Implementation plan</summary>

## Problem

Member search (both the global Users page and the Organization Members
page) matches only on `username` and `email`. It does not match on the
user's display name (`users.name`), even though the Organization Members
table shows `name` as the primary title. So typing a person's full name
in the search box returns nothing.

Today a bare search term (`alice`) is routed to the SQL `@search`
filter, which only checks `email`/`username`. Display name is only
matched if the user explicitly types `name:alice`, which is
undiscoverable.

## Design decision

Include `name` in the free-text `@search` condition in the affected SQL
queries. A bare term then matches `email OR username OR name`, using the
same case-insensitive substring `ILIKE` already in place. This keeps the
existing explicit `name:` filter working.

Tradeoff: this broadens the meaning of free-text `search` globally
(anything using these queries now also matches display name). This is
the intended behavior, confirmed against DEVEX-565 (display name search
in the user picker).

## Affected files

Backend:
- `coderd/database/queries/users.sql` (`GetUsers`)
- `coderd/database/queries/organizationmembers.sql`
(`PaginatedOrganizationMembers`)
- `coderd/database/queries/groupmembers.sql`
(`GetGroupMembersByGroupIDPaginated`)
- `coderd/database/queries.sql.go` regenerated via `make gen`

Frontend:
- `site/src/components/UserAutocomplete/UserAutocomplete.tsx` (add
`name` to client-side cmdk keywords)

Tests:
- `coderd/coderdtest/users.go` (shared `UsersFilter` helper): added a
`DisplayNameSearch` case and extended search-based expectations to
include `name`. Exercised by `TestGetUsersFilter`,
`TestGetOrgMembersFilter`, and `TestGetGroupMembersFilter`.

Docs:
- `docs/admin/users/index.md`: documented that free-text search matches
username, email, and display name.

## Frontend surface coverage

| Surface | Sends | Backend | Query |
|---|---|---|---|
| Users page | `q` | `GET /users` | `GetUsers` |
| Organization Members page | `q` | paginated members |
`PaginatedOrganizationMembers` |
| Group Members page | `q` | `groupMembers` |
`GetGroupMembersByGroupIDPaginated` |
| User pickers (server-filtered) | `q` | `GET /users` | `GetUsers` |
| Org member picker (client-filtered) | local cmdk | n/a | keyword
change |

## Out of scope

- Trigram/similarity (fuzzy) matching; keeps `ILIKE` substring
semantics.
- Sort/pagination ordering (still `LOWER(username)`).

</details>

---
_Created by Coder Agents on behalf of @aqandrew._
2026-07-28 12:13:58 -07:00
Steven MasleyandNick Vigilante 92d45a0411 docs: document SCIM 2.0 handler opt-in and legacy flag (#27469)
Documents the SCIM 2.0 handler introduced in #25572 and how to opt in.

Adds a "SCIM 2.0 handler" subsection to the SCIM section of
`docs/admin/users/oidc-auth/index.md`:

- The handler follows RFC 7644 and supports user
provisioning/deprovisioning and user listing.
- Opt in with `CODER_SCIM_USE_LEGACY=false` (also `--scim-use-legacy` /
`scimUseLegacy`); requires a server restart.
- Behavior notes: delete/deactivate suspends (never hard-deletes),
reactivation goes through dormant, usernames are immutable.
- Notes it will eventually become the default behavior.

Behavior details were verified against
`enterprise/coderd/scimroutes.go`, `enterprise/coderd/scim/`, and the
`SCIM Use Legacy` option in `codersdk/deployment.go`.

`make lint/markdown` and `make lint/emdash` pass.

---

Generated by Coder Agents on behalf of @Emyrk.

---------

Co-authored-by: Nick Vigilante <nickvigilante@users.noreply.github.com>
2026-07-27 08:20:27 -05:00
Nick Vigilante f5e0c1a860 fix: correct invalid inline HTML in hand-written docs (#27298)
## What

Fixes three classes of invalid inline HTML in hand-written docs, all of
which
render incorrectly (or only render by accident) today. Found via a
systematic,
markdown-aware audit of every `.md` under `docs/` (ignores code blocks,
inline
code, comments, and autolinks), so this is a complete sweep of the
hand-written
surface, not a spot fix.

## Changes

1. **`<kdb>` → `<kbd>` (72 tags).** The keyboard element is `<kbd>`;
`<kdb>` is
a typo that is not a real element, so renderers drop/mangle it and the
   keystrokes lose their styling. Corrected across the IDE access guides
(`cursor.md`, `windsurf.md`, `antigravity.md`). The correct `<kbd>` is
   already used in the JetBrains Gateway guide.
2. **Unclosed `<div class="tabs">` in `docs/admin/users/idp-sync.md`.**
The
"Provider-Specific Guides" section opened a `.tabs` container (rendered
as
the `DocsTabs` component) that was never closed, so the wrapper leaked
over
the rest of the page. Added the missing `</div>` before `## Next Steps`,
   matching the three other tab sections in the same file.
3. **`<Image>` → `<img>` (6 tags).** `<Image>` is not a registered docs
component — it renders only because the HTML5 parser rewrites the legacy
`<image>` tag to `<img>`. Converted to lowercase `<img>` for correctness
and
   clarity; rendering is unchanged. (`organizations.md`, `idp-sync.md`,
   `add-envbuilder.md`.)

## Scope / what is intentionally not here

- **Generated reference docs.** The audit also found swallowed
placeholders in
  generated pages (`<server>` in `reference/api/{chats,schemas}.md`;
`<glob>`/`<host>` in `agent-firewall`; `<region>` in `server`). Those
are
fixed at the generator source (codersdk comments / CLI flag help) and
tracked
  in DOCS-551.
- **`<b>Resource<b>`** in the generated audit-logs table was fixed
separately in
  #27293 (merged) and is not duplicated here.
- **`<children></children>`** is an intentional, renderer-implemented
docs
component (child-page card grid) with no HTML equivalent, so it is left
as-is.
It is well-formed; a follow-up CI checker will still verify its
open/close
  balance.

A follow-up adds CI enforcement so invalid inline HTML can't regress.

<details>
<summary>Verification</summary>

Run against the changed files:

- `markdownlint-cli2` — 0 errors
- `markdown-table-formatter --check` — no changes needed
- `typos --config .github/workflows/typos.toml` — clean
- Re-running the audit scanner: hand-written `unclosed`, `<kdb>`, and
  capitalized-component findings all drop to 0 (only the generated-doc
  placeholders tracked in DOCS-551 remain).

</details>

## Linear

DOCS-581:
https://linear.app/codercom/issue/DOCS-581/audit-and-fix-all-invalid-html-across-the-docs

> This PR was created with AI assistance (Coder Agents).
2026-07-21 19:59:59 +00:00
Atif Ali 2b2a5c963a Revert "fix(coderd): explain default GitHub app org visibility on login rejection" (#27388) 2026-07-21 16:17:27 +00:00
Atif Ali 48e9bb3391 fix(coderd): explain default GitHub app org visibility on login rejection (#27374)
## Problem

On a fresh deployment with no custom GitHub OAuth app, Coder falls back
to the default Coder-managed GitHub app. That app can only see
organization memberships in organizations where it has been installed.
If `CODER_OAUTH2_GITHUB_ALLOWED_ORGS` is set but the app isn't installed
in the allowed organizations, the membership list comes back empty and
every login, including the first admin login, is rejected with a bare
"You aren't a member of the authorized Github organizations!" with no
hint about the actual cause. This leaves fresh deployments in an
apparently broken state.

## Fix

* Append a remediation hint to the login rejection when the default
provider is configured, pointing at the [app installation
page](<https://github.com/apps/coder/installations/select_target>) and
at configuring a custom GitHub OAuth app.
* Log a startup warning when the default provider is combined with
`CODER_OAUTH2_GITHUB_ALLOWED_ORGS`, listing the allowed orgs and the
install URL.
* Document the installation requirement next to the
`CODER_OAUTH2_GITHUB_ALLOWED_ORGS` step in the GitHub auth docs.

Access-control behavior is unchanged; the org check still rejects logins
as before, it just explains why and how to fix it.

## Testing

* New `TestUserOAuth2Github/NotInAllowedOrganizationDefaultProvider`
asserts the hint appears when `DefaultProviderConfigured` is set; the
existing `NotInAllowedOrganization` subtest asserts it does not leak
into the custom-app path.

Fixes coder/coder#17752
2026-07-21 20:43:10 +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
Nick Vigilante 199b5936c1 fix(docs): replace invalid </br> tags and format swallowed placeholder URL (#27174)
## Summary

Fixes two classes of invalid/broken HTML in hand-written docs. Both are
visible problems in today's rendered docs, independent of any
docs-engine work.

1. **`</br>` is not a real HTML tag.** `br` is a void element with no
closing form; browsers error-correct `</br>`, but it is invalid HTML.
Replaced all 15 usages with `<br />` across:
   - `docs/admin/templates/extending-templates/dynamic-parameters.md`
   - `docs/admin/users/idp-sync.md`
   - `docs/tutorials/best-practices/organizations.md`
2. **Browser-swallowed placeholder URL.** In
`docs/ai-coder/github-to-tasks.md`,
`https://<your-coder-url>/settings/external-auth` was unformatted, so
HTML renderers parse `<your-coder-url>` as an unknown tag and drop it.
The live docs currently render the broken text `re-authenticate at
https:///settings/external-auth`. Wrapped in backticks, matching every
other instance in the same file.

Table realignment noise in the diff is from `fmt/markdown` (`<br />` is
one character wider than `</br>`).

A repo-wide grep confirms no remaining `</br>` and no other unformatted
`https://<placeholder>` URLs in prose (other hits are inside code fences
or already backticked). The equivalent placeholder issues in
**generated** reference docs (CLI help strings, swagger annotations) are
intentionally out of scope and tracked separately in
[DOCS-551](https://linear.app/codercom/issue/DOCS-551/backtick-placeholder-syntax-in-generated-reference-docs-cli-help).

Tracking issue:
[DOCS-550](https://linear.app/codercom/issue/DOCS-550/fix-invalid-br-tags-and-browser-swallowed-placeholder-url-in-hand)

---

Created by Coder Agents on behalf of @nickvigilante.
2026-07-13 10:41:38 -04:00
Ben Potter 6c3bf80892 docs(docs/admin/users/oidc-auth): note SCIM 2.0 support is not guaranteed (#25008)
Adds an `[!IMPORTANT]` callout under the SCIM heading in the OIDC auth
docs noting that Coder's SCIM 2.0 implementation is not a fully
certified or guaranteed implementation of the spec. It covers common
provisioning/deprovisioning flows with major IdPs (Okta, Entra ID, etc.)
but specific attributes, endpoints, or behaviors may not be supported
and may change between releases.

This matches what we say in conversations with prospects and avoids
setting an expectation we can't always meet. Background: #15830 (current
implementation is an MVP scoped to Okta cloud; `PATCH` is not RFC 7644
compliant; user updates only change status, not groups/orgs/roles).

Companion PR: coder/coder.com#738 removes the SCIM row from the pricing
comparison.

> Generated with [Coder Agents](https://coder.com/agents)
2026-05-07 12:25:28 -05:00
Kayla はな c5f1a2fccf feat: make service accounts a Premium feature (#24020) 2026-04-07 12:25:32 -06:00
Asher 81188b9ac9 feat: add filtering by service account (#23468)
You can now filter by/out service accounts using
`service_account:true/false` or using the filter dropdown.
2026-03-24 10:13:25 -08:00
Kayla はな 4c9e37b659 feat: add page for editing users (#23328) 2026-03-23 12:42:50 -06:00
Kacper Sawicki 1e274063d4 feat(coderd): filter expired API tokens server-side (#22263)
## Summary

Moves expired token filtering from client-side to server-side by adding
an `include_expired` parameter to the `GetAPIKeysByLoginType` and
`GetAPIKeysByUserID` database queries. This is more efficient for large
deployments with many expired/short-lived tokens.

## Changes

- Add `include_expired` parameter to SQL queries using `OR`
short-circuit
- Add `include_expired` query parameter to `GET
/users/{user}/keys/tokens`
- Add `IncludeExpired` field to `codersdk.TokensFilter`
- Remove client-side filtering from CLI `tokens list` command
- Add `TestTokensFilterExpired` test

Fixes coder/internal#1357
2026-02-24 15:27:03 +00:00
Cian JohnstonandClaude Opus 4.5 4a3304fc38 feat(cli)!: expire tokens by default (#21783)
## Summary

> NOTE: Calling this out as a breaking change in case existing consumers
of the CLI depend on being able to see expired tokens OR being able to
delete tokens immediately.

Updates the `coder tokens rm` command to immediately expire a token by
ID, preserving the token record for audit trail purposes. Tokens can
still be deleted by passing `--delete`.

## Problem

During an incident on dev.coder.com, operators needed to urgently expire
an API key that was stuck in a hot loop. The only way to do this was via
direct database access:

```sql
UPDATE api_keys SET expires_at = NOW() WHERE id = '...';
```

This is not ideal for operators who may not have direct DB access or
want to avoid manual SQL.

## Solution

This PR adds:

- **API endpoint**: `PUT /api/v2/users/{user}/keys/{keyid}/expire` -
Sets the token's `expires_at` to now
- **SDK method**: `ExpireAPIKey(ctx, userID, keyID)` 
- **Updates CLI**: `coder tokens rm <name|id|token>` now _expires_ by
default. You can still delete by passing the `--delete` flag. The `coder
tokens list` command now also hides expired tokens by default. You can
`--include-expired` if needed to include them.
- **Audit logging**: The expire action is logged with old and new key
states

## Test plan

- Tests cover: owner expiring own token, admin expiring other user's
token, non-admin cannot expire other's token, 404 for non-existent token

Closes #21782

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

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-17 13:16:46 +00:00
Kacper Sawicki d09300eadf feat(cli): add 'coder login token' command to print session token (#21627)
Adds a new subcommand to print the current session token for use in
scripts and automation, similar to `gh auth token`.

## Usage

```bash
CODER_SESSION_TOKEN=$(coder login token)
```

Fixes #21515
2026-01-29 16:06:17 +01:00
Rowan Smith a6581c7157 chore: update OIDC scopes to include offline_access (#20876)
This is an update to
https://coder.com/docs/admin/users/oidc-auth/microsoft#enable-refresh-tokens-recommended.
We recommend users enable refresh tokens but don't actually give them
the env var value to add.

https://coder.com/docs/admin/users/oidc-auth/refresh-tokens does a good
job of including `offline_access` in the list, so the first page should
align with this.
2025-11-24 07:04:21 +05:00
Phorcys 0cd33d1abb chore(docs/admin/users): fix typo in headless auth page (#20841) 2025-11-20 11:25:54 +01:00
Steven Masley a2728439ff docs: add API key scopes documentation (#20742)
## Description

Adds a brief section to the API & Session Tokens documentation
explaining API key scopes.

## Changes

- Added "API Key Scopes" section to
`docs/admin/users/sessions-tokens.md`
- Includes overview of scope functionality and security benefits
- Documents scope format (`resource:action`) and wildcard usage
- Provides CLI examples for creating scoped tokens
- Lists common scope examples with descriptions

## Motivation

Users need documentation on how to create and use scoped API tokens for
improved security by limiting token permissions to only necessary
operations.

## Testing

- Reviewed documentation formatting
- Verified markdown structure
- Confirmed examples are accurate
2025-11-17 11:34:01 -06:00
1d1e1f92b0 docs: add OIDC documentation for Microsoft Entra ID user auth (#20202)
Propose Microsoft Entra ID OIDC Directions for Admin Documentation based
on my personal experience / setup.

Propose information on changing access URL in Tutorials -> FAQs

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: DevCats <chris@dualriver.com>
Co-authored-by: DevelopmentCats <christofer@coder.com>
2025-11-07 16:33:51 +05:00
DevCatsandAtif Ali ea7025b562 docs(admin/users): add google provider-specific guide (#19309)
## Summary
- Add a provider-specific guide for configuring Google as an OIDC
provider
- Document refresh token setup via CODER_OIDC_AUTH_URL_PARAMS
- Add page to docs navigation under Users → OIDC Authentication

## Test plan
- Docs site builds: `docs/admin/users/oidc-auth/google.md` renders
- Nav shows 'Google' under OIDC Authentication
- Links to OIDC overview and refresh tokens work

Fixes #13508

---------

Co-authored-by: Atif Ali <atif@coder.com>
2025-08-12 13:02:40 -05:00
Jakub Domeracki d05a15cb12 fix: adjust the kubectl exec example (#19148)
Current example fails since kubectl version 1.31:
```sh
$ kubectl exec -it deployment/coder /bin/bash -n coder
error: exec [POD] [COMMAND] is not supported anymore. Use exec [POD] -- [COMMAND] instead
```

The legacy syntax was removed in:
https://github.com/kubernetes/kubernetes/pull/125437
2025-08-04 21:24:09 +02:00
Edward AngertandEdwardAngert 998fbdfbb3 docs: use CODER_LOG_FILTER instead of CODER_VERBOSE (#19105)
closes #18833

replace suggestions to use the now-deprecated `CODER_VERBOSE` with more
specific `CODER_LOG_FILTER`

thanks @UnicornyRainbow!

---------

Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
2025-07-30 12:35:45 -04:00
Edward AngertandEdwardAngert 072c81cd73 docs: remove nested alerts (#18580)
hotfix

removes nested gfm alerts, which is a known ~issue~ feature
https://github.com/orgs/community/discussions/16925#discussioncomment-12043928

Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
2025-06-25 15:17:49 +00:00