# Maintenance and diagnostics **English** · [Português](../../pt-BR/commands/maintenance-and-diagnostics.md) ## Purpose Inspect vault health and keep definitions, theme, and package version aligned without treating change commands as global checks. ## When to use Use after install/update, when hooks emit warnings, or before starting a change. ## When not to use Do not run `wendkeep verify` when no change is active. It proves a change's tasks; it is not a replacement for doctor. ## Prerequisites Run from the project root or provide `--project` and `--vault` explicitly. ## Syntax ```bash npx --no-install wendkeep doctor [--vault ] [--scope all|core|runtime] [--strict] npx --no-install wendkeep memory curate --vault npx --no-install wendkeep sync-defs [--check|--reseed] --vault --project npx --no-install wendkeep theme sync --vault npx --no-install wendkeep --version npx --no-install wendkeep --help ``` ## Options and exit codes - `doctor` is read-only. By default only structural errors produce a non-zero exit; `--strict` also fails on workflow attention, repairable debt, semantic degradation, and warnings. - `--scope core` checks the installation, binding, ledger, and Keep Core only. `--scope runtime` checks changes, sensors, and governance only. The default `all` reports both surfaces. - The `[worktrees]` section reconciles the private registry with Git and reports slugs in `failed`, `missing`, or invalid-binding states. Under `--strict` this debt also fails; doctor never performs the repair. - `doctor` uses human-readable output with `[integrity]` and `[memory]` sections, friendly categories, and a copyable next action. The `vault-health.mjs` hook remains the JSON surface for automation; neither surface applies curation. - Even with a missing Vault, unsafe physical boundary, or unsafe registry, `doctor` marks memory as blocked and shows `memory status --gate` with the resolved path; the hook preserves structured JSON instead of replacing the result with stderr or a stack trace. - In v2, `doctor`/`memory status --gate` correlate `last_memory_attempt` (mode, disposition, event IDs, and checkpoint) with outbox, ledger, and SHARED; they do not infer health from revision alone. - `revision: 0` after a valid migration, with no v2 attempt, is healthy. A `degraded` attempt whose events remain durable in the outbox/ledger is a recoverable warning. - An ambiguous publication attempt, a lost event ID (absent from ledger and outbox), `projected` state found only in the outbox, or a mismatched checkpoint is a structural block. Active semantic candidates degrade memory by key and remain available for explicit curation. - For session observability, `legacy`, `degraded`, `stale`, and `manifest-unproven` require reconciliation or more evidence. Only fresh `none` and fresh `complete` are healthy: frontier, checkpoint, root stat, and source manifest must agree. - `doctor` remains read-only. It recommends the targeted dry-run first and only advises repeating the command with `--apply` after human review. - `sync-defs --check` detects drift without writes; `--reseed` restores packaged `wk-*` skills. - `theme sync` reapplies the CSS snippet and graph groups without recreating the vault. - `wendkeep --version` prints the running version; `wendkeep --help` lists the public interface. ## Examples Post-update checklist: ```bash npx --no-install wendkeep --version npx --no-install wendkeep sync-defs --check --vault .MyApp-vault --project . npx --no-install wendkeep doctor --vault .MyApp-vault npx --no-install wendkeep doctor --scope core --vault .MyApp-vault npx --no-install wendkeep doctor --scope runtime --strict --vault .MyApp-vault npx --no-install wendkeep memory status --gate --vault .MyApp-vault npx --no-install wendkeep memory curate --vault .MyApp-vault npx --no-install wendkeep memory candidates --active --vault .MyApp-vault npx --no-install wendkeep cost rebuild --session --json --vault .MyApp-vault npx --no-install wendkeep cost rebuild --session --json --vault .MyApp-vault --apply ``` ## Expected result Doctor separates structural errors, workflow attention, repairable debt, and semantic ambiguity. It names sessions, registry, links, notes, prices, derived sections, and memory as healthy or provides a specific diagnostic/repair command. For memory, it distinguishes a valid initial empty state, recoverable pending replay, key-scoped conflicts, and lost/divergent lifecycle state. It never repairs implicitly or echoes private projector-error content into its report. For session observability, it separates fresh `none`/`complete` from legacy, degraded, stale, or manifest-unproven state and gives a dry-run path before any write. ## Common errors and diagnosis - `no vault`: run from the bound root or pass `--vault`. - `defs stale`: confirm the version and run `sync-defs --reseed`. - Legacy vault: this is a non-blocking warning; doctor shows `npx --no-install wendkeep memory migrate --apply --vault ` with the resolved Vault, but migration remains opt-in and must be planned separately. - `degraded` plus an intact outbox: warning; preserve the outbox and allow idempotent replay. - Ambiguous publication, lost publication, or a mismatched checkpoint: blocking; preserve registry, ledger, outbox, and SHARED so `last_memory_attempt` can be correlated before repair. - Corrupt bundle: preserve evidence and run `memory status --gate` before `memory repair`. - An active semantic conflict degrades only the affected memory key and requires a human decision: `memory repair` does not choose a winner. Start with the guided menu `memory curate --vault `. For advanced inspection or a non-interactive terminal, list safe IDs with `memory candidates --active --vault `, review the evidence, and then use `memory promote --event --vault ` to select an event or `memory reject --vault ` to keep the current operational value. - Historical handoffs from closed sessions are repairable debt, not actionable conflicts. Run `memory rescope --vault ` first and review the dry run, then apply with `--apply`. If debt remains, `memory curate --all --vault ` shows context and offers `H` to batch-close safe recommendations only, always after confirmation. - `legacy`/`degraded`/`stale`/`manifest-unproven` observability: run `npx --no-install wendkeep cost rebuild --session --json --vault `, review diagnostics, and only then authorize the second variant with `--apply`. ## Next steps See [installation and first use](getting-started.md), [memory](memory.md), and [change verification](verify.md).