@open-agent-toolkit/cli 0.2.66 → 0.2.67

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.2.66"
+  "oatVersion": "0.2.67"
 }

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

@@ -93,7 +93,7 @@ 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 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.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
 - `archive.s3Uri` — base S3 archive prefix
 - `archive.s3SyncOnComplete` — upload archived projects to S3 during completion
@@ -274,6 +274,19 @@ packaged `assets/` directory next to the installed CLI. Setting a non-empty
   unset the override, never to rebuild or reinstall the CLI; a packaged-bundle
   failure keeps the rebuild/reinstall guidance. A directory that exists but
   cannot be read reports the underlying error code.
+- The published npm tarball is held to the same seven-directory shape. The
+  CLI's public-package contract names a concrete file under each of the seven
+  directories, and release validation requires each one in the build workspace
+  and again in the packed tarball. The tarball check is the stronger of the two,
+  because a path can exist in the workspace and still never reach the tarball —
+  an empty directory that `npm pack` drops, or a `files`/symlink exclusion. So a
+  published package cannot ship a bundle whose top-level shape would fail
+  `validateBundleStructure`. That is a narrower promise than the exit-2 list
+  above: release validation does not check bundle metadata beyond its presence,
+  so a malformed or version-mismatched `bundle-metadata.json` is not covered.
+  The regression evidence is the negative pack control in
+  `packages/cli/src/release/public-package-contract.test.ts`:
+  `fails release validation when a required bundle directory is empty in the tarball`.
 - Produce a matching bundle with `bash packages/cli/scripts/bundle-assets.sh`
   while `OAT_ASSETS_DIR` points at the target directory (the script already
   honors the variable as its destination).

package/assets/docs/cli-utilities/project-log.md

@@ -77,8 +77,10 @@ Two optional flags let an interrupted append be replayed safely:
 
 - `--idempotency-key <key>` — skip the append when an existing entry body
   already carries `key`, reporting `already-appended` instead of writing a
-  duplicate. The key must appear in `--body`, since that is how a replay
-  recognizes the entry it already wrote.
+  duplicate. The key must appear in `--body` as its own whitespace-delimited
+  word, since that is how a replay recognizes the entry it already wrote; a key
+  glued to varying text such as a timestamp never matches its earlier self.
+  Deduplication does not require `--commit`.
 - `--commit` — stage and commit the log after appending, retrying a bounded
   three attempts when the failure is a transient `.git/index.lock`.
 
@@ -101,6 +103,14 @@ instead.
 
 Run `oat project log append --help` for the complete entry contract.
 
+Bodies may use line feeds or CRLF line endings. A CRLF body is accepted and
+stored normalized to line feeds, and the result then carries
+`normalizedLineEndings: true`, so the bytes on disk are known to differ from the
+bytes passed. A lone carriage return, U+2028, or U+2029 anywhere in a body — including
+at its very start or end — is refused, because those are the terminators the
+log's readers do not all agree about. Structural entries take one line and
+accept no line terminator at all.
+
 ## Automatic workflow integration
 
 When project logging is enabled, OAT lifecycle surfaces append structural
@@ -149,6 +159,25 @@ oat project log check --project .oat/projects/shared/example --json
 entry counts by class, type, and scope; the last entry date; and invalid
 hand-written headings. It reads only `project-log.md`.
 
+It also reports whether the log carries a completion seal:
+
+- `sealed`: `true` once the log holds a structural entry whose producer is
+  `oat-project-complete` and whose ref is `seal`. Both halves are required — a
+  `seal` ref from another producer is an ordinary entry.
+- `seal`: `null` when unsealed, otherwise the first seal's `heading` and
+  `date`, whether it is `keyed`, and the `count` of seal entries. A `count`
+  above one is a log sealed twice before the seal append became idempotent.
+
+`status` keeps its `ok` / `absent` / `synthesis_pending` values on a sealed log;
+sealing is reported alongside the status, not as a status value. The one
+additional status is `ambiguous`: a `##` heading, or a dated `###` entry
+heading, starts a line after a lone carriage return, U+2028, or U+2029 rather
+than a line feed, so the log's structure can be read two ways; or a seal is
+physically present outside the parseable `## Entries` region. `check` then
+exits 1 and reports an `ambiguity` reason instead of a clean verdict, every
+writing command (`append`, `synthesize`, `rollup`) refuses the same file, and
+the lifecycle skills stop rather than treat the log as empty.
+
 Use `--require-synthesis` to exit with status 1 while synthesis is pending:
 
 ```bash
@@ -156,7 +185,8 @@ oat project log check --require-synthesis
 ```
 
 Without that flag, normal `absent`, `ok`, and `synthesis_pending` results exit
-successfully so lifecycle skills can decide whether to warn or enforce.
+successfully so lifecycle skills can decide whether to warn or enforce;
+`ambiguous` always exits 1.
 
 ## Complete the synthesis
 
@@ -201,15 +231,44 @@ deduplicate by date and area. The command is idempotent.
 
 The structured result contains:
 
-- `status`: `ok` or `failed`
+- `status`: `ok`, `failed`, or `ambiguous`
 - `summarySection`: `written` or `updated`
 - `ledgerOutcome`: `appended`, `deduplicated`, `skipped_permitted`, or `failed`
 - `entriesRolledUp`: number of log entries written to the summary section
 
+An `ambiguous` result carries only `status` and an `ambiguity` reason, and exits
+1: the log's structure has two readings, so no count would mean anything and
+neither `summary.md` nor the ledger is written. The other fields are absent
+rather than zeroed, because `entriesRolledUp: 0` for an unreadable log is
+indistinguishable from the same result for an empty one.
+
 `skipped_permitted` means the default repository reference layer is absent and
 no ledger path was explicitly configured; `status` remains `ok`. An explicitly
 configured ledger write failure returns `status: "failed"`. Completion must not
 seal or archive a project with entries until roll-up reports `status: "ok"`.
 
+## The completion seal
+
+The seal is the last entry a project log may ever receive, and `append`
+enforces that rather than leaving it to convention:
+
+- Replaying the seal reports `already-appended` and leaves exactly one seal
+  entry. This holds for a seal carrying the completion skill's
+  `oat-seal:<project>` key and for an unkeyed seal written before that
+  convention, which is recognized by its heading instead.
+- Every append carrying **new** content is refused with `status: "sealed"` and a
+  non-zero exit, naming the seal that closed the log.
+- A replay that `--idempotency-key` recognizes as its own earlier entry is the
+  one exception: it reports `already-appended` and exits 0 even on a sealed log.
+  Nothing is appended — the entry it finds necessarily predates the seal — so
+  the seal stays the final entry. This is what keeps a gate
+  partial-finalization receipt replayable after the project is completed. The
+  key matches a whole word in an existing entry body, so an unrelated append
+  whose key happens to occur in some earlier entry is reported the same way
+  and likewise writes nothing.
+
+A resumed completion therefore reads `sealed` from `check` and skips the
+roll-up and the seal instead of duplicating them.
+
 `rollup` requires an existing `summary.md`; summary authoring remains the
 responsibility of the project summary workflow.

package/assets/docs/contributing/code.md

@@ -56,8 +56,8 @@ pnpm build:docs               # builds docs site and its dependencies
 ```
 
 `pnpm test` is composite: it runs the workspace vitest suites, then
-`test:smoke` (`tools/smoke`), `test:skills` (`.agents/skills/*/tests`), and
-the named-file `test:release` set. Steps 5 and 6 are the version-lockstep
+`test:smoke` (`tools/smoke`), `test:skills` (`.agents/skills/*/tests`), the
+named-file `test:release` set, and last `test:scripts` (`scripts/worktree`). Steps 5 and 6 are the version-lockstep
 gates; they are in the local list because they previously ran only in CI and
 version-bump drift twice reached review with no local gate to surface it.
 
@@ -73,8 +73,12 @@ 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` — run both whenever a change
-touches `tools/smoke` or `.agents/skills`, since nothing else covers them.
+CI runs neither `pnpm lint` nor `pnpm format`. `pnpm check` now 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.
 For narrower changes, use package-specific checks when possible, but do not
 merge without passing the relevant workspace gates.
 

package/assets/docs/contributing/skills.md

@@ -203,15 +203,19 @@ resolution. `resolveSkillVersion` in
 `packages/cli/src/commands/shared/frontmatter.ts` owns that order, so the
 runtime helper and the validators cannot disagree.
 
-The top-level `version` field remains supported as a deprecated alias. Every
-bundled skill now declares `metadata.version` and carries no top-level
-`version`, so `pnpm oat:validate-skills` reports no alias warnings on the
-bundled tree. The alias is retained for third-party skills installed from
-packs, which may still carry it; it retires on the schedule recorded in
-`DR-260908-bundled-skills-declare` — the warning becomes an error in the first
-release after 0.2.65 that changes the validator, and the resolver's top-level
-read is removed one release after that error has produced no findings on the
-bundled tree.
+The top-level `version` field remains supported as a deprecated alias, and a
+skill that declares it is now reported as an **error**. Every bundled skill
+declares `metadata.version` and carries no top-level `version`, so
+`pnpm oat:validate-skills` reports no alias findings on the bundled tree. The
+alias is still read for third-party skills installed from packs, which may
+carry it; it retires on the schedule recorded in
+`DR-260908-bundled-skills-declare`. Step 1 of that schedule — promoting the
+alias finding from a warning to an error — ships in the first release after
+0.2.65 that changes the validator. Step 2 removes the resolver's top-level read
+one release after that error has produced no findings on the bundled tree; it
+is tracked by `BL-260908-remove-the-top-level-skill` and must account for the
+canonical agent roles, which the bump gate now enforces while they still
+declare the top-level field.
 
 A skill that carries both fields with different values is a conflict. The
 resolver reports the `metadata.version` value together with the conflict, and
@@ -220,7 +224,7 @@ than silently picking one, and canonical role resolution treats the identity as
 invalid. The runtime version readers still return the `metadata.version` value,
 so an installed-versus-bundled comparison keeps working while the conflict is
 being fixed. Carrying both with the _same_ value resolves without a conflict and
-without an alias warning, because `metadata.version` wins. A bundled skill must
+without an alias finding, because `metadata.version` wins. A bundled skill must
 still carry `metadata.version` alone: the corpus sweep in
 `packages/cli/src/validation/skills.test.ts` fails on any column-0 `version:`
 line under `.agents/skills`, which is the only check that catches the
@@ -228,16 +232,24 @@ same-value case.
 
 ### The version is gated
 
-Changing any canonical skill's `SKILL.md` requires bumping its frontmatter
-version in the same PR — one bump per changed skill in the final PR diff,
-even if the skill was edited multiple times on the branch. The gate reads the
-resolved version, so it enforces the bump whether the skill declares
+Changing any bundled file of a canonical skill — anything under
+`.agents/skills/<name>/` except `tests/`, because `tests/` is the one subtree
+the bundle strips — requires bumping that skill's `metadata.version` in the
+same PR, one bump per changed skill in the final PR diff, even if the skill was
+edited multiple times on the branch. A change to a skill's `scripts/` or
+`references/` therefore needs the bump just as an edit to `SKILL.md` does: both
+ship to every `oat tools install` consumer. Changing a canonical agent role
+under `.agents/agents/*.md` requires bumping that file's top-level `version:`;
+agent roles deliberately keep the top-level field, so the gate accepts either
+declaration shape and never demands `metadata.version` of them. The gate reads
+the resolved version, so it enforces the bump whether the file declares
 `metadata.version` or the top-level alias. The rule is enforced by
 `pnpm run check:skill-bumps`, which runs locally (root `AGENTS.md` Definition
 of Done) and in CI; a changed skill whose version matches `origin/main` fails
-the gate. The deprecation warning above is deliberately not part of that gate:
-`check:skill-bumps` fails on any finding it receives, so an alias warning
-routed through it would fail every changed skill that still carried one.
+the gate. The alias finding above is deliberately not part of that gate:
+`check:skill-bumps` fails on any finding it receives regardless of severity, so
+an alias finding routed through it would fail every changed skill that still
+carried one.
 
 ## Practical Authoring Flow
 

package/assets/docs/docs-tooling/commands.md

@@ -132,11 +132,13 @@ Key behavior:
 - treats explicitly supplied `--docs-dir` / `--output` paths as overrides resolved from the current directory
 - fails with exit code `2` before generating or writing anything when an omitted path has no non-empty `documentation.root` to resolve against, or when the configured root is not a directory
 - refuses unsafe output targets with exit code `1` before generation, for derived and explicit paths alike, comparing symlink-resolved paths: inside the docs directory it indexes, equal to `documentation.config`, or ending in `.yml` / `.yaml` in any case. A derived output whose existing file lacks the `AUTOGENERATED` header is refused too; naming that path with `--output` overwrites it explicitly. A refused target is an actionable flag error (`1`); unusable path configuration is a separate condition and exits `2`, so scripts can branch on the two
+- refuses a symlink chain that exceeds its own 32-hop cap, naming the path you supplied or the CLI derived rather than an intermediate link, and addressing the flag that owns it: an unusable **output** chain names `--output` and exits `1`; an unusable **docs directory** chain names `--docs-dir` and, when the directory was derived from `documentation.root` rather than passed explicitly, also names the `oat config set documentation.root <path>` repair and exits `2` as unusable path configuration. That cap governs the dangling links the command walks itself; a chain the operating system refuses first surfaces as its own `ELOOP` error with exit `1`, which is what a too-deep chain reports on a platform whose own limit is 32 or lower
 - writes configuration only for the Fumadocs manifest transition — recording the manifest it just wrote inside `documentation.root` in `documentation.index`, when `documentation.tooling` is `fumadocs` or the config declares neither `tooling` nor `config`. MkDocs configurations are never written, and `documentation.root` and `documentation.config` are never modified
 - prepends an `AUTOGENERATED` warning comment to the output and rewrites the file on every run; do not hand-edit the generated `index.md`
 - should be freshness-checked against authored `docs/**/index.md` `## Contents` maps before treating it as navigation evidence
 - sorting: `index.md` first, then directories before files, then lexical
-- reports the derived docs directory in human output and as `docsDir` / `docsDirSource` under `--json`
+- reports the derived docs directory in human output and as `docsDir` / `docsDirSource` under `--json`, alongside `excludes` — the effective exclusion list, `documentation.excludes` merged with the `--exclude` flags exactly as it was handed to the generator
+- says where to look when a manifest is empty rather than reporting a bare `0 entries`: which exclusion patterns were active, or that the docs directory held no indexable pages. The wording is observational — the command reports indexed entries, not pattern matches, so it names the exclusions without asserting they are the cause. An empty manifest is a report, not a failure — the file is still written, so a stale index is never left behind, and the command still exits `0`
 - omits pages matching the exclusion list. Nothing is excluded by default; once listed, non-page Markdown such as `CLAUDE.md` or `AGENTS.md` stops reaching the manifest. Patterns come from `documentation.excludes` in `.oat/config.json` and from repeated `--exclude` flags, and the flags **extend** the configured list rather than replacing it. A directory left empty by exclusion emits no heading, and an empty list produces byte-identical output to no exclusions at all
 
 Supported flags:

package/assets/docs/provider-sync/manifest-and-drift.md

@@ -95,8 +95,8 @@ the manifest.
 
 - `missing-additive` — active, supported, no manifest entry, nothing at the expected path: the only true projection gap
 - `removed` — a manifest entry exists but the provider file is gone
-- `modified` — a manifest entry exists and the view no longer agrees with what the last sync recorded, or its version has fallen behind canonical. A `copy` view also reaches this class through the known limitation below, where the difference may be nothing but the generated banner
-- `in-sync` — a symlinked, collection-aliased, or natively read view _is_ the canonical file; a `copy` view matches the content recorded at its last sync
+- `modified` — a manifest entry exists and the view no longer agrees with what the last sync recorded, or its version has fallen behind canonical
+- `in-sync` — a symlinked, collection-aliased, or natively read view _is_ the canonical file; a `copy` view matches the content recorded at its last sync. A managed directory copy is compared with its OAT-managed banner and its `.oat-generated` sentinel excluded, so a freshly synced copy reads `in_sync` rather than drifted (owned by `skill-view-convergence.integration.test.ts`, "converges a copy-strategy skill directory")
 - `untracked` — something exists at the expected path that no manifest entry tracks; stray detection skips provider entries whose name matches a canonical entry, so `oat status` does not report it as a stray and reports the untracked projection as `missing` instead
 - `unverified` — the view's state is unknown: either a manifest entry arrived with no drift observation, or reading that one view failed and the row carries the redacted reason
 - `inactive`, `unsupported`, `excluded` — no projection is expected in this scope, so none of them is reported as missing
@@ -173,22 +173,6 @@ declared values and says the comparison was skipped, so the ambiguity is
 visible rather than silently resolved. When the resolver's answer happens to
 agree with canonical, nothing is withheld and the detail says so instead.
 
-### Known limitation: copy-strategy skill views
-
-A `copy` skill view is reported `modified` immediately after a successful sync,
-and stays that way. The engine writes an OAT-managed banner into the copied
-`SKILL.md` and an `.oat-generated` sentinel beside it, and neither is accounted
-for in the manifest hash, so `oat status` reports `drifted:modified` and every
-later `oat sync --dry-run` plans another `update_copy`. Because no sync clears
-that state, `oat tools info` prints no repair line when a `modified` copy's
-version still matches canonical.
-
-That suppression is a conservative heuristic rather than a proof: equal versions
-do not establish equal bodies, so an edit to the canonical source or to the copy
-that kept the version reaches the same branch, and a sync _would_ repair that
-one. The class detail says so and names the concrete scope command to run if you
-know either side was edited. Tracked as `BL-260908-make-copy-strategy-skill`.
-
 ## Stray adoption
 
 `oat init` and `oat status` can offer adoption of unmanaged provider entries into canonical `.agents`.

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

@@ -113,6 +113,15 @@ and retro is not added to the lite closeout sequence.
 On completion, OAT treats archive handling as an explicit closeout choice:
 
 - When archiving is selected, the local archive is written to `.oat/projects/archived/<project>/`.
+- Every completion that will actually archive — any durable (`shared` or
+  `synced`) project with archive selected — keeps the `activeProject` pointer
+  until the archive returns a validated receipt, and only then clears it.
+  `local` projects are never durable and never archive, so they clear the
+  pointer immediately, as does any completion that declines archive. An archive
+  failure therefore leaves the pointer intact and the completion directly
+  resumable. See
+  [Picking Up a Project](picking-up-projects.md#archive-contents) for the
+  post-archive resume and its manual recovery path.
 - When archiving is disabled or declined, durable projects remain at their
   active path. Synced completion still finalizes and pushes the project ref,
   commits the discovery record as `complete`, retains the checkout and ref, and
@@ -183,6 +192,14 @@ each finding as a `deferred advisory` warning and continues, a project with no l
 final completion summary, and a resumed completion whose log already
 carries a seal runs report-only and appends nothing.
 
+A resume detects that seal from `oat project log check`, which reports a
+`sealed` field, rather than by re-reading the log. The invariant is enforced in
+the CLI: replaying the seal reports `already-appended` and leaves exactly one
+seal entry; a replay recognized by its own idempotency key reports
+`already-appended` even on a sealed log (nothing is appended), and every
+append carrying new content is refused with `status: "sealed"` and a non-zero
+exit.
+
 Repositories that never adopted PJM skip the sweep with a one-line note. A
 missing planning surface degrades the sweep, never the closeout.
 

package/assets/docs/workflows/projects/picking-up-projects.md

@@ -99,6 +99,24 @@ If closeout is interrupted after terminal archive identity exists, rerun
 completion so it can resume from the completed ref and archive metadata. Do not
 use `pull` or `open` to recreate an active record or checkout.
 
+For a `shared` project, archive moves the project into
+`.oat/projects/archived/<project>/` and removes the source directory, while
+completion keeps the `activeProject` pointer until the receipt validates.
+Rerunning completion after an interruption between the archive and that clear
+recognizes exactly this state — the pointer names a source directory that no
+longer exists and the archive carries `oat_lifecycle: complete` plus the
+`Lifecycle complete; archived locally` phase marker — so it validates the
+discovered archive and clears the pointer without archiving a second time or
+sealing the project log again. An interruption before the archive leaves the
+source directory in place, so completion simply reruns from the start and skips
+the work it already finished.
+
+If the archive cannot be discovered — the source directory is gone and either
+no archived project or several match the name — completion stops and leaves the
+pointer untouched. Recover manually: locate the archive directory under
+`.oat/projects/archived/`, confirm `oat_lifecycle: complete` in its `state.md`,
+then clear the pointer with `oat config set activeProject ""`.
+
 ## Related
 
 - [Reviewing OAT PRs](reviewing-oat-prs.md)

package/assets/docs/workflows/skills/repo-improve.md

@@ -72,9 +72,13 @@ Failure to publish a backlog item or issue does not invalidate a successfully wr
 
 Full repository audits use bounded read-only reconnaissance while the root
 agent retains classification, vetting, prioritization, cross-lane synthesis,
-and plan writing. Before launch, the caller loads the durable task classes and
-model-selection principles from `subagent-orchestration` plus exactly one
-active-provider selection reference.
+and plan writing. Plan writes never move below the caller's model class — a
+parallelized author runs on the caller's model and every plan is
+caller-reviewed before publication or wave composition; the
+`keeps external-plan writes on the caller's model class` case in
+`skills-bundled-docs-contract.test.ts` is the backstop. Before launch, the
+caller loads the durable task classes and model-selection principles from
+`subagent-orchestration` plus exactly one active-provider selection reference.
 
 The internal `oat-dispatch-subagents` skill then owns capability checks, live
 catalog intersection, exact route selection, launch acceptance, recovery, and

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.66",
-  "docs-config": "0.2.66",
-  "docs-theme": "0.2.66",
-  "docs-transforms": "0.2.66"
+  "cli": "0.2.67",
+  "docs-config": "0.2.67",
+  "docs-theme": "0.2.67",
+  "docs-transforms": "0.2.67"
 }

package/assets/skills/create-agnostic-skill/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 user-invocable: true
 metadata:
-  version: 1.4.3
+  version: 1.5.0
 ---
 
 # Create Skill
@@ -69,7 +69,7 @@ If not provided in arguments, ask for:
 **The context window is a shared resource.** Skills share context with everything else the agent needs. Structure information in three levels:
 
 1. **Metadata** (~100 words): Name + description in frontmatter, always loaded
-2. **SKILL.md body** (<5k words): Loads when skill triggers
+2. **SKILL.md body** (~5,000 tokens): Loads when skill triggers
 3. **Bundled resources**: Files in `references/`, `scripts/`, `assets/` loaded as-needed
 
 **Writing principles:**
@@ -172,11 +172,12 @@ Natural language request that triggers this skill
 **Frontmatter notes:**
 
 - `argument-hint`, `allowed-tools`, `user-invocable`, `context`, `hooks` are Claude Code specific
-- Other agents ignore unknown frontmatter fields, so it's safe to include Claude-specific fields everywhere
+- `allowed-tools`: write the value as a **comma-separated** list. The spec's own example is space-delimited and OAT never parses the separator — `validateOatSkills` in `packages/cli/src/validation/skills.ts` only checks that the key is present, and `getToolDetail` in `packages/cli/src/commands/tools/info/index.ts` reads the raw scalar — so this is OAT's authoring convention rather than a runtime contract. Backstop: `it('declares allowed-tools as a comma-separated list in every canonical skill')` in `packages/cli/src/validation/skills.test.ts`
+- The spec defines a fixed field set, and providers differ in which extension fields they read. An unread field is inert rather than guaranteed harmless, so check the dated compatibility section of `references/docs/skills-guide.md` for the per-provider picture before depending on one
 - `name`: max 64 chars for cross-provider portability (Codex allows 100, but 64 is the spec limit)
 - `metadata.version`: include valid semver and start new skills at `1.0.0`. The Agent Skills specification puts the version under `metadata`, and OAT resolves `metadata.version` first and the top-level `version` second — `resolveSkillVersion` in `packages/cli/src/commands/shared/frontmatter.ts` owns that order, backstopped by `packages/cli/src/commands/shared/frontmatter.test.ts`
-- `version` (top-level): the deprecated alias, still read when `metadata.version` is absent. Do not set both to different values: OAT reports the conflict, skill validation fails on it, and canonical role identity rejects it
-- `description`: **single line, ≤ 500 chars** (Codex enforces single-line ≤ 500 chars; spec allows 1024)
+- `version` (top-level): the deprecated alias, still read when `metadata.version` is absent — but a skill whose only version is that alias no longer validates. `validateOatSkills` in `packages/cli/src/validation/skills.ts` reports it as `skill-version-alias` at `severity: 'error'`, so `pnpm oat:validate-skills` fails the skill outright; the pass runs over every skill directory, not just `oat-*`, so an agnostic skill is covered too. Backstop: `it('reports exactly once for a non-oat-* alias-only skill')` in `packages/cli/src/validation/skills.test.ts`. Setting both to different values is the separate `skill-version-conflict` error: OAT reports the conflict, skill validation fails on it, and canonical role identity rejects it. Declare `metadata.version` and leave the alias out
+- `description`: **single line, ≤ 500 chars**. This is OAT's house rule, not a provider requirement: `validateOatSkills` in `packages/cli/src/validation/skills.ts` enforces it only for skills whose directory name starts with `oat-`. For every other skill it is an unenforced authoring convention this repository follows for portability. Backstops in `packages/cli/src/validation/skills.test.ts`: `it('reports description longer than 500 characters')` and `it('does not report a description longer than 500 characters for a non-oat-* skill')`. The spec allows 1024
 - Bump `metadata.version` on future edits: patch for fixes/clarifications, minor for backward-compatible behavior additions, major for breaking workflow/interface changes
 
 **Writing the `description` field:**
@@ -194,7 +195,7 @@ Examples:
 - Bad: "Reviews code by checking spec compliance, then code quality, then creates PR"
 - Good: "Use when reviewing code or checking PRs. Systematic quality and security analysis."
 
-Present the plan and wait for user approval before creating files.
+Present the plan and ask once for approval, stating the approval scope: it covers the skill directory, its `SKILL.md`, and the supporting files this plan named, for the rest of this run. Re-ask only if the file set changes. If the user declines, stop before creating any file and report the plan instead.
 
 ### Step 4: Create Skill File
 
@@ -231,18 +232,21 @@ Skills can include supporting files in subdirectories:
 
 ### Step 5: Sync and Verify
 
-After creating the skill, run OAT sync to update provider views:
+If the repository uses OAT sync, refresh the provider views for this repository only:
 
 ```bash
-oat sync
+oat sync --scope project
 ```
 
+A bare `oat sync` defaults to `--scope all`, which also rewrites the invoking user's home-scope provider
+directories. `withScopeOption` in `packages/cli/src/commands/shared/scope-option.ts` owns that default, and `it('sync --help matches snapshot')` in `packages/cli/src/commands/help-snapshots.test.ts` is its backstop.
+
 Verify:
 
 - File created at `.agents/skills/{skill-name}/SKILL.md`
 - Frontmatter syntax is valid
 - Frontmatter includes valid semver `metadata.version:` (new skills start at `1.0.0`)
-- Skill appears in `AGENTS.md`
+- Skill resolves through the provider views after a scoped sync — check with `oat tools info {skill-name}` or the provider's own skill list
 - Examples include both invocation styles
 - If the skill name starts with `oat-`, run `pnpm oat:validate-skills` and fix any findings
 
@@ -268,7 +272,7 @@ Provide:
 - **Context window is a public good**—keep skills lean, challenge every paragraph
 - Description is the trigger—include "when to use" in frontmatter, not just body
 - Bump `metadata.version` for edits: patch = fixes/clarifications, minor = backward-compatible additions, major = breaking changes
-- Keep SKILL.md **under 500 lines / ~5,000 tokens** (spec constraint)
+- Keep SKILL.md **under 500 lines / ~5,000 tokens** — OAT's authoring budget, not a specification limit; see the dated provider-compatibility section of `references/docs/skills-guide.md` for what each provider documents
 - Use clear, task-based headings
 - Include working examples for both invocation styles
 - Document all arguments with defaults
@@ -289,7 +293,7 @@ Skills that need user decisions (parameter choices, confirmations, disambiguatio
 
 Do **not** hard-code a specific Codex question tool name in skill prose unless the runtime contract is guaranteed. Prefer capability-based wording ("structured user-input tooling when available") so the skill remains portable across Codex hosts.
 
-**Claude Code enhancement:** Add `AskUserQuestion` to `allowed-tools` in frontmatter. Claude Code renders these as structured UI prompts with selectable options, headers, and multi-select support. Other providers ignore the field and handle the same instructions as conversational questions.
+**Claude Code enhancement:** Add `AskUserQuestion` to `allowed-tools` in frontmatter. Claude Code renders these as structured UI prompts with selectable options, headers, and multi-select support. Providers that do not read `allowed-tools` handle the same instructions as conversational questions; treat the field as having no effect there rather than as universally supported, and check the dated compatibility matrix in `references/docs/skills-guide.md`.
 
 **When to include interactive input:**
 
@@ -374,32 +378,11 @@ For multi-step skills, print brief progress updates so the user knows what's hap
 
 ### Frontmatter Reference
 
-Legend: ✅ supported | ⚠️ provider-specific | 💤 ignored | ❓ unknown
-
-| Field                      | Spec            | Claude Code | Cursor | Codex CLI   | Gemini CLI |
-| -------------------------- | --------------- | ----------- | ------ | ----------- | ---------- |
-| `name`                     | ✅ required     | ✅          | ✅     | ✅ required | ✅         |
-| `description`              | ✅ required     | ✅          | ✅     | ✅ required | ✅         |
-| `license`                  | ✅ optional     | ❓          | ✅     | 💤          | ❓         |
-| `compatibility`            | ✅ optional     | ❓          | ✅     | 💤          | ❓         |
-| `metadata`                 | ✅ optional     | ❓          | ✅     | 💤          | ❓         |
-| `allowed-tools`            | ⚠️ experimental | ✅          | ❓     | 💤          | ❓         |
-| `disable-model-invocation` | ❌              | ✅          | ✅     | 💤          | ❓         |
-| `user-invocable`           | ❌              | ✅          | ❓     | 💤          | ❓         |
-| `argument-hint`            | ❌              | ✅          | ❓     | 💤          | ❓         |
-| `context` / `agent`        | ❌              | ✅          | ❌     | 💤          | ❓         |
-| `hooks`                    | ❌              | ✅          | ❌     | 💤          | ❓         |
-
-**Key takeaway:** `name` + `description` are the only truly portable interface. Codex ignores unknown keys (safe to include Claude fields), so layer tool-specific fields on top of a portable baseline. For the full matrix, see `references/docs/skills-guide.md` (bundled with this skill).
+**Key takeaway:** `name` + `description` are the only truly portable interface. Layer tool-specific fields on top of that baseline, but treat an unread field as inert rather than guaranteed harmless — providers differ in which extension fields they read, and not every provider documents what it does with the rest. The single canonical, dated compatibility matrix lives in `references/docs/skills-guide.md` (bundled with this skill); consult it rather than a copy.
 
 ### Detail Level
 
-| Skill Type            | Detail Level | Examples                       |
-| --------------------- | ------------ | ------------------------------ |
-| Complex workflows     | Detailed     | docs-new, docs-review          |
-| Simple command-like   | Concise      | update-doc-refs, create-ticket |
-| Reference/standards   | Detailed     | repo-documentation             |
-| Helper (auto-invoked) | Moderate     | read-relevant-docs             |
+For the detail level each skill type warrants, see `references/skill-template.md`.
 
 ## Examples
 
@@ -428,7 +411,7 @@ I need a skill for running database migrations
 - [Agent Skills Open Standard](https://agentskills.io) — the spec
 - [Claude Code Skills](https://code.claude.com/docs/en/skills) — Claude-specific features
 - [Cursor Skills](https://cursor.com/docs/context/skills) — Cursor-specific features
-- [Codex CLI Skills](https://developers.openai.com/codex/skills) — Codex-specific features
+- [Codex CLI Skills](https://learn.chatgpt.com/docs/build-skills) — Codex-specific features
 - [Gemini CLI Skills](https://geminicli.com/docs/cli/skills/) — Gemini-specific features
 - [npx skills CLI](https://github.com/vercel-labs/skills) — installing remote/community skills
 - [Skills best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) — authoring guidance
@@ -439,7 +422,7 @@ I need a skill for running database migrations
 
 **Skill not appearing in menu:**
 
-- Run `oat sync` to regenerate provider views
+- Run `oat sync --scope project` to regenerate this repository's provider views
 - Verify YAML frontmatter syntax is valid
 - Check that skill name matches directory name
 - Ensure `user-invocable` is not set to `false` (Claude Code)
@@ -461,7 +444,6 @@ I need a skill for running database migrations
 Successful skill creation:
 
 - ✅ Skill created at `.agents/skills/{name}/SKILL.md`
-- ✅ `oat sync` run successfully
 - ✅ For `oat-*` skills, `pnpm oat:validate-skills` passes
 - ✅ Frontmatter valid
 - ✅ Workflow uses "Step" naming