@open-agent-toolkit/cli 0.3.22 → 0.3.24

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

@@ -6,7 +6,7 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.0.6
+  version: 1.0.7
 ---
 
 # OAT Docs
@@ -89,29 +89,15 @@ Read the user's question from `$ARGUMENTS`. If no question was provided or the q
 
 > "What would you like to know about OAT? I can help with workflows, CLI commands, skill authoring, configuration, project lifecycle, and more."
 
-Classify the question into one or more topic areas to guide the search:
-
-| Topic Area       | Docs Path                                                       | Key Content                                  |
-| ---------------- | --------------------------------------------------------------- | -------------------------------------------- |
-| Getting started  | `getting-started/quickstart.md`, `getting-started/bootstrap.md` | Installation, first project setup            |
-| Concepts         | `getting-started/concepts.md`                                   | Core OAT concepts and terminology            |
-| CLI commands     | `reference/cli-reference.md`                                    | Full CLI command reference                   |
-| Tool packs       | `getting-started/tool-packs.md`                                 | Installing and managing skill packs          |
-| Skills           | `contributing/skills.md`                                        | Skill authoring, SKILL.md format             |
-| Workflows        | `workflows/projects/`                                           | Project lifecycle, state machine, artifacts  |
-| Ideas            | `workflows/ideas/`                                              | Idea capture and brainstorming               |
-| Provider sync    | `provider-sync/`                                                | Multi-provider sync, config, commands        |
-| Documentation    | `docs-tooling/`                                                 | Docs analysis and apply workflows            |
-| Contributing     | `contributing/`                                                 | Code contributions, design principles, hooks |
-| File locations   | `reference/file-locations.md`                                   | Where OAT puts things                        |
-| Directory layout | `reference/oat-directory-structure.md`                          | `.oat/` and `.agents/` structure             |
-| Troubleshooting  | `reference/troubleshooting.md`                                  | Common issues and fixes                      |
+Read `DOCS_ROOT/index.md` and its `## Contents` section. Derive a temporary topic map from the installed labels, summaries, and link targets; do not assume OAT's repository layout or a fixed set of topic paths. Choose the entries that match the question and descend through their authored `index.md` Contents maps when needed. Resolve each link relative to its containing file and verify it exists before reading it.
+
+If the installed index has no usable Contents or a linked target is missing, report that specific stale or incomplete installation. Search within `DOCS_ROOT` for the requested terms to find existing evidence, and recommend updating the installed docs when appropriate. Never invent a replacement path or fall back to the repository.
 
 ### Step 3: Search and Read Documentation
 
 Based on the topic classification:
 
-1. **Read the most relevant docs file(s)** — start with the primary match from the topic table. All paths are relative to `DOCS_ROOT` (`~/.oat/docs/`).
+1. **Read the most relevant docs file(s)** — start with the primary match from the topic map derived in Step 2. All paths are relative to `DOCS_ROOT` (`~/.oat/docs/`).
 2. **Search for specific terms** — if the question mentions specific concepts, commands, or features, use Grep to find mentions across `~/.oat/docs/`.
 3. **Follow cross-references** — if the primary doc references other pages, read those for complete context.
 4. **Check the index** — read the `index.md` of relevant directories to discover additional relevant pages.
@@ -143,7 +129,7 @@ Frame these as suggestions, not automatic actions. Let the user decide.
 ```
 Based on the docs, here's how OAT project workflows work: [answer]
 
-You can read more in `workflows/projects/lifecycle.md`.
+Cite the installed workflow page discovered through Contents.
 
 Would you like me to:
 - Start a new project? (I'd invoke oat-project-lite for single-sitting work, oat-project-brief for one delivery planned as a Project Brief, oat-project-goal for an outcome delivered over several milestones, or oat-project-quick-start for a larger quick workflow)
@@ -190,7 +176,7 @@ Both create a project directory under your projects root
 state.md, plan.md, and implementation.md; quick and spec-driven modes also use
 discovery.md.
 
-See: workflows/projects/lifecycle.md, getting-started/quickstart.md
+See: the actual installed workflow and getting-started pages found through Contents.
 
 Would you like me to create a project for you?
 ```
@@ -203,20 +189,20 @@ Would you like me to create a project for you?
 
 ```
 Tool packs are bundles of related OAT skills that you install together.
-There are four packs:
+Describe the packs listed by the installed tool-pack documentation, for example:
 
-- **core** — Diagnostics and docs skills (oat-doctor, oat-docs).
-  Always installed at user level. 2 skills.
+- **core** — Diagnostics and docs skills.
+  Read the installed docs for scope and current membership.
 - **workflows** — Project lifecycle skills (discover, plan, implement,
-  review, PR). 26 skills total.
-- **ideas** — Brainstorming and idea capture skills. 4 skills.
+  review, PR).
+- **ideas** — Brainstorming and idea capture skills.
 - **utility** — Cross-cutting tools (docs analysis, code review,
-  skill creation). 9 skills.
+  skill creation).
 
 Install with: oat init tools
 Manage with: oat tools list, oat tools update, oat tools outdated
 
-See: getting-started/tool-packs.md
+See: the installed tool-pack page discovered through Contents.
 
 Would you like me to check which packs you have installed? (I'd run /oat-doctor --summary)
 ```

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 docs nav sync --check:*), 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.2'
+  version: '1.7.0'
 ---
 
 # Docs Analysis
@@ -85,6 +86,38 @@ 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. Propose only: no IA
+persistence, restructure action or scaffold materialization in this stage.
+
 ### Step 0: Resolve Docs Target and Analysis Mode
 
 Determine the documentation root using explicit docs-app evidence before generic
@@ -162,6 +195,8 @@ Capture the evidence sources that will justify later findings and recommendation
 - existing `index.md` trees and repeated directory patterns
 - exact missing or stale paths, commands, and page references
 
+For framework apps, also read [Legacy scaffold checks](references/legacy-scaffold-checks.md). Apply those checks to the actual installed app, cite the observed file and source contract, and report discrepancies in Findings and Recommendations. These are read-only checks, not bootstrap post-patches. Do not change app-shell configuration during analysis or assume docs-apply can edit it; identify the manual upgrade needed when outside apply's current scope.
+
 Do **not** infer docs structure conventions from a tiny sample of pages when the broader
 tree or config disagrees.
 
@@ -265,8 +300,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

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

@@ -15,6 +15,18 @@ 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.
+
 ## Summary
 
 - **Files evaluated:** {N}

package/assets/skills/oat-docs-analyze/references/legacy-scaffold-checks.md

@@ -0,0 +1,16 @@
+# Legacy scaffold checks
+
+Evaluate existing framework apps against the current contracts below. A match produces an evidence-backed finding in the analysis artifact, never an automatic rewrite. Cite the actual app path and line, the missing contract, confidence and a specific repair. Respect intentional user customization; when intent is unclear, use `ask_user`.
+
+| Observed older shape                                                                                                                             | Finding and repair                                                                                                                                                                                                                                                                                                                                                                                | Contract source                                                             |
+| ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| Fumadocs `next.config.js` replaces `createDocsConfig` with `createMDX()({ reactStrictMode: true, turbopack: { root: __dirname } })`              | High: static-export settings are missing and `__dirname` is invalid in ESM. Recommend a manual app-config upgrade to `createDocsConfig({ basePath, turbopack: { root: dirname(fileURLToPath(import.meta.url)) } })`, preserving `output: 'export'`, `trailingSlash`, `images.unoptimized`, base path and client environment. Verify the installed docs-config supports forwarding the root first. | `@open-agent-toolkit/docs-config` factory and the current Fumadocs template |
+| Layout lacks Next `metadata`, or site title differs between branding, metadata and authored headings                                             | Medium: site identity or document metadata is inconsistent. Report exact mismatches; titles belong in layout metadata and branding, not `createDocsConfig`.                                                                                                                                                                                                                                       | Fumadocs layout template and Next metadata export                           |
+| Getting Started has an empty description, bare commands with no working directory, or claims lint runs when package scripts disable it           | Medium: setup guidance disagrees with package scripts or page metadata. Recommend corrected prose backed by the actual scripts.                                                                                                                                                                                                                                                                   | Rendered scaffold package scripts and page frontmatter                      |
+| Node prerequisite is a fixed old major or tells readers to guess from repo pins                                                                  | Medium: compare `.nvmrc` first, then root `package.json` `engines.node`; quote the detected requirement. When neither exists, disclose the CLI minimum rather than claiming a repo pin.                                                                                                                                                                                                           | Repository Node pin and current scaffold renderer                           |
+| Authored `docs/index.md` says it is generated, or contributing lacks the generated-files boundary                                                | Medium: distinguish authored `docs/index.md` from the generated app-root manifest. Document committed `docs/**/meta.json` and `oat docs nav sync` separately.                                                                                                                                                                                                                                     | `oat docs generate-index` and `oat docs nav sync`                           |
+| Contents links omit `.md` despite real Markdown targets                                                                                          | Medium: recommend `.md`-suffixed source links, which the build transforms into routes.                                                                                                                                                                                                                                                                                                            | Authored Contents contract and docs-transforms links plugin                 |
+| Contributing duplicates agent runtime rules rather than pointing to app-root `AGENTS.md`                                                         | Low: recommend consolidating runtime instructions into the existing agent guidance after approval; preserve custom rules.                                                                                                                                                                                                                                                                         | Docs-app guidance and contributing audience boundary                        |
+| MkDocs setup says `setup-docs.sh` creates a virtual environment, config calls `tooling` an object, or index points at an assumed `docs/index.md` | Medium: verify the actual script and `.oat/config.json`. The scaffold installs with the selected Python, uses a framework string, and seeds index/config as `mkdocs.yml`.                                                                                                                                                                                                                         | MkDocs setup script, documentation schema and scaffold config               |
+
+A user-owned dynamic app may intentionally omit static export. Do not apply a static-export finding to it without evidence that static output is required. Likewise, verify commands and filenames against the target repository; these patterns identify discrepancies, not authority to overwrite customization.

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

@@ -3,9 +3,9 @@ name: oat-docs-apply
 description: Run when you have a docs analysis artifact and want to generate or update documentation structure and content. Creates a branch, applies approved changes, and optionally opens a PR.
 disable-model-invocation: true
 user-invocable: true
-allowed-tools: Read, Write, Edit, Bash(git:*), Bash(gh:*), Glob, Grep, AskUserQuestion
+allowed-tools: Read, Write, Edit, Bash(git:*), Bash(gh:*), Bash(oat:*), Bash(pnpm:*), Bash(bash:*), Bash(jq:*), Bash(mkdir:*), Bash(date:*), Bash(echo:*), Bash(cd:*), Bash(pwd:*), Glob, Grep, AskUserQuestion
 metadata:
-  version: '1.4.3'
+  version: '1.4.5'
 ---
 
 # Docs Apply
@@ -200,6 +200,24 @@ If branch creation fails because of unrelated local changes, ask the user to res
 
 ### Step 4: Apply Approved Changes
 
+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>`.
+
+Before content actions, use its page-purpose, landing, placement and five-axis IA
+method within the approved recommendation scope. Carry the analysis artifact's ordered guidance
+locators/provenance into the apply plan; do not silently re-resolve different
+sources. Verify cited inputs still exist and remain read-only outside the repo.
+Local AGENTS/contributing rules stay authoritative; a conflict is `ask_user`
+and blocks that recommendation pending a fresh analysis/user decision. Cite
+sources without copying private contents. This hook adds no restructure action.
+
 Before the first approved write, initialize `OWNED_OUTPUT_FILES=()`. Append
 each exact successfully created, modified or removed path at that write,
 including both names of a rename and any generated navigation/index file this

package/assets/skills/oat-docs-apply/references/apply-plan-template.md

@@ -12,6 +12,15 @@ oat_docs_target: { docs-target-path }
 **Source Analysis:** `{analysis-artifact-path}`
 **Docs Target:** `{docs-target-path}`
 
+## Guidance provenance
+
+- Analysis-selected IA sources, in order: {locators + provenance}
+- Local authority: {AGENTS/contributing citations}
+- Read-only sources verified: {resolved entries or blocked recommendation IDs}
+- Conflicts: {ask_user disposition or none}
+
+Keep the analysis selection; do not copy private contents or invent missing evidence.
+
 ## Instructions
 
 Review the full recommendation set first, then choose a review mode:

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

@@ -1,12 +1,12 @@
 ---
 name: oat-docs-authoring
 description: Use when authoring or restructuring targeted content inside an existing OAT Markdown surface or OAT/Fumadocs docs app. Preserves OAT docs navigation, generated indexes, and validation boundaries.
-argument-hint: '[docs task or target path]'
+argument-hint: '[docs task or target path] [--ia-guidance <path|url>]'
 disable-model-invocation: false
-allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 user-invocable: true
 metadata:
-  version: '1.1.2'
+  version: '1.2.0'
 ---
 
 # OAT Docs Authoring
@@ -14,9 +14,8 @@ metadata:
 Use this skill for targeted documentation authoring and small structural edits
 inside an existing OAT Markdown surface or OAT/Fumadocs docs app.
 
-This is a thin wrapper over `authoring-docs`. Load `authoring-docs` for
-universal evidence gathering, page-type selection, writing style, templates,
-and review standards. Keep this wrapper focused on OAT Markdown/Fumadocs placement,
+This is a thin wrapper over `authoring-docs` for universal evidence gathering,
+page-type selection, writing style, templates, and review standards. Keep this wrapper focused on OAT Markdown/Fumadocs placement,
 navigation, generated artifacts, validation, and lifecycle boundaries.
 
 ## Prerequisites
@@ -111,9 +110,22 @@ Use `references/docs-root-resolution.md` before assuming any path. OAT docs apps
 commonly live outside `apps/oat-docs`, and `.oat/config.json` may describe the
 generated root index separately from the authored docs root.
 
-If the request needs universal documentation standards, load `authoring-docs`
-and use its reference map for evidence gathering, page type, writing style,
-templates, and review rubric.
+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>`.
+
+Use the bound skill's reference map for evidence gathering, page type, writing
+style, templates and review rubric. For IA work use its five-axis method and
+`${AUTHORING_DOCS_ROOT}/references/guidance-sources.md`: explicit `--ia-guidance` or
+conversation → repo config → user config → built-in. Cite ordered source
+locators/provenance in the handoff; respect AGENTS/contributing authority,
+keep non-repo sources read-only and report conflicts as `ask_user`.
 
 ### Step 2: Inspect Evidence and Local Maps
 

package/assets/skills/oat-docs-authoring/references/lifecycle-boundaries.md

@@ -42,8 +42,7 @@ Stop and reroute when you notice:
 ## Migration Pointer
 
 Full MkDocs-to-OAT-Fumadocs migration is not bootstrap and is not targeted
-authoring. Use the standalone `mkdocs-to-oat-fumadocs-refactor-guide.md` handoff
-when available, and keep the migration in an OAT project or explicit migration
+authoring. Use the bundled [MkDocs-to-OAT-Fumadocs migration guide](mkdocs-to-oat-fumadocs-refactor-guide.md), and keep the migration in an OAT project or explicit migration
 branch with owner-review items for unverifiable claims.
 
 For migration-sensitive follow-up after the migration workflow has created a

package/assets/skills/oat-docs-authoring/references/mkdocs-to-oat-fumadocs-refactor-guide.md

@@ -0,0 +1,73 @@
+# MkDocs to OAT/Fumadocs migration guide
+
+Use this standalone handoff for an explicitly approved migration of an existing MkDocs site. Bootstrap creates an app; targeted authoring edits content; neither performs a full migration. Keep migration work in an OAT project or an explicit migration branch, with the agreed scope and owner recorded before changes.
+
+This guide is reconstructed from current OAT CLI, template and authoring contracts. The older project-local handoff mentioned in OAT's docs-authoring project summary was unavailable; this is not a copy of that historical document.
+
+## Preflight: inventory before mutation
+
+1. Read repository and docs-local instructions, `mkdocs.yml`, `.oat/config.json`, Python dependency files, docs package scripts and deployment workflows. Resolve the actual content root, published URL/base path and build output; do not assume `docs/` or GitHub Pages.
+2. Inventory every source page, attachment, image, local link, anchor, nav entry and public URL. Record pages outside nav too. Keep a before/after mapping for every source path and URL; never silently drop an unlisted page.
+3. Inventory MkDocs-specific features: admonitions, tabs, includes/macros, plugin-generated pages, API generation, Mermaid, custom assets/theme, search and redirects. Distinguish supported conversion from manual work and unsupported features.
+4. Find claims requiring code/config evidence, confidential material, unresolved product behavior and owner-only knowledge. Record owner-review items rather than guessing or publishing uncertain claims.
+5. Discover validation commands and required runtimes from scripts, CI and contributor instructions. Establish a baseline with exact commands and exit codes, including existing failures. Agree on the target app location, dependency policy, URL preservation strategy and deployment change with the user.
+
+Produce an inventory and proposed migration scope for approval. Do not overwrite the MkDocs app, clear its configuration, delete Python tooling or switch deployment as a side effect of preparing a proposal.
+
+## Phase 1: create the approved target app
+
+Use `oat docs init --help` to inspect installed capabilities. Scaffold Fumadocs into an empty, approved destination with `--framework fumadocs`, a package/app name, site name, description and target directory. Bootstrap can guide this step, but creating a second app does not imply support for two active `documentation` entries: the current config describes one surface. Explicitly agree when the configured docs root will switch, and preserve the old config for rollback.
+
+Read the rendered package scripts and configuration. The current Fumadocs template uses Next static export, trailing slashes and unoptimized images through `createDocsConfig`. For nested-standalone repos only, it forwards an ESM-safe app directory as `turbopack.root`; monorepo and single-package scaffolds use Next.js root discovery. Preserve the site's base path and `NEXT_PUBLIC_BASE_PATH`; set site identity through layout metadata and `DocsLayout` branding, not factory title options.
+
+Install using the repository's package-manager conventions. Keep dependency or workspace changes visible in the migration diff. Do not delete the old site yet.
+
+## Phase 2: migrate content without losing source
+
+Copy approved content and assets into the target content root, retaining the source until parity is verified. Use the inventory to account for every file.
+
+`oat docs migrate` converts supported MkDocs admonitions and injects missing frontmatter in `.md` files. It is a dry run by default; `--apply` writes changes. `--config` supplies MkDocs nav title hints, not a complete navigation or app migration. For example, from the repository root:
+
+```bash
+# Replace paths with the approved destination and preserved source config.
+oat docs migrate --docs-dir apps/handbook/docs --config documentation/mkdocs.yml
+# Review the preview and approve the content conversion before writing.
+oat docs migrate --docs-dir apps/handbook/docs --config documentation/mkdocs.yml --apply
+```
+
+The command does not migrate app shells, deployment, plugins, macros, redirects or all Markdown extensions. Review seeded descriptions for meaningful content; metadata injection is not editorial completion. Convert unsupported syntax manually within the approved scope, preferring `.md` and using `.mdx` only where components require it. Preserve code examples, cautions, provenance and external attributions.
+
+## Phase 3: preserve navigation, links and URLs
+
+Create authored `index.md` pages with purpose and `## Contents` maps in each content directory. Map every retained page into the approved tree; use `.md` or `subdir/index.md` targets and the current dash-bullet Contents grammar. When consolidating `overview.md`, carry its content and inbound references into `index.md` and retain the old-URL mapping.
+
+Run `oat docs nav sync --target-dir <app-root>` to generate committed `docs/**/meta.json` navigation from authored maps. Resolve unlisted pages explicitly. Do not hand-edit generated navigation. The separate app-root `index.md` manifest is generated by `oat docs generate-index` through the scaffold's `predev`/`prebuild`; it is not the authored root page.
+
+Rewrite inbound links, relative assets and anchors using the before/after map. Test public URLs under the real base path. Choose an approved host-compatible recovery for moved URLs; do not assume Next redirects work with static export. If old URLs cannot be preserved, report the exact break and obtain a decision before deployment changes or source deletion.
+
+## Phase 4: validate the migration
+
+Discover and run the target app's actual lint, format, build and any link checks. Do not treat disabled/no-op scripts as validation. Run nav sync's read-only `--check` form to check committed navigation. Run existing repository gates required for package, config and workflow changes; keep exact exit codes and distinguish new failures from the baseline.
+
+Inspect the static output and use the available browser to spot-check:
+
+- landing and deeply nested pages, sidebar labels/order and search;
+- old and new URLs, anchors, relative links and base-path assets;
+- admonitions, tabs, tables, Mermaid, code blocks and custom components;
+- title/description metadata, theme and layout behavior.
+
+A successful build does not prove rendering or link parity. If a check cannot run, record the missing evidence and owner action; do not mark it verified. Review every inventory entry as migrated, deliberately retained, or explicitly approved for retirement, with a reason.
+
+## Phase 5: review, switch and retain rollback
+
+Present the content conservation diff, URL map, validation evidence, unresolved owner-review items, config changes and deployment proposal. Obtain user approval before switching the configured docs surface, changing publication workflows or retiring the old site. Use `oat-docs-analyze` for a read-only audit and the appropriate reviewed workflow for follow-up changes; do not assume docs-apply may edit app-shell or deployment configuration.
+
+Only after parity and approval, remove obsolete MkDocs dependencies/configuration and update repository guidance to the new authored source, generated artifacts and commands. Keep an explicit rollback reference to the prior site/config/deployment. Package publishing and production deployment require their own authorization.
+
+## Final report
+
+Report the approved scope, changed files and commits; source-to-target page and URL dispositions; commands and exit codes; rendered spot checks; the configured docs root and publication behavior; known failures and unverified evidence; owner-review items and decisions; and the rollback reference. State whether the migration is ready for owner acceptance, rather than treating the absence of build errors as acceptance.
+
+## Current contract references
+
+Within this installed skill, read [lifecycle boundaries](lifecycle-boundaries.md), [the Fumadocs contract](oat-fumadocs-contract.md) and [validation](validation.md). Load `authoring-docs` from installed scope for universal evidence and writing guidance. Inspect installed CLI help and rendered templates before executing commands; the consuming repository's instructions and approved migration scope remain authoritative.