@open-agent-toolkit/cli 0.2.36 → 0.2.38

package/assets/docs/provider-sync/scope-and-surface.md

@@ -17,6 +17,7 @@ This capability is intentionally independent from OAT workflow artifacts. Teams
 - Cursor's `.cursor/skills` and `~/.cursor/skills` directories are provider-local extension and adoption surfaces, not managed output directories.
 - Copilot's legacy `.github/skills` and `~/.copilot/skills` directories are adoption sources, not managed output directories. Copilot agents and project rules still use `.github/agents`, `~/.copilot/agents`, and `.github/instructions` provider views.
 - Manifest tracking: `.oat/sync/manifest.json` (project) and `~/.oat/sync/manifest.json` (user)
+- Canonical skills and agents installed by OAT tool packs exist at both scopes: `.agents/skills`, `.agents/agents` for project scope, and `~/.agents/skills`, `~/.agents/agents` for user scope. Every reusable pack defaults to user scope on a fresh install, so user-scope canonical content is the common case rather than the exception.
 
 Rules are currently project-scoped canonical content. Unlike skills and agents, synced rule files for Claude, Cursor, and Copilot are rendered copies with provider-specific frontmatter and filename extensions.
 
@@ -30,6 +31,8 @@ Rules are currently project-scoped canonical content. Unlike skills and agents,
 - Obsolete managed mappings are deleted only when their provider paths are verified clean; changed or unverified paths are preserved and detached from manifest ownership
 - Canonical `.agents/agents` is source of truth for subagents; provider views are derived
 - Canonical `.agents/rules` is source of truth for rules; provider rule files are derived rendered copies
+- Each scope syncs independently. When the same canonical asset exists at both project and user scope, OAT reports the duplication with both paths and versions and does **not** infer which copy a provider executes; resolve it explicitly with `oat tools migrate`
+- Pack removal and migration drive a symmetric removal sync: the exact canonical paths that were removed are pruned from provider views in that scope only, and only after the canonical source is confirmed absent
 
 ## Implemented command surface
 
@@ -43,7 +46,7 @@ Rules are currently project-scoped canonical content. Unlike skills and agents,
 ## Adjacent CLI commands (commonly used with provider interop)
 
 - `oat init` (bootstrap canonical structure and sync config) — see `../cli-utilities/bootstrap.md`
-- `oat tools ...` (install/update/remove/list/inspect tools) — see `../cli-utilities/tool-packs.md`
+- `oat tools ...` (install/update/remove/migrate/list/inspect tools) — see `../cli-utilities/tool-packs.md`
 - `oat doctor` (environment + skill-version diagnostics) — see `../reference/cli-reference.md`
 
 ## Provider enablement model

package/assets/docs/reference/cli-reference.md

@@ -12,7 +12,7 @@ The CLI is also a standalone value path. You can use `oat init`, `oat sync`, `oa
 ## Contents
 
 - [CLI Bootstrap](../cli-utilities/bootstrap.md) - Bootstrap a repo with `oat init`, guided setup, and initial provider adoption.
-- [Tool Packs](../cli-utilities/tool-packs.md) - Install, update, inspect, and remove bundled OAT skills and agents.
+- [Tool Packs](../cli-utilities/tool-packs.md) - Install, update, inspect, migrate, and remove bundled OAT skills and agents at project or user scope.
 - [Config and Local State](../cli-utilities/config-and-local-state.md) - Config, backlog, local paths, diagnostics, and related utility commands.
 - [Workflow Gates](../cli-utilities/workflow-gates.md) - Per-skill final commands, review gates, and cross-runtime prompt dispatch.
 - [Docs Tooling Commands](../docs-tooling/commands.md) - Docs app scaffolding, migration, index generation, and nav sync.
@@ -41,8 +41,8 @@ The first practical expansion path is to keep improving the existing owners: [Do
 | Command group                                   | What it covers                                                                                                                                                                                                             | Go deeper                                                                          |
 | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
 | `oat init`                                      | Bootstrap canonical OAT directories, sync config, optional hooks, and guided setup.                                                                                                                                        | [CLI Bootstrap](../cli-utilities/bootstrap.md)                                     |
-| `oat tools ...`                                 | Install, inspect, update, and remove bundled OAT tool packs and assets.                                                                                                                                                    | [Tool Packs](../cli-utilities/tool-packs.md)                                       |
-| `oat pjm ...`                                   | Initialize the two-layer repo-reference surface (`init`), run enabled-pack reference diagnostics (`doctor`), and migrate legacy layouts to `pjm/` + `reference/` (`migrate`) after installing the project-management pack. | [Install vs. initialize](../cli-utilities/tool-packs.md#install-vs-initialize)     |
+| `oat tools ...`                                 | Install, inspect, update, remove, and migrate bundled OAT tool packs and assets across project and user scope.                                                                                                             | [Tool Packs](../cli-utilities/tool-packs.md)                                       |
+| `oat pjm ...`                                   | Adopt PJM for a repository and record it (`init`), run read-only adoption and reference diagnostics (`doctor`), and migrate legacy layouts to `pjm/` + `reference/` (`migrate`). Adoption is separate from pack placement. | [Install vs. initialize](../cli-utilities/tool-packs.md#install-vs-initialize)     |
 | `oat decision ...`                              | Create, index, and migrate file-per-record repo decisions under `reference/decisions/` (`init`, `new`, `regenerate-index`, `migrate`).                                                                                     | [Config and Local State](../cli-utilities/config-and-local-state.md#oat-decision-) |
 | `oat backlog ...` / `oat local ...`             | File-backed backlog helpers, local path sync, and local-only operational support.                                                                                                                                          | [Config and Local State](../cli-utilities/config-and-local-state.md)               |
 | `oat config ...` / `oat instructions ...`       | Config discovery, source-aware config dumps, supported mutations, and instruction-integrity helpers.                                                                                                                       | [Config and Local State](../cli-utilities/config-and-local-state.md)               |
@@ -56,6 +56,8 @@ The first practical expansion path is to keep improving the existing owners: [Do
 
 Notable commands introduced in the current CLI surface:
 
+- `oat tools migrate --pack <pack> --from <scope> --to <scope>` - move one installed pack between project and user scope. Always previews first, installs and re-inventories the destination before touching the source, and offers source removal only after the destination is verified complete. Declining or running non-interactively leaves the pack installed at both scopes rather than failing. `--dry-run` stops after the preview; there is no force flag. See [Tool Packs](../cli-utilities/tool-packs.md#oat-tools-migrate).
+- `oat pjm doctor --json` - read-only repository PJM diagnostics whose result carries an additive `adoption` object (`state` of `declared` | `inferred-legacy` | `partial-initialization` | `none`, `repoRoot`, and `recovery`). This, not `oat tools has project-management`, is the check that answers whether _this repository_ adopted PJM.
 - `oat config dump --json` - merged config with source attribution
 - `oat project status --json` - full parsed state for the active tracked project. **Stable contract for skills:** the JSON output is a typed read interface for OAT skills; the field set consumed by migrated skills is locked by `MIGRATED_FIELDS` in `packages/cli/src/commands/project/status.test.ts`. Removing or renaming any of `project.{name, path, phase, phaseStatus, workflowMode, docsUpdated, lastCommit, prStatus, prUrl}` is a breaking change and will fail the contract test.
 - `oat project status --field <path>` - print one arbitrary dot-path field from the same status payload, e.g. `project.workflowMode` or `project.timestamps.stateUpdated`. Missing/null fields print `null`; object and array fields print compact JSON.

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

@@ -11,9 +11,9 @@ For detailed `.oat/` tree semantics, see:
 
 ## Canonical agent assets
 
-- Skills: `.agents/skills/`
-- Agents/subagents: `.agents/agents/`
-- Rules: `.agents/rules/`
+- Skills: `.agents/skills/` (project) and `~/.agents/skills/` (user)
+- Agents/subagents: `.agents/agents/` (project) and `~/.agents/agents/` (user)
+- Rules: `.agents/rules/` (project only)
 - Cursor reads project skills directly from `.agents/skills/` and user skills
   directly from `~/.agents/skills/`. `.cursor/skills/` remains a Cursor-only
   extension and adoption surface, not generated output.
@@ -23,6 +23,29 @@ For detailed `.oat/` tree semantics, see:
   still sync to `.github/agents/` and `~/.copilot/agents/`, and project rules
   still sync to `.github/instructions/`.
 
+## Managed tool-pack assets by scope
+
+Every reusable tool pack defaults to user scope on a fresh install, so both
+columns are ordinary states.
+
+| Asset kind        | Project scope              | User scope                   |
+| ----------------- | -------------------------- | ---------------------------- |
+| Pack skills       | `.agents/skills/<name>/`   | `~/.agents/skills/<name>/`   |
+| Pack agents       | `.agents/agents/<name>.md` | `~/.agents/agents/<name>.md` |
+| Pack templates    | `.oat/templates/<name>`    | `~/.oat/templates/<name>`    |
+| Pack scripts      | `.oat/scripts/<name>`      | `~/.oat/scripts/<name>`      |
+| Bundled docs tree | not applicable             | `~/.oat/docs/`               |
+
+Project-scope templates under `.oat/templates/` are owner overrides that OAT
+seeds once and never rewrites; the managed default lives at user scope and in
+the bundle. PJM templates resolve repository → user → bundle.
+
+Pack intent is stored per scope:
+
+- Project intent: `tools.<pack>: true` in `.oat/config.json`
+- User intent: `tools.<pack>: true` in `~/.oat/config.json`
+- Repository PJM adoption: `pjm.initialized` and `pjm.schemaVersion` in `.oat/config.json`
+
 ## OAT runtime/state
 
 - Repo runtime config (non-sync settings): `.oat/config.json`
@@ -52,7 +75,8 @@ Config ownership note:
 
 ## OAT workflow
 
-- Templates: `.oat/templates/`
+- Templates: `.oat/templates/` (repo overrides) and `~/.oat/templates/` (managed defaults)
+- Shared scripts: `.oat/scripts/` and `~/.oat/scripts/`
 - Runtime sync state: `.oat/sync/`
 - Repo knowledge: `.oat/repo/knowledge/`
 - Active PJM operational layer: `.oat/repo/pjm/` (`current-state.md`, `roadmap.md`, `backlog/`)

package/assets/docs/reference/troubleshooting.md

@@ -78,6 +78,7 @@ Use [Instruction Sync](../provider-sync/instruction-sync.md) for the full strate
 - Run `oat init tools` to install/update bundled OAT tool packs.
 - In TTY mode, select which outdated skills to update when prompted.
 - In non-interactive mode, rerun the relevant pack subcommand with `--force` if you want to overwrite outdated installed skills.
+- For pack-level drift rather than a single skill, prefer the scoped command doctor prints: `oat tools update --pack <pack> --scope <scope>`.
 
 ## `sync` reports an unsafe provider parent
 
@@ -106,8 +107,11 @@ OAT intentionally does not automate this recovery.
 
 ## A user-installed pack is missing from shared `tools.*`
 
-This is expected. `.oat/config.json#tools` records project installation state,
-so a user-only install does not set `tools.<pack>` in shared repo config.
+This is expected. `.oat/config.json#tools` records **project-scope** intent
+only. A user install writes `tools.<pack>: true` to `~/.oat/config.json`
+instead, and never touches repository config. Since every reusable pack now
+defaults to user scope on a fresh install, an empty repository `tools` map is
+normal.
 
 Check effective project-plus-user availability with:
 
@@ -121,6 +125,130 @@ To confirm specifically that the user copy is present, run:
 oat tools has <pack> --scope user
 ```
 
+## `oat tools has <pack>` reports `false` for a pack I installed
+
+Availability is complete-only: a scope counts only when every managed asset the
+current release declares for it is present. A partially installed pack — for
+example one missing a skill added in a newer release — reports `false`.
+
+Read the reason from the JSON result and repair the named scope:
+
+```bash
+oat --json tools has <pack>
+oat tools update --pack <pack> --scope <project|user>
+```
+
+`completeness` shows `complete`, `partial`, or `absent` per scope, and `missing`
+lists the exact managed assets and paths behind a `false`.
+
+## `status` or `doctor` reports a partial or stale pack
+
+Both commands report managed pack state with a scoped recovery command:
+
+- `partial` — some managed assets are missing, or intent is declared with none
+  installed. Fix with `oat tools update --pack <pack> --scope <scope>`.
+- `stale` — installed assets are behind the bundled release. Same fix.
+- `newer` — installed assets are ahead of the bundle. This is informational and
+  usually means the CLI is older than the assets; update the CLI rather than
+  downgrading the pack.
+- `retained-override` — an owner-owned seeded asset exists at the scope, so the
+  managed default is intentionally not applied there. This covers repository
+  templates under `.oat/templates/` **and** seeded content such as
+  `.oat/ideas/backlog.md` and `.oat/ideas/scratchpad.md`. Deleting the file is
+  the right move only for a **template** you want OAT to manage again; never
+  delete seeded content you have edited, because the next install or update
+  reseeds the bundled default in its place and your edits are gone. The finding
+  is informational and carries no recovery command for exactly that reason.
+- `user-agent-unmaterialized` — the pack installed canonical agents into
+  `~/.agents/agents/`, but user scope materializes no provider view for them
+  beyond the bundled managed role files. `oat tools update` cannot fix this.
+  Install the pack at project scope (`oat tools install <pack> --scope project`)
+  when you need its agents. See
+  [Tool packs](../cli-utilities/tool-packs.md) for the full limitation.
+
+## `status` or `doctor` reports `legacy-false-conflict`
+
+An older repository left `tools.<pack>: false` in shared config while managed
+assets for that pack are present. The `false` is never honored as an opt-out.
+Choose one:
+
+```bash
+# adopt the existing install and rewrite intent as true
+oat tools update --pack <pack> --scope <project|user>
+
+# or remove the pack and delete the intent key entirely
+oat tools remove --pack <pack> --scope <project|user>
+```
+
+## `status` or `doctor` reports `duplicate-scope`
+
+The pack is installed at both project and user scope. This is a legitimate
+state, and OAT deliberately does **not** infer which copy a provider executes.
+Resolve it explicitly when you want one owner:
+
+```bash
+oat tools migrate --pack <pack> --from project --to user --dry-run
+oat tools migrate --pack <pack> --from project --to user
+```
+
+The destination is installed and verified before source removal is offered, so
+declining the confirmation leaves you exactly where you started — installed at
+both scopes — rather than in a broken half-state.
+
+## `oat tools migrate` leaves the pack at both scopes
+
+That is the safe outcome, not a failure. Migration verifies the destination
+first and removes the source only after an explicit confirmation. Declining, or
+running non-interactively, reports status `retained-both`. Rerun the command
+interactively to finish the move; the destination work is already done.
+
+If source removal or its sync failed partway, the command prints structured
+recovery instructions and retains source intent. Rerun the same command to
+complete it. Never delete the source by hand while the recovery instructions are
+outstanding.
+
+## A PJM command refuses to write and asks for `oat pjm init`
+
+Installing the `project-management` pack installs the **capability**. It does
+not adopt PJM for a repository, and `oat backlog init` / `oat decision init` are
+not alternate adoption paths. `oat pjm`, `oat backlog`, and `oat decision`
+mutations fail closed until adoption is recorded.
+
+Inspect the state, then adopt:
+
+```bash
+oat pjm doctor --json   # read adoption.state
+oat pjm init
+```
+
+`adoption.state` is `declared` (explicit marker present), `inferred-legacy`
+(complete legacy scaffold, no marker), `partial-initialization` (incomplete
+scaffold — rerun `oat pjm init`), or `none`. `oat pjm init` records
+`pjm.initialized` in `.oat/config.json` after verifying the canonical scaffold.
+
+## A PJM template change is not taking effect
+
+PJM templates resolve repository → user → bundle, first match wins. A
+repository template under `.oat/templates/` is an owner override that pack
+updates never rewrite, so it shadows the managed user default.
+
+Delete the repository copy to fall back to the managed default, or update the
+managed default itself:
+
+```bash
+oat tools update --pack project-management --scope user
+```
+
+## `--scope all` fails outside a Git repository
+
+It should not. `oat status --scope all` and `oat doctor --scope all` complete
+the user-scope work and report project scope as unavailable.
+`oat tools update --scope all` also completes the user-scope work, but it skips
+project scope silently rather than naming it in the result, so an empty project
+section there means "no repository here", not "nothing to update". An
+explicitly requested `--scope project` outside a repository is still a hard
+failure, which is intentional — you asked for a scope that does not exist here.
+
 ## Manifest not found or invalid
 
 - Missing manifest: run `sync` or `init`
@@ -183,4 +311,6 @@ be upgraded in place; restart them to receive an authenticated `ekrt2` token.
 - `.oat/projects/<scope>/<project>/reviews/`
 - `.oat/projects/<scope>/<project>/explainers/<slug>/qa/`
 - `packages/cli/src/commands/doctor/index.ts`
+- `packages/cli/src/commands/status/index.ts`
+- `packages/cli/src/commands/tools/shared/pack-inventory.ts`
 - `packages/cli/src/commands/instructions/`

package/assets/docs/workflows/projects/lifecycle.md

@@ -18,7 +18,7 @@ OAT lifecycle order:
 7. Summary (`oat-project-summary`) — generates `summary.md` as institutional memory; `oat-project-pr-final` and `oat-project-complete` auto-refresh it when missing or stale
 8. PR (`oat-project-pr-progress` / `oat-project-pr-final`) — sets `pr_open` status
 9. Revision loop (`oat-project-revise`) — optional; accepts post-PR feedback
-10. Documentation sync (`oat-project-document`) — optional; reads project artifacts and code evidence to identify docs needing updates, checks for missing coverage of newly shipped capability areas, checks effective project-management availability with `oat tools has project-management`, and auto-runs `oat-pjm-update-repo-reference` before scanning docs when the pack is available
+10. Documentation sync (`oat-project-document`) — optional; reads project artifacts and code evidence to identify docs needing updates, checks for missing coverage of newly shipped capability areas, and auto-runs `oat-pjm-update-repo-reference` before scanning docs only when the PJM capability is available **and** this repository has adopted PJM
 11. Complete (`oat-project-complete`)
 
 **Shortcut:** `oat-project-next` reads project state and invokes the correct next skill automatically — use it instead of remembering which skill comes next. Complements `oat-project-progress` (which is read-only diagnostic).
@@ -63,7 +63,7 @@ from missing state.
 After implementation closeout finishes:
 
 1. **Summary** (`oat-project-summary`) — generates `summary.md` as institutional memory from project artifacts; PR-final and completion will auto-refresh it if you have not already run it or if it is stale
-2. **Documentation** (`oat-project-document`) — optional sync of project docs; checks effective project-management availability with `oat tools has project-management` to decide whether repo-reference refresh should run before docs analysis, and should recommend new docs pages/directories when the shipped work introduces a capability area that the docs app does not already cover
+2. **Documentation** (`oat-project-document`) — optional sync of project docs; decides whether repo-reference refresh should run before docs analysis using two independent checks, and should recommend new docs pages/directories when the shipped work introduces a capability area that the docs app does not already cover
 3. **PR** (`oat-project-pr-final`) — creates PR description (auto-refreshes `summary.md` first when needed, then uses it as source), sets `oat_phase_status: pr_open`, and tracks actual PR existence with `oat_pr_status` / `oat_pr_url`
 4. **Revision loop** (`oat-project-revise`) — accepts post-PR feedback:
    - Inline feedback creates `p-revN` revision phases with `prevN-tNN` task IDs
@@ -308,6 +308,25 @@ See the [Workflow preferences section in the Configuration guide](../../cli-util
 - Projects root is stored in `.oat/config.json` (`projects.root`) and can be read via `oat config get projects.root`.
 - Workflow skills prefer `oat config get activeProject` / `oat config get projects.root` rather than reading pointer files directly.
 
+## Capability availability versus repository adoption
+
+Lifecycle skills that touch repository project-management state make two
+separate checks, and both must hold before any PJM write:
+
+1. **Capability availability** — `oat tools has project-management` answers
+   whether the PJM skills and templates are installed and complete at project or
+   user scope. Since packs default to user scope, this is usually satisfied by a
+   user-scope install with no repository footprint.
+2. **Repository adoption** — `oat pjm doctor --json` answers whether _this_
+   repository adopted PJM. Branch on its `adoption.state` field: `declared` and
+   `inferred-legacy` allow repository PJM writes; `partial-initialization` and
+   `none` stop with `oat pjm init` as the recovery.
+
+Pack presence is never treated as evidence of repository adoption. A skill that
+finds the capability available but the repository unadopted reports the
+actionable `oat pjm init` stop instead of scaffolding implicitly. See
+[Install vs. initialize](../../cli-utilities/tool-packs.md#install-vs-initialize).
+
 ## Brainstorming integration with the project lifecycle
 
 `oat-brainstorm` (in the `brainstorm` tool pack) interacts with the project lifecycle in two distinct ways: it can **seed a brand new project** from a brainstorming conversation when no project is active, or **fold back into an active project** when one is.

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.36",
-  "docs-config": "0.2.36",
-  "docs-theme": "0.2.36",
-  "docs-transforms": "0.2.36"
+  "cli": "0.2.38",
+  "docs-config": "0.2.38",
+  "docs-theme": "0.2.38",
+  "docs-transforms": "0.2.38"
 }