> [!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>