@open-agent-toolkit/cli 0.3.32 → 0.3.33

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.3.32"
+  "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.
@@ -85,8 +105,8 @@ recursive tabs participate.
 | `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.                                                                                                          |
+| `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.                                                                                                                                        |
@@ -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

@@ -297,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/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

@@ -97,7 +97,7 @@ Common keys in `.oat/config.json`:
 - `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

@@ -90,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
 
@@ -109,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.32",
-  "docs-config": "0.3.32",
-  "docs-theme": "0.3.32",
-  "docs-transforms": "0.3.32"
+  "cli": "0.3.33",
+  "docs-config": "0.3.33",
+  "docs-theme": "0.3.33",
+  "docs-transforms": "0.3.33"
 }

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.8.0'
+  version: '1.9.0'
 ---
 
 # Docs Analysis
@@ -599,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:
@@ -651,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
@@ -661,10 +671,24 @@ 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
+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

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

@@ -56,10 +56,10 @@ 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, even if the helper emits a reinstall command. For `ahead`, select
+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}.