Summary
README.md:65-72 lists six documentation files (USER_GUIDE, CLOUD_BOOTSTRAP, DEVELOPER_GUIDE, TESTING_GUIDE, SELF_IMPROVEMENT, INTEGRATION_POLICY) but doesn't reference CLAUDE.md, which is the authoritative source for the Status Contract per CLAUDE.md:3 ("Read AGENT_GUIDE.md first") and CLAUDE.md:27 ("Keep the three docs synchronized"). New contributors and integrators reading README first cannot discover where the Status Contract lives, breaking the documented "three docs" sync chain.
Where
Suggested approach
(1) Add CLAUDE.md (and AGENT_GUIDE.md) to the README documentation table with a short "what this is for" hook: "CLAUDE.md — Claude Code entry point and Status Contract". (2) For each entry, link to the relevant section anchor (e.g. CLAUDE.md#status-contract) so readers land on the contract directly. (3) Add a one-paragraph note at the top of README explaining the AGENT_GUIDE / CLAUDE.md / .codex/workflows triangle — many contributors don't know which to read first. (4) Add a doc-lint CI check that asserts every .md file at repo root is referenced from the README documentation table (cross-link the just-filed #1862 doc drift CI). (5) Cross-link with #1452, #881, and the just-filed C552 (.NET version inconsistency) / C551 (Status Contract README — already in dedupe to #1452+#881 but reinforces the same area).
Summary
README.md:65-72 lists six documentation files (USER_GUIDE, CLOUD_BOOTSTRAP, DEVELOPER_GUIDE, TESTING_GUIDE, SELF_IMPROVEMENT, INTEGRATION_POLICY) but doesn't reference CLAUDE.md, which is the authoritative source for the Status Contract per CLAUDE.md:3 ("Read AGENT_GUIDE.md first") and CLAUDE.md:27 ("Keep the three docs synchronized"). New contributors and integrators reading README first cannot discover where the Status Contract lives, breaking the documented "three docs" sync chain.
Where
README.md:65-72(documentation table)CLAUDE.md:3, 27(references to three-doc sync)Suggested approach
(1) Add CLAUDE.md (and AGENT_GUIDE.md) to the README documentation table with a short "what this is for" hook: "CLAUDE.md — Claude Code entry point and Status Contract". (2) For each entry, link to the relevant section anchor (e.g.
CLAUDE.md#status-contract) so readers land on the contract directly. (3) Add a one-paragraph note at the top of README explaining the AGENT_GUIDE / CLAUDE.md / .codex/workflows triangle — many contributors don't know which to read first. (4) Add a doc-lint CI check that asserts every .md file at repo root is referenced from the README documentation table (cross-link the just-filed #1862 doc drift CI). (5) Cross-link with #1452, #881, and the just-filed C552 (.NET version inconsistency) / C551 (Status Contract README — already in dedupe to #1452+#881 but reinforces the same area).