@open-agent-toolkit/cli 0.2.74 → 0.2.76

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.2.74"
+  "oatVersion": "0.2.76"
 }

package/assets/docs/cli-utilities/config-and-local-state.md

@@ -124,7 +124,7 @@ Use `oat config` for repo runtime config inspection and supported key mutation.
 - `oat config list` - show the resolved command-surface values with source information
 - `oat config dump --json` - emit the full merged config payload with per-key source attribution, suitable for automation and debugging
 - `oat config describe` - list supported config surfaces and keys across shared repo, repo-local, user, and sync/provider config
-- `oat config describe <key>` - show file location, scope, default, mutability, and owning command for one key
+- `oat config describe <key>` - show file location, scope, default, mutability, and owning command for one key; a deprecated key also prints a `Deprecated: prefer …` line, and `--json` carries it as a `deprecated` object with `supersededBy` (plus `legacyValues` when only a legacy value form is deprecated), which `oat-doctor` reads
 
 Use `oat config dump --json` when you need the whole resolved config in one machine-readable response rather than a single key or a human-oriented list view.
 
@@ -281,6 +281,6 @@ For the full state model, repair semantics, and examples, see [Instruction Sync]
 - `oat internal validate-oat-skills` - validate `oat-*` skill contracts and metadata
 - `oat doctor` - run environment and setup diagnostics, including installed-vs-bundled skill version checks
 
-`oat doctor` is the quickest way to confirm that your runtime, directory structure, and installed OAT assets are healthy before deeper debugging. At project scope it also scans bounded repository script and documentation surfaces for known-stale CLI grammar, such as `oat --scope all sync`, and reports file/line evidence plus the current `oat sync --scope all` form. Generated provider views, OAT lifecycle artifacts, archived content, dependencies, build output, and nested worktrees are excluded.
+`oat doctor` is the quickest way to confirm that your runtime, directory structure, and installed OAT assets are healthy before deeper debugging. At project scope it also scans bounded repository script and documentation surfaces for known-stale CLI grammar, such as `oat --scope all sync` <!-- oat-doctor: allow-stale-invocation -->, and reports file/line evidence plus the current `oat sync --scope all` form. Generated provider views, OAT lifecycle artifacts, archived content, dependencies, build output, and nested worktrees are excluded.
 
-The `/oat-doctor` skill (installed via the core pack) provides richer diagnostics with check and summary modes, including config explanations sourced from bundled documentation.
+The `/oat-doctor` skill (installed via the core pack) goes further: it sweeps config, project management (PJM), agent instructions, docs, and installed tools read-only, prints one report grouped by area and severity, and then dives into any area you pick, teaching from the bundled documentation and the `oat config describe` entries and offering the exact fix command or the owning skill. It applies nothing except a single fix command you approve. Unattended (`OAT_NON_INTERACTIVE=1`), the report is the whole output; `--summary` keeps the installed-tools dashboard.

package/assets/docs/cli-utilities/configuration.md

@@ -54,7 +54,9 @@ What each command is for:
 - `oat config set <key> <value>` updates supported shared or repo-local keys.
 - `oat config unset <key>` removes a supported key from one surface, using the same `--shared`/`--local`/`--user` flags and per-key restrictions as `set`. The resolved value then falls back to the next surface down, or to the built-in default. A key the surface does not hold exits 0 as already-unset (`--json` adds a `removed` boolean to tell the two apart). Unknown keys, lifecycle state, `tools.*` pack intent, aggregate read views, read-only remote-policy structure, and environment-shadowed keys with nothing stored are refused with exit 1 — see [CLI Reference](../reference/cli-reference.md#oat-config-surface-flags).
 - `oat config describe` shows the supported config catalog across shared repo, repo-local, user, and sync/provider surfaces.
-- `oat config describe <key>` shows file, scope, default, mutability, owning command, and description for one key.
+- `oat config describe <key>` shows file, scope, default, mutability, owning command, and description for one key. A deprecated key also prints `Deprecated: prefer <successor>`, and `--json` carries the same fact as a `deprecated` object (`supersededBy`, plus `note` and `legacyValues` where they apply).
+
+For a guided pass instead of individual commands, run the `/oat-doctor` skill (core pack). It sweeps every config surface read-only, flags stale `activeProject` / `lastPausedProject` pointers, keys set on the wrong surface, and deprecated values, then walks each key group you have not set: what it does, when you would want it, and which surface owns it. It offers the exact `oat config` command for each fix and runs one only after you approve it. See [Config and Local State](config-and-local-state.md#internal-helpers-and-diagnostics) for the other areas it covers.
 
 ### Source labels
 

package/assets/docs/cli-utilities/index.md

@@ -31,6 +31,7 @@ Examples include:
 - general configuration guidance
 - workflow gate commands for per-skill final checks and cross-runtime review dispatch
 - utility command groups for config, local state, diagnostics, and related inspection flows
+- a guided health check, the `/oat-doctor` skill, that sweeps config, project management, agent instructions, docs, and installed tools, then explains and offers fixes for what it finds (described in [Config and Local State](config-and-local-state.md))
 
 ## Who It's For
 

package/assets/docs/cli-utilities/tool-packs.md

@@ -850,7 +850,7 @@ packs and is retained while either pack still owns it in that scope.
 
 The `core` pack contains foundational diagnostic and documentation skills:
 
-- **oat-doctor** — Setup diagnostics with two modes: check mode (terse `brew doctor`-style warnings with fix commands) and summary mode (full dashboard of installed packs, config values, and sync status).
+- **oat-doctor** — One read-only sweep over config, PJM, agent instructions, docs, and tools; a report grouped by area and severity; then a dive into any area on request that explains findings and unset settings from the bundled docs and offers the exact fix command or the owning skill (nothing is applied without approval). `--summary` keeps the installed-tools dashboard.
 - **oat-docs** — Interactive Q&A skill backed by locally-bundled OAT documentation at `~/.oat/docs/`.
 
 Key behavior:

package/assets/docs/reference/file-locations.md

@@ -62,7 +62,7 @@ Pack intent is stored per scope:
 Config discovery via CLI:
 
 - `oat config describe` lists the supported config surfaces and keys across `.oat/config.json`, `.oat/config.local.json`, `~/.oat/config.json`, `.oat/sync/config.json`, and `~/.oat/sync/config.json`.
-- `oat config describe <key>` shows file location, scope, default, mutability, and the owning command for one key.
+- `oat config describe <key>` shows file location, scope, default, mutability, and the owning command for one key, and for a deprecated key its successor.
 - `oat config list` shows the currently resolved values for the repo-local/shared command surface.
 
 Config ownership note:

package/assets/docs/reference/oat-directory-structure.md

@@ -104,7 +104,7 @@ Current config ownership:
 CLI discovery surfaces:
 
 - `oat config describe` lists the supported config surfaces and keys across shared repo, repo-local, user, and sync/provider config.
-- `oat config describe <key>` prints scope, file, default, mutability, owning command, and description for one config key.
+- `oat config describe <key>` prints scope, file, default, mutability, owning command, and description for one config key, plus a `Deprecated: prefer …` line when the key is deprecated.
 - `oat config list` prints the resolved values for the repo-scoped/local command surface.
 
 Legacy `.oat/active-project` / `.oat/projects-root` / `.oat/active-idea` files may still be present in some environments but are no longer the canonical source in migrated command paths.

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.74",
-  "docs-config": "0.2.74",
-  "docs-theme": "0.2.74",
-  "docs-transforms": "0.2.74"
+  "cli": "0.2.76",
+  "docs-config": "0.2.76",
+  "docs-theme": "0.2.76",
+  "docs-transforms": "0.2.76"
 }

package/assets/skills/oat-doctor/SKILL.md

@@ -1,47 +1,49 @@
 ---
 name: oat-doctor
-description: Use when you need to diagnose your OAT setup, check for outdated skills, identify misconfigurations, or get a summary of installed tools and config. Runs health checks and recommends corrective actions.
+description: Use when you want to check the health of your OAT setup in one place — config, project management (PJM), agent instructions, docs, and installed tools — and then work through what it finds. Sweeps read-only, reports by area, and dives into an area on request, teaching from the bundled docs and offering exact fix commands.
 argument-hint: '[--summary]'
 disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Bash, Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.2.4
+  version: 2.0.0
 ---
 
 # OAT Doctor
 
-Diagnose your OAT setup at both project and user levels. Checks for skill updates, identifies misconfigurations, summarizes what's installed, and recommends corrective actions.
+One place to look at everything OAT knows about this checkout and this user. A run has three stages: a read-only **sweep** over five areas, a grouped **report**, and a **dive** into any area the person picks. Dives teach from the bundled docs and offer fixes; they do not apply them.
 
 ## Prerequisites
 
 - OAT CLI installed and available as `oat` in PATH.
-- At least one `oat init` has been run (project or user level).
+- At least one `oat init` has been run (project or user level). When nothing is initialized, the sweep still runs: every area then offers its bootstrap.
 
 ## Mode Assertion
 
 **OAT MODE: Doctor (Diagnostic)**
 
-**Purpose:** Inspect OAT setup and report findings with actionable fix commands. Never modify files or configuration.
+**Purpose:** Inspect OAT setup, explain what it finds, and offer the exact fix. The sweep and the dives never write.
 
 **BLOCKED Activities:**
 
-- No editing configuration files, skills, or templates.
-- No running `oat init`, `oat sync`, `oat tools update`, or any mutating commands.
-- No creating, modifying, or deleting any files.
+- No editing configuration files, skills, templates, instruction files, PJM files, or docs.
+- No creating, modifying, or deleting any file.
+- No running any mutating command, with exactly one carve-out below.
+
+**The one carve-out:** after a dive has named a fix as one of `oat config set`, `oat config unset`, `oat config adopt`, `oat pjm init`, `oat instructions sync`, `oat tools update`, or `oat tools install`, and the person has approved that exact command, run it once and report the result. Nothing else is ever run; a hand-off to another skill (`oat-docs-bootstrap`, `oat-agent-instructions-analyze`, `oat-agent-instructions-apply`, `oat-pjm-*`) is an invocation the person starts.
 
 **ALLOWED Activities:**
 
-- Running `oat` CLI commands with `--json` flag for read-only data gathering.
-- Reading files to inspect configuration state.
-- Reading `~/.oat/docs/` for config key explanations.
-- Presenting diagnostic findings and recommendations to the user.
+- Running `oat` CLI commands with `--json` for read-only data gathering, projected to the fields named below.
+- Reading files to inspect state, and reading `~/.oat/docs/` to explain it.
+- Presenting findings, explanations, and recommendations.
 
 **Self-Correction Protocol:**
 If you catch yourself:
 
-- About to run a mutating command → STOP and present it as a recommendation instead.
-- Editing a file to fix a problem → STOP and tell the user the fix command.
+- About to run a mutating command that is not the one approved carve-out → STOP and present it as a recommendation instead.
+- Editing a file to fix a problem → STOP and tell the person the fix command or the owning skill.
+- Explaining a config key from memory → STOP and read the `describe` entry and the docs section named for its group.
 
 **Recovery:**
 
@@ -56,21 +58,11 @@ Print a phase banner once at start:
 OAT ▸ DOCTOR
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-### Check Mode (default)
-
-- `[1/4] Gathering installed tools…`
-- `[2/4] Checking for outdated skills…`
-- `[3/4] Inspecting configuration…`
-- `[4/4] Reporting findings…`
+- `[1/3] Sweeping config, PJM, agent instructions, docs, and tools…`
+- `[2/3] Reporting findings…`
+- `[3/3] Diving into {area}…` (once per dive)
 
-### Summary Mode (`--summary`)
-
-- `[1/6] Gathering installed tools…`
-- `[2/6] Checking for outdated skills…`
-- `[3/6] Inspecting configuration…`
-- `[4/6] Discovering available packs…`
-- `[5/6] Checking sync status…`
-- `[6/6] Building dashboard…`
+Summary mode (`--summary`) prints `[1/2] Gathering installed tools…` and `[2/2] Building dashboard…` instead.
 
 ## Process
 
@@ -78,157 +70,172 @@ OAT ▸ DOCTOR
 
 Read `$ARGUMENTS`:
 
-- If `$ARGUMENTS` contains `--summary` → **summary mode**
-- Otherwise → **check mode** (default)
+- `--summary` → **summary mode** (Step 4 only).
+- Otherwise → **sweep mode** (Steps 1–3).
 
-### Step 1: Gather Installed Tools
+Report-only rule: when `OAT_NON_INTERACTIVE=1` is set, or no user-response channel exists, the run ends after Step 2's report. Never prompt in that case, and never run a fix.
 
-```bash
-TOOLS_JSON=$(oat tools list --json --scope all 2>/dev/null || echo '{"tools":[]}')
-```
+### Step 1: Sweep
 
-Parse the JSON output. Each tool has: `name`, `type` (skill/agent), `scope` (project/user), `version`, `bundledVersion`, `pack` (core/docs/ideas/workflows/utility/project-management/research/custom), `status` (current/outdated/newer/not-bundled).
+Run the seven commands below and the four file checks. Every command call is projected to the fields named here with `node -e` (or `jq` when present); never print or read a raw payload — `oat doctor --json` is about 410 KB and `oat tools list --json` about 626 KB on a mid-sized repository, and neither fits a working context.
 
-### Step 2: Check for Outdated Skills
+A command has **failed** only when its stdout does not parse as JSON, or the process is killed or times out. A non-zero exit with parseable JSON is a findings result: `oat doctor` and `oat pjm doctor` both exit 1 whenever any check warns, which is the normal state of a healthy repository. A failed command becomes one `warning` finding for its area whose summary names the command and quotes the first line of stderr; the sweep continues.
 
-```bash
-OUTDATED_JSON=$(oat tools outdated --json --scope all 2>/dev/null || echo '{"tools":[]}')
-```
+| #   | Command                                 | Projection                                                                               | Feeds                                        |
+| --- | --------------------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------- |
+| 1   | `oat doctor --json --scope all`         | `.checks[] \| {name, status, message}` — drop `packEvidence` and `providerRefreshAdvice` | config, tools, docs (by the check map below) |
+| 2   | `oat pjm doctor --json`                 | `.adoption` and `.checks[] \| {name, status, message}`                                   | PJM                                          |
+| 3   | `oat config dump --json`                | `.shared`, `.local`, `.user` (the three surface objects)                                 | config, docs                                 |
+| 4   | `oat config describe --json`            | `.entries[] \| {key, group, file, scope, defaultValue, owningCommand, deprecated}`       | config                                       |
+| 5   | `oat instructions validate --json`      | `.summary` and `.entries[] \| select(.status != "ok") \| {agentsPath, status, detail}`   | agent instructions                           |
+| 6   | `oat tools list --json --scope all`     | `.tools[] \| {name, pack, scope, status}`                                                | tools                                        |
+| 7   | `oat tools outdated --json --scope all` | `.tools[] \| {name, version, bundledVersion, scope}`                                     | tools                                        |
 
-Parse the JSON output. Each entry has `name`, `version` (installed), `bundledVersion` (available), `pack`, `scope`.
+File checks (read-only):
 
-### Step 3: Inspect Configuration
+- **Root instructions headings.** Read `AGENTS.md` at the repository root (and `CLAUDE.md` when it is a file rather than a pointer). Note which of these headings are present: `## Tool Packs` (written by `oat tools install --project-guidance`), `### Project Management` and `### Decision Records` (written by `oat pjm init`), `## Documentation` (written by `oat docs init` / `oat-docs-bootstrap`).
+- **Sync config surfaces.** Read `.oat/sync/config.json` and `~/.oat/sync/config.json` when present, keys only. `oat config dump` does not carry the `Sync/Provider` and `User Sync` groups, so this is their only set-state source.
+- **Docs surface.** Detect an existing docs surface the way `oat-docs-bootstrap`'s preflight does: `documentation.root` in the dump; a docs app under `apps/docs` or `apps/*-docs`, or any `apps/*` with a `source.config.*`, a `next.config.*` beside a `docs/` directory, or `mkdocs.yml`; a root `mkdocs.yml`; a root `docs/` or `documentation/` directory.
+- **`documentation.root` on disk.** When the dump sets it, check that the directory exists.
 
-```bash
-CONFIG_JSON=$(oat config list --json 2>/dev/null || echo '{"configs":[]}')
-```
+#### Finding rules
 
-Check for issues:
+Each finding is one line with an **area**, a **severity**, a one-line **summary**, its **evidence** (a check name, a key and its surface, or a file path), and a **fix path** (an exact command, an owning skill, or none). Severities:
 
-- **Stale `activeProject` pointer:** If `activeProject` is set, verify the directory exists. If not, warn.
-- **Stale `activeIdea` pointer:** If `activeIdea` is set, verify the directory exists. If not, warn.
-- **Missing `projects.root`:** If not configured and no default exists, warn.
-- **Synced project health:** Report `project:synced_tracked_artifacts`,
-  `project:synced_gitignore`, `project:synced_projects`,
-  `project:synced_editor_hint`, and per-project
-  `project:synced_<slug>_<kind>` checks without treating an absent checkout as
-  proof that no synced project exists.
+- `error` — a lifecycle skill would fail or write to the wrong place.
+- `warning` — drift the person should fix soon.
+- `info` — a teaching opportunity or a fact with no fix path.
 
-For config key explanations, read from the bundled docs at `~/.oat/docs/`. Check `reference/file-locations.md` and `guide/cli-reference.md` for authoritative descriptions.
+**Config**
 
-### Step 4: Check Mode — Report Findings
+- `activeProject` or `lastPausedProject` set to a path that does not exist → `error`; fix `oat config set activeProject ''` / `oat config set lastPausedProject ''` (the CLI refuses `unset` for these two lifecycle keys). `activeIdea` set to a missing path → `error`; fix `oat config unset activeIdea --local` (or `--user` for a user-level value).
+- A set key whose `describe` entry carries `deprecated` → `warning`; summary names the key and its `deprecated.supersededBy`; when `deprecated.legacyValues` is present the finding fires only when the set value is one of those values; fix = the entry's `owningCommand` for the successor.
+- A key set on a surface that is not one of the surfaces its `describe` entry's `file` names → `warning`; fix `oat config unset <key> --<surface>` then `oat config set <key> <value> --<right surface>`.
+- The `dispatch-matrix` recommendation is reported only through the `project:dispatch_matrix` check (command 1, config area); there is no separate rule for it, so one gap is one finding. Its fix is `oat config adopt dispatch-matrix --shared`, and the config dive explains it from `workflow.dispatchCeiling.recommendationVersion` in the dump.
+- A documented key group with nothing set on any surface → one `info` per group, expanded only in the dive.
+- Synced project health: `project:synced_tracked_artifacts`, `project:synced_gitignore`, `project:synced_projects`, `project:synced_editor_hint`, and per-project `project:synced_<slug>_<kind>` checks from command 1 → severity from status, summary from the message; report them without treating an absent checkout as proof that no synced project exists (an absent checkout is materialized by `oat project pull`, which the check's message names).
 
-If in **check mode**, output a terse, `brew doctor`-style checklist.
+**PJM**
 
-**Format:**
+- `adoption.state` `none` → `error` (PJM not adopted; fix `oat pjm init`); `partial-initialization` → `error` (declared but canonical files missing; fix `oat pjm init`, which completes the layout); `inferred-legacy` → `warning` (a pre-adoption layout the CLI recognizes; fix `oat pjm init` to declare it); `declared` is healthy.
+- Any other `pjm:*` check with status `fail` → `error`; `warn` → `warning`; the fix path is the one the check's message implies (see the PJM dive for the map). `pjm:adoption` is excluded here: the `adoption.state` rule above owns adoption, so it is one finding with one severity.
+- A `pjm:*` check name the PJM dive does not know → `info` with its message.
 
-```
-Your OAT setup has {N} warning(s).
+**Agent instructions**
 
-⚠  {N} outdated skill(s)
-   Run: oat tools update --scope {scope}
+- An entry with status `missing` or `content_mismatch` (the entry literal; the summary counter is spelled `contentMismatch`) → `error`; fix `oat instructions sync` (`--force` for a content mismatch the person confirms is stale).
+- An entry with status `stray` → `warning`; fix `oat instructions sync` after the person decides whether the stray file should exist.
+- A CLI-written heading absent while its capability is present → `warning`: no `## Tool Packs` while any pack is installed at project scope (fix `oat tools install <pack> --project-guidance`); no `### Project Management` or `### Decision Records` while PJM adoption is `declared` (fix `oat pjm init`, which rewrites the guidance); no `## Documentation` while a docs surface exists (fix: `oat-docs-bootstrap`).
+- Content quality beyond presence is not judged here; route to `oat-agent-instructions-analyze`.
 
-⚠  Stale activeProject pointer: {path} does not exist
-   Run: oat config set activeProject ""
+**Docs**
 
-⚠  Stale activeIdea pointer: {path} does not exist
-   Run: oat config set activeIdea ""
+- A docs surface detected with no `documentation` config → `warning`; fix: run `oat-docs-bootstrap`, which detects the existing surface and offers the audit.
+- `documentation.root` set but absent on disk → `error`; fix `oat config unset documentation.root --shared` or `oat-docs-bootstrap`.
+- No docs surface and no `documentation` config (an uninitialized or docs-less repository) → `info`; fix: run `oat-docs-bootstrap` to set one up. This is what makes an empty repository offer its docs bootstrap alongside the other areas.
 
-⚠  {pack} pack not installed at {scope} scope
-   Run: oat init tools
-```
+**Tools**
 
-If no warnings:
+- An outdated tool → `warning`; fix `oat tools update <name> --scope <scope>` (or `oat tools update --scope <scope>` for all).
+- The same pack installed at both scopes → `warning`; fix `oat tools migrate --pack <pack> --from project --to user` (or the reverse).
+- A pack enabled under `tools.*` in the dump but with no installed skill → `warning`; fix `oat tools install <pack>`.
 
-```
-Your OAT setup looks good. No issues found.
-```
-
-Stop here for check mode.
-
-### Step 5: Summary Mode — Discover Available Packs
+**`oat doctor` checks** (command 1). Any check with status `fail` or `warn` becomes a finding, severity from status, evidence = the check name, summary = its message, by this map (a semantic map, not a prefix rule):
 
-For summary mode, compare installed skills against the full manifest to identify available-but-uninstalled packs and skills.
+| Check names                                                                                                                                                                                                                                                         | Area                                                                             |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `project:dispatch_matrix`, `project:synced_*`                                                                                                                                                                                                                       | config                                                                           |
+| `project:manifest`, `project:providers`, `project:symlink_support`, `project:canonical_directories`, `project:codex_*`, `project:skill_versions`, `project:cursor_materialized_models`, and their `user:` twins; `project:pack_state`, `user:pack_state`, `packs:*` | tools                                                                            |
+| `project:stale_invocations`                                                                                                                                                                                                                                         | docs (it cites doc and script file:line)                                         |
+| `pjm:*`                                                                                                                                                                                                                                                             | suppressed — `oat pjm doctor` reports the same checks and the PJM area owns them |
+| any other name                                                                                                                                                                                                                                                      | `info` in tools, with the message                                                |
 
-**Bundled skill manifest (source of truth):**
+### Step 2: Report
 
-Each heading below names a pack exactly as `oat tools install <pack>` expects
-it, and lists every skill that pack ships.
+Print the findings grouped by area in this order: config, PJM, agent instructions, docs, tools. Within an area, errors first, then warnings. Print `info` findings as one count per area; they expand only in a dive. An area with no findings prints `(ok)`.
 
-`core` pack skills:
-
-- oat-docs, oat-doctor
-
-`ideas` pack skills:
+```text
+OAT ▸ DOCTOR
+Config (1 error, 1 warning, 4 info)
+  ✖ activeProject points at .oat/projects/shared/x, which does not exist   [config.local]
+    → oat config set activeProject ''
+  ⚠ workflow.postImplementSequence uses the legacy value "docs-pr"         [shared]
+    → prefer the structured form: oat config describe workflow.postImplementSequence
+PJM (ok)
+Agent instructions (1 warning)
+  ⚠ AGENTS.md has no "### Project Management" section although PJM is adopted   [AGENTS.md]
+    → oat pjm init   (or: run oat-agent-instructions-analyze)
+Docs (1 warning)
+  ⚠ docs/ exists but .oat/config.json has no documentation section          [docs/]
+    → run oat-docs-bootstrap; it detects the surface and offers the audit
+Tools (ok)
+```
 
-- oat-idea-new, oat-idea-ideate, oat-idea-summarize, oat-idea-scratchpad
+When every area is `(ok)` and no `info` exists, print `Your OAT setup looks good. No issues found.` and stop.
 
-`docs` pack skills:
+Under the report-only rule, stop here. Otherwise ask, with `AskUserQuestion`, which area to dive into: offer each area that has findings (errors, warnings, or info), plus `all` and `done`. Repeat after each dive until the person picks `done`.
 
-- authoring-docs, oat-agent-instructions-analyze
-- oat-agent-instructions-apply, oat-docs-analyze
-- oat-docs-apply, oat-docs-authoring, oat-docs-bootstrap
+### Step 3: Dives
 
-`workflows` pack skills:
+Every dive has the same shape:
 
-- oat-cursor-cloud-projects, oat-explainer-kit, oat-project-autonomous
-- oat-project-capture, oat-project-clear-active, oat-project-complete
-- oat-project-design, oat-project-dispatch-subagents, oat-project-discover
-- oat-project-document, oat-project-implement, oat-project-import-plan
-- oat-project-lite, oat-project-new, oat-project-next, oat-project-open
-- oat-project-plan, oat-project-plan-writing, oat-project-pr-final
-- oat-project-pr-progress, oat-project-progress, oat-project-promote-spec-driven
-- oat-project-quick-start, oat-project-reconcile, oat-project-retro
-- oat-project-retro-file, oat-project-revise, oat-project-review-provide
-- oat-project-review-provide-remote, oat-project-review-receive
-- oat-project-review-receive-remote, oat-project-spec, oat-project-split
-- oat-project-summary, oat-repo-knowledge-index, oat-worktree-bootstrap
-- oat-worktree-bootstrap-auto, oat-wave-execute, oat-wave-program
-- oat-wrap-up
+1. **Restate** the area's findings with their evidence, expanding the `info` lines.
+2. **Teach** from the bundled docs and, for config, from the `describe` entries: name the page and section, read it at run time, and explain in two or three sentences what the thing does, when the person would want it, and which surface owns it. Quote nothing from memory. When `~/.oat/docs/` is absent, say so and offer `oat tools install core`; do not invent an explanation.
+3. **Answer** the person's questions from the same sources.
+4. **Offer** each fix as the exact command (the `describe` entry's `owningCommand` for config keys) or the owning skill, then stop. If the person approves a listed carve-out command, run that one command and report the result; otherwise the person runs it.
 
-`utility` pack skills:
+Docs citations below name a page under `~/.oat/docs/` (the same tree as `apps/oat-docs/docs/`) and a `##` heading; a citation must be a prefix of the real heading.
 
-- create-agnostic-skill, explainer-kit, oat-dispatch-subagents
-- subagent-orchestration, oat-repo-improve, oat-repo-maintainability-review
-- oat-review-provide, oat-review-provide-remote, oat-review-receive
-- oat-review-receive-remote
+#### Config dive
 
-`project-management` pack skills:
+Walk every distinct `group` value in the `describe` output — nine today, including `PJM Remote Shared Policy`, `Explainer Defaults (local > shared)`, and `User Sync (~/.oat/sync/config.json)`; never a hard-coded list. For each group, say what is set (from the dump or the sync files), what is deprecated, and what is unset; for an unset group, teach it from the entry descriptions and its docs section:
 
-- oat-pjm-add-backlog-item, oat-pjm-decision, oat-pjm-remote
-- oat-pjm-update-repo-reference, oat-pjm-review-backlog
+| Group                                                              | Docs section                                                                    |
+| ------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
+| The five surfaces themselves (which file owns what)                | `cli-utilities/configuration.md` § The five config surfaces                     |
+| `Shared Repo (.oat/config.json)`                                   | `cli-utilities/configuration.md` § Shared repo config you will touch most often |
+| `Repo Local (.oat/config.local.json)`, `User (~/.oat/config.json)` | `cli-utilities/configuration.md` § Repo-local and user state                    |
+| `Workflow Preferences` (dispatch policy keys)                      | `cli-utilities/configuration.md` § Dispatch policy resolution                   |
+| `Workflow Preferences` (everything else)                           | `cli-utilities/configuration.md` § Workflow preferences                         |
+| `Workflow Preferences` (gate keys)                                 | `cli-utilities/workflow-gates.md` § Gate config                                 |
+| `Sync/Provider`, `User Sync`                                       | `cli-utilities/configuration.md` § Provider sync config is different            |
+| `PJM Remote Shared Policy`                                         | `cli-utilities/remote-project-management.md`                                    |
+| the `pjm.*` keys under Shared Repo                                 | `cli-utilities/backlog-lifecycle.md` § Adoption comes first                     |
+| `Explainer Defaults`                                               | the entry descriptions (`oat config describe explainers.defaults.style`)        |
 
-`research` pack skills:
+A deprecated key is explained through its `deprecated.supersededBy` and the successor's `owningCommand`.
 
-- analyze, compare, deep-research
-- recon, skeptic, synthesize
+#### PJM dive
 
-`brainstorm` pack skills:
+State the adoption state (`declared`, `inferred-legacy`, `partial-initialization`, or `none`) and what it means (`cli-utilities/backlog-lifecycle.md` § Adoption comes first). Then each non-passing check and its fix:
 
-- oat-brainstorm
+| Check                                                                                                                                                                                                                                         | Fix path                                                                                                                                                                         |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pjm:adoption`                                                                                                                                                                                                                                | not reported separately: the `adoption.state` rule owns it; fix `oat pjm init`                                                                                                   |
+| `pjm:canonical_files`, `pjm:template_frontmatter`, `pjm:top_level_layout`                                                                                                                                                                     | `oat pjm init` re-creates canonical files; unknown top-level folders are the person's to move (`cli-utilities/backlog-lifecycle.md` § Catching lifecycle drift)                  |
+| `pjm:legacy_monoliths`, `pjm:loose_reference_files`, `pjm:second_roadmap`                                                                                                                                                                     | structural drift: `cli-utilities/backlog-lifecycle.md` § Catching lifecycle drift and the migration guidance it links; `oat-pjm-update-repo-reference` for the reference records |
+| `pjm:backlog_terminal_in_items`, `pjm:backlog_completed_unarchived`                                                                                                                                                                           | `oat backlog archive <id>` for each named item, then `oat backlog regenerate-index`                                                                                              |
+| `pjm:backlog_invalid_status`, `pjm:backlog_archived_open`, `pjm:backlog_duplicate_id`                                                                                                                                                         | edit the named item's frontmatter (the person), then `oat backlog regenerate-index`                                                                                              |
+| `pjm:remote_schema`, `pjm:remote_binding_ids`, `pjm:remote_metadata_state`, `pjm:remote_storage_content`, `pjm:remote_policy`, `pjm:remote_concurrent_intents`, `pjm:remote_operations`, `pjm:remote_retention`, `pjm:remote_host_capability` | emitted only when a remote binding is adopted: `oat-pjm-remote` (reconcile or refresh) and `cli-utilities/remote-project-management.md`                                          |
+| any other `pjm:*` name                                                                                                                                                                                                                        | `info` with the check's message; no fix path is invented                                                                                                                         |
 
-For each pack, determine:
+#### Agent instructions dive
 
-- **Installed:** all pack skills found in installed tools list
-- **Partially installed:** some but not all pack skills found
-- **Not installed:** no pack skills found
-- **Missing skills:** specific skills in the manifest but not in installed list (highlights newly-added skills after CLI upgrades)
+Explain the sync strategy in use (`oat instructions validate --json` `.summary`) and each non-`ok` entry with its path. Explain each missing heading: what the CLI writes there and why an agent needs it (`cli-utilities/bootstrap.md` for `## Tool Packs`; `cli-utilities/backlog-lifecycle.md` § Adoption comes first for the PJM sections). Offer `oat instructions sync`, `oat tools install <pack> --project-guidance`, or `oat pjm init` as the finding names; for wording and coverage beyond presence, hand off to `oat-agent-instructions-analyze` then `oat-agent-instructions-apply`.
 
-### Step 6: Summary Mode — Check Sync Status
+#### Docs dive
 
-If in a project directory (`.oat/` exists):
+Say what surface was detected and what `documentation.*` says. This dive owns no docs logic: hand off to `oat-docs-bootstrap`, which detects the existing surface and offers the audit (`oat-docs-analyze` then `oat-docs-apply`), or `oat config unset documentation.root --shared` when the root is gone.
 
-```bash
-SYNC_STATUS=$(oat sync --dry-run --json --scope project 2>/dev/null || echo '{}')
-```
+#### Tools dive
 
-Report whether provider views are in sync or have pending changes.
+List outdated tools with installed and bundled versions and scope, packs at both scopes, and packs enabled but not installed, each with its command. Explain scopes from `cli-utilities/tool-packs.md`.
 
-### Step 7: Summary Mode — Build Dashboard
+### Step 4: Summary Mode (`--summary`)
 
-Output a full dashboard:
+Keep the dashboard. Gather `oat tools list --json --scope all` (projected to `{name, pack, scope, status}`) and `oat tools outdated --json --scope all`, group the tools by `pack`, and print:
 
-```
+```text
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 OAT ▸ DOCTOR SUMMARY
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -237,75 +244,28 @@ OAT ▸ DOCTOR SUMMARY
 
 | Pack      | Scope   | Skills | Status   |
 | --------- | ------- | ------ | -------- |
-| core      | user    | 2/2    | current  |
-| workflows | project | 40/40  | current  |
-| ideas     | user    | 4/4    | current  |
-| utility   | project | 10/10  | outdated |
+| core      | user    | 2      | current  |
+| workflows | project | 40     | outdated |
 
 ## Outdated Skills
 
-| Skill                   | Installed | Available | Scope   |
-| ----------------------- | --------- | --------- | ------- |
-| oat-project-implement   | 1.1.0     | 1.2.0     | project |
-
-## Available But Not Installed
-
-- **docs** pack: authoring-docs, oat-agent-instructions-analyze, oat-agent-instructions-apply, oat-docs-analyze, oat-docs-apply, oat-docs-authoring, oat-docs-bootstrap (7 skills available)
-  → Run: oat tools install docs --scope {scope}
-- **project-management** pack: oat-pjm-add-backlog-item, oat-pjm-decision, oat-pjm-remote, oat-pjm-update-repo-reference, oat-pjm-review-backlog (5 skills available)
-  → Run: oat tools install project-management --scope {scope}
-- **research** pack: analyze, compare, deep-research, recon, skeptic, synthesize (6 skills available)
-  → Run: oat tools install research --scope {scope}
-
-## Configuration
-
-| Key                  | Value                     | Source  |
-| -------------------- | ------------------------- | ------- |
-| activeProject        | .oat/projects/shared/foo  | local   |
-| activeIdea           | (not set)                 | -       |
-| projects.root        | .oat/projects/shared      | default |
-| projects.defaultScope | synced                    | default |
-| documentation.root   | (not set)                 | -       |
-| worktrees.root       | (not set)                 | -       |
-
-### Config Key Explanations
-
-Read config key descriptions from `~/.oat/docs/reference/file-locations.md` and `~/.oat/docs/guide/cli-reference.md`. If docs are not available, use these fallback descriptions:
-
-- **activeProject:** Path to the currently active OAT project. Set automatically by project skills.
-- **activeIdea:** Path to the currently active idea. Set by oat-idea-new.
-- **lastPausedProject:** Path to the last paused project for quick resume.
-- **projects.root:** Base directory for all OAT projects. Default: `.oat/projects/shared`.
-- **projects.defaultScope:** Scope used by project creation when `--scope` is omitted. Default: `synced`; supported values are `shared`, `local`, and `synced`.
-- **documentation.root:** Root directory for documentation. Used by docs skills.
-- **documentation.config:** Path to docs config file (e.g., mkdocs.yml).
-- **documentation.tooling:** Docs tooling in use (e.g., mkdocs, fumadocs).
-- **documentation.requireForProjectCompletion:** Whether docs update is required before project completion.
-- **workflow.autoReviewAtHillCheckpoints:** When true, completing a HiLL checkpoint auto-triggers the lifecycle review. Default unset. This does not control Tier 1 per-phase `oat-reviewer` gates. Can be overridden per-project via `oat_auto_review_at_hill_checkpoints` in plan.md frontmatter. Legacy `autoReviewAtCheckpoints` and `oat_auto_review_at_checkpoints` are still read as fallbacks.
-- **worktrees.root:** Base directory for git worktrees. Used by worktree-bootstrap skills.
-
-## Sync Status
-
-{In sync / N pending changes across M providers}
-
-## Warnings
-
-{Same warnings as check mode, if any}
+| Skill                 | Installed | Available | Scope   |
+| --------------------- | --------- | --------- | ------- |
+| oat-project-implement | 1.1.0     | 1.2.0     | project |
 
 ## Recommendations
 
-- Run `oat tools update` to update outdated skills.
-- Run `oat init tools` to install newly available packs.
-- Run `oat sync --scope project` to sync provider views.
+- Run `oat tools update --scope {scope}` to update outdated skills.
+- Run `oat-doctor` (no arguments) for the config, PJM, instructions, and docs sweep.
 ```
 
-Adapt the dashboard to show only sections with relevant data. Omit empty sections.
+The pack list comes from the `pack` field of `oat tools list`; the skill carries no pack manifest. Omit empty sections.
 
 ## Success Criteria
 
-- ✅ Check mode reports all warnings with actionable fix commands.
-- ✅ Summary mode shows a complete dashboard of installed packs, config, and available skills.
-- ✅ Outdated skills are detected and update commands are provided.
-- ✅ Stale config pointers are identified.
-- ✅ Available-but-uninstalled packs/skills are surfaced (discovery gap closed).
-- ✅ No files are modified — purely diagnostic output.
+- ✅ The sweep runs all seven commands and four file checks, projected, and never aborts on a non-zero exit with parseable JSON.
+- ✅ The report groups findings by area and severity, folds `info` into counts, and ends with the area prompt (or ends at the report under the report-only rule).
+- ✅ Every dive explains from the bundled docs and `describe` entries, names a fix path per finding, and applies nothing except one approved carve-out command.
+- ✅ Every `pjm:*` check the CLI defines has a fix path or the generic `info` rule.
+- ✅ Summary mode still prints the dashboard from live `oat tools list` output.
+- ✅ No file is modified by the sweep, the report, or a dive.