@open-agent-toolkit/cli 0.3.9 → 0.3.11

package/assets/skills/oat-cursor-cloud-projects/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Write, Bash, Glob, Grep
 metadata:
-  version: 1.1.2
+  version: 1.1.3
 ---
 
 # OAT in Cursor Cloud
@@ -183,7 +183,7 @@ commands from the target repository or pass their supported project path.
 
 ### Step 3: Resolve Assets with User Scope First
 
-Apply one source order independently to every asset file:
+Apply one source order independently to every skill and script file:
 
 1. user scope;
 2. target-repository scope when the user asset is absent;
@@ -191,18 +191,30 @@ Apply one source order independently to every asset file:
 
 User locations:
 
-| Asset    | User source                 |
-| -------- | --------------------------- |
-| Skill    | `~/.agents/skills/<skill>/` |
-| Template | `~/.oat/templates/<file>`   |
-| Script   | `~/.oat/scripts/<file>`     |
+| Asset  | User source                 |
+| ------ | --------------------------- |
+| Skill  | `~/.agents/skills/<skill>/` |
+| Script | `~/.oat/scripts/<file>`     |
 
-Repository locations are `.agents/skills/`, `.oat/templates/`, and
-`.oat/scripts/` within the target repository.
+Repository locations are `.agents/skills/` and `.oat/scripts/` within the
+target repository.
 
-The user tier is provisioned from `@latest` at environment boot and is the
-canonical execution tier. Repository copies in this fleet are not customized;
-a difference indicates staleness, not a local override.
+For skills and scripts, the user tier is provisioned from `@latest` at
+environment boot and is the canonical execution tier. Repository copies of
+skills and scripts in this fleet are not customized; a difference indicates
+staleness, not a local override.
+
+Templates are the exception. They resolve repository, then user, then bundled,
+the same order every lifecycle skill uses, because a repository template is an
+owner override. Resolve them only through the CLI, run from the target
+repository:
+
+```bash
+oat template resolve <name> --json                      # report the tier
+oat template resolve <name> --output "<destination>"    # copy the template
+```
+
+Do not read `~/.oat/templates/` directly or choose a template tier by hand.
 
 #### Absolute-path loading contract
 
@@ -213,7 +225,6 @@ Therefore, resolve and read the selected user asset by absolute path as the
 
 ```bash
 USER_SKILLS_ROOT="${HOME}/.agents/skills"
-USER_TEMPLATES_ROOT="${HOME}/.oat/templates"
 USER_SCRIPTS_ROOT="${HOME}/.oat/scripts"
 ```
 
@@ -238,8 +249,9 @@ It never chooses the source:
 - if freshness is safety-critical, refresh and re-verify before continuing;
   stop if the user tier cannot be refreshed safely.
 
-Never silently switch to the repo copy. Apply per-file precedence to templates
-and scripts without using skill semver as their arbitration mechanism.
+Never silently switch to the repo copy. Apply per-file precedence to scripts
+without using skill semver as their arbitration mechanism; templates follow
+`oat template resolve`.
 
 ### Step 4: Load Cursor Dispatch Context When Needed
 
@@ -328,7 +340,9 @@ separate dispatch surface and snapshot its current catalog. See
 - ✅ `oat` was verified before project artifact work.
 - ✅ The project home is anchored inside the target repository in both single-
   and multi-repo environments.
-- ✅ Existing user assets won independently for skills, templates, and scripts.
+- ✅ Existing user assets won independently for skills and scripts.
+- ✅ Templates were resolved through `oat template resolve` (repository, user,
+  then bundled).
 - ✅ Skill version comparison verified freshness without changing source.
 - ✅ User assets were read by absolute path as the primary mechanism.
 - ✅ Cursor dispatch mechanics remained delegated to the canonical provider

package/assets/skills/oat-dispatch-subagents/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: false
 allowed-tools: Read
 metadata:
-  version: 1.2.10
+  version: 1.2.12
 ---
 
 # Dispatching OAT Subagents
@@ -176,17 +176,9 @@ terminal outcome, not a pre-start rejection, and must be recorded through
 `provesNoChildStarted: true`, and no fallback is authorized.
 
 The calling workflow records each launch in its own run record (request ID,
-`Dispatch:` stamp, launch status, terminal outcome). Writing a per-dispatch file with `oat project dispatch record` is optional and off by default: no lifecycle skill or command consumes those files, so do not write them unless the host has explicitly opted in. A host that has opted
-in passes the validated record and event on standard input:
-
-```bash
-oat project dispatch record \
-  --project "$PROJECT_PATH" \
-  --event-file - \
-  --json
-```
-
-The command validates and persists evidence only. It never launches a provider.
+`Dispatch:` stamp, launch status, terminal outcome); that run record is the
+only launch record. `oat project dispatch record --event-file - --json`
+validates a record and event and writes nothing. It never launches a provider.
 
 ## Capability and Authorization
 

package/assets/skills/oat-dispatch-subagents/references/managed-claude-example.json

@@ -1,5 +1,5 @@
 {
-  "description": "Managed Claude validation-only inputs for `oat project dispatch record --event-file <file> --json` (no --project). Each role key is one complete input. claudeLaunch.resolution is `oat project dispatch-ceiling resolve --provider claude --role <role> --json` output verbatim; claudeLaunch.definition is the generated Claude agent file content; claudeLaunch.payload is the exact launch payload; event is `oat project dispatch canonical-role --json` output. Built from fixture agents, so the definition body, role version, and content digest are illustrative. See record-schema.md, Managed Claude Validation Input.",
+  "description": "Managed Claude validation-only inputs for `oat project dispatch record --event-file <file> --json`. Each role key is one complete input. claudeLaunch.resolution is `oat project dispatch-ceiling resolve --provider claude --role <role> --json` output verbatim; claudeLaunch.definition is the generated Claude agent file content; claudeLaunch.payload is the exact launch payload; event is `oat project dispatch canonical-role --json` output. Built from fixture agents, so the definition body, role version, and content digest are illustrative. See record-schema.md, Managed Claude Validation Input.",
   "implementer": {
     "claudeLaunch": {
       "resolution": {

package/assets/skills/oat-dispatch-subagents/references/provider-codex.md

@@ -110,3 +110,54 @@ Add a service tier or reasoning mode only through controls shown by the current
 CLI/schema. Honor the caller's authorization boundary. Record every selector
 as configured invocation evidence; do not infer runtime identity from process
 success alone.
+
+## Agent-Limit Rejections and v2 Residency
+
+A native spawn rejected with `agent thread limit reached`
+(`AgentLimitReached`) before any child is accepted is a pre-start
+provider/dispatch outcome, not a worker failure, and not by itself evidence of
+cumulative or lifetime thread exhaustion. The v2 lifecycle facts below are
+cited from the openai/codex `rust-v0.159.2` tag; re-check them when the
+installed Codex version changes.
+
+- Before returning `AgentLimitReached`, v2 admission tries to unload an eligible
+  resident. A resident is eligible only when it is completed, errored, or
+  interrupted, has no active turn, has no pending mailbox items, and holds no
+  residency lock
+  ([`residency.rs` L99-L120](https://github.com/openai/codex/blob/rust-v0.159.2/codex-rs/core/src/agent/control/residency.rs#L99-L120),
+  [eligibility L266-L272](https://github.com/openai/codex/blob/rust-v0.159.2/codex-rs/core/src/agent/control/residency.rs#L266-L272)).
+  A visible completed status does not prove eligibility: status does not
+  expose mailbox state, active-turn cleanup, or residency locks.
+- The v2 toolset exposes `interrupt_agent`, which interrupts work but does not
+  unregister the agent. Older toolsets expose `close_agent`
+  ([`spec_plan.rs`](https://github.com/openai/codex/blob/rust-v0.159.2/codex-rs/core/src/tools/spec_plan.rs)).
+  Never present `interrupt_agent` as a close or release.
+- A queue-only message to a completed v2 agent can pin it by leaving a pending
+  mailbox item
+  ([openai/codex#32353](https://github.com/openai/codex/issues/32353)). Do not
+  message completed agents to clean them up.
+- Reports of completed residents blocking replacement are nondeterministic
+  ([openai/codex#44351](https://github.com/openai/codex/issues/44351)), and
+  older open-thread quota behavior
+  ([openai/codex#22779](https://github.com/openai/codex/issues/22779)) is a
+  different mechanism. Do not conflate either with v2 residency eviction.
+
+On a pre-acceptance agent-limit rejection:
+
+1. Keep every accepted artifact and record the exact rejection as a
+   provider/dispatch outcome.
+2. Inspect the available lifecycle tools and statuses. Release only completed
+   agents whose output is already retained, and only through a close or release
+   tool the live toolset supports; never close the root or an active required
+   lane.
+3. Do not archive or delete sessions to free capacity. Archive availability
+   does not prove that it releases a v2 residency slot.
+4. Make at most one admission retry, only when the caller's approved dispatch
+   envelope allows retries and after the eligibility check above. A wait result
+   or a completed status alone does not justify another attempt.
+5. If admission still fails, use an alternate route only when the caller
+   already approved it; otherwise stop and return the partial result for a
+   concrete continuation amendment.
+
+No retry or route changes model, effort, role behavior, data authority, output
+limits, or reviewer blindness. Never rerun an accepted lane to free capacity.

package/assets/skills/oat-dispatch-subagents/references/provider-cursor.md

@@ -46,8 +46,11 @@ prohibited.
 
 Outer lifecycle implementer and reviewer dispatch uses the exact
 `providers.cursor.dispatchArgs.variant` returned by the lifecycle resolver.
-The resolver maps an opaque flat model ID and owns the bracket-form model pin
-inside the materialized definition; skills never parse, normalize, or
+The resolver maps an opaque flat model ID to the mapping's explicit frontmatter
+pin inside the materialized definition. Existing families keep their verified
+bracket-form pins; Sonnet 5.5 uses verified exact-ID pins. Each exact ID needs
+its own native evidence and approved registry entry: this is not generic
+pass-through of any CLI catalog ID. Skills never parse, normalize, or
 reconstruct either model string.
 
 1. Require a non-empty resolver-returned variant for managed dispatch.

package/assets/skills/oat-dispatch-subagents/references/record-schema.md

@@ -212,7 +212,7 @@ selection source.
 
 Before every managed, effort-pinned Claude implementer or reviewer launch,
 `oat-project-implement` runs `oat project dispatch record --event-file <file>
---json` without `--project` and requires `status: validated-only`. That input
+--json` and requires `status: validated-only`. That input
 replaces `record` with three top-level keys:
 
 - `claudeLaunch`, an object with three keys of its own:
@@ -361,10 +361,10 @@ be traded against another:
   strings; and
 - at most 16 KiB serialized per field.
 
-The whole record is additionally capped at 64 KiB, measured as the **published**
-bytes — the pretty-printed JSON plus trailing newline that is actually written
-to the journal, not compact `JSON.stringify` output. The two differ by roughly a
-tenth on a nested record, so size against the published form. Per-field
+The whole record is additionally capped at 64 KiB, measured as the **serialized**
+document — the pretty-printed JSON plus trailing newline, not compact
+`JSON.stringify` output. The two differ by roughly a tenth on a nested record,
+so size against the serialized form. Per-field
 projection limits above remain compact measurements, because they bound the
 shape of a field rather than the size of a file. A realistically rich record
 measures a few kilobytes, so these limits bind prompt bodies, transcripts, and
@@ -376,8 +376,9 @@ cannot fully account for is treated as sensitive rather than classified on a
 partial token. Store references, identifiers, and digests; never role content, message bodies,
 or credentials.
 
-Absolute filesystem paths are handled by field class, because the journal is
-committed and a home path in it is permanent:
+Absolute filesystem paths are handled by field class, because the validated
+record is printed verbatim and a caller may copy it into a committed artifact,
+where a home path is permanent:
 
 - **Identity and control fields reject them.** `caller`, `scope`, every
   selector, `selected_route`, the `guidance_*` fields, `authority`,

package/assets/skills/oat-docs-analyze/SKILL.md

@@ -3,9 +3,9 @@ name: oat-docs-analyze
 description: Run when you need to evaluate documentation structure, navigation, and coverage against the OAT docs app contract. Produces a severity-rated analysis artifact for oat-docs-apply.
 disable-model-invocation: true
 user-invocable: true
-allowed-tools: Read, Write, Bash(git:*), Glob, Grep, AskUserQuestion, Task
+allowed-tools: Read, Write, Bash(git:*), Bash(oat docs nav sync --check:*), Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: 1.5.2
+  version: 1.6.0
 ---
 
 # Docs Analysis
@@ -386,6 +386,31 @@ If a generated root index or manifest exists:
    files, and representative links for each finding.
 5. Prefer source-of-truth fixes over generated-file edits.
 
+If the app is Fumadocs (a `source.config.ts` beside `docs/`), its sidebar comes from
+`docs/**/meta.json` files that `oat docs nav sync` generates from `## Contents`:
+
+1. Flag a docs directory with an `index.md` but no `meta.json` as a missing
+   generated artifact.
+2. Flag a `meta.json` whose `pages` order or entries differ from that directory's
+   `## Contents` (immediate pages and child folders by name, `index` first in the
+   docs root and in any `root: true` folder, other targets as `[Title](url)` link
+   entries) as stale; the fix is to rerun `oat docs nav sync`.
+3. Flag a `"..."` or `"z...a"` rest entry as a hand edit; nav sync output is strict.
+4. Flag pages that no `## Contents` map lists: under strict `meta.json` they are
+   hidden from the sidebar. Recommend listing them, not adding a rest entry.
+5. During analysis, run only the read-only check, with `--check` first and
+   `--target-dir` set to the resolved docs app directory (the directory that
+   holds `source.config.ts` and `docs/`, such as `apps/oat-docs`, not its `docs/`
+   content root):
+
+   ```bash
+   oat docs nav sync --check --target-dir <docs-app-dir>
+   ```
+
+   It writes nothing, names stale `meta.json` files and unlisted pages, and exits
+   1 when either exists. The skill grants only this `--check` form; plain
+   `oat docs nav sync` writes files and is not part of analysis.
+
 If `mkdocs.yml` exists:
 
 1. Compare nav entries with the docs tree.
@@ -394,7 +419,7 @@ If `mkdocs.yml` exists:
 4. Flag directories whose `index.md` `## Contents` section appears inconsistent with nav structure.
 5. Flag docs guidance that claims structure, plugin support, or workflow rules not backed by current repo evidence.
 
-If no `mkdocs.yml` exists, record whether the repo should be migrated to an OAT docs app.
+If neither `mkdocs.yml` nor a Fumadocs app exists, record whether the repo should be migrated to an OAT docs app.
 
 ### Step 7: Severity-Rate Findings
 

package/assets/skills/oat-docs-apply/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash(git:*), Bash(gh:*), Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.3.1
+  version: 1.3.2
 ---
 
 # Docs Apply
@@ -34,7 +34,7 @@ Generate or update documentation files from a docs analysis artifact, with expli
 **ALLOWED Activities:**
 
 - Reading analysis artifacts and the current docs surface.
-- Creating or updating docs files and `mkdocs.yml` when approved.
+- Creating or updating docs files and `mkdocs.yml` when approved. Fumadocs `meta.json` files change only through `oat docs nav sync`.
 - Running `oat docs nav sync` after approved structural changes.
 - Creating branches, commits, and optional PRs.
 
@@ -203,7 +203,7 @@ For each approved recommendation:
 When approved actions involve docs app creation or nav updates:
 
 - Use `oat docs init` for scaffolding when appropriate.
-- Use `oat docs nav sync` instead of manually editing nav when the CLI helper can generate it.
+- Use `oat docs nav sync` instead of manually editing nav when the CLI helper can generate it. In Fumadocs apps it writes strict `meta.json` files and reports pages no `## Contents` map lists (`unlisted` in `--json`); resolve a reported page through an approved `## Contents` change, never by hand-editing `meta.json`.
 
 Negative rules:
 

package/assets/skills/oat-docs-authoring/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: false
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 user-invocable: true
 metadata:
-  version: 1.0.1
+  version: 1.0.2
 ---
 
 # OAT Docs Authoring

package/assets/skills/oat-docs-authoring/references/oat-fumadocs-contract.md

@@ -60,8 +60,11 @@ authored docs tree. Treat it as generated output.
 - Asset-only directories do not need `index.md` unless local guidance says so.
 - Build output, hidden tool directories, and generated artifacts are not content
   directories.
-- Optional Fumadocs metadata files, such as `meta.json`, may refine sidebar
-  presentation when local style uses them. They do not replace `## Contents`.
+- Fumadocs `meta.json` files are generated by `oat docs nav sync` from each
+  directory's `## Contents`, not hand-authored. After structural changes, rerun
+  nav sync and commit the result; it never adds a `"..."` rest entry, so list a
+  page in `## Contents` to show it in the sidebar. Keys nav sync does not own,
+  such as `icon` or `defaultOpen`, may be added by hand and are preserved.
 - Preserve local audience routers, ownership notes, and app-shell
   customizations.
 

package/assets/skills/oat-docs-bootstrap/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.2.1
+  version: 1.2.2
 ---
 
 # Docs Bootstrap
@@ -930,10 +930,11 @@ Narrate:
 
 - **The authored source** at `<appRoot>/docs/index.md`. This is the file the user edits. It has frontmatter (`title`, `description`) and a `## Contents` section listing direct children of the docs root. It is the top of a fractal: every directory has its own `index.md`, each with its own `## Contents`.
 - **The Fumadocs generated map** at `<appRoot>/index.md`. Regenerated on every `predev` / `prebuild` by the `oat docs generate-index` command. Machine-shaped: inventories Markdown files with titles and descriptions so tools have a single searchable map. **Hand-edits are silently clobbered.**
+- **The Fumadocs sidebar navigation** in `<appRoot>/docs/**/meta.json`. `oat docs nav sync` writes one per docs directory from that directory's `## Contents` order, and the files are committed. Navigation is strict: a page no `## Contents` map lists stays out of the sidebar and the command reports it, so the fix is to list the page, never to edit `meta.json` by hand.
 - **The MkDocs derived nav** in `mkdocs.yml` `nav:`. MkDocs does not use a Fumadocs-style generated app-root manifest; its generated/derived navigation boundary is the YAML nav block.
 - **How to tell them apart when opening a file.** If the file sits inside `docs/`, it's authored. If it sits at `<appRoot>/index.md` (outside `docs/`), it's the Fumadocs generated manifest — and when the CLI wrote the warning correctly, the first line is `<!-- AUTOGENERATED by \`oat docs generate-index\`... -->`.
 
-End with: "Always edit `docs/index.md` and the `## Contents` sections. In Fumadocs, never edit the root-level `index.md` — your edits will disappear next build. In MkDocs, treat `mkdocs.yml` `nav:` as derived from authored Contents unless the local workflow says otherwise."
+End with: "Always edit `docs/index.md` and the `## Contents` sections. In Fumadocs, never edit the root-level `index.md` — your edits will disappear next build — and regenerate `meta.json` with `oat docs nav sync` instead of editing it. In MkDocs, treat `mkdocs.yml` `nav:` as derived from authored Contents unless the local workflow says otherwise."
 
 #### Section C (both frameworks) — The `## Contents` contract
 
@@ -944,7 +945,7 @@ Narrate:
 - **Every directory under `docs/` has an `index.md`.** No exceptions, no `overview.md`, no README-as-index. Missing `index.md`s are the first thing `oat-docs-analyze` flags.
 - **Every `index.md` has a `## Contents` section.** The section is a plain Markdown bulleted list of links to the direct children of that directory — both subdirectory `index.md`s and leaf pages.
 - **Link targets use `.md` extensions.** Leaf pages link as `[Title](page.md)`; subdirectories link as `[Section](subdir/index.md)`. The `@open-agent-toolkit/docs-transforms` remark-links plugin normalizes these at build time for Fumadocs routing (`.md` stripped; `dir/index.md` collapsed to `dir`). `.md`-suffixed authored links render correctly **and** let agents follow each link to the target file without path inference — the best of both worlds.
-- **The `## Contents` section is the machine-readable local map.** For Fumadocs, it remains the authored navigation intent that agents maintain and compare against the generated app-root manifest. For MkDocs, `oat docs nav sync` reads it to update `mkdocs.yml` `nav:`. `oat-docs-analyze` reads the same authored source to find orphaned pages and stale generated artifacts.
+- **The `## Contents` section is the machine-readable local map.** For Fumadocs, `oat docs nav sync` reads it to write the committed `meta.json` sidebar files, and agents compare it against the generated app-root manifest. For MkDocs, `oat docs nav sync` reads it to update `mkdocs.yml` `nav:`. `oat-docs-analyze` reads the same authored source to find orphaned pages and stale generated artifacts.
 - **Anything not listed in `## Contents` is invisible to the tooling.** Adding a Markdown file is not enough — it must also appear under the parent `index.md`'s `## Contents`.
 
 Show the user their own `docs/index.md` `## Contents` as a concrete example (read the file and paste the relevant 5–15 lines). If `patchesApplied` includes an `FP-16` entry with `status: 'applied'`, mention it — the skill rewrote the scaffold's extension-less links to `.md`-suffixed form so agents can follow them. Then note: "That's the pattern. Every directory you create from now on follows the same shape — `.md`-suffixed links, bulleted list, dash-separated summary per entry."

package/assets/skills/oat-docs-bootstrap/assets/AGENTS.md.template

@@ -12,13 +12,13 @@ This file tells agents how to work inside `{{APP_DIR}}`, the documentation app f
 2. Add frontmatter with at minimum `title:` and `description:`. The title drives nav display and page `<title>`; the description drives search previews, social cards, and sibling summaries. Empty descriptions hurt all three.
 3. Update the nearest `index.md`'s `## Contents` section to include a link to the new page. Use `.md`-suffixed relative links: `[Title](page.md)` for leaf pages, `[Section](subdir/index.md)` for subdirectories. The `@open-agent-toolkit/docs-transforms` remark-links plugin normalizes these for Fumadocs routing at build time (strips `.md`, collapses `dir/index.md` → `dir`), so the suffixed form renders correctly **and** lets agents follow links to the target file without path inference. The `## Contents` section is the machine-readable local map — anything not listed there is effectively invisible to the navigation tooling.
 4. If the new page introduces a new subdirectory, create an `index.md` in that subdirectory with its own `## Contents` section. Every content directory must have an `index.md`.
-5. Regenerate the derived navigation artifact for this framework. For Fumadocs, run the generated-index command (`{{GENERATE_INDEX_CMD}}`) so the app-root `index.md` manifest reflects the current Markdown file tree. For MkDocs, run `oat docs nav sync` or the local equivalent so `mkdocs.yml` `nav:` reflects authored `## Contents`. Derived artifacts never replace the authored `## Contents`; keep authored maps current and compare generated output against them when checking freshness.
+5. Regenerate the derived navigation artifacts for this framework. For Fumadocs, run `oat docs nav sync` (from the app directory, or with `--target-dir <app-dir>`) so the committed `docs/**/meta.json` sidebar files follow authored `## Contents`, and run the generated-index command (`{{GENERATE_INDEX_CMD}}`) so the app-root `index.md` manifest reflects the current Markdown file tree. Fumadocs nav sync is strict: a page no `## Contents` map lists stays out of the sidebar and is reported, so list the new page rather than editing `meta.json`. For MkDocs, run `oat docs nav sync` or the local equivalent so `mkdocs.yml` `nav:` reflects authored `## Contents`. Derived artifacts never replace the authored `## Contents`; keep authored maps current and compare generated output against them when checking freshness.
 
 ## When you need to restructure navigation
 
 1. Make changes in the authored `## Contents` sections of each affected `index.md`. That is the authoritative local map.
-2. Do **not** hand-edit generated navigation artifacts. The Fumadocs app-root `index.md` manifest, `mkdocs.yml` `nav:` (for MkDocs), and any other derived nav file is rewritten by the local generation workflow.
-3. After editing `## Contents`, run the framework's generation command to refresh derived artifacts.
+2. Do **not** hand-edit generated navigation artifacts. The Fumadocs app-root `index.md` manifest, Fumadocs `meta.json` files, `mkdocs.yml` `nav:` (for MkDocs), and any other derived nav file is rewritten by the local generation workflow.
+3. After editing `## Contents`, run `oat docs nav sync` and the framework's generation command to refresh derived artifacts.
 4. If you're moving pages between directories, update both source and destination `index.md` `## Contents` entries in the same commit so the site isn't broken mid-way through history.
 5. If you're reparenting an entire subtree, consider whether the moved directory's own `index.md` needs a revised "scope" paragraph.
 

package/assets/skills/oat-pjm-decision/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.1.1
+  version: 1.1.2
 ---
 
 # Record Repo Decision
@@ -90,7 +90,8 @@ The CLI:
 
 - Generates a deterministic `DR-YYMMDD-slug` ID from the creation date and title.
 - Writes one record file whose filename stem equals the ID.
-- Strips template frontmatter and seeds the body from `.oat/templates/decision.md`.
+- Strips template frontmatter and seeds the body from the `decision.md` template, resolved
+  repository (`.oat/templates/`), then user (`~/.oat/templates/`), then bundled.
 - Regenerates the managed decision index.
 
 The slug is **capped at 30 characters** at the last whole-word boundary, with trailing