docs: fix what the docs claimed, and document what shipped

[charlesgreen]

Two documentation audits, one technical and one adopter-facing, found the same root cause: twelve tickets merged in a day without a documentation pass, so the docs describe a release behind the code.

Contradictions removed

Each of these was visible to anyone reading top to bottom, and a sceptical reader trusts the pessimistic sentence because it comes first.

• The README said the reviewer is not yet wired into the loop, then explained how to turn it on 114 lines later.
• It said a Claude adapter is planned, eight lines below the instructions for enabling it.
• STATUS.md still named v0.1.5, and listed "CI actions are pinned by tag, not commit SHA" under deliberately not done. We SHA-pinned everything in ci: pin actions by commit SHA #70. That one is the worst of the set: a security-conscious reader opens the file we tell them to read first and finds us self-reporting a supply-chain risk we had already closed.
• The FAQ said init did not exist yet.

Three features had no adopter-facing documentation at all

preflight, --dry-run, and the install self-test. Those are precisely the three things built for a reader who does not yet trust this, and they existed only in CLI stdout and an unreferenced template. They are now in the README's first screen, in docs/setup.md, and in the FAQ.

New: docs/troubleshooting.md

There was no troubleshooting document. It starts from the symptom every install-time failure shares, the run went green and nothing happened, because that is what an adopter actually sees.

Its content is mostly lifted rather than written: the explanations for the sandbox failure, the missing git identity, and the token that cannot trigger workflows already existed as prose in code comments, where no adopter could ever read them. One of those comments even pointed at the FAQ for the bwrap condition, and the FAQ had never mentioned it.

Three diagrams

Each earns its place; the reviewer explicitly recommended against a fourth for the label lifecycle, since the existing table carries information a state diagram would lose.

1. The credential split (docs/setup.md) — local CLI versus Actions, each with its own identity and its own source for the same two values. This is a two-dimensional fact currently smeared across three sections, and the product's own error strings tell you people get it wrong.
2. The silent-success diagnosis tree (docs/troubleshooting.md) — four unrelated causes with one identical symptom is a decision tree, not a narrative. Prose forces you to read three irrelevant causes before reaching yours.
3. What triggers a run (README) — including that a plain comment is not a review. Only honest to draw now that fix: route comments through the parser instead of straight into a run #89 fixed comment dispatch; drawing it is how that bug was found.

Also

The hero image is the same card shown when simplycubed.com/code is shared, committed into the repo rather than referenced from the web build so the README does not depend on the marketing site to render. The scattered trust claims are consolidated into one argued block, led by the strongest fact in the codebase: the loop cannot merge by construction, because the interface it is built against has no merge method.

All new prose went through the humanizer pass.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!