| Need | Start here | Source of truth |
|---|---|---|
| Install and run | Project README | bin/passioncode.js, family.json |
| Command results, failure recovery, state | CLI contract | lib/launcher.js, test/launcher.test.js |
| Set up or check a computer: setup, doctor, the copy-prompt | CLI contract — setup and doctor, README | lib/setup.js, lib/doctor.js, test/setup.test.js |
| Automatic-update trust and filesystem effects | Security | plugin/passioncode/hooks/, trust.json |
| Contribute or release | Contributing | Tests and .github/workflows/ |
| User paths and wording | Scenarios, copy pack | Named regression coverage and CLI source |
| Coordinate work | Generated coordination snapshot | .claude/agent-sync.json and the live tool |
| Resume the latest audit | Audit handoff | Exact source commits and command receipts |
| Understand architecture decisions | Launcher shape, publisher trust, MCP registration, setup and doctor | Append-only historical decisions |
Current operational docs are README, SECURITY, CONTRIBUTING, this index and the CLI contract. Historical ADRs and dated handoffs describe the state at their recorded date; later releases may supersede package names, trust-list contents or checks. Keep historical evidence intact and link its successor.
npm test includes documentation checks for relative Markdown links, anchors,
registered source locations, scenario coverage and evidence-test names. These
checks establish resolvability, not semantic correctness. Review the affected
contract against implementation whenever behaviour changes; update its scenario,
wording and regression receipt in the same commit.