# aura doctor

*Diagnose repository health; optionally fix common issues in place.*

## Synopsis

```bash
aura doctor [--fix] [--reindex] [--check=<id>...] [--verbose] [--json]
```

## Description

`aura doctor` runs a battery of diagnostic checks over the Aura installation in the current repository and reports their results. Each check has an id, a severity, a human-readable finding, and — for most checks — a `--fix` path that repairs the issue automatically. Running `aura doctor` with no flags performs the checks read-only; running with `--fix` applies repairs for every check that has a safe automatic remediation and prints a summary of what was changed. Checks with dangerous remediations (for example, deleting orphaned snapshots older than 30 days) are never auto-fixed; they print the exact command you would run.

The intended cadence is: run `aura doctor` when something feels off, when `aura status` reports a warning, after pulling a large batch of teammate changes, and as part of CI (`aura doctor --json`). It is idempotent and safe.

## What it checks

Checks are grouped into five categories. Ids are stable across versions so you can allowlist or suppress them in `aura.toml`.

### Index and semantic state

- `IDX001` — semantic index exists and is readable.
- `IDX002` — index age vs working tree age; triggers a suggestion to reindex if stale.
- `IDX003` — no AST parse errors on tracked files. Parse errors are reported per-file.
- `IDX004` — no orphaned logic nodes (nodes whose source file no longer exists).
- `IDX005` — shadow branch in sync with primary branch.

### Sessions and snapshots

- `SES001` — no stuck sessions from previous process crashes. Fixable.
- `SES002` — session lock file belongs to a live process. Fixable (removes stale locks).
- `SNP001` — snapshot storage integrity (hashes match contents).
- `SNP002` — orphaned snapshots older than 30 days. Not auto-fixed; printed as a command.
- `SNP003` — snapshot directory size within `snapshot.max_storage_mb` (default 500 MB).

### Git integration

- `GIT001` — pre-commit hook is installed and current version.
- `GIT002` — post-merge hook is installed.
- `GIT003` — `.gitignore` includes `.aura/` excluding the bits meant to be versioned.
- `GIT004` — no unmerged paths left from a previous `aura merge`.
- `GIT005` — current branch has a Git remote configured.

### Mothership and team sync

- `MOT001` — mothership endpoint reachable.
- `MOT002` — auth token is valid and not near expiry.
- `MOT003` — outgoing delta queue not stalled (no pending delta older than 10 minutes).
- `MOT004` — incoming cursor not behind by more than `sync.max_lag_deltas` (default 500).
- `MOT005` — clock skew vs Mothership under 5 seconds.

### Configuration

- `CFG001` — `aura.toml` parses and matches the current schema version.
- `CFG002` — strict-mode settings consistent between local and team config.
- `CFG003` — registered proofs can still be grounded (otherwise they would false-fail).
- `CFG004` — no deprecated config keys remaining.

## Flags

| Flag | Description |
| --- | --- |
| `--fix` | Apply automatic remediations for any check that has one. |
| `--reindex` | Force a full semantic reindex before running checks. |
| `--check=<id>...` | Run only the listed checks. Comma-separated or repeatable. |
| `--verbose` | Print the steps each check performs. |
| `--json` | Machine-readable output for CI. |

## Output format

```text
aura doctor  (repo: aura-cli  v0.12.6)

Index and semantic state
  ok      IDX001  index present (1,842 nodes)
  warn    IDX002  index is 14m old (threshold: 10m)            suggest: aura doctor --reindex
  ok      IDX003  no parse errors
  fail    IDX004  3 orphaned nodes (files removed outside of aura)
                  fixable: --fix will prune them

Sessions and snapshots
  ok      SES001  no stuck sessions
  ok      SES002  session lock belongs to pid 44121 (this process)
  warn    SNP002  14 snapshots older than 30 days (not auto-fixed)
                  run: aura snapshot gc --older-than 30d

Git integration
  ok      GIT001  pre-commit hook current (v12)
  fail    GIT002  post-merge hook missing
                  fixable: --fix will install it

Mothership and team sync
  ok      MOT001  origin-mothership reachable (47 ms)
  ok      MOT002  token valid until 2026-07-14
  warn    MOT003  1 delta pending for 12 minutes (teammate offline?)
  ok      MOT004  cursor lag: 0
  ok      MOT005  clock skew: 0.4s

Configuration
  ok      CFG001  aura.toml schema: v3
  ok      CFG002  strict-mode consistent
  ok      CFG003  4 proofs ground cleanly
  ok      CFG004  no deprecated keys

Summary:  ok 15  warn 3  fail 2
Run `aura doctor --fix` to apply 2 automatic remediations.
```

Severities are:

| Severity | Meaning |
| --- | --- |
| `ok` | No action needed. |
| `warn` | Degraded but functional. Usually fixable, sometimes intentional. |
| `fail` | Aura will not function correctly until addressed. |

## Examples

### 1. Read-only diagnostic

```bash
aura doctor
```

### 2. Fix everything fixable

```bash
aura doctor --fix
```

```text
Applying fixes...
  IDX004  pruned 3 orphaned nodes
  GIT002  installed post-merge hook
2 fixes applied. Re-running checks:
  ok  IDX004
  ok  GIT002
```

### 3. Scope to one category

```bash
aura doctor --check=MOT001,MOT002,MOT003
```

Runs only the Mothership reachability and auth checks. Good for a quick network triage.

### 4. Force a reindex

```bash
aura doctor --reindex --fix
```

Rebuilds the semantic index from scratch before running checks. Use after a large `git pull`, a branch switch with many changes, or when `IDX002`/`IDX003` are persistent.

### 5. CI usage

```bash
aura doctor --json > aura-doctor.json
# fail the build if any check is 'fail'
jq -e '.checks[] | select(.severity == "fail")' aura-doctor.json && exit 1 || exit 0
```

The JSON output is stable and schema-versioned. A lightweight wrapper can fail the build on any `fail`, or on any `warn` above a configured threshold.

## Common findings

- **`IDX002` stale index.** Normal after long breaks. `--reindex` resolves.
- **`GIT001/GIT002` hook missing.** Happens after `git clone` or after running a third-party `git config core.hooksPath`. `--fix` reinstalls.
- **`MOT001` unreachable.** Check VPN. Aura will continue to work locally; pushes queue until the Mothership is back.
- **`SNP002` old snapshots.** Snapshots are cheap but not free. Run `aura snapshot gc` when prompted.
- **`CFG003` proof ungroundable.** A registered proof is no longer valid because the code it referenced was removed. Either update the proof or delete it from `aura.toml`.

## Exit Codes

| Code | Meaning |
| --- | --- |
| `0` | All checks passed (possibly with warnings, unless `--strict` was set via config). |
| `1` | Generic failure running doctor itself. |
| `2` | One or more checks are at `fail` severity. |
| `3` | `--fix` was requested but one or more fixes could not be applied. |

## When to run it

Run `aura doctor` when any of the following happens: a fresh clone of the repository; a machine migration; the first time after an Aura version upgrade; after a force-push or a history rewrite; after a network outage longer than a few minutes; whenever `aura status` reports a `cached` or `stale` banner; whenever a save unexpectedly fails; whenever a teammate reports that your Mothership presence is stuck.

In healthy day-to-day use, most developers run `aura doctor` perhaps once a week. In CI it runs on every build. The cost is a few hundred milliseconds and a small amount of I/O; there is no reason to avoid it.

## A triage recipe

When `aura doctor` reports several warnings and failures at once, work through them in this order.

First, handle `GIT001`/`GIT002` (hooks missing). Without the hooks, subsequent saves cannot be verified. `--fix` reinstalls them.

Second, handle `IDX003` (parse errors). A file that does not parse has no logic nodes and therefore does not participate in diffs, traces, or proofs. Fix the parse error or exclude the file in `aura.toml`.

Third, handle `IDX002`/`IDX004` (stale or orphaned index). `--reindex` rebuilds from scratch.

Fourth, handle `MOT001`/`MOT002` (Mothership reachability and auth). If these are failing, team sync is offline — confirm network and refresh the token.

Fifth, handle `SNP002`/`SNP003` (snapshot storage). These rarely block anything but can silently bloat the `.aura` directory.

Sixth, handle configuration checks. `CFG003` in particular — a broken proof — will cause `aura pr-review` to report false regressions, which is confusing.

## Suppressing checks

A check can be suppressed in `aura.toml` when it is expected to fail in a given repository:

```text
[doctor.suppress]
IDX002 = { reason = "CI reindexes on entry; staleness is expected locally" }
SNP002 = { reason = "snapshots retained for audit, GC handled externally" }
```

Suppressed checks still run and are printed under a `suppressed` banner, but do not contribute to the exit code. Use suppression sparingly; the goal is to keep the baseline clean so real problems stand out.

## Relationship to CI

In CI, the pattern is:

```bash
aura doctor --json --strict > report.json
```

With `--strict`, warnings are treated as failures. This is stricter than most teams want locally but appropriate as a gate on main. Run the non-strict version in PR checks so warnings surface without blocking.

## See Also

- [aura status](/aura-status) — shows many of the same signals at a glance
- [aura save](/aura-save) — the pre-commit hook checked by `GIT001`
- [aura rewind](/aura-rewind) — uses the snapshots audited by `SNP001`
- [aura prove](/aura-prove) — the proofs audited by `CFG003`