Closes the five deferred items from the prior gotcha audit:
A. Link checker — scripts/sync/lint-links.mjs walks docs/**/*.md and
verifies every relative markdown/image link resolves to an existing
file. Skips external URLs, absolute SPA routes (/...), URI schemes
(mailto:, agent://, etc.), and template placeholders. Found 3 real
pre-existing broken links to missing screenshots — not fixed in
this commit, but the tool will now block any new ones.
B. Nav verification — scripts/sync/verify-nav.mjs cross-checks
site/content.json against the docs filesystem. Dangling entries
(in nav but missing on disk) are errors; orphans (on disk but not
in nav) are warnings. Found 1 real orphan (require-board-approval-
before-spend.md from c0ff148 — never registered in content.json)
that the user should triage separately.
C. Screenshot registry backfill — scripts/sync/backfill-screenshots.mjs
scaffolds entries for every PNG under docs/user-guides/screenshots/.
Run once; registry.json now ships with 274 scaffolded entries
(137 light + 137 dark). Each has placeholder `depends_on: []` and
a `_todo` field; humans fill in parent-repo path anchors over time
to activate staleness detection per-entry. Re-runs preserve any
entry with non-empty depends_on.
D. content.json edit serialisation — SKILL Phase 5 now requires
subagents to return a structured `nav_addition` object alongside
page content rather than editing site/content.json directly. The
orchestrator merges all nav_additions on the main thread after
subagents finish. Prevents the parallel-write race where two
subagents creating new pages clobber each other's nav entries.
E. gh compare truncation — SKILL Phase 2 now explicitly documents
the GitHub compare endpoint's ~300-file/~300-commit cap and the
window-splitting fallback (walk intermediate release tags for
release mode; binary-split commit list for nightly mode).
Also wires the scripts into package.json (sync:lint-links,
sync:verify-nav, sync:check, sync:backfill-screenshots) and into
SKILL Phase 7 (sync:check runs before commit; dangling/broken-link
failures abort the run).
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
