Skip to content

docs: stella doctor ships undocumented on the docs site (residual of #642) #690

Description

@macanderson

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Polish — worth doing, not urgentarea:clistella-cli — commands, flags, wiringarea:docsREADME, CONTRIBUTING, doc comments, website copy

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions