@open-agent-toolkit/cli 0.2.65 → 0.2.67

package/assets/docs/reference/file-locations.md

@@ -82,10 +82,32 @@ Config ownership note:
 - Runtime sync state: `.oat/sync/`
 - Repo knowledge: `.oat/repo/knowledge/`
 - Active PJM operational layer: `.oat/repo/pjm/` (`current-state.md`, `roadmap.md`, `backlog/`)
+- Shared backlog remote-binding metadata: `.oat/repo/pjm/remote/bindings/`
 - Durable repo references: `.oat/repo/reference/` (file-per-record decisions under `decisions/`)
 - Repo reviews: `.oat/repo/reviews/`
 - Repo archive: `.oat/repo/archive/`
 
+### Remote PJM binding and operation state
+
+Remote binding metadata follows the local owner:
+
+- shared backlog bindings: `.oat/repo/pjm/remote/bindings/`
+- shared or synced project bindings: `<project>/remote/bindings/`
+- local project bindings: the local operational store's `metadata/bindings/`
+
+Operational snapshots, journals, batches, and receipts default to
+`<git-common-dir>/oat/pjm-remote/<repository-fingerprint>/`. Git linked
+worktrees resolve the same common directory and therefore share this local
+state. A separate clone has a different Git directory and begins without the
+first clone's operational snapshot; run `oat pjm remote refresh` through a live
+host capability before relying on remote freshness.
+
+When shared state is explicitly previewed and approved,
+`.oat/repo/pjm/remote/state/` or `<project>/remote/state/` replaces the local
+operational root. Shared state can contain remote planning content and is not
+available for local projects. See
+[Remote Project Management](../cli-utilities/remote-project-management.md).
+
 ## Project artifact trees
 
 - Shared: `.oat/projects/shared/<project>/`

package/assets/docs/reference/oat-directory-structure.md

@@ -38,6 +38,9 @@ Project scope is used for project workflows and repo-local sync state. User scop
   repo/
     knowledge/
     pjm/
+      remote/
+        bindings/
+        state/
     reference/
     reviews/
     archive/
@@ -45,16 +48,16 @@ Project scope is used for project workflows and repo-local sync state. User scop
 
 ## Top-level entries
 
-| Path                     | Purpose                                             | Notes                                                                                                   |
-| ------------------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| `.oat/config.json`       | Shared repo runtime config for non-sync settings    | Includes `worktrees.root`, `projects.root`, `git.defaultBranch`, `archive.*`, and `documentation.*`     |
-| `.oat/config.local.json` | Local per-developer runtime state                   | Gitignored; includes `activeProject`, `lastPausedProject`, `activeIdea`                                 |
-| `.oat/state.md`          | Generated repo state dashboard                      | Gitignored; rebuilt with `oat state refresh` from config, project artifacts, and knowledge metadata     |
-| `.oat/projects/`         | OAT project artifacts                               | `shared`, `synced`, `local`, and lifecycle `archived` locations                                         |
-| `.oat/ideas/`            | Project-level ideas store                           | Often gitignored                                                                                        |
-| `.oat/sync/`             | Interop sync state/config                           | See details below                                                                                       |
-| `.oat/templates/`        | Artifact templates used by OAT skills               | Source for scaffolding. Includes `docs-app-fuma/` (Fumadocs) and `docs-app-mkdocs/` (MkDocs) templates. |
-| `.oat/repo/`             | Repo-level PJM/knowledge/reference/review artifacts | Active PJM state under `pjm/`; durable references (including decisions) under `reference/`              |
+| Path                     | Purpose                                             | Notes                                                                                                               |
+| ------------------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `.oat/config.json`       | Shared repo runtime config for non-sync settings    | Includes `worktrees.root`, `projects.root`, `git.defaultBranch`, `archive.*`, `documentation.*`, and `pjm.remote.*` |
+| `.oat/config.local.json` | Local per-developer runtime state                   | Gitignored; includes `activeProject`, `lastPausedProject`, `activeIdea`                                             |
+| `.oat/state.md`          | Generated repo state dashboard                      | Gitignored; rebuilt with `oat state refresh` from config, project artifacts, and knowledge metadata                 |
+| `.oat/projects/`         | OAT project artifacts                               | `shared`, `synced`, `local`, and lifecycle `archived` locations                                                     |
+| `.oat/ideas/`            | Project-level ideas store                           | Often gitignored                                                                                                    |
+| `.oat/sync/`             | Interop sync state/config                           | See details below                                                                                                   |
+| `.oat/templates/`        | Artifact templates used by OAT skills               | Source for scaffolding. Includes `docs-app-fuma/` (Fumadocs) and `docs-app-mkdocs/` (MkDocs) templates.             |
+| `.oat/repo/`             | Repo-level PJM/knowledge/reference/review artifacts | Active PJM state under `pjm/`; durable references (including decisions) under `reference/`                          |
 
 ## `.oat/sync/` details
 
@@ -283,8 +286,17 @@ Typical contents:
   reviews/
   pr/
   references/
+  remote/
+    bindings/
+    state/
 ```
 
+The `remote/bindings/` directory is portable metadata for shared and synced
+projects. `remote/state/` exists only after approved shared-storage promotion.
+With the default local storage policy, operational state instead lives under
+`<git-common-dir>/oat/pjm-remote/<repository-fingerprint>/`, outside `.oat/`.
+Linked worktrees share that location; independent clones do not.
+
 ### Core artifact roles
 
 | File                    | Purpose                                                                                                                                                                                                                        |
@@ -310,13 +322,14 @@ Not all workflow modes require every artifact:
 
 ## `.oat/repo/` structure
 
-| Path                   | Purpose                                                                                  |
-| ---------------------- | ---------------------------------------------------------------------------------------- |
-| `.oat/repo/knowledge/` | Generated codebase knowledge indexes                                                     |
-| `.oat/repo/pjm/`       | Active operational PJM layer (`current-state.md`, `roadmap.md`, and `backlog/`)          |
-| `.oat/repo/reference/` | Durable append-mostly references, including file-per-record decisions under `decisions/` |
-| `.oat/repo/reviews/`   | Repo-scoped review artifacts (ad-hoc/non-project)                                        |
-| `.oat/repo/archive/`   | Archived repo-level artifacts                                                            |
+| Path                    | Purpose                                                                                  |
+| ----------------------- | ---------------------------------------------------------------------------------------- |
+| `.oat/repo/knowledge/`  | Generated codebase knowledge indexes                                                     |
+| `.oat/repo/pjm/`        | Active operational PJM layer (`current-state.md`, `roadmap.md`, and `backlog/`)          |
+| `.oat/repo/pjm/remote/` | Portable backlog binding metadata and, only when approved, shared operational state      |
+| `.oat/repo/reference/`  | Durable append-mostly references, including file-per-record decisions under `decisions/` |
+| `.oat/repo/reviews/`    | Repo-scoped review artifacts (ad-hoc/non-project)                                        |
+| `.oat/repo/archive/`    | Archived repo-level artifacts                                                            |
 
 Canonical project-management repo-reference surface splits the active
 operational layer (`pjm/`) from durable references (`reference/`):

package/assets/docs/reference/troubleshooting.md

@@ -264,6 +264,50 @@ managed default itself:
 oat tools update --pack project-management --scope user
 ```
 
+## A remote PJM command is pending, uncertain, or blocked
+
+Read the JSON envelope before retrying:
+
+```bash
+oat pjm remote doctor --json
+```
+
+Before the first provider-contacting command, discover a matching live
+connector. If no capable connector exists, inspect an already configured
+provider CLI's live help. Construct only bounded provider-neutral capability
+evidence and supply it through `--capability-evidence-stdin`.
+
+- `pending` with `externalAction` means OAT durably prepared one exact semantic
+  host action. Confirm the previously selected capability remains granted,
+  execute that exact action at most once, then submit one bounded observation
+  through `oat pjm remote operation continue`.
+- `uncertain` means an effect may have occurred. Follow the envelope's recovery
+  instructions; never repeat a create or update blindly.
+- `needs-review` requires an explicit reconciliation choice.
+- `blocked` means policy, approval, capability, lifecycle state, or outbound
+  safety prevented the action. Do not bypass the gate or broaden the field
+  projection.
+
+Only an `ok` envelope after authoritative read-back is remote success. Native
+provider output, a zero process exit, or a visible remote change is not.
+
+## A clone or worktree has unexpected remote PJM state
+
+Linked worktrees share default local operational state through the Git common
+directory. If one worktree has a pending operation, inspect or continue it
+instead of starting a competing action elsewhere.
+
+Independent clones do not share that local store. In a fresh clone, use
+portable binding metadata plus `oat pjm remote refresh` through a matching live
+host capability before treating snapshots as current. Offline, doctor and
+migration remain available, but commands requiring remote freshness stay
+pending or blocked.
+
+If the repository opted into `.oat/repo/pjm/remote/state/` or
+`<project>/remote/state/`, remember that shared operational storage may contain
+remote planning content visible to repository readers. Promotion requires an
+exact persisted preview and fresh approval; local projects cannot use it.
+
 ## `--scope all` fails outside a Git repository
 
 It should not. `oat status --scope all` and `oat doctor --scope all` complete

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/index.md

@@ -31,6 +31,10 @@ Use this section when you want to choose the right OAT skill for a task. If you
   [Project Retrospectives](../projects/retro.md).
 - Capture a scoped, shippable backlog item: `oat-pjm-add-backlog-item` directly when the work is already scoped, or `oat-brainstorm` when the thought hasn't converged yet — the brainstorm dispatcher's "scoped backlog item" destination pre-fills the title / description / acceptance criteria / scope estimate / priority from the conversation and then runs `oat-pjm-add-backlog-item` with confirmed inputs
 - Manage the repo backlog and reference docs: `oat-pjm-update-repo-reference`, `oat-pjm-review-backlog`
+- Operate an explicit GitHub, Linear, or Jira planning-record binding through a
+  live host capability: `oat-pjm-remote`. The OAT CLI retains policy, preview,
+  approval, journal, and verification authority; the skill discovers and
+  invokes only the exact host action emitted for one durable operation.
 - Turn a repo audit, maintainability review, backlog review, backlog directory, or backlog item into standalone external implementation plans: `oat-repo-improve`. Plans land under `.oat/repo/reference/external-plans/`; execute them directly or optionally pass one to `oat-project-import-plan` for tracked OAT execution.
 - Choose what to delegate and route bounded work by task class across Codex, Claude, or Cursor: `subagent-orchestration`. It is self-contained and usable without OAT; live catalogs and current instructions take precedence over its dated provider examples.
 - Build visual project explainers and final project recaps: `oat-explainer-kit`, backed by the destination-neutral `explainer-kit` core. See [Explainer Kit](explainer-kit.md).
@@ -46,6 +50,34 @@ Use this section when you want to choose the right OAT skill for a task. If you
 - Capture or refine ideas: `oat-idea-new` (capture a new idea), `oat-idea-ideate` (resume an existing tracked idea or expand a scratchpad seed — not for blank-slate brainstorms; use `oat-brainstorm` for those), `oat-idea-scratchpad`, `oat-idea-summarize`
 - Run a project-independent brainstorming conversation: `oat-brainstorm` — entry point with an explicit activation contract. Hard Activation fires only on the `brainstorm` verb ("let's brainstorm", "brainstorm this", "can we brainstorm X", "help me brainstorm X", or `/oat-brainstorm`); ambiguous exploratory phrasing answers conversationally without the banner and offers structured mode only after sustained exploration. Once entered, runs a structured design conversation (one question at a time, 2-3 approaches with a recommendation) and routes to inline / doc-to-path / idea / backlog item / project handoffs based on installed packs. See [Tool Packs](../../cli-utilities/tool-packs.md) for the brainstorm pack details.
 
+## Remote host execution loop
+
+Use `oat-pjm-remote` only for an explicit remote lifecycle request. Its loop is
+deliberately narrow:
+
+1. Before the first provider-contacting command, inspect currently granted MCP
+   or connector descriptions for a semantic and exact-context match.
+2. If no capable connector is available, inspect an already configured
+   provider CLI's live help before the first attempt. Do not install a tool,
+   retain its dialect, or switch execution surfaces mid-attempt.
+3. Construct only bounded provider-neutral capability evidence and pass it to
+   the requested command with `--capability-evidence-stdin`. Treat the CLI's
+   policy, preview, approval, safety, and durable state as authoritative.
+4. When the CLI returns `pending` with `externalAction`, execute that exact
+   semantic action at most once and submit one bounded,
+   sanitized observation with `oat pjm remote operation continue`.
+5. Continue only when the CLI emits another exact action for the same durable
+   operation. Stop on its terminal envelope.
+
+The skill cannot broaden the normalized projection, bypass effective policy,
+binding clamps, purpose field grants, hard approval floors, or caller-owned
+authority evidence, read credential values, persist native provider data, or
+declare remote success. A connector result, process exit, or visible remote
+change is only evidence. Success requires an OAT `ok` envelope after
+authoritative read-back.
+See [Remote Project Management](../../cli-utilities/remote-project-management.md)
+for policy, storage, approval, and recovery details.
+
 ## If You Are Trying To...
 
 - choose the right skill for a task, stay in this guide page
@@ -122,6 +154,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
     - `oat-pjm-add-backlog-item`
     - `oat-pjm-update-repo-reference`
     - `oat-pjm-review-backlog`
+    - `oat-pjm-remote`
     - `docs-completed-projects-gap-review`
 
 === "Research"

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.65",
-  "docs-config": "0.2.65",
-  "docs-theme": "0.2.65",
-  "docs-transforms": "0.2.65"
+  "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