Problem

People want a doctor command. They run it when something looks wrong and expect it to tell them what is wrong with their project and what to do about it. bm doctor does neither.

Today it is a smoke test. It registers a throwaway project in the user's real config and database, writes a note through the API and one through the filesystem, indexes them, searches, checks status, then deletes the project. It passes on an install whose real projects have duplicate search rows, orphaned rows or unindexed files (#1773), because it never looks at them.

The throwaway project is also why doctor keeps breaking. It is a real project, so it runs into every policy a real project is subject to, and each one has produced a bug and a special case:

The next policy change will produce the next doctor bug.

Goal

bm doctor produces a report on the user's actual projects and, for each problem it finds, suggests an action the user or their agent can take to fix it.

Proposed design

1. Inspect real projects (read-only)

Doctor checks the projects that exist and never writes to them. Each check produces findings, and each finding carries a suggested action. A first set of checks:

Two rules:

• Severity follows the consistency model in AGENTS.md. Derived state (search rows, vectors, materialization status, Wiki output) is eventually consistent. A lag while indexing is running is reported as info, not as a failure. A finding is an error only when nothing will repair it without action: a real duplicate, a missing file, a parse error, a conflict.
• Actions are concrete commands or edits, not "wait and rerun". If doctor cannot name an action, the finding says so and shows the evidence.

2. Pipeline self-test, sandboxed

Keep the write, index, search and status round trip. It catches broken installs, missing dependencies and migration failures. But run it in-process against a temporary home, config, SQLite database and project directory, the way just doctor already does, and never register anything in the user's real config or database. That removes the project-root, default-project, config-mutation and cleanup bugs as a class. It needs ConfigManager to be injectable at the composition root (the open half of #1109).

3. Output for people and agents

• Human output: a short summary per project, then findings grouped by severity, each with its action.
• --json: a stable, typed report (checks, findings, severity, evidence, suggested action) that an agent can act on without parsing prose.
• Exit codes: 0 when there are no errors; nonzero when there is at least one error. Info and warnings never fail the run.
• Scoping: --project X, with every project by default.

Doctor reports and suggests. It does not repair. A separate --fix that runs the suggested safe actions could come later; it is out of scope here.

Open questions

• Cloud. Should bm doctor --cloud run the read-only inspection against cloud projects only, with no self-test? Today it would create a real cloud project.
• MCP. Should the report also be exposed as an MCP tool, or a memory://doctor resource, so an agent can run it directly?
• bm status. Some of these checks overlap with status ([BUG] bm status and bm doctor` don't surface index inconsistencies (duplicate rows, orphans, inverted timestamps) #1773 also asks for index counts there). Should status show a one-line "doctor would report N problems" summary?

Relationship to existing work

• [BUG] bm status and bm doctor` don't surface index inconsistencies (duplicate rows, orphans, inverted timestamps) #1773 and PR fix(cli): surface existing project index integrity in doctor #1792: PR fix(cli): surface existing project index integrity in doctor #1792's read-only integrity report is the right shape for the first check in section 1. As written it also fails the run on transient derived-state lag and suggests waiting instead of bm reindex; folding it into this design fixes both.
• Wiki projection fails the whole run when folders differ only by case #1787 (PR fix(core): report case-only Wiki scope collisions instead of failing the run #1789): Wiki scope collisions become a doctor finding with a rename action.
• Consolidate _v2/_v2_external DI provider triplication; stop reading ConfigManager below the composition root #1109: injectable ConfigManager unblocks the sandboxed self-test.

Acceptance

• bm doctor never creates, modifies or deletes anything in the user's real config or database.
• On a project with a duplicate search row, a missing file and an unindexed file, doctor reports three findings, each with an action, and exits nonzero.
• On a healthy project with indexing in progress, doctor exits 0 and reports the lag as info.
• bm doctor --json output is a typed schema covered by tests.
• The sandboxed self-test passes with project_root configured, with no default project, and with a fresh config.