[adamaltman]

What/Why/How?

Adds a recheck job to the documentation tests workflow so Redocly CLI lints its own Markdown with redocly recheck, next to the markdownlint, vale, and linkcheck jobs. The job is a port of the monorepo's recheck.yml, adapted to this CLI's flags.

• The job builds the repository and installs the local CLI pack, as the smoke workflows do.
  The steps are npm ci, npm run pack:prepare, and npm i -g ./redocly-cli.tgz.
  This way, a PR that changes a recheck rule shows its effect on the docs in the same run.
  The cost is a few minutes of build time on each docs PR.
• The config lives in docs/redocly.yaml and is passed with --config. A redocly.yaml in the repository root would change the CLI package's unit tests.
• Changed files get annotations at every severity plus a summary written with --summary json. The full tree gates on errors only, because deleting a file or renaming a heading breaks links in files a PR never touched. Readability is scored for changed files on the PR head and on the merge-base from detached worktrees.
• A summary comment on the PR lists findings by rule and a per-file readability table (ARI, lower is easier). It is updated in place on every run. A fork PR has a read-only token, so a failed comment does not fail the job.
• This CLI has no --changed-only or --severity flag, so the job passes the changed files as paths and uses --max-problems on the full-tree step: errors sort first, so the cap only trims the warning backlog.

Rules ported from the monorepo

docs/redocly.yaml keeps the .markdownlint.yaml parity settings and ports the monorepo's recheck.yaml, with severities set from a measurement of this tree:

• Presets: recheck/markdown, recheck/markdoc, recheck/plain-language, recheck/technical-english, recheck/inclusive-language.
• At error because the tree is at zero findings: the plain-language word-choice rules, us-spelling, inclusion-gender-culture, oxford-comma, no-trailing-spaces, bullet-style-dash, no-hard-tabs, no-duplicate-headings, no-broken-fragment-links (cross-file).
• At warn as a worklist: semantic-line-breaks (628), readable-line-length (22), no-gerund-headings (4), optimize-images (3), plus the preset defaults for sentence-length, paragraph-length, excess-intensifiers, and paragraph-sentence-count. passive-voice stays at info.
• Prose budget: page-reading-time applies to docs/** and cookbook/** at warn, with a 15-minute limit at 200 words per minute.
  Three pages are over the limit: both changelogs and guides/use-generated-client.md.
• Not ported: front-matter (these docs have none), markdoc-tables-only (this repo uses pipe tables), and pitch-reading-time (this repo has no pitches).
  skill-length is also not ported.
  The job does not scan SKILL.md files, and the skills tree is not at zero errors under this config.
  In .claude/skills and packages/recheck/skills, us-spelling reports neighbour in redocly-lint-rules/SKILL.md.
  That skill also has 3,253 prose words, over the 1,500-word budget.

Docs fixes

The first run found 12 errors in the no-ambiguous-paths and no-identical-paths rule pages (v1 and v2).
Those fixes landed on main in #3188, so this PR does not carry them now.
This PR still fixes one British spelling in the cookbook (fulfil).
The recheck docs from #3182 show British spellings in swap-pair examples on purpose, for example colour: color.
us-spelling has a line exception for each of these five pairs.
With those changes, the tree has no errors and needs no baseline file.

No changeset: repository tooling and docs only. The command docs ship separately in #3182.

Reference

• Docs and skills for the command: docs(recheck): document the recheck command and update the agent skills #3182
• Source of the port: the monorepo's .github/workflows/recheck.yml and recheck.yaml

Testing

Ran locally after the merge of main, with the CLI from the local pack (2.59.0):

• npm ci, npm run pack:prepare, and npm i -g ./redocly-cli.tgz --prefix /tmp/recheck-pack-probe install the pack.
  The temporary prefix keeps the global install unchanged.
• redocly recheck docs cookbook --config docs/redocly.yaml --format=github-actions --max-problems 50 scans 384 files, reports 0 errors, and exits 0.
  It also reports 2,376 warnings and info.
  A temporary file with a trailing-punctuation heading produces a ::error annotation and exit code 1.
• The changed-files call writes the summary file with the fields that the comment script reads, and exits 0.
• The readability call runs from a tree with no docs/redocly.yaml, reads the config from an absolute path, and scores each file.
• npx oxfmt --check .github passes, and js-yaml parses docs-tests.yaml.
  The machine has no actionlint or yamllint.

Check yourself

• This PR follows the contributing guide
• All new/updated code is covered by tests
• Core code changed? - Tested with other Redocly products (internal contributions only)
• New package installed? - Tested in different environments (browser/node)
• Documentation update has been considered

Security

• The security impact of the change has been considered
• Code follows company security practices and guidelines

🤖 Generated with Claude Code

---

Note

Low Risk
CI and documentation-only changes; no runtime product code, with gating limited to docs lint errors and optional PR comments.

Overview
Adds a recheck GitHub Actions job alongside markdownlint, Vale, and linkcheck so docs/ and cookbook/ Markdown is linted with redocly recheck using a new docs/redocly.yaml (not at repo root, to avoid affecting CLI unit tests). The job diffs PR-touched Markdown, annotates changed files, fails the build if the full tree has recheck errors, scores readability on head vs merge-base, and updates a PR comment with rule breakdowns and an ARI table.

docs/redocly.yaml extends recheck presets (markdown, markdoc, plain-language, technical-english, inclusive-language) with severities tuned to the current tree: zero-backlog rules at error, known backlog items at warn (e.g. semantic line breaks, line length).

Small cookbook edits: US spelling fulfill, and an updated Spectral OWASP ruleset link.

^{Reviewed by Cursor Bugbot for commit bbd44bc. Bugbot is set up for automated code reviews on this repo. Configure here.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: ee796a9

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	83.15% (🎯 80%)	20268 / 24374
🔵	Statements	82.71% (🎯 80%)	21892 / 26467
🔵	Functions	84.38% (🎯 80%)	3821 / 4528
🔵	Branches	75.2% (🎯 75%)	14706 / 19554

File Coverage

No changed files found.

Generated in workflow #12373 for commit ee796a9 by the Vitest Coverage Report Action

[github-actions]

Performance Benchmark (Lower is Faster)

CLI Version	Bundle	Lint	Check Config
latest	▓░░░░░░░░░░ 1.01x ± 0.03	▓░░░░░░░░░░ 1.01x ± 0.03	▓░░░░░░░░░░ 1.00x ± 0.02
next	▓░░░░░░░░░░ 1.00x	▓░░░░░░░░░░ 1.00x	▓░░░░░░░░░░ 1.00x

[github-actions]

📝 Recheck Summary

⚠️ Warnings found • Scanned 2 changed file(s)

• 0 error(s)
• 14 warning(s)
• 12 info

📋 Findings by rule

🟡 technical-english/sentence-length: 0 errors, 11 warnings, 0 info
🔵 technical-english/passive-voice: 0 errors, 0 warnings, 12 info
🟡 semantic-line-breaks: 0 errors, 3 warnings, 0 info

Errors fail the full-tree check. Warnings and info are a worklist and do not block the PR.

📖 Readability of changed files

Automated Readability Index (ARI): a U.S. grade level. Lower is easier to read.

File	Base	This PR	Change
cookbook/custom-plugins/sorting/README.md	10.7	10.8	±0
cookbook/rulesets/security/README.md	8.1	8.0	🟢 -0.1 easier

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 01cbe68. Configure here.}

[tatomyr]

Left a couple of comments to consider. Otherwise LGTM.