@open-agent-toolkit/cli 0.3.12 → 0.3.14

package/README.md

@@ -72,7 +72,7 @@ Use these commands when you want structured runtime/project state out of the CLI
 ## Docs
 
 - [Docs Home](https://voxmedia.github.io/open-agent-toolkit/)
-- [CLI Utilities](https://voxmedia.github.io/open-agent-toolkit/cli-utilities)
+- [CLI Utilities](https://voxmedia.github.io/open-agent-toolkit/reference#general-cli-adoption-guidance)
 - [Provider Sync](https://voxmedia.github.io/open-agent-toolkit/provider-sync)
 - [Instruction Sync](https://voxmedia.github.io/open-agent-toolkit/provider-sync/instruction-sync)
 - [Reference](https://voxmedia.github.io/open-agent-toolkit/reference)

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.3.12"
+  "oatVersion": "0.3.14"
 }

package/assets/docs/contributing/index.md

@@ -10,7 +10,7 @@ Use this section when you are changing OAT itself rather than consuming it as a
 ## Contents
 
 - [Contributing Code](code.md) - Repo setup, monorepo structure, quality gates, and PR expectations.
-- [Contributing Docs](documentation.md) - Docs contract, local docs workflow, and docs-specific authoring guidance.
+- [Contributing to OAT Docs](documentation.md) - Docs contract, local docs workflow, and docs-specific authoring guidance.
 - [Markdown Features](markdown-features.md) - Supported docs syntax for callouts, tabs, Mermaid, and code blocks.
 - [Writing Skills](skills.md) - Skill authoring guidance, runtime contracts, and governance.
 - [CLI Design Principles](design-principles.md) - Cross-cutting CLI architecture and UX principles.
@@ -19,3 +19,16 @@ Use this section when you are changing OAT itself rather than consuming it as a
 - [Smoke Testing](smoke-testing.md) - Runbook for the live workflow smoke runner: prerequisites, scenarios, evidence reports, and recovery.
 - [Updating Model Guidance](updating-model-guidance.md) - Source map and verification checklist for provider model refreshes.
 - [Verifying Cursor Pins](verifying-cursor-pins.md) - Runbook for probe-verifying a Cursor model pin before shipping it.
+
+## Source-of-truth hierarchy
+
+When you document OAT behavior, check it against these sources, highest
+first:
+
+1. Runtime behavior: `packages/cli/src/**`
+2. Skill behavior contracts: `.agents/skills/*/SKILL.md`
+3. OAT templates and runtime state: `.oat/templates/**`, `.oat/sync/**`, `.oat/config.json`, `.oat/config.local.json`
+4. Repo reference records: `.oat/repo/**`
+
+New pages belong in one of the top-level sections listed on the
+[docs home page](../index.md); the older `guide/` section no longer exists.

package/assets/docs/contributing/skills.md

@@ -363,7 +363,7 @@ The Gate Execution step should:
 
    A null, missing, malformed, or unrecognized result is an operational failure
    that fails closed as unresolved. Never treat it as "no gate configured." See
-   [Per-project gate overrides](../cli-utilities/workflow-gates.md#per-project-gate-overrides).
+   [Per-project gate overrides](../workflows/advanced/workflow-gates.md#per-project-gate-overrides).
 
 3. Export the resolved path with `export PROJECT_PATH` before launching the
    command shell.
@@ -387,7 +387,7 @@ that should report only the child process status, not review findings.
 Reusable lifecycle gate commands must omit `--target <id>` so the
 dispatcher can avoid the current runtime; reserve explicit targets for
 manual/debug commands or deliberate local/user-specific overrides. See
-[Workflow Gates](../cli-utilities/workflow-gates.md) for the config and command
+[Workflow Gates](../workflows/advanced/workflow-gates.md) for the config and command
 surface.
 
 ## Reading project state
@@ -438,3 +438,65 @@ The JSON output is a stable contract: the field set consumed by migrated skills
 - `.agents/skills/oat-project-implement/SKILL.md`
 - `.agents/skills/oat-project-complete/SKILL.md`
 - `.agents/skills/oat-project-review-receive/SKILL.md`
+
+## create-agnostic-skill
+
+**Invocation:** `/create-agnostic-skill verify-migration` (or
+`$create-agnostic-skill verify-migration` in Codex). The skill is
+explicit-invocation only, so use the slash or `$` form rather than asking the
+agent to pick it. These are agent instructions, not terminal commands. Supply
+a kebab-case skill name, or answer the naming question when prompted.
+
+**Prerequisites:** A repeatable workflow with a stable enough trigger,
+sequence, and outcome to be reusable, plus permission to create files in the
+repository's canonical `.agents/skills/` directory. Needs an active OAT
+project: no. Before creating another skill, check whether composition of
+existing skills would meet the need. For a new `oat-*` skill, use
+`/create-oat-skill` instead; it builds on this workflow and adds OAT
+conventions such as `{PROJECTS_ROOT}` resolution and progress banners.
+
+**Example scenario:** Your team repeatedly reviews database migrations for
+rollback assumptions, compatibility with the previous application version,
+and operator handoff. Turn that recurring review into a portable skill that
+asks for the migration and constraints, produces a review, and stops before
+running database commands. The skill is not a place to hide production
+execution behind a convenient trigger.
+
+The authoring conversation establishes when the skill should run, what it
+accepts, what it produces, which tools it needs, and what remains outside its
+authority. The agent presents a bounded file plan and asks for approval
+before creating anything. Expanding the approved file set requires another
+confirmation; approval of a `SKILL.md` does not implicitly authorize an
+unplanned collection of scripts or assets.
+
+**What it does without asking:** Before your approval it only asks questions
+and presents the file plan; if you decline, it creates nothing. After you
+approve the plan once, it creates the skill directory, its `SKILL.md`, and the
+planned supporting files without asking again, then, in a repository that
+uses OAT sync, runs `oat sync --scope project` to refresh this repository's provider views (the
+provider-specific copies such as `.claude/skills/`). For a skill whose name
+starts with `oat-`, it also runs `pnpm oat:validate-skills`. It does not
+commit, push, or install the skill at user scope.
+
+Use progressive disclosure to keep the result useful. The frontmatter's
+trigger-oriented description helps an agent choose the skill. The body
+contains the actual ordered workflow and stop conditions. Put detailed
+references, deterministic helpers, and templates in supporting directories
+only when the workflow needs them. Include both a direct invocation and a
+conversational example so users can recognize the intended trigger without
+memorizing provider-specific syntax.
+
+**Expected output:** An approved canonical skill at
+`.agents/skills/verify-migration/SKILL.md`, with its name matching the
+directory, an initial `metadata.version` of `1.0.0`, workflow steps, examples, and any
+approved support files. The authoring workflow synchronizes the project
+scope and checks tool/provider discoverability; it does not install the
+skill into the user's global scope. Canonical content remains the editable
+owner rather than being duplicated into provider views.
+
+**Next step:** Exercise the skill with a representative migration and verify
+that its instructions produce the intended review without crossing the
+execution boundary. Adjust the canonical workflow if the trigger or outcome
+is unclear, then resynchronize project views. Pack distribution, public
+publication, and user-scope installation are separate decisions, not an
+automatic consequence of local authoring.

package/assets/docs/contributing/smoke-testing.md

@@ -224,7 +224,7 @@ Reading the output:
 The evidence is organized as three layers — launcher-owned production records,
 independent durable corroboration from Git and the fixture, and the normalized
 bundle and assertion report. See
-[Evidence Layers](../workflows/projects/evidence-layers.md) for the model.
+[Evidence Layers](../workflows/advanced/evidence-layers.md) for the model.
 
 ## Cleanup and recovery
 
@@ -324,5 +324,5 @@ fixture does not pass, the workflow change is not accepted.
 ## Related
 
 - [Contributing Code](code.md)
-- [Implementation Execution](../workflows/projects/implementation-execution.md)
-- [Dispatch Ceiling](../workflows/projects/dispatch-ceiling.md)
+- [Implementation Execution](../workflows/projects/execution/implementation-execution.md)
+- [Dispatch Ceiling](../workflows/advanced/dispatch-ceiling.md)

package/assets/docs/contributing/updating-model-guidance.md

@@ -81,7 +81,7 @@ or GPT-6.1 Cursor targets until that runtime lists and verifies them.
 A 2026-09-25 desktop 3.21.18 probe added Grok 4.6 and Fable 5.1 mappings
 and moved the bundled Cursor ladder to them. The same probe showed Grok 4.7
 resolves only bare flat IDs, never bracket selectors. It still needs its own
-approved registry entry and complete per-pin evidence before admission; see [Verifying Cursor Pins](verifying-cursor-pins.md). See [Dispatch Policy](../workflows/projects/dispatch-ceiling.md#cursor-evidence-authority)
+approved registry entry and complete per-pin evidence before admission; see [Verifying Cursor Pins](verifying-cursor-pins.md). See [Dispatch Policy](../workflows/advanced/dispatch-ceiling.md#cursor-evidence-authority)
 for the distinction between catalog, configured mapping, and runtime identity.
 
 The October 1 refresh migrates Codex Sol defaults and examples to
@@ -142,5 +142,5 @@ bundled cells in the chosen scope, with a warning and a `--dry-run` preview;
 extra custom cells remain. Add `--keep-existing` to fill only missing cells.
 The active project's named ceiling is a separate policy in its `state.md`;
 a model update must not silently change it.
-See [Dispatch Policy](../workflows/projects/dispatch-ceiling.md#ownership-and-adoption)
+See [Dispatch Policy](../workflows/advanced/dispatch-ceiling.md#ownership-and-adoption)
 for config precedence and examples.

package/assets/docs/contributing/verifying-cursor-pins.md

@@ -339,5 +339,5 @@ oat sync --scope project
 ## Related
 
 - [Smoke Testing](smoke-testing.md) - Runbook for the live workflow smoke runner.
-- [Dispatch Policy](../workflows/projects/dispatch-ceiling.md) - How pins reach the recommendation and role files.
+- [Dispatch Policy](../workflows/advanced/dispatch-ceiling.md) - How pins reach the recommendation and role files.
 - [Provider Sync](../provider-sync/providers.md) - Provider-specific sync behavior.

package/assets/docs/docs-tooling/add-docs-to-a-repo.md

@@ -1,11 +1,11 @@
 ---
-title: Add Docs to a New Repo
-description: 'Step-by-step guide for adding an OAT-managed docs app to a repository.'
+title: Add or Adopt Docs in a Repo
+description: 'Step-by-step guide for adding or adopting OAT-managed documentation to a repository.'
 ---
 
-# Add Docs to a New Repo
+# Add or Adopt Docs in a Repo
 
-Use this path when you want to add an OAT-managed docs app and the docs
+Use this path when you want to add or adopt documentation and the docs
 analyze/apply workflow to a repository.
 
 If you are developing inside the OAT repo itself, replace `oat ...` with
@@ -13,7 +13,7 @@ If you are developing inside the OAT repo itself, replace `oat ...` with
 
 ## What this gives you
 
-- a docs app scaffolded with OAT defaults (Fumadocs or MkDocs)
+- plain Markdown files or a docs app scaffolded with OAT defaults (Fumadocs or MkDocs)
 - `index.md`-driven navigation
 - docs analysis and apply skills installed via the docs pack
 - a repeatable workflow for finding gaps, verifying claims, and applying docs changes
@@ -51,9 +51,9 @@ The docs pack installs `authoring-docs`, `oat-docs-authoring`,
 `oat-agent-instructions-apply`. For this quickstart, the authoring and docs
 analysis/apply skills are the parts you need immediately.
 
-## 3. Scaffold the docs app
+## 3. Set up the documentation surface
 
-Two paths — pick one:
+Choose Markdown files or a framework app, using the guided skill or direct CLI.
 
 ### 3a. Preferred: the `oat-docs-bootstrap` skill (guided)
 
@@ -61,9 +61,11 @@ Two paths — pick one:
 /oat-docs-bootstrap
 ```
 
-The docs-bootstrap skill wraps `oat docs init` with a seven-step guided flow: preflight detection (repo shape + existing-setup conflict surfacing), richer input gathering (including a site name distinct from the package name), the CLI invocation itself, labeled post-patches for open CLI gaps, install + build verification, post-scaffold config inspection, and a chunked educational walkthrough.
+The docs-bootstrap skill offers Markdown, Fumadocs, and MkDocs. Configured tooling is authoritative; framework evidence is checked before plain-directory evidence. A root README alone does not trigger adoption, and an empty selected target stays fresh setup. Markdown uses file checks and an adopt/audit handoff, with no app questions, dependencies, framework patches, docs-root AGENTS, or site build.
 
-What the skill adds over the raw CLI:
+For framework apps, it wraps `oat docs init` with a seven-step guided flow: preflight detection (repo shape + existing-setup conflict surfacing), richer input gathering (including a site name distinct from the package name), the CLI invocation itself, labeled post-patches for open CLI gaps, install + build verification, post-scaffold config inspection, and a chunked educational walkthrough.
+
+What the framework path adds over the raw CLI:
 
 - **Preflight + conflict resolution.** Detects existing `documentation` config / docs app dir / root `AGENTS.md` section and walks a deliberate resolution choice (replace, abort, repair, or deferred second-app) before any mutation.
 - **Richer inputs.** Asks for a **site name** separate from the package name, so `createDocsConfig()` / layout branding / page metadata all converge on the same display title.
@@ -90,10 +92,11 @@ oat docs init --app-name my-docs
 
 In interactive mode, you'll be prompted to choose a framework:
 
+- **Markdown** — authored files, context indexes, and Contents maps without a site framework
 - **Fumadocs** — Next.js-based static site with FlexSearch, Mermaid diagrams, dark/light mode, and code copy buttons
 - **MkDocs** — MkDocs Material with the OAT contributor contract
 
-Default placement:
+Framework default placement:
 
 - monorepo: `apps/my-docs`
 - single-package repo: `my-docs/` at repo root
@@ -113,8 +116,68 @@ Use 3b when you want a fully headless scaffold (CI, automation) and can accept t
 For compatible Turbo monorepos, the CLI also patches the repo-root
 `package.json` by default so root `pnpm build` excludes the new docs app and a
 root `build:docs` script is available for docs-only builds. Use
-`--no-root-patch` to opt out, or `--dry-run` to preview the diff without
-writing it.
+`--no-root-patch` to opt out. `--dry-run` is available only for Markdown
+files/config/guidance; it does not preview framework package patches.
+
+### Plain Markdown: fresh setup or additive adoption
+
+```bash
+# Fresh default root: docs/ in every repository shape
+oat docs init --framework markdown --site-name "Project Docs" --yes
+
+# Existing content: preview, then explicitly adopt without overwriting files
+oat docs init --framework markdown --target-dir handbook --adopt --dry-run --yes
+oat docs init --framework markdown --target-dir handbook --adopt --yes
+```
+
+Markdown creates missing `index.md` and `contributing.md` baseline pages and
+records `documentation.tooling: "markdown"`, the literal root, and its authored
+`<root>/index.md`. A nested `<root>/docs` remains a subsection. Root managed
+Documentation guidance names these paths; bootstrap creates no docs-root
+`AGENTS.md` and preserves one already present. It creates no app package,
+framework config, dependencies, or install/dev/build commands. Lint/format
+choices default to `none` and never install tools.
+
+A default setup records:
+
+```json
+{
+  "documentation": {
+    "tooling": "markdown",
+    "root": "docs",
+    "index": "docs/index.md"
+  }
+}
+```
+
+A populated target is refused without `--adopt`, including with `--yes`.
+Adoption preserves existing page/index/local-instruction bytes and adds only
+missing baseline files. Missing child indexes, metadata, context, or Contents
+remain audit gaps: run `oat-docs-analyze`, then `oat-docs-apply` for approved
+repairs. Successful config/guidance setup does not prove full content conformity.
+See [Markdown setup details](commands.md#oat-docs-init) for initial Contents
+discovery and repair advice for optional child indexes and unreadable directories.
+
+Incompatible declared tooling/root/index or unsafe paths are refused before
+writes. Selecting a framework explicitly retains its existing replacement
+prompt/`--yes` behavior, including over configured Markdown: config may change
+while old Markdown files remain. This is not an automatic content migration.
+
+Dry-run writes nothing. Manual-required or blocked guidance returns `partial`
+and exit `1`; files/config are planned, not completed. A real partial run may
+already have created baseline files and config: follow its reported state and
+preserve those files when retrying. Converged repeated adoption returns `ok`,
+exit `0`, and no changes.
+
+Markdown indexes are authored. Optional inventories require external output:
+
+```bash
+oat docs generate-index --docs-dir handbook --output .oat/docs-manifest.md
+```
+
+Default generation is refused for configured Markdown. External output cannot
+be inside the full configured content root or overwrite its authored index,
+even with a narrowed `--docs-dir`. It never repoints `documentation.index`.
 
 ### 3c. Existing MkDocs content
 
@@ -132,13 +195,15 @@ refactor, use the assigned migration handoff guide or project plan; do not make
 
 ## 4. Start authoring docs with the OAT contract
 
-Use `oat-docs-authoring` for targeted OAT/Fumadocs content edits or local
+Use `oat-docs-authoring` for targeted OAT Markdown/Fumadocs content edits or local
 restructuring. It uses `authoring-docs` for the portable documentation baseline
 and adds the OAT-specific navigation, generated-index, and validation contract.
 
 Core rules:
 
-- every docs directory should have an `index.md`
+- every non-excluded Markdown-bearing docs directory should have an authored `index.md`
+- preserve useful audience/scope context and nonempty title/description metadata
+- honor asset-only exceptions, configured excludes, and existing local instructions
 - every `index.md` should include a `## Contents` section
 - the `## Contents` section should map sibling pages and immediate child directories
 - `## Contents` links should use `.md`-suffixed relative targets, including `subdir/index.md` for child directories
@@ -214,7 +279,7 @@ Important:
 3. `oat docs init --app-name my-docs`
 4. (optional) handle MkDocs migration as a separate workstream; use `oat docs migrate --docs-dir docs --config mkdocs.yml --apply` only for the syntax/frontmatter helper
 5. Author docs with `index.md` + `## Contents`
-6. `oat docs nav sync --target-dir apps/my-docs` (both frameworks), plus `oat docs generate-index` (Fumadocs)
+6. Check Markdown files/links, or refresh declared artifacts with `oat docs nav sync --target-dir apps/my-docs` (both frameworks), plus `oat docs generate-index` (Fumadocs)
 7. `/oat-docs-analyze`
 8. `/oat-docs-apply`
 9. Repeat as the codebase changes
@@ -224,3 +289,35 @@ Important:
 - [`commands.md`](commands.md)
 - [`workflows.md`](workflows.md)
 - [`../reference/docs-index-contract.md`](../reference/docs-index-contract.md)
+
+## Choosing Markdown or a site framework
+
+`oat docs init --framework` (and the `oat-docs-bootstrap` skill) sets up one of
+three kinds of documentation. In all three, each folder's `index.md` has a
+`## Contents` list of its pages.
+
+| Framework      | Choose it when                                                       | What you give up                                                                                                       |
+| -------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Plain Markdown | People and agents read the docs in the repository; no site is needed | A rendered site and search. You keep each `## Contents` list up to date by hand                                        |
+| Fumadocs       | A Node/pnpm repository wants a hosted docs site                      | An app with dependencies and a build. A page missing from its folder's `## Contents` list is hidden from the sidebar   |
+| MkDocs         | The team already uses Python and MkDocs Material                     | Python setup (`setup-docs.sh` runs `pip install`). `oat docs nav sync` rewrites the whole `nav:` block of `mkdocs.yml` |
+
+When nothing chooses for it (a non-interactive run or `--yes`), `oat docs init`
+uses Fumadocs. That is only a default; pick the smallest option your readers
+need.
+
+- If you are a solo developer or a team that only needs guides readable in the
+  repository, choose plain Markdown. It adds no app, dependencies, or build.
+- If a Node/pnpm team wants a hosted site, choose Fumadocs. Its build hooks
+  regenerate the app-root `index.md` inventory but not the sidebar files, so run
+  `oat docs nav sync` after adding, moving, or renaming pages, commit the
+  `meta.json` files it writes, and add `oat docs nav sync --check` to your build
+  or CI yourself, because the scaffold does not.
+- If your team uses Python and MkDocs Material, choose MkDocs. Run
+  `oat docs nav sync --check` to see what would change before letting nav sync
+  rewrite `nav:`.
+- If the repository already has docs, do not initialize over them. Adopt
+  existing plain Markdown with `--adopt` (try `--dry-run` first), and record an
+  existing MkDocs site with `oat init --setup` instead of `oat docs init`. When
+  moving an MkDocs site to Fumadocs, `oat docs migrate` converts MkDocs syntax
+  and frontmatter; it only previews changes until you pass `--apply`.

package/assets/docs/docs-tooling/agent-instructions.md

@@ -0,0 +1,131 @@
+---
+title: Improve Agent Instructions
+description: Audit instruction coverage and accuracy, then apply approved recommendations without inventing repository conventions.
+---
+
+# Improve Agent Instructions
+
+Keep analysis and application separate. The analysis report establishes what
+is supported by repository evidence; apply translates selected recommendations
+into canonical instructions and provider views. Canonical instructions are
+the provider-neutral source files OAT treats as the source of truth, such as
+`AGENTS.md` and rule files under `.agents/rules/`. Provider views are the
+per-tool files, such as Cursor rule files, that `oat sync` generates from
+them. Neither skill needs an active OAT project.
+
+The analysis report is an analysis artifact: a timestamped Markdown report
+that analyze writes under `.oat/repo/analysis/` and that apply later reads.
+
+The invocations below are agent instructions, not terminal commands. Use
+slash names where supported, `$name` in Codex, or ask for the skill by name.
+
+## oat-agent-instructions-analyze
+
+**Invocation:** `/oat-agent-instructions-analyze` in the repository you want
+to evaluate. Confirm the provider scope when prompted so the audit covers
+the instruction formats your team actually uses.
+
+**Prerequisites:** A Git repository with at least one instruction file (root
+`AGENTS.md` is the baseline), accessible configuration/documentation evidence,
+and `jq` for the helper scripts. OAT documentation configuration is useful when present but not
+required for discovering the repository's documentation surfaces. No active
+project is required.
+
+**Example scenario:** Claude, Cursor, and Codex users receive inconsistent
+test instructions, and a nested package has no clear ownership guidance.
+Audit the canonical instructions and relevant provider views against actual
+package scripts and local documentation before copying another provider's
+rules into every directory.
+
+The audit checks quality, coverage, existing-rule accuracy, progressive
+disclosure, file-type opportunities, and cross-format consistency. Full or
+delta analysis follows valid tracking evidence. Claims about exhaustive
+consistency need exhaustive evidence, not a convenient sample. Formatting
+tools and canonical documentation are often better linked than restated as
+large always-loaded instruction blocks.
+
+Provider recommendations follow configured policy. For example, a Claude
+shim (a `CLAUDE.md` file whose job is to import `AGENTS.md` with
+`@AGENTS.md`) is not universally required. The setting
+`instructions.claude.shims` chooses the strategy. Under the default, `none`,
+Claude Code reads `AGENTS.md` itself, so analysis recommends no `CLAUDE.md`.
+Under `pointer`, `symlink`, or `copy`, it checks for the matching shim next
+to each `AGENTS.md`.
+
+Some `CLAUDE.md` files hold the only copy of instructions that an
+`AGENTS.md` links to. For those files, the recommended fix is to move the
+content into each linking `AGENTS.md` first and only then remove the file.
+A duplication finding is never permission to discard the sole copy of
+useful guidance.
+
+**Expected output:** A human-readable
+`.oat/repo/analysis/agent-instructions-<timestamp>.md` report and its
+companion bundle. The companion bundle is a folder next to the report
+(`agent-instructions-<timestamp>.bundle/`) that holds `summary.md`,
+`recommendations.yaml`, and one recommendation pack file per recommendation
+under `packs/`. The bundle is what apply generates from; the Markdown report
+provides review context. The default bounded artifact-review loop can
+correct these outputs but cannot edit downstream instruction files. Skipped
+review and residual findings remain visible in the handoff.
+
+**What it does without asking:** It writes the report and companion bundle
+under `.oat/repo/analysis/`, lets its review loop correct them, and updates
+its tracking record in `.oat/tracking.json`. It does not create or modify
+instruction files or repository configuration.
+
+**Next step:** Review the recommendations and use
+[oat-agent-instructions-apply](#oat-agent-instructions-apply) for approved
+changes. Resolve missing evidence in analysis rather than making apply guess
+which convention new files should follow.
+
+## oat-agent-instructions-apply
+
+**Invocation:** `/oat-agent-instructions-apply` after reviewing an analysis
+artifact. Choose batch approval, recommendation-by-recommendation review,
+discussion, or cancellation when the skill presents the plan.
+
+**Prerequisites:** A Git repository, `jq`, the installed
+`oat-agent-instructions-analyze` skill (apply reuses its scripts and stops if
+it cannot find them), and a recent analysis artifact. Apply always reads the
+newest `.oat/repo/analysis/agent-instructions-*.md` report. Each
+recommendation needs evidence, confidence, a disclosure decision (whether
+the item is written inline, added only as a link, omitted, or left for you
+to decide), and concrete link targets for link-only recommendations. When a
+companion bundle exists, it is the primary generation contract; older
+Markdown-only artifacts remain supported. `gh` is needed only if you want
+apply to open the pull request. No active OAT project is required.
+
+**Example scenario:** The audit recommends fixing one inaccurate test command
+and adding scoped guidance to a package. Approve those two changes, but
+decline a proposed always-loaded architecture summary in favor of its
+documentation link. The resulting instructions should preserve that
+disclosure choice rather than copying the full summary into every provider.
+
+Apply may reopen cited sources to verify them and generate instruction text,
+but cannot add new recommendations or infer a formatting rule from tool
+defaults. Missing preferred patterns, evidence, or link targets are reasons
+to stop for clarification. Provider baselines must already be explicit in
+the analysis, including which shim strategy applies.
+
+**Expected output:** Approved canonical instruction and rule changes
+committed on a new `oat/agent-instructions-<timestamp>` branch, with
+regenerated provider views where needed. The plan and source-backed
+rationale remain aligned with the analysis bundle.
+
+**What it does without asking:** Nothing changes until you approve the plan
+(choosing `cancel`, or skipping every item, exits without changes). After
+approval, apply continues without asking again. It creates branch
+`oat/agent-instructions-<timestamp>` and writes the approved files. Items
+whose disclosure is `ask_user` are confirmed with you once more before they
+are written. When it writes canonical rule files, it runs
+`oat sync --scope project` to regenerate the provider views. It then commits
+the generated and updated files as `chore: update agent instruction files`.
+If the branch cannot be created (for example because of uncommitted
+changes), it asks you to resolve that first. After committing, it asks
+whether to push and open a pull request; only a yes pushes. The PR targets
+`main`, and its body includes the applied plan and the full analysis
+report. Finally it updates `.oat/tracking.json`.
+
+**Next step:** Review the committed diff and provider scope before you agree
+to push or open a pull request. Reanalyze when you need to evaluate new
+conventions or gaps; apply is not a second independent audit.