@open-agent-toolkit/cli 0.1.21 → 0.1.22

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

@@ -0,0 +1,133 @@
+---
+title: Documentation Authoring Workflow
+description: Evidence-first workflow for creating, migrating, or improving docs.
+---
+
+# Documentation Authoring Workflow
+
+The job is not to write plausible documentation. The job is to extract truth
+from the repository, organize it, and make it usable.
+
+## 1. Classify the Project
+
+Identify the primary project type before writing:
+
+- frontend app
+- backend service
+- full-stack app
+- API service
+- CLI
+- library, package, framework, or SDK
+- infrastructure module
+- worker or job processor
+- event-driven system
+- documentation-only repo
+- mixed monorepo
+
+Repos can have multiple types. Document the dominant reader path first, then
+add category-specific coverage.
+
+## 2. Inventory Sources of Truth
+
+Inspect likely evidence before editing.
+
+For package-based projects, check package metadata, lockfiles, runtime version
+files, build config, source entry points, scripts, tests, and CI.
+
+For APIs, check route definitions, controllers, middleware, schema files,
+OpenAPI, GraphQL, protobuf, tests, and generated clients.
+
+For CLIs, check `bin` entries, command definitions, flag parsing,
+configuration loading, environment variables, tests, and existing examples.
+
+For services and infrastructure, check Docker files, compose files, workflows,
+Terraform, Kubernetes, Helm, serverless or CDK configuration, deployment
+manifests, monitor definitions, dashboards, and runbooks.
+
+For existing docs, check README files, docs directories, contribution guides,
+changelogs, ADRs, RFCs, and migration notes.
+
+## 3. Build a Docs Inventory
+
+Create a lightweight inventory before making broad changes.
+
+| Area              | Exists? | Quality            | Source of Truth         | Action          |
+| ----------------- | ------: | ------------------ | ----------------------- | --------------- |
+| Landing page      |  Yes/No | Good/Stale/Missing | README or docs index    | Update/Create   |
+| Getting started   |  Yes/No | Good/Stale/Missing | scripts, README, tests  | Update/Create   |
+| Local development |  Yes/No | Good/Stale/Missing | package scripts, config | Update/Create   |
+| Testing           |  Yes/No | Good/Stale/Missing | package scripts, CI     | Update/Create   |
+| Deployment        |  Yes/No | Good/Stale/Missing | CI, infra               | Verify/Create   |
+| API reference     |  Yes/No | Good/Stale/Missing | schema/routes           | Generate/Create |
+| CLI reference     |  Yes/No | Good/Stale/Missing | CLI source              | Generate/Create |
+| Configuration     |  Yes/No | Good/Stale/Missing | env/config files        | Create          |
+| Architecture      |  Yes/No | Good/Stale/Missing | source, infra           | Create          |
+| Operations        |  Yes/No | Good/Stale/Missing | monitors, runbooks      | Create          |
+| Troubleshooting   |  Yes/No | Good/Stale/Missing | issues, tests, logs     | Create          |
+
+## 4. Identify Reader Personas
+
+Most docs serve one or more of these readers:
+
+- new contributor
+- maintainer
+- service consumer
+- CLI user
+- API consumer
+- operator on call
+- reviewer
+- product stakeholder
+- support engineer
+- AI agent making future changes
+
+Write pages for actual tasks, not org-chart abstractions.
+
+## 5. Decide the Minimum Useful Set
+
+Most repos need a landing page, getting started, local development, testing,
+configuration reference, deployment or release docs if deployable, and
+ownership.
+
+Then add category-specific pages. APIs need auth, examples, endpoint or
+operation reference, and error behavior. CLIs need command reference, config,
+output, exit codes, and automation behavior. Production systems need
+observability, runbooks, rollback, and failure modes.
+
+## 6. Preserve Existing Intent
+
+Do not blindly replace existing docs. Existing pages often contain historical
+context, production details, migration notes, local setup caveats, owner
+knowledge, and important links. Extract useful facts, remove duplication, and
+restructure around reader needs.
+
+## 7. Ground Every Claim
+
+For each factual statement, ask where it came from. Good sources include source
+code, schemas, package scripts, configuration files, CI workflows, deployment
+manifests, tests, generated types, and current docs that still match behavior.
+
+Weak sources include stale comments, guessed conventions, issue titles without
+details, inferred ownership, and copied docs from a similar repo. Mark weak but
+useful facts as needing verification.
+
+## 8. Write in Layers
+
+For each topic, prefer this order:
+
+1. Purpose
+2. Common path
+3. Example
+4. Verification
+5. Edge cases
+6. Troubleshooting
+7. Related reference
+8. Deeper explanation
+
+This keeps pages useful under time pressure.
+
+## 9. Verify and Handoff
+
+Run relevant checks when available: docs build, link check, formatter,
+generated-reference command, examples, tests, or local preview. Handoff with
+files changed, evidence inspected, verification results, unresolved facts, and
+recommended next improvements.

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

@@ -0,0 +1,128 @@
+---
+title: Writing Style
+description: Style rules for clear, direct, maintainable technical documentation.
+---
+
+# Writing Style
+
+Technical documentation should be plain, specific, and useful under pressure.
+The reader should not have to decode tone, chase implied context, or guess
+whether a statement is current.
+
+## Voice
+
+Use a direct, practical voice.
+
+Prefer:
+
+```md
+Run the tests before opening a pull request.
+```
+
+Avoid:
+
+```md
+It is recommended that tests are run prior to the opening of a pull request.
+```
+
+## Active Voice and Specific Nouns
+
+Active voice makes responsibility clear. Specific nouns make actions
+verifiable.
+
+Weak:
+
+```md
+The cache is invalidated after the migration is run.
+```
+
+Stronger:
+
+```md
+The deploy workflow invalidates the Fastly cache after the migration finishes.
+```
+
+## Avoid False Ease
+
+Avoid words that make complex tasks sound trivial:
+
+- just
+- simply
+- obviously
+- easy
+- basically
+
+Replace hidden assumptions with exact steps, commands, or links.
+
+## Avoid Tribal Knowledge
+
+Do not write "use the usual process" or "deploy normally." Name the workflow,
+environment, command, approval requirement, and verification path when known.
+
+## Define Acronyms on First Use
+
+Define acronyms the first time they appear. If an acronym is used only once,
+avoid introducing it.
+
+## Prefer Present Tense
+
+Use future tense only for future behavior that is planned and dated. Avoid
+stale words such as `new`, `soon`, `currently`, `temporary`, `eventually`, and
+`recent` without a date or issue link.
+
+## Use Concrete Examples
+
+Show copyable examples with expected output when possible. Expected output helps
+humans verify success and helps agents reason about command behavior.
+
+## Warn Only for Real Risk
+
+Use warnings for production impact, destructive operations, security concerns,
+and irreversible behavior.
+
+```md
+> [!WARNING]
+> This command deletes all pending jobs in the queue. Run it only during an
+> active incident after confirming the queue contents.
+```
+
+Use notes for useful context, not ordinary tips.
+
+## Markdown Rules
+
+- Use one `#` heading per page.
+- Do not skip heading levels.
+- Use fenced code blocks with language identifiers.
+- Use `sh` for shell commands.
+- Use `txt` for command output.
+- Do not include shell prompts unless the prompt itself matters.
+- Use angle brackets for placeholders, such as `<environment>`.
+- Explain every placeholder.
+- Use descriptive link text.
+- Use tables for reference data, not long prose.
+
+## Headings Should Be Descriptive
+
+Weak headings:
+
+```md
+## Stuff
+
+## More
+
+## Notes
+
+## Misc
+```
+
+Stronger headings:
+
+```md
+## Configure environment variables
+
+## Run database migrations
+
+## Verify the deployment
+
+## Roll back a failed deploy
+```

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

@@ -1,6 +1,6 @@
 ---
 name: oat-docs-analyze
-version: 1.3.0
+version: 1.4.0
 description: Run when you need to evaluate documentation structure, navigation, and coverage against the OAT docs app contract. Produces a severity-rated analysis artifact for oat-docs-apply.
 disable-model-invocation: true
 user-invocable: true
@@ -13,7 +13,8 @@ Scan a repository's documentation surface, evaluate it against the OAT docs cont
 
 ## Prerequisites
 
-- Git repository with either an MkDocs app, a `docs/` tree, or root-level Markdown docs.
+- Git repository with either an OAT/Fumadocs docs app, an MkDocs app, a
+  `docs/` tree, or root-level Markdown docs.
 - `jq` available in PATH for tracking updates.
 
 ## Mode Assertion
@@ -50,6 +51,9 @@ If you catch yourself:
 
 - Editing docs content directly -> STOP and move that recommendation to the artifact.
 - Rewriting navigation while analyzing -> STOP and record the required fix instead.
+- Hand-editing or regenerating generated root indexes -> STOP and record a
+  generated-artifact finding with the exact evidence that proves freshness or
+  source-contract drift.
 
 **Recovery:**
 
@@ -73,7 +77,7 @@ When executing this skill, provide lightweight progress feedback so the user can
   - `[4/10] Assessing quality + coverage…`
   - `[5/10] Verifying substantive claims…`
   - `[6/10] Finding content opportunities…`
-  - `[7/10] Checking nav and drift…`
+  - `[7/10] Checking generated indexes, nav and drift…`
   - `[8/10] Writing analysis artifact…`
   - `[9/10] Reviewing artifact accuracy…`
   - `[10/10] Updating verified tracking + summary…`
@@ -82,14 +86,27 @@ When executing this skill, provide lightweight progress feedback so the user can
 
 ### Step 0: Resolve Docs Target and Analysis Mode
 
-Determine the documentation root using the first matching surface:
-
-1. `apps/*/mkdocs.yml`
-2. `mkdocs.yml` at repo root
-3. `docs/`
-4. Root-level Markdown docs (`README.md`, `CONTRIBUTING.md`, etc.) when no docs app exists
-
-Prefer the OAT docs app when multiple MkDocs apps exist and one is clearly the active repo docs surface.
+Determine the documentation root using explicit docs-app evidence before generic
+repo fallbacks:
+
+1. `.oat/config.json` `documentation.root` / `documentation.tooling`.
+   - When `documentation.tooling` is `fumadocs`, record the surface type as
+     `oat-fumadocs-app`.
+   - Treat `documentation.root` as the docs app root. Resolve the authored docs
+     source root and generated index path from `documentation.index`, app config,
+     package scripts, generator scripts, or local guidance.
+2. OAT/Fumadocs app candidates under `apps/*`, before root `docs/` fallback:
+   - `apps/*/source.config.*`
+   - `apps/*/next.config.*` with `apps/*/docs`
+   - `apps/*/docs` plus docs-app package scripts or local guidance evidence
+3. `apps/*/mkdocs.yml`
+4. `mkdocs.yml` at repo root
+5. generic root `docs/`
+6. Root-level Markdown docs (`README.md`, `CONTRIBUTING.md`, etc.) when no docs app exists
+
+Do not select generic root `docs/` or root Markdown docs while `.oat/config.json`
+or `apps/*` Fumadocs evidence identifies an active OAT/Fumadocs docs app. Prefer
+the app declared in `.oat/config.json` when multiple app candidates exist.
 
 Resolve tracking and analysis mode using the shared helper:
 
@@ -109,6 +126,8 @@ Build a complete inventory of:
 - All directories containing Markdown files
 - All `index.md` files
 - Any `overview.md` files
+- Generated root indexes or manifests, including warning banners such as "do not edit"
+- Local guidance that identifies generated index paths or regeneration commands
 - `mkdocs.yml` nav entries when present
 
 Record the docs surface type:
@@ -116,11 +135,16 @@ Record the docs surface type:
 - `mkdocs-app`
 - `docs-tree`
 - `root-markdown`
+- `oat-fumadocs-app`
 
 Capture the evidence sources that will justify later findings and recommendations. Prefer:
 
 - `mkdocs.yml` and generated nav structure
+- `.oat/config.json`, package scripts, generator scripts, and local `AGENTS.md`
+  files that identify authored docs roots or generated root indexes
 - `docs/contributing.md`, contributor guides, and setup docs
+- docs-app `AGENTS.md`, contributing pages, or authoring guides that tell
+  agents how to edit, analyze, apply, and validate docs
 - `package.json` scripts, `requirements.txt`, and docs bootstrap scripts
 - existing `index.md` trees and repeated directory patterns
 - exact missing or stale paths, commands, and page references
@@ -128,6 +152,21 @@ Capture the evidence sources that will justify later findings and recommendation
 Do **not** infer docs structure conventions from a tiny sample of pages when the broader
 tree or config disagrees.
 
+For OAT/Fumadocs docs apps, check whether local guidance covers:
+
+- authored docs source location
+- generated root indexes or manifests and their no-hand-edit boundary
+- every content directory needing `index.md`
+- useful `## Contents` maps
+- `.md`-suffixed relative links, including `subdir/index.md`
+- `.md` as the default format and `.mdx` only for JSX/component needs
+- read-only audit routing to `oat-docs-analyze`
+- approved bulk edits routing to `oat-docs-apply`
+- generated artifact regeneration or freshness checks after source docs changes
+
+Flag stale local guidance that references older aliases without mapping them to
+the current analyze/apply flow.
+
 ### Step 2: Evaluate the `index.md` Contract
 
 Use `references/quality-checklist.md` and `references/directory-assessment-criteria.md`.
@@ -136,9 +175,41 @@ For every documentation directory:
 
 1. Verify `index.md` exists.
 2. Verify `index.md` includes a `## Contents` section.
-3. Verify the `## Contents` section maps sibling pages and immediate child directories.
-4. Flag `overview.md` usage as a migration finding.
-5. Verify single-file directories still expose an `index.md` entrypoint.
+3. Flag placeholder-only `## Contents` sections, including comments, generic
+   "add links here" copy, or empty lists.
+4. Verify the `## Contents` section maps sibling pages and immediate child directories.
+5. Verify parent `## Contents` maps include child directories that contain docs.
+6. Flag `overview.md` usage as a migration finding.
+7. Flag unexpected `.mdx` for plain content unless JSX/components or local
+   guidance justify it.
+8. Verify single-file directories still expose a useful `index.md` entrypoint
+   or local section map.
+9. Exempt asset-only directories that contain no Markdown content and are not
+   linked as navigable docs sections.
+
+For OAT/Fumadocs docs apps, also distinguish authored source maps from generated
+root indexes:
+
+1. Resolve the authored docs source root and generated root index path from
+   `.oat/config.json`, package scripts, generator scripts, or local guidance.
+2. Confirm the generated root index exists when local configuration says it is
+   produced, and record whether it appears tracked, ignored, or local-only.
+3. Confirm generated warning banners are present when the repo's generator emits
+   them or local guidance requires them.
+4. Compare generated entries against the authored `## Contents` graph.
+5. Flag stale generated entries that point to deleted or moved docs paths.
+6. Flag missing generated entries for authored pages or child directories that
+   are reachable from source `## Contents` maps.
+7. Flag generated entries that are not reachable from any authored parent
+   `## Contents` map unless local generator semantics explicitly explain them.
+8. Classify ordering drift separately from missing or stale entries.
+9. If source maps and generated output disagree but generator behavior is not
+   documented well enough to judge, classify the finding as unclear generator
+   semantics instead of guessing.
+
+Generated index checks are read-only. Recommend regeneration, source-map fixes,
+or tool investigation in the analysis artifact; do not hand-edit generated
+files from this skill.
 
 ### Step 3: Assess Quality and Coverage
 
@@ -165,13 +236,28 @@ Evidence standard:
 For each evaluated page or directory:
 
 1. Read the docs file plus the local evidence needed to validate its claims.
-2. Record findings with severity, exact source refs, and confidence.
-3. Decide a disclosure mode for each recommendation:
+2. Resolve every local relative Markdown link from the page where it appears.
+   Flag broken targets. In OAT/Fumadocs docs apps, flag extensionless local
+   Markdown links and prefer `.md`-suffixed targets, including
+   `subdir/index.md`.
+3. Accept anchors on `.md` links, such as `page.md#section`, and do not flag
+   anchors-only, external URLs, `mailto:` links, image/asset links, or link
+   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.
+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
+   signals that make search/navigation output look stale.
+6. Record findings with severity, exact source refs, and confidence.
+7. Decide a disclosure mode for each recommendation:
    - `inline`
    - `link_only`
    - `omit`
    - `ask_user`
-4. Record canonical link targets whenever a `link_only` recommendation is used.
+8. Record canonical link targets whenever a `link_only` recommendation is used.
 
 In `delta` mode, always evaluate changed docs files plus the nearest parent `index.md` pages.
 In `full` mode, evaluate the whole docs surface.
@@ -227,9 +313,32 @@ sources only. Prefer:
 - `app/services/`, `src/services/`, or equivalent business-logic modules
 - the main application entrypoint and route registration files
 - key models, schemas, and config surfaces that define user-facing behavior
+- command definitions, CLI parsers, flag schemas, and command tests
+- deployment, release, monitoring, runbook, rollback, and support/escalation
+  files that define operational behavior
 
 Do not speculate about future roadmap items or undocumented external integrations.
 
+Classify coverage by the surfaces proven in the repo:
+
+- For app/service docs, check purpose, audience, local setup, testing,
+  configuration, deployment/release, observability, runbooks, rollback,
+  ownership, support/escalation, troubleshooting, and common failure modes.
+- For API docs, check whether broad API surfaces have navigable
+  contract-grade reference pages with routes/endpoints, request/response
+  shapes, authentication, error modes, examples, and versioning where those
+  concepts exist in repo sources.
+- For CLI docs, check command groups, flags, output modes, destructive
+  behavior, dry-run/force options, scripting contracts, exit-code behavior when
+  sourced, and examples for common workflows.
+- For operations docs, flag "Future Topics" placeholders, empty runbook
+  outlines, unsupported deploy/monitoring claims, and missing owner-reviewed
+  gaps for unverifiable operations knowledge.
+
+When a claim affects ownership, support, deployment, observability, rollback, or
+external integration behavior and repo evidence cannot verify it, mark it as an
+owner-review gap rather than guessing.
+
 For each significant feature or API capability found in the codebase:
 
 1. Capture the capability area and the evidence that proves it exists.
@@ -261,6 +370,19 @@ where the docs should live, and what specific subtopics the codebase shows shoul
 
 ### Step 6: Check Navigation and Drift
 
+If a generated root index or manifest exists:
+
+1. Compare generated entries with the authored `## Contents` graph.
+2. Flag generated output that is missing, ignored/local-only when local guidance
+   expects a tracked artifact, stale, ordered differently from authored maps, or
+   unclear because generator semantics are undocumented.
+3. Flag generated entries that are not reachable from authored maps as either
+   authored-source contract drift or generator-semantics uncertainty, depending
+   on the evidence.
+4. Cite exact generated paths, authored source paths, package scripts, config
+   files, and representative links for each finding.
+5. Prefer source-of-truth fixes over generated-file edits.
+
 If `mkdocs.yml` exists:
 
 1. Compare nav entries with the docs tree.
@@ -295,6 +417,9 @@ Populate the artifact with:
 - Inventory summary
 - Severity-rated findings
 - Directory coverage and contract gaps
+- Generated index and authored local-map findings
+- Authored link, `## Contents`, and Markdown hygiene findings
+- Local docs-app guidance gaps
 - Accuracy verification verdicts for repo-checkable claims
 - Content opportunities for missing or thin docs coverage
 - Navigation/drift findings
@@ -355,7 +480,7 @@ Output a summary:
 Analysis complete.
 
   Docs target:      {path}
-  Surface type:     {mkdocs-app|docs-tree|root-markdown}
+  Surface type:     {mkdocs-app|oat-fumadocs-app|docs-tree|root-markdown}
   Files evaluated:  {N}
   Mode:             {full|delta}
 

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.