docs: professional README + docs consolidation + scorecard fix (wave 3)

[CodeWithJuber]

What & why

The final wave: the repo's front door and documentation brought up to the standard of what's now inside it. Two parallel worktree agents + one CI fix, integrated.

Professional README (rewritten, 216 lines — scannable in ~2 minutes)

• Badge row of real, functional badges only: CI, CodeQL, OSSF Scorecard, MIT, node ≥20, zero-runtime-dependencies. No vanity metrics.
• "What you get" hook where every number is measured and sourced: 0.43 ms blast-radius queries, 118 ms full pre-action gate, 158 ms CRDT merge of 2×500-claim replicas (all from reports/benchmarks.md); recall 0.97 vs 0.33 edited-file-only baseline (n=6 caveat carried into Honest limits); the 62.1 % routing saving explicitly labeled as the white paper prototype's live measurement; the 1.3 s-vs-60 s dry-run.
• 60-second quickstart, grouped command table, one mermaid diagram of the whole loop (task → gate → act → oracles → ledger → team merge), a 6-row structural comparison table including the "what they do better" honesty row, and searchable headings ("team memory for AI agents", "cross-tool AGENTS.md config") worked in naturally.
• npm SEO: 17 keywords in package.json matching the staged repo topics.

Docs consolidation (18 files, net −)

• Deduplicated cross-doc prose into single canonical homes (substrate README now points at the GUIDE instead of repeating its tables); verified before touching anything that global/tools/ and skills/ copies are load-bearing for the two plugin manifests — the Codex mirror stays byte-identical by design, not oversight.
• Three orientation mermaid diagrams: ARCHITECTURE (four-layer compiler + PCM ledger), substrate-v2 plan (P0→P8 dependency graph, all phases marked ✅ shipped), GUIDE (the daily loop).
• All 14 skills + crew guidance refreshed for the v0.5.0 surface (forge context, imagine --run, diagnose, ledger blame, cost --stages, uicheck design --taste) with a net −262 byte context payload — guidance grew in capability while shrinking in tokens.
• Guide accuracy pass run against the live CLI: five drift items found and fixed (stale "P5 follow-up" text, missing context: gate line in the substrate example, nonexistent dirs/commands in ARCHITECTURE's layout, ROADMAP still listing shipped phases as future). Stale machine-specific advice purged from skills.
• ROADMAP now: Shipped (P0–P8, v0.5.0) / Next (ledger read-path flip, embeddings tier, Playwright loop, advisory→gated promotions).

CI fix — the new Scorecard workflow failed on master: ossf/scorecard-action@v2 doesn't exist (Scorecard publishes exact tags only — practicing the pinning its own check preaches). Pinned to v2.4.0.

Checklist

• npm test passes (401/401 — docs + keywords + one workflow line; zero runtime changes)
• npm run check / npm run typecheck clean; node scripts/bump.mjs check → versions agree at 0.5.0
• New public functions have a test — n/a (no code)
• Conventional commits
• CHANGELOG.md updated under ## [Unreleased] → Changed
• No new runtime dependency
• Substrate/docs updated — this PR is that
• forge sync output verified byte-identical before/after the skills edits

Risk & rollback

• Risk level: low (docs, keywords, one workflow version pin)
• Rollback plan: revert the merge commits

Extra checks (tick if applicable)

• Every relative link in the new README verified to resolve (16/16, anchors included)
• Logs contain no secrets/PII
• If AI-assisted: I understand it, verified the claims against the benchmark doc, and nothing unmeasured is stated as fact

🤖 Generated with Claude Code

https://claude.ai/code/session_01Fc2MvWJbQ1cyNQ76ymv4hs

---

Generated by Claude Code