Residual of #642, which closed with PR #685. The code shipped in full; the docs-site page did not.
What is missing
#642's acceptance criterion says "with a documented repair path". Verified at 8a6babec:
website/content/docs/commands/ has a page per command — but no doctor.mdx.
website/content/docs/commands/index.mdx lists 23 commands in its table; doctor is not among them (rg -n "doctor" website/content/docs/commands/index.mdx → no matches).
So stella doctor — including --repair, which quarantines and rewrites a user's store.db — is discoverable only via --help. The repair path is documented in --help and in the doctor's own remedy output (stella-cli/src/doctor.rs:280 repair_advice), but not where users look commands up.
Why it matters more than a typical missing page
--repair is a data-affecting operation on .stella/private/store.db. It is non-destructive by design (quarantine_corrupt_store at stella-store/src/integrity.rs:465 renames the db plus its WAL/SHM siblings to a timestamped name and salvages what SQLite can still read, and unique_sibling at :580 stops one quarantine overwriting another) — but a user who cannot find that written down has no way to know it is safe before running it.
Scope
- Add
website/content/docs/commands/doctor.mdx covering the checks, the exit-code contract (0 when everything passes including a successful --repair, 1 otherwise — stella-cli/src/doctor.rs:119), and what --repair does to the on-disk file.
- Add the row to
index.mdx's table (23 → 24).
- Worth stating explicitly that
--repair only acts on a corrupt database (gated at doctor.rs:226-232) and no-ops on an inconclusive diagnosis.
Residual of #642, which closed with PR #685. The code shipped in full; the docs-site page did not.
What is missing
#642's acceptance criterion says "with a documented repair path". Verified at
8a6babec:website/content/docs/commands/has a page per command — but nodoctor.mdx.website/content/docs/commands/index.mdxlists 23 commands in its table;doctoris not among them (rg -n "doctor" website/content/docs/commands/index.mdx→ no matches).So
stella doctor— including--repair, which quarantines and rewrites a user'sstore.db— is discoverable only via--help. The repair path is documented in--helpand in the doctor's own remedy output (stella-cli/src/doctor.rs:280repair_advice), but not where users look commands up.Why it matters more than a typical missing page
--repairis a data-affecting operation on.stella/private/store.db. It is non-destructive by design (quarantine_corrupt_storeatstella-store/src/integrity.rs:465renames the db plus its WAL/SHM siblings to a timestamped name and salvages what SQLite can still read, andunique_siblingat:580stops one quarantine overwriting another) — but a user who cannot find that written down has no way to know it is safe before running it.Scope
website/content/docs/commands/doctor.mdxcovering the checks, the exit-code contract (0 when everything passes including a successful--repair, 1 otherwise —stella-cli/src/doctor.rs:119), and what--repairdoes to the on-disk file.index.mdx's table (23 → 24).--repaironly acts on a corrupt database (gated atdoctor.rs:226-232) and no-ops on an inconclusive diagnosis.