@open-agent-toolkit/cli 0.3.23 → 0.3.25

package/assets/skills/authoring-docs/references/page-types.md

@@ -98,6 +98,30 @@ Rules:
 - Include verification, rollback, and escalation.
 - Avoid long historical background before recovery steps.
 
+## Feature Guide
+
+Describe intended user behavior, the problem solved, prerequisites, boundaries
+and linked Engineering/QA counterparts when the IA declares them. Distinguish
+concept names from verified literal screen text; do not infer behavior from a UI.
+
+## Validation Matrix
+
+Specify scenarios, preconditions, actions and expected outcomes independently
+of implementation details. Link the canonical feature and only cite test IDs
+that exist. Keep duplicate or contradictory scenarios out of the matrix.
+
+## Solution
+
+Explain how supported capabilities combine to solve one end-to-end problem.
+State constraints, tradeoffs, integration steps and verification; link exact
+contracts rather than duplicating reference facts.
+
+## Decision Record
+
+Record an accepted choice with context, alternatives, reasoning, consequences
+and status. Link the authoritative decision surface when it lives elsewhere;
+keep planning and execution evidence out of reader docs.
+
 ## Mixed Pages
 
 Some pages legitimately mix types. A landing page can include orientation,
@@ -110,10 +134,14 @@ and keep everything else subordinate.
 
 ## Smell Test
 
-| If the Reader Asks              | They Need    | Do Not Give Them            |
-| ------------------------------- | ------------ | --------------------------- |
-| I am new. Walk me through this. | Tutorial     | Full API reference          |
-| How do I do X?                  | How-to guide | Architecture essay          |
-| What does this option mean?     | Reference    | A blog post                 |
-| Why does this behave this way?  | Explanation  | A command list              |
-| Production is broken. What now? | Runbook      | Historical background first |
+| If the Reader Asks                          | They Need         | Do Not Give Them             |
+| ------------------------------------------- | ----------------- | ---------------------------- |
+| I am new. Walk me through this.             | Tutorial          | Full API reference           |
+| How do I do X?                              | How-to guide      | Architecture essay           |
+| What does this option mean?                 | Reference         | A blog post                  |
+| Why does this behave this way?              | Explanation       | A command list               |
+| Production is broken. What now?             | Runbook           | Historical background first  |
+| What behavior should this feature provide?  | Feature guide     | Implementation internals     |
+| How do I verify that behavior?              | Validation matrix | Unverified test IDs          |
+| How do these capabilities solve my problem? | Solution          | Disconnected reference dumps |
+| Why was this choice accepted?               | Decision record   | A transient project plan     |

package/assets/skills/authoring-docs/references/review-rubric.md

@@ -53,18 +53,18 @@ Production runbooks should be especially strong on operational safety.
 Public-facing docs should be especially strong on examples, accuracy, and
 audience boundary.
 
-| Area                     | 0                           | 1                      | 2                           | 3                                                          |
-| ------------------------ | --------------------------- | ---------------------- | --------------------------- | ---------------------------------------------------------- |
-| Purpose                  | No clear reason page exists | Purpose is implied     | Purpose is stated           | Purpose, reader, and outcome are clear                     |
-| Accuracy                 | Incorrect or invented       | Partially accurate     | Mostly accurate             | Grounded and verified                                      |
-| Structure                | Hard to scan                | Some headings          | Clear sections              | Predictable IA and strong headings                         |
-| Task support             | Cannot complete task        | Can partially complete | Can complete with some gaps | Can complete safely with verification                      |
-| Reference quality        | Missing facts               | Facts scattered        | Most fields documented      | Types, defaults, constraints, examples, errors documented  |
-| Operational safety       | Risky or absent             | Mentions risk          | Includes basic verification | Includes verification, rollback, escalation, failure modes |
-| Agent usefulness         | Ambiguous                   | Some exact data        | Mostly explicit             | Exact commands, paths, constraints, and uncertainty        |
-| Maintainability          | Duplicated or stale         | Hard to update         | Mostly maintainable         | Clear source of truth and generated markers where needed   |
-| Public/internal boundary | Leaks or omits key context  | Boundary unclear       | Mostly appropriate          | Correct assumptions and safe content                       |
-| Links and navigation     | Broken or absent            | Sparse                 | Useful                      | Strong cross-links and clear next steps                    |
+| Area                     | 0                           | 1                      | 2                           | 3                                                                         |
+| ------------------------ | --------------------------- | ---------------------- | --------------------------- | ------------------------------------------------------------------------- |
+| Purpose                  | No clear reason page exists | Purpose is implied     | Purpose is stated           | Purpose, reader, and outcome are clear                                    |
+| Accuracy                 | Incorrect or invented       | Partially accurate     | Mostly accurate             | Grounded and verified                                                     |
+| Structure                | Hard to scan                | Some headings          | Clear sections              | Reader-first [IA method](information-architecture.md) and strong headings |
+| Task support             | Cannot complete task        | Can partially complete | Can complete with some gaps | Can complete safely with verification                                     |
+| Reference quality        | Missing facts               | Facts scattered        | Most fields documented      | Types, defaults, constraints, examples, errors documented                 |
+| Operational safety       | Risky or absent             | Mentions risk          | Includes basic verification | Includes verification, rollback, escalation, failure modes                |
+| Agent usefulness         | Ambiguous                   | Some exact data        | Mostly explicit             | Exact commands, paths, constraints, and uncertainty                       |
+| Maintainability          | Duplicated or stale         | Hard to update         | Mostly maintainable         | Clear source of truth and generated markers where needed                  |
+| Public/internal boundary | Leaks or omits key context  | Boundary unclear       | Mostly appropriate          | Correct assumptions and safe content                                      |
+| Links and navigation     | Broken or absent            | Sparse                 | Useful                      | Strong cross-links and clear next steps                                   |
 
 ## Minimum Acceptable Scores
 

package/assets/skills/authoring-docs/references/templates.md

@@ -547,3 +547,57 @@ docs/
 
 - <Explicitly out-of-scope docs>
 ```
+
+## IA Proposal
+
+Use for bootstrap or an existing-tree `--ia` analysis. This proposes structure;
+it neither persists an IA decision nor materializes a preset. Feature and QA
+validation page templates are not included; use the page-type guidance to
+plan their content.
+
+````markdown
+# IA Proposal: {surface}
+
+## Evidence and guidance
+
+- Resolved sources, in order: {path/URL, provenance: explicit/conversation/shared/user/builtin}
+- Local authority: {AGENTS/contributing paths and relevant rules}
+- Repo signals: {manifests, navigators, bin, routers, IaC, e2e, docs, units}
+- Readers and work contexts: {who must succeed at what}
+- Entry key per track: {task/domain/capability/unit/command/page type}
+- Page purposes: {one primary job per representative page}
+- Verification overlay: {triad/agent-only/none and evidence}
+- Size gate: {page count and amount of structure justified}
+- Canonical facts elsewhere and links to preserve: {paths/URLs}
+- Unresolved conflicts: {ask_user finding with source citations, or none}
+
+## Candidate A: {reader-facing name}
+
+Nearest preset: {approved label}. Choose when: {signals and tradeoffs}.
+
+```text
+{track-or-section}/
+  {page.md} — {page's one job}
+  {page.md} — {page's one job}
+{track-or-section}/
+  {page.md} — {page's one job}
+  {page.md} — {page's one job}
+  {page.md} — {page's one job}
+```
+
+Use a two-level tree and 5–8 representative page placements. For Flat Small,
+first-level labels are grouped headings in one index, not new directories.
+
+## Candidate B: {alternative reader-facing name}
+
+Nearest preset: {approved label}. Choose when: {different plausible signals}.
+
+{Second two-level tree with 5–8 representative page placements and page jobs.}
+
+## Recommendation and open decisions
+
+{Preferred candidate, evidence and tradeoffs. Ask only decision-changing
+questions. Record an explicit choice before replacement or a second app.
+Existing docs default to analyze → apply of approved recommendations.
+No private exemplar text, copied external contents or unapproved moves.}
+````

package/assets/skills/authoring-docs/references/workflow.md

@@ -80,7 +80,12 @@ Most docs serve one or more of these readers:
 - support engineer
 - AI agent making future changes
 
-Write pages for actual tasks, not org-chart abstractions.
+Map personas to tracks by work context: consumers and CLI/API users usually
+enter through tasks or contracts; maintainers through domains and operations;
+product stakeholders through behavior; independent QA through validation;
+agents through exact task inputs and checks. One person may use several tracks.
+Use the five axes in [Information Architecture](information-architecture.md)
+before naming a preset. Write pages for actual tasks, not org-chart abstractions.
 
 ## 5. Decide the Minimum Useful Set
 

package/assets/skills/authoring-docs/references/writing-style.md

@@ -93,7 +93,7 @@ Use notes for useful context, not ordinary tips.
 - Use one `#` heading per page.
 - Do not skip heading levels.
 - Use fenced code blocks with language identifiers.
-- Use `sh` for shell commands.
+- Use `bash` for shell commands unless the example is POSIX-only (`sh`) or local repository conventions require another fence.
 - Use `txt` for command output.
 - Do not include shell prompts unless the prompt itself matters.
 - Use angle brackets for placeholders, such as `<environment>`.

package/assets/skills/authoring-docs/scripts/resolve-guidance.mjs

@@ -0,0 +1,53 @@
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+
+// Select inputs only. The consuming skill reads Markdown and checks Contents,
+// local authority and conflicts; this helper never fetches or writes a source.
+const { values } = parseArgs({
+  options: {
+    builtin: { type: 'string' },
+    'ia-guidance': { type: 'string', multiple: true },
+    'conversation-guidance': { type: 'string', multiple: true },
+  },
+});
+const explicit = values['ia-guidance'];
+const conversation = values['conversation-guidance'];
+if (explicit && conversation) {
+  throw new Error(
+    'Use one explicit source list; reconcile argument/conversation disagreement with the user first.',
+  );
+}
+const input = JSON.parse(readFileSync(0, 'utf8'));
+if (input.status !== 'ok' || input.key !== 'documentation.guidance') {
+  throw new Error(
+    'Expected successful oat config get documentation.guidance --json output.',
+  );
+}
+let locations;
+let source;
+if (explicit || conversation) {
+  locations = explicit ?? conversation;
+  source = explicit ? 'explicit' : 'conversation';
+} else if (input.value !== null && input.value !== undefined) {
+  if (!['shared', 'user'].includes(input.source)) {
+    throw new Error(
+      `Unsupported documentation.guidance config source: ${input.source}`,
+    );
+  }
+  locations = Array.isArray(input.value) ? input.value : [input.value];
+  source = input.source;
+} else {
+  locations = [values.builtin];
+  source = 'builtin';
+}
+if (
+  !locations.length ||
+  locations.some((location) => typeof location !== 'string' || !location.trim())
+) {
+  throw new Error(
+    'Guidance requires non-empty path/URL strings (or --builtin for fallback).',
+  );
+}
+process.stdout.write(
+  `${JSON.stringify({ sources: locations.map((location) => ({ location: location.trim(), source })) }, null, 2)}\n`,
+);

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

@@ -1,11 +1,12 @@
 ---
 name: oat-docs-analyze
 description: Run when you need to evaluate documentation structure, navigation, and coverage against the OAT documentation contract. Produces a severity-rated analysis artifact for oat-docs-apply.
+argument-hint: '[target] [--ia] [--ia-guidance <path|url>]'
 disable-model-invocation: true
 user-invocable: true
-allowed-tools: Read, Write, Bash(git:*), Bash(oat config:*), Bash(oat docs nav sync --check:*), Bash(pnpm:*), Bash(bash:*), Bash(jq:*), Bash(mkdir:*), Bash(date:*), Bash(echo:*), Bash(cd:*), Bash(pwd:*), Glob, Grep, AskUserQuestion, Task
+allowed-tools: Read, Write, Bash(git:*), Bash(oat config:*), Bash(oat docs nav sync --check:*), Bash(pnpm:*), Bash(bash:*), Bash(jq:*), Bash(node:*), Bash(mkdir:*), Bash(date:*), Bash(echo:*), Bash(cd:*), Bash(pwd:*), Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: '1.6.3'
+  version: '1.7.1'
 ---
 
 # Docs Analysis
@@ -85,6 +86,39 @@ When executing this skill, provide lightweight progress feedback so the user can
 
 ## Process
 
+### Shared authoring method and optional IA proposal
+
+Independently probe each exact `authoring-docs/SKILL.md` in order:
+`${SKILL_DIR}/..` from the loaded skill (`SKILL_DIR` is the absolute directory
+containing that loaded `SKILL.md`), `${HOME}/.agents/skills`, then
+`<repo-root>/.agents/skills`. Bind the first matching `authoring-docs` directory
+once as `AUTHORING_DOCS_ROOT`; load `${AUTHORING_DOCS_ROOT}/SKILL.md` and use
+that same root for every authoring-docs reference and script, never ambient
+discovery. If none is found, name `authoring-docs`, stop this handoff, and give
+the intended-scope recovery command: `oat tools install docs --scope <user|project>`
+or `oat tools update --pack docs --scope <user|project>`.
+
+Always use its landing-page contract, section entries and one-purpose-per-page
+rule for the quality pass even without `--ia`. For IA work, read
+`${AUTHORING_DOCS_ROOT}/references/guidance-sources.md` and use the source-aware config-get
+interface/helper: explicit `--ia-guidance` or conversation → repo → user →
+built-in. Preserve selected source order and cite locators/provenance in the
+analysis artifact. External Markdown packs require `index.md` and `## Contents`;
+non-repo inputs stay read-only and private contents never enter the artifact.
+
+`--ia` is a skill argument, not a CLI docs command. It adds the shared IA Proposal
+to the **same analysis artifact and existing artifact-review loop**. Read manifests,
+UI navigators/journeys, CLI `bin`, routers, IaC, `e2e/`/`.maestro/`, existing docs
+and independent monorepo units. Ask only decision-changing questions about reader
+work contexts, independent verification, canonical facts and link survival.
+Use the five axes before presets and show two plausible two-level trees with
+5–8 representative page placements each, page jobs, nearest approved presets
+and tradeoffs. A UI alone does not justify Product/Engineering/QA; size chooses
+depth, not audience. For an existing tree respect AGENTS/contributing authority;
+conflicts are `ask_user`, with both source citations. Analyze remains read-only:
+propose `record-ia` or `restructure` recommendations for apply; never persist
+IA or materialize scaffolds from analysis.
+
 ### Step 0: Resolve Docs Target and Analysis Mode
 
 Determine the documentation root using explicit docs-app evidence before generic
@@ -267,8 +301,8 @@ For each evaluated page or directory:
    syntax intentionally shown inside inline code, fenced examples, or template
    snippets.
 4. Check Markdown hygiene: opening code fences need language identifiers; shell
-   examples should follow local fence conventions, defaulting to `sh` unless
-   local guidance uses `bash` or the block needs Bash-only syntax.
+   examples should follow local fence conventions, defaulting to `bash` unless
+   the example is POSIX-only (`sh`) or local guidance requires another fence.
 5. Flag empty headings, multiple document-level H1s outside intentional imported
    README contexts, overlong frontmatter descriptions when local guidance
    defines a limit, ellipsis-truncated descriptions, and README-copy metadata
@@ -284,6 +318,37 @@ For each evaluated page or directory:
 In `delta` mode, always evaluate changed docs files plus the nearest parent `index.md` pages.
 In `full` mode, evaluate the whole docs surface.
 
+### Information Architecture Fit
+
+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
+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
+while those recommendations are blocked.
+
+In the artifact's **Information Architecture Fit** section, cite whether the
+landing page routes each declared audience, all declared sections exist and are
+reachable, page reader/purpose matches placement, root breadth is usable, and an
+app's docs avoid merely mirroring implementation directories. Review coverage
+only for declared readers: Product features/journeys/screens/states; QA scenario
+tables with seeds and automation references; consumer first-success/task guides;
+agent entrypoints, canonical sources and verification commands. Do not demand
+these tracks from every repository or implement the later P24 source checks.
+
+Top-level IA misroutes a declared audience: `High` when the reader cannot find
+a normal first-success or required verification path; `Medium` when that path
+is reachable but its placement causes material detours/confusion. Cite the
+declared audience, route and concrete reader impact. This rule overrides Low
+organization polish; do not upgrade purely cosmetic differences.
+
+For framework apps read `documentation.navOwner` independently of IA. Missing
+means **undeclared**: issue `ask_user` to choose `nav-sync` or `hand-authored`,
+and run only read-only membership/order comparisons. Never assume nav sync owns
+existing navigation. Markdown ignores navOwner and never runs nav sync.
+
 ### Step 4: Verify Substantive Claims Against Repo Sources
 
 Add a dedicated accuracy verification pass between page-quality assessment and nav/drift checks.
@@ -405,8 +470,8 @@ If a generated root index or manifest exists:
    files, and representative links for each finding.
 5. Prefer source-of-truth fixes over generated-file edits.
 
-If the app is Fumadocs (a `source.config.ts` beside `docs/`), its sidebar comes from
-`docs/**/meta.json` files that `oat docs nav sync` generates from `## Contents`:
+For a Fumadocs app with recorded `navOwner: nav-sync`, compare generated
+`docs/**/meta.json` with authored `## Contents`:
 
 1. Flag a docs directory with an `index.md` but no `meta.json` as a missing
    generated artifact.
@@ -430,6 +495,13 @@ If the app is Fumadocs (a `source.config.ts` beside `docs/`), its sidebar comes
    1 when either exists. The skill grants only this `--check` form; plain
    `oat docs nav sync` writes files and is not part of analysis.
 
+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
+`oat docs nav sync --check --target-dir <docs-app-dir>`.
+
 If `mkdocs.yml` exists:
 
 1. Compare nav entries with the docs tree.
@@ -443,6 +515,53 @@ site nav generation or builds. Lack of `mkdocs.yml`, a generated manifest, or an
 app package is expected, not a migration finding. For other unconfigured surfaces,
 record whether app migration is relevant only when evidence or user intent supports it.
 
+### Offline docs-package drift
+
+For framework apps read their package.json and installed docs packages against
+the running CLI's bundled `assets/public-package-versions.json`, without network.
+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
+`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:
+
+```bash
+OAT_INSTALLED_ENTRY="<absolute JavaScript target from the invoked shim>"
+OAT_INSTALLED_ROOT="<that installed @open-agent-toolkit/cli package root>"
+# Both must equal the invoked oat version; stop if either differs.
+test "$(node "$OAT_INSTALLED_ENTRY" --version)" = "$(oat --version)" &&
+  test "$(node -p 'JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8")).version' "$OAT_INSTALLED_ROOT/package.json")" = "$(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
+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
+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
+app-package drift check. This helper reads only and never upgrades anything.
+
 ### Step 7: Severity-Rate Findings
 
 Use these defaults:
@@ -452,6 +571,19 @@ Use these defaults:
 - `Medium`: incomplete `## Contents`, `overview.md` still in use, plugin/contributor guidance gaps, moderate duplication
 - `Low`: polish, wording, or organization improvements
 
+### Recommendation handoff
+
+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.
+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
+a list of approved recommendation IDs. Blanket or unattended approval never
+covers explicit recommendations; apply reports skipped IDs with reasons.
+
 ### Step 8: Write Analysis Artifact
 
 Use `references/analysis-artifact-template.md`.
@@ -473,7 +605,8 @@ Populate the artifact with:
 - Accuracy verification verdicts for repo-checkable claims
 - Content opportunities for missing or thin docs coverage
 - Navigation/drift findings
-- Ordered recommendations
+- Information Architecture Fit and offline package drift
+- Ordered recommendations with stable IDs and approval classes
 - Exact evidence references for each finding and recommendation
 - Confidence for each recommendation
 - Progressive disclosure decisions (`inline`, `link_only`, `omit`, `ask_user`)

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

@@ -15,6 +15,51 @@ oat_analysis_commit: { commitHash }
 **Surface Type:** {mkdocs-app|oat-fumadocs-app|docs-tree|root-markdown}
 **Commit:** {short-hash}
 
+## IA guidance and proposal
+
+- Selected sources in order: {locator + explicit/conversation/shared/user/builtin provenance}
+- Resolved index entries: {entry paths/URLs; external Markdown has index.md + Contents}
+- Local authority: {AGENTS/contributing source citations}
+- Conflicts/unreadable sources: {ask_user with both citations, or none}
+- IA proposal: {when --ia, embed the shared authoring-docs IA Proposal template:
+  two two-level trees, 5–8 placements each, page jobs, nearest approved presets,
+  evidence and tradeoffs; otherwise not requested}
+
+Do not copy private guidance contents or persist an IA decision from this report.
+
+## Information Architecture Fit
+
+- Authored decision and Information architecture section: {paths/lines or missing}
+- Config mirror: {preset, decision, tracks/principles, verification; agrees/conflicts}
+- Missing IA / conflicting authority: {ask_user recommendation ID or none}
+- Sidebar owner: {nav-sync / hand-authored / undeclared; Markdown: ignored}
+- Undeclared framework owner: {ask_user recommendation ID or none}
+
+| Declared reader/track                                    | Landing route and section reachability | Placement/coverage evidence               | Reader impact                                                  | Severity              |
+| -------------------------------------------------------- | -------------------------------------- | ----------------------------------------- | -------------------------------------------------------------- | --------------------- |
+| {Product / QA / consumer / agent / other declared track} | {exact links}                          | {sources; page purpose; missing coverage} | {blocked first success/verification, material detour, or none} | {High / Medium / N/A} |
+
+Assess root breadth and implementation-directory mirroring using reader evidence.
+Do not invent missing audiences or choose an IA without approval.
+
+## Offline Package Drift
+
+- 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} |
+
+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
+or update the intended CLI installation, then re-analyze; do not recommend a docs
+package downgrade. `unverified` requires manual verification before a package
+recommendation.
+
+Unsupported app config/routes/scripts: {manual changes required; never automatic}.
+
 ## Summary
 
 - **Files evaluated:** {N}
@@ -258,14 +303,18 @@ canonical docs/config/examples.
 
 1. **{Action}** — {rationale}
    - Target: `{path}`
-   - Action Type: {create / update / move / scaffold / sync-nav}
+   - ID: {R-NNN; unique and stable}
+   - approval: {explicit | default}
+   - Action Type: {create / update / move / scaffold / sync-nav / record-ia / restructure / tooling-update / manual}
    - Evidence: {exact refs}
    - Confidence: {high | medium | low}
    - Disclosure: {inline | link_only | omit | ask_user}
    - Link Targets: {path or URL / N/A}
 2. **{Action}** — {rationale}
    - Target: `{path}`
-   - Action Type: {create / update / move / scaffold / sync-nav}
+   - ID: {R-NNN; unique and stable}
+   - approval: {explicit | default}
+   - Action Type: {create / update / move / scaffold / sync-nav / record-ia / restructure / tooling-update / manual}
    - Evidence: {exact refs}
    - Confidence: {high | medium | low}
    - Disclosure: {inline | link_only | omit | ask_user}
@@ -274,6 +323,9 @@ canonical docs/config/examples.
 
 ## Apply Contract
 
+- `oat-docs-apply` input is this artifact path plus approved recommendation IDs.
+- Every recommendation has a unique stable ID and approval: explicit | default.
+- Explicit items need individual approval by ID; blanket/unattended approval skips them and reports the reason.
 - `oat-docs-apply` may only implement recommendations backed by evidence in this artifact.
 - Findings based on contradicted claims must be resolved against cited repo sources before `oat-docs-apply` acts on them.
 - Generated artifacts must not be hand-edited by `oat-docs-apply`. If a

package/assets/skills/oat-docs-analyze/scripts/package-drift.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+// Read-only, offline comparison used by oat-docs-analyze. No package resolution or install.
+import { readFile, realpath } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+
+const shellQuote = (value) =>
+  `'${value.replaceAll("'", String.fromCharCode(39, 92, 39, 39))}'`;
+
+async function versionsForCli(executable) {
+  if (!executable)
+    throw new Error(
+      'Provide --cli with the installed oat executable or --versions with its bundled public-package-versions.json.',
+    );
+  let directory = dirname(await realpath(executable));
+  for (;;) {
+    try {
+      const pkg = JSON.parse(
+        await readFile(join(directory, 'package.json'), 'utf8'),
+      );
+      if (pkg.name === '@open-agent-toolkit/cli')
+        return join(directory, 'assets/public-package-versions.json');
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+    const parent = dirname(directory);
+    if (parent === directory)
+      throw new Error(
+        'Cannot locate the running CLI bundle through this wrapper; supply --versions from that installed CLI.',
+      );
+    directory = parent;
+  }
+}
+
+try {
+  const { values } = parseArgs({
+    options: {
+      app: { type: 'string' },
+      versions: { type: 'string' },
+      cli: { type: 'string' },
+    },
+  });
+  if (!values.app) throw new Error('Required: --app <docs-app-directory>.');
+  const versionsPath = resolve(
+    values.versions ?? (await versionsForCli(values.cli)),
+  );
+  const versions = JSON.parse(await readFile(versionsPath, 'utf8'));
+  const appPath = resolve(values.app);
+  const manifest = JSON.parse(
+    await readFile(join(appPath, 'package.json'), 'utf8'),
+  );
+  const packages = [];
+  for (const section of [
+    'dependencies',
+    'devDependencies',
+    'optionalDependencies',
+  ]) {
+    for (const [name, declared] of Object.entries(manifest[section] ?? {})) {
+      if (
+        ![
+          '@open-agent-toolkit/docs-config',
+          '@open-agent-toolkit/docs-theme',
+          '@open-agent-toolkit/docs-transforms',
+        ].includes(name)
+      )
+        continue;
+      const bundled = versions[name.slice('@open-agent-toolkit/'.length)];
+      if (
+        typeof bundled !== 'string' ||
+        !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(bundled)
+      )
+        throw new Error(`Missing/invalid bundled version for ${name}.`);
+      // Report installed package bytes when available, not just a declared range.
+      let installed = null;
+      try {
+        const installedManifest = JSON.parse(
+          await readFile(
+            join(appPath, 'node_modules', name, 'package.json'),
+            'utf8',
+          ),
+        );
+        if (typeof installedManifest.version !== 'string')
+          throw new Error(`Invalid installed version for ${name}.`);
+        installed = installedManifest.version;
+      } catch (error) {
+        if (error.code !== 'ENOENT') throw error;
+      }
+      // Only stable numeric releases are orderable here; prereleases and other
+      // package-manager version forms need manual verification, never an upgrade.
+      const stable = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+      let status = 'unverified';
+      if (
+        installed !== null &&
+        stable.test(installed) &&
+        stable.test(bundled)
+      ) {
+        const left = installed.split('.').map(BigInt);
+        const right = bundled.split('.').map(BigInt);
+        const differing = left.findIndex(
+          (part, index) => part !== right[index],
+        );
+        status =
+          differing === -1
+            ? 'current'
+            : left[differing] < right[differing]
+              ? 'drift'
+              : 'ahead';
+      }
+      packages.push({
+        name,
+        section,
+        declared,
+        installed,
+        bundled,
+        status,
+        upgradeCommand:
+          status === 'drift' || status === 'current'
+            ? `pnpm --dir ${shellQuote(appPath)} add${section === 'devDependencies' ? ' --save-dev' : section === 'optionalDependencies' ? ' --save-optional' : ''} ${name}@${bundled}`
+            : null,
+      });
+    }
+  }
+  process.stdout.write(
+    `${JSON.stringify({ versionsPath, appPath, packages }, null, 2)}\n`,
+  );
+} catch (error) {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+}