@open-agent-toolkit/cli 0.3.31 → 0.3.33

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.3.31"
+  "oatVersion": "0.3.33"
 }

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

@@ -17,7 +17,13 @@ oat docs check --rule description h1 --rule links --json
 
 Omitted targets use `documentation.root`, then the existing `docs` fallback.
 Framework app roots resolve to their content directory. A literal Markdown root
-stays literal even with a child named `docs`. Paths in findings are deterministic,
+stays literal even with a child named `docs`. The checker never reads
+`node_modules` or hidden directories such as `.git` and `.oat`. An explicit
+target other than the configured root is checked without the configured policy;
+the text output prints a notice that says so and names the mode. Targeting a
+configured framework app's `docs/` content directory checks it as Markdown and
+skips navigation, so the notice suggests the app root instead. Notices never
+appear in `--json` output. Paths in findings are deterministic,
 content-root-relative POSIX paths; physical line locations are included when
 available, including nested supported tabs. No sidebar or default manifest is
 required for Markdown.
@@ -47,9 +53,23 @@ Fix the authored page, its local Contents map and inbound links together. For
 owned generated navigation, run `oat docs nav sync`, then rerun the checker.
 Hand-authored or undeclared navigation is compared for membership/order without
 requiring generated display labels, title fields or YAML formatting; do not
-silently regenerate it. Missing optional Fumadocs metadata, metadata objects without
-`pages`, and absent MkDocs `nav` skip comparison. Present `pages` must be an array;
-explicit entries still compare membership/order. Implicit Fumadocs order is not
+silently regenerate it. A page listed in Contents must be reachable from some
+sidebar entry: its own folder's `pages`, a rest entry, a borrow from another
+folder such as `"../install"`, a root-relative link item to its URL, or the
+folder's `pagesIndex` (a page path, or a link to the folder's own URL). The
+docs root never shows its own index in the sidebar, so a root `pagesIndex` does
+not count; list `index` or link to `/`. Folders with `root` set get no implicit
+index either. Only
+folders the sidebar attaches from the docs root count: a link to a folder's URL
+reaches its landing page, not its other pages. A `"...name"` extraction inlines a folder's
+index and pages and never names a page. Every
+`pages` or `nav` entry must name an existing page or folder, and listed pages keep
+their Contents order. Separators and their labels, MkDocs section labels and
+nesting, link items, rest entries and borrowed pages are presentation and are
+not compared. Messages name the mismatch: a missing reader page or folder, a
+missing target, or an order difference with both orders. Missing optional
+Fumadocs metadata, metadata objects without `pages`, and absent MkDocs `nav`
+skip comparison. Present `pages` must be an array of strings. Implicit Fumadocs order is not
 compared. Nav-sync ownership retains its existing strict read-only freshness check. Generated inventories are separate: regenerate configured output
 and check its Git diff after the build. A build that rewrites the inventory does
 not prove the committed copy was fresh.
@@ -69,30 +89,30 @@ fenced examples do not become headings, links, groups or diagrams. YAML
 frontmatter, GFM/reference links, explicit heading IDs, static HTML and supported
 recursive tabs participate.
 
-| Rule ID                 | Default behavior                                                                                                                                                                                                                                 |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `directory-index`       | Error for a reader-bearing directory without `index.md` and a nonempty dash-bullet Contents map, invalid map grammar or unresolved strict Contents target. Ancestors of reader pages participate.                                                |
-| `root-width`            | Flat root Contents links warn above `rootWarn: 10`, error above `rootError: 14`. Real groups exempt the width.                                                                                                                                   |
-| `contents-width`        | Ungrouped Contents links warn above `contentsWarn: 10`, error above `contentsError: 15`. `catalog: true` or the recognized OAT generated-index marker exempts only this width rule.                                                              |
-| `leaf-size`             | Direct reader pages include index. A leaf has no reader-bearing child directory: index-only errors; two total pages warn.                                                                                                                        |
-| `folder-size`           | Direct reader pages including index warn above `folderWarn: 12`, error above `folderError: 20`, unless the index has real groups.                                                                                                                |
-| `depth`                 | Content root is depth 0; warn at `depthWarn: 4`, error at `depthError: 5`.                                                                                                                                                                       |
-| `page-length`           | Warn above `pageLines: 500` physical source lines. Explicit `type: reference` or `reference`/`references` path segments use `referenceLines: 1000` and warn above `referenceH3: 40` real H3 headings. No default length error limit.             |
-| `frontmatter`           | Unreadable source, invalid YAML or a non-mapping frontmatter document errors. Read failures use relative paths and safe error codes; invalid metadata skips description validation while independent body checks continue at physical positions. |
-| `description`           | Missing/empty frontmatter description errors; character lengths below `descriptionMin: 40` or above `descriptionMax: 160` warn.                                                                                                                  |
-| `h1`                    | Error unless each page has exactly one real H1.                                                                                                                                                                                                  |
-| `links`                 | Error for unresolved in-root source links/anchors. No network checking. Ordinary escaping links are provenance warnings and their targets are not read. Contents links retain stricter local-map rules.                                          |
-| `contents-description`  | Error for descriptions ending in an ellipsis/truncation.                                                                                                                                                                                         |
-| `overview`              | Warn below `overviewWords: 10` before Contents.                                                                                                                                                                                                  |
-| `contents-separator`    | Warn when Contents descriptions mix separators in a tree.                                                                                                                                                                                        |
-| `navigation`            | Error for explicit navigation drift using declared ownership semantics; hand-authored/undeclared absent optional meta/pages/nav skips comparison. Nav-sync freshness stays strict; Markdown skips it.                                            |
-| `commands`              | Error for missing literal contributor scripts; implicit pnpm shorthand also accepts installed package/workspace `.bin` entries. Explicit pnpm run/npm run stays script-only; unresolved context errors; echo scripts warn.                       |
-| `mermaid`               | Parse every real Mermaid fence using the pinned Mermaid parser. Invalid syntax errors.                                                                                                                                                           |
-| `diagram-pairs`         | Diagram light/dark SVG siblings and both page references are required. Conventional diagram paths and explicit paired references participate; ordinary logos are not diagrams.                                                                   |
-| `diagram-accessibility` | Mermaid missing `accTitle`/`accDescr` warns. SVGs require `role="img"`, nonempty title/desc. Rendered diagrams without page-visible explanatory text or an associated long description warn.                                                     |
-| `diagram-freshness`     | Warn when changed Mermaid lacks both associated SVG changes; association follows the actual section/tab group. Missing usable Git comparison is explicitly unverified.                                                                           |
-| `image-alt`             | Warn for empty, filename/slug-like or longer than `altMax: 155` image alt text.                                                                                                                                                                  |
-| `provenance`            | Warn for planning/backlog/home paths, configured ticket/milestone patterns and ordinary links escaping the root. Legitimate reader docs remain visible.                                                                                          |
+| Rule ID                 | Default behavior                                                                                                                                                                                                                                                                                                                    |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `directory-index`       | Error for a reader-bearing directory without `index.md` and a nonempty dash-bullet Contents map, invalid map grammar or unresolved strict Contents target. Ancestors of reader pages participate.                                                                                                                                   |
+| `root-width`            | Flat root Contents links warn above `rootWarn: 10`, error above `rootError: 14`. Real groups exempt the width.                                                                                                                                                                                                                      |
+| `contents-width`        | Ungrouped Contents links warn above `contentsWarn: 10`, error above `contentsError: 15`. `catalog: true` or the recognized OAT generated-index marker exempts only this width rule.                                                                                                                                                 |
+| `leaf-size`             | Direct reader pages include index. A leaf has no reader-bearing child directory: index-only errors; two total pages warn.                                                                                                                                                                                                           |
+| `folder-size`           | Direct reader pages including index warn above `folderWarn: 12`, error above `folderError: 20`, unless the index has real groups.                                                                                                                                                                                                   |
+| `depth`                 | Content root is depth 0; warn at `depthWarn: 4`, error at `depthError: 5`.                                                                                                                                                                                                                                                          |
+| `page-length`           | Warn above `pageLines: 500` physical source lines. Explicit `type: reference` or `reference`/`references` path segments use `referenceLines: 1000` and warn above `referenceH3: 40` real H3 headings. No default length error limit. `line` is the first physical line past the line limit, or the first H3 past the heading limit. |
+| `frontmatter`           | Unreadable source, invalid YAML or a non-mapping frontmatter document errors. Read failures use relative paths and safe error codes; invalid metadata skips description validation while independent body checks continue at physical positions.                                                                                    |
+| `description`           | Missing/empty frontmatter description errors; character lengths below `descriptionMin: 40` or above `descriptionMax: 160` warn.                                                                                                                                                                                                     |
+| `h1`                    | Error unless each page has exactly one real H1.                                                                                                                                                                                                                                                                                     |
+| `links`                 | Error for unresolved in-root source links/anchors. No network checking. Ordinary escaping links are provenance warnings and their targets are not read. Contents links retain stricter local-map rules.                                                                                                                             |
+| `contents-description`  | Error for descriptions ending in an ellipsis/truncation.                                                                                                                                                                                                                                                                            |
+| `overview`              | Warn below `overviewWords: 10` before Contents.                                                                                                                                                                                                                                                                                     |
+| `contents-separator`    | Warn when Contents descriptions mix separators in a tree.                                                                                                                                                                                                                                                                           |
+| `navigation`            | Error for explicit navigation drift. Nav-sync freshness stays strict; hand-authored/undeclared compare membership and order only (separators, labels, links and borrows are not compared), and absent optional meta/pages/nav skips comparison. Markdown skips it.                                                                  |
+| `commands`              | Error for missing literal contributor scripts; framework app targets try the app package first, then the repository root. Implicit pnpm shorthand also accepts installed package/workspace `.bin` entries. Explicit pnpm run/npm run stays script-only; unresolved context errors; echo scripts warn.                               |
+| `mermaid`               | Parse every real Mermaid fence using the pinned Mermaid parser. Invalid syntax errors.                                                                                                                                                                                                                                              |
+| `diagram-pairs`         | Diagram light/dark SVG siblings and both page references are required. Conventional diagram paths and explicit paired references participate; ordinary logos are not diagrams.                                                                                                                                                      |
+| `diagram-accessibility` | Mermaid missing `accTitle`/`accDescr` warns. SVGs require `role="img"`, nonempty title/desc. Rendered diagrams without page-visible explanatory text or an associated long description warn.                                                                                                                                        |
+| `diagram-freshness`     | Warn when changed Mermaid lacks both associated SVG changes; association follows the actual section/tab group. Missing usable Git comparison is explicitly unverified.                                                                                                                                                              |
+| `image-alt`             | Warn for empty, filename/slug-like or longer than `altMax: 155` image alt text.                                                                                                                                                                                                                                                     |
+| `provenance`            | Warn for planning/backlog/home paths, configured ticket/milestone patterns and ordinary links escaping the root. Legitimate reader docs remain visible.                                                                                                                                                                             |
 
 These are lint limits, distinct from authoring targets for concise pages and
 focused maps. `documentation.nonReaderPaths` uses the existing
@@ -103,8 +123,12 @@ focused maps. `documentation.nonReaderPaths` uses the existing
 
 Literal pnpm script and npm run examples in `contributing.md`/`.mdx` and
 `contributing/**` are checked against package manifests. Each code block starts
-at the repository root. Use executable `cd`, `-w`/`--workspace-root`, `--dir` or
-literal `--filter` selection to establish another context. Prose such as “from
+at the repository root. For a framework app target with its own `package.json`,
+it also starts at the app root, which is tried first: a script defined by the app
+resolves there, a script only the repository root defines still resolves, and a
+missing script names both manifests. Markdown targets use the repository root
+only. Use executable `cd`, `-w`/`--workspace-root`, `--dir` or literal `--filter`
+selection to establish another context. Prose such as “from
 the app directory” alone does not change it. Built-in package-manager commands
 and illustrative placeholders are recognized; commands are never run.
 

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

@@ -226,6 +226,7 @@ Key behavior:
 - 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`. Markdown and 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`
+- writes each link relative to the output file, so links resolve from where the manifest sits: a Fumadocs app-root `index.md` links `docs/guide.md` and `docs/index.md`, never itself. Whitespace, `#`, `?`, `%`, `&`, backslashes, parentheses and angle brackets in link paths are percent-encoded (UTF-8). Starting in 0.3.32; earlier manifests used docs-directory-relative links
 - should be freshness-checked against authored `docs/**/index.md` `## Contents` maps before treating it as navigation evidence
 - ordering: authored local Contents orders surviving direct entries in the hierarchical inventory; cross-directory links order the containing entry without duplicates. Child directory titles use index frontmatter, then H1, then slug. Remaining entries use index/directories/files/lexical fallback and are flagged `[unlisted in Contents]` when Contents exists. Missing Contents keeps fallback; malformed present Contents is an error
 - reports the derived docs directory in human output and as `docsDir` / `docsDirSource` under `--json`, alongside `excludes` — the effective exclusion list, `documentation.excludes`, applicable `documentation.nonReaderPaths`, then the `--exclude` flags, exactly as handed to the generator
@@ -296,10 +297,28 @@ site nav generation. Framework apps generate navigation as follows:
   generated `meta.json` files.
 
 Use `--check` in builds and CI. It computes the same navigation, writes
-nothing, and exits 1 when any generated file would change or, for Fumadocs,
-any page or folder is unlisted, naming each one (`stale` and `unlisted` in
+nothing, and exits 1 when any generated file is missing or would change or, for
+Fumadocs, any page or folder is unlisted. It names each one and separates
+missing files from differing ones (`stale`, `missing` and `unlisted` in
 `--json`). Fresh Fumadocs `prebuild` and MkDocs `docs:build` scripts run it with explicit app selection, preserving external `oat` versus source-workspace CLI commands and quoting paths with spaces. This repository's `apps/oat-docs` `prebuild` also runs it, so `pnpm build:docs` fails on stale navigation.
 
+Without `--target-dir`, the command uses the configured `documentation.root`,
+like `oat docs check`, and falls back to the current directory only when no root
+is configured. With `documentation.tooling: markdown` it exits 1 and says nav
+sync does not apply: Markdown Contents maps are the navigation, so validate
+them with `oat docs check`.
+
+The command reads `documentation.navOwner` when the target is the configured root:
+
+| Owner           | Writing run                                                                               | `--check`                                                                                                                                                                        |
+| --------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `nav-sync`      | Regenerates navigation.                                                                   | Strict: generated files must match.                                                                                                                                              |
+| `hand-authored` | Refuses with exit 1 and writes nothing. Edit the navigation directly or change the owner. | Membership and order only, as in [`oat docs check`](check.md#results-and-repair): every Contents page reachable, no entry naming a missing page, listed pages in Contents order. |
+| undeclared      | Regenerates navigation and warns you to declare an owner.                                 | Strict, with the same warning.                                                                                                                                                   |
+
+Fresh `oat docs init` framework scaffolds declare `nav-sync` and run their first
+sync directly, so they are unaffected.
+
 Shared `documentation.nonReaderPaths` uses the exclusion grammar above, relative to the configured content root. Navigation inventory, explicit Contents links, `--check` and manifests omit matches; excluded metadata is never cleaned or rewritten. An unrelated explicit target does not inherit the setting. `documentation.excludes` stays manifest-only. OAT Fumadocs source collections omit non-readers from rendering too; pinned MkDocs 1.4.2 omits them from nav/manifest but still renders their routes (no rendering-exclusion support).
 
 Fumadocs apps also regenerate the root markdown manifest with

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

@@ -495,7 +495,7 @@ work.
 ## Approval, IA records and restructuring
 
 Every analyze recommendation has a stable ID and `approval: explicit | default`.
-`apply all` covers only non-blocked default content repairs. Docs-package updates,
+`apply all` covers only non-blocked default content repairs. Docs tooling updates,
 restructure blocks and work outside Markdown scope require individual approval
 by ID; unattended runs skip explicit items even when their IDs were supplied,
 with reason `explicit_requires_interactive_approval`. Kickoff consent is not
@@ -538,18 +538,26 @@ canonical-source judgment; not-found is initially unverified. It cannot prove
 runtime behavior, registry membership or scenario correctness. Accepted IA,
 source citations and existing recommendation approval classes still govern.
 
-For framework apps, offline drift compares installed `@open-agent-toolkit/docs-*` packages to the
+For framework apps, offline drift compares installed `@open-agent-toolkit/docs-*` packages, and
+the app's own `@open-agent-toolkit/cli` when the app declares it, to the
 running CLI's bundled `public-package-versions.json`, never registry latest.
+The app-local CLI matters because its `oat docs generate-index` runs in
+`predev`/`prebuild`: a stale local CLI writes a different manifest than yours, so
+its drift joins the docs-package drift in the same tooling update.
 Older installed packages produce an explicit drift recommendation with the
 exact upgrade command. Equal versions are current. Newer packages are `ahead`: select
 or update the intended CLI installation before re-analysis, without a package
 downgrade command. Missing installations or bundle metadata and non-orderable
 versions are `unverified` and require manual verification; hoisted-only packages
 also remain unverified. Neither ahead nor unverified supplies a package-update
-command or authorizes an upgrade. Individual tooling approval permits only docs-app `@open-agent-toolkit/docs-*`
-dependency bumps (and resulting lockfile), the admonition/frontmatter conversions
-already supported by `oat docs migrate`, and build verification. App config,
-routes and package scripts remain manual required changes.
+command or authorizes an upgrade. Individual tooling approval permits only
+docs-app `@open-agent-toolkit/docs-*` dependency bumps, a bump of the app's own
+`@open-agent-toolkit/cli` in the dependency section it already uses (with the
+resulting lockfile), regenerating the app's generated manifest with that upgraded
+CLI, the admonition/frontmatter conversions already supported by
+`oat docs migrate`, and build verification. Other application dependencies,
+framework upgrades, app config, routes and package scripts remain manual
+required changes.
 
 ## Related docs
 

package/assets/docs/reference/cli-reference.md

@@ -237,7 +237,7 @@ Notable commands introduced in the current CLI surface:
 - `--local` — write to or remove from `.oat/config.local.json` (per-developer repo state, gitignored)
 - `--user` — write to or remove from `~/.oat/config.json` (user-level fallback, applies across all repos)
 
-When no flag is passed, the CLI picks a sensible default per key type: structural keys (`projects.root`, `documentation.*`, etc.) go to shared, state keys (`activeProject`, etc.) go to local, workflow preferences (`workflow.*`) go to local. Pass at most one flag — the command rejects multiple surface flags. `documentation.guidance` is shared by default and also accepts `--user`; use a path/URL string or a JSON string array, not a comma-separated list. `documentation.ia` accepts the [recorded IA JSON shape](configuration.md#shared-repo-config-you-will-touch-most-often) and `documentation.navOwner` accepts `nav-sync` or `hand-authored`; both are shared-only. Unset owner means undeclared, and Markdown ignores it. IA is an atomic value in get/dump, not a set of separately configurable child keys. `documentation.nonReaderPaths` is also shared-only and uses a comma-separated glob list on `set`, stored as an array; empty clears it. It omits matching reader paths from nav/check/manifest and supported Fumadocs collections, while `documentation.excludes` remains manifest-only. See [non-reader configuration](configuration.md#shared-repo-config-you-will-touch-most-often).
+When no flag is passed, the CLI picks a sensible default per key type: structural keys (`projects.root`, `documentation.*`, etc.) go to shared, state keys (`activeProject`, etc.) go to local, workflow preferences (`workflow.*`) go to local. Pass at most one flag — the command rejects multiple surface flags. `documentation.guidance` is shared by default and also accepts `--user`; use a path/URL string or a JSON string array, not a comma-separated list. `documentation.ia` accepts the [recorded IA JSON shape](configuration.md#shared-repo-config-you-will-touch-most-often) and `documentation.navOwner` accepts `nav-sync` or `hand-authored`; both are shared-only. Unset owner means undeclared, and Markdown ignores it. IA is an atomic value in get/dump, not a set of separately configurable child keys. `documentation.nonReaderPaths` is also shared-only and takes a comma-separated glob list or a JSON string array on `set` (other input starting with `[` or `{` is rejected), stored as an array; empty clears it. `documentation.excludes` accepts the same two forms. It omits matching reader paths from nav/check/manifest and supported Fumadocs collections, while `documentation.excludes` remains manifest-only. See [non-reader configuration](configuration.md#shared-repo-config-you-will-touch-most-often).
 
 Per-key restrictions apply identically to `set` and `unset`: structural keys can only be written at shared scope, most state keys can only be written at local scope (`activeIdea` is the exception — it accepts both local and user), and workflow preference keys accept any non-auto surface. Legacy `autoReviewAtCheckpoints` remains shared-only; prefer `workflow.autoReviewAtHillCheckpoints`.
 
@@ -247,7 +247,7 @@ Remote settings under `pjm.remote.*` remain shared-only. Removing a mutable leaf
 
 `unset` refuses six classes of key, each with exit code 1:
 
-- **Unknown keys**, including keys OAT reads but does not expose in the `oat config` catalog (`documentation.index`). These are not removable by any `oat config` command.
+- **Unknown keys**, meaning keys outside the `oat config` catalog. These are not removable by any `oat config` command.
 - **Lifecycle state** (`activeProject`, `lastPausedProject`) — cleared with `oat config set <key> ''` instead.
 - **Pack intent** (`tools.*`) — removed with `oat tools remove --pack <pack> --scope project`, which also removes the installed pack files. Clearing the intent alone would leave them behind.
 - **Aggregate read views** (`workflow.dispatchCeiling`, `workflow.dispatchCeiling.providers`) — these are assembled for `get` from the leaf keys and are not stored as such. Unset `workflow.dispatchCeiling.preset` or `workflow.dispatchCeiling.providers.<provider>` instead.

package/assets/docs/reference/config-and-local-state.md

@@ -131,7 +131,7 @@ Use `oat config` for repo runtime config inspection and supported key mutation.
 
 - `oat config get <key>` - read one resolved config value
 - `oat config set <key> <value>` - update a supported shared, repo-local, or user key according to per-key restrictions
-- `oat config unset <key>` - remove a supported key from one surface, with the same `--shared`/`--local`/`--user` flags and per-key restrictions as `set`. Pruning removes any parent object the removal empties, and the resolved value falls back to the next surface or the built-in default. A key the surface does not hold reports an already-unset outcome and exits 0; `--json` adds a `removed` boolean that distinguishes that no-op from a real removal. Five classes are refused with exit 1: unknown keys (including the uncatalogued `documentation.index`), lifecycle state (`activeProject`, `lastPausedProject`, cleared with `oat config set <key> ''`), pack intent (`tools.*`, removed with `oat tools remove --pack <pack> --scope project`), the aggregate read views `workflow.dispatchCeiling` and `workflow.dispatchCeiling.providers`, and environment-shadowed keys with nothing stored on the target surface. See [CLI Reference](cli-reference.md#oat-config-surface-flags) for the full contract
+- `oat config unset <key>` - remove a supported key from one surface, with the same `--shared`/`--local`/`--user` flags and per-key restrictions as `set`. Pruning removes any parent object the removal empties, and the resolved value falls back to the next surface or the built-in default. A key the surface does not hold reports an already-unset outcome and exits 0; `--json` adds a `removed` boolean that distinguishes that no-op from a real removal. Five classes are refused with exit 1: unknown keys, lifecycle state (`activeProject`, `lastPausedProject`, cleared with `oat config set <key> ''`), pack intent (`tools.*`, removed with `oat tools remove --pack <pack> --scope project`), the aggregate read views `workflow.dispatchCeiling` and `workflow.dispatchCeiling.providers`, and environment-shadowed keys with nothing stored on the target surface. See [CLI Reference](cli-reference.md#oat-config-surface-flags) for the full contract
 - `oat config list` - show the resolved command-surface values with source information
 - `oat config dump --json` - emit the full merged config payload with per-key source attribution, suitable for automation and debugging
 - `oat config describe` - list supported config surfaces and keys across shared repo, repo-local, user, and sync/provider config

package/assets/docs/reference/configuration.md

@@ -94,10 +94,10 @@ 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. With tooling `markdown`, root is the literal content directory (including nested `docs`) and `documentation.index` is authored `<root>/index.md`; Markdown adds no framework config. Framework roots retain app/source semantics. Use `oat docs init --framework markdown` or explicit `--adopt` for setup; optional manifests need external output and never change the authored index. See [Documentation path resolution](oat-directory-structure.md#documentation-path-resolution)
-- `documentation.ia` — shared repository-only mirror of the accepted authored IA. Set JSON with required `preset` and repo-relative `decision`, optional `tracks: [{path, principle}]`, and optional `verification: "triad" | "agent-only" | "none"`. The decision record plus Information architecture section in framework docs-app `AGENTS.md` or Markdown contributing page remain authoritative. Use `oat config set documentation.ia '{"preset":"Flat Small","decision":".oat/repo/reference/decisions/DR-example.md","verification":"none"}'`; unset removes the mirror only. Invalid shapes/paths are rejected; neither `--user` nor `--local` is supported.
+- `documentation.ia` — shared repository-only mirror of the accepted authored IA. Set JSON with required `preset` (one of the `oat docs init --ia-preset` IDs: `product-engineering-qa`, `consumer-maintainer`, `domain-engineering`, `task-type`, `toolkit-cli` or `flat-small`; the matching approved label, such as `Flat Small`, is accepted as an exact alias) and repo-relative `decision`, optional `tracks: [{path, principle}]`, and optional `verification: "triad" | "agent-only" | "none"`. The decision record plus Information architecture section in framework docs-app `AGENTS.md` or Markdown contributing page remain authoritative. Use `oat config set documentation.ia '{"preset":"flat-small","decision":".oat/repo/reference/decisions/DR-example.md","verification":"none"}'`; unset removes the mirror only. Invalid shapes, unknown presets and absolute, URL or `..` paths are rejected, both when set and when stored config is read: from 0.3.32 a stored unknown preset makes config-reading commands fail until repaired with `oat config set documentation.ia '<JSON>'` or `oat config unset documentation.ia --shared`; the CLI does not check that the decision file exists, and analyze reports a missing record as `ask_user`; neither `--user` nor `--local` is supported.
 - `documentation.navOwner` — shared `nav-sync | hand-authored`, independent of recorded IA, for Fumadocs/MkDocs only. Set with `oat config set documentation.navOwner hand-authored`. Absent is undeclared (`get --json` reports null/default), never implied nav-sync; analyze asks the operator and no automatic regeneration is authorized. Markdown ignores this field. Fresh Fumadocs/MkDocs init explicitly seeds nav-sync and generates navigation after scaffold/config succeeds. Existing apps are not regenerated through bootstrap; explicit nav-sync commands retain their behavior.
 - `documentation.guidance` — advisory Markdown IA source paths/URLs, as a string or ordered non-empty string array. Repo config overrides user config; explicit skill input overrides both. Absent values use the installed `authoring-docs` IA reference. Use `oat config set documentation.guidance ./docs/ia/index.md` or `oat config set documentation.guidance '["~/guidance/index.md","https://example.com/docs/index.md"]' --user`. Arrays retain order; commas in paths are literal. `--local` is unsupported. `get --json` reports `shared`, `user`, or `default` provenance; `unset` reveals the next tier. Only locators are stored, with unrelated config fields preserved. Sources stay read-only, external packs have `index.md` and `## Contents`, and local AGENTS/contributing rules remain authoritative. Conflicts become `ask_user`. See [IA selection](../docs-tooling/workflows.md#ia-selection-and-guidance).
-- `documentation.nonReaderPaths` — shared repository-only array of content-root-relative globs for drafts/templates. Set with `oat config set documentation.nonReaderPaths 'templates/,drafts/**'`; empty value clears and `unset` removes it. Entries are trimmed/de-duplicated; non-arrays, empty or non-string entries are rejected. Local/user writes are refused. The [bounded grammar](../docs-tooling/commands.md#exclusion-patterns) matches nav inventory, explicit Contents targets, nav checks and manifests only for the configured app/content root; excluded metadata is not rewritten. Fumadocs source collections also exclude rendering when wired through OAT source config. Pinned MkDocs 1.4.2 still renders excluded pages as routes; only nav/manifest exclusion is supported.
+- `documentation.nonReaderPaths` — shared repository-only array of content-root-relative globs for drafts/templates. Set with `oat config set documentation.nonReaderPaths 'templates/,drafts/**'` or a JSON string array such as `'["**/AGENTS.md"]'`; other JSON-looking input is rejected; empty value clears and `unset` removes it. Entries are trimmed/de-duplicated; non-arrays, empty or non-string entries are rejected. Local/user writes are refused. The [bounded grammar](../docs-tooling/commands.md#exclusion-patterns) matches nav inventory, explicit Contents targets, nav checks and manifests only for the configured app/content root; excluded metadata is not rewritten. Fumadocs source collections also exclude rendering when wired through OAT source config. Pinned MkDocs 1.4.2 still renders excluded pages as routes; only nav/manifest exclusion is supported.
 - `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.check` — shared checker policy: stable rule severities, named numeric thresholds, reason-bearing bounded path/rule exceptions, ticket/milestone regex patterns and optional diagram base ref. Set/get/dump/unset preserve and validate the object. See [Check Documentation](../docs-tooling/check.md#configure-narrow-policy) for exact fields/defaults and repair commands.
 - `documentation.requireForProjectCompletion` — whether docs sync is a completion gate

package/assets/docs/reference/docs-index-contract.md

@@ -73,6 +73,7 @@ Fumadocs generated behavior:
 - The inventory stays hierarchical. Each local Contents orders its surviving direct entries; a cross-directory link orders its containing direct entry without duplicating the page. Child directory titles come from their index frontmatter title, then H1, then slug, independently of nav labels.
 - Remaining entries use deterministic index/directories/files/lexical fallback and carry `[unlisted in Contents]` when a Contents map exists. With no Contents map the inventory keeps its fallback order; malformed present Contents reports the shared grammar errors.
 - Generated manifests should carry an autogen warning and are rewritten by `predev` / `prebuild`.
+- Manifest links are relative to the manifest file, so the app-root `index.md` links docs pages as `docs/<path>.md`.
 
 ## Fumadocs Nav Sync
 
@@ -89,7 +90,7 @@ Fumadocs generated behavior:
 - Existing files are compared by meaning, not bytes, so a second run with no docs changes writes nothing, even after a formatter rewrites the files.
 - `.md` and `.mdx` pages can both be listed; each appears in `pages` by its file name without the extension.
 
-`oat docs nav sync --check` computes the same result and writes nothing. It exits 1 when a `meta.json` file would change or a page or folder is unlisted, and names each one. In this app, `prebuild` runs it, so `pnpm build:docs` fails until the `## Contents` maps and the committed `meta.json` files agree.
+`oat docs nav sync --check` computes the same result and writes nothing. It exits 1 when a `meta.json` file is missing or would change, or a page or folder is unlisted, and names each one, listing missing files separately. In this app, `prebuild` runs it, so `pnpm build:docs` fails until the `## Contents` maps and the committed `meta.json` files agree.
 
 ## MkDocs Nav Sync
 
@@ -108,7 +109,7 @@ Shared `documentation.nonReaderPaths` declares drafts/templates outside the read
 
 Fumadocs collections also omit matching pages and metadata when `defineDocs` uses OAT's `docs` and `meta` source options with an explicit repository config path. The pinned MkDocs 1.4.2 has no configurable rendering exclusion: these pages leave navigation and manifests but still render as routes. This setting is not a way to keep private content out of a MkDocs site.
 
-Fresh Fumadocs/MkDocs init explicitly writes `documentation.navOwner: nav-sync` and generates navigation after scaffold/config succeeds. Their generated `prebuild` / `docs:build` scripts run `nav sync --check`. Existing hand-authored or undeclared surfaces are preserved through bootstrap and use analyze/apply to choose ownership; absence never implies permission to regenerate. Markdown has no sidebar or nav sync.
+Fresh Fumadocs/MkDocs init explicitly writes `documentation.navOwner: nav-sync` and generates navigation after scaffold/config succeeds. Their generated `prebuild` / `docs:build` scripts run `nav sync --check`. Existing hand-authored or undeclared surfaces are preserved through bootstrap and use analyze/apply to choose ownership; absence never implies permission to regenerate. With `hand-authored`, the writing `oat docs nav sync` refuses and `--check` compares membership and order only; an undeclared owner gets a warning to declare one. Markdown has no sidebar or nav sync.
 
 ## Generated-file boundaries
 

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

@@ -146,7 +146,7 @@ Current schema keys:
 | `archive.awsProfile`                                       | `string`                   | -                        | Optional AWS named profile forwarded as `AWS_PROFILE` to every `aws` invocation in archive flows (`oat-project-complete` S3 sync, `oat repo archive sync`). Overrides ambient shell `AWS_PROFILE` / `AWS_DEFAULT_PROFILE` when set.                                                                                                                                                                                                                                                                 |
 | `archive.awsRegion`                                        | `string`                   | -                        | Optional AWS region forwarded as `AWS_REGION` to every `aws` invocation in archive flows. Overrides ambient shell `AWS_REGION` / `AWS_DEFAULT_REGION` when set.                                                                                                                                                                                                                                                                                                                                     |
 
-Most `documentation.*` keys are managed via `oat config get/set` and are set automatically by `oat docs init`. One has no `oat config set` entry and is edited directly in `.oat/config.json`: `documentation.index`, which `oat docs init` still seeds for you.
+`documentation.*` keys are managed via `oat config get/set` and are set automatically by `oat docs init`, including `documentation.index`, which `oat docs generate-index` also updates for the Fumadocs manifest transition.
 The `git.defaultBranch` key is auto-detected during `oat init` and can be overridden via `oat config set git.defaultBranch <branch>`.
 Archive settings are managed via `oat config get/set`, and `oat config describe archive.s3Uri` (or the other archive keys) shows the lifecycle and ownership details from the CLI.
 Workflow gate objects are structured config and are managed with `oat gate`, not the scalar `oat config set` surface. See [Workflow Gates](../workflows/advanced/workflow-gates.md).

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.3.31",
-  "docs-config": "0.3.31",
-  "docs-theme": "0.3.31",
-  "docs-transforms": "0.3.31"
+  "cli": "0.3.33",
+  "docs-config": "0.3.33",
+  "docs-theme": "0.3.33",
+  "docs-transforms": "0.3.33"
 }

package/assets/skills/oat-agent-instructions-analyze/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: 1.12.4
+  version: 1.12.5
 ---
 
 # Agent Instructions Analysis
@@ -455,7 +455,7 @@ Use the `analysis` target:
 Follow the canonical loop exactly:
 
 1. Resolve `workflow.autoArtifactReview.analysis`; missing config means enabled, and only explicit `false` skips the loop.
-2. Resolve `oat_orchestration_retry_limit`; default to `2` if unavailable.
+2. Resolve the retry bound from `oat_orchestration_retry_limit` in the active OAT project's `state.md` frontmatter; it is not an `oat config` key. Default to `2` when no project is active or the value is absent or invalid.
 3. Dispatch `oat-reviewer` in structured mode via Tier 1 subagent when available, falling back to the same reviewer prompt inline when needed.
 4. Apply Critical and High fixes when they are local to the analysis artifact, companion bundle, and unambiguous.
 5. Offer Medium and Low fixes rather than applying them silently.

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

@@ -6,7 +6,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Bash(oat config:*), Bash(oat docs nav sync --check:*), Bash(oat docs check:*), Bash(oat docs literals:*), Bash(pnpm:*), Bash(bash:*), Bash(jq:*), Bash(node:*), Bash(command -v:*), Bash(sed:*), Bash(npm root -g:*), Bash(test:*), Bash(oat --version), Bash(mkdir:*), Bash(date:*), Bash(echo:*), Bash(cd:*), Bash(pwd:*), Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: '1.7.5'
+  version: '1.9.0'
 ---
 
 # Docs Analysis
@@ -323,7 +323,9 @@ In `full` mode, evaluate the whole docs surface.
 Read the authored IA decision and `## Information architecture` section in the
 docs-app AGENTS.md (Fumadocs/MkDocs) or contributing page (Markdown).
 `documentation.ia` is a repository-only mirror: compare preset, decision path,
-tracks/principles and verification overlay to those authored sources. The
+tracks/principles and verification overlay to those authored sources. A preset
+ID and its approved label (for example `flat-small` and Flat Small) name the
+same preset, not a contradiction. The
 authored record is authoritative; missing/broken records or contradictory
 mirrors become `ask_user` findings. No recorded IA means `ask_user` to choose
 and record one, not an inferred preset. Keep ordinary contract analysis useful
@@ -556,7 +558,10 @@ suppressions or automatic navigation ownership.
 
 If a generated root index or manifest exists:
 
-1. Compare generated entries with the authored `## Contents` graph.
+1. Compare generated entries with the authored `## Contents` graph. Current
+   manifests link relative to the manifest file (an app-root manifest links
+   `docs/<page>.md`); links relative to the docs directory instead mean an older
+   CLI wrote it, so cite the CLI that regenerates it rather than content drift.
 2. Flag generated output that is missing, ignored/local-only when local guidance
    expects a tracked artifact, stale, ordered differently from authored maps, or
    unclear because generator semantics are undocumented.
@@ -594,9 +599,14 @@ For a Fumadocs app with recorded `navOwner: nav-sync`, compare generated
 
 For `hand-authored` or undeclared Fumadocs navigation, compare current meta.json
 membership/order with Contents without assuming strict generator output; do not
-flag rest entries merely because they are hand-authored. Report missing reader
-routes and differences with local ownership evidence; recommend no automatic
-regeneration. For nav-sync-owned MkDocs, use the same explicit-target read-only
+flag rest entries merely because they are hand-authored. `oat docs check` runs
+this comparison for both: a Contents page must be reachable (listed, shown by a
+rest entry, borrowed by another folder or linked by URL), every pages entry must
+name an existing page or folder, and listed pages keep Contents order.
+Separators, labels, link items and borrowed pages are not compared. For
+`hand-authored`, `oat docs nav sync --check` uses the same comparison and the
+writing form refuses to run. Report missing reader routes and differences with
+local ownership evidence; recommend no automatic regeneration. For nav-sync-owned MkDocs, use the same explicit-target read-only
 `oat docs nav sync --check --target-dir <docs-app-dir>`.
 
 If `mkdocs.yml` exists:
@@ -616,18 +626,23 @@ record whether app migration is relevant only when evidence or user intent suppo
 
 For framework apps read their package.json and installed docs packages against
 the running CLI's bundled `assets/public-package-versions.json`, without network.
+The helper covers the `@open-agent-toolkit/docs-*` packages and, when the app
+declares it in any dependency section, the app-local `@open-agent-toolkit/cli`
+whose `oat docs generate-index` runs in `predev`/`prebuild`; a stale local CLI
+writes a different manifest than the running CLI.
 Run this skill's production helper after resolving this skill's own directory:
 
 ```bash
 node "$SKILL_DIR/scripts/package-drift.mjs" --app "<docs-app-dir>" --cli "$(command -v oat)"
 ```
 
-If a package-manager wrapper prevents locating the CLI root, discover the bundle
-from that invoked installation offline. Inspect `command -v oat` and, for a shell
-shim, read its `exec` lines or `cmd-shim-target` comment (for example,
-`sed -n '1,160p' "$(command -v oat)"`). Resolve a relative JavaScript target from
-the shim's directory; do not evaluate copied shell text. Locate that target's
-package root containing `package.json` named `@open-agent-toolkit/cli` and
+`--cli` follows a direct install to its package root. For a POSIX shell shim,
+such as a pnpm global `oat`, the helper reads the shim as text without executing
+it: the `# cmd-shim-target=` comment first, then relative `exec` targets resolved
+from the shim's real directory. If the helper still reports that it cannot
+locate the running CLI bundle (a wrapper it cannot parse), locate the invoked
+installation offline without evaluating wrapper text: find its JavaScript entry
+and that entry's package root containing `package.json` named `@open-agent-toolkit/cli` and
 `assets/public-package-versions.json`. `pnpm root -g` or `npm root -g` can help
 locate it, but newer pnpm installations may nest it in a hashed directory; use
 the actual shim target, never another checkout's bundle. Bind the inspected paths:
@@ -641,9 +656,14 @@ test "$(node "$OAT_INSTALLED_ENTRY" --version)" = "$(oat --version)" &&
   node "$SKILL_DIR/scripts/package-drift.mjs" --app "<docs-app-dir>" --versions "$OAT_INSTALLED_ROOT/assets/public-package-versions.json"
 ```
 
-Never substitute registry latest or this target repo's package version. Missing
-bundle metadata, missing installed packages, or non-orderable versions (including
-prereleases) mean unverified, never an upgrade. The helper compares stable numeric
+Never substitute registry latest or this target repo's package version. The
+helper finds installed packages with Node's lookup: the app's `node_modules`,
+then each ancestor's, so hoisted installs (pnpm `node-linker=hoisted`, npm or yarn
+workspaces) resolve. A docs directory without `package.json` (Markdown) returns
+`applicable: false` with exit 0. Missing bundle metadata, missing installed
+packages, or non-orderable versions (including prereleases) mean unverified,
+never an upgrade; each `unverified` row carries a `reason` (for example, not
+installed: run the app's install first, then re-run the helper). The helper compares stable numeric
 version components: older installed packages are `drift`; equal versions are
 `current`; newer installed packages are `ahead`, with no upgrade command. For
 `ahead`, report that the running CLI is stale and ask the operator to update or
@@ -651,12 +671,29 @@ select the intended CLI installation before re-analysis; do not recommend a docs
 package downgrade. `unverified` also has no package command and needs manual
 verification. Neither status authorizes a tooling update.
 
-The helper reports declared and installed versions, target versions and commands
-for orderable targets. If the app uses a different package manager, translate the
-command to its documented equivalent preserving package, exact target and
-dependency section. Cite the manifest, installed package path, bundle path and
-exact command. Report older-package drift as `tooling-update`, `approval: explicit`;
-describe unsupported scaffold repairs separately as `manual`. Markdown has no
+The helper reports declared and installed versions, the installed manifest path
+and target versions, and an `upgradeCommand` only for `drift`. The command pins
+the `packageManager` of the app or its nearest ancestor (`npx --yes pnpm@<version>`,
+which works without Corepack; `corepack pnpm@<version>` is equivalent where
+Corepack is installed) and adds
+`--ignore-workspace` for a nested app that the ancestor `pnpm-workspace.yaml`
+`packages` globs do not include (its own lockfile alone does not make it
+standalone). The output's `workspace` field reports `member`, `standalone`,
+`root` or `undetermined`; for `undetermined` (glob syntax the helper does not
+evaluate) the command omits `--ignore-workspace` and `reason` asks you to
+confirm membership with `pnpm -r ls` first. Run it as given: a global pnpm of another major can rewrite the app's
+`pnpm-workspace.yaml` settings and leave `node_modules` linked to a different
+store version (`ERR_PNPM_UNEXPECTED_STORE`); recover by reinstalling with the
+pinned version, not by switching managers. Without a `packageManager`, the
+command uses bare `pnpm`; confirm its version matches the lockfile before
+running it. When `packageManager` names another manager, the row has no command
+and its `reason` asks for the equivalent add command; translate it preserving
+package, exact target and dependency section. Cite the manifest, installed package path, bundle path and
+exact command. Report older docs-package drift and older app-local CLI drift
+together as one `tooling-update`, `approval: explicit`, listing each drifting
+package's exact command in its own dependency section; apply's approved tooling
+update bumps them and regenerates the manifest with the upgraded app-local CLI.
+Describe unsupported scaffold repairs separately as `manual`. Markdown has no
 app-package drift check. This helper reads only and never upgrades anything.
 
 ### Step 7: Severity-Rate Findings
@@ -672,9 +709,10 @@ Use these defaults:
 
 Give every recommendation a unique stable ID (`R-001`, etc.) and
 `approval: explicit | default`; preserve IDs through review and never reuse a
-retired ID for a different change. `explicit` covers docs-package updates,
-restructure blocks and anything outside the Markdown scope (including authored
-IA decision/config writes). `default` covers ordinary in-scope content repairs.
+retired ID for a different change. `explicit` covers tooling updates (docs
+packages and the app-local CLI), restructure blocks and anything outside the
+Markdown scope (including authored IA decision/config writes). `default` covers
+ordinary in-scope content repairs.
 Missing evidence, `omit` and `ask_user` remain independent blockers regardless
 of approval class. Capture exact targets and commands; an explicit class is not
 permission to perform unsupported work. Apply's one input is this artifact plus
@@ -723,7 +761,7 @@ Use the `analysis` target:
 Follow the canonical loop exactly:
 
 1. Resolve `workflow.autoArtifactReview.analysis`; missing config means enabled, and only explicit `false` skips the loop.
-2. Resolve `oat_orchestration_retry_limit`; default to `2` if unavailable.
+2. Resolve the retry bound from `oat_orchestration_retry_limit` in the active OAT project's `state.md` frontmatter; it is not an `oat config` key. Default to `2` when no project is active or the value is absent or invalid.
 3. Dispatch `oat-reviewer` in structured mode via Tier 1 subagent when available, falling back to the same reviewer prompt inline when needed.
 4. Apply Critical and High fixes when they are local to the analysis artifact and unambiguous.
 5. Offer Medium and Low fixes rather than applying them silently.

package/assets/skills/oat-docs-analyze/references/analysis-artifact-template.md

@@ -47,16 +47,19 @@ Do not invent missing audiences or choose an IA without approval.
 - Bundle metadata: {running CLI public-package-versions.json path or unverified}
 - Docs app manifest: {path; Markdown: not applicable}
 
-| Package                       | Declared / installed                | Bundled   | Status                                 | Exact upgrade command                                                          | Recommendation ID                                       |
-| ----------------------------- | ----------------------------------- | --------- | -------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------- |
-| {@open-agent-toolkit/docs-\*} | {range / actual version or missing} | {version} | {current / drift / ahead / unverified} | {drift only: helper upgrade command adapted to actual manager; otherwise none} | {drift only: R-NNN; approval: explicit; otherwise none} |
+| Package                                       | Declared / installed                | Bundled   | Status                                 | Exact upgrade command                                                          | Recommendation ID                                       |
+| --------------------------------------------- | ----------------------------------- | --------- | -------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------- |
+| {@open-agent-toolkit/docs-\* or declared cli} | {range / actual version or missing} | {version} | {current / drift / ahead / unverified} | {drift only: helper upgrade command adapted to actual manager; otherwise none} | {drift only: R-NNN; approval: explicit; otherwise none} |
 
 Only older installed packages (`drift`) receive a package-upgrade command and
-stable recommendation ID with `approval: explicit`. `current` needs no tooling
-recommendation, even if the helper emits a reinstall command. For `ahead`, select
+stable recommendation ID with `approval: explicit`. Docs-package drift and
+app-local `@open-agent-toolkit/cli` drift share one `tooling-update` ID, each row
+keeping its own dependency section in its command; apply then regenerates the
+manifest with the upgraded app-local CLI. `current` needs no tooling
+recommendation and has no command. For `ahead`, select
 or update the intended CLI installation, then re-analyze; do not recommend a docs
 package downgrade. `unverified` requires manual verification before a package
-recommendation.
+recommendation; record the helper's `reason` (for example, not installed).
 
 Unsupported app config/routes/scripts: {manual changes required; never automatic}.
 

package/assets/skills/oat-docs-analyze/references/quality-checklist.md

@@ -38,8 +38,8 @@ Use this checklist when evaluating a docs surface.
 
 - Opening code fences have language identifiers.
 - Shell command examples follow the repo's documented fence convention; default
-  to `sh` unless local guidance uses `bash` or the block requires Bash-only
-  syntax.
+  to `bash` unless the example is POSIX-only (`sh`) or local guidance requires
+  another fence.
 - Headings are non-empty.
 - Each authored page has at most one document-level H1 unless the file is an
   intentional imported README or generated/imported artifact.