coder · nickvigilante · Jun 25, 2026 · Jun 23, 2026 · Jun 25, 2026 · Jun 25, 2026
diff --git a/.claude/docs/DOCS_STYLE_GUIDE.md b/.claude/docs/DOCS_STYLE_GUIDE.md
@@ -8,12 +8,9 @@ This guide documents structure, research, and content patterns for documentation
 > Read that first. When this style guide conflicts with the content
 > guidelines, the content guidelines govern.
 >
-> **For prose rules**, the canonical Coder documentation style guide lives
-> at [`docs/.style/style-guide.md`](../../docs/.style/style-guide.md) and
-> will be enforced by the Vale rules under `docs/.style/styles/Coder/`.
-> That guide is currently a scaffold; continue using the **Writing Style**
-> section below until it is populated. This file also remains authoritative
-> for structure, research, and content patterns.
+> **For prose rules**, refer to the canonical Coder documentation style guide at [`docs/.style/style-guide/`](../../docs/.style/style-guide/README.md).
+> Vale rules under `docs/.style/styles/Coder/` enforce those rules incrementally as each rule lands.
+> This file remains authoritative for structure, research, and content patterns.
 
 See [CONTRIBUTING.md](../../docs/about/contributing/CONTRIBUTING.md) for general contribution guidelines.
 

@@ -183,7 +183,7 @@ jobs:
       # `**.md` (not `docs/**.md`) because the action's globber collapses a
       # `**` adjacent to `.md` to a single path segment, so `docs/**.md`
       # only matches top-level docs/*.md and misses nested pages such as
-      # docs/.style/style-guide.md. The prose step below re-filters to
+      # docs/.style/style-guide/README.md. The prose step below re-filters to
       # docs/ paths.
       # Cache split into restore + conditional save to avoid letting PR
       # runs populate a cache that other branches restore from (the

diff --git a/AGENTS.md b/AGENTS.md
@@ -12,7 +12,8 @@ Rule #1: If you want exception to ANY rule, YOU MUST STOP and get explicit permi
 - Docs content scope: Use [Coder Docs Content Guidelines](docs/.style/content-guidelines.md) to decide whether a piece of content belongs in `docs/` at all. The Documentation Style Guide above covers prose and formatting; the content guidelines govern scope and routing and supersede the style guide on conflicts.
 - Compatibility: `.agents/docs` symlinks to `.claude/docs` for agent runtimes that look there.
 - Frontend: Read [Frontend Development Guidelines](site/AGENTS.md) before changing anything under `site/`.
-- Docs prose: When editing anything under `docs/`, see the prose style guide at [`docs/.style/style-guide.md`](docs/.style/style-guide.md). It is currently a scaffold; until it is populated, use the **Writing Style** section in [`.claude/docs/DOCS_STYLE_GUIDE.md`](.claude/docs/DOCS_STYLE_GUIDE.md). That file also covers structure, research, and content patterns.
+- Docs prose: When editing anything under `docs/`, refer to the prose style guide at [`docs/.style/style-guide/`](docs/.style/style-guide/README.md).
+  For supporting agent-specific guidance, refer to [`.claude/docs/DOCS_STYLE_GUIDE.md`](.claude/docs/DOCS_STYLE_GUIDE.md), which covers structure, research, and content patterns.
 
 ## Foundational rules
 

diff --git a/docs/.style/README.md b/docs/.style/README.md
@@ -56,9 +56,9 @@ directory from the surgical-reindex payload on mixed commits.
   `markdownlint-cli2 --fix $(find docs -name '*.md')`.
 - `make fmt/markdown` (markdown-table-formatter) reflows tables here for
   the same reason.
-- Vale lints the entire `docs/**/*.md` set, including
-  `docs/.style/style-guide.md`. See the repo-root `.vale.ini` for the
-  active configuration; run `make lint/prose` locally to reproduce.
+- Vale lints the entire `docs/**/*.md` set, including `docs/.style/style-guide/`.
+  Refer to the repo-root `.vale.ini` for the active configuration.
+  Run `make lint/prose` locally to reproduce.
 
 ## What does not run against this directory
 
@@ -80,8 +80,8 @@ with another style or contributing doc in the repo, it governs.
 
 ## Editing the style guide
 
-Open a PR against `docs/.style/style-guide.md`. Follow-up PRs add each
-rule and the matching style-guide section together.
+Open a PR against the appropriate subpage of `docs/.style/style-guide/`.
+Follow-up PRs add each rule and the matching style-guide section together.
 
 ## Adding a Vale rule
 
@@ -92,12 +92,8 @@ The PR that adds a rule is the rule's complete unit:
 1. **Cleanup commit**: fix every existing-content violation of the new
    rule so `make lint/prose` reports zero findings for it.
    The cleanup ships in the same PR as the enable, ordered first.
-2. **Enable commit**: add the rule to `.vale.ini` at its chosen
-   severity, write a corresponding section under
-   `docs/.style/style-guide.md`, and add the custom rule YAML under
-   `docs/.style/styles/Coder/` if applicable.
-   The rule's `message:` field points at the relevant `style-guide.md`
-   anchor.
+2. **Enable commit**: add the rule to `.vale.ini` at its chosen severity, write a corresponding section under the matching subpage of `docs/.style/style-guide/`, and add the custom rule YAML under `docs/.style/styles/Coder/` if applicable.
+   The rule's `message:` field points at the relevant style-guide subpage anchor.
 
 Severity is a deliberate per-rule choice:
 

diff --git a/docs/.style/style-guide.md b/docs/.style/style-guide.md
diff --git a/docs/.style/style-guide/README.md b/docs/.style/style-guide/README.md
@@ -0,0 +1,109 @@
+# Coder documentation style guide
+
+This is the canonical prose style guide for the Coder documentation.
+It tells you *how* to write the words that go in the docs.
+For decisions about what belongs in the docs and what does not, refer to [`content-guidelines.md`](../content-guidelines.md).
+
+Each rule on the pages below is a policy decision the Coder docs team has made.
+Where a Vale rule already enforces the policy, the rule name is listed in a parenthetical so you can reproduce the warning locally.
+Where the rule is documentation-only, the parenthetical says so.
+The doctrine for adding Vale rules lives in [`README.md`](../README.md).
+
+## How to use this guide
+
+- **Contributors**: read the section that matches what you are writing.
+  Each rule includes a brief rationale and **Do** / **Don't** examples.
+- **Reviewers**: cite the section in a review comment.
+  Reviews are easier when the guidance lives in one place.
+- **AI agents**: read every section before editing anything under `docs/`.
+  The Coder Agents and Claude Code guides ([`AGENTS.md`](../../../AGENTS.md), [`.claude/docs/DOCS_STYLE_GUIDE.md`](../../../.claude/docs/DOCS_STYLE_GUIDE.md)) link here.
+
+## Sections
+
+| Page                                                                  | Covers                                                                                                                                                                                |
+|-----------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [Audience and scope](./audience-and-scope.md)                         | One audience per page; one outcome per page; declare both up front; Coder personas                                                                                                    |
+| [Voice and tone](./voice-and-tone.md)                                 | Second person; no first-person singular; "we" as the company, not the software; active voice; present tense                                                                           |
+| [Word choice](./word-choice.md)                                       | Canonical brand and product names; "refer to" over "see"; "select" over "click"; weasel words; plain English for product actions; keep internal-only references out of published docs |
+| [Accessibility and inclusion](./accessibility-and-inclusion.md)       | WCAG target; inclusive pronouns and substitutions; descriptive link text; alt text; page descriptions; heading structure; reading level                                               |
+| [Capitalization and punctuation](./capitalization-and-punctuation.md) | Sentence-case headings; no gerund leads; no em-dashes; commas; US-style quotation                                                                                                     |
+| [Formatting](./formatting.md)                                         | Bold for UI; italics for emphasis; code font for identifiers; language fences on code blocks; callouts; tabs; lists; tables; links; images; screenshots sparingly                     |
+| [Numbers, units, and dates](./numbers-units-and-dates.md)             | Digits everywhere; non-breaking space between number and unit; `Month Day, Year` dates; 12-hour time with AM/PM                                                                       |
+| [Editor setup](./editor-setup.md)                                     | Vale editor integration for VS Code, Cursor, JetBrains, and Neovim (placeholder)                                                                                                      |
+
+## Conventions for editing Coder docs
+
+These conventions apply to every Markdown file under `docs/`.
+The style guide subpages dogfood them so contributors can see the rules in action.
+
+### One sentence per line
+
+Source lines in Coder documentation follow a one-sentence-per-line policy.
+Each sentence sits on its own Markdown source line.
+Sentences are not split across lines, and lines do not wrap to a fixed column width.
+
+The rendered Markdown joins lines inside a paragraph back together, so the source line breaks do not appear in the rendered output.
+Reviewers reading the diff do encounter them, and they make diffs land cleanly at the sentence level.
+
+`markdownlint`'s `MD013` (line length) is already disabled, so the convention is editorial.
+Editors that auto-wrap on save should be configured to leave the source alone.
+
+#### Incremental adoption
+
+The Coder docs corpus predates this convention.
+Much of the existing prose still wraps to a fixed column width or runs on a single long line, and some paragraphs on the other pages of this style guide still carry semantic line breaks (sembr) from earlier commits in this PR.
+The convention is adopted incrementally.
+
+When a contributor edits any line inside a paragraph, the entire paragraph is reformatted to one sentence per line as part of the same edit.
+The contributor does not reformat surrounding paragraphs they did not otherwise touch.
+
+For this rule, a bullet item, a numbered list entry, and a blockquote line are each their own paragraph.
+Headings, fenced code blocks, and tables are out of scope: headings are single lines by convention, code blocks render their source verbatim, and table rows are governed by `markdown-table-formatter`.
+
+### The style guide does not use "see" for navigation
+
+The [Word choice page](./word-choice.md) bans "see" as a navigational verb across all docs.
+The style guide itself follows the rule: "refer to" for formal cross-references, "check out" for informal pointers in tutorial-style passages, "visit" for external URLs.
+Reserve "see" for the rare case where the prose describes what a reader observes in the product UI.
+
+## Vale enforcement
+
+The repo-root `.vale.ini` loads only the Coder rule package by default.
+Third-party rules from Google, alex, and write-good are not enabled until a per-rule PR brings each back in.
+
+Each enabled rule lands via a dedicated PR that:
+
+1. Cleans the corpus to zero baseline findings.
+2. Adds the rule line in `.vale.ini` at the rule author's chosen severity.
+3. Adds the corresponding section to the appropriate subpage of this guide.
+
+Severity is a deliberate per-rule choice from the three-tier ladder:
+
+- `error` blocks merge in CI.
+  Use for hard policy where any violation is wrong.
+- `warning` surfaces an annotation without failing CI.
+  Use for strong guidance with legitimate human-judgment exceptions.
+- `suggestion` surfaces a `notice` annotation.
+  Use for soft guidance where the right fix is contextual.
+
+The full doctrine, including the false-positive policy, lives in [`README.md`](../README.md).
+Run `make lint/prose` to reproduce the baseline locally.
+
+## Relationship to `docs/about/contributing/documentation.md`
+
+A public-facing prose summary lives today at [`docs/about/contributing/documentation.md`](../../about/contributing/documentation.md).
+A follow-up PR will redirect that page to this guide.
+Until then, follow the public summary for anything the subpages of this guide do not cover.
+New prose rules land here.
+The public page is frozen pending the redirect.
+
+## Third-party references
+
+When this guide does not cover something, consult:
+
+| Type of guidance         | Reference                                                                               |
+|--------------------------|-----------------------------------------------------------------------------------------|
+| Spelling                 | [Merriam-Webster](https://www.merriam-webster.com/)                                     |
+| Style, nontechnical      | [The Chicago Manual of Style](https://www.chicagomanualofstyle.org/home.html)           |
+| Style, technical         | [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) |
+| Style, developer-focused | [Google developer documentation style guide](https://developers.google.com/style)       |