@open-agent-toolkit/cli 0.3.12 → 0.3.14

package/assets/docs/{workflows/projects/artifacts.md → reference/project-artifacts.md}

@@ -86,7 +86,7 @@ behavioral change needs evidence that fails without the change.
   machine-scannable repo-improvement (`RP-NN`) and upstream-feedback (`UP-NN`)
   registers. Promotion and filing rollups let the retro skills resume approved
   applications and tracker filing without repeating settled work. See
-  [Project Retrospectives](retro.md).
+  [Project Retrospectives](../workflows/projects/closeout/retro.md).
 
 ### Explainer artifacts
 
@@ -197,7 +197,7 @@ Coordination parents do not contain executable phase files. `spec.md`, `design.m
 
 The parent still keeps `state.md`, `discovery.md`, and `references/split-plan.json`. Child projects are flat siblings and link back to the parent through state metadata. Each child starts from a distilled discovery seed and must revalidate inherited context before moving beyond discovery/design.
 
-See [Project Splitting](splitting.md) for the full parent/child model.
+See [Project Splitting](../workflows/projects/planning/splitting.md) for the full parent/child model.
 
 ### plan.md frontmatter
 
@@ -232,7 +232,7 @@ Each inner array is a group of phases that execute concurrently in their own wor
 
 **Validation:**
 
-Before dispatching, `oat-project-implement` invokes `oat project validate-plan --project-path "${PROJECT_PATH}"`. Non-zero exit blocks the run. See [CLI Reference](../../reference/cli-reference.md) and [Implementation Execution](implementation-execution.md) for details.
+Before dispatching, `oat-project-implement` invokes `oat project validate-plan --project-path "${PROJECT_PATH}"`. Non-zero exit blocks the run. See [CLI Reference](cli-reference.md) and [Implementation Execution](../workflows/projects/execution/implementation-execution.md) for details.
 
 #### oat_phase_review_gate
 
@@ -261,7 +261,7 @@ oat_phase_review_gate:
 - `review_type` → optional, defaults to `code`. Only `code` is supported for phase gates.
 - `exit_nonzero_on` → optional, defaults to `high`. One of `critical`, `high`, `medium`, `low`. This is the blocking threshold: findings at or above it stop the phase; sub-threshold findings are dispositioned by the judgment sweep rather than ignored.
 
-A malformed gate stops the run before task execution rather than being silently disabled. The gate is independent of HiLL checkpoints and reuses the existing `oat gate review` target config — it does not hardcode a `--target`. See [Reviews → Phase review gate](reviews.md#phase-review-gate) for the runtime behavior and disposition rules.
+A malformed gate stops the run before task execution rather than being silently disabled. The gate is independent of HiLL checkpoints and reuses the existing `oat gate review` target config — it does not hardcode a `--target`. See [Reviews → Phase review gate](../workflows/projects/reviews/index.md#phase-review-gate) for the runtime behavior and disposition rules.
 
 ## Reference artifacts
 

package/assets/docs/{workflows/projects/state-machine.md → reference/project-state-machine.md}

@@ -83,7 +83,7 @@ Lite progression:
 A lite project that outgrows one sitting can move to the quick chain with `oat
 project promote <project-path> --to quick`, which flips `oat_workflow_mode` to
 `quick` and sets `oat_phase: discovery` with `oat_phase_status: complete`. See
-[Lifecycle](lifecycle.md#promoting-a-lite-project-to-quick).
+[Lifecycle](../workflows/projects/lifecycle.md#promoting-a-lite-project-to-quick).
 
 ## Review progression
 

package/assets/docs/{workflows/projects/repo-analysis.md → reference/repository-pr-comments.md}

@@ -7,7 +7,7 @@ description: 'Repository-level PR comment analysis commands for collecting and t
 
 The `oat repo pr-comments` command group provides repository-level review analysis tools. These commands operate across merged pull requests rather than on individual PRs.
 
-This page covers the PR-comment analysis surface only. Other repository-level commands, such as `oat repo archive sync`, are covered in [Lifecycle](lifecycle.md#completion-archive-behavior) and [Configuration](../../cli-utilities/configuration.md#shared-repo-config-you-will-touch-most-often).
+This page covers the PR-comment analysis surface only. Other repository-level commands, such as `oat repo archive sync`, are covered in [Lifecycle](../workflows/projects/lifecycle.md#completion-archive-behavior) and [Configuration](configuration.md#shared-repo-config-you-will-touch-most-often).
 
 ## Quick Look
 
@@ -102,4 +102,4 @@ Both commands accept dependency injection for testability:
 
 - Source: `packages/cli/src/commands/repo/pr-comments/`
 - Types: `packages/cli/src/commands/repo/pr-comments/collect/pr-comments.types.ts`
-- Archive sync: [Lifecycle](lifecycle.md#completion-archive-behavior) and [Configuration](../../cli-utilities/configuration.md#shared-repo-config-you-will-touch-most-often)
+- Archive sync: [Lifecycle](../workflows/projects/lifecycle.md#completion-archive-behavior) and [Configuration](configuration.md#shared-repo-config-you-will-touch-most-often)

package/assets/docs/reference/troubleshooting.md

@@ -5,16 +5,99 @@ description: 'Common issues and fixes for skills visibility, worktrees, sync, an
 
 # Troubleshooting
 
+The commands on this page use the installed `oat` command. A few entries also
+give a `pnpm run ...` form; those work only inside a checkout of the OAT source
+repository and are labelled that way.
+
 ## Skills not visible in host UI
 
-- Run: `pnpm run cli -- sync --scope all`
-- Reload/restart host app session
-- Verify `AGENTS.md` skills table matches `.agents/skills/*/SKILL.md`
+A skill shows up in your coding tool only when two things are true: the skill
+is installed (a folder with a `SKILL.md` under `.agents/skills/` in this
+repository, or under `~/.agents/skills/` in your home directory), and the
+tool can read it. Some tools, such as Claude Code, read a provider view: a
+link or copy that OAT creates in the tool's own folder, such as
+`.claude/skills`. Others, such as Cursor, read `.agents/skills` directly.
+
+**Diagnose first.** These commands only read; they change nothing.
+
+1. Check whether the skill is installed, and where:
+
+   ```bash
+   oat tools info <skill-name>
+   ```
+
+   It prints the skill's pack, its scope (`project` for this repository,
+   `user` for your home directory) and its status, then a "Provider views"
+   block for each scope with one row per coding tool.
+   - `Tool '<skill-name>' not found.` means the skill is not installed at
+     either scope. Install the pack that contains it (see the fixes below), or
+     create the skill at `.agents/skills/<skill-name>/SKILL.md`. To see every
+     installed skill with its pack and scope, run `oat tools list`.
+   - `in-sync` on your tool's row means its view of the skill is in place, so
+     go to the last fix step and start a new session.
+   - `missing-additive`, `removed` or `modified` means your tool's view is
+     absent or out of date. The block ends with a `Repair:` line that gives
+     the exact `oat sync --scope ...` command to run.
+   - `inactive` means that tool is not active at that scope, so OAT creates
+     no view for it. Enable it, as shown in the fixes below.
+
+2. Check whether the repository's provider views are in sync:
+
+   ```bash
+   oat status --scope project
+   ```
+
+   Each row names a tool and a skill. `✓ in_sync` means the view is in place.
+   `✗ missing  provider entry missing` means the view has not been created
+   yet; `oat sync` creates it. `No managed entries found.` means OAT manages
+   no provider views in this repository, which usually means no tool that
+   needs views is enabled. Run `oat providers list --scope project` to see
+   which tools are enabled or detected.
+
+**Then fix**, always with an explicit scope:
+
+- Enable the tool if step 1 or 2 showed it is not active, for example
+  `oat providers set --scope project --enabled claude`.
+- For skills in this repository (`.agents/skills`), preview and then
+  regenerate the provider views:
+
+  ```bash
+  oat sync --scope project --dry-run
+  oat sync --scope project
+  ```
+
+- For skills installed at user scope (`~/.agents/skills`, where a tool pack
+  installs when you give no `--scope`), run `oat sync --scope user`. This
+  writes provider views in your home directory, such as `~/.claude/skills`.
+- If the skill comes from a pack that is not installed, install that pack with
+  an explicit scope, for example `oat tools install research --scope project`
+  (this repository) or `oat tools install research --scope user` (your home
+  directory). If you installed a pack with `--no-sync`, running the install
+  again does not create the views; run `oat sync` for that scope instead.
+- Reload the tool or start a new session: most tools read their skill list
+  when a session starts.
+- If your repository's `AGENTS.md` names skills or packs, check that it
+  matches what `oat tools list` reports. The `<!-- OAT tools -->` block that
+  `--project-guidance` writes lists the installed packs and the folders
+  agents should scan for skills; it does not list each skill.
+- If you are working in the OAT source repository: run
+  `pnpm run cli -- sync --scope all`, which runs the CLI from source and syncs
+  both project and user scope.
 
 ## Worktree checkout missing provider links
 
-- Run: `pnpm run worktree:init`
-- This command installs dependencies, builds the workspace, and runs `oat sync --scope project`.
+- In the new worktree, run `oat sync --scope project` to recreate the
+  project's provider views. Add `--dry-run` first to preview.
+- To prepare the whole worktree, including local-only files and the
+  repository's setup and readiness checks, invoke
+  `/oat-worktree-bootstrap --existing` in your coding agent. See
+  [Worktree bootstrap](../workflows/advanced/worktree-bootstrap.md).
+- If you are working in the OAT source repository: run
+  `pnpm run worktree:init`. This command copies local-only files from the main
+  worktree, installs dependencies, configures Git hooks, builds the workspace,
+  and runs `oat sync` with no scope flag. A bare `oat sync` uses
+  `--scope all`, so it refreshes user-scope provider views in your home
+  directory as well as the project's.
 
 ## Codex appears detected but no skill sync actions are listed
 
@@ -85,12 +168,18 @@ Use [Instruction Sync](../provider-sync/instruction-sync.md) for the full strate
 
 ## `doctor` warns about canonical directories
 
-- Run `oat init` for the relevant scope.
+- Run `oat init` for the relevant scope. The check's name says which scope is
+  missing directories: for `project:canonical_directories` run
+  `oat init --scope project`, and for `user:canonical_directories` run
+  `oat init --scope user`. A bare `oat init` initializes both.
 - Re-run `oat doctor` after initialization.
 
 ## `doctor` warns about outdated installed OAT skills
 
-- Run `oat init tools` to install/update bundled OAT tool packs.
+- Run `oat tools update --pack <pack> --scope <project|user>` to update an
+  installed pack, or `oat tools install <pack> --scope <project|user>` to
+  install one. The older form `oat init tools` is a legacy command that still
+  installs or updates the bundled tool packs.
 - In TTY mode, select which outdated skills to update when prompted.
 - In non-interactive mode, run the scoped command doctor prints:
   `oat tools update --pack <pack> --scope <scope>`.
@@ -212,7 +301,7 @@ Both commands report managed pack state with a scoped recovery command:
   contract and does not clear this finding. `oat tools update` cannot fix it.
   Enable a provider with `oat providers set --scope user --enabled <provider>`
   and run `oat sync --scope user`; reinstalling at project scope is not
-  required. See [Tool packs](../cli-utilities/tool-packs.md) for how
+  required. See [Tool packs](../getting-started/tool-packs.md) for how
   user-scope agents reach each provider.
 
 ## `status` or `doctor` reports `packs:inventory`
@@ -229,7 +318,21 @@ and the home root becomes `~` when user scope is checked. Redaction is a literal
 replacement of those exact root paths, so a path outside them, such as a global
 bundle path in an assets error, stays absolute in the message.
 
-Rebuild the CLI workspace, then rerun the command named in the diagnostic:
+With an installed CLI, reinstall it so its bundled assets are complete and
+match the CLI version, then rerun the command named in the diagnostic. If you
+set `OAT_ASSETS_DIR`, point it at a complete asset bundle built for this CLI
+version, or unset it to use the bundled copy.
+
+```bash
+npm install --global @open-agent-toolkit/cli
+oat status # or: oat doctor
+```
+
+The diagnostic's own recovery line says to run `pnpm build`. That applies only
+when you run the CLI from a checkout of the OAT source repository.
+
+If you are working in the OAT source repository: rebuild the CLI workspace,
+then rerun the command named in the diagnostic:
 
 ```bash
 pnpm build
@@ -373,7 +476,11 @@ 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`
+- Missing manifest: run `sync` or `init`. For the repository's manifest
+  (`.oat/sync/manifest.json`), use `oat sync --scope project` or
+  `oat init --scope project`; without `--scope`, both commands also write to
+  your home directory. For the user manifest (`~/.oat/sync/manifest.json`),
+  use `--scope user`.
 - Invalid manifest: repair/remove file and rerun
 
 ## Status/output mismatches with lifecycle expectations
@@ -405,10 +512,18 @@ package.
 
 ## Reference artifacts
 
+In your own repository, these project files hold the evidence most entries on
+this page refer to:
+
 - `.oat/projects/<scope>/<project>/implementation.md`
 - `.oat/projects/<scope>/<project>/reviews/`
 - `.oat/projects/<scope>/<project>/explainers/<slug>/manifest.json`
 - `.oat/projects/<scope>/<project>/explainers/<slug>/qa/result.json`
+
+If you are working on OAT itself, in a checkout of the OAT source repository,
+the checks behind `oat doctor`, `oat status` and `oat instructions` live in
+these source files:
+
 - `packages/cli/src/commands/doctor/index.ts`
 - `packages/cli/src/commands/status/index.ts`
 - `packages/cli/src/commands/tools/shared/pack-inventory.ts`