coder · nickvigilante · Aug 18, 2026 · Aug 4, 2026
diff --git a/docs/.style/style-guide/README.md b/docs/.style/style-guide/README.md
@@ -7,7 +7,7 @@ For decisions about what belongs in the docs and what doesn't, refer to [`conten
 Each rule on the linked pages 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).
+The doctrine for adding Vale rules lives in the [Vale doctrine README](../README.md).
 
 ## How to use this guide
 
@@ -44,22 +44,23 @@ Each sentence sits on its own Markdown source line.
 Sentences aren't split across lines, and lines don't wrap to a fixed column width.
 
 The rendered Markdown joins lines inside a paragraph back together, so the source line breaks don't appear in the rendered output.
-Reviewers reading the diff do encounter them, and they make diffs land cleanly at the sentence level.
+Reviewers reading the diff do encounter them, and the per-sentence lines 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.
+Configure editors that auto-wrap on save 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.
+Much of the existing prose still wraps to a fixed column width or runs on a single long line.
+Some paragraphs on the other pages of this style guide still carry semantic line breaks (sembr) from earlier commits.
 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.
+A contributor who edits any line inside a paragraph reformats the entire paragraph to one sentence per line as part of the same edit.
 The contributor doesn't reformat surrounding paragraphs they didn't 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`.
+Headings, fenced code blocks, and tables are out of scope: headings are single lines by convention, code blocks render their source verbatim, and `markdown-table-formatter` governs table rows.
 
 ### The style guide doesn't use "see" for navigation
 
@@ -78,7 +79,7 @@ Each enabled rule lands via a dedicated PR that:
 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:
+Severity is a deliberate per-rule choice among 3 tiers:
 
 - `error` blocks merge in CI.
   Use for hard policy where any violation is wrong.
@@ -87,7 +88,7 @@ Severity is a deliberate per-rule choice from the three-tier ladder:
 - `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).
+The full doctrine, including the false-positive policy, lives in the [Vale doctrine README](../README.md).
 This guide is itself exempt from the Coder rules: it demonstrates the violations those rules ban, so the repo-root `.vale.ini` clears `BasedOnStyles` for `docs/.style/style-guide/**`.
 Zero baseline is measured over `docs/` excluding `docs/.style/style-guide/`.
 Run `make lint/prose` to reproduce the baseline locally.

diff --git a/docs/.style/style-guide/accessibility-and-inclusion.md b/docs/.style/style-guide/accessibility-and-inclusion.md
@@ -1,10 +1,12 @@
 # Accessibility and inclusion
 
-The Coder documentation aims for [WCAG 2.1](https://www.w3.org/TR/WCAG21/) Level AA conformance as a minimum, with Level AAA as a stretch goal where it doesn't sacrifice clarity.
+The Coder documentation aims for [WCAG 2.1](https://www.w3.org/TR/WCAG21/) Level AA conformance as a minimum, with Level AAA conformance wherever it doesn't sacrifice clarity.
 The rules on this page support that target.
-They cover heading structure, inclusive language, link text, images, plain English for international readers, page descriptions, and reading level.
+They cover heading structure, inclusive language, link text, and images.
+They also cover plain English for international readers, page descriptions, and reading level.
 
-> [!NOTE] Color contrast and other rendered-output a11y concerns belong to the docs site theme, not to prose conventions.
+> [!NOTE]
+> Color contrast and other rendered-output accessibility concerns belong to the docs site theme, not to prose conventions.
 > The Coder docs team tracks color-contrast conformance separately.
 
 ## Heading structure and placement
@@ -33,12 +35,11 @@ The following sections cover SSH access and environment variables.
 ## Set up SSH access
 
 SSH access uses the agent that runs inside your workspace.
-Two client setups are documented in the following sections.
+The following sections cover 2 client setups.
 
 ### Connect through JetBrains Toolbox
 
-Install the Coder plugin in JetBrains Toolbox,
-then connect to your workspace by name.
+Install the Coder plugin in JetBrains Toolbox, then connect to your workspace by name.
 
 ### Connect through VS Code Remote SSH
 
@@ -59,8 +60,7 @@ Define them in the template or in the workspace's parameters.
 
 #### Connect through JetBrains Toolbox
 
-Install the Coder plugin in JetBrains Toolbox,
-then connect to your workspace by name.
+Install the Coder plugin in JetBrains Toolbox, then connect to your workspace by name.
 ```
 
 The second H1 creates two competing page titles.
@@ -126,16 +126,16 @@ The alt text describes what the image shows or what purpose it serves.
 It isn't a caption.
 Captions follow the image in a `<small>` tag.
 
-Aim for one or two sentences that convey the same information a sighted reader would extract from the image.
-Lead with the subject, not "An image of" or "A screenshot showing".
+Aim for 1 or 2 sentences that convey the same information a sighted reader would extract from the image.
+Lead with the subject, not "An image of" or "A screenshot showing."
 
 ```md
 ![Template Insights dashboard with weekly active users and connection latency charts](../../images/admin/templates/template-insights.png)
 
 <small>The Template Insights dashboard with active-user and connection-latency widgets.</small>
 ```
 
-For complex diagrams that can't be summarized in alt text, provide a longer description in the body of the page and reference it from the alt text.
+For diagrams that alt text can't summarize, provide a longer description in the body of the page and reference it from the alt text.
 
 *Enforced by `markdownlint` rule `MD045` for the alt-text-required requirement.*
 
@@ -150,15 +150,15 @@ Empty alt text tells the screen reader to skip the image rather than announce a
 
 Decorative images are rare in the Coder docs.
 Most images shown to a reader are screenshots or diagrams that convey information, and those images need descriptive alt text.
-When in doubt, write descriptive alt text.
+If you aren't sure, write descriptive alt text.
 
 *Documentation-only.
 No Vale rule.*
 
 ## Directional language
 
 Screen-reader users navigate documents linearly and don't experience the visual layout.
-Phrases like "see below", "above the table", or "the menu on the left" lose meaning when the reader can't see where elements sit on the page.
+Phrases like "see below," "above the table," or "the menu on the left" lose meaning when the reader can't see where elements sit on the page.
 Sighted readers also benefit from semantic references when the page gets restructured or they jump in through an anchor link.
 
 Refer to content by section heading, by document order (`the previous section`, `the following section`), or by anchor link.
@@ -193,7 +193,7 @@ Common replacements:
 | scroll down                  | scroll to the `[Section](#anchor)`, scroll to the end             |
 
 The rule covers prose.
-Idiomatic stack metaphors like "built on top of Terraform" and phrasal verbs like "set up", "back up", "log in", and "shut down" aren't directional and stay as-is.
+Idiomatic stack metaphors like "built on top of Terraform" and phrasal verbs like "set up," "back up," "log in," and "shut down" aren't directional and stay as-is.
 
 *Documentation-only.
 No Vale rule.*
@@ -206,7 +206,7 @@ Two patterns add friction for non-native speakers without adding meaning, so the
 ### Avoid idioms and figurative language
 
 Idioms (`under the weather`, `ballpark figure`, `get the ball rolling`, `at the eleventh hour`) and figurative language (`unleash`, `supercharge`, `dive in`, `out of the box`) rely on cultural context that doesn't translate.
-They also rarely add precision.
+They add no precision.
 Replace them with the literal meaning.
 
 **Do**:
@@ -226,7 +226,7 @@ Replace them with the literal meaning.
 > Coder ships with a default template out of the box.
 
 The rule covers developer idiom too.
-"Spin up a workspace" becomes "create a workspace", "tear down the deployment" becomes "delete the deployment", and "stand up a cluster" becomes "deploy a cluster".
+"Spin up a workspace" becomes "create a workspace," "tear down the deployment" becomes "delete the deployment," and "stand up a cluster" becomes "deploy a cluster."
 The figurative forms are so common in developer conversation that they no longer register as figurative, but they translate as badly as any other idiom.
 
 *Documentation-only.
@@ -235,7 +235,8 @@ Planned Vale rule `Coder.Idioms`.*
 ### Latin abbreviations
 
 The following Latin abbreviations are fine in Coder docs.
-Use them when they fit the sentence; the English equivalent is also fine.
+Use them when they fit the sentence.
+The English equivalent is also fine.
 
 | Abbreviation | Meaning                                        | Notes                                                                      |
 |--------------|------------------------------------------------|----------------------------------------------------------------------------|
@@ -245,7 +246,8 @@ Use them when they fit the sentence; the English equivalent is also fine.
 | `vs.`        | versus, against, as opposed to, in contrast to | No comma. Example: `coder server vs. coder agent`.                         |
 | `et al.`     | and others                                     | Citation contexts only. Follow the citation style's punctuation rules.     |
 
-**Prefer parentheses around `e.g.` and `i.e.` clauses.** The parentheses make the sentence structure obvious and avoid a cascade of commas around the abbreviation.
+**Prefer parentheses around `e.g.` and `i.e.` clauses.**
+The parentheses make the sentence structure obvious and avoid a cascade of commas around the abbreviation.
 
 **Do**:
 
@@ -261,7 +263,8 @@ Use them when they fit the sentence; the English equivalent is also fine.
 
 The **Don't** versions are grammatical, but the comma cascade makes the sentence structure harder to follow.
 
-**One period when `etc.` ends a sentence.** The period in `etc.` doubles as the sentence-ending period.
+**One period when `etc.` ends a sentence.**
+The period in `etc.` doubles as the sentence-ending period.
 
 **Do**:
 
@@ -280,15 +283,17 @@ The abbreviation's period closes `etc.`, the closing parenthesis follows, and th
 
 The same rule applies if `e.g.` or `i.e.` ever sits at the end of a sentence, though that placement is unusual.
 
-**Citation form for `et al.`** In an author-date citation, place a comma between the author phrase and the year, and keep the abbreviation's period.
+**Citation form for `et al.`**
+In an author-date citation, place a comma between the author phrase and the year, and keep the abbreviation's period.
 
 **Do**:
 
 > The protocol is described by Smith et al., 2020.
 >
 > The protocol is described by Smith et al. (2020).
 
-**Less common Latin abbreviations aren't allowed.** Latin abbreviations beyond the five in the table, such as `a priori`, `q.v.`, `viz.`, `n.b.`, `cf.`, and `ibid.`, are unfamiliar to many readers and easy to misuse.
+**Less common Latin abbreviations aren't allowed.**
+Latin abbreviations beyond the five in the table, such as `a priori`, `q.v.`, `viz.`, `n.b.`, `cf.`, and `ibid.`, are unfamiliar to non-specialist readers and invite misuse.
 Replace them with plain English.
 
 **Don't**:
@@ -303,7 +308,9 @@ Replace them with plain English.
 Major plain-language guides such as the [Google developer documentation style guide](https://developers.google.com/style/abbreviations), the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/abbreviations/), the [18F Content Guide](https://content-guide.18f.gov/our-style/inclusive-language/), and the [Plain Language Action and Information Network (PLAIN) federal guidance](https://www.plainlanguage.gov/guidelines/words/use-simple-words-phrases/) recommend English equivalents for all Latin abbreviations.
 The argument is that the abbreviations are unfamiliar to many readers and frequently misused (`i.e.` confused with `e.g.`).
 
-The Coder docs follow the spirit of that guidance for less common Latin but make an exception for `e.g.`, `i.e.`, `etc.`, `vs.`, and `et al.` These five are near-universal in industry technical writing; restricting them adds friction for writers without a clear payoff for readers familiar with the conventions of the genre.
+The Coder docs follow the spirit of that guidance for less common Latin but make an exception for `e.g.`, `i.e.`, `etc.`, `vs.`, and `et al.`
+These five are near-universal in industry technical writing.
+Restricting them burdens writers without a matching gain for readers familiar with the conventions of the genre.
 
 </details>
 
@@ -322,15 +329,15 @@ A page's H1 and its sidebar title serve different jobs and may diverge.
   The Coder docs site reads the sidebar title from the `title` field in [`docs/manifest.json`](../../manifest.json).
 
 The two must each stand alone, but they don't need to be identical.
-Breadcrumb depth gives one layer of context for free.
+Breadcrumb depth already supplies one layer of context.
 The sidebar title can drop redundancy that the parent breadcrumbs already imply.
 
 Worked example.
-A page reachable through **Administration** > **Authentication** > **Google** has parent breadcrumbs that already say "Administration" and "Authentication".
+A page reachable through **Administration** > **Authentication** > **Google** has parent breadcrumbs that already say "Administration" and "Authentication."
 The sidebar title can be `Google` alone, and the H1 can be `Configure Google authentication with Coder`.
 Both labels stand alone in their own context.
 
-When the H1 and the sidebar title coincide (often the case for short-titled pages), that's fine.
+When the H1 and the sidebar title coincide (common for short-titled pages), that's fine.
 When they diverge, the divergence is intentional and serves the reader.
 The same pattern is common in mature docs sites.
 AWS, Microsoft Learn, and GitHub Docs all pair task-focused H1s with shorter noun-focused sidebar titles.
@@ -424,7 +431,7 @@ A reading-level rule is part of [WCAG 2.1 Level AAA](https://www.w3.org/TR/WCAG2
 The criterion is satisfied either by writing at the lower-secondary reading level or by providing an alternative version.
 Coder docs write at the target reading level directly.
 
-Editors that surface a grade-level score (Hemingway, Vale's `write-good.Reading`) are a useful spot check.
+Editors that surface a grade-level score (Hemingway, Vale's `Readability.FleschKincaid`) are a useful spot check.
 The grade level isn't a hard ceiling.
 A reference page that requires technical vocabulary will read higher than a tutorial, and that's correct.
 
@@ -435,12 +442,12 @@ No Vale rule wired.*
 
 The docs site theme controls color contrast, not the prose written on each page.
 Tracked separately from this guide.
-The target is WCAG 2.1 Level AA for normal text (contrast ratio 4.5:1) and Level AA for large text (3:1), with AAA (7:1 normal, 4.5:1 large) as the stretch goal.
+The target is WCAG 2.1 Level AA for normal text (contrast ratio 4.5:1) and Level AA for large text (3:1), with AAA (7:1 normal, 4.5:1 large) as the further target.
 
 *Out of scope for this guide.
 Tracked by the docs site theme.*
 
-## Related
+## Learn more
 
 - [Style guide landing page](./README.md)
 - [Voice and tone](./voice-and-tone.md)