@open-agent-toolkit/cli 0.1.20 → 0.1.22

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

@@ -12,7 +12,7 @@ oat_analysis_commit: { commitHash }
 **Date:** {YYYY-MM-DD}
 **Mode:** {full|delta}
 **Docs Target:** `{docs-target-path}`
-**Surface Type:** {mkdocs-app|docs-tree|root-markdown}
+**Surface Type:** {mkdocs-app|oat-fumadocs-app|docs-tree|root-markdown}
 **Commit:** {short-hash}
 
 ## Summary
@@ -26,6 +26,11 @@ oat_analysis_commit: { commitHash }
 - **Open questions / ask-user items:** {N}
 - **Contradicted claims:** {N}
 - **Coverage gaps / content opportunities:** {N}
+- **Generated index findings:** {N}
+- **Broken or extensionless local docs links:** {N}
+- **Markdown hygiene findings:** {N}
+- **Local guidance gaps:** {N}
+- **Owner-review gaps:** {N}
 
 ## Docs Inventory
 
@@ -108,6 +113,81 @@ None | {numbered list}
 
 {Or: "No directory contract gaps identified."}
 
+## Generated Index and Local Map Findings
+
+Use this section for OAT/Fumadocs docs apps or any docs surface with generated
+root indexes, generated manifests, `meta.json`, or comparable derived navigation
+files. Treat authored `docs/**/index.md` `## Contents` maps as source unless
+local configuration or guidance proves a different source of truth.
+
+| #   | Classification                   | Generated Artifact       | Authored Source Evidence        | Issue                         | Severity | Recommended Fix                         |
+| --- | -------------------------------- | ------------------------ | ------------------------------- | ----------------------------- | -------- | --------------------------------------- |
+| 1   | {missing output}                 | `{index.md or manifest}` | `{config/script/guidance refs}` | Generated output is absent    | Medium   | Run or document the generation workflow |
+| 2   | {ignored/local output}           | `{index.md or manifest}` | `{gitignore/config refs}`       | Local generated file is stale | Medium   | Regenerate locally or clarify lifecycle |
+| 3   | {stale output}                   | `{index.md or manifest}` | `{docs/**/index.md refs}`       | Deleted path still appears    | High     | Regenerate derived output               |
+| 4   | {authored-source contract drift} | `{index.md or manifest}` | `{parent index.md refs}`        | Source map omits child docs   | Medium   | Fix authored `## Contents` map          |
+| 5   | {unclear generator semantics}    | `{index.md or manifest}` | `{generator/config refs}`       | Ordering or inclusion unclear | Low      | Document or investigate semantics       |
+
+{Or: "No generated index or local-map findings identified."}
+
+For every generated-index finding:
+
+- Cite exact generated artifact paths and authored source-map paths.
+- Distinguish missing entries, stale entries, ordering drift, unreachable
+  generated entries, and unclear generator behavior.
+- State whether generated warning banners are present, absent, or not expected.
+- Do not recommend hand-editing generated artifacts; recommend source-map fixes,
+  regeneration, local guidance updates, or generator investigation.
+
+## Authored Links, Contents, and Markdown Hygiene
+
+Use this section for local Markdown links, `## Contents` quality, page-extension
+conventions, and Markdown syntax issues that affect rendering, navigation, or
+search quality.
+
+| #   | Category                   | File Ref          | Issue                                           | Evidence                             | Severity | Recommended Fix                         |
+| --- | -------------------------- | ----------------- | ----------------------------------------------- | ------------------------------------ | -------- | --------------------------------------- |
+| 1   | {broken local link}        | `{docs/path.md}`  | Target does not exist                           | `{source line and target path}`      | High     | Update or remove the link               |
+| 2   | {extensionless local link} | `{docs/path.md}`  | Link omits `.md` suffix                         | `{source line}`                      | Medium   | Use `.md` or `subdir/index.md`          |
+| 3   | {placeholder Contents}     | `{docs/index.md}` | `## Contents` is scaffold                       | `{source line}`                      | Medium   | Replace with useful local map           |
+| 4   | {overview.md}              | `{docs/topic/}`   | Legacy entrypoint remains                       | `{overview.md refs}`                 | Medium   | Convert to `index.md` or topic page     |
+| 5   | {unexpected mdx}           | `{docs/page.mdx}` | Plain content uses `.mdx`                       | `{page and local guidance}`          | Medium   | Convert to `.md` or document exception  |
+| 6   | {unlabeled code fence}     | `{docs/path.md}`  | Code fence has no language                      | `{source line}`                      | Low      | Add a language identifier               |
+| 7   | {shell fence drift}        | `{docs/path.md}`  | Shell fence convention drifts                   | `{source line and guidance}`         | Low      | Use the documented shell fence language |
+| 8   | {heading hygiene}          | `{docs/path.md}`  | Empty heading or extra H1                       | `{source line}`                      | Low      | Fix heading hierarchy                   |
+| 9   | {metadata hygiene}         | `{docs/path.md}`  | Description too long, truncated, or README-like | `{frontmatter refs and local limit}` | Low      | Rewrite concise metadata                |
+
+{Or: "No authored link, Contents, or Markdown hygiene findings identified."}
+
+False-positive guardrails:
+
+- Ignore external URLs, anchors-only links, `mailto:` links, image links, and
+  asset/file links that are not docs pages.
+- Accept anchors on `.md` links, such as `page.md#section`.
+- Ignore link syntax shown inside inline code, fenced snippets, placeholder
+  templates, or intentional examples.
+- Only enforce frontmatter description length limits when local guidance,
+  schemas, or generators define the limit.
+- Do not flag multiple H1s in intentional imported README/generated contexts
+  unless local guidance says those files are authored docs.
+
+## Local Docs-App Guidance
+
+Use this section when the repository has docs-app `AGENTS.md`, contributing
+docs, authoring guides, generated-index docs, or legacy docs workflow guidance.
+
+| #   | Guidance Area              | Source Ref             | Status                        | Evidence       | Severity | Recommended Fix                     |
+| --- | -------------------------- | ---------------------- | ----------------------------- | -------------- | -------- | ----------------------------------- |
+| 1   | Authored docs source root  | `{AGENTS.md or guide}` | {covered \| missing \| stale} | `{exact refs}` | Medium   | Document the source root            |
+| 2   | Generated root index       | `{AGENTS.md or guide}` | {covered \| missing \| stale} | `{exact refs}` | Medium   | Explain derived output lifecycle    |
+| 3   | `index.md` / `## Contents` | `{AGENTS.md or guide}` | {covered \| missing \| stale} | `{exact refs}` | Medium   | Add local map contract guidance     |
+| 4   | `.md` links                | `{AGENTS.md or guide}` | {covered \| missing \| stale} | `{exact refs}` | Medium   | Document `.md` relative links       |
+| 5   | `.md` vs `.mdx`            | `{AGENTS.md or guide}` | {covered \| missing \| stale} | `{exact refs}` | Low      | Explain when `.mdx` is allowed      |
+| 6   | Analyze/apply boundaries   | `{AGENTS.md or guide}` | {covered \| missing \| stale} | `{exact refs}` | Medium   | Route audits/apply work correctly   |
+| 7   | Freshness checks           | `{AGENTS.md or guide}` | {covered \| missing \| stale} | `{exact refs}` | Medium   | Add regeneration/freshness guidance |
+
+{Or: "No local docs-app guidance gaps identified."}
+
 ## Accuracy Verification
 
 Check only claims that are verifiable from repo sources such as code, config, schemas,
@@ -122,6 +202,22 @@ runtime-only behavior here.
 
 {Or: "No repo-checkable substantive claims required accuracy verification."}
 
+## Coverage Review by Surface
+
+Summarize which documentable surfaces were proven by repo evidence and how well
+the docs cover them. Mark owner-review gaps instead of guessing when claims
+depend on unsupported ownership, support, deployment, observability, rollback,
+external integration, or production behavior.
+
+| #   | Surface     | Repo Evidence                      | Docs Coverage State                      | Missing or Thin Areas                                      | Owner Review Needed |
+| --- | ----------- | ---------------------------------- | ---------------------------------------- | ---------------------------------------------------------- | ------------------- |
+| 1   | App/service | `{entrypoint/service/config refs}` | {adequate \| thin \| no coverage \| N/A} | `{setup/testing/config/deploy/observability/runbook refs}` | {yes/no + reason}   |
+| 2   | API         | `{router/schema refs}`             | {adequate \| thin \| no coverage \| N/A} | `{contracts/auth/errors/examples/versioning}`              | {yes/no + reason}   |
+| 3   | CLI         | `{command/flag/test refs}`         | {adequate \| thin \| no coverage \| N/A} | `{flags/output/dry-run/force/scripting/exit-codes}`        | {yes/no + reason}   |
+| 4   | Operations  | `{deploy/monitoring/runbook refs}` | {adequate \| thin \| no coverage \| N/A} | `{release/rollback/support/escalation/troubleshooting}`    | {yes/no + reason}   |
+
+{Or: "No app/service, API, CLI, or operations surface required coverage review."}
+
 ## Content Opportunities
 
 Surface only repo-checkable coverage gaps based on routers, services, models, schemas,
@@ -180,6 +276,10 @@ canonical docs/config/examples.
 
 - `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
+  generated-index finding requires output changes, apply should update authored
+  source maps or run the documented generator only after user approval and local
+  workflow confirmation.
 - Content opportunity recommendations require `oat-docs-apply` to read the cited router/service/model files before generating prose; it must not synthesize feature coverage from memory.
 - Recommendations marked `omit` must stay out of generated docs changes.
 - Recommendations marked `ask_user` require explicit user confirmation before generation.

package/assets/skills/oat-docs-analyze/references/directory-assessment-criteria.md

@@ -10,6 +10,12 @@ Treat a directory as a docs node when one or more of these is true:
 - It has child directories that contain Markdown files.
 - It represents a distinct product, package, workflow, or topic area.
 - It is linked from another docs page as a navigable subsection.
+- It is represented in a generated root index, sidebar metadata file, or local
+  `## Contents` map.
+
+Treat a directory as asset-only when it contains no Markdown files, contains no
+Markdown-bearing child directory, and is only referenced as an image/file asset
+container. Asset-only directories do not need their own `index.md`.
 
 ## Severity guidance
 
@@ -20,14 +26,21 @@ Use `High` when the directory:
 - Is a top-level docs section with no `index.md`
 - Contains multiple pages or subtrees but lacks a local map
 - Is important to setup, operations, or contributor workflows
+- Is listed in a parent map or generated index but has no useful entrypoint
 
 ### Medium
 
 Use `Medium` when the directory:
 
 - Has an `index.md` but no useful `## Contents`
+- Has a placeholder-only `## Contents`, such as an empty list, HTML comment, or
+  generic scaffold text
 - Still uses `overview.md` as the directory entrypoint
 - Has a partial map that omits key siblings or child directories
+- Is a single-page directory whose `index.md` does not orient readers to the
+  page's purpose or downstream links
+- Uses `.mdx` for plain Markdown content without local guidance or JSX/component
+  evidence
 
 ### Low
 
@@ -35,6 +48,8 @@ Use `Low` when the directory:
 
 - Is technically covered but the descriptions are vague
 - Has minor organization issues that do not block discovery
+- Has ordering drift between authored maps and generated indexes that does not
+  break reachability and may reflect documented generator behavior
 
 ## Exclusions
 
@@ -44,3 +59,4 @@ Do not require `index.md` for:
 - `site/`
 - build output directories
 - hidden tool directories that are not part of the docs surface
+- asset-only image, media, or attachment directories

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

@@ -6,8 +6,45 @@ Use this checklist when evaluating a docs surface.
 
 - Every docs directory has an `index.md`.
 - Every `index.md` includes a `## Contents` section.
+- `## Contents` is useful content, not a placeholder comment, empty list, or
+  generic "add links here" scaffold.
 - `## Contents` links describe sibling files and immediate child directories.
+- Parent `## Contents` maps include immediate child directories that contain
+  docs.
+- Single-page directories still expose a useful `index.md` entrypoint or local
+  section map.
+- Asset-only directories are exempt when they contain no Markdown content and
+  are not linked as navigable docs sections.
 - `overview.md` is not used as the directory entrypoint.
+- Plain docs content uses `.md` by default; `.mdx` is reserved for pages that
+  need JSX/components or are explicitly allowed by local guidance.
+
+## Links
+
+- Local relative Markdown links resolve from the page where they appear.
+- OAT/Fumadocs docs apps use `.md`-suffixed local links for docs pages,
+  including `subdir/index.md` for child directory maps.
+- Anchors on `.md` links are allowed, such as `page.md#section`.
+- Extensionless local docs links are flagged when local guidance follows the
+  OAT/Fumadocs `.md` link convention.
+- Inline-code examples, fenced snippets, placeholder templates, external URLs,
+  anchors-only links, `mailto:` links, and asset/image links are not false
+  positives for broken docs-page links.
+
+## Markdown Hygiene
+
+- Opening code fences have language identifiers.
+- Shell command examples follow the repo's documented fence convention; default
+  to `sh` unless local guidance uses `bash` or the block requires Bash-only
+  syntax.
+- Headings are non-empty.
+- Each authored page has at most one document-level H1 unless the file is an
+  intentional imported README or generated/imported artifact.
+- Frontmatter descriptions respect local length limits when those limits are
+  documented.
+- Descriptions are not ellipsis-truncated.
+- Titles, descriptions, and metadata do not look like copied README boilerplate
+  when rendered in docs navigation or search.
 
 ## Accuracy
 
@@ -23,9 +60,50 @@ Use this checklist when evaluating a docs surface.
 
 ## Docs App Contract
 
-- `mkdocs.yml` exists when the repo is using an OAT docs app.
-- Navigation is consistent with the docs tree.
-- `docs/contributing.md` documents enabled plugins/extensions when an MkDocs app exists.
+- For `mkdocs-app`, `mkdocs.yml` exists.
+- For `mkdocs-app`, navigation is consistent with the docs tree.
+- For `mkdocs-app`, `docs/contributing.md` documents enabled
+  plugins/extensions when local convention requires it.
+- For `oat-fumadocs-app`, OAT config or app-local evidence identifies the docs
+  app before any generic root `docs/` fallback.
+- For `oat-fumadocs-app`, `.oat/config.json` `documentation.root` /
+  `documentation.tooling`, `apps/*/source.config.*`, `apps/*/next.config.*`, or
+  equivalent local guidance backs the classification.
+- For `oat-fumadocs-app`, the authored docs source root exists and is distinct
+  from generated app-root indexes/manifests when the app uses generated output.
+- For `oat-fumadocs-app`, generated app-root index evidence exists when local
+  config or guidance declares one.
+- OAT/Fumadocs docs-app guidance identifies the authored docs source root.
+- Local guidance explains that generated root indexes/manifests are derived
+  output and must not be hand-edited.
+- Local guidance states that each content directory needs `index.md` and each
+  authored `index.md` needs a useful `## Contents`.
+- Local guidance documents `.md`-suffixed relative docs links, including
+  `subdir/index.md`.
+- Local guidance explains `.md` vs `.mdx` expectations.
+- Local guidance routes broad read-only audits to `oat-docs-analyze` and
+  approved bulk changes to `oat-docs-apply`.
+- Local guidance tells agents to regenerate or freshness-check generated
+  artifacts after source docs edits.
+- Older analyze/apply aliases are mapped to the current flow or removed.
+
+## Coverage
+
+- App/service docs cover purpose, audience, local setup, testing, configuration,
+  deployment/release, observability, runbooks, rollback, ownership,
+  support/escalation, troubleshooting, and common failure modes when those
+  surfaces exist in repo evidence.
+- API docs for broad API surfaces include navigable contract-grade references:
+  routes/endpoints, request/response shapes, authentication, error modes,
+  examples, and versioning when applicable.
+- CLI docs expose command groups, flags, output modes, destructive behavior,
+  dry-run/force options, scripting contracts, exit-code behavior when sourced,
+  and common workflow examples.
+- Operations docs replace "Future Topics" placeholders with concrete pages or
+  explicit owner-reviewed gaps.
+- Unsupported or unverifiable claims about owners, support, deployment,
+  observability, rollback, external integrations, or production behavior are
+  marked for owner review instead of being treated as facts.
 
 ## Claims Are Evidence-Backed
 
@@ -44,5 +122,7 @@ Use this checklist when evaluating a docs surface.
 - Nav points to missing files.
 - Files exist but are not represented in indexes/nav.
 - Index descriptions no longer match the content they point to.
+- Generated root indexes include stale paths, omit authored-map entries, or
+  order entries differently without documented generator semantics.
 - Commands mention removed or renamed tooling.
 - Docs claim plugin support or structure rules that are not backed by current repo evidence.

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

@@ -0,0 +1,193 @@
+---
+name: oat-docs-authoring
+version: 1.0.0
+description: Use when authoring or restructuring targeted content inside an existing OAT/Fumadocs docs app. Preserves OAT docs navigation, generated indexes, and validation boundaries.
+argument-hint: '[docs task or target path]'
+disable-model-invocation: false
+allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
+user-invocable: true
+---
+
+# OAT Docs Authoring
+
+Use this skill for targeted documentation authoring and small structural edits
+inside an existing 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/Fumadocs placement,
+navigation, generated artifacts, validation, and lifecycle boundaries.
+
+## Prerequisites
+
+- The repository already has an OAT/Fumadocs docs app or a clearly identified
+  target docs app that follows OAT conventions.
+- The task is a targeted authoring, restructuring, repair, or review task, not
+  a new docs-app bootstrap, broad audit, or approved bulk-apply workflow.
+
+## Mode Assertion
+
+**OAT MODE: Docs Authoring Wrapper**
+
+**Purpose:** Author or restructure focused docs content while preserving the
+OAT/Fumadocs source-of-truth contract.
+
+**BLOCKED Activities:**
+
+- Bootstrapping a new docs app.
+- Running a broad read-only docs audit as an ad hoc manual review.
+- Applying a batch of approved audit recommendations.
+- Writing project-derived release or feature docs from active OAT project
+  artifacts.
+- Running a full MkDocs-to-OAT-Fumadocs migration.
+- Treating generated navigation artifacts as editable source.
+
+**ALLOWED Activities:**
+
+- Creating or improving targeted docs pages inside an existing docs app.
+- Moving or renaming a small number of docs pages when the local maps are
+  updated in the same change.
+- Repairing local navigation, frontmatter, link, or Markdown issues near the
+  requested target.
+- Reviewing a docs change for OAT/Fumadocs contract fit.
+
+**Self-Correction Protocol:**
+If you catch yourself:
+
+- Writing general documentation guidance already covered by `authoring-docs` ->
+  STOP and reference the baseline instead.
+- Expanding a targeted task into a repo-wide audit -> STOP and route to
+  `oat-docs-analyze`.
+- Applying a broad set of recommendations -> STOP and route to `oat-docs-apply`.
+- Bootstrapping or repairing a docs app shell -> STOP and route to
+  `oat-docs-bootstrap`.
+- Migrating an existing MkDocs docs app to OAT/Fumadocs -> STOP and use the
+  standalone migration guide; bootstrap is not the migration workflow.
+- Editing generated root indexes or derived navigation output -> STOP and move
+  the change back to authored docs sources.
+- Treating generated root indexes as proof of local navigation health -> STOP
+  and inspect the nearest authored `## Contents` map.
+
+**Recovery:**
+
+1. Re-state the narrower target and the lifecycle skill, if any, that owns the
+   larger work.
+2. Continue only with authored docs files and local validation relevant to the
+   target.
+
+## Progress Indicators (User-Facing)
+
+When executing this skill, provide lightweight progress feedback so the user can
+tell what is happening after they confirm.
+
+- Print a phase banner once at start:
+
+  ```txt
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  OAT ▸ DOCS AUTHORING
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  ```
+
+- Print each step indicator at the start of that step, not all at once upfront:
+  - `[1/5] Resolving docs app and local instructions...`
+  - `[2/5] Inspecting source evidence and navigation maps...`
+  - `[3/5] Authoring targeted docs changes...`
+  - `[4/5] Regenerating or checking derived docs artifacts...`
+  - `[5/5] Running validation and preparing handoff...`
+
+## Process
+
+### Step 1: Resolve the Authoring Target
+
+Identify the docs task, target reader, docs app root, authored docs root, and
+nearest local instruction files. Read repository and docs-app guidance before
+choosing placement.
+
+Use `references/lifecycle-boundaries.md` first when the request may be setup,
+audit, apply, project-documentation, or migration work.
+
+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.
+
+### Step 2: Inspect Evidence and Local Maps
+
+Ground every new or changed claim in source evidence. Inspect the nearest
+authored navigation map for the target area before adding, moving, or deleting a
+page.
+
+Use `references/targeted-authoring-workflow.md` for the focused edit loop.
+
+### Step 3: Edit Authored Docs Sources
+
+Edit source docs pages and local maps together. Keep changes near the requested
+target unless the user explicitly approved broader restructuring.
+
+Use `references/oat-fumadocs-contract.md` for the concrete authored-source
+rules: `index.md`, `## Contents`, `.md` links, generated root indexes, Markdown
+defaults, and asset-only exceptions.
+
+Prefer plain Markdown for content pages. Use MDX only when local guidance and
+the task require JSX or custom components.
+
+### Step 4: Check Generated Artifacts and Validation
+
+Regenerate or freshness-check derived docs artifacts using local scripts when
+the change affects navigation or generated indexes. Run the docs app's local
+validation commands when they exist and are meaningful.
+
+Use `references/validation.md` for script discovery, generated-index checks,
+and render spot-check guidance.
+
+### Step 5: Handoff
+
+Summarize changed files, evidence inspected, local maps updated, generated
+artifacts regenerated or intentionally not run, validation commands, unresolved
+facts, and any recommended lifecycle follow-up.
+
+## Reference Map
+
+Load only the references needed for the task:
+
+- `references/docs-root-resolution.md`: resolve docs app root, authored docs
+  root, generated root index, and local instruction surfaces.
+- `references/lifecycle-boundaries.md`: route setup, audits, applies,
+  project-derived docs, and migrations to the correct workflow owner.
+- `references/oat-fumadocs-contract.md`: OAT/Fumadocs authored-source and
+  generated-artifact contract.
+- `references/targeted-authoring-workflow.md`: focused OAT/Fumadocs authoring
+  flow for small edits.
+- `references/validation.md`: local validation, generated-index, and render
+  spot-check guidance.
+- `authoring-docs`: universal documentation-quality baseline.
+
+## Examples
+
+Basic usage:
+
+```txt
+/oat-docs-authoring apps/oat-docs/docs/reference/
+```
+
+Conversational triggers:
+
+```txt
+Add a new OAT docs page and wire it into the local Contents map.
+Move this Fumadocs page without breaking generated navigation.
+Review this docs change for OAT index contract issues.
+Fix the local docs links near this page.
+```
+
+## Success Criteria
+
+- The task stayed within targeted authoring or restructuring scope.
+- Universal docs quality came from `authoring-docs` instead of duplicated
+  wrapper prose.
+- Authored docs source files and local maps were updated together.
+- Generated artifacts were checked or regenerated when navigation changed.
+- Local validation ran, or the handoff explains why it was not available or not
+  meaningful.

package/assets/skills/oat-docs-authoring/references/docs-root-resolution.md

@@ -0,0 +1,64 @@
+---
+title: OAT docs root resolution
+description: How to resolve OAT/Fumadocs app roots, authored docs roots, generated index outputs, and local instruction surfaces before editing.
+---
+
+# OAT Docs Root Resolution
+
+Do not assume the docs app lives at `apps/oat-docs`. Resolve the app and source
+roots before editing.
+
+## Resolution Order
+
+1. Read repo-level instructions.
+   - Root `AGENTS.md` often names the docs app root, framework, and generated
+     index file.
+   - A docs-app `AGENTS.md` may override or narrow the repo-level guidance.
+2. Inspect `.oat/config.json`.
+   - Prefer documented `documentation.root` values for the docs app root.
+   - Treat `documentation.index` as the generated root index when present; it
+     may not be the same as the authored docs root.
+   - If config is incomplete, keep resolving from local files instead of
+     guessing.
+3. Inspect package scripts in likely docs app directories.
+   - Look for `predev`, `prebuild`, `fumadocs-mdx`, `oat docs generate-index`,
+     docs lint/format scripts, and local build commands.
+   - Use the scripts as evidence for generated-artifact ownership and
+     validation, not as a substitute for reading docs instructions.
+4. Inspect Fumadocs files when the task touches framework behavior.
+   - `source.config.ts`, `next.config.*`, and `app/layout.*` can reveal source
+     config, transforms, base paths, static export behavior, branding, metadata,
+     or custom components.
+   - Content-only edits usually should not modify these files.
+   - Site chrome, browser metadata, search behavior, image handling, and base
+     paths can be wired separately. Preserve local customizations unless the
+     user explicitly asked for app-shell work.
+5. Resolve the authored docs root.
+   - The common root is `<docs-app>/docs`, but local guidance is authoritative.
+   - Find the top-level authored `index.md`, then follow `## Contents` maps to
+     the target area.
+
+## Instruction Surfaces
+
+Read applicable local guidance before placing content:
+
+- repo-root `AGENTS.md`;
+- docs-app `AGENTS.md`;
+- nested `AGENTS.md` files in the target area;
+- human contributing or documentation-authoring pages;
+- nearest parent `index.md` with `## Contents`.
+
+Keep the audiences distinct. Runtime agent instructions belong in `AGENTS.md`;
+rendered human docs should describe durable authoring conventions and shipped
+behavior.
+
+## Output of This Step
+
+Before editing, know:
+
+- docs app root;
+- authored docs root;
+- generated root index path, if any;
+- nearest parent `index.md` map;
+- relevant local validation scripts;
+- any local exception or router that affects placement.

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

@@ -0,0 +1,51 @@
+---
+title: OAT docs authoring lifecycle boundaries
+description: Routing and self-correction rules for OAT docs setup, audit, apply, project-documentation, and migration workflows.
+---
+
+# OAT Docs Authoring Lifecycle Boundaries
+
+Use `oat-docs-authoring` for targeted authoring and small local restructuring.
+Route larger lifecycle work to its owner.
+
+## Routing Rules
+
+| Request shape                                                           | Owner                      | Why                                                                                                                        |
+| ----------------------------------------------------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| New docs app setup, scaffold repair, package/app shell bootstrap        | `oat-docs-bootstrap`       | Bootstrap owns preflight, inputs, `oat docs init`, post-scaffold checks, config inspection, and walkthrough.               |
+| Read-only docs audit, structure analysis, coverage review, drift report | `oat-docs-analyze`         | Analyze owns inventory, evidence gathering, severity-rated findings, and analysis artifacts.                               |
+| Applying approved analysis recommendations or batch docs changes        | `oat-docs-apply`           | Apply owns branch creation, approved changes, deterministic nav sync, verification, commit, and optional PR.               |
+| Docs updates derived from an active OAT project                         | `oat-project-document`     | Project-document owns artifact/code scanning, docs delta planning, approval, and project provenance.                       |
+| Existing MkDocs app to OAT/Fumadocs migration                           | Standalone migration guide | Migration needs inventory, syntax conversion, app-shell work, render checks, config/CI changes, and owner-review handling. |
+
+If a request mixes targeted authoring with lifecycle work, split it:
+
+1. Complete the lifecycle step through the owning skill or guide.
+2. Return to `oat-docs-authoring` only for a focused follow-up edit.
+
+## Self-Correction Rules
+
+Stop and reroute when you notice:
+
+- a new docs app is needed before content can be authored;
+- the user asked for "audit docs", "find all gaps", or similar broad analysis;
+- an analysis artifact or recommendation list is the source of truth;
+- the docs change is derived from OAT project artifacts rather than a direct
+  authoring request;
+- the migration requires converting MkDocs config, Python tooling, legacy
+  syntax, deploy workflows, or `overview.md` trees;
+- you are hand-editing a generated root index, generated route output,
+  `mkdocs.yml` nav, or other derived artifact;
+- you are treating the generated root index as source instead of checking the
+  nearest authored `## Contents`.
+
+## 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
+branch with owner-review items for unverifiable claims.
+
+For migration-sensitive follow-up after the migration workflow has created a
+Fumadocs app, this wrapper can help with a specific page, local map, link, or
+render issue. Keep that follow-up narrow.