@open-agent-toolkit/cli 0.2.55 → 0.2.57

package/assets/agents/oat-phase-implementer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-phase-implementer
-version: 1.1.1
+version: 1.1.2
 description: Implements one plan phase end-to-end, commits each task separately, self-checks between tasks, and handles bounded review fixes when resumed by oat-project-implement.
 tools: Read, Write, Edit, Bash, Grep, Glob, Task
 color: cyan
@@ -37,7 +37,8 @@ The root supplies:
   candidates, and formal dispatch stamp;
 - `phase_recovery_limit`, `phase_recovery_attempts_used`,
   `original_request_id`, and the root-resolved recovery authorization source;
-- optional `parallel_group`, `expected_base_sha`, and smoke run metadata.
+- optional `parallel_group`, `expected_base_sha`, `recovered_patch`, and
+  smoke run metadata.
 
 Fix mode also supplies:
 
@@ -341,6 +342,16 @@ use ancestry from `expected_base_sha` as a substitute for the exact
 `phase_base_head` check. For a plan-declared parallel group, verify this before
 any task edit.
 
+A fresh child never starts on a dirty tree. The one exception is a supplied
+`recovered_patch`, which carries work a lost child left behind: verify it,
+apply it, review it, and commit it as your first action before task one,
+exactly as `## Mode: Recover` steps 2 and 4 describe, and only after every
+precondition that can park the phase has passed. That single commit is a
+recovery commit rather than a planned task commit, so it does not consume any
+task's one-commit budget; report it under `### Recovery Events` with the
+artifact reference and manifest digest. Without a verified `recovered_patch`,
+any dirt blocks.
+
 When smoke containment, ownership registration, expected base, or fixture
 readiness proves the run invalid, return `INVALID_RUN_ABORT` with the evidence.
 Do not launch a child, continue sequentially, review, or repair the invalid run.
@@ -462,8 +473,18 @@ phase_verification: { relevant phase command }
 dispatch_target: { exact original launcher-owned target }
 dispatch_axes: { unchanged original launcher-owned axes }
 dispatch_stamp: { original formal Dispatch line }
+recovered_patch: { artifact, manifest_digest, size, stat, components }
 ```
 
+`recovered_patch` is optional. It is present only when a lost child left
+uncommitted work that the lifecycle captured before restoring the worktree to
+its clean base. Its `artifact` is a readable path outside the worktree, never a
+mutable worktree path; `manifest_digest` and `size` are the capture's recorded
+values; `stat` is the captured `git diff --cached --stat` summary; and
+`components` lists the `index`, `worktree`, and `untracked` entries the
+artifact holds. The same field may arrive on a same-target `implement`
+continuation.
+
 1. Validate every recover input. Confirm the exact launcher-owned target equals
    the original target and the generic `continuation_events` record links
    `continuation_event` to `original_request_id`.
@@ -471,23 +492,116 @@ dispatch_stamp: { original formal Dispatch line }
    remains immutable at the same history position; and the worktree contains
    only the reconciled pending ledger reservation plus an optional mechanically
    bounded diff inside `bounded_files`. Any other dirt or history change
-   blocks.
+   blocks. Compare against the briefed `recovery_base_head`, never a remembered
+   earlier value: once a recovery-patch commit has landed, the retry's
+   `recovery_base_head` is the reconciled current HEAD, which includes that
+   recovery commit and any candidate or ledger-only commit already durably
+   made, and the brief omits the already-committed artifact because re-applying
+   it would duplicate the work. Beyond that reconciled reservation and its
+   bounded diff, a supplied `recovered_patch` is the only permitted
+   pre-existing dirt, and only after it verifies. Verification is read-only and
+   happens here; the apply and the commit wait for step 4, so every precondition
+   that can park the phase resolves before anything is written. When the brief
+   carries no `recovered_patch` — an ordinary resume, or a retry after the
+   recovery commit already landed — the ordinary permitted-dirt invariant above
+   is the whole of this step: there is no artifact to resolve a script for, so
+   the continuation skips verification and continues to the ledger
+   reconciliation in step 3, and step 4 is a no-op. Resolve
+   `capture-dirty-tree.mjs` through installed scope rather than a
+   repository-relative path, probing in order and binding the first match, and
+   only when an artifact was briefed:
+
+   ```bash
+   set -eu
+   # `recovered_patch` is optional and all-or-nothing. Without one there is
+   # nothing to verify and nothing to apply, so the verifier is skipped
+   # entirely; a partial brief is a named stop rather than an unbound-variable
+   # death. Never dereference an artifact variable outside the branch: under
+   # `set -u` an unset one exits here, and an empty one fails verification —
+   # either way an artifact-free retry parks before the ledger reconciliation
+   # it needs to reach.
+   if [ -z "${ARTIFACT_DIR:-}${MANIFEST_DIGEST:-}${ARTIFACT_SIZE:-}" ]; then
+     : # No recovered_patch: continue to the ledger reconciliation.
+   elif [ -z "${ARTIFACT_DIR:-}" ] || [ -z "${MANIFEST_DIGEST:-}" ] ||
+     [ -z "${ARTIFACT_SIZE:-}" ]; then
+     echo "artifact-verification-failed: a partial recovered_patch is unusable; artifact, manifest_digest and size travel together" >&2
+     exit 1
+   else
+     CAPTURE_SCRIPT=""
+     REPO_ROOT=$(git -C "$PHASE_WORKTREE" rev-parse --show-toplevel 2>/dev/null || true)
+     for CAPTURE_ROOT in "${HOME:-}/.agents/skills/oat-project-implement" \
+       "${REPO_ROOT:+$REPO_ROOT/.agents/skills/oat-project-implement}"; do
+       [ -n "$CAPTURE_ROOT" ] || continue
+       [ -f "$CAPTURE_ROOT/scripts/capture-dirty-tree.mjs" ] || continue
+       CAPTURE_SCRIPT="$CAPTURE_ROOT/scripts/capture-dirty-tree.mjs"
+       break
+     done
+     [ -n "$CAPTURE_SCRIPT" ] || {
+       echo "capture-script-unavailable" >&2
+       exit 1
+     }
+
+     EXPECTED_HEAD=$(git -C "$PHASE_WORKTREE" rev-parse --verify HEAD)
+     node "$CAPTURE_SCRIPT" --verify \
+       --artifact-dir "$ARTIFACT_DIR" \
+       --manifest-digest "$MANIFEST_DIGEST" \
+       --size "$ARTIFACT_SIZE" \
+       --expected-head "$EXPECTED_HEAD"
+   fi
+   ```
+
+   `ARTIFACT_DIR`, `MANIFEST_DIGEST`, and `ARTIFACT_SIZE` are the
+   `recovered_patch` fields; bind them as shell variables rather than pasting
+   `<placeholder>` tokens, which a shell reads as input redirections. The guard
+   terminates rather than warning: `node ""` reads its program from stdin and
+   exits zero at EOF, so a fall-through would report an unverified artifact as
+   verified. Every block that runs the script repeats the resolution and the
+   guard, because shell variables do not survive across separate tool
+   invocations. `--expected-head` and the
+   apply below both resolve against `$PHASE_WORKTREE`, never the ambient
+   working directory. An empty `CAPTURE_SCRIPT` is a
+   `capture-script-unavailable` stop: report it verbatim with the probed roots
+   and the recovery command
+   `oat tools install workflows --scope <user|project>` or
+   `oat tools update --pack workflows --scope <user|project>`, and never fall
+   back to a repository-relative path. With an artifact briefed, verify before
+   touching the tree and stop on any `artifact-verification-failed` mismatch, including the base mismatch
+   `--expected-head` catches: integrity is not base agreement, and a hunk whose
+   context happens to match applies cleanly at the wrong commit. Report an
+   `active-writer`, `unsupported-dirt`, `round-trip-failed`, or
+   `artifact-verification-failed` reason verbatim and stop; never improvise a
+   partial or best-effort restore. Without a verified `recovered_patch` you
+   start on a clean tree.
+
 3. Reconcile the authoritative `pending_attempt` and nonzero
    `phase_recovery_attempts_used` with `state.md`. Recover mode continues that
    same consumed attempt and must not increment usage again. Missing,
-   contradictory, or unreconciled state blocks before editing.
-4. Apply or complete only `bounded_correction_scope`. Recover mode must not
+   contradictory, or unreconciled state blocks before editing. Nothing has been
+   applied or committed yet, so this block leaves the branch exactly at
+   `recovery_base_head` with the artifact untouched and re-verifiable; the root
+   re-briefs from current authoritative state once the ledger is repaired.
+4. Only now apply the verified `recovered_patch`, if one was supplied:
+   `git apply --index` for the `index` component, `git apply` for the
+   `worktree` component, and byte copies plus the manifest's recorded
+   executable bit for the `untracked` component. Review the result and commit
+   it as your first action. That commit is immutable, and so is every commit
+   this mode durably makes after it: if anything later parks the phase, the
+   retry's `recovery_base_head` is the reconciled current HEAD, which includes
+   that recovery commit and any candidate or ledger-only commit already made.
+   That brief omits the already-committed artifact; dirt that accumulated
+   afterwards travels as its own newly captured `recovered_patch`.
+5. Apply or complete only `bounded_correction_scope`. Recover mode must not
    replay planned tasks and must not require, fabricate, or consume a review
    artifact.
-5. Apply the bounded correction, then run `focused_verification` and
+6. Apply the bounded correction, then run `focused_verification` and
    `phase_verification` before creating a candidate commit. If either check
    fails, restore `bounded_files` to their original committed content,
    atomically mark the pending entry `failed`, durably commit only that
    ledger transition, emit one `failed-attempt` event, and stop.
-6. When both pre-commit checks pass, atomically mark the pending entry
+7. When both pre-commit checks pass, atomically mark the pending entry
    `completed` and create one append-only candidate recovery commit containing
    only `bounded_files` plus that ledger transition.
-7. Immediately rerun `focused_verification` and `phase_verification` against the
+8. Immediately rerun `focused_verification` and `phase_verification` against the
    committed HEAD; these reruns are authoritative. On pass, emit one `recovered`
    event and report the candidate as the successful recovery commit. On
    failure, atomically replace `completed` with `failed`, durably commit that
@@ -496,7 +610,7 @@ dispatch_stamp: { original formal Dispatch line }
    commit. If terminal evidence cannot be committed, report an unreconciled
    block that root must reject before bookkeeping. Never amend history or
    launch fallback.
-8. Return the report below. `DONE` is accepted success;
+9. Return the report below. `DONE` is accepted success;
    `DONE_WITH_CONCERNS` and `BLOCKED` may be accepted terminal stops and must
    still report provenance, accounting, immutable history, and the event.
 

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.2.55"
+  "oatVersion": "0.2.57"
 }

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

@@ -90,6 +90,7 @@ Common keys in `.oat/config.json`:
 - `worktrees.root` — where OAT-managed worktrees live
 - `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.requireForProjectCompletion` — whether docs sync is a completion gate
 - `archive.s3Uri` — base S3 archive prefix
 - `archive.s3SyncOnComplete` — upload archived projects to S3 during completion
@@ -242,8 +243,17 @@ packaged `assets/` directory next to the installed CLI. Setting a non-empty
   directory.
 - The override is validated exactly like the packaged root and fails closed:
   the path must be a directory containing bundle metadata whose version matches
-  the running CLI (`OAT_VERSION`). A missing, malformed, or version-mismatched
-  override is an error — the CLI never silently falls back to packaged assets.
+  the running CLI (`OAT_VERSION`) **and** the seven top-level directories the
+  bundle producer creates (`skills`, `agents`, `templates`, `scripts`, `docs`,
+  `migration`, `config`), each of which must be a directory. A missing,
+  malformed, version-mismatched, or structurally incomplete override is an
+  error with exit code 2 that names the first offending path — the CLI never
+  silently falls back to packaged assets, and a metadata-only directory is no
+  longer accepted as an empty installation.
+- Remedies are source-aware: an `OAT_ASSETS_DIR` failure tells you to fix or
+  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.
 - 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/docs-tooling/commands.md

@@ -128,23 +128,54 @@ Key behavior:
 - recursively walks the docs directory
 - extracts page titles from frontmatter (falls back to first `# heading`, then filename title-case)
 - includes descriptions from frontmatter when present
-- outputs to app root (`index.md`) by default, not inside the docs directory
-- updates `documentation.index` in `.oat/config.json`
+- resolves omitted paths from `.oat/config.json` rather than the current directory: `--docs-dir` defaults to `<documentation.root>/docs` when that directory exists and to `<documentation.root>` otherwise, and `--output` defaults to the app-root manifest `<documentation.root>/index.md`
+- 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
+- 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`
+- 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:
 
-- `--docs-dir <path>` (default: `docs`)
-- `--output <path>` (default: `index.md` at app root)
+- `--docs-dir <path>` (default: `<documentation.root>/docs`, falling back to `<documentation.root>`)
+- `--output <path>` (default: `<documentation.root>/index.md`)
+- `--exclude <glob>` (repeatable; additive to `documentation.excludes`)
+
+### Exclusion patterns
+
+Patterns match the path of each candidate **relative to the docs directory being indexed** — `api/auth.md`, `api/nested` — never an absolute or current-directory-relative path, and never the repository-relative path.
+
+| Pattern        | Matches                                                  |
+| -------------- | -------------------------------------------------------- |
+| `CLAUDE.md`    | only the root-level `CLAUDE.md`; patterns are anchored   |
+| `**/CLAUDE.md` | `CLAUDE.md` at any depth, including the docs root        |
+| `*.md`         | root-level Markdown only; `*` never crosses `/`          |
+| `drafts/`      | the `drafts` directory and everything beneath it         |
+| `drafts`       | the same directory; the trailing `/` only forbids a file |
+| `api/**/*.md`  | Markdown at any depth under `api/`, including `api/x.md` |
+
+A trailing `/` restricts a pattern to directories and never matches a file; without it, a pattern that matches a directory path still prunes that directory. `**` spans `/` only as a whole path segment — inside a segment (`a**b`) it is an ordinary single-segment wildcard. Matching is case-sensitive, `/` is the separator on every platform, and only `*` and `**` are metacharacters — every other character, `.` included, is literal. A leading `./` or `/` is stripped, so both spellings anchor at the docs root.
 
 Example:
 
 ```bash
-oat docs generate-index --docs-dir docs
+# Resolve both paths from .oat/config.json
+oat docs generate-index
+
+# Portable explicit form, resolved from the current directory
+oat docs generate-index --docs-dir apps/oat-docs/docs --output apps/oat-docs/index.md
+
+# Persist the repository's own exclusions, then add a one-off
+oat config set documentation.excludes "**/CLAUDE.md,**/AGENTS.md"
+oat docs generate-index --exclude 'drafts/'
 ```
 
+See [Documentation path resolution](../reference/oat-directory-structure.md#documentation-path-resolution) for the app-root meaning of `documentation.root` and the legacy source-root compatibility rule.
+
 The Fumadocs scaffold runs this automatically via `predev`/`prebuild` npm
 script hooks.
 

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

@@ -117,10 +117,11 @@ Current schema keys:
 | `projects.root`                                            | `string`                   | `".oat/projects/shared"` | Default root directory for OAT projects                                                                                                                                                                                                                                                                 |
 | `projects.defaultScope`                                    | `string`                   | `"synced"`               | Scope used by project creation when `--scope` is omitted: `shared`, `local`, or `synced`. Environment override: `OAT_PROJECTS_DEFAULT_SCOPE`.                                                                                                                                                           |
 | `localPaths`                                               | `string[]`                 | -                        | Gitignored directories to sync between main repo and worktrees. Supports glob patterns. Managed via `oat local add/remove`.                                                                                                                                                                             |
-| `documentation.root`                                       | `string`                   | -                        | Root directory containing documentation source files (e.g., `apps/docs/docs`)                                                                                                                                                                                                                           |
+| `documentation.root`                                       | `string`                   | -                        | Docs **app root** — the directory `oat docs init` scaffolds (e.g., `apps/docs`). Authored pages live under `<root>/docs`. See [Documentation path resolution](#documentation-path-resolution).                                                                                                          |
 | `documentation.tooling`                                    | `string`                   | -                        | Documentation framework identifier (`mkdocs` or `fumadocs`)                                                                                                                                                                                                                                             |
 | `documentation.config`                                     | `string`                   | -                        | Path to the documentation framework config file (e.g., `mkdocs.yml`, `next.config.js`)                                                                                                                                                                                                                  |
-| `documentation.index`                                      | `string`                   | -                        | Path to the docs surface entry point (e.g., `index.md` for Fumadocs, `mkdocs.yml` for MkDocs). Set by `oat docs init` and updated by `oat docs generate-index`.                                                                                                                                         |
+| `documentation.index`                                      | `string`                   | -                        | Path to the docs surface entry point: the generated app-root manifest `<root>/index.md` for Fumadocs, `mkdocs.yml` for MkDocs. Set by `oat docs init`. `oat docs generate-index` writes it only for the Fumadocs manifest transition and never for MkDocs.                                              |
+| `documentation.excludes`                                   | `string[]`                 | -                        | Globs, relative to the docs directory, that `oat docs generate-index` leaves out of the generated index. See [Excluding pages from the generated index](#excluding-pages-from-the-generated-index).                                                                                                     |
 | `documentation.requireForProjectCompletion`                | `boolean`                  | `false`                  | When `true`, OAT project completion gates require documentation to be updated                                                                                                                                                                                                                           |
 | `git.defaultBranch`                                        | `string`                   | `"main"`                 | Default branch for PR creation. Auto-detected during `oat init` via `gh repo view` or `origin/HEAD`. Used by `oat-project-pr-final` and `oat-project-pr-progress`.                                                                                                                                      |
 | `workflow.autoReviewAtHillCheckpoints`                     | `boolean`                  | unset                    | When `true`, completing a HiLL checkpoint automatically runs the extra lifecycle review. Does not control Tier 1 per-phase `oat-reviewer` gates. Can be overridden per-project via `oat_auto_review_at_hill_checkpoints` in `plan.md` frontmatter. Legacy `autoReviewAtCheckpoints` remains a fallback. |
@@ -157,14 +158,65 @@ Example:
     "root": ".worktrees"
   },
   "documentation": {
-    "root": "apps/docs/docs",
+    "root": "apps/docs",
     "tooling": "mkdocs",
-    "config": "mkdocs.yml",
+    "config": "apps/docs/mkdocs.yml",
+    "index": "apps/docs/mkdocs.yml",
     "requireForProjectCompletion": false
   }
 }
 ```
 
+### Documentation path resolution
+
+`documentation.root` canonically names the docs **app root** — exactly the directory `oat docs init` scaffolds. Authored Markdown lives under `<root>/docs`, and the generated Fumadocs manifest is written to `<root>/index.md`, outside the tree it indexes.
+
+`oat docs generate-index` resolves omitted options from this configuration:
+
+| Option       | Omitted                                                                                  | Supplied                            |
+| ------------ | ---------------------------------------------------------------------------------------- | ----------------------------------- |
+| `--docs-dir` | `<documentation.root>/docs` when that directory exists, otherwise `<documentation.root>` | Resolved from the current directory |
+| `--output`   | `<documentation.root>/index.md`                                                          | Resolved from the current directory |
+
+If an omitted option has no non-empty `documentation.root` to resolve against, or the configured root is not a directory, the command fails with exit code `2` before generating or writing anything.
+
+**Compatibility behavior.** Preferring `<root>/docs` exists for legacy configs whose `root` names a docs _source_ directory rather than an app root; it is not a second meaning of the key. Because the rule is a plain directory-existence test, a source root that happens to contain its own `docs` subdirectory is narrowed to it. The command prints the directory it derived in both human and JSON output (`docsDir`, `docsDirSource`), and `--docs-dir` is the escape hatch when the derivation is wrong.
+
+A legacy source root with no `docs` child resolves `--docs-dir` and `--output` to the same tree, so a bare run is refused rather than allowed to overwrite an authored page. Pass an explicit `--output` outside the source tree, or repoint `documentation.root` at the app root.
+
+**Refused output targets.** Checked before generation for derived and explicit paths alike, the command refuses to write an output that is inside the docs directory it indexes, equals `documentation.config`, or ends in `.yml` / `.yaml`. A derived output whose existing file lacks the `AUTOGENERATED by oat docs generate-index` header is also refused; naming that same path with `--output` overwrites it explicitly.
+
+**Configuration writes.** The only configuration write generation performs is the Fumadocs manifest transition: when the written manifest lies inside `documentation.root` and `documentation.tooling` is `fumadocs`, the repo-relative output path is recorded in `documentation.index`. A config that declares neither `documentation.tooling` nor `documentation.config` is treated as the same Fumadocs-shaped case. Any other declared tooling — `mkdocs` included — is never written, and neither are `documentation.root` and `documentation.config`. The value is always repo-relative: when `documentation.root` points outside the repository, the manifest is still generated but the key is left untouched rather than recording a machine-specific path.
+
+### Excluding pages from the generated index
+
+`documentation.excludes` and the repeatable `--exclude <glob>` flag feed one matcher. Flags **extend** the configured list rather than replacing it, so a one-off exclusion cannot silently republish pages the repository deliberately excluded. A directory left empty by exclusion emits no heading, and an empty list produces byte-identical output to no exclusions at all.
+
+Patterns are matched against each candidate's path **relative to the docs directory being indexed** — the directory `--docs-dir` resolved to, not `documentation.root` and not the repository root.
+
+| Pattern        | Matches                                                  |
+| -------------- | -------------------------------------------------------- |
+| `CLAUDE.md`    | only the root-level `CLAUDE.md`; patterns are anchored   |
+| `**/CLAUDE.md` | `CLAUDE.md` at any depth, including the docs root        |
+| `*.md`         | root-level Markdown only; `*` never crosses `/`          |
+| `drafts/`      | the `drafts` directory and everything beneath it         |
+| `api/**/*.md`  | Markdown at any depth under `api/`, including `api/x.md` |
+
+A trailing `/` restricts a pattern to directories and never matches a file; without it, a pattern that matches a directory path still prunes that directory. `**` spans `/` only as a whole path segment — inside a segment (`a**b`) it is an ordinary single-segment wildcard. Matching is case-sensitive, `/` is the separator on every platform, and only `*` and `**` are metacharacters — every other character, `.` included, is literal. A leading `./` or `/` is stripped, so both spellings anchor at the docs root. Entries are trimmed and de-duplicated; a malformed `documentation.excludes` (a non-array, or an empty or non-string entry) is rejected rather than silently ignored. `oat docs generate-index` reports it with exit code `2`; `oat config` surfaces the same error as an ordinary exit-`1` user error. `oat config set documentation.excludes` can still replace or clear a malformed value, so the repair the error names always works.
+
+Set the list with the comma-separated grammar, and clear it with an empty value:
+
+```bash
+oat config set documentation.excludes "**/CLAUDE.md,**/AGENTS.md"
+oat config set documentation.excludes ""
+```
+
+This repository pins the invocation explicitly, which is the portable fallback anywhere the configured defaults are not what you want:
+
+```bash
+oat docs generate-index --docs-dir apps/oat-docs/docs --output apps/oat-docs/index.md
+```
+
 ### Worktree root precedence
 
 When resolving the worktree root directory, `oat-worktree-bootstrap` uses this strict precedence (stops at the first match):

package/assets/docs/workflows/projects/implementation-execution.md

@@ -152,7 +152,11 @@ by the phase's standing authority. The important distinctions are:
   boundary, not for every eligible defect;
 - a **continuation** preserves the original request and exact target, either in
   the accepted handle or through an explicitly linked fresh same-target
-  recovery launch; and
+  recovery launch, and never starts on a dirty tree: uncommitted work a lost
+  child left behind is first captured into a digest-verified artifact,
+  restored out of the worktree, handed forward as `recovered_patch`, and
+  committed by the continuation as its first action, while unverified or
+  unsupported dirt still blocks; and
 - a **successful repair** produces one immutable append-only recovery commit.
 
 This recovery is not accepted-launch fallback. After a launch is accepted,

package/assets/docs/workflows/skills/explainer-kit.md

@@ -434,11 +434,14 @@ typed adapter settings.
 Private integrations use the core boundary directly: resolve private inputs
 before the run, construct one versioned request, invoke the core once, then
 publish or link the versioned manifest after the run. Wrapper acceptance reads
-the complete post-run `publish-receipt/v2`, verifies every manifest artifact
-and the core run ID, and rejects foreign or stale receipts; `publish-receipt/v1`
-remains readable for replay of older runs only. Presets, private source
-systems, external-document synchronization, and personal destinations remain
-wrapper-owned.
+the complete post-run `publish-receipt/v2`, requires complete manifest and
+catalog evidence, verifies the core run ID, and rejects foreign or stale
+receipts; `publish-receipt/v1` remains readable for replay of older runs only.
+Public and protected v2 receipts must each provide exactly one entry for every
+finalized manifest artifact and exactly one generated catalog entry. The
+`explainer-kit` wrapper extension contract owns this rule; this page restates
+it for integrators. Presets, private source systems, external-document
+synchronization, and personal destinations remain wrapper-owned.
 
 V1 exposes no plugin registry or private mid-pipeline hook. Unsupported
 contract majors and identity mismatches fail closed instead of being guessed

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.55",
-  "docs-config": "0.2.55",
-  "docs-theme": "0.2.55",
-  "docs-transforms": "0.2.55"
+  "cli": "0.2.57",
+  "docs-config": "0.2.57",
+  "docs-theme": "0.2.57",
+  "docs-transforms": "0.2.57"
 }

package/assets/skills/analyze/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: analyze
-version: 0.1.1
+version: 0.2.0
 description: Multi-angle analysis of existing artifacts, codebases, documents, or systems. Examines what you have from six analysis angles and produces structured findings with prioritized recommendations.
 argument-hint: 'target [--context path]'
 user-invocable: true
@@ -49,15 +49,16 @@ Print this banner once at start:
 
 Then print step indicators before beginning work:
 
-- `[1/9] Parsing arguments…`
-- `[2/9] Reading context…` (if applicable)
-- `[3/9] Classifying input type…`
-- `[4/9] Selecting analysis angles…`
-- `[5/9] Checking sub-agent availability…`
-- `[6/9] Executing analysis angles…`
-- `[7/9] Checking for comparisons…` (if applicable)
-- `[8/9] Cross-angle synthesis…`
-- `[9/9] Writing artifact…`
+- `[1/10] Parsing arguments…`
+- `[2/10] Reading context…` (if applicable)
+- `[3/10] Classifying input type…`
+- `[4/10] Selecting analysis angles…`
+- `[5/10] Checking sub-agent availability…`
+- `[6/10] Executing analysis angles…`
+- `[7/10] Checking for comparisons…` (if applicable)
+- `[8/10] Cross-angle synthesis…`
+- `[9/10] Resolving output destination…`
+- `[10/10] Writing artifact…`
 
 For long-running operations, print a start line and a completion line:
 
@@ -72,7 +73,7 @@ Keep it concise; don't print a line for every shell command.
 
 ### Step 1: Parse arguments
 
-`[1/9] Parsing arguments…`
+`[1/10] Parsing arguments…`
 
 Parse from `$ARGUMENTS`:
 
@@ -91,7 +92,7 @@ The prompt should ask: _"What would you like me to analyze? Provide a file path,
 
 ### Step 2: Read context (if provided)
 
-`[2/9] Reading context…`
+`[2/10] Reading context…`
 
 If `--context` is specified:
 
@@ -107,7 +108,7 @@ If `--context` is not specified, skip this step.
 
 ### Step 3: Input type classification
 
-`[3/9] Classifying input type…`
+`[3/10] Classifying input type…`
 
 Classify the target to determine analysis angle emphasis:
 
@@ -126,7 +127,7 @@ Log: `→ Input type: {type}`
 
 ### Step 4: Analysis angle selection
 
-`[4/9] Selecting analysis angles…`
+`[4/10] Selecting analysis angles…`
 
 All six angles are ALWAYS run. The input type determines emphasis weighting (primary angles get deeper investigation):
 
@@ -157,7 +158,7 @@ Log the selected emphasis: `→ Primary: {angles} · Secondary: {angles}`
 ### Step 5: Sub-agent availability probe
 
 ```
-[5/9] Checking sub-agent availability…
+[5/10] Checking sub-agent availability…
   → analysis workers: {available | not resolved} ({reason})
   → Selected: Execution Tier {1|2|3} — {description}
 ```
@@ -184,7 +185,7 @@ Log the selected emphasis: `→ Primary: {angles} · Secondary: {angles}`
 
 ### Step 6: Execute analysis angles
 
-`[6/9] Executing analysis angles…`
+`[6/10] Executing analysis angles…`
 
 For each angle, the worker (sub-agent or self) receives:
 
@@ -209,7 +210,7 @@ Print progress for each angle:
 
 ### Step 7: Conditional /compare dispatch
 
-`[7/9] Checking for comparisons…`
+`[7/10] Checking for comparisons…`
 
 If any angle surfaces comparables (e.g. "this component could use library A or B"):
 

package/assets/skills/oat-brainstorm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-brainstorm
-version: 1.3.4
+version: 1.3.5
 description: Use when the user explicitly invokes the `brainstorm` verb, including `/oat-brainstorm`, "let's brainstorm", "brainstorm this", "can we brainstorm X", or "help me brainstorm X". For ambiguous exploratory phrasing ("I've been thinking", "what if", "help me think through"), do NOT auto-enter; respond conversationally and offer mode only after ≥2 sustained exploratory turns. Do NOT use for review, debug, PR, status, implementation, or active-workflow questions.
 disable-model-invocation: false
 user-invocable: true
@@ -191,7 +191,7 @@ Classify the opening brainstorm topic before running the Node preflight or print
 command -v node >/dev/null 2>&1 && echo "available" || echo "missing"
 ```
 
-- If `node` is **missing**: skip the offer entirely. Do not print the offer message. Log a one-line note in the conversation that the visual companion is unavailable in this environment (a state `oat-doctor` can pick up later: "visual companion suppressed — node not on PATH"). Proceed with `VISUAL_COMPANION = "unavailable"`.
+- If `node` is **missing**: skip the offer entirely. Do not print the offer message. Log a one-line note in the conversation for this session only: "visual companion suppressed — node not on PATH". Nothing persists that note, so no later diagnostic run can report it. Proceed with `VISUAL_COMPANION = "unavailable"`.
 - If `node` is **available**: print the offer as its own message. Suggested wording (adapt freely; the constraint is "own message, no other content"):
 
   > "Some of what we're working on might be easier to explain if I can show it in a local web browser — mockups, diagrams, side-by-side comparisons. The visual companion is bundled with this skill (a small Node-based local server). Want me to start it? (Requires opening a `localhost` URL.)"