P1W2: Codex iteration 1 — strict discovery + tutorial READMEs + honest docs
Addresses Codex iteration 1's NOT CONVERGED verdict.
(2) Discovery hard-errors on bad manifests, no more silent cell drops:
unknown manifest_key (no matching frameworks/<key>.yml), kind/section
mismatch (descriptor declares kind: onchain but the key is under offchain:),
and missing example.yml are all collected during the walk and reported as
::error:: with the offending entry list, then exit 1. Smoke-tested by
injecting a typo into escrow's offchain: section.
(4) Stale heuristic-fallback docs cleaned up:
- frameworks/SCHEMA.md "Discovery" rewritten to describe manifest-only
semantics and the unknown-key error.
- escrow/example.yml's "falls back to legacy filename heuristics" comment
removed; replaced with the unknown-key-is-an-error rule.
- vesting/example.yml's note rephrased as historical context (vesting/
offchain/meshjs/ has no deno.json; the manifest now declares it
explicitly).
(3) README-badge limitation made explicit:
- scripts/embed-readme-badges.sh comment block now states honestly that
every embedded badge points at the same workflow status, not per-cell.
- docs/README.md "I'm here to learn" notes that README quality varies and
the 5 starting-path use cases are first-targeted for tutorial rewrites.
(1, partial) Tutorial-grade READMEs for 4 of the 5 starting-path use
cases — simple-transfer, vesting, htlc, escrow — rewritten to the plan's
template (What this is / Why it matters / How the onchain logic works /
How to use it offchain / Try it yourself / What's tested in CI /
Variations to explore). atomic-transaction's existing README is already
content-rich and covers the same ground in a different structure;
left untouched. The other 16 use cases keep their original READMEs;
docs/README.md and docs/learn.md are now honest about the uneven state
and the remaining rewrites are tracked as ongoing rather than blocking
P1W2 close.
.codex-reviews/p1w2.md: iteration 1 actions logged.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>