doctor

Doctor

Diagnose the health of your OneBrain vault and plugin configuration. Inspired by brew doctor and npm doctor.

Usage:

• /doctor — full check (vault + config + memory)
• /doctor --vault — vault content checks only (skips CLI doctor)
• /doctor --config — plugin config + CLI doctor only (skips vault content)
• /doctor --fix — auto-fix safe issues (CLI fix recipes + skill fixes)

Flag detection: Determine active flags from the user's message. --vault = user mentions vault-only or content health; --config = user mentions config or plugin check; --fix = user explicitly asks to fix or auto-fix. Default (no flags) = run all checks.

Two-source architecture (post-v3.0.0 GA):

• CLI doctor (onebrain doctor --json) handles the built-in checks, grouped into four sections: Config (onebrain.yml, onebrain.yml-keys, vault-config-migration, legacy-qmd-collection), Vault structure (folders, plugin-files, plugin-cache), Integration (settings-hooks, claude-settings), Index & state (orphan-checkpoints, search). Rust-native, single subprocess call, structured JSON output. (search replaced the v3.3 qmd-embeddings probe; legacy-qmd-collection migrates a top-level qmd_collection → search.collection.)
• Skill checks handle vault-content + state-machine checks the CLI doesn't cover: broken wikilinks, orphan notes, stale memory/ files, MEMORY.md size, inbox backlog, log folder size, scheduler health, pause-thread state, memory health.

The skill merges both into one unified report.

---

Step 1: Read onebrain.yml

Read onebrain.yml. If it's missing → ⛔ onebrain.yml not found — OneBrain may not be configured correctly. Stop.

Resolve folder variables ([inbox_folder], [projects_folder], etc.) from onebrain.yml or defaults.

---

Step 2a: Run CLI doctor (skip if --vault flag)

Run onebrain doctor --json (or onebrain doctor --fix --json if --fix is active). Parse the JSON envelope:

{
  "ok": true|false,
  "summary": {"total": N, "errors": N, "warnings": N, "passing": N},
  "checks": [
    {"check": "<name>", "status": "ok|warn|error", "message": "...", "details": ["..."], "hint": "..."}
  ],
  "fix": [
    {"check": "<name>", "outcome": "fixed|partial|failed|manual", "message": "..."}
  ]
}