@redocly/recheck 0.9.0 → 0.11.0

package/README.md

@@ -58,77 +58,77 @@ pnpm build
 
 ```bash
 # Validate with explicit config file
-node dist/cli.js validate --config recheck.example.yaml
+node dist/cli.js --validate-config --config recheck.example.yaml
 
 # Auto-discover config file in current directory
-node dist/cli.js validate
+node dist/cli.js --validate-config
 ```
 
 ### Run content linting
 
 ```bash
 # Run on current directory
-node dist/cli.js run . --config recheck.example.yaml
+node dist/cli.js . --config recheck.example.yaml
 
 # Run on specific file
-node dist/cli.js run README.md --config recheck.example.yaml
+node dist/cli.js README.md --config recheck.example.yaml
 
 # Filter by severity (only show errors)
-node dist/cli.js run . --severity error
+node dist/cli.js . --severity error
 
 # Show all enabled rules (info and above)
-node dist/cli.js run . --severity info
+node dist/cli.js . --severity info
 
 # Work one rule at a time. This helps you clear a large list of findings.
 # Give the name that the report shows, or the full config key. Use the flag
 # more than one time for more than one rule. A rule from a namespace other
 # than `recheck/` keeps that namespace: use `google/passive-voice`.
-node dist/cli.js run . --rule semantic-line-breaks
-node dist/cli.js run . -r us-spelling -r recheck/oxford-comma
+node dist/cli.js . --rule semantic-line-breaks
+node dist/cli.js . -r us-spelling -r recheck/oxford-comma
 
 # ...and its inverse, to silence a rule you have already triaged
-node dist/cli.js run . --exclude-rule semantic-line-breaks
+node dist/cli.js . --exclude-rule semantic-line-breaks
 
 # Use --rule with --fix to clear one rule's findings across all documents
-node dist/cli.js run . --rule semantic-line-breaks --fix
+node dist/cli.js . --rule semantic-line-breaks --fix
 
 # A name that matches no rule in your config is an error, not an empty run:
 # a misspelled filter that reported "no issues" would look the same as a
 # clean document set. The error message lists the rules your config loaded.
 
 # Output formats (table is default)
-node dist/cli.js run . --output table           # Human-readable table (default)
-node dist/cli.js run . --output json            # Structured JSON for CI
-node dist/cli.js run . --output sarif           # SARIF format for security tools
-node dist/cli.js run . --output github-actions  # GitHub Actions annotations (inline PR comments)
+node dist/cli.js . --output table           # Human-readable table (default)
+node dist/cli.js . --output json            # Structured JSON for CI
+node dist/cli.js . --output sarif           # SARIF format for security tools
+node dist/cli.js . --output github-actions  # GitHub Actions annotations (inline PR comments)
 
 # Show detailed statistics
-node dist/cli.js run . --stats
+node dist/cli.js . --stats
 
 # Auto-fix safe issues (35 fixable rules total: swap + semantic-line-breaks
 # natively, plus 33 of the 53 markdownlint-parity rules — see the rule table
 # under "Markdownlint parity" below for the full per-rule breakdown)
-node dist/cli.js run . --fix
+node dist/cli.js . --fix
 
 # Combine auto-fix with statistics
-node dist/cli.js run . --fix --stats
+node dist/cli.js . --fix --stats
 
 # Limit annotations for CI (applies to file output, default: 20)
-node dist/cli.js run . --annotations-limit 50
+node dist/cli.js . --annotations-limit 50
 
 # Output to file (works with all formats)
-node dist/cli.js run . --output json --output-path report.json
-node dist/cli.js run . --output sarif --output-path recheck.sarif
-node dist/cli.js run . --output json --output-path limited.json --annotations-limit 50
+node dist/cli.js . --output json --output-path report.json
+node dist/cli.js . --output sarif --output-path recheck.sarif
+node dist/cli.js . --output json --output-path limited.json --annotations-limit 50
 
 # Emit run summary to a file (json or text)
-node dist/cli.js run . --summary json --summary-path recheck-summary.json
+node dist/cli.js . --summary json --summary-path recheck-summary.json
 
 # Scan only changed files (via file list or stdin)
 # From file:
-node dist/cli.js run . --changed-only --changed-list changed.txt
+node dist/cli.js . --changed-only --changed-list changed.txt
 # Or with stdin:
-git diff --name-only origin/main... | node dist/cli.js run . --changed-only
+git diff --name-only origin/main... | node dist/cli.js . --changed-only
 ```
 
 ## Library API
@@ -261,7 +261,7 @@ recheck/ul-style-dash:
 A baseline lets a team adopt recheck on a large document set with no cleanup project first: record the findings that exist today, then fail only on new ones.
 
 ```bash
-recheck baseline            # writes recheck-baseline.yaml next to your config
+recheck --generate-baseline            # writes recheck-baseline.yaml next to your config
 ```
 
 Activate it with one config line:
@@ -279,11 +279,11 @@ files:
     recheck/semantic-line-breaks: 3
 ```
 
-With the baseline active, `recheck run`:
+With the baseline active, `recheck`:
 
 - **suppresses** findings whose (file, rule) count matches the baseline, and reports how many matched;
 - **fails** when a count rises — the group's findings are printed with `(baseline 3, found 5)` context;
-- **fails** when a count falls, because the baseline is stale — the message says to run `recheck baseline` and commit the result.
+- **fails** when a count falls, because the baseline is stale — the message says to run `recheck --generate-baseline` and commit the result.
   Counts only step down, so the file equals reality at every green commit.
 
 Warnings are never baselined; they do not affect exit codes.
@@ -293,15 +293,15 @@ A renamed file is a new path with no budget, so its pre-existing findings report
 
 ## Readability
 
-`recheck readability` reports scores per file: Flesch reading ease, Flesch-Kincaid grade, Automated Readability Index (ARI), words, and sentences, plus medians.
+`recheck --readability` reports scores per file: Flesch reading ease, Flesch-Kincaid grade, Automated Readability Index (ARI), words, and sentences, plus medians.
 ARI is a grade level computed from exact character counts, with no syllable heuristic, which makes it steadier on technical vocabulary.
 It is score-shaped, not rule-shaped: it never gates and always exits 0 when it ran.
 To gate on a bound, use the `metric` assertion — both read the same prose and the same formulas, so they can never disagree.
 
 ```bash
-recheck readability docs
-recheck readability docs --output json
-recheck readability docs --changed-only < changed.txt   # score only listed files
+recheck docs --readability
+recheck docs --readability --output json
+recheck docs --readability --changed-only < changed.txt   # score only listed files
 ```
 
 The score reads flowing prose the way standard readability tools do: headings, code, and Markdoc tags are excluded, and every block ends a sentence.
@@ -414,7 +414,7 @@ Nothing in this file is linted at all, no matter where this comment sits.
 The five forms:
 
 | Directive | Effect |
-|---|---|
+| --- | --- |
 | `<!-- recheck-disable -->` | Disables **all** rules from this line to the end of the file, or until a matching `recheck-enable`. |
 | `<!-- recheck-disable rule… -->` | Disables only the **listed** rules from this line on (same end conditions). |
 | `<!-- recheck-enable -->` | Re-enables all rules (or, with rule names, only the listed ones) from this line on. |
@@ -437,7 +437,10 @@ Rules are defined using `assertions` that specify their behavior:
 
 #### Swap Assertions (`swap`)
 Text replacement with configurable options.
-**Fixable**: each match is replaced with its pair's value, with the matched text's own casing applied to the replacement -- an all-lowercase match inserts the replacement as configured, a Capitalized match capitalizes just the replacement's first word, and an ALL-CAPS match (2+ letters) uppercases the whole replacement; any other (mixed-case) casing is left as configured, since it carries no reliable intent to infer.
+**Fixable**: each match is replaced with its pair's value, with the matched text's own casing applied to the replacement --
+an all-lowercase match inserts the replacement as configured, a Capitalized match capitalizes just the replacement's first word,
+and an ALL-CAPS match (2+ letters) uppercases the whole replacement;
+any other (mixed-case) casing is left as configured, since it carries no reliable intent to infer.
 This matters most with `ignoreCase: true`: without it, a sentence-initial `'Behaviour'` would be fixed to literal `'behavior'`, silently lowercasing the start of the sentence -- with it, it fixes to `'Behavior'`.
 (With `keysAreRegex: true`, casing is inferred from the MATCHED text, not the regex key, so this applies uniformly to regex keys too.)
 When two pairs' matches overlap in the source (a compound key together with the shorter keys it contains), the longest match wins and is reported and fixed as one span.
@@ -505,7 +508,8 @@ The rule's `message` gets two positional `%s` substitutions, in this order: **1s
 Not fixable (detection-only): a count-based violation has no single match position to anchor an edit to.
 
 #### Repetition Assertions (`repetition`)
-Vale-parity `repetition` check: flags an adjacent repeated word — two tokens matching `pattern`, separated only by whitespace (which may include a single hard-wrap newline), so `'the theory'` is not flagged (different words) but `'the the'` and a hard-wrapped `'the\nthe rest'` are. **Fixable**: collapses the pair back to one occurrence, keeping the FIRST token's casing/text (so `'The the'` fixes to `'The'`, not `'the'`).
+Vale-parity `repetition` check: flags an adjacent repeated word — two tokens matching `pattern`, separated only by whitespace (which may include a single hard-wrap newline), so `'the theory'` is not flagged (different words) but `'the the'` and a hard-wrapped `'the\nthe rest'` are.
+**Fixable**: collapses the pair back to one occurrence, keeping the FIRST token's casing/text (so `'The the'` fixes to `'The'`, not `'the'`).
 
 ```yaml
 assertions:
@@ -525,7 +529,8 @@ Fix idempotency holds under repeated `--fix` passes: `'the the the'` converges t
 
 #### Consistency Assertions (`consistency`)
 Vale-parity `consistency` check: each `either` entry declares one alternative group — the key and the value are the two variants (both matched as literals with word boundaries, like `swap` keys).
-Whichever variant appears **first in the file (by source order)** wins file-wide; every later occurrence of the other variant is flagged. **Fixable**: each later occurrence is replaced with the winning variant **literally as written in `either`** — unlike `swap`, the losing match's own casing is not preserved here (with `ignoreCase: true`, a later `'Behaviour'` in a `behavior`-first document fixes to `'behavior'`).
+Whichever variant appears **first in the file (by source order)** wins file-wide; every later occurrence of the other variant is flagged.
+**Fixable**: each later occurrence is replaced with the winning variant **literally as written in `either`** — unlike `swap`, the losing match's own casing is not preserved here (with `ignoreCase: true`, a later `'Behaviour'` in a `behavior`-first document fixes to `'behavior'`).
 
 ```yaml
 assertions:
@@ -549,7 +554,8 @@ The rule's `message` gets two positional `%s` substitutions, in this order: **1s
 
 #### Conditional Assertions (`conditional`)
 Vale-parity `conditional` check: if `first` (a regex pattern) matches anywhere within the rule's scoped segments, `second` (a regex pattern) must exist **somewhere in the whole file** — checked against the full raw file content, not just the rule's own scope, so a `second` match sitting inside a code block still satisfies a rule scoped to `paragraph`.
-When `second` is absent file-wide, every `first` match becomes its own problem, at its exact source position. **Detection-only** (not fixable) — there is no single well-defined edit that would "introduce" `second`.
+When `second` is absent file-wide, every `first` match becomes its own problem, at its exact source position.
+**Detection-only** (not fixable) — there is no single well-defined edit that would "introduce" `second`.
 
 ```yaml
 assertions:
@@ -600,24 +606,31 @@ Unknown option keys, a missing/empty `match`, an invalid `style`, a non-string-a
   The compound's first part always capitalizes when the compound opens the title, and its last part always capitalizes when the compound closes the title — e.g. `the new state-of-the-art` → `The New State-of-the-Art` (changed from the original simplification by product decision during execution, 2026-07-27).
 - A word already in ALL-CAPS (2+ letters, e.g. an acronym like `API`) is left exactly as written.
 - **AP** (default) lowercases articles (`a`, `an`, `the`), coordinating conjunctions (`and`, `but`, `or`, `nor`, `for`, `so`, `yet`), and prepositions of **3 letters or fewer** (`at`, `by`, `in`, `of`, `off`, `on`, `out`, `to`, `up`, `via`).
-- **Chicago** lowercases the same articles/conjunctions, plus **every** preposition regardless of length (the short ones above, plus `about`, `above`, `across`, `after`, `against`, `along`, `among`, `around`, `before`, `behind`, `below`, `between`, `during`, `through`, `toward`, `under`, `until`, `with`, `within`, `without`) — e.g. Chicago lowercases `'...walking through the park'` → `'...walking through the Park'`, where AP capitalizes `Through`.
+- **Chicago** lowercases the same articles/conjunctions, plus **every** preposition regardless of length (the short ones above, plus `about`, `above`, `across`, `after`, `against`, `along`, `among`, `around`, `before`, `behind`, `below`, `between`, `during`, `through`, `toward`, `under`, `until`, `with`, `within`, `without`) —
+  e.g. Chicago lowercases `'...walking through the park'` → `'...walking through the Park'`, where AP capitalizes `Through`.
 
 **`$sentence`** — only the first word is capitalized; every other word is lowercased unless it's an `exceptions` entry (as-written) or already ALL-CAPS (left alone).
 
-**Word position counts a phrase exception as one word.** A *phrase* exception (one containing whitespace or a dot, like `Node.js` or `VS Code` — see the phrase-matching note above) is a single atomic token in the word sequence the `$`-styles case: it's emitted in its exact as-written form, and it **occupies a position**, so it never changes which word counts as first or last.
+**Word position counts a phrase exception as one word.**
+A *phrase* exception (one containing whitespace or a dot, like `Node.js` or `VS Code` — see the phrase-matching note above) is a single atomic token in the word sequence the `$`-styles case: it's emitted in its exact as-written form, and it **occupies a position**, so it never changes which word counts as first or last.
 With `exceptions: [VS Code]`, the already-correctly-cased heading `## VS Code actions for teams` produces no finding under `$sentence` (`actions` is the second word, not the first), and `## a guide to Node.js` becomes `## A Guide to Node.js` under `$title`/AP (`Node.js` is the last word, so `to` is a mid-title stopword and stays lowercase).
 Single-word exceptions (e.g. `GitHub`) behave as they always have — resolved by lookup rather than position.
 
-This used to be a bug, tracked as [Redocly/redocly#25610](https://github.com/Redocly/redocly/issues/25610) and fixed since: phrase exceptions were previously *masked out* of the text before word position was computed, which made a leading phrase promote the next word to sentence-initial under `$sentence` (`## VS Code actions for teams` was flagged, and under `fix: true` rewritten to `## VS Code Actions for teams`) and made a trailing phrase promote the preceding word to last-word position under `$title` (`a guide to Node.js` → `A Guide To Node.js`).
+This used to be a bug, tracked as [Redocly/redocly#25610](https://github.com/Redocly/redocly/issues/25610) and fixed since:
+phrase exceptions were previously *masked out* of the text before word position was computed, which made a leading phrase promote the next word to sentence-initial under `$sentence`
+(`## VS Code actions for teams` was flagged, and under `fix: true` rewritten to `## VS Code Actions for teams`)
+and made a trailing phrase promote the preceding word to last-word position under `$title` (`a guide to Node.js` → `A Guide To Node.js`).
 If you had worked around it by rephrasing headings or by swapping in a custom regex `match`, neither is needed any more.
 See `rules/scope/title-case.ts`'s `recaseWords` for the tokenization that replaced the masking.
 
 **`$lower`** / **`$upper`** — the whole segment must be all-lowercase / all-uppercase respectively; no exceptions/ALL-CAPS carve-out (unconditional, matching Vale's own `$lower`/`$upper`).
 
-**Custom regex** — the whole segment text must satisfy the pattern. **Detection-only**: unlike the four `$`-styles, a failing regex is flagged but never auto-fixed, even though the rule itself is registered fixable.
+**Custom regex** — the whole segment text must satisfy the pattern.
+**Detection-only**: unlike the four `$`-styles, a failing regex is flagged but never auto-fixed, even though the rule itself is registered fixable.
 Like `pattern`'s `tokens`, an invalid regex is caught and silently produces zero problems rather than crashing the run.
 
-**Inline code is frozen.** A backtick-delimited span in the segment text (e.g. a heading like ``'the `configFile` option'``) is treated like an exception: its content is never flagged or rewritten by any of the four `$`-styles, even if it would otherwise land on the first/last word.
+**Inline code is frozen.**
+A backtick-delimited span in the segment text (e.g. a heading like ``'the `configFile` option'``) is treated like an exception: its content is never flagged or rewritten by any of the four `$`-styles, even if it would otherwise land on the first/last word.
 
 **Fixable** for `$title`/`$sentence`/`$lower`/`$upper` only, one segment-wide edit per flagged segment.
 A **multi-line** segment (e.g. a soft-wrapped paragraph) is skipped entirely under these four styles — neither a problem nor a fix — since a `Fix` can only rewrite a single line; a custom regex `match` has no such restriction and still checks (and reports) multi-line segments, since it never produces a fix regardless of segment span.
@@ -642,16 +655,19 @@ assertions:
 
 Omitting both `min` and `max`, an unrecognized `formula`, or an unknown option key are all validation errors — a metric assertion with no bound can never report anything, and an unrecognized formula would otherwise reach the scoring engine's own exhaustive-switch failure at lint time instead of at config validation.
 
-**Always summary-scoped.** Unlike every other assertion above, `metric` does not honor a configurable `scope:` — readability is a property of the WHOLE document's prose, not something a selector could sensibly narrow (a readability score isn't meaningful for one paragraph in isolation the way an `occurrence` count is).
+**Always summary-scoped.**
+Unlike every other assertion above, `metric` does not honor a configurable `scope:` — readability is a property of the WHOLE document's prose, not something a selector could sensibly narrow (a readability score isn't meaningful for one paragraph in isolation the way an `occurrence` count is).
 Config validation forces every `metric` rule to `scope: summary`.
 Omit `scope` on a `metric` rule (or write `scope: summary` explicitly); configuring any other scope prints a warning (`metric is always summary-scoped; ignoring configured scope ...`) and applies `summary` behavior anyway.
 Text from overlapping segments (e.g. a list nested inside a blockquote) is deduplicated by source position, same as `consistency`/`conditional` above.
 
-**What the score reads.** The metric scores flowing prose the way standard readability tools do: `paragraph`, `list-item`, `blockquote`, `table.cell`, and `table.header` text counts; **headings are excluded**, and `code`, `frontmatter`, `html`, `comment`, `alt`, and `link` content is never counted.
+**What the score reads.**
+The metric scores flowing prose the way standard readability tools do: `paragraph`, `list-item`, `blockquote`, `table.cell`, and `table.header` text counts; **headings are excluded**, and `code`, `frontmatter`, `html`, `comment`, `alt`, and `link` content is never counted.
 Every block that does not end in terminal punctuation ends a sentence — an unpunctuated list item is one sentence, not a fragment fused into its neighbors.
 Without that rule, a run of bullets scored as one enormous "sentence" and pushed Flesch reading ease far below zero; with it, scores line up with other readability tools within syllable-heuristic differences.
 
-**Non-prose stripping.** Before scoring, each segment's text also has Markdoc tag-marker spans (`{% tag attr="x" %}`, `{% /tag %}`, and the `{%- ... -%}` trim variant) and backtick-delimited inline code spans stripped out — neither is readable prose, and both otherwise skew word/syllable counts.
+**Non-prose stripping.**
+Before scoring, each segment's text also has Markdoc tag-marker spans (`{% tag attr="x" %}`, `{% /tag %}`, and the `{%- ... -%}` trim variant) and backtick-delimited inline code spans stripped out — neither is readable prose, and both otherwise skew word/syllable counts.
 Prose between two block-tag markers still counts (only the marker spans themselves are removed); a paragraph consisting only of tag markers contributes nothing.
 Multi-backtick delimiters (`` ``like this`` ``) are handled conservatively as a simple open-run/close-run pair match, not a full CommonMark-correct implementation.
 
@@ -683,7 +699,8 @@ assertions:
 All options are optional — an empty `spelling: {}` is valid (default dictionary, no extra vocabulary, no ignore patterns, built-in vocabulary on).
 Unknown option keys, a non-string/empty-string `dictionary`, a `vocab`/`ignore` entry that isn't a non-empty string, or a non-boolean `builtinVocabulary` are all validation errors.
 
-**Optional peer dependencies — install to enable.** `nspell` and its default dictionary (`dictionary-en`) are **optional peer dependencies**: installing `@redocly/recheck` itself pulls in **neither**.
+**Optional peer dependencies — install to enable.**
+`nspell` and its default dictionary (`dictionary-en`) are **optional peer dependencies**: installing `@redocly/recheck` itself pulls in **neither**.
 Enable `spelling` with:
 
 ```bash
@@ -696,18 +713,21 @@ npm i nspell dictionary-en
 npm i nspell
 ```
 
-If a config enables `spelling` without the required peer(s) installed, `recheck validate` fails with an actionable error naming the exact command above — never a bare `Cannot find module 'nspell'` surfacing for the first time at lint time.
+If a config enables `spelling` without the required peer(s) installed, `recheck --validate-config` fails with an actionable error naming the exact command above — never a bare `Cannot find module 'nspell'` surfacing for the first time at lint time.
 
-**Dictionaries load lazily.** Neither `nspell` nor `dictionary-en` is imported unless some rule in your config actually has a `spelling` assertion — a config without one never touches either package, at either `validate` or lint time.
+**Dictionaries load lazily.**
+Neither `nspell` nor `dictionary-en` is imported unless some rule in your config actually has a `spelling` assertion — a config without one never touches either package, at either `validate` or lint time.
 The loaded speller (including the ~500KB parsed dictionary) is cached per dictionary source for the process's lifetime, so every file/rule sharing the same `dictionary` (or the shared default) reuses one instance rather than reloading it per call.
 
-**Word tokenization.** Words are matched with `/\p{L}+(?:['’]\p{L}+)?/gu` — Unicode letter runs, with an optional apostrophe-joined suffix so contractions (`don't`, `it's`) tokenize as one word.
+**Word tokenization.**
+Words are matched with `/\p{L}+(?:['’]\p{L}+)?/gu` — Unicode letter runs, with an optional apostrophe-joined suffix so contractions (`don't`, `it's`) tokenize as one word.
 A token is skipped (never checked) when it's in `vocab` (case-insensitively), matches any `ignore` pattern, is ALL-CAPS (2+ letters, e.g. an acronym) — matching the same ALL-CAPS carve-out `$title`/`$sentence` capitalization use — or is digit-adjacent (see below).
 Because `\p{L}` can never match a digit, a token touching one is never captured WHOLE by the tokenizer in the first place: a digit-adjacent identifier like `config2` still splits into a letter-only fragment (`config`) as its own regex match.
 Rather than checking that fragment like any other word, a digit-adjacency guard looks at the character immediately before and after each match and skips it when either neighbor is a digit — so common digit-bearing identifiers (`sha256` → `sha`, `utf8` → `utf`, `oauth2` → `oauth`, `es6` → `es`, `log4j` → both `log` and `j`, `2fast` → `fast`) are no longer flagged as false-positive misspellings.
 This mitigates, but doesn't eliminate, every false positive from the tokenizer's inability to capture digits at all — a token entirely surrounded by non-digit characters is still checked normally, so a genuine misspelling elsewhere in the same sentence is still flagged.
 
-**Code is never spell-checked, by construction of scope segmentation — not something this assertion special-cases.** A fenced or indented code block is its own `scope: 'code'` segment, entirely distinct from `paragraph`/`heading`/etc.; scoping `spelling` to prose (the common case, e.g. `scope: paragraph` or an array of prose scopes) means `ctx.segments` never contains one.
+**Code is never spell-checked, by construction of scope segmentation — not something this assertion special-cases.**
+A fenced or indented code block is its own `scope: 'code'` segment, entirely distinct from `paragraph`/`heading`/etc.; scoping `spelling` to prose (the common case, e.g. `scope: paragraph` or an array of prose scopes) means `ctx.segments` never contains one.
 A backtick-delimited **inline** code span, though, remains embedded as raw text inside a prose segment's own content (verified directly against the extractor) — those spans are masked out before tokenizing, the same length-preserving technique `capitalization`'s backtick-span freezing uses, so positions of any remaining flagged word stay exact.
 Scoping `spelling` to `all`/`raw` (or leaving `scope` at its default) checks the whole raw file, literal code included — same default-scope behavior every other native assertion (`swap`, `pattern`, ...) has.
 
@@ -726,18 +746,23 @@ It exists so a config that turns on sentence-case headings or spelling doesn't i
 - Your own `exceptions`/`vocab` on the same rule **compose** with the built-ins rather than replacing them — unlike a preset-shipped list on the same rule key, which a same-key override *would* replace entirely (see [`extends` presets](#extends-presets) above).
   This is exactly how [`recheck/prose`](#extends-presets)'s `capitalization` rule gets its protection for common technical nouns without shipping any `exceptions` of its own.
 
-**Multi-token entries work.** An entry containing a dot or whitespace (`Node.js`, `VS Code`, `Visual Studio Code`, `GitHub Actions`, `Google Cloud`, `Azure DevOps`) is matched by `capitalization` as a whole phrase against the segment text (longest-match-first, case-insensitive but otherwise literal) and preserved verbatim — not looked up per word, which is what a single-token entry like `GitHub` still gets.
+**Multi-token entries work.**
+An entry containing a dot or whitespace (`Node.js`, `VS Code`, `Visual Studio Code`, `GitHub Actions`, `Google Cloud`, `Azure DevOps`) is matched by `capitalization` as a whole phrase against the segment text (longest-match-first, case-insensitive but otherwise literal) and preserved verbatim — not looked up per word, which is what a single-token entry like `GitHub` still gets.
 
 **Inclusion bar** (why an entry is — or isn't — in the list, and the bar to clear before proposing one): an entry qualifies if it's an unambiguous technology, product, or company name whose exception listing wouldn't *weaken* capitalization/spelling checks — concretely, its lowercase form must not be a legitimate English word in its own right.
 That covers ordinary Title-Case brand names (`Android`, `Kubernetes`, `Redocly`) just as much as entries with an internal capital (`OpenAPI`, `GraphQL`), a dot (`Node.js`), or forced lowercase (`npm`) — `$sentence` lowercases every non-first word regardless of how "ordinary" its casing looks, so plain Title-Case names need protection too.
 Excluded, deliberately:
 - **Pure ALL-CAPS acronyms** (`JWT`, `YAML`) — already handled structurally by the ALL-CAPS carve-out both `capitalization` and `spelling` apply, so listing them adds maintenance for no behavior change.
   Note this is narrower than "looks like an acronym": `OAuth` and `AsyncAPI` are mixed-case, not pure ALL-CAPS, and are in the list.
-- **Terms with legitimate lowercase prose usage** — generic English (`cloud`, `apps`), words that are ALSO ordinary English words even though they're Redocly product names too (`Realm`, `Replay`, `Respect` — listing them would force-capitalize ordinary usage like "we respect your privacy"; `Node` — the common technical noun, superseded by the `Node.js` phrase entry for the platform specifically), and — caught by a later audit, not the original pass — ordinary brand-shaped words with a real dictionary meaning (`Chrome`, `Markdown`, `Postman`, `Prettier`, `Safari`, `Swagger`, `Windows`; see `src/data/proper-nouns.ts`'s header for each one's disqualifying lowercase usage).
+- **Terms with legitimate lowercase prose usage** — generic English (`cloud`, `apps`),
+  words that are ALSO ordinary English words even though they're Redocly product names too (`Realm`, `Replay`, `Respect` — listing them would force-capitalize ordinary usage like "we respect your privacy"; `Node` — the common technical noun, superseded by the `Node.js` phrase entry for the platform specifically),
+  and — caught by a later audit, not the original pass — ordinary brand-shaped words with a real dictionary meaning (`Chrome`, `Markdown`, `Postman`, `Prettier`, `Safari`, `Swagger`, `Windows`; see `src/data/proper-nouns.ts`'s header for each one's disqualifying lowercase usage).
   A few real dictionary words (`Android`, `Docker`, `TypeScript`) were judged rare enough in ordinary lowercase usage to keep anyway — a documented, deliberate risk-acceptance, not an oversight.
   List your own such names in your rule's own `exceptions`/`vocab`, which compose with this list as described above.
 
-Two automated tests in `src/data/__tests__/proper-nouns.test.ts` enforce this: one checks every entry's shape against the bar above — no pure ALL-CAPS, and, mechanically, no single-token entry whose lowercase form the REAL spelling dictionary (`dictionary-en`/`nspell`, the same pair `spelling` loads at runtime) accepts as a legitimate English word, unless it's named in an explicit accepted-risk allowlist — plus alphabetization and no duplicates.
+Two automated tests in `src/data/__tests__/proper-nouns.test.ts` enforce this:
+one checks every entry's shape against the bar above — no pure ALL-CAPS, and, mechanically, no single-token entry whose lowercase form the REAL spelling dictionary (`dictionary-en`/`nspell`, the same pair `spelling` loads at runtime) accepts as a legitimate English word, unless it's named in an explicit accepted-risk allowlist —
+plus alphabetization and no duplicates.
 A round-trip guard separately drives every entry through the real `capitalization` and `spelling` rules and fails the suite if any entry can't actually be protected — the list can't silently regress into decoration.
 
 #### Length Assertions (`length`)
@@ -772,7 +797,9 @@ Beyond `swap`, `pattern`, `occurrence`, `repetition`, `consistency`, `conditiona
 - `semantic-line-breaks` - Semantic line break validation ✅ **Fixable**
 - `max-image-size` - Oversized image detection
 
-Three of the assertions above (`repetition`, `consistency`, `capitalization`) are bundled, pre-configured, in the [`recheck/prose`](#extends-presets) preset, and `capitalization`/`length` are also used by [`recheck/google`](#extends-presets) (sentence-case headings and list items, and a sentence-length cap); the remaining four (`occurrence`, `conditional`, `metric`, `spelling`) are documented [opt-ins](#opt-in-prose-assertions) with copy-paste snippets, not shipped in any preset by default.
+Three of the assertions above (`repetition`, `consistency`, `capitalization`) are bundled, pre-configured, in the [`recheck/prose`](#extends-presets) preset,
+and `capitalization`/`length` are also used by [`recheck/google`](#extends-presets) (sentence-case headings and list items, and a sentence-length cap);
+the remaining four (`occurrence`, `conditional`, `metric`, `spelling`) are documented [opt-ins](#opt-in-prose-assertions) with copy-paste snippets, not shipped in any preset by default.
 
 ### Recheck-original structural rules
 
@@ -788,7 +815,7 @@ The other two — `markdoc-unknown-tag` and
 the [`recheck/markdoc`](#extends-presets) preset instead.
 
 | Rule | Flags | Why |
-|---|---|---|
+| --- | --- | --- |
 | `no-empty-headings` | A heading whose text content is empty (a bare `#`, or markup that renders to nothing such as `## <span></span>`) | An empty heading still lands in the document outline and in screen-reader heading navigation. Inline code counts as content, so `` # `config.yaml` `` is fine. |
 | `no-duplicate-link-destinations` | The second and later links to one destination when the link **text** differs from the first occurrence's | Screen-reader users listing a page's links hear one target described inconsistently; the texts also drift apart over time. Repeating the *same* text for the same destination is ordinary prose and is not flagged. Resolves reference links through their definition. |
 | `list-length` | A list (ordered or unordered) with fewer than `min` items (default 2) or more than `max` items (no default — unbounded unless set) | A single-item list usually reads better as a plain sentence, and a very long list asks readers to hold too many parallel items in mind. Every list is evaluated independently, including nested sublists — a short sublist is flagged even when its parent list is long enough. |
@@ -924,7 +951,7 @@ markdoc:
 - **`extend.tagsFile`** — the same tag-definition surface as `extend.tags`, but sourced from
   a separate YAML file instead of written inline into `recheck.yaml`.
   This is the shape
-  [`recheck markdoc-schema`](#generate-a-tagsfile-recheck-markdoc-schema) below generates,
+  [`recheck --generate-markdoc-schema`](#generate-a-tagsfile-recheck---generate-markdoc-schema) below generates,
   so a project with tags defined in TypeScript (a `@theme/markdoc/schema.ts` module, say)
   never hand-transcribes them into YAML.
   ```yaml
@@ -942,20 +969,27 @@ markdoc:
     `extend.tags` above).
     `tags` and `tagsFile` can both be set on the same `extend` block;
     `extend` with neither key is rejected by config validation as a likely no-op.
-  - **Errors are fatal to the whole run, not a silent markdoc downgrade.** A `tagsFile` that
+  - **Errors are fatal to the whole run, not a silent markdoc downgrade.**
+    A `tagsFile` that
     doesn't exist, isn't valid YAML, isn't a YAML map, or contains a tag entry with an
-    invalid shape all fail `recheck run`/`recheck validate` outright
+    invalid shape all fail `recheck`/`recheck --validate-config` outright
     (`Configuration validation failed!`, the same failure every other structurally-invalid
     config produces) — markdoc checking is never quietly switched off while the rest of the
     config keeps running.
 
 Turning `markdoc` on (either form) changes how every prose rule sees a Markdoc tag, not just `markdoc.tag` (above):
 
-- **Prose scopes exclude the tag itself.** `paragraph`, `heading`, `list-item`, `blockquote`, and `table.header`/`table.cell` all blank a tag's own `{% ... %}` span out of their content before any rule runs — a `swap`/`pattern`/`capitalization` match can't fire on the tag's syntax, and a `length`/`metric` count doesn't include it.
+- **Prose scopes exclude the tag itself.**
+  `paragraph`, `heading`, `list-item`, `blockquote`, and `table.header`/`table.cell` all blank a tag's own `{% ... %}` span out of their content before any rule runs — a `swap`/`pattern`/`capitalization` match can't fire on the tag's syntax, and a `length`/`metric` count doesn't include it.
   The blanking is position-preserving (same-width spaces, never a deletion), so real text on either side of a tag keeps its exact line and column.
-- **A segment with no prose left isn't emitted at all.** A heading or table cell whose entire text IS a tag (`# {% #anchor %}`) produces no `heading.h1`/`table.cell` segment — there's nothing for a heading or cell rule to check, so none fires on it.
-- **`--fix` never rewrites a Markdoc tag's bytes.** Every proposed fix is checked against the document's tag spans before it's applied: one that doesn't touch a tag goes through untouched, one that fully covers a tag with a same-length replacement gets the tag spliced back in, and anything that would change a tag's length or split it in half is withheld instead — a withheld fix is reported (`skippedFixes` in the [Library API](#library-api)), not silently swallowed.
-- **Two CommonMark constructs Markdoc doesn't have stop being recognized.** Markdoc's own tokenizer disables indented code blocks and setext headings (the `Title\n===\n` underline form) unconditionally, which is how Realm renders, so `markdoc: true` disables them too — and only while the flag is on:
+- **A segment with no prose left isn't emitted at all.**
+  A heading or table cell whose entire text IS a tag (`# {% #anchor %}`) produces no `heading.h1`/`table.cell` segment — there's nothing for a heading or cell rule to check, so none fires on it.
+- **`--fix` never rewrites a Markdoc tag's bytes.**
+  Every proposed fix is checked against the document's tag spans before it's applied:
+  one that doesn't touch a tag goes through untouched, one that fully covers a tag with a same-length replacement gets the tag spliced back in,
+  and anything that would change a tag's length or split it in half is withheld instead — a withheld fix is reported (`skippedFixes` in the [Library API](#library-api)), not silently swallowed.
+- **Two CommonMark constructs Markdoc doesn't have stop being recognized.**
+  Markdoc's own tokenizer disables indented code blocks and setext headings (the `Title\n===\n` underline form) unconditionally, which is how Realm renders, so `markdoc: true` disables them too — and only while the flag is on:
   - A 4+-space-indented block that would otherwise be an indented code block parses as ordinary content instead: a paragraph, list, or fence, whichever the un-indented text would have produced.
     This shows up most with a block-positioned tag followed immediately by more indented lines, and with genuinely indented example text.
     Realm renders both as prose, so matching that is the intent.
@@ -965,7 +999,7 @@ Turning `markdoc` on (either form) changes how every prose rule sees a Markdoc t
   - Practical effect: on documents using either construct, expect `heading-style`, `blanks-around-headings`, `capitalization`, and `code-block-style` findings to shift when you first turn the flag on.
     They are moving to match how Markdoc actually renders, not regressing.
 
-### Generate a tagsFile: `recheck markdoc-schema`
+### Generate a tagsFile: `recheck --generate-markdoc-schema`
 
 Projects that define their own Markdoc tags in TypeScript — a `@theme/markdoc/schema.ts`
 module exporting a `tags` map, the shape both `docs/realm` and `docs/intranet` use in this
@@ -973,7 +1007,7 @@ monorepo — can generate an `extend.tagsFile` YAML file from it instead of hand
 each tag's schema:
 
 ```bash
-recheck markdoc-schema --from path/to/schema.ts --out recheck-markdoc-tags.yaml
+recheck --generate-markdoc-schema --from path/to/schema.ts --out recheck-markdoc-tags.yaml
 ```
 
 - **`--from <path>`** (repeatable) — a project schema module to extract tags from, resolved
@@ -997,13 +1031,14 @@ recheck markdoc-schema --from path/to/schema.ts --out recheck-markdoc-tags.yaml
   This is what a CI drift
   check should call — see this repo's own wiring below.
 
-**TypeScript sources need a loader.** `recheck markdoc-schema` dynamic-`import()`s each
+**TypeScript sources need a loader.**
+`recheck --generate-markdoc-schema` dynamic-`import()`s each
 `--from` module directly; running the command under plain `node` against a `.ts` module
 fails with an actionable one-line error naming the fix, rather than a raw stack trace:
 
-```
+```text
 could not import "path/to/schema.ts" — TypeScript sources need a loader, e.g.: pnpm exec tsx
-node_modules/.bin/recheck markdoc-schema … (Cannot find module '<a module your schema
+node_modules/.bin/recheck --generate-markdoc-schema … (Cannot find module '<a module your schema
 imports>' imported from '<path to your schema.ts>')
 ```
 
@@ -1017,12 +1052,13 @@ Run it through `tsx` instead (directly, or via a package script that already wra
 this repo's `recheck:markdoc-tags` below) — a plain `.js` schema module needs no loader and
 works under either.
 
-**Experimental, pending a canonical manifest.** This command is an interim bridge, not a
+**Experimental, pending a canonical manifest.**
+This command is an interim bridge, not a
 long-term source of truth: [issue #25666](https://github.com/Redocly/redocly/issues/25666)
 tracks Realm itself emitting one canonical, statics-only Markdoc tag/schema manifest, which
 would let this generator (and its drift check) retire in favor of reading that manifest
 directly.
-Until then, `recheck markdoc-schema` is the supported way to keep a project's
+Until then, `recheck --generate-markdoc-schema` is the supported way to keep a project's
 `tagsFile` in sync with its real tag schema modules.
 
 #### Worked example: this repo's own setup
@@ -1040,10 +1076,10 @@ markdoc:
 The committed `recheck-markdoc-tags.yaml` is generated, not hand-written — its header names
 the exact regenerate command:
 
-```
+```yaml
 # Generated file — do not hand-edit.
 # Source module(s): ../../docs/realm/@theme/markdoc/schema.ts, ../../docs/intranet/@theme/markdoc/schema.ts
-# Regenerate: recheck markdoc-schema --from ../../docs/realm/@theme/markdoc/schema.ts --from ../../docs/intranet/@theme/markdoc/schema.ts --out ../../recheck-markdoc-tags.yaml
+# Regenerate: recheck --generate-markdoc-schema --from ../../docs/realm/@theme/markdoc/schema.ts --from ../../docs/intranet/@theme/markdoc/schema.ts --out ../../recheck-markdoc-tags.yaml
 ```
 
 The root `package.json` wraps that same invocation in one script, run from
@@ -1054,9 +1090,10 @@ pnpm run recheck:markdoc-tags            # regenerate recheck-markdoc-tags.yaml
 pnpm run recheck:markdoc-tags --check    # verify it's current; exits 1 on drift
 ```
 
-**Do not add `--` before `--check`.** `pnpm run recheck:markdoc-tags -- --check` looks
+**Do not add `--` before `--check`.**
+`pnpm run recheck:markdoc-tags -- --check` looks
 equivalent but isn't: the script itself already ends in `pnpm --filter @redocly/recheck exec
-tsx dist/cli.js markdoc-schema …`, and pnpm's own `--` forwarding through that nested `exec`
+tsx dist/cli.js --generate-markdoc-schema …`, and pnpm's own `--` forwarding through that nested `exec`
 makes yargs read `--check` as a positional argument instead of the `--check` flag — the
 command then silently regenerates the file and always exits `0`, defeating the whole point
 of a drift check.
@@ -1187,7 +1224,9 @@ A rule may attach a milder severity to some of its own reports, and your config
   Equivalent to markdownlint's `{ default: true }`.
 - **`recheck/markdown-relaxed`** — mirrors markdownlint's own `style/relaxed.json`: the same 53 rules, with `no-trailing-spaces`, `no-hard-tabs`, `no-multiple-blanks`, `no-multiple-space-blockquote`, `no-blanks-blockquote`, `line-length`, `ul-indent`, `no-inline-html`, `no-bare-urls`, `fenced-code-language`, and `first-line-h1` turned off.
 - **`recheck/minimal`** — a small, high-signal set: `no-trailing-spaces`, `no-hard-tabs`, `single-trailing-newline`, `no-reversed-links`, `no-empty-links`.
-- **`recheck/prose`** — Recheck's Vale-parity starter set, all at `severity: warn`: `repetition` (default options), `consistency` (one US spelling enforced file-wide for `behavior`/`color`/`license`/`organize` vs. their British spellings, matched with `ignoreCase: true` so a capitalized, sentence-initial variant like `Colour` still counts), and `capitalization` (`$sentence`, `scope: heading` only, `fix: false`, no preset-level `exceptions` — see below).
+- **`recheck/prose`** — Recheck's Vale-parity starter set, all at `severity: warn`: `repetition` (default options),
+  `consistency` (one US spelling enforced file-wide for `behavior`/`color`/`license`/`organize` vs. their British spellings, matched with `ignoreCase: true` so a capitalized, sentence-initial variant like `Colour` still counts),
+  and `capitalization` (`$sentence`, `scope: heading` only, `fix: false`, no preset-level `exceptions` — see below).
   All three are scoped to prose segments — `repetition` and `consistency` to `summary` (the document's prose: paragraph, heading, list-item, blockquote, and table-cell text), `capitalization` to headings — so the preset never flags (and `--fix` never rewrites) code samples or frontmatter.
   `extends: [recheck/markdown, recheck/prose]` is the one-liner that replaces a markdownlint + Vale combo.
   See [Opt-in prose assertions](#opt-in-prose-assertions) below for three more prose assertions that exist but are deliberately **not** in this preset.
@@ -1200,27 +1239,39 @@ A rule may attach a milder severity to some of its own reports, and your config
     That `warn` is set per report by the rule itself, so it wins over the rule's configured severity: setting the rule to `severity: error` does not escalate those reports.
     Only `severity: 'off'` removes them, by disabling the rule.
 
-  **These rules only fire when Markdoc tokenization is also on.** Set `markdoc: true` (or the object form, see below) alongside `extends: [recheck/markdoc]`.
+  **These rules only fire when Markdoc tokenization is also on.**
+  Set `markdoc: true` (or the object form, see below) alongside `extends: [recheck/markdoc]`.
   Extending the preset without the flag validates, but prints a console warning that the four rules can never report.
   The flag stays an explicit opt-in because Liquid and Jinja templates use the same `{% %}` delimiters for unrelated syntax, so Recheck never assumes it.
-- **`recheck/google`** — Google's developer documentation style guide (https://developers.google.com/style), CC BY 4.0, synced 2026-07-29. 99 rules covering heading/list/table/link structure, sentence-case headings, sentence length, voice and contractions, plain language, product naming, compound word forms, and inclusive/precise-language terminology — all derived from the *live* guide (see `packages/recheck/presets/google/PROVENANCE.md` for the rule -> source page -> quote -> verdict table, including everything considered and NOT shipped, and why).
+- **`recheck/google`** — Google's developer documentation style guide (https://developers.google.com/style), CC BY 4.0, synced 2026-07-29.
+  99 rules covering heading/list/table/link structure, sentence-case headings, sentence length, voice and contractions, plain language, product naming, compound word forms, and inclusive/precise-language terminology —
+  all derived from the *live* guide (see `packages/recheck/presets/google/PROVENANCE.md` for the rule -> source page -> quote -> verdict table, including everything considered and NOT shipped, and why).
   `extends: [recheck/google]` is a one-line adoption of Google's style; combine with `recheck/markdown` for full structural linting too.
   Rule ids are namespaced `google/<rule>` (not `recheck/<rule>`) so they never collide with the markdownlint-parity or other style-guide presets.
   Structural/mechanical rules (heading hierarchy, list mechanics, alt-text presence, sentence length) are `severity: error`; every word-choice, terminology, and punctuation-convention rule is `severity: warn`.
-  See `packages/recheck/presets/google/sources.json` for the fetched-page hashes. **Adopting this preset has a real, measured performance cost — roughly 2.7× the standard `recheck/markdown`-only profile's lint time on a docs-sized document set** — see [Performance](#performance) below (Phase 4) before turning it on in CI.
-- **`recheck/microsoft`** — the Microsoft Writing Style Guide (https://learn.microsoft.com/en-us/style-guide/welcome/), CC BY 4.0 (via the guide's backing GitHub repository's LICENSE file — no `learn.microsoft.com` page states the licence itself, see `packages/recheck/presets/microsoft/PROVENANCE.md`), synced 2026-07-30. 93 rules covering heading/list/table/alt-text structure, the guide's own numeric thresholds (paragraph length, list length, comma density, alt-text length), its signature "use contractions" rule, US spelling, bias-free and people-first terminology, and a large A-Z terminology word list — all derived from the *live* guide and checked against four independent verification passes (~490 rules/entries across ~340 page fetches), with every Tier-1 pair anchored or demoted to detection-only wherever it was found capable of rewriting correct prose.
+  See `packages/recheck/presets/google/sources.json` for the fetched-page hashes.
+  **Adopting this preset has a real, measured performance cost — roughly 2.7× the standard `recheck/markdown`-only profile's lint time on a docs-sized document set** — see [Performance](#performance) below (Phase 4) before turning it on in CI.
+- **`recheck/microsoft`** — the Microsoft Writing Style Guide (https://learn.microsoft.com/en-us/style-guide/welcome/), CC BY 4.0 (via the guide's backing GitHub repository's LICENSE file — no `learn.microsoft.com` page states the licence itself, see `packages/recheck/presets/microsoft/PROVENANCE.md`), synced 2026-07-30.
+  93 rules covering heading/list/table/alt-text structure, the guide's own numeric thresholds (paragraph length, list length, comma density, alt-text length), its signature "use contractions" rule, US spelling, bias-free and people-first terminology, and a large A-Z terminology word list —
+  all derived from the *live* guide and checked against four independent verification passes (~490 rules/entries across ~340 page fetches), with every Tier-1 pair anchored or demoted to detection-only wherever it was found capable of rewriting correct prose.
   Rule ids are namespaced `microsoft/<rule>`.
   Structural rules and the A-Z word list's three unconditional tiers are `severity: error`; voice, punctuation-convention, and UI-terminology rules are `severity: warn`.
   Audience-conditional and UI-conditional entries (Microsoft's own "Tier 4") are never enforced, and developer-audience carve-outs relevant to API documentation (`header`, `context menu`, `disk`, `directory`) are excluded rather than misfiring on Redocly's own docs — see `packages/recheck/presets/microsoft/PROVENANCE.md` for the full table, every excluded candidate, and why.
   Unlike `recheck/google` (which allows `click`), this preset bans all input-specific UI verbs (`click`, `press`, `hit`) in favor of `select` — the sharpest divergence between the two guides.
   See `packages/recheck/presets/microsoft/sources.json` for the fetched-page hashes.
-- **`recheck/inclusive-language`** — composable, guide-agnostic: the *intersection* of `recheck/google` and `recheck/microsoft`'s inclusive/bias-free/ableist/accessibility content — terminology both flagship guides independently state should be avoided (`slave`, `master/slave`, `blacklist`/`whitelist`, `DMZ`, `grayed-out`, `he/she`, `normal person`/`healthy person`, `suffering from`/`victim of`, `differently abled`, `crippled`, `nuke`).
+- **`recheck/inclusive-language`** — composable, guide-agnostic: the *intersection* of `recheck/google` and `recheck/microsoft`'s inclusive/bias-free/ableist/accessibility content —
+  terminology both flagship guides independently state should be avoided (`slave`, `master/slave`, `blacklist`/`whitelist`, `DMZ`, `grayed-out`, `he/she`, `normal person`/`healthy person`, `suffering from`/`victim of`, `differently abled`, `crippled`, `nuke`).
   All `warn` severity, all detection-only.
   Needed no new web fetch — every term was already confirmed against a live page by five existing verification reports; see `packages/recheck/presets/inclusive-language/PROVENANCE.md` for the report → row → term table and every single-guide term left out on purpose.
-  Layer it onto either flagship or onto `recheck/prose`: `extends: [recheck/google, recheck/inclusive-language]`. **Because it's built as an intersection, every one of its 11 rules is already shipped by at least one flagship's own preset** (measured: 7 of 11 duplicate a `google/*` finding on the same span when stacked onto `recheck/google` alone, 6 of 11 duplicate a `microsoft/*` finding when stacked onto `recheck/microsoft` alone — see `packages/recheck/presets/inclusive-language/PROVENANCE.md`'s "Duplicate-finding audit").
+  Layer it onto either flagship or onto `recheck/prose`: `extends: [recheck/google, recheck/inclusive-language]`.
+  **Because it's built as an intersection, every one of its 11 rules is already shipped by at least one flagship's own preset**
+  (measured: 7 of 11 duplicate a `google/*` finding on the same span when stacked onto `recheck/google` alone, 6 of 11 duplicate a `microsoft/*` finding when stacked onto `recheck/microsoft` alone — see `packages/recheck/presets/inclusive-language/PROVENANCE.md`'s "Duplicate-finding audit").
   Its full, zero-duplicate value is realized standalone, with `recheck/prose`, or on a project using neither flagship; stacked onto exactly one flagship it still fills that flagship's own gaps, but expect a majority of its findings to be reported twice.
 - **`recheck/plain-language`** — composable, derived from the *live* US federal plain-language guidance (`digital.gov/guides/plain-language`; public domain, no attribution constraint).
-  Smaller than a first read of the old `plainlanguage.gov` site would suggest: that site is now dead and redirects to a much thinner overview, so there's no sentence-length or readability-`metric` rule (`metric` stays a documented [opt-in](#opt-in-prose-assertions), unchanged) — only paragraph length (the one family with real, quotable numbers), filler/wordy phrases, complex-word substitutes, redundant pairs, double negatives, and jargon-to-plain examples. **`shall` is never flagged** — it's a defined RFC 2119 normative keyword used throughout specs and API docs, exactly what Recheck lints; `implement` and `command` carry the identical technical-sense collision and are excluded the same way.
+  Smaller than a first read of the old `plainlanguage.gov` site would suggest:
+  that site is now dead and redirects to a much thinner overview, so there's no sentence-length or readability-`metric` rule (`metric` stays a documented [opt-in](#opt-in-prose-assertions), unchanged) —
+  only paragraph length (the one family with real, quotable numbers), filler/wordy phrases, complex-word substitutes, redundant pairs, double negatives, and jargon-to-plain examples.
+  **`shall` is never flagged** — it's a defined RFC 2119 normative keyword used throughout specs and API docs, exactly what Recheck lints; `implement` and `command` carry the identical technical-sense collision and are excluded the same way.
   All `warn`/`error` (paragraph-length ceiling only) severity, all detection-only.
   `in order to` and `utilize`/`utilization` are deliberately NOT shipped despite being live, verbatim guide content — both flagships already ship the identical pair, so keeping them here would only ever produce a duplicate finding, never new coverage (measured: this cut duplicate findings on the same fixture from 6 to 3 against `recheck/google`, and from 5 to 3 against `recheck/microsoft`).
   The 3 that remain are an accepted paragraph-length overlap with `recheck/microsoft` (two independently-sourced numbers, not the same fact restated) and a coincidental substring collision with `use-contractions`, not content duplication.
@@ -1326,7 +1377,7 @@ microsoft/spelling-hyphenation:
 
 drops the preset's whole `pairs` map along with it, and the config then fails validation outright (verified against this exact rule on a live build):
 
-```
+```text
 Rule "microsoft/spelling-hyphenation": swap requires a "pairs" object mapping find -> replace strings
 ```
 
@@ -1336,14 +1387,18 @@ A per-term opt-out for `swap`/`pattern` is a known follow-up, not shipped yet.
 
 ### Example configs
 
-`packages/recheck/examples/{google,microsoft,inclusive-language,plain-language}.yaml` are ready-to-copy configs for the four style-guide presets, generated by `pnpm examples:generate` (`packages/recheck/scripts/generate-examples.mjs`) so they can never drift from the preset they document — a test (`src/config/__tests__/examples-drift.test.ts`) byte-compares each on-disk file against a fresh render and fails, naming the file, if either the preset or the file's own hand-maintained appendix (`examples/appendices/<name>.appendix.yaml`) changes without regenerating.
+`packages/recheck/examples/{google,microsoft,inclusive-language,plain-language,technical-english}.yaml` are ready-to-copy configs for the five style presets,
+generated by `pnpm examples:generate` (`packages/recheck/scripts/generate-examples.mjs`) so they can never drift from the preset they document —
+a test (`src/config/__tests__/examples-drift.test.ts`) byte-compares each on-disk file against a fresh render and fails, naming the file, if either the preset or the file's own hand-maintained appendix (`examples/appendices/<name>.appendix.yaml`) changes without regenerating.
 
 Each file has four parts, in this order:
 
 1. **An attribution header** — source, license, and sync date, as YAML comments (mirrors that preset's `PROVENANCE.md`).
 2. **`# What to paste`** — the actual adoption cost: a two-to-four-line `extends` block.
    This is the only part most readers need; everything below it is supporting material, not something to copy.
-3. **`# How to tune it`** — override patterns verified to work today (turn a rule off, downgrade its severity, inline-disable one occurrence with an HTML comment), plus a documented sharp edge: overriding one option on a bundled `swap`/`pattern` rule's `assertions` **replaces that assertion entirely**, silently discarding options like a `pairs` map you didn't restate (merging is per *assertion id*, not per option) — restate the whole map, turn the rule off, or use an inline directive instead.
+3. **`# How to tune it`** — override patterns verified to work today (turn a rule off, downgrade its severity, inline-disable one occurrence with an HTML comment),
+   plus a documented sharp edge: overriding one option on a bundled `swap`/`pattern` rule's `assertions` **replaces that assertion entirely**, silently discarding options like a `pairs` map you didn't restate (merging is per *assertion id*, not per option) —
+   restate the whole map, turn the rule off, or use an inline directive instead.
    `capitalization`'s `exceptions` and `spelling`'s `ignore` are the two assertion types that already have a real per-term escape hatch; an equivalent for `swap`/`pattern` is a known follow-up, not shipped yet.
 4. **`# Full expansion (reference)`** — the preset's entire resolved rule set (alphabetized), so a reader can see exactly what they're adopting without running the tool.
    Every value here is identical to what the `extends` block above already resolves to, so copying this section too is redundant, not broken — it's for reading, not pasting.
@@ -1354,7 +1409,8 @@ A hand-maintained appendix is appended verbatim after part 4: NOISY candidates t
 
 `recheck/prose` (above) intentionally ships only `repetition`, `consistency`, and `capitalization` — a small, broadly-applicable default.
 Three more Vale-parity/native assertions exist (see [Assertion Types](#assertion-types) above for full per-option tables) but are **not shipped in any preset**, because their thresholds, patterns, or dictionaries are inherently project-specific rather than having one right-for-everyone default: `conditional`, `metric`, `spelling`.
-(`length` and `occurrence` used to be entries here; neither is an opt-in any more — [`recheck/google`](#extends-presets) ships `length` directly for the guide's sentence-length limit, and [`recheck/microsoft`](#extends-presets) ships `occurrence` directly for the guide's comma-density rule, so neither one's default bounds are "no one right answer" any more.) Add any of the three by copying its rule below into your own config, alongside `extends: [recheck/prose]`:
+(`length` and `occurrence` used to be entries here; neither is an opt-in any more — [`recheck/google`](#extends-presets) ships `length` directly for the guide's sentence-length limit, and [`recheck/microsoft`](#extends-presets) ships `occurrence` directly for the guide's comma-density rule, so neither one's default bounds are "no one right answer" any more.)
+Add any of the three by copying its rule below into your own config, alongside `extends: [recheck/prose]`:
 
 ```yaml
 extends: [recheck/markdown, recheck/prose]
@@ -1410,7 +1466,8 @@ recheck/ul-style:
   severity: off
 ```
 
-**Renamed legacy assertion ids — old ids are no longer accepted.** A handful of ids from Recheck's pre-parity native rules were converged onto their markdownlint-parity replacements.
+**Renamed legacy assertion ids — old ids are no longer accepted.**
+A handful of ids from Recheck's pre-parity native rules were converged onto their markdownlint-parity replacements.
 These four were removed outright, not kept as aliases: using the old id in a config now fails validation with an `unknown assertion type "<old>"` error, and the config must be updated to the new id:
 
 | Old id (removed) | Use instead |
@@ -1505,10 +1562,30 @@ recheck/front-matter:
           schemaFile: schemas/docs-front-matter.yaml
 ```
 
-- `schema` is an inline JSON Schema object; `schemaFile` loads one from a YAML or JSON file, relative to the working directory.
+- `schema` is an inline JSON Schema object, or the name of a built-in schema (see below); `schemaFile` loads one from a YAML or JSON file, relative to the working directory.
 - A file with no front matter validates as an empty object, so the schema's `required` list decides whether front matter is mandatory.
 - Findings point at the line of the offending top-level key; front matter that is not valid YAML is one finding at the block start.
 
+#### Built-in schema: Realm page front matter
+
+`schema: realm` validates the front matter options a Realm page accepts, so a project gets the check without vendoring a copy that goes stale:
+
+```yaml
+        - files: ['docs/**']
+          schema: realm
+          strict: true
+```
+
+It covers the front-matter-only options (`excludeFromSearch`, `sidebar`, `slug`, `template`, `navigation`, `keywords`), the options that override `redocly.yaml` (`banner`, `breadcrumbs`, `codeSnippet`, `colorMode`, `feedback`, `footer`, `markdown`, `metadata`, `navbar`, `navigation`, `rbac`, `redirects`, `search`, `seo`, `versionPicker`), and `title`/`description`.
+
+The schema checks the **type** of each known key, not the inner shape of the option objects.
+`seo`, `markdown`, and their siblings are whole configuration blocks that Realm evolves independently, so encoding their structure here would drift and start rejecting valid pages.
+Type checking still catches what actually goes wrong: a misspelled key (with `strict`), and a value of the wrong kind (`excludeFromSearch: "true"`).
+
+`strict: true` adds `additionalProperties: false`, which turns a misspelled option into a finding.
+It is off by default because pages carry project data that Markdoc templates read back through `$frontmatter.<key>` — Redocly's own docs use `products` and `plans` this way on 268 pages.
+To keep `strict` and allow your own keys, copy the built-in as a starting point and add them.
+
 ## GitHub Actions Integration
 
 Recheck provides seamless GitHub Actions integration for automated content quality checking on pull requests.
@@ -1519,17 +1596,17 @@ Use the `--output github-actions` format to generate inline file annotations tha
 
 ```bash
 # Basic GitHub Actions output
-node dist/cli.js run docs --output github-actions
+node dist/cli.js docs --output github-actions
 
 # With annotation limits (recommended for PR workflows)
-node dist/cli.js run docs --output github-actions --annotations-limit 20
+node dist/cli.js docs --output github-actions --annotations-limit 20
 ```
 
 ### Annotation Output
 
 The GitHub Actions format produces annotations that GitHub automatically displays as inline comments:
 
-```
+```text
 ::error title=recheck/no-trailing-spaces,file=docs/guide.md,line=42,col=15,endColumn=18::Trailing spaces
 ::warning title=recheck/ul-style,file=docs/api.md,line=23,col=1,endColumn=2::Unordered list style
 ```
@@ -1547,7 +1624,7 @@ GitHub Actions has strict limits on annotations:
 ```yaml
 - name: Run recheck with inline annotations
   run: |
-    node packages/recheck/dist/cli.js run docs \
+    node packages/recheck/dist/cli.js docs \
       --config recheck.yaml \
       --output github-actions \
       --changed-only < changed-files.txt
@@ -1574,11 +1651,13 @@ pnpm bench --subject benchmarks/run-markdownlint.mjs --corpus monorepo-docs --re
 Recheck trades a bit of the Phase 1 constant-factor lead for full rule-count parity (53 rules vs. 10) — still within budget, and the shared AST-parse-once architecture means adding prose/style rules on top costs little extra, since markdown structure parsing is already paid for.
 
 - **Phase 3** (prose profile — the standard Phase 2 rule set vs. that same set plus the Vale-parity prose additions, `monorepo-docs` document set, the same set on both sides):
-  - Standard profile (`recheck-mdl-preset.yaml`, `extends: [recheck/markdown]`, 53 rules, `run-recheck-mdl-preset.mjs`, 965 files): **4072ms** median — **-8.9% vs the Phase 2 recording** (`phase2-parity-recheck`, 4468ms, 954 files), i.e. no regression from the Phase 3 rule-registry additions, since the standard profile doesn't exercise any of them (the small speedup is run-to-run variance plus the document-set size difference, not an optimization claim).
+  - Standard profile (`recheck-mdl-preset.yaml`, `extends: [recheck/markdown]`, 53 rules, `run-recheck-mdl-preset.mjs`, 965 files): **4072ms** median — **-8.9% vs the Phase 2 recording** (`phase2-parity-recheck`, 4468ms, 954 files),
+    i.e. no regression from the Phase 3 rule-registry additions, since the standard profile doesn't exercise any of them (the small speedup is run-to-run variance plus the document-set size difference, not an optimization claim).
   - Prose profile (`recheck-prose-bench.yaml`, `extends: [recheck/markdown, recheck/prose]` plus one opt-in `occurrence` rule and one opt-in `conditional` rule, 58 rules, `run-recheck-prose.mjs`, same 965 files): **4547ms** median — **+11.7%** vs. the standard profile above, for the five added prose/scope rules (`repetition`, `consistency`, `capitalization`, and the two opt-ins).
     Comfortably under the "investigate if >2x standard" threshold; no pathological per-rule cost found.
     There is no hard pass/fail gate for this profile (new profile, first recording) — these numbers establish its baseline.
-  - Measured 2026-07-27 (local time; the result JSONs record the UTC date `2026-07-28`, so the file dates and this measurement date differ by design, not by error) at commit `27a8b6feb10` (immediately prior to the commit that added this benchmark profile), on an Apple M2 Max / Darwin 24.6.0 / Node v23.7.0 machine; single 3-run session, not a statistically rigorous multi-session average — treat the deltas as directional, not precise.
+  - Measured 2026-07-27 (local time; the result JSONs record the UTC date `2026-07-28`, so the file dates and this measurement date differ by design, not by error) at commit `27a8b6feb10` (immediately prior to the commit that added this benchmark profile), on an Apple M2 Max / Darwin 24.6.0 / Node v23.7.0 machine;
+    single 3-run session, not a statistically rigorous multi-session average — treat the deltas as directional, not precise.
     `pnpm bench --subject <script> --corpus monorepo-docs --runs 3 --record <label>` (median of 3 timed runs after 1 warm-up); recorded to `benchmarks/results/phase3-prose-standard.json` / `phase3-prose-profile.json`.
     A `--corpus self` (2-file) smoke pair recorded to `phase3-prose-standard-self.json` / `phase3-prose-profile-self.json` proves the harness/subject-script mechanics end-to-end but isn't large enough to be a meaningful timing signal on its own.
 
@@ -1618,7 +1697,8 @@ Recheck trades a bit of the Phase 1 constant-factor lead for full rule-count par
 - `string-width` - measures the display width of strings containing wide/ambiguous-width or ANSI-styled characters, for CLI table output alignment
 
 ### Optional Peer Dependencies
-- `nspell` + `dictionary-en` - Hunspell-compatible spell checker (and its bundled English dictionary) backing the `spelling` assertion (see [Spelling Assertions](#spelling-assertions-spelling) above). **Not installed by installing `@redocly/recheck`** — both are declared `optional: true` in `peerDependenciesMeta`, loaded lazily via dynamic `import()` only when a config actually enables `spelling`.
+- `nspell` + `dictionary-en` - Hunspell-compatible spell checker (and its bundled English dictionary) backing the `spelling` assertion (see [Spelling Assertions](#spelling-assertions-spelling) above).
+  **Not installed by installing `@redocly/recheck`** — both are declared `optional: true` in `peerDependenciesMeta`, loaded lazily via dynamic `import()` only when a config actually enables `spelling`.
   Run `npm i nspell dictionary-en` to enable it (or just `npm i nspell` if every `spelling` rule supplies its own `dictionary` path).
 
 ### Development Dependencies
@@ -1631,7 +1711,7 @@ Recheck trades a bit of the Phase 1 constant-factor lead for full rule-count par
 ## Example Output
 
 ### Standard Run
-```
+```text
 🏃 Running recheck on: docs/
 ✅ Configuration loaded successfully!
    Config file: recheck.yaml