feat(docs): enable Coder.CheckOut Vale rule (#31185)

> [!NOTE]
> Recreated from #30793 under coder[bot] by Superblink, at the request
of @nickvigilante, so he can review and merge it. An AI agent wrote the
original, which was opened from his account. The diff is identical to
#30793, squashed onto current `main`. Superblink reviewed it and ran
Vale over `docs/` before opening this PR (no new warnings or errors).
#30793 should be closed in favor of this one.
> Stack: based on #31184 (#31180 → #31181 → #31182 → #31183 → #31184 →
#31185). The diff matches #30793 except for the counters in
`docs/.style/style-guide/README.md`, which build on the PRs below this
one. `make lint/style-claims` passes at every level.

Builds on #30782, which is merged; the branch now merges `main`.

Adds `Coder.CheckOut`, a Vale rule that enforces [Refer to or visit, not
see or check
out](https://github.com/coder/coder/blob/main/docs/.style/style-guide/word-choice.md#refer-to-or-visit-not-see-or-check-out).
It flips only `Coder.CheckOut` in the footer; `Coder.SeeAlternatives`
stays planned.

- Flags "check out" and its inflections (`checks out`, `checked out`,
`checking out`) when used to point the reader at a page or site.
- Severity: `warning`. Scope: `docs/**` except
`docs/.style/style-guide/**`.
- Baseline: 11 findings in 10 pages, 0 after cleanup. One of them
(`docs/ai-coder/agent-firewall/index.md`) landed on `main` after the
branch was cut.
- Cleanup rewrites each to "refer to" (docs destinations) or "visit"
(external destinations).
- The Git sense is allowed and isn't flagged. Examples: "check out the
branch", `git checkout`, "a source checkout".
- Generated pages: no findings, so no `.vale.ini` change and no Go
source change.

Commits:

1. `docs(docs): refer to or visit instead of "check out"`
2. `feat(docs/.style): enable Coder.CheckOut Vale rule`

Linear: DOCS-1260

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

- Vale's `existence` rule can't do this. RE2 has no lookahead, so the
rule can't say "check out, unless a Git object follows". A token that
includes the following words also fails: Vale can't locate a match that
spans link text (`check out [Dev Containers]` renders without the
bracket), and it silently drops the finding. Those link-follows cases
are the main true positives.
- The rule is therefore `extends: script` (Tengo, supported by the
pinned Vale 3.7.1) with `scope: text`. It finds each "check out" and
reports only those two words. It skips the match when one of the next 3
words is a Git object, or when "and" follows directly.
- Git objects skipped: branch, repo, repository, code, source, commit,
tag, PR, pull request, fork, clone, worktree, file, revision, ref,
master, main, trunk, submodule, sha, changes, release, version, folder,
directory, dotfiles. A hyphenated name such as `code-marketplace` isn't
a Git object.
- The one-word "checkout" is never flagged. In this corpus it's a Git
noun or command (`git checkout`, "source checkout") or the
`actions/checkout` action. The brief mentions "checkout" as a possible
verb, but I found no verb use, so I left it out rather than guess.
- `warning`, because the rule can't tell the senses apart from text
alone.

Test cases (fixtures under `/tmp/checkout-test/`, not committed), run
with LF and CRLF line endings:

- Flagged (8 each): link follows ("Check out [Dev Containers
integration]"), "check out our [module registry]", "check out
HashiCorp's [Getting Started Guides]", "Checking out the [Quickstart]",
"checked out" in a blockquote, "Checks out" in a list item, a heading
("Check out more"), a hard-wrapped "check out the\n[envbox docs]".
- Not flagged (0 each): "check out the branch", "the repository", "the
code", "a commit", "the tag", "the PR", "the pull request", "check out
and install a dotfiles repository", "source checkout", "Git checkout",
`git checkout main`, a `git checkout -b` fenced block, "Checkout
repository" in a list item, "the checkout action", "check outputs",
"check output".

Known gaps:

- False negative: a cross-reference that names a Git word right after
the verb, such as "check out our code samples".
- False positive risk: a Git sense with an object the list doesn't name.

Checks:

- `vale --output=line docs/` reports 0 `Coder.CheckOut` findings.
- `go run ./scripts/styleclaims` passes.
- The pre-commit-light hook passes on both commits.

</details>

*Generated by [Coder Agents](https://coder.com/docs/ai-coder/agents) on
behalf of @nickvigilante.*

Created on behalf of @nickvigilante

---------

Co-authored-by: Nick Vigilante <nick.vigilante@coder.com>
This commit is contained in:
coder[bot]andNick Vigilante authored and GitHub committed 2026-10-23 16:44:35 +00:00
1 parent a3876a3634
commit 78aa570078
13 files changed
+63 -17

No files matched your search

+6 -5
View File
@@ -23,8 +23,8 @@ The doctrine for adding Vale rules lives in the [Vale doctrine README](../README
A clean `make lint/prose` run is not evidence that a page follows this guide.
The guide documents 88 rules.
Automated tooling checks 16 of them, and 1 of those 16 doesn't run on published pages.
The other 72 are yours to apply by reading, 73 on published pages, where the one-sentence-per-line rule is off.
Automated tooling checks 17 of them, and 1 of those 17 doesn't run on published pages.
The other 71 are yours to apply by reading, 72 on published pages, where the one-sentence-per-line rule is off.
Open the section that matches what you're writing and work through it.
The linters catch a narrow band of mechanical errors; they can't tell you that a page serves 2 audiences, buries a required step in a `NOTE`, or wraps every paragraph at 80 columns.
@@ -42,6 +42,7 @@ The linters catch a narrow band of mechanical errors; they can't tell you that a
| `Coder.SelectClick` | Vale | `warning` | `docs/**` except `docs/.style/style-guide/**` | `click` and its inflections |
| `Coder.OneSentencePerLine` | Vale | `warning` | `docs/.style/*.md` and `docs/.style/styles/Coder/*.md` only | Sentence boundaries mid-line, on contributor docs only |
| `Coder.UnitSpacing` | Vale | `warning` | `docs/**` except `docs/.style/style-guide/**` and `docs/admin/integrations/prometheus.md` and `docs/admin/setup/configuration-reference.md` and `docs/reference/{api,cli}/*.md` | A regular space, or no space, between a number and its unit |
| `Coder.CheckOut` | Vale | `warning` | `docs/**` except `docs/.style/style-guide/**` | `check out` as a cross-reference verb, not the Git sense |
| `Coder.AmbiguousWords` | Vale | `suggestion` | `docs/**` except `docs/.style/style-guide/**` and `docs/reference/{api,cli}/*.md` | `ensure`, `should`, `since`, and `may` (not the month `May`) |
| `MD001`, `MD025`, `MD040`, `MD045` | markdownlint | `error` | All Markdown | Heading increments, single H1, fence language, missing alt text |
| `scripts/check_emdash.sh` | `make lint/emdash` | `error` | Repository | Em-dash, en-dash, and `--` as punctuation |
@@ -63,12 +64,12 @@ The markdownlint, emdash, docs HTML, and docs-manifest checks do fail the build.
| [Audience and scope](./audience-and-scope.md) | 6 | 0 | 0 | 6 |
| [Voice and tone](./voice-and-tone.md) | 12 | 1 | 3 | 8 |
| [Procedural writing](./procedural-writing.md) | 6 | 0 | 1 | 5 |
| [Word choice](./word-choice.md) | 20 | 3 | 11 | 6 |
| [Word choice](./word-choice.md) | 20 | 4 | 10 | 6 |
| [Accessibility and inclusion](./accessibility-and-inclusion.md) | 14 | 5 | 3 | 6 |
| [Capitalization and punctuation](./capitalization-and-punctuation.md) | 12 | 3 | 7 | 2 |
| [Formatting](./formatting.md) | 13 | 3 | 0 | 10 |
| [Numbers, units, and dates](./numbers-units-and-dates.md) | 5 | 1 | 4 | 0 |
| **Total** | 88 | 16 | 29 | 43 |
| **Total** | 88 | 17 | 28 | 43 |
Every column counts rule sections, not linter rule names.
A rule section is a heading that carries an enforcement footer, the italic line that names the section's enforcement status.
@@ -95,7 +96,7 @@ Classify a counted section from its footer, in this order:
A section that names several checks still counts once.
3. Anything else: the section is planned.
So the 14 rows in the table above name 17 checks, because the markdownlint row bundles 4, and those 17 checks cover 16 sections: each check counts under the section that owns it rather than under every section that mentions it.
So the 15 rows in the table above name 18 checks, because the markdownlint row bundles 4, and those 18 checks cover 17 sections: each check counts under the section that owns it rather than under every section that mentions it.
A rule marked `(planned)` in a section footer names the rule that would enforce it if it existed.
It isn't running today.
+2 -1
View File
@@ -419,7 +419,8 @@ In a list of outcomes, "learn why the build fails" or "find out why the build fa
>
> Add a Ruby option, then see why the option alone doesn't install the toolchain.
*Enforced by `Coder.SeeAlternatives` (planned) and `Coder.CheckOut` (planned).*
*Enforced by `Coder.SeeAlternatives` (planned) and `Coder.CheckOut` (`warning`).
The rule leaves the Git sense alone: it skips a "check out" followed within 3 words by a Git object such as a branch, repository, commit, tag, or pull request, or by "and".*
## Learn more, not Next steps
+44
View File
@@ -0,0 +1,44 @@
# Coder.CheckOut - use "refer to" or "visit" instead of "check out" when the
# prose points the reader at a page, section, or site.
# Refer to word-choice.md#refer-to-or-visit-not-see-or-check-out for the rule.
#
# The Git sense of "check out" is allowed ("check out the branch", "check out
# a commit"), and so is the noun "checkout" ("a source checkout"), which this
# rule never matches. A match that spans link text can't be located in the
# source, so the rule is a script: it finds each "check out" and reports only
# those two words, after skipping a Git object in the next 3 words (a
# hyphenated name such as `code-marketplace` isn't one) or an "and" right after
# the verb ("check out and install a dotfiles repository").
#
# Level: warning. A cross-reference that names a Git word right after the verb
# is skipped, and a Git sense with an object the list below doesn't name is
# flagged, because the rule can't tell the two senses apart from text alone.
extends: script
message: "Use 'refer to' or 'visit' instead of '%s' for a cross-reference. Refer to word-choice.md#refer-to-or-visit-not-see-or-check-out."
link: https://github.com/coder/coder/blob/main/docs/.style/style-guide/word-choice.md#refer-to-or-visit-not-see-or-check-out
level: warning
scope: text
script: |
text := import("text")
matches := []
verb := `(?i)\bcheck(?:s|ed|ing)?[ \t\r\n]+out\b`
gitWord := `(?i)(?:^|[^\w-])(?:branch(?:es)?|repos?|repositor(?:y|ies)|code|source|commits?|tags?|prs?|pull|requests?|forks?|clones?|worktrees?|files?|revisions?|refs?|master|main|trunk|submodules?|sha|changes|release|version|folder|directory|dotfiles)(?:$|[^\w-])`
andNext := `(?i)^[ \t\r\n]+and\b`
found := text.re_find(verb, scope, -1)
if found != undefined {
for group in found {
m := group[0]
rest := scope[m.end:]
// The 3 words after the verb are the window that can name a Git object.
window := text.re_find(`^(?:[ \t\r\n]+[\w'’-]+){0,3}`, rest, 1)
ctx := ""
if window != undefined {
ctx = window[0][0].text
}
if !text.re_match(gitWord, ctx) && !text.re_match(andNext, rest) {
matches = append(matches, {begin: m.begin, end: m.end, text: m.text})
}
}
}
+2 -2
View File
@@ -7,12 +7,12 @@ title: Administration
These guides contain information on managing the Coder control plane and [authoring templates](./templates/index.md).
First time viewers looking to set up control plane access can start with the [configuration guide](./setup/index.md).
If you're a team lead looking to design environments for your developers, check out our [templates guides](./templates/index.md).
If you're a team lead looking to design environments for your developers, refer to our [templates guides](./templates/index.md).
If you are a developer using Coder, we recommend the [user guides](../user-guides/index.md).
For automation and scripting workflows, see our [CLI](../reference/cli/index.md) and [API](../reference/api/index.md) docs.
For any information not strictly contained in these sections, check out our [Tutorials](../tutorials/index.md) and [FAQs](../tutorials/faqs.md).
For any information not strictly contained in these sections, refer to our [Tutorials](../tutorials/index.md) and [FAQs](../tutorials/faqs.md).
## What is an image, template, dev container, or workspace
+1 -1
View File
@@ -142,4 +142,4 @@ See the [air-gapped deployments](../templates/extending-templates/modules.md#off
- See the [full example Docker template](../../../examples/jfrog/docker).
- To serve extensions from your own VS Code Marketplace, check out [code-marketplace](https://github.com/coder/code-marketplace#artifactory-storage).
- To serve extensions from your own VS Code Marketplace, visit [code-marketplace](https://github.com/coder/code-marketplace#artifactory-storage).
@@ -131,7 +131,7 @@ Some drawbacks include:
Envbox requires the same kernel requirements as running sysbox directly on the nodes.
Refer to sysbox's [compatibility matrix](https://github.com/nestybox/sysbox/blob/master/docs/distro-compat.md#sysbox-distro-compatibility) to ensure your nodes are compliant.
To get started with `envbox` check out the [starter template](../../../../examples/templates/kubernetes-envbox) or visit the [repo](https://github.com/coder/envbox).
To get started with `envbox`, refer to the [starter template](../../../../examples/templates/kubernetes-envbox) or visit the [repo](https://github.com/coder/envbox).
<a id="authenticating-with-a-private-registry"></a>
@@ -111,7 +111,7 @@ resource "coder_app" "zed" {
</div>
Check out our [module registry](https://registry.coder.com/modules) for additional Coder apps from the team and our OSS community.
Visit our [module registry](https://registry.coder.com/modules) for additional Coder apps from the team and our OSS community.
## Environment variables
+1 -1
View File
@@ -131,4 +131,4 @@ Selecting **Cancel** falls back to the standard creation form where all paramete
### Example: Kubernetes
For a full example of the Open in Coder flow in Kubernetes, check out [this example template](https://github.com/bpmct/coder-templates/tree/main/kubernetes-open-in-coder).
For a full example of the Open in Coder flow in Kubernetes, visit [this example template](https://github.com/bpmct/coder-templates/tree/main/kubernetes-open-in-coder).
+1 -1
View File
@@ -73,7 +73,7 @@ module "agent-firewall" {
For examples of wrapping an agent or process such as Claude Code with Agent Firewall, see the [agent-firewall module README](https://registry.coder.com/modules/coder/agent-firewall#with-claude-code).
For a basic recommendation of what to allow for agents, see the [Anthropic documentation on default allowed domains](https://code.claude.com/docs/en/claude-code-on-the-web#default-allowed-domains).
For a comprehensive configuration covering multi-language development, check out the [example policy](./example-policy.md).
For a comprehensive configuration covering multi-language development, refer to the [example policy](./example-policy.md).
To load the policy from a `config.yaml` file in your template directory instead, pass it via `agent_firewall_config`.
The module writes the config to the workspace and exposes the resolved path via `agent_firewall_config_path`, so everyone who launches Agent Firewall manually inside the workspace picks up the same configuration without extra flags.
@@ -108,7 +108,7 @@ The same control is available outside the dashboard.
Use `coder templates create --agents-allowed=false` or `coder templates edit --agents-allowed=false <template>` for a single template.
Use the search filter `agents-allowed:false` on `GET /api/v2/templates` to list the templates that block agents.
Check out [Template Optimization](./template-optimization.md) for best practices on writing discoverable descriptions, restricting template visibility, configuring network boundaries, scoping credentials, and designing template parameters for agent use.
Refer to [Template Optimization](./template-optimization.md) for best practices on writing discoverable descriptions, restricting template visibility, configuring network boundaries, scoping credentials, and designing template parameters for agent use.
### MCP servers
+1 -1
View File
@@ -93,7 +93,7 @@ For more details, see [Configuring proxy settings for Copilot](https://docs.gith
Add the AI Gateway Proxy CA certificate to your operating system's trust store.
By default, VS Code loads system certificates, controlled by the `http.systemCertificates` setting.
Check out [Client Configuration CA certificate trust](../ai-gateway-proxy/setup.md#trust-the-ca-certificate) for details on how to obtain the certificate file.
Refer to [Client Configuration CA certificate trust](../ai-gateway-proxy/setup.md#trust-the-ca-certificate) for details on how to obtain the certificate file.
When [TLS is enabled](../ai-gateway-proxy/setup.md#proxy-tls-configuration) on the proxy, add the TLS certificate to the system trust store as well.
+1 -1
View File
@@ -25,7 +25,7 @@ The Coder server essentially runs a `terraform apply` every time a workspace is
> [!TIP]
> Haven't written Terraform before?
> Check out HashiCorp's [Getting Started Guides](https://developer.hashicorp.com/terraform/tutorials).
> Visit HashiCorp's [Getting Started Guides](https://developer.hashicorp.com/terraform/tutorials).
Here's a simplified diagram that shows the main parts of the template we'll create:
+1 -1
View File
@@ -7,6 +7,6 @@ These guides contain information on workspace management, workspace access via I
These are intended for end-user flows only.
If you are an administrator, please refer to our docs on configuring [templates](../admin/index.md) or the [control plane](../admin/index.md).
Check out [Dev Containers integration](./devcontainers/index.md) for running containerized development environments in your Coder workspace.
Refer to [Dev Containers integration](./devcontainers/index.md) for running containerized development environments in your Coder workspace.
<children></children>