mirror of
https://github.com/coder/coder.git
synced 2026-11-22 03:18:31 +08:00
feea5ab959f59cd2135443ed2a0c19bf7643db8f
11
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
d1a58b9f5d |
feat: add script to check for title case (#21484)
Historically, much of the UI used title case. This PR adds a lint check
that reports title case UI text so it can be converted to sentence case,
and converts the existing text.
- `site/scripts/check-sentence-case.mjs` runs as `pnpm
lint:sentence-case` and is part of `pnpm lint`. It reads JSX text and
string/template literals from the TypeScript AST and skips literals that
are code rather than UI text (imports, types, property names, tagged
templates, values of JSX attributes that are not displayed such as
`className` or `style`, and operands of `===`/`case` comparisons). JSX
text across inline elements and conditional JSX is checked as one
phrase. `--fix` lowercases the reported words. The checker is a
heuristic: it is not meant to model every code shape, so use a
`sentence-case-expect` comment where it guesses wrong.
- Proper nouns (Coder products, role names, third-party products,
protocols, font names) live in `PROPER_NOUNS`. For other deliberate
exceptions, a `sentence-case-expect` comment on the line above
suppresses the report and fails when that line no longer needs it.
- Existing UI text is converted to sentence case, and tests that assert
on it are updated.
- Deployment option lookups (`useDeploymentOptions`) now use CLI flags
instead of display names, so they do not depend on UI wording.
## Performance
`pnpm lint:sentence-case` takes **1.6 s** and is 2% to 4.5% of `pnpm
lint`. Measured on
|
||
|
|
ed9e9a84ec |
docs: add sandbox agents guide and startup time tips (#32280)
Adds a "Sandbox agents" guide under Extending templates, and adds startup time tips from the [Improving Coder Workspace Startup Times](https://www.youtube.com/watch?v=-xcVJQWVCxs) livestream to the speed-up templates guide. **Sandbox agents** (`docs/templates/extending-templates/sandbox-agents.md`) is organized around three traits: kernel, network, and secrets isolation, plus fast startup. Each trait has a short methods table with tradeoffs, plus examples and references. - Starts with the coder-labs registry templates (agent-sandbox, Plain Sandbox, OpenShell) that implement all three, and calls out [agent-sandbox](https://agent-sandbox.sigs.k8s.io/). - Explains what the sandbox covers for CLI Agents, Coder Agents, and Agent Relay. - Shows how to define sandbox profiles as immutable parameters with one preset each, and how to control which profile an agent gets. - Kernel: gVisor, Kata, and EKS Nitro Sandboxes (`isolated-sandbox` RuntimeClass in EKS Auto Mode). - Network: separate proxy Pod vs. sidecar, example rules using an internal GitHub and artifact store, and a cloud firewall layer (AWS Network Firewall, Route 53 Resolver DNS Firewall) that also limits DNS. - Secrets: `api_key_scope = "no_user_data"`, a scoped AI Gateway token (skipped for prebuilds, optional `lifetime`), per-workspace EKS Pod Identity, and just-in-time credentials from Vault. **Speed up templates** (`docs/workspaces/speed-up-templates.md`) gets new sections for pre-warming Kubernetes nodes (with GKE, EKS, and AKS alternatives), building tools into the image, prebuilt workspaces (including one preset for each configuration), and skipping the Kubernetes rollout wait (with coder-logstream-kube to surface Pods that can't start). It links the [fast-workspaces-lab](https://github.com/coder-contrib/fast-workspaces-lab) repo for the sample base image, node schedule, and prebuild templates. **Agent Firewall** gets a notice on its index page and in the glossary that it is being phased out, pointing to the sandbox guide. The sandbox guide doesn't mention Agent Firewall. Two diagrams in the speed-up templates guide come from the talk's slide deck, cropped to the diagram. Notes for reviewers: - The scoped AI Gateway token (`user:read_personal`) isn't tied to a workspace, so with several organizations, AI Gateway uses the user's effective group for budgets. The page doesn't mention this. - The Nitro (coder/registry#1253) and Cilium (coder/registry#1254) registry templates are still open, so they aren't linked yet. <details> <summary>Decisions and checks</summary> - **Structure:** three traits, several ways to get each, and simple tradeoffs. - **Sysbox** is not listed as kernel isolation, because system calls still reach the node's kernel. - **Deployments** stay the recommendation over bare Pods, because `wait_for_rollout` and coder-logstream-kube cover the startup and error cases. - **Token lifetime** is left commented out in the example: Coder can't revoke the token at stop, and a lifetime shorter than autostop breaks running workspaces. - **Process logging** wording: the eBPF sidecar runs inside the sandbox with gVisor, Kata, or Nitro, so the page asks readers to test it. - **"CLI Agents"** is kept as the term for agents that run fully in the workspace. - **Verified in code:** - `mutable = false` is enforced on later builds (`coderd/dynamicparameters/resolver.go`). - Presets match by subset, also without a `preset_id` (`coderd/database/queries/prebuilds.sql`, `coderd/workspaces.go`). - `no_user_data` blocks the Git SSH key and external auth (`coderd/gitsshkey_test.go`, `coderd/externalauth_test.go`). - Token creation is rejected for the prebuilds system user (`coderd/apikey.go`), and the default token lifetime is 7 days (`codersdk/deployment.go`). - No Coder code sets `CODER_SESSION_TOKEN` in a workspace; registry modules such as `coder-login` do. - **Checks run:** `make lint/emdash`, `make lint/docs-html`, `make lint/docs-manifest`, markdownlint, markdown-table-formatter, Vale (0 errors), and the pre-commit hook. </details> 🤖 This PR was generated by Coder Agents on behalf of @bpmct. |
||
|
|
0be6e7a034 | feat: add a setting for web terminal font size (#32027) | ||
|
|
1baff57cb0 |
fix: resolve docs and code conflicts found in the main docs audit (#32158)
## Summary Addresses 106 of the 113 conflicts between the docs and the code that the November audit of `main` found: 102 are fixed and 4 have an interim docs fix. Every finding was re-checked against the code before it was fixed. Most fixes are docs-only. Three are small code fixes where the docs described the intended behavior and the code was wrong, each in its own commits so it can be split out. No change in this PR alters template build or agent behavior. ## Changes Fixes by area (finding counts): templates 28, install 13, integrations and monitoring 13, auth and security 12, networking 11, Coder Agents 9, AI governance 7, reference 7, workspaces 6. Code fixes. Each needs a look from the code owner. If an owner prefers not to take one, drop its commits and I will change the docs to describe the current behavior instead. | Commits | Change | Risk to check | |---------|--------|---------------| | `fix: keep built-in listener defaults in packaged coder.env`, and three follow-up commits | `coder.env` comments out `CODER_HTTP_ADDRESS=` and the three `CODER_TLS_*` lines, so an untouched package install listens on `127.0.0.1:3000` as the docs say. Only the `CODER_HTTP_ADDRESS=` line changed behavior. The TLS options default to empty, so commenting them out is for consistency. The Lima examples rewrite the commented line and fail if the line is not found. A test compares every option that the file sets against the built-in defaults. | The deb and RPM packages were not built or installed. Every released package through v2.39.0 ships the empty line, and upgrades keep an existing file (`config\|noreplace`), so the upgrade pages now say how to fix it. | | `fix(cli/clilog): accept log sinks that are all disabled`, and three follow-up commits | `--log-human=/dev/null` with no other log location no longer fails with "no loggers provided". It is the documented way to disable logging. An empty location still fails with that error when no other sink is set, as before. | Behavior change: with `/dev/null`, the server and the provisioner daemon can start with no log output. | | `fix(cli): detect CODER_PROC_PRIO_MGMT by presence`, and a comment follow-up | Log line only. With the variable set to an empty value, the agent now logs that process priority management is enabled, which is what `agentexec` already does. No detection or behavior change. | Low. | Two option descriptions in `codersdk/deployment.go` are corrected, with the CLI reference, configuration reference, and golden files regenerated: the default quiet hours schedule (the max deadline is the quiet hours window on the next day that the template's autostop requirement applies) and `--experiments` (`*` opts in to the experiments marked safe, also in `enterprise/cli/provisionerdaemonstart.go`). ### Code fixes that were reverted after review Two code fixes from the first version of this PR are reverted in the branch. The net diff has no change under `agent/` or `coderd/`. The docs now describe what the code does, and both issues stay open for the owner. - **`error` merge strategy for `coder_env` (DOCS-1669).** The fix made `merge_strategy = "error"` fail whenever a name was set twice, whatever the resource order. Existing template versions that pair an `error` entry with a later `replace` or `append` entry would start to fail every build after `terraform apply`. That is a breaking change that needs its own PR and release note. The fix and its tests are in `dff8e7c6ce` and can be cherry-picked. `environment-variables.md` now says the check runs only when the `error` resource is processed. - **Nice value before the capability drop (DOCS-1687).** The fix let `coder agent-exec` apply a negative nice value by calling `setpriority` before it drops effective capabilities. The current order is deliberate: with the fix, any local process could run the agent binary with `--coder-nice=-20` when the binary has the `CAP_SYS_NICE` file capability. `process-priority.md` now says a nice value below the agent's own is not applied, and no longer tells admins to grant `CAP_SYS_NICE`. ## Not included Seven findings are left out. - DOCS-1629: covered by #31639. - DOCS-1703 and DOCS-1724: covered by #31980. - DOCS-1584, DOCS-1683, DOCS-1685, DOCS-1686: each needs an owner decision, and no neutral docs wording exists until that decision is made. The validation comment on each issue names the decision. Four fixes are interim, so their issues stay open: - DOCS-1600: the AI Gateway pages now agree that the legacy metric names are deprecated and "will be removed in a future release". The code still emits them, and its TODO names v2.37, which has shipped. The owner still needs to set the removal release. - DOCS-1689: the page now says **New Template** opens the builder only for users with the Owner role, because the page gates on read access to the deployment config. Whether Template Admins should get the builder is still open. - DOCS-1669 and DOCS-1687: docs-only for now. Refer to [Code fixes that were reverted after review](#code-fixes-that-were-reverted-after-review). ## Review notes - Claims that describe product intent and need an owner's yes: the Premium qualifier on per-organization workspace sharing (the API route has no license check, the dashboard needs multiple organizations), `organization` port sharing in OSS, the telemetry field list, and the `1-5` cron range in the prebuilds schedule example. - Not run end to end: the PostgreSQL TLS procedure on a cluster, the OpenShift and air-gapped examples, the BSD `date` and `tar` forms on macOS, the Windows command on the multiple Kubernetes clusters page, and the keep-alive script in `docs/reference/index.md` (only its comparison logic was run, against sample values). Nothing was checked on a live deployment. - Likely merge conflicts with open PRs: #31990 (`mcp-server.md`, `feature-stages.md`, `docker-in-workspaces.md`), #31982 (`workspace-management.md`), #31980 (`health-check.md`), #31977 (`manage-provisioner-jobs.md`), #31869 (`airgap.md`), #30486 (`add-envbuilder.md`), and #31326 and #31531 (`codersdk/deployment.go` and generated files). ## Testing - `make pre-commit` (gen, fmt, lint, slim build), before the PR opened and again after the review changes. - `go test` for `./cli/clilog/...`, `./codersdk/`, `./cli/` (`TestServer`, `TestAgent`, and golden files), and `./enterprise/cli/` (provisioner, server, and help golden files). `./agent/agentexec/...` and `./coderd/provisionerdserver/...` pass after the reverts. Linux only. CI covers macOS and Windows. - The `coder.env` test fails against the file on `main` and passes against the new one. It reads the file with `godotenv`, which accepts CRLF line endings. - An empty `CODER_HTTP_ADDRESS=` was confirmed end to end with a full build of the server (output below). - The new `sed` and `grep` lines in the Lima examples were run with GNU tools against the old and the new form of `coder.env`. The Lima VMs were not started. - `--log-human=/dev/null` and `CODER_LOGGING_HUMAN=` were confirmed with the same build (output below). - `coder agent-exec --coder-nice=-5 -- echo` from a full build, as a non-root user: `coder-agent: failed to adjust niceness to -5 ...: permission denied` on stderr, the command output on stdout, exit code 0. - `postgres-ssl.md` rendered with the GitHub Markdown API: two ordered lists with three and five items, where `main` has six lists. - markdownlint, the table formatter, `make lint/emdash`, `make lint/docs-html`, `make lint/docs-manifest`, `make lint/docs-redirects`, `make lint/style-claims`, and Vale on the changed lines. - A doc-check self-review of the docs diff by four independent reviewers. It found six problems, which are fixed. The accuracy and coverage lenses ran on every area. The language and structure lenses ran in full on only part of the diff. <details> <summary>Test and terminal output for the code fixes (Linux)</summary> ```console $ go test ./codersdk/ -run TestPackagedCoderEnvKeepsDefaults -count=1 -v --- PASS: TestPackagedCoderEnvKeepsDefaults (0.00s) ok github.com/coder/coder/v2/codersdk 0.071s $ go test ./cli/clilog/ -run TestBuilder -count=1 -v --- PASS: TestBuilder (0.00s) --- PASS: TestBuilder/NoSinks (0.00s) --- PASS: TestBuilder/NoSinks/JSONDevNull (0.00s) --- PASS: TestBuilder/NoSinks/StackdriverDevNull (0.00s) --- PASS: TestBuilder/NoSinks/NoConfiguration (0.00s) --- PASS: TestBuilder/NoSinks/HumanDevNull (0.00s) --- PASS: TestBuilder/WithHuman (0.00s) --- PASS: TestBuilder/WithFilter (0.00s) --- PASS: TestBuilder/WithJSON (0.00s) --- PASS: TestBuilder/Verbose (0.00s) --- PASS: TestBuilder/FromDeploymentValues (0.01s) --- PASS: TestBuilder/FromDeploymentValues/Defaults (0.00s) --- PASS: TestBuilder/FromDeploymentValues/EmptyHumanEnv (0.00s) --- PASS: TestBuilder/FromDeploymentValues/Override (0.00s) ok github.com/coder/coder/v2/cli/clilog 0.171s $ TMPDIR=$HOME/.cache/agentexec-tmp go test ./agent/agentexec/... ./coderd/provisionerdserver/... -count=1 ok github.com/coder/coder/v2/agent/agentexec 4.236s ok github.com/coder/coder/v2/coderd/provisionerdserver 2.404s # Full build of the server (go build ./cmd/coder). An empty value stops it before it connects to the database. $ CODER_HTTP_ADDRESS= coder server --postgres-url 'postgres://127.0.0.1:1/x?sslmode=disable' Encountered an error running "coder server", see "coder server --help" for more information error: TLS is disabled. Enable with --tls-enable or specify a HTTP address # With the variable unset, the server passes that check and goes on to the database. $ coder server --postgres-url 'postgres://127.0.0.1:1/x?sslmode=disable' 2026-11-13 02:19:41.901 [warn] ping postgres: retrying error="dial tcp 127.0.0.1:1: connect: connection refused" try=11 Encountered an error running "coder server", see "coder server --help" for more information error: connect to postgres: connect to postgres: unable to connect after 11 tries; last error: dial tcp 127.0.0.1:1: connect: connection refused # An empty log location with no other sink still stops the server. $ CODER_LOGGING_HUMAN= coder server --postgres-url 'postgres://127.0.0.1:1/x?sslmode=disable' Encountered an error running "coder server", see "coder server --help" for more information error: make logger: no loggers provided, use /dev/null to disable logging # /dev/null passes the logger check. The server prints no log lines and goes on to the database. $ coder server --log-human=/dev/null --postgres-url 'postgres://127.0.0.1:1/x?sslmode=disable' Encountered an error running "coder server", see "coder server --help" for more information error: connect to postgres: connect to postgres: unable to connect after 11 tries; last error: dial tcp 127.0.0.1:1: connect: connection refused ``` </details> ## Linear Fixes DOCS-1583, DOCS-1585, DOCS-1586, DOCS-1587, DOCS-1588, DOCS-1589, DOCS-1590, DOCS-1591, DOCS-1592, DOCS-1593, DOCS-1594, DOCS-1595, DOCS-1596, DOCS-1597, DOCS-1598, DOCS-1599, DOCS-1601, DOCS-1602, DOCS-1603, DOCS-1604, DOCS-1605, DOCS-1606, DOCS-1607, DOCS-1608, DOCS-1609, DOCS-1614, DOCS-1618, DOCS-1619, DOCS-1620, DOCS-1624, DOCS-1635, DOCS-1639, DOCS-1644, DOCS-1651, DOCS-1652, DOCS-1653, DOCS-1654, DOCS-1655, DOCS-1656, DOCS-1657, DOCS-1658, DOCS-1659, DOCS-1660, DOCS-1661, DOCS-1662, DOCS-1663, DOCS-1664, DOCS-1665, DOCS-1666, DOCS-1667, DOCS-1668, DOCS-1670, DOCS-1671, DOCS-1672, DOCS-1673, DOCS-1674, DOCS-1675, DOCS-1676, DOCS-1677, DOCS-1678, DOCS-1679, DOCS-1680, DOCS-1681, DOCS-1682, DOCS-1684, DOCS-1688, DOCS-1690, DOCS-1691, DOCS-1692, DOCS-1693, DOCS-1694, DOCS-1695, DOCS-1696, DOCS-1697, DOCS-1698, DOCS-1699, DOCS-1700, DOCS-1701, DOCS-1702, DOCS-1704, DOCS-1705, DOCS-1706, DOCS-1707, DOCS-1708, DOCS-1709, DOCS-1710, DOCS-1711, DOCS-1712, DOCS-1713, DOCS-1714, DOCS-1715, DOCS-1716, DOCS-1717, DOCS-1718, DOCS-1719, DOCS-1720, DOCS-1721, DOCS-1722, DOCS-1723, DOCS-1725, DOCS-1726, DOCS-1727 Part of DOCS-1600, DOCS-1689, DOCS-1669, DOCS-1687 <details> <summary>Decision log</summary> ### Scope - One PR for all findings, as agreed with the reviewer. The code fixes are separate commits so an owner can ask for any of them to move to its own PR. Nothing in the PR is a breaking change, so the title has no `!`. - A finding was skipped only when an open PR already covers it, or when every available wording would assert an undecided product behavior. - Each validation comment on the Linear issues records the evidence, the corrections to the original finding, and what was not verified. ### Docs or code - The default was a docs-only fix that describes what the code does. - A code fix was chosen when the docs describe a behavior the code plainly intended and the code change is small and testable: the packaged env file, the log sink check, and the log line for the environment variable presence check. - The `error` merge strategy and the nice value ordering started as code fixes and went back to docs-only after review. The first breaks existing template versions. The second weakens a deliberate security ordering. - The SCIM `userName` finding (DOCS-1609) took the docs path. The handler is unchanged. ### Wording choices worth a second look - `feature-stages.md` says `--experiments=*` enables only the experiments marked safe, and points to the "Get safe experiments" API. It does not list the other experiments, because the list would drift and those experiments are hidden on purpose. The `--experiments` flag help now says the same. - `agent-metadata.md` replaces the writes-per-second formula with a description of the batcher (each server replica writes one statement every 5 seconds, or sooner at 500 entries). - `extending-templates/index.md` no longer calls `startup_script` deprecated. The provider documents it as an alias for a `coder_script`. - `postgres-ssl.md` separates client verification from server verification, so the server verification steps work alone. - `rpm.md`, `upgrade.md`, and the 2.29 to 2.34 ESR upgrade page explain the empty `CODER_HTTP_ADDRESS=` line that older packages shipped, because upgrades keep the old file. The behavior changed in v2.34.0 with the serpent upgrade in #24926. - The keep-alive script in `docs/reference/index.md` reads the current deadline and skips the request when it is already later. The comparison is on text, so it applies only when the API returns a UTC timestamp, which needs the database to use the UTC time zone. Otherwise the script sets the deadline on every pass, as it did before, and the page says so. - `external-auth.md` anchors the new GitHub Enterprise regex example. The older unanchored examples on that page and on `git-providers.md` are not changed here. ### Self-review findings that were rejected - "The builder opens for Template Admins": the Templates page needs a successful deployment config read, which the Template Admin role does not have. - "Organization Admins can set AI model prices": the price write authorizes against a site-level object, which organization-scoped grants do not match. - "The provisioner chart sets no default resources": `helm/libcoder/templates/_coder.yaml` applies 2000m and 4096Mi when `coder.resources` is empty. ### Automated review, round 1 The `coder-agents-review` app left 45 findings on `8853332`. Fixed: the two reverts above, the anchored regex, the `coder.env` follow-ups (Lima examples, upgrade notes, a comment in the file, and a test that covers every option in the file), the clilog change, the two option descriptions, and the docs findings (CORS behavior, token lifetime example, keep-alive script, agent metadata, refresh token errors, `switch` form type, `dbcrypt` skip list, and a stray line in a YAML example). Declined, with the reason on each thread: - Refactoring the `agentexec` logging and renaming its log field: not related to a docs conflict. - Rewording the "process priority management not enabled (linux-only)" log message: the docs quote the message, and the wording predates this PR. - Problems in code and docs that this PR does not change (the `Capabilities` subtest, the Helm values comment, the AWS provider path in `airgap.md`, and others in the review's out-of-scope list). ### Automated review, round 2 The app left 14 new findings on `04925bd`, and accepted the three declined threads on `cli/agent.go`. All 14 are fixed. The main one: the round 1 change that removed the "no loggers provided" error went too far, because an empty log location would then start a server with no logs. The error is back for every case except `/dev/null`. Reported by the app as out of scope and not changed: the swagger annotation for `GET /api/v2/experiments/available` declares an array, but the handler returns an object with a `safe` array. Three Storybook fixtures keep the old `--experiments` description. ### Automated review, round 3 The app confirmed that all round 2 findings are fixed, and left 10 small findings on `f55cb6d` (8 P4, 2 Nit). All are fixed: the TLS condition and the release range in the `coder.env` notes, one place for the `/dev/null` rule in `clilog`, two test cases, a clearer test failure, and the CPU example in `agent-metadata.md`. ### Automated review, rounds 4 and 5 Round 4 left one P4 on `8fffb38` (name the `--trace` option in the logging note), which is fixed. Round 5 on `2ce754e` reports no new findings and says every earlier finding is fixed or closed. The app did not post an approval: it leaves its out-of-scope items and the code fixes to a human reviewer. Two threads on `cli/agent.go` stay open on purpose for the code owner. ### Doc-check review The doc-check workflow left 12 comments on `2ce754e` (10 blocking, 2 suggestions). All are fixed in `c888885`: "refer to" or "visit" in place of "see" for cross-references on the lines this PR added, the **New template** label as the dashboard shows it, one instruction per step in the server verification procedure of `postgres-ssl.md`, and two wording changes in `process-priority.md`. The `CAP_SYS_NICE` sentence keeps a short reason, which differs from the suggested text. The `coder-agents-review` app then reviewed that commit (rounds 6 and 7). Round 6 left two P4 findings, fixed in `30b2c79`: the `failed to adjust niceness` message is described once, in the troubleshooting entry, with where it appears, and the client verification steps in `postgres-ssl.md` render as one numbered list. Round 7 reports no new findings. `2a6035c` then softens one sentence from that fix, because the agent logs the stderr of devcontainer CLI commands. The app was not run again on that commit. ### Adjacent gaps found and not fixed here - `add-envbuilder.md` has the same `zip` command that `template-from-scratch.md` had. - `template-from-scratch.md` leaves the reader in `build/` after `cd $_`, before a step that runs from `template-tour`. </details> --- _Generated by Coder Agents on behalf of @nickvigilante._ --------- Co-authored-by: Ben Potter <me@bpmct.net> |
||
|
|
b798061108 |
perf: reuse import-time lock file and cache terraform version (#29825)
Workspace builds now reuse the lock file that `terraform init` wrote during template import, which takes a minimal Docker build from about 3.1s to 1.65s, measured from build created to agent connected. --------- Co-authored-by: Jon Ayers <jon@coder.com> |
||
|
|
155861f04e |
docs: replace ensure, should, and since per the Vale spike review (#31879)
Applies the Vale findings spike review's `ensure`, `should`, and `since` decisions, following `word-choice.md#choose-words-that-have-one-meaning`. ## `ensure`, `ensures`, `ensuring`: every row marked valid - 148 lines in 70 files. - Most became `make sure`, `makes sure`, or `making sure`. - When the subject isn't a person, I used a verb that reads better, such as `guarantees`, `keeps`, `prevents`, `maintains`, or `provides`. - `admin/monitoring/health-check.md:227`: "Make sure that" is now "Make sure", so the step stays within `Coder.StepLength`. - Left as-is: `admin/setup/configuration-reference.md:1339`, which is generated from `codersdk`. ## `should` and `since`: only rows with a verdict or a note - `.style/README.md`: "what should be routed elsewhere" is now "what to route elsewhere". - `.style/content-guidelines.md`: - "Avoid mixing those modes within a single page." - "Every page must be accurate" - "Check docs claims against the actual implementation" - "must include the documentation" - "Support owns the content they produce." - "because they don't change" - `.style/styles/Coder/README.md`: "must link to the matching section". - `admin/external-auth.md`: - "The redirect URI for Gitea is ..." - "Use custom authentication and token URLs ...", which is now active voice. - `envbuilder-releases-known-issues.md`: "so it's experimental and prone to breaking changes". Rows marked unsure with no note were left alone: `content-guidelines.md` lines 49, 330, and 405, and `envbuilder/index.md:24`. The changed files have no new findings from other rules. --- AI-generated by Superblink on behalf of @nickvigilante. --------- Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com> |
||
|
|
5e711930f7 |
docs: add Claude Code subscription sign-in guide for workspaces (#31805)
Adds a how-to page for using a Claude subscription with Claude Code inside a Coder workspace, rather than an Anthropic API key. Until now the docs covered API keys, other providers, and AI Gateway, but not this path. New page: `docs/workspaces/workspace-access/claude-code-subscription.md` (added to the sidebar under Workspace access, after Claude Desktop). - **Interactive sign-in:** `claude auth login` (or `/login`), open the printed URL locally, paste the code back. A fallback section covers forwarding the `localhost` callback port with `coder port-forward` or `ssh -L` when a local browser gets redirected to the workspace. - **Long-lived token:** `claude setup-token`, stored as a Coder user secret injected as `CLAUDE_CODE_OAUTH_TOKEN`. Also covers the Claude Code module's `claude_code_oauth_token` input for template admins, and notes that a template-level token is shared by every user of that template. - **Troubleshooting:** `ANTHROPIC_API_KEY` takes precedence over the subscription. Confirm with `claude auth status --text` or `/status`, then `unset` the key. Also lists where Coder can set the key (user secret, dotfiles, template). Notes that `ANTHROPIC_AUTH_TOKEN` (AI Gateway) also takes precedence. - **Cross-links** from `templates/extending-templates/modules.md` (AI agent modules), `ai-governance/ai-gateway/clients/claude-code.md` (BYOK Claude subscription), and `workspaces/workspace-access/claude-desktop.md` (next steps). Claude Code behavior (precedence, `setup-token`, plan requirements) links to Anthropic's docs instead of restating plan details. **These steps were not tested with a real Claude subscription.** I ran Claude Code 2.1.318 in a Linux workspace without completing a sign-in. I captured the `claude auth login` prompt and the redirect targets of both the printed and the browser-opened URLs. I also captured `claude auth status` output with dummy `CLAUDE_CODE_OAUTH_TOKEN` and `ANTHROPIC_API_KEY` values to confirm precedence. <details> <summary>Decision log</summary> - **Paste-code flow first, port forwarding as fallback.** The URL that `claude auth login` prints redirects to `https://platform.claude.com/oauth/code/callback`, which shows a code to paste, so SSH users don't need to forward a port. Only the URL handed to `$BROWSER` redirects to `http://localhost:<random-port>/callback`. The ticket described port forwarding as the main path. - **Page location.** No Claude Code page exists under Workspaces. Claude Code in workspaces is only mentioned in `modules.md` and the AI Gateway client page. The page sits next to Claude Desktop, and those pages link to it. - **User secret over template input for the token.** A subscription token belongs to one person. A user secret is per user and overrides `coder_env` with the same name. The template input is still documented for admins, with the sharing caveat. </details> ### Verified against - `coder/registry`: `registry/coder/modules/claude-code/main.tf` and `README.md` (main, v5.5.2). `claude_code_oauth_token` is sensitive and sets `CLAUDE_CODE_OAUTH_TOKEN`. It exists in v5.2.0, which matches the docs' `~> 5.2` pin. Plan-time validation rejects it together with `enable_ai_gateway` or `api_key_helper`. - `cli/portforward.go` and `docs/workspaces/workspace-access/port-forwarding.md`: `--tcp` syntax and the `ssh -L` section anchor. - `cli/secret.go`, `docs/workspaces/user-secrets.md`, `site/src/pages/UserSettingsPage/SecretsPage/SecretDialog.tsx` and `SecretsPageView.tsx`: Account > Secrets, **Add secret**, the **Name**, **Value**, and **Environment variable** field labels, **Save**, and user-secret precedence over `coder_env`. - Anthropic's Claude Code docs: `authentication` (log in, credential storage, authentication precedence, generate a long-lived token) and `cli-reference` (`claude auth login`, `claude auth status`, `claude setup-token`). - Local runs of Claude Code 2.1.318 as described above. ### Open questions for the reviewer - Nobody has completed either flow with a real Pro or Max account. Someone with a subscription should check the paste-code flow end to end, and that `claude auth status` then shows `"authMethod": "claude.ai"` (the value comes from Anthropic's CLI reference). - The port-forward fallback says to reload the failed `localhost` callback page after starting `coder port-forward`. I haven't confirmed that the reload completes the sign-in instead of needing a fresh `claude auth login`. - The acceptance criteria ask for a link back from the registry module page. That README lives in `coder/registry` and needs a separate PR there. - Should the template example have a callout about whether sharing one subscription token across users is acceptable? The page currently only states the consequence. Generated by Coder Agents. Closes DOCS-510 Co-authored-by: Coder Prototypes <294797144+coder-prototypes@users.noreply.github.com> |
||
|
|
d91aa1bebd |
docs: replace may with can or might per the Vale spike review (#31878)
Replaces `may` with `can` (ability or permission) or `might` (possibility), following `word-choice.md#choose-words-that-have-one-meaning`. The Vale findings spike review marked every `may` row valid. - 247 lines in 110 files: 75 became `can` and 162 became `might`. The rest are small rewordings, such as "may wish" becoming "might want". - Applied the reviewer notes: - `.style/content-guidelines.md`: "docs may be written ahead" is now "you can write docs ahead", which also drops the passive voice. - `admin/external-auth.md`: now "You can grant access to a subset of repositories.", so the sentence doesn't end on a preposition. - Also fixed a typo in `gcp-to-aws.md`: "may needed" is now "might need". ## Left as-is - **`admin/setup/configuration-reference.md` (7 lines):** this page is generated from `codersdk` deployment options (`<!-- DO NOT EDIT | GENERATED CONTENT -->`), so the fix belongs in the Go option descriptions, followed by `make gen`. - **Text that quotes the product:** - `admin/monitoring/health-check.md:196` matches the derphealth message. - The heading at `templates/troubleshooting.md:45`, the first "may" on line 47, and the link on line 67 match the web terminal's "your workspace may be incomplete" warning and its anchor. - `admin/integrations/oauth2-provider/troubleshooting.md:269` quotes a server error. The changed files have no new findings from other rules. --- AI-generated by Superblink on behalf of @nickvigilante. --------- Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com> |
||
|
|
ae6b1faea3 |
fix: make SSH connection hints consistent across CLI, dashboard and docs (#31188)
SSH hints across the CLI, dashboard and docs used different, sometimes broken, workspace names. This makes them consistent with minimal, non-breaking changes and no new syntax: - Plain `ssh` hostnames: `<agent>.<workspace>.<owner>.<suffix>` (or `<workspace>.<suffix>` for single-agent workspaces). Works with `config-ssh` (with or without `--no-wildcard`) and Coder Connect. - `coder` CLI arguments: `[<owner>/]<workspace>[.<agent>]`, with the owner unless the workspace was given by its bare name. Built on #31192, which is now merged into `main`. ## Changes - **`coder ping` multi-agent error**: now suggests `coder ping <workspace>.<agent>` instead of listing agents without a runnable command. Owner-qualified and UUID inputs retain `<owner>/<workspace>`. JSON-mode errors leave stdout empty, and ping still does not autostart stopped workspaces. - **`coder ssh` multi-agent error**: when run directly (no `--ssh-host-prefix`/`--hostname-suffix`), it suggested `ssh coder.dogfood.matifali`, which never resolves without a matching SSH config entry or Coder Connect. For an agent named `dev`, it now suggests `coder ssh dogfood.dev`, or `coder ssh bob/dogfood.dev` if the workspace was given as `owner/name` or by ID. Here `.dev` selects the agent; it is not an SSH hostname suffix. The ProxyCommand path used by `config-ssh` and the IDE plugins still suggests the full hostname. - **`coder show` / `coder create`**: the access column dropped the owner, so `coder show bob/dogfood` or `coder show <id>` suggested `coder ssh dogfood.dev`. It now keeps the owner unless the workspace was given by its bare name. - **`coder config-ssh`**: the example `ssh <workspace>.coder` is ambiguous for multi-agent workspaces. It now names an agent, `ssh <agent>.<workspace>.<owner>.coder`, reading a stopped workspace’s known agents from its latest successful start using the same template version. With `--no-wildcard`, the hint reuses the workspace snapshot and resources used to write the Host entries. - **Dashboard "Connect via SSH"**: rendered `...<owner>.undefined` when the deployment has no hostname suffix. It now falls back to `coder ssh <owner>/<workspace>` for single-agent workspaces, or `coder ssh <owner>/<workspace>.<agent>` otherwise. With a hostname suffix, owned single-agent workspaces show `ssh <workspace>.<suffix>` unless that hostname collides with the deployment’s legacy prefix block. Prefix collisions, shared workspaces and multi-agent workspaces retain the full agent/workspace/owner hostname. The count includes agents across all resources and devcontainers. Commands remain undefined while the SSH config loads, with a spinner instead of a premature fallback. If the initial load fails, it displays the error while keeping the CLI command available. - **Docs**: workspace access docs said `config-ssh` prints `ssh coder.<workspace>`; it prints `ssh <workspace>.coder`. Added the multi-agent hostname, noted it in the Desktop docs, and updated the Gateway host and the networking page to `<workspace>.coder`. ## Before / after ```console $ coder ssh dogfood error: multiple agents found, please specify the agent name, available agents: [coder dev] Try running: $ ssh dev.dogfood.matifali # before: does not resolve $ coder ssh dogfood.dev # after: dev is the agent name ``` ## Compatibility Hostname parsing (`findWorkspaceAndAgentByHostname`, `normalizeWorkspaceInput`) is unchanged, so every hostname that resolves today still does. The VS Code, JetBrains Gateway and Toolbox plugins write their own `Host` entries and run `coder ssh --stdio --ssh-host-prefix <prefix>`, so they don't reach the changed hints. `TestSSH_AgentHostnames` connects with their `<prefix>--<owner>--<workspace>.<agent>` form, and with the `<agent>.<workspace>.<owner>` forms used by `config-ssh` and the dashboard. ## Verification CLI/resource race tests pass, including the complete original `TestSSH` suite and the new agent-hostname round trips. `TestConfigSSH_Example` checks running two-agent and stopped one-/two-agent workspaces whose import defaults differ, with and without `--no-wildcard`. It verifies the hint has a matching generated Host entry and reuses workspace history once per stopped workspace. `TestShow` covers bare names, owner-qualified names and UUIDs; `TestCreate/CreateForOtherUser` checks the owner-qualified preview. Mutation checks confirmed the new assertions fail when the protected behavior is removed. `TestPing_AgentSuggestions` covers bare names, owner-qualified names, UUIDs and JSON-mode errors with a shared fixture. The tests fail without the new hints; an owner-omission control also fails the qualified/UUID cases. The original network-heavy `TestPing` suite remains unchanged and passes its normal race run. Normal and strict new-code Go lint, frontend checks/lint/typechecking, all eleven SSHButton stories, and docs checks pass. Browser checks verified copied SSH/CLI commands and keyboard dismissal; screenshots were visually inspected. The single-agent follow-up adds 25 command-copy cases covering ownership, agents across resources, subagents, and zero/unknown counts. All 53 affected SSHButton, AgentRow, and AgentDevcontainerCard stories pass, with browser validation of both real callers and regression/mutation controls for the command-selection guards. <details> <summary>CI follow-up and validation commands</summary> After #31192 merged, the parent commits were dropped and the remaining eleven commits were rebased onto the merge commit `fb6d287528`. Range-diff and full-tree comparisons confirm no implementation changes. Revalidated the complete SSH/ping/config race suite and strict lint after that rebase. Latest rebase preserves the implementation and carries the docs edits to main’s renamed `docs/workspaces/` paths. The SSHButton documentation links and preview URL use the new routes. Revalidated the full SSH/ping/config CLI race suite, strict lint, 25 frontend tests, 53 stories, and docs/manifest/redirect checks. The local shell’s Oh My Zsh update prompt interrupted the first race run; the unchanged suite passed with `DISABLE_AUTO_UPDATE=true` scoped to the test process. Latest review follow-up: connection commands remain undefined during initial loading, and each instruction is gated on its own command. A cached SSH suffix remains usable after a failed refetch; a story captures that state. Rebased directly onto `main` at `fb6d287528` after #31192 merged. The P2 follow-up preserves native hostnames that collide with legacy prefix blocks, uses workspace-specific history for stopped agents, and retains safe precreated devcontainer names. Earlier stress runs of the unmodified `TestSSH` suite exceeded the 6,144 MiB guard under 35-repeat stress. Its existing scenarios remain unchanged. The three added agent-qualified hostname cases have independent full SSH round-trip coverage in `TestSSH_AgentHostnames`, with a shared fixture. The current top-PR changed-test selector chooses seven tests without the unrelated `TestSSH` scenarios, and the complete selected set passes 35 repetitions at parallelism 16 with the same memory guard. No test cases, repetitions, parallelism or memory checks were removed. ```sh go test -race -tags=testsmallbatch ./cli ./cli/cliui -run '^TestSSH$|^TestSSH_AgentHostnames$|TestPing|TestConfigSSH|TestShow|TestCreate|Test_agentSSHSuggestion|Test_suggestWithOwner|TestWorkspaceResources|Test_noWildcardHostNames|Test_previousStartResources|TestCommandHelp' -count=1 -parallel=4 GOMEMLIMIT=6GiB golangci-lint run --allow-serial-runners --concurrency=4 --new-from-rev=origin/main ./cli/... GOMEMLIMIT=6GiB make lint/go/new-code GO_LINT_CONCURRENCY=4 CODER_TEST_MEMORY_LIMIT_MIB=6144 TS_DEBUG_DISCO=true TS_DEBUG_DERP=true go test -tags=testsmallbatch -p=4 -count=35 -parallel=16 -shuffle=1 -timeout=10m -run '^(TestConfigSSH_Example|TestCreate|TestPing_AgentSuggestions|TestSSH_AgentHostnames|TestShow|Test_agentSSHSuggestion|Test_suggestWithOwner)(/.*)?$' ./cli cd site pnpm check pnpm lint pnpm test src/modules/resources/SSHButton/SSHButton.test.tsx pnpm test:storybook src/modules/resources/SSHButton/SSHButton.stories.tsx src/modules/resources/AgentRow.stories.tsx src/modules/resources/AgentDevcontainerCard.stories.tsx --run ``` </details> Follow-up to #19943. Tracks [CLI-67](https://linear.app/codercom/issue/CLI-67/fix-coder-ssh-suggestions-for-multi-agent-workspaces). Preview: https://coder.com/docs/@fix%2Fssh-multi-agent-hint/workspaces/workspace-access > 🤖 This PR was created with the help of Coder Agents, and has been reviewed by my human. 🧑💻 |
||
|
|
fb6d287528 |
fix: write agent host entries with config-ssh --no-wildcard (#31192)
`coder config-ssh --no-wildcard` writes one `Host` entry per workspace and none per agent. OpenSSH only applies exact `Host` matches, so with `--no-wildcard` (and without Coder Desktop): - `ssh <agent>.<workspace>.<owner>.coder`, the hostname the dashboard's **Connect via SSH** button shows and Coder Connect serves, doesn't resolve. - Agents in multi-agent workspaces can't be reached with plain `ssh`; `ssh <workspace>.coder` hits "multiple agents found". Before wildcard hosts (#14986), `config-ssh` wrote an entry per agent. `--no-wildcard` (#26753) brought back per-workspace entries only. ## Change With `--no-wildcard`, also write an `<agent>.<workspace>.<owner>` entry for each agent, using the same prefix/suffix as workspace entries: ``` Host dogfood.coder # unchanged Host coder.dogfood.matifali.coder # new Host dev.dogfood.matifali.coder # new ``` `coder ssh --stdio` already parses `agent.workspace.owner`, so no ProxyCommand changes are needed. - **Non-breaking**: existing `<workspace>` entries are unchanged; agent entries are added after them. Without `--no-wildcard` the config is unchanged. - **Workspaces without agents on their latest build** (stopped, or a start that is pending or failed): known agents come from that workspace’s most recent successful start using the same template version, not template-import defaults. Lookups are cached per workspace and bounded to eight concurrent requests. Missing or incompatible history leaves only the workspace entry; lookup failures also produce a warning. - **Devcontainers**: while a workspace runs, its sub-agents get entries too. - **Validation**: workspace and owner names retain `codersdk.NameValid` checks. Agent components permit safe ASCII letters, digits, underscores and hyphens, preserving Terraform-precreated names such as `dev_box` while rejecting SSH syntax, leading options and doubled-hyphen delimiters. Workspace entries are written as before, including legacy names (related: SEC-378). The flag description, generated CLI reference/help, and workspace access and Gateway tips describe known agents. The guide explains when stopped workspaces have only a workspace entry and how to populate their agent entries. ## Verification `TestConfigSSH_NoWildcard` verifies two stopped workspaces sharing a template version but having different actual agents, import defaults that differ from both, a precreated `dev_box` agent, and injection rejection. History tests cover pagination, failed/newer builds, version changes and request failures. Regression controls failed before the fixes and passed afterward. Race tests, strict Go lint and docs checks pass on the refreshed stack. <details> <summary>Validation commands</summary> Latest rebase preserves the implementation and carries the docs edits to main’s renamed `docs/workspaces/` paths. The SSHButton documentation links and preview URL use the new routes. Revalidated the full SSH/ping/config CLI race suite, strict lint, 25 frontend tests, 53 stories, and docs/manifest/redirect checks. The local shell’s Oh My Zsh update prompt interrupted the first race run; the unchanged suite passed with `DISABLE_AUTO_UPDATE=true` scoped to the test process. Review decision: use workspace-specific build history because template imports cannot represent chosen workspace parameters. Preserve the last-start template-version boundary rather than inventing agents when no compatible history exists. Both stack branches are rebased onto `main` at `63b5c4d64a`. ```sh go test -race -tags=testsmallbatch ./cli -run 'TestConfigSSH|Test_noWildcardHostNames|Test_previousStartResources|TestCommandHelp' -count=1 -parallel=4 GOMEMLIMIT=6GiB make lint/go/new-code GO_LINT_CONCURRENCY=4 ``` Docs validation also passed emdash, HTML-table and manifest checks, targeted markdownlint, table formatting and Vale. </details> Fixes [CLI-68](https://linear.app/codercom/issue/CLI-68/config-ssh-no-wildcard-does-not-write-host-entries-for-workspace). #31188 is stacked on this PR. Preview: https://coder.com/docs/@fix%2Fconfig-ssh-no-wildcard-agents/workspaces/workspace-access > 🤖 This PR was created with the help of Coder Agents, and has been reviewed by my human. 🧑💻 |
||
|
|
a988af518c |
docs: rename the user-guides folder to workspaces (#31650)
> [!NOTE]
> Generated by Coder Agents. The branch and this description were
written by an AI agent and need human review.
## Summary
Fourth stacked PR for the docs IA overhaul. PR C renamed the User guides
sidebar section to **Workspaces**. This PR renames its folder to match,
so the folder tree and the sidebar agree (DOCS-1154). The section's
title, position, and contents don't change.
- `docs/user-guides/**` moves to `docs/workspaces/**` with `git mv`: 33
files. That includes pages that are not in the sidebar and the three
pages PR C moved in (`persistent-shared-workspaces.md`,
`cloning-git-repositories.md`, `speed-up-templates.md`).
- `docs/manifest/user-guides.yml` and `docs/manifest/user-guides/` (4
files) move to `docs/manifest/workspaces.yml` and
`docs/manifest/workspaces/`, and `index.yml` lists `workspaces.yml` in
the same position.
- Every relative link and image path is fixed, in moved pages and in
pages that link to them. This was done in one scripted pass from a clean
tree. `docs/images/` stays where it is, so images under
`docs/images/user-guides/` keep their names; only the relative paths
that point at them change.
- Commit 2, `chore: point in-product docs links at the new docs paths`,
updates docs URLs outside `docs/`, then regenerates the files built from
them with `make gen`. You can drop that commit; the redirects cover the
old URLs.
- Updated sources: `site/` `docs()` links and hardcoded docs URLs,
`cli/sharing.go` help text, `README.md`, `examples/templates/` READMEs
and `docker/main.tf`, templatebuilder base READMEs, and the doc-check
skill's audience persona.
- Regenerated files: the `coder sharing add/remove` CLI golden files,
`docs/reference/cli/sharing/{add,remove}.md`, and
`examples/examples.gen.json`.
- Commit 3, `fix: keep docs links healthy before the release`, keeps
links working on the live site until a release that includes this stack
becomes the default docs version:
- In hand-written pages, the docs commit's rewrite left 4 absolute
`https://coder.com/docs/workspaces/...` URLs. They are now relative
links, anchors kept: `admin/networking/wildcard-access-url.md`,
`install/operate/upgrade/esr-2.24-2.29-upgrade.md` (2 links), and
`workspaces/workspace-access/jetbrains/gateway.md`.
- Every hardcoded, unversioned `https://coder.com/docs/workspaces/...`
URL that commit 2 introduced outside `docs/` goes back to
`https://coder.com/docs/user-guides/...`. That covers 32 URLs in
`README.md`, `cli/sharing.go`, the examples and templatebuilder READMEs,
`examples/templates/docker/main.tf`, the `UserDropdownContent.tsx`
constant and its story assertion, and a JSDoc link in
`site/src/api/queries/workspaces.ts`. `make gen` then regenerated the
CLI golden files, `docs/reference/cli/sharing/{add,remove}.md`, and
`examples/examples.gen.json`. See "Post-release follow-up".
- The `site/` `docs()` changes stay, because those URLs are versioned
(`/docs/@vX.Y.Z/...`) and resolve once the release ships.
Stack: `docs/ia-ai-sections` (#31645, with Templates squash-merged in
#31646) → `docs/ia-tutorials-nav` (#31647) → **this PR**.
Refs: Linear DOCS-1154, DOCS-1179.
## Move map
| Old | New |
| --- | --- |
| `docs/user-guides/**` (33 files) | `docs/workspaces/**` |
| `docs/manifest/user-guides.yml` | `docs/manifest/workspaces.yml` |
| `docs/manifest/user-guides/**` (4 files) |
`docs/manifest/workspaces/**` |
## Redirects added
| Source | Destination |
| --- | --- |
| `/docs/user-guides` | `/docs/workspaces` |
| `/docs/user-guides/:path*` | `/docs/workspaces/:path*` |
Updated existing rules so none of them chain through the new wildcard:
| Source | Old destination | New destination |
| --- | --- | --- |
| `/docs/ai-coder/ide-agents` | `/docs/user-guides/workspace-access` |
`/docs/workspaces/workspace-access` |
| `/docs/tutorials/best-practices/speed-up-templates` |
`/docs/user-guides/speed-up-templates` |
`/docs/workspaces/speed-up-templates` |
| `/docs/tutorials/cloning-git-repositories` |
`/docs/user-guides/cloning-git-repositories` |
`/docs/workspaces/cloning-git-repositories` |
| `/docs/tutorials/persistent-shared-workspaces` |
`/docs/user-guides/persistent-shared-workspaces` |
`/docs/workspaces/persistent-shared-workspaces` |
**coder.com and router static redirects:** a chain simulation of
coder.com's and the router's static rules together with this branch's
`docs/redirects.json` finds one problem from this PR. The static
`/docs/workspaces` → `/docs/user-guides/workspace-management` rule in
both repos would hide the new `docs/workspaces/index.md` behind a
redirect to `/docs/workspaces/workspace-management`.
coder/coder.com#1201 and coder/docs-engine#304 remove it, together with
the Templates loops from #31645, once a release with this layout is the
docs mainline. If this PR ships in a later release than #31645, drop the
`/docs/workspaces` part of those PRs until then. The other static
`/docs/user-guides/...` destinations there still work; each now takes
two redirects.
## Deviations from the proposal
- **Not in Proposal 1.** The proposal only renamed the sidebar title.
This folder rename was requested afterward so the folder-driven renderer
shows the same name.
- **Generated files belong to commit 2.** Commit 1 doesn't edit
generated docs. They change only through their sources and `make gen`.
- **Left unchanged on purpose:**
- `docs/images/user-guides/` keeps its name, as requested.
- `.github/workflows/test-docs-preview-mapper.sh` uses
`docs/user-guides/...` as synthetic fixture paths.
- `docs/templates/extending-templates/jetbrains-airgapped.md` has a
"file a GitHub issue" link whose URL-encoded body names
`coder.com/docs/user-guides/workspace-access/jetbrains/jetbrains-airgapped`.
That URL was already wrong before this PR (the page lives under
`templates/`), and it only pre-fills an issue body, so I left it.
- Database migrations and notification golden files: none of them
contain `user-guides` links.
## Open questions for Nick
1. Should `docs/images/user-guides/` be renamed to
`docs/images/workspaces/` in a follow-up, or stay as is?
2. Frontend review nits on existing code that this PR only touched; I
didn't change them:
- `UserDropdownContent.tsx` defines `CODER_DESKTOP_DOCS_URL` as a
hardcoded `https://coder.com/docs/...` URL instead of
`docs("/workspaces/desktop")`, which `SSHButton.tsx` uses for the same
page.
- The `UserDropdown` and `SecretsPageView` stories' `play` functions
only assert link attributes.
## Post-release follow-up
After a release that includes this stack becomes the default docs
version on coder.com, point these hardcoded URLs at the new paths. They
work today and redirect after the release. Anchors are unchanged. Rerun
`make gen` afterward to update the CLI golden files,
`docs/reference/cli/sharing/{add,remove}.md`, and
`examples/examples.gen.json`.
| Current (old) URL | Post-release URL | Files |
| --- | --- | --- |
| `https://coder.com/docs/user-guides/desktop` |
`https://coder.com/docs/workspaces/desktop` |
`site/src/modules/dashboard/Navbar/UserDropdown/UserDropdownContent.tsx`,
`UserDropdown.stories.tsx` |
| `https://coder.com/docs/user-guides/devcontainers` |
`https://coder.com/docs/workspaces/devcontainers` | `README.md` |
| `https://coder.com/docs/user-guides/shared-workspaces` |
`https://coder.com/docs/workspaces/shared-workspaces` | `cli/sharing.go`
(CLI help, 2 places) |
| `https://coder.com/docs/user-guides/workspace-access` |
`https://coder.com/docs/workspaces/workspace-access` | `README.md` |
|
`https://coder.com/docs/user-guides/workspace-access/jetbrains/toolbox`
| `https://coder.com/docs/workspaces/workspace-access/jetbrains/toolbox`
| `examples/templates/docker/main.tf` |
| `https://coder.com/docs/user-guides/workspace-dotfiles` |
`https://coder.com/docs/workspaces/workspace-dotfiles` |
`coderd/templatebuilder/bases/{azure-linux,docker,kubernetes}/README.md`,
`examples/templates/{azure-linux,docker,kubernetes}/README.md` |
| `https://coder.com/docs/user-guides/workspace-management` |
`https://coder.com/docs/workspaces/workspace-management` | `README.md`,
`coderd/templatebuilder/bases/{aws-linux,aws-windows,azure-linux,digitalocean-linux,docker,kubernetes}/README.md`,
`examples/templates/{aws-linux,aws-windows,azure-linux,azure-windows,digitalocean-linux,docker-devcontainer,docker-envbuilder,docker,kubernetes-devcontainer,kubernetes,nomad-docker}/README.md`,
`site/src/api/queries/workspaces.ts` (JSDoc) |
## Validation run
- `make gen/docs-manifest`: clean diff afterward.
- `make lint/docs-manifest`, `lint/docs-redirects` (`-base
docs/ia-tutorials-nav`: 36 rules OK), `lint/docs-html`, `lint/emdash`:
pass.
- `pnpm check-docs` (markdownlint + table formatter): pass.
- Vale over `docs/`: identical to `docs/ia-tutorials-nav` (12 warnings,
1 error, 645 suggestions, all pre-existing).
- Local relative-link check over `docs/**/*.md`: 0 unresolved (3410
links and images in 498 files).
- `grep -rn user-guides docs/` finds only `docs/redirects.json`, image
paths under `docs/images/user-guides/`, and the issue link above.
- Pre-commit hook: `make pre-commit-light` on the docs commit, and the
full `make pre-commit` (gen, fmt, lint/go, lint/ts, build, and others)
on the chore commit. `make gen` left a clean tree.
- Targeted tests:
- Go: `go test ./cli -run TestCommandHelp`, `./examples/...`,
`./coderd/templatebuilder/...`.
- Site: Vitest for the touched directories (22 files, 409 tests), and
the `UserDropdown` and `SecretsPageView` story tests (2 files, 59
tests).
- Every `docs()` path and `coder.com/docs` URL in the chore diff
resolves to a page and heading in this branch.
- Frontend deep review (all 8 roles) on the `site/` diff: no blocking or
should-fix findings; the nits are in question 2.
- Restacked on the rebased `docs/ia-tutorials-nav` (on `main` at
`ccf5ec74ae`). After the restack, `make gen/docs-manifest` (clean),
`lint/docs-manifest`, `lint/docs-redirects` (36 rules OK),
`lint/docs-html`, `lint/emdash`, `pnpm check-docs`, and the
relative-link and anchor check over the changed pages pass.
- Page counts: `docs/**/*.md` (excluding `.style`) 485 → 485;
`manifest.json` routes 482 → 482 (moves only).
- **Link health (commit 3):**
- linkspector 0.5.6 with `.github/.linkspector.yml` over all of `docs/`,
like the weekly docs job, run locally.
- `origin/main`: 0 errors. Before the fix (`7382a41faa`): 11 errors. 10
were `https://coder.com/docs/<new path>` 404s: the 6 from #31645 plus 4
`workspaces/...` URLs. The 11th was a transient Red Hat URL failure in
`install/server/openshift.md`, which is unchanged from `main` and passed
on reruns. After the fix (`c1f287fc1b`): 0 errors. Nothing is new
compared with `main`.
- After the fix: `make gen/docs-manifest` (clean), `lint/docs-manifest`,
`lint/docs-redirects` (36 rules OK against `docs/ia-tutorials-nav`),
`lint/docs-html`, `lint/emdash`, `pnpm check-docs`, and the
relative-link check (0 unresolved in 3419 links) pass. The full `make
pre-commit`, including `make gen`, passed on the commit.
- Outside `docs/`, no line in this stack adds an unversioned
`coder.com/docs` URL compared with `main`.
- Tests after the fix:
- Go: `go test ./cli -run 'TestCommandHelp|TestServerYAMLConfig'`,
`./examples/...`, `./coderd/templatebuilder/...`, `./cli/cliui`.
- Site: Vitest for the touched directories (21 files, 404 tests), and
the `UserDropdown` story tests (28 tests).
- **Skipped:** the docs-engine sync check, which was not available in
this environment.
<details>
<summary>Implementation notes</summary>
- Same one-shot move script as PRs A to C, with a single rule,
`docs/user-guides/` → `docs/workspaces/`. It resolves each relative link
against the page's old directory, maps the target through the move,
recomputes it from the new directory, and also rewrites
`coder.com/docs/...` and
`github.com/coder/coder/(blob|edit|tree)/main/docs/...` URLs. It skips
fenced code blocks and inline code, and refuses to run on a dirty
`docs/` tree.
- After #31645 and #31647 got their link-health fixes, a plain rebase of
this branch conflicted in `esr-2.24-2.29-upgrade.md`, where both changed
the same table rows. Instead of resolving by hand, I rebuilt the docs
and chore commits from the fixed `docs/ia-tutorials-nav` with the same
scripts. The resulting docs commit differs from the earlier one only by
#31645's fix, and the chore commit touches the same 36 files.
- No hand edits were needed in the docs commit. The sidebar sources were
renamed with `git mv` and their `path`/`include` prefixes rewritten.
- The redirect script repointed every existing destination under
`/docs/user-guides` before appending the two new rules.
- Restacked on 2026-11-03 onto `docs/ia-tutorials-nav` at `76aed1a618`.
The chore commit conflicted with #31603 in
`site/src/pages/WorkspacesPage/WorkspaceHelpPopover.tsx`; both links
keep `main`'s `target="_blank" rel="noreferrer"` with only the path
changed, and the `WorkspacesPage` Vitest suite (24 tests) passes. Folded
into the docs commit: the `../user-guides/` links in
`docs/coder-agents/bring-your-own-mcp-servers.md`, a page `main` added,
now point at `../workspaces/`.
</details>
---------
Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com>
Co-authored-by: Nick Vigilante <nick.vigilante@coder.com>
|