Context

npm run audit:docs is useful, but it currently mixes high-signal problems with false positives.

Examples from current logic:

• Broad semver regex flags unrelated versions (Rails/TypeScript/etc)
• Placeholder regex flags intentional XXX/YYY tokens in error-message examples
• All findings are reported at the same level

Relevant script: scripts/audit-docs.mjs

Goal

Improve audit precision and introduce severity tiers.

Proposed changes

• Skip fenced code blocks for placeholder checks.
• Refine version checks to target React on Rails version context.
• Keep strict checks for broken links and malformed anchors.
• Emit severity (error, warn, info) in report output.

Acceptance criteria

• Placeholder false positives on intentional code examples are reduced.
• Version-floor warnings focus on relevant product/version references.
• Report clearly distinguishes blocking vs advisory findings.