Update to Redocly

{
  "description": "Use when you create or tune the recheck block and recheck/* presets in redocly.yaml for a project — choose presets, set severities from measured counts, add exceptions, adopt a baseline, and validate the result.",
  "included_files": [],
  "name": "recheck-config",
  "skill_md_contents": "---\nname: recheck-config\ndescription: Use when you create or tune the recheck block and recheck/* presets in redocly.yaml for a project — choose presets, set severities from measured counts, add exceptions, adopt a baseline, and validate the result.\n---\n\n# Configure recheck in redocly.yaml\n\nConfigure `redocly recheck` for a project the way its maintainers would: measure first, decide per rule, and record intent.\nThe documentation is at [redocly.com/docs/cli/recheck](https://redocly.com/docs/cli/recheck); favor it over memory for rule names and options.\n\n## How the configuration is shaped\n\nPresets go in the root `extends`.\nAdjustments go in the `recheck` block, with rules nested under `rules`.\nThe `lint` command ignores both, so they live next to the API ruleset:\n\n```yaml\nextends:\n  - recommended\n  - recheck/markdown\n  - recheck/prose\nrecheck:\n  excludes:\n    - CHANGELOG.md\n  rules:\n    recheck/line-length: off\n    recheck/no-duplicate-heading:\n      severity: warn\n      assertions:\n        no-duplicate-heading:\n          siblingsOnly: true\n```\n\nRules of the shape:\n\n- A rule key is `<namespace>/<name>`: `recheck/line-length`, `google/no-via`, or your own, such as `acme/product-names`.\n- A severity string (`off`, `info`, `warn`, `error`) adjusts a rule that a preset defines.\n  For a key no preset defines, it is a configuration error, because the rule has no assertions.\n- A rule object merges over the preset's rule, but its `assertions` merge by assertion id: one option you set on a `swap` or `pattern` assertion replaces the preset's whole word list.\n  To reject one term from a preset's list, turn the rule off, restate the full list, or use an inline directive.\n- A new prose rule needs `severity`, `message`, and `assertions`.\n  A new Markdown rule, such as `recheck/list-length`, needs only `severity` and `assertions`.\n- The block does not accept `extends` or `baseline`; both are configuration errors.\n- The command reads the root block only.\n  A `recheck` block under `apis.<name>` does nothing and prints a warning.\n\n## Start a new config\n\n1. Begin with the structural preset, and run recheck to validate it:\n\n   ```yaml\n   extends:\n     - recheck/markdown\n   ```\n\n   ```bash\n   npx @redocly/cli recheck docs\n   npx @redocly/cli check-config\n   ```\n\n   The `recheck` command reports configuration errors before it lints anything, and `check-config` validates the block's shape.\n\n2. Add prose presets deliberately, not wholesale.\n   `recheck/prose` is a small starter at `warn`.\n   `recheck/google` and `recheck/microsoft` are large style guides, detection-only, that need tuning before they help.\n   `recheck/plain-language`, `recheck/inclusive-language`, and `recheck/technical-english` compose onto either.\n\n3. If the project writes Markdoc tags, add `recheck/markdoc` to `extends` and `markdoc: true` to the block.\n   Without the flag, the Markdoc rules never report.\n\n## Tune severities from measurements, not taste\n\n1. Run the whole document set and count findings per rule:\n\n   ```bash\n   npx @redocly/cli recheck docs --summary=json --summary-path=recheck-summary.json\n   ```\n\n   The summary's `breakdown` has the count per rule and severity.\n   For examples of each rule's findings, run `--rule=<name>` and read a few.\n\n2. Decide per rule from the counts:\n   - `error` — enforce now; the document set is clean or you fix it in the same change.\n   - `warn` — a worklist; visible, not blocking.\n   - `off` — decided against; keep a YAML comment that says why, or the decision is lost.\n\n3. Prefer fixing content over configuring around it.\n   Run `--fix` first; most structural findings repair themselves.\n   Review the fix list before you commit: fixes that re-indent lines can move content out of an indented Markdoc tag body.\n\n## Exceptions, in order of preference\n\n1. Fix the content.\n2. The top-level `excludes` list, or a rule's `excludes` or `appliesTo`, for generated or frozen content such as archives and vendored docs — with a comment naming the reason.\n3. `exceptions.lines` for a recurring true positive that must stay as written.\n4. An inline `<!-- recheck-disable-next-line rule-name -->` for a single line.\n\n## Adopt strictness on a large document set with a baseline\n\nWhen the document set has too many errors to fix at once, record them and gate only new ones:\n\n```bash\nnpx @redocly/cli recheck docs --generate-baseline\n```\n\nCommit `.redocly.recheck-baseline.yaml`.\nThe command writes it next to `redocly.yaml`, and later runs pick it up by presence; there is no configuration key.\nIt records errors only, as one count per file per rule.\n\nCounts only step down: when findings get fixed, the run reports stale entries, so regenerate the baseline and commit the diff.\n\n## Finish\n\n- `npx @redocly/cli recheck docs` and `npx @redocly/cli check-config` report no configuration errors.\n- Every `off` and every exception carries a comment with its reason.\n- The project's contributing docs say how contributors run recheck locally, and CI runs it with `--format=github-actions`.\n"
}