@open-agent-toolkit/cli 0.3.8 → 0.3.9

package/README.md

@@ -2,7 +2,7 @@
 
 Open Agent Toolkit command-line interface for provider sync, docs tooling, workflow utilities, and diagnostics.
 
-The CLI also supports project-scoped instruction sync for nested `AGENTS.md` / `CLAUDE.md` files, including pointer, symlink, and hard-copy repair strategies plus Claude-only adoption.
+The CLI also supports project-scoped instruction sync for nested `AGENTS.md` files. By default it creates no `CLAUDE.md` shims, because Claude Code reads `AGENTS.md` itself, and removes the shims OAT created earlier once no `CLAUDE.md` with its own content remains; pointer, symlink, and hard-copy shim strategies are opt-in through `instructions.claude.shims`, and Claude-only `CLAUDE.md` files are adopted into `AGENTS.md`.
 
 ## Install
 
@@ -28,8 +28,8 @@ oat config describe
 Additional useful entry points:
 
 - `oat tools install`
-- `oat instructions validate --strategy pointer`
-- `oat instructions sync --dry-run --strategy symlink`
+- `oat instructions validate`
+- `oat instructions sync --dry-run`
 - `oat docs init --app-name my-docs`
 - `oat pjm init` - initialize the project-management repo-reference surface after installing the pack
 - `oat config dump --json`

package/assets/agents/oat-codebase-mapper.md

@@ -1,6 +1,6 @@
 ---
 name: oat-codebase-mapper
-version: 1.0.1
+version: 1.0.2
 description: Explores codebase and writes structured analysis documents. Spawned by oat-repo-knowledge-index with a focus area (tech, arch, quality, concerns). Writes documents directly to reduce orchestrator context load.
 tools: Read, Bash, Grep, Glob, Write
 color: cyan
@@ -243,11 +243,12 @@ Return a brief confirmation. DO NOT include document contents.
 
 Format:
 
-```
+```markdown
 ## Mapping Complete
 
 **Focus:** {focus}
 **Documents written:**
+
 - `.oat/repo/knowledge/{DOC1}.md` ({N} lines)
 - `.oat/repo/knowledge/{DOC2}.md` ({N} lines)
 

package/assets/agents/oat-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-reviewer
-version: 1.2.9
+version: 1.2.10
 description: Unified reviewer for OAT projects - mode-aware verification of requirements/design alignment and code quality. Writes a review artifact to disk by default, or returns structured findings in-memory when dispatched in structured-output mode.
 tools: Read, Bash, Grep, Glob, Write, Task
 color: yellow
@@ -98,7 +98,7 @@ When delegation is eligible:
    Mechanical workers may execute checks and report exact output, but interpretation and policy judgment require stronger classes or stay with the root reviewer.
 
 5. The generic dispatch contract owns capability, catalog, model, effort, route, authorization, launch evidence, class-floor selection, and floor-satisfaction evidence. It applies active user and repository instructions, the active-provider reference, the live nested catalog, and the supplied policy/ceiling. Select an explicit target meeting the declared floor; never silently inherit the primary reviewer's model and never hard-code provider model names. Prefer a cheaper/faster worker only when the host reliably exposes that control and the target still satisfies the floor.
-6. When the selected lane worker is the canonical `recon-worker`, construct and validate its complete Assignment Gate envelope before launch: run, wave, and lane IDs; approved manifest wave mode; worker assignment mode; bounded objective; included and excluded scope; allowed and excluded inputs; source-read authority and read-only tools; sole write path; artifact kind, schema version, and closed output schema; enforcement; deadline; and escalation path. If the complete envelope cannot be constructed, do not launch the worker; record the attempt as not attempted or failed as appropriate and cover the lane inline. Other worker roles follow their own contracts.
+6. Launch every lane as an ordinary read-only sub-agent through the generic dispatch contract. The `recon` skill's evidence-packet worker and its assignment machinery belong to that skill alone; reviewer lanes never use them. When a lane cannot be launched within these limits, record the attempt as not attempted or failed as appropriate and cover the lane inline.
 7. Give each lane an exact scope and a compact return contract: coverage, checks performed, exact `file:line` evidence, gaps, and explicit uncertainty. Reports are advisory candidate observations, not accepted findings.
 8. Workers must not mutate files, emit final findings, assign severity, make validation decisions, write review artifacts or `StructuredFindings`, or otherwise write either output sink.
 
@@ -499,8 +499,6 @@ Run these to verify the implementation:
 Run the `oat-project-review-receive` skill to convert findings into plan tasks.
 ````
 
-```
-
 Gate parsing contract: artifact-mode reviews, including reviews spawned by `oat gate review`, MUST include either the complete `Findings by severity: {N} critical, {N} high, {N} medium, {N} low` count line or the standard `## Findings` sections shown above with every severity subsection present. When more than one count source is present — the frontmatter count fields, the count line, and the sections — the counts must agree; the gate refuses an artifact whose sources contradict each other rather than picking one. How a section is counted is load-bearing: the gate counts only markdown list items (`- `, `* `, `+ `, or `1. `) as findings. A finding written as a bold paragraph, a heading, or any other prose shape counts as zero, so a section of prose findings under a non-zero count line is a contradiction and the gate refuses the artifact — the entire review is rejected, not just the miscounted section.
 
 For every artifact-mode code review, `oat_review_head_sha` is required and must be the full 40-character commit SHA at the head of the authoritative review range. Resolve it with `git rev-parse <authoritative-range-head>^{commit}`. An abbreviated SHA, symbolic ref, or range string is invalid. When the review narrowed, `oat_review_range`, `oat_prior_review_artifact`, and `oat_prior_review_head_sha` are also required; the prior head must likewise be a full 40-character SHA. These code-review fields are independent of the gate-only block and do not apply to artifact, analysis, or structured-output reviews.
@@ -509,7 +507,6 @@ For a narrowed review, do not restate requirements-coverage claims that this pas
 
 For gate-originated artifacts, all six gate-only fields are required when the prompt supplies gate context. Copy the values exactly. Do not parse the provider command, infer values from the target id, or replace configured values with observed/self-reported identity. Any optional self-report belongs in review prose and is non-authoritative; the gate validates the copied frontmatter against its immutable configured invocation record before applying severity thresholds.
 
-
 ### Step 9: Return Confirmation
 
 **Artifact mode only.** In structured-output mode (`oat_output_mode: structured`), return the `StructuredFindings` object instead — see **Structured-Output Mode** below.
@@ -520,8 +517,8 @@ Return exactly one reconnaissance status line using only `attempted` or
 attempted, including an attempted launch that fell back or failed.
 
 Format:
-```
 
+```markdown
 ## Review Complete
 
 **Scope:** {scope}
@@ -530,8 +527,7 @@ Format:
 **Reconnaissance:** {attempted | not-attempted}
 
 Return to your main session and run the `oat-project-review-receive` skill.
-
-````
+```
 
 ## Structured-Output Mode
 
@@ -556,7 +552,7 @@ interface StructuredFindings {
   }>;
   verification_commands: string[]; // commands the caller can run to verify fixes — returned as an array, NOT appended to a file
 }
-````
+```
 
 **Rules for the structured return:**
 
@@ -595,7 +591,3 @@ Default behavior is unaffected: when `oat_output_mode` is absent or set to anyth
 - [ ] Findings have actionable fix guidance
 - [ ] Verification commands included
 - [ ] Brief confirmation returned (artifact mode) / `StructuredFindings` object returned (structured-output mode)
-
-```
-
-```

package/assets/agents/skeptical-evaluator.md

@@ -1,6 +1,6 @@
 ---
 name: skeptical-evaluator
-version: 1.0.0
+version: 1.0.1
 description: Adversarial claim evaluator — receives a context package and gathers evidence to disprove then support a claim. Returns structured findings with citations.
 tools: Read, Bash, Grep, Glob, WebSearch, WebFetch
 color: red
@@ -78,21 +78,25 @@ Return findings to the orchestrator using the output structure below. Do NOT wri
 
 Return inline findings to the orchestrator in this structure:
 
-```
+```markdown
 ## Evidence
 
 ### Contradicting Evidence
+
 {Each piece with specific citation — file:line, URL, version, etc.}
 {Or "None found after searching: [list of sources checked]"}
 
 ### Supporting Evidence
+
 {Each piece with specific citation}
 {Or "None found"}
 
 ### Evidence Quality Assessment
+
 {How reliable the evidence is — direct vs indirect, authoritative vs anecdotal}
 
 ## Preliminary Assessment
+
 {Lean toward one of: holds_up | skepticism_warranted | nuanced | inconclusive}
 {Brief reasoning for the lean}
 {Confidence estimate: X%}

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.3.8"
+  "oatVersion": "0.3.9"
 }

package/assets/docs/cli-utilities/backlog-lifecycle.md

@@ -56,9 +56,10 @@ A single `oat backlog archive` run performs the whole close-out so its parts can
 1. Sets the terminal `status` (`closed` by default, `wont_do` with `--wont-do`) and stamps `updated`.
 2. Validates and trims a nonblank `--summary` before mutating a `closed` item, then appends its canonical newest-first `completed.md` entry. `wont_do` items may omit the summary and get an entry only when one is provided.
 3. Moves `items/<id>.md` into `archived/` — with `git mv` inside a work tree, or a plain rename outside git.
-4. Regenerates the managed backlog index.
+4. Rewrites inbound references to the moved file across Markdown under `.oat/repo/**` (tracked and untracked files that Git does not ignore; a code span whose whole content is the item's path, such as an external plan's source citation, is rewritten, while other code spans and fenced code are left as written with a warning) — external plans, decision records, and other backlog items — so no link dangles at `items/<id>.md`, and reports each rewritten file. A reference it cannot resolve is left alone with a warning.
+5. Regenerates the managed backlog index.
 
-The command is safe to re-run: an item already in `archived/` produces a no-op warning with no writes. A missing closed-item summary or an out-of-enum current status (for example a hand-set `done`) is a hard error before mutation and includes recovery guidance. See the [command reference](config-and-local-state.md#oat-backlog-archive) for exit codes and the `--json` payload.
+The command is safe to re-run: an item already in `archived/` produces a no-op warning and only retries the reference rewrite and index regeneration, so an interrupted close-out finishes on the next run. A missing closed-item summary or an out-of-enum current status (for example a hand-set `done`) is a hard error before mutation and includes recovery guidance. See the [command reference](config-and-local-state.md#oat-backlog-archive) for exit codes and the `--json` payload.
 
 ## Catching lifecycle drift
 

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

@@ -47,7 +47,7 @@ After core initialization completes, `oat init` can enter an interactive guided
    - choose **Yes** to run the per-pack scope selector for every pack that allows both scopes (`ideas`, `docs`, `workflows`, `utility`, `project-management`, `research`, `brainstorm`)
    - choose **No** to apply additive per-pack defaults without extra scope prompts
    - on a fresh install every pack defaults to **user** scope, so capabilities follow you across repositories; an existing install keeps its current placement
-   - after placement is chosen, repository `AGENTS.md` guidance is a separate opt-in. Accepting creates the managed `OAT tools` section only when the root file is absent. An existing file or symlink is never replaced: OAT prints a repository-relative, copy-pasteable managed-block patch instead. Declining leaves `AGENTS.md` unchanged
+   - after placement is chosen, repository `AGENTS.md` guidance is a separate opt-in. Accepting creates the root file with the managed `OAT tools` section when it is absent, and appends that section to an existing file or contained symlink target that lacks it, with one append-only write. An existing file is never replaced: when the section exists but differs, OAT prints a repository-relative, copy-pasteable managed-block patch instead. Declining leaves `AGENTS.md` unchanged
    - installing `project-management` installs the capability only. Adopting it for this repository is a third, separate choice made with `oat pjm init` — see [Install vs. initialize](tool-packs.md#install-vs-initialize)
 2. **Local paths** — multi-select from default gitignored artifact paths (analysis, PR, reviews, ideas). Pre-existing paths are pre-checked; only new paths are added.
 3. **Documentation** — detect or enter docs metadata for the repo when documentation exists.
@@ -65,9 +65,12 @@ Hook install note:
 # Explicit guided setup on an existing repo
 oat init --setup --scope project
 
-# Install capabilities and create or propose repository guidance
+# Install capabilities and create, append, or propose repository guidance
 oat init --setup --project-guidance
 
+# Write guidance for the packs already installed, without guided setup
+oat init --project-guidance
+
 # Fresh init — guided setup is offered automatically
 oat init --scope project
 ```

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

@@ -17,7 +17,7 @@ Use the `oat backlog` group when you want direct CLI support for the file-backed
 - `oat backlog new <title>` - validate and create a file-backed backlog item from the canonical template, then regenerate the managed index
 - `oat backlog generate-id <title>` - generate a deterministic `BL-YYMMDD-slug` backlog ID from a title
 - `oat backlog generate-id <title> --created-at <timestamp>` - generate a reproducible ID for a known creation timestamp
-- `oat backlog archive <id>` - atomic close-out: set a terminal status, record the completion in `completed.md`, move the item into `archived/`, and regenerate the index in one step
+- `oat backlog archive <id>` - atomic close-out: set a terminal status, record the completion in `completed.md`, move the item into `archived/`, rewrite inbound `.oat/repo` references to the moved file, and regenerate the index in one step
 - `oat backlog regenerate-index` - rebuild the managed backlog index table from item frontmatter
 
 Backlog IDs are deterministic date+slug identifiers (`BL-YYMMDD-slug`) derived from the creation date and title, so two machines or worktrees produce the same ID for the same record without scanning the local checkout. The slug is capped at 30 characters at the last whole-word boundary (with trailing stop-words trimmed), so prefer concise, meaningful titles. Index regeneration is deterministic and safe to re-run when resolving an index merge conflict.
@@ -52,8 +52,9 @@ The command validates all inputs before creating the scaffold or writing an item
 - For the default `closed` path, validates and trims a nonblank `--summary` before any file or index mutation. The `wont_do` path may omit the summary and completion-ledger entry.
 - Rewrites only the `status:` and `updated:` frontmatter lines (preserving any inline enum comment), then moves the item from `items/` to `archived/` with `git mv` inside a work tree, falling back to a plain rename (with a warning) outside git or if `git mv` fails.
 - `closed` archives append a canonical newest-first `completed.md` entry (`YYYY-MM-DD — <id> — Title — summary`). `wont_do` archives append an entry only when `--summary` is provided. A missing `completed.md` is scaffolded from the starter template; a missing `## Completed Items` heading is scaffolded with a warning.
+- Rewrites inbound references to the moved file across Markdown under `.oat/repo/**` — tracked and untracked files that Git does not ignore, or every `.md` file outside a Git work tree — (external plans, decision records, other backlog items): relative links, `.oat/repo`-relative and repository-root path strings (including `oat_external_plan_sources` frontmatter) that resolve to `items/<id>.md` now point at `archived/<id>.md`, and the moved item's own relative links (inline links with any title form, and reference-style definitions; never footnotes or prose) are rebased when their target exists, so they keep resolving. An inline code span whose whole content is a path to the item (optionally with an `#anchor`), such as an external plan's `Source artifact or scope` citation, is rewritten; any other code span or fenced code block that mentions `items/<id>.md` is left as written with a warning, so recorded commands keep their meaning. Only references that resolve to the item's former `items/<id>.md` path change, and a link that already resolves to a different existing file is never repointed; URLs are never touched, and symlinked Markdown files are skipped so nothing outside `.oat/repo` is read or written. Each rewritten file is reported; a reference that names `items/<id>.md` but cannot be resolved is left untouched with a warning.
 - Regenerates the managed backlog index after the move.
-- Idempotent: re-running on an item already in `archived/` is a no-op warning with no writes.
+- Idempotent: re-running on an item already in `archived/` returns `noop` with a warning and makes no status, `completed.md`, or move changes; it only retries the idempotent reference rewrite and index regeneration, so a run interrupted during the rewrite (or an item archived by hand or by an older CLI) can be finished by running the command again.
 
 **Exit codes:**
 
@@ -73,11 +74,14 @@ On success the payload is the archive result object:
   "completedEntry": "written",
   "movedTo": ".oat/repo/pjm/backlog/archived/BL-260705-example.md",
   "indexRegenerated": true,
+  "rewrittenReferences": [
+    ".oat/repo/reference/external-plans/2026-07-05-example-plan.md"
+  ],
   "warnings": []
 }
 ```
 
-`result` is `archived` or `noop` (already archived); `completedEntry` is `written`, `scaffolded`, or `skipped` (e.g. a `wont_do` archive without `--summary`); `movedTo` is the destination path or `null`. On an actionable failure the payload is `{ "result": "error", "id": "<id>", "message": "<why + fix>" }`.
+`result` is `archived` or `noop` (already archived); `completedEntry` is `written`, `scaffolded`, or `skipped` (e.g. a `wont_do` archive without `--summary`); `movedTo` is the destination path or `null`; `rewrittenReferences` lists the repository-relative Markdown files whose references to the moved item were rewritten (on a no-op this lists anything the retried rewrite changed, and the human output prints each file on both paths). On an actionable failure the payload is `{ "result": "error", "id": "<id>", "message": "<why + fix>" }`.
 
 For full project-management repo-reference setup, use [`oat pjm init`](tool-packs.md#install-vs-initialize). It scaffolds the two-layer PJM surface (`pjm/current-state.md`, `pjm/roadmap.md`, `reference/decisions/`, and AGENTS guides) and delegates the backlog sub-surface to `oat backlog init`.
 
@@ -258,15 +262,18 @@ Use these reference pages for file ownership and schema details:
 
 These commands validate and repair project-scoped instruction integrity between `AGENTS.md` and sibling `CLAUDE.md` files.
 
-- `oat instructions validate` - read-only integrity check with `--strategy pointer|symlink|copy`
-- `oat instructions sync` - preview or apply pointer, symlink, or hard-copy repairs
+- `oat instructions validate` - read-only integrity check with `--strategy none|pointer|symlink|copy`
+- `oat instructions sync` - preview or apply the effective strategy: remove OAT-managed shims (`none`, the default) or create and repair pointer, symlink, or hard-copy shims
 
 Use this command group when instruction files drift after manual edits or generated updates, or when nested project directories contain Claude-only stray files that should be adopted into canonical `AGENTS.md`.
 
 Operational notes:
 
 - Validation and sync use the same recursive scan model, so `--dry-run` previews the same states that `validate` reports.
-- `pointer` is the default strategy; `symlink` and `copy` make file shape part of correctness.
+- `none` is the default strategy: no `CLAUDE.md` shims, because Claude Code reads `AGENTS.md` itself. Persist a shim strategy with `oat config set instructions.claude.shims pointer|symlink|copy`; `--strategy` overrides it for one run.
+- Under `none`, every remaining `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` is reported with a warning, because it makes Claude Code ignore every `AGENTS.md`.
+- Under `none`, shim removal is all or nothing: while any of those files has content of its own, sync removes no shim, exits `1`, and reports one `claude_md_blocks_shim_removal` finding naming the files with content and the shims it kept. See [All or nothing](../provider-sync/instruction-sync.md#all-or-nothing).
+- Under a shim strategy, `symlink` and `copy` make file shape part of correctness.
 - Unreadable canonical `AGENTS.md` files and unreadable Claude-only sources are surfaced as drift, but sync leaves them in manual-repair mode instead of guessing at recovery.
 
 For the full state model, repair semantics, and examples, see [Instruction Sync](../provider-sync/instruction-sync.md).

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

@@ -19,13 +19,13 @@ For the deep file-by-file reference, see:
 
 ## The five config surfaces
 
-| Surface                   | File                      | Typical contents                                                                                                                                      | Primary CLI surface                                  |
-| ------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
-| Shared repo config        | `.oat/config.json`        | Repo-wide non-sync settings such as `projects.root`, `git.defaultBranch`, `documentation.*`, `archive.*`, `tools.*`, and shared `workflow.*` defaults | `oat config get/set/unset/list/describe`, `oat gate` |
-| Repo-local config         | `.oat/config.local.json`  | Per-developer state for this checkout, such as `activeProject`, `lastPausedProject`, repo-local `activeIdea`, and local `workflow.*` overrides        | `oat config get/set/unset/list/describe`, `oat gate` |
-| User config               | `~/.oat/config.json`      | User-level state such as global `activeIdea` fallback and personal `workflow.*` defaults                                                              | `oat config get/set/unset/describe`, `oat gate`      |
-| Project sync config       | `.oat/sync/config.json`   | Provider enablement, sync strategy, and repo-level known stray settings                                                                               | `oat providers set`, `oat config describe`           |
-| User provider sync config | `~/.oat/sync/config.json` | User sync strategy and personal known provider strays                                                                                                 | Provider-sync commands, `oat config describe`        |
+| Surface                   | File                      | Typical contents                                                                                                                                                        | Primary CLI surface                                  |
+| ------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| Shared repo config        | `.oat/config.json`        | Repo-wide non-sync settings such as `projects.root`, `git.defaultBranch`, `documentation.*`, `instructions.*`, `archive.*`, `tools.*`, and shared `workflow.*` defaults | `oat config get/set/unset/list/describe`, `oat gate` |
+| Repo-local config         | `.oat/config.local.json`  | Per-developer state for this checkout, such as `activeProject`, `lastPausedProject`, repo-local `activeIdea`, and local `workflow.*` overrides                          | `oat config get/set/unset/list/describe`, `oat gate` |
+| User config               | `~/.oat/config.json`      | User-level state such as global `activeIdea` fallback and personal `workflow.*` defaults                                                                                | `oat config get/set/unset/describe`, `oat gate`      |
+| Project sync config       | `.oat/sync/config.json`   | Provider enablement, sync strategy, and repo-level known stray settings                                                                                                 | `oat providers set`, `oat config describe`           |
+| User provider sync config | `~/.oat/sync/config.json` | User sync strategy and personal known provider strays                                                                                                                   | Provider-sync commands, `oat config describe`        |
 
 The main split is:
 
@@ -95,8 +95,9 @@ Common keys in `.oat/config.json`:
 - `git.defaultBranch` — base branch fallback for PR workflows
 - `documentation.root`, `documentation.tooling`, `documentation.config` — docs-surface ownership
 - `documentation.excludes` — a JSON array of globs, relative to the docs directory, that `oat docs generate-index` leaves out of the generated index. `oat config set` takes the list as one comma-separated value (`"a/**,b.md"`) and stores it as an array; repeated `--exclude` flags extend it, and an empty value clears the key
-- `documentation.instructionPointerExcludes` — a JSON array of repository-relative directories that `oat instructions sync` and `oat instructions validate` must not treat as pointer sites, additive to the documentation content root they already skip by default (see [Instruction Sync](../provider-sync/instruction-sync.md#documentation-trees)). `oat config set` takes the list as one comma-separated value (`"vendor/generated,apps/oat-docs/docs"`) and stores it as an array of repository-relative POSIX paths, trimmed and de-duplicated; an empty value clears the key, and `oat config unset documentation.instructionPointerExcludes` removes it. An entry that could never exclude anything — an absolute path, or one escaping the repository with `..` — is rejected with exit code `1` rather than stored. A structurally malformed value already on disk (a non-array, or an empty or non-string entry) is rejected with exit code `2` and a repair message, and `oat config set` can still replace it. Entries that are well formed but cannot exclude anything — among them absolute paths, paths escaping the repository, paths that match no directory (matching is case-sensitive, and the warning names the on-disk spelling when the path differs only in case), paths that resolve elsewhere through a symlink (the warning names the resolved target instead of blaming case-sensitivity), and the unexcludable `.oat/repo` carve-in root — never abort the command; they are reported as warnings and are not counted as protection. Warnings go to stderr in human mode and to the `exclusionWarnings` field under `--json`
 - `documentation.requireForProjectCompletion` — whether docs sync is a completion gate
+- `instructions.claude.shims` — how `oat instructions sync` keeps a `CLAUDE.md` beside each `AGENTS.md`: `none` (the default: no shims; sync removes the ones OAT created and warns about any other `CLAUDE.md`, all or nothing: it removes none while any `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` has content of its own; see [All or nothing](../provider-sync/instruction-sync.md#all-or-nothing)), `pointer`, `symlink`, or `copy`. The `--strategy` flag overrides it for one run. Set it with `oat config set instructions.claude.shims pointer` when contributors need `CLAUDE.md` (see [Claude Code and AGENTS.md](../provider-sync/instruction-sync.md#claude-code-and-agentsmd)); `oat config unset` returns to `none`. Any other value is rejected with exit code `2` rather than read as unset, and `oat config set` can still replace it
+- `instructions.claude.excludes` — a JSON array of repository-relative directories that `oat instructions sync` and `oat instructions validate` must not treat as pointer sites, additive to the documentation content root they already skip by default (see [Instruction Sync](../provider-sync/instruction-sync.md#documentation-trees)). `oat config set` takes the list as one comma-separated value (`"vendor/generated,apps/oat-docs/docs"`) and stores it as an array of repository-relative POSIX paths, trimmed and de-duplicated; an empty value clears the key, and `oat config unset instructions.claude.excludes` removes it. An entry that could never exclude anything — an absolute path, or one escaping the repository with `..` — is rejected with exit code `1` rather than stored. A structurally malformed value already on disk (a non-array, or an empty or non-string entry) is rejected with exit code `2` and a repair message, and `oat config set` can still replace it. Entries that are well formed but cannot exclude anything — among them absolute paths, paths escaping the repository, paths that match no directory (matching is case-sensitive, and the warning names the on-disk spelling when the path differs only in case), paths that resolve elsewhere through a symlink (the warning names the resolved target instead of blaming case-sensitivity), and the unexcludable `.oat/repo` carve-in root — never abort the command; they are reported as warnings and are not counted as protection. Warnings go to stderr in human mode and to the `exclusionWarnings` field under `--json`
 - `archive.s3Uri` — base S3 archive prefix
 - `archive.s3SyncOnComplete` — upload archived projects to S3 during completion
 - `archive.summaryExportPath` — export `summary.md` into a durable tracked directory during completion
@@ -815,7 +816,7 @@ oat config set workflow.dispatchCeiling.providers.codex medium  # Advanced: per-
 oat config set workflow.autoArtifactReview.analysis false
 ```
 
-Default (no flag) targets `.oat/config.local.json` for workflow keys. Pass at most one of `--user`, `--shared`, or `--local`. Structural keys (`projects.root`, `worktrees.root`, `git.*`, `documentation.*`, `archive.*`, `tools.*`) are still shared-only regardless of flag.
+Default (no flag) targets `.oat/config.local.json` for workflow keys. Pass at most one of `--user`, `--shared`, or `--local`. Structural keys (`projects.root`, `worktrees.root`, `git.*`, `documentation.*`, `instructions.*`, `archive.*`, `tools.*`) are still shared-only regardless of flag.
 
 ### Choosing the right surface (personal vs per-repo)
 

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

@@ -11,7 +11,7 @@ This page covers CLI commands that manage bundled OAT tool packs and installed O
 
 - What it does: explains how bundled OAT packs are installed, updated, inspected, and removed.
 - When to use it: when you need to add capabilities to a repo, update installed skills, or understand which packs own which tools.
-- Primary commands: `oat tools list`, `oat tools has`, `oat tools install`, `oat tools update`, `oat tools remove`, `oat tools migrate`
+- Primary commands: `oat tools list`, `oat tools has`, `oat tools guidance`, `oat tools install`, `oat tools update`, `oat tools remove`, `oat tools migrate`
 - Coming from an earlier CLI: read [Upgrading from an earlier CLI](#upgrading-from-an-earlier-cli) for the changed install-scope default, PJM adoption gating, sparse `tools` config map, and per-pack `--json` shape
 
 ## Bundled packs at a glance
@@ -243,16 +243,31 @@ Tool-pack setup separates three decisions that do not imply one another:
    user scope, or both. Placement controls where the capability is available;
    it does not authorize a repository `AGENTS.md` edit.
 2. **Project guidance** is an explicit choice to create an absent root
-   `AGENTS.md` or print a manual patch for its managed `OAT tools` section. Use
+   `AGENTS.md`, append an absent managed `OAT tools` section to an existing
+   one, or print a manual patch when that section exists but differs. Use
    `--project-guidance` to accept or `--no-project-guidance` to decline on
-   `oat init --setup`, `oat init tools`, and `oat tools install` flows. The
+   `oat init`, `oat init tools`, and `oat tools install`, including every
+   per-pack subcommand such as `oat tools install docs --project-guidance`:
+   the `OAT tools` block describes every installed pack, so any pack install
+   can write it. The `workflows` pack also offers guidance without the flag;
+   other pack commands plan it only when the flag is given. `oat init` without
+   `--setup` applies an explicit `--project-guidance` for the packs already
+   installed, because guided setup is not there to do it; with no pack
+   installed it writes nothing, reports `skipped` with a warning, and exits 0. The
    interactive prompt defaults to decline. Non-interactive runs perform no
    guidance write unless `--project-guidance` is present and report the exact
    opt-in command instead. When `AGENTS.md` already exists or is a contained
-   symlink, accepted guidance performs zero writes and prints the same
-   repository-relative, copy-pasteable managed block on every run. The patch
-   describes the complete realized project-and-user pack inventory and tells
-   the operator to remove a legacy `OAT workflows` block manually when needed.
+   symlink to a file inside the repository, accepted guidance appends an
+   absent `OAT tools` section with one append-only write (reported as
+   `appended`, exit 0) that never truncates, renames, or rewrites existing
+   bytes. A file with more than one hard link is never appended to; it gets
+   the manual patch instead, as does a file OAT cannot write (the patch names
+   the cause). A matching section is a no-op. A section that is present but
+   differs, or a legacy `OAT workflows` block that must be removed, gets zero
+   writes and the same repository-relative, copy-pasteable managed block on
+   every run, with a non-zero exit. The block describes the complete realized
+   project-and-user pack inventory and tells the operator to remove a legacy
+   `OAT workflows` block manually when needed.
 3. **PJM adoption** is the repository decision to use project-management state.
    Make it separately with `oat pjm init`; neither installing the
    `project-management` pack nor accepting tool guidance adopts PJM.
@@ -467,7 +482,7 @@ neither recognized legacy input nor a complete current layout is skipped with
 an `oat pjm init` recovery. `--print-prompt` only reads the bundled prompt and
 does not inspect adoption or modify the repository.
 
-Decision records still require repository PJM adoption. Run `oat pjm init` first: like every repository-mutating PJM command, `oat decision init` fails closed in an unadopted repository, writes nothing, and returns `oat pjm init` as the recovery. Once the repository is adopted, `oat decision init` scaffolds only the decision surface — the decision directory, generated index, and decision-specific AGENTS guidance — without touching current state, roadmap, or backlog artifacts. It does not require the `project-management` pack. A missing AGENTS file can be created exclusively; an existing file or symlink is left byte-for-byte unchanged and receives a manual decision-guidance patch. If the pack is installed later, project-management guidance remains a separate managed section so the decision instructions stay independently reusable.
+Decision records still require repository PJM adoption. Run `oat pjm init` first: like every repository-mutating PJM command, `oat decision init` fails closed in an unadopted repository, writes nothing, and returns `oat pjm init` as the recovery. Once the repository is adopted, `oat decision init` scaffolds only the decision surface — the decision directory, generated index, and decision-specific AGENTS guidance — without touching current state, roadmap, or backlog artifacts. It does not require the `project-management` pack. A missing AGENTS file can be created exclusively; an existing file or contained symlink target without an `OAT decisions` section gets that section appended with one append-only write that leaves every existing byte in place, and a section that exists but differs is left byte-for-byte unchanged and receives a manual decision-guidance patch. If the pack is installed later, project-management guidance remains a separate managed section so the decision instructions stay independently reusable.
 
 `oat pjm init` is idempotent and non-destructive. Existing reference docs are skipped and left unchanged, so curated repo state is not overwritten on repeated runs.
 
@@ -657,6 +672,41 @@ oat tools has brainstorm --scope user
 oat --json tools has workflows
 ```
 
+### `oat tools guidance`
+
+Purpose:
+
+- Print the managed `OAT tools` `AGENTS.md` block for the packs installed now,
+  without installing, upgrading, or writing anything
+
+Key behavior:
+
+- Reads installed pack placement at project and user scope (user scope only
+  outside a Git repository) and renders the same block, markers included,
+  that `--project-guidance` would create or append
+- Never touches `AGENTS.md`, pack assets, or config, so it is the safe way to
+  obtain the block for a manual edit, such as when an existing `OAT tools`
+  section differs and guidance prints a manual patch
+- The block names `.agents/skills/` only when a pack is installed at project
+  scope and `~/.agents/skills/` only when a pack is installed at user scope,
+  each with its packs, deciding by pack membership rather than by whether the
+  directory exists. Project skills that belong to no OAT pack are described
+  on a separate line, never as pack skills
+- `--json` returns `status`, `sectionKey` (`tools`), `target` (`AGENTS.md`),
+  `packs` (each `pack` with its `scope`), `otherProjectSkills` (names of
+  project skills that belong to no pack), and `managedBlock`
+- With no OAT pack installed it prints no block, only a note that there is
+  nothing to add (an empty block would be a stale placeholder); `--json`
+  returns `status: "no-packs"`, `managedBlock: null`, and a `message`
+- Exits `0` on success and `1` when pack state cannot be read
+
+Examples:
+
+```bash
+oat tools guidance
+oat --json tools guidance
+```
+
 ### `oat tools install`
 
 Purpose:
@@ -685,8 +735,8 @@ Key behavior:
   JSON output adds `adoptedPacks` only when the list is non-empty. This is pack
   intent reconciliation, not repository PJM adoption
 - A user-only capability install needs no Git repository and performs no repository writes unless `--project-guidance` explicitly requests the separate repository guidance update
-- Offers repository `AGENTS.md` guidance independently of capability scope. Pass `--project-guidance` to create an absent file or print a manual managed `OAT tools` patch for an existing file/symlink, or `--no-project-guidance` to decline; the interactive prompt defaults to decline and non-interactive runs write nothing without the explicit opt-in
-- Repository `AGENTS.md` guidance for project management is owned by adoption, not by pack placement. Installing the `project-management` pack never writes the section. `oat pjm init` creates guidance only when the root file is absent; otherwise it completes scaffold/adoption and prints a manual patch without changing the existing file or symlink
+- Offers repository `AGENTS.md` guidance independently of capability scope. Pass `--project-guidance` to create an absent file, append an absent managed `OAT tools` section to an existing file/symlink target, or print a manual patch for a section that exists but differs, or `--no-project-guidance` to decline; the interactive prompt defaults to decline and non-interactive runs write nothing without the explicit opt-in
+- Repository `AGENTS.md` guidance for project management is owned by adoption, not by pack placement. Installing the `project-management` pack never writes the section. `oat pjm init` creates the root file when it is absent and appends the absent `OAT project-management` and `OAT decisions` sections to an existing file (reported as `appended`, exit 0). A section that exists but differs from the managed version, or an `AGENTS.md` OAT will not append to (more than one hard link, or not writable), completes scaffold/adoption with one combined manual patch, printed once, and a non-zero exit, without changing the existing file or symlink; the header names the refusal cause when OAT could not append
 - Interactive runs can prompt to update selected outdated skills
 - Successful installs report the final scope chosen for each pack, including `project + user` when a pack is installed in both, and auto-sync only the scopes actually changed by the install so untouched scopes are never re-synced or pruned
 - Install-triggered auto-sync limits removal planning to the canonical entries from the pack that was just installed, so stale manifest drift in unrelated packs does not delete other provider views

package/assets/docs/contributing/code.md

@@ -73,12 +73,16 @@ checkout with neither `origin/main` nor `main` skips the whole gate (CI uses
 `fetch-depth: 0`). Test files under `packages/cli/src/` count as publishable
 changes for this gate.
 
-CI runs neither `pnpm lint` nor `pnpm format`. `pnpm check` now covers the
+CI runs neither `pnpm lint` nor `pnpm format`. `pnpm check` covers the
 formatting of `.agents/skills/**`, `apps/oat-docs/docs`, and `tools/smoke`
-through `format:root`, but `pnpm lint`'s root `oxlint` pass over `tools/smoke`
-and `.agents/skills`, and `packages/control-plane`'s `format` (it defines no
-`check` script), still run in no CI gate — run both whenever a change touches
-those paths.
+through `format:root`, and the `check` script of every package under
+`packages/` (`packages/control-plane` included) runs its `oxlint` passes and
+`oxfmt --check .` (the docs app's `check` covers only its Markdown), but
+`pnpm lint`'s root `oxlint` pass over `tools/smoke` and `.agents/skills` still
+runs in no CI gate — the smoke test that shells out to `pnpm lint` passes as
+long as its own seeded violations are reported, so it cannot catch an existing
+root-oxlint violation. Run `pnpm lint` and `pnpm format` whenever a change
+touches those paths.
 For narrower changes, use package-specific checks when possible, but do not
 merge without passing the relevant workspace gates.
 

package/assets/docs/provider-sync/commands.md

@@ -213,10 +213,11 @@ Purpose:
 Key behavior:
 
 - Read-only validation of nested project-scoped instruction directories
-- Supports `--strategy pointer|symlink|copy` to validate the expected file shape
-- Reports `ok`, `missing`, `content_mismatch`, and `stray` states
+- Validates the effective strategy: `--strategy none|pointer|symlink|copy`, else `instructions.claude.shims`, else `none` (the default, which expects no `CLAUDE.md`); reports it as `strategy` under `--json`
+- Reports `ok`, `missing` (shim strategies only), `content_mismatch`, `stray`, and, under `none`, `managed_shim` (drift sync removes) and `unmanaged` (kept, not drift)
 - Detects Claude-only adoptable directories and unreadable/broken instruction paths as drift
-- Skips the derived documentation content root and any `documentation.instructionPointerExcludes` paths, using the same exclusions as `oat instructions sync`
+- Under `none`, warns about every remaining `CLAUDE.md`, `.claude/CLAUDE.md`, and `CLAUDE.local.md` (stderr, or the `warnings` array under `--json`) without changing the exit code
+- Skips the derived documentation content root and any `instructions.claude.excludes` paths, using the same exclusions as `oat instructions sync`
 - Exit code `0` when all entries are valid, `1` when drift is detected
 - Detailed behavior: [`Instruction Sync`](instruction-sync.md)
 
@@ -229,12 +230,14 @@ Purpose:
 Key behavior:
 
 - Mutates by default; use `--dry-run` to preview changes
-- Supports `--strategy pointer|symlink|copy`
-- Creates missing `CLAUDE.md` files using the selected strategy
-- Adopts Claude-only stray files by writing canonical `AGENTS.md` content first, then regenerating `CLAUDE.md`
-- Skips mismatched files unless `--force` is provided
+- Supports `--strategy none|pointer|symlink|copy` as a one-run override of `instructions.claude.shims` (default `none`)
+- Under `none`, removes the `CLAUDE.md` shims OAT created (exact `@AGENTS.md` pointer, symlink to the sibling `AGENTS.md`, or byte-identical copy), re-verifying each immediately before deletion; hand-written or modified `CLAUDE.md` files are reported, never deleted, and while any `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` has content of its own, nothing is removed (`claude_md_blocks_shim_removal`)
+- Under a shim strategy, creates missing `CLAUDE.md` files using that strategy
+- Adopts Claude-only stray files by writing canonical `AGENTS.md` content first, then regenerating `CLAUDE.md` (shim strategies) or removing it (`none`)
+- Under a shim strategy, skips mismatched files unless `--force` is provided
 - Skips unreadable canonical or Claude-only sources and reports manual-repair guidance instead of forcing recovery
-- Skips the documentation content tree (`<documentation.root>/docs` when that is a directory, otherwise `documentation.root`) plus any `documentation.instructionPointerExcludes` paths, so authored pages never receive pointers; app-level instruction files such as `apps/oat-docs/AGENTS.md` are still synced
+- Skips the documentation content tree (`<documentation.root>/docs` when that is a directory, otherwise `documentation.root`) plus any `instructions.claude.excludes` paths, so authored pages never receive pointers; app-level instruction files such as `apps/oat-docs/AGENTS.md` are still synced
 - Never deletes an existing `CLAUDE.md` inside an excluded tree
+- Under `none`, warns about every `CLAUDE.md` that remains after sync, including inside excluded trees, because any one of them makes Claude Code ignore every `AGENTS.md`
 - Uses pointer content `@AGENTS.md\n`, file symlinks, or hard copies depending on the selected strategy
 - Detailed behavior and examples: [`Instruction Sync`](instruction-sync.md)