Docs Freshness Pipeline — feat/docs-freshness playground

📚 Docs Freshness Pipeline

Playground for feat/docs-freshness — why hand-written docs facts rotted, what was actually stale (and what wasn't), and the three layers that now keep them honest.

stale CC-floor instances fixed (2.1.148 → 2.1.183)

10+

111-era & derived-count strings refreshed

pages now render facts via <Count/> / <MinCC/>

new CI gate: check-docs-facts.mjs

Coverage: before → after

Generated pages
(reference/, by-category/)

✅ regenerated every npm run build + CI drift gate diffs them

CLAUDE.md / README floor

✅ stamped by stamp-cc-support.mjs

Hand-written MDX facts
(floors, counts)

❌ nothing — literals rot silently (floor missed the 2026-06-20 bump for 10+ days)

Generated pages

✅ unchanged — build + drift gate

Hand-written prose

✅ <Count k="skills|commands|references|agents|hooks"/> + <MinCC/> render from generated data — rot impossiblenew

Code blocks

✅ can't interpolate → stamped by stamp-cc-support.mjs docs targetnew

Frontmatter + leftovers

✅ check-docs-facts.mjs CI gate: floor-claim shapes + "N skills, M agents[, K hooks]" triples vs computed truthnew

The counting trap 🪤

Four independent auditors (assessor, two blind refuters, the auto-router) all "verified" the docs counts as stale — using the same wrong method.

Method	Result	Verdict
`ls src/skills \| wc -l`	114	wrong — includes shared/ (no SKILL.md)
`ls src/agents/*.md \| wc -l`	38	wrong — includes README.md
SKILL.md files / agent files with `name:`	113 / 37	matches manifest + shared-data.ts TOTALS

Method

Result

Verdict

ls src/skills | wc -l

114

wrong — includes shared/ (no SKILL.md)

ls src/agents/*.md | wc -l

wrong — includes README.md

SKILL.md files / agent files with name:

113 / 37

matches manifest + shared-data.ts TOTALS

Lesson: agent independence ≠ method diversity. The gate now encodes the generator's semantics, not raw filesystem counts.

What was actually stale

Claim	Where	Status
Claude Code floor 2.1.148	installation, FAQ, release-channels, troubleshooting, cookbook	stale — and security-relevant (skipped range includes the 2.1.163 Bash $HOME secrets-read fix)
"111 skills" era strings	faq, skills-agents-hooks, writing-skills, doctor refs, skill-fitness.mjs	stale (two releases of sweeps missed them)
"27 user-invocable / 22 listed / 47 hidden"	skills/overview	stale → 32 / 23 / 48
"113 skills, 37 agents, 212 hooks"	~12 pages	current — manually swept 2026-06-24 (#2645)
"81 reference skills"	reference-skills	current — flagged as stale by the first audit pass, refuted on verification

Claim

Where

Status

Claude Code floor 2.1.148

installation, FAQ, release-channels, troubleshooting, cookbook

stale — and security-relevant (skipped range includes the 2.1.163 Bash $HOME secrets-read fix)

"111 skills" era strings

faq, skills-agents-hooks, writing-skills, doctor refs, skill-fitness.mjs

stale (two releases of sweeps missed them)

"27 user-invocable / 22 listed / 47 hidden"

skills/overview

stale → 32 / 23 / 48

"113 skills, 37 agents, 212 hooks"

~12 pages

current — manually swept 2026-06-24 (#2645)

"81 reference skills"

reference-skills

current — flagged as stale by the first audit pass, refuted on verification

Gate contract

node scripts/check-docs-facts.mjs # floor claims: />= 2.x.x/, /Claude Code 2.x.x or later/, /below 2.x.x/ → must equal shared/cc-support.json supported_floor # count triples: /(\d+) skills, (\d+) agents[, (\d+) hooks]/ → must equal computed 113 / 37 / 212 # scope: docs/site/content/docs/**/*.mdx minus generated (reference/, skills/by-category/) # escape: line containing "docs-facts-ignore" check-docs-facts: OK (floor 2.1.183, 113 skills, 37 agents, 212 hooks)