@open-agent-toolkit/cli 0.1.21 → 0.1.22

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.

package/assets/skills/oat-docs-authoring/references/oat-fumadocs-contract.md

@@ -0,0 +1,77 @@
+---
+title: OAT Fumadocs authoring contract
+description: Authored source, navigation, link, file-type, generated-index, and exception rules for OAT/Fumadocs docs apps.
+---
+
+# OAT Fumadocs Authoring Contract
+
+The OAT/Fumadocs contract is tooling-critical. It is not just style.
+
+## Authored Source of Truth
+
+- Author content under the authored docs root, usually `docs/` inside the docs
+  app.
+- Every Markdown-bearing content directory has an authored `index.md`.
+- Every authored `index.md` that represents a content directory has a
+  `## Contents` section.
+- `## Contents` lists sibling pages and immediate child directories for that
+  directory.
+- If you create a child directory, create `child/index.md` and link it from the
+  parent as `child/index.md`.
+
+## Links in `## Contents`
+
+Use file-path-friendly relative Markdown links:
+
+- leaf page: `[Title](page.md)`;
+- child directory: `[Section](section/index.md)`;
+- avoid extensionless local docs links for new authored navigation entries;
+- preserve anchors only when the target heading exists and the local renderer
+  supports the anchor.
+
+Existing extensionless links are drift, not precedent. Normalize them only when
+the task scope or an approved recommendation covers that change.
+
+## File Types
+
+- Prefer `.md` for plain content pages.
+- Use `.mdx` only for pages that need JSX, imports, custom components, or other
+  MDX-only behavior.
+- Do not create `overview.md` as a directory entrypoint. Use `index.md` with
+  `## Contents`.
+- Add or preserve at least `title` and `description` frontmatter on touched
+  pages unless local guidance defines a stricter schema.
+
+## Generated Root Indexes
+
+Many OAT/Fumadocs apps have an app-root generated `index.md` that rolls up the
+authored docs tree. Treat it as generated output.
+
+- Do not hand-edit generated root indexes.
+- Regenerate or freshness-check them through local scripts when navigation
+  changes.
+- Do not treat a generated-root entry as proof that the nearest parent
+  `## Contents` is healthy.
+- If generated output is intentionally gitignored or locally absent, record that
+  in the handoff instead of inventing a manual replacement.
+
+## Exceptions and Local Extensions
+
+- Asset-only directories do not need `index.md` unless local guidance says so.
+- Build output, hidden tool directories, and generated artifacts are not content
+  directories.
+- Optional Fumadocs metadata files, such as `meta.json`, may refine sidebar
+  presentation when local style uses them. They do not replace `## Contents`.
+- Preserve local audience routers, ownership notes, and app-shell
+  customizations.
+
+## Quick Check
+
+For every touched directory or page, confirm:
+
+- content directory has `index.md`;
+- local `index.md` has useful `## Contents`;
+- new links include `.md` or `subdir/index.md`;
+- generated root index was not hand-edited;
+- `.mdx` has a real reason;
+- no new `overview.md` entrypoint was introduced.

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

@@ -0,0 +1,61 @@
+---
+title: Targeted OAT docs authoring workflow
+description: Focused edit loop for small OAT/Fumadocs documentation authoring and restructuring tasks.
+---
+
+# Targeted OAT Docs Authoring Workflow
+
+Use this workflow when the user asks for a focused docs addition, repair, move,
+or review inside an existing OAT/Fumadocs docs app.
+
+## 1. Bound the Change
+
+- Restate the requested target in terms of pages or directories.
+- Identify whether the work is content authoring, local restructuring, link
+  repair, or review.
+- If the task becomes setup, repo-wide audit, recommendation-driven apply,
+  project-derived documentation, or full migration work, stop and route through
+  `references/lifecycle-boundaries.md`.
+
+## 2. Gather Evidence
+
+- Read local instructions before editing.
+- Inspect current docs pages in the target area.
+- Inspect source code, package scripts, CLI help, schemas, tests, or deployment
+  files needed to support factual claims.
+- Use `authoring-docs` for page type, evidence quality, writing style,
+  templates, and review rubric.
+
+## 3. Preserve Local Navigation
+
+- Read the nearest authored map before changing a page.
+- For moves or renames, update links to the old path in the same change.
+- Preserve local audience routers, area ownership notes, and sidebar metadata
+  when present.
+
+For page moves and renames:
+
+- update both the old parent and new parent `## Contents` sections;
+- search for links to the old path before finishing;
+- preserve optional local sidebar metadata, such as `meta.json`, when present;
+- regenerate or freshness-check the generated root index after authored maps
+  change;
+- do not treat a generated-root entry as proof that the nearest parent map is
+  correct.
+
+## 4. Validate Locally
+
+- Read package scripts before choosing validation commands.
+- Run generation or validation scripts that are relevant to the touched files.
+- For render-sensitive Markdown, inspect the rendered result when practical.
+
+## 5. Report Clearly
+
+Handoff with:
+
+- files changed;
+- source evidence inspected;
+- maps and links updated;
+- generated artifacts checked or regenerated;
+- validation command results;
+- unresolved facts or owner-review items.

package/assets/skills/oat-docs-authoring/references/validation.md

@@ -0,0 +1,61 @@
+---
+title: OAT docs authoring validation
+description: Local validation, generated-index checks, and render spot-check guidance for targeted OAT/Fumadocs docs changes.
+---
+
+# OAT Docs Authoring Validation
+
+Validation is local to the docs app. Read scripts and instructions before
+choosing commands.
+
+## Script Discovery
+
+Inspect the docs app `package.json` and local instructions for:
+
+- `predev` or `prebuild` generation steps;
+- `fumadocs-mdx`;
+- `oat docs generate-index`;
+- docs lint, format, type-check, test, or build scripts;
+- intentionally disabled or no-op scripts.
+
+Use the local script names and package manager style already present in the
+repo. Do not invent universal docs commands.
+
+## Generated Index Checks
+
+When navigation, file placement, or `## Contents` changes:
+
+- regenerate the generated root index through the local command when available;
+- if generation is tied to `predev` or `prebuild`, run the smallest local
+  command that updates or checks the generated output;
+- inspect the generated diff for stale paths, missing pages, unexpected
+  ordering drift, or missing generated-file warning banners;
+- leave generated output unedited by hand.
+
+If generated output is ignored, absent by policy, or cannot be produced in the
+current environment, record the exact reason in the handoff.
+
+## Local Contract Checks
+
+Before finishing:
+
+- every touched content directory has `index.md`;
+- every touched authored `index.md` has a meaningful `## Contents`;
+- parent maps include new or moved immediate children;
+- links to moved files were updated;
+- new local navigation links use `.md` or `subdir/index.md`;
+- no new `overview.md` or unnecessary `.mdx` page was introduced.
+
+## Render Spot Checks
+
+Build success is not always enough for render-sensitive content. Spot-check the
+rendered result when changes include:
+
+- migrated MkDocs syntax;
+- callouts, tabs, Mermaid, images, iframes, or custom MDX components;
+- large link rewrites or directory moves;
+- frontmatter or metadata behavior;
+- app-shell or layout changes.
+
+Use the app's local dev or build workflow when practical. If rendering cannot
+be checked, state that explicitly.