@open-agent-toolkit/cli 0.1.21 → 0.1.22

package/assets/docs/contributing/documentation.md

@@ -12,6 +12,7 @@ Documentation should ship with the code it explains. This page covers the core d
 - Every documentation directory must contain an `index.md`.
 - Each `index.md` must include a `## Contents` section.
 - The `## Contents` section is the machine-readable local map for sibling pages and child directories.
+- Use `.md`-suffixed relative links in `## Contents`: `[Page](page.md)` for leaf pages and `[Section](subdir/index.md)` for child directories.
 
 ## Local workflow
 
@@ -51,7 +52,10 @@ Documentation should ship with the code it explains. This page covers the core d
 
 - Keep docs aligned with the current repo behavior and current command surface.
 - Prefer cross-links over duplicated conceptual content.
-- When you add, remove, or rename docs pages, refresh the generated docs surface:
+- Use `oat-docs-authoring` for targeted OAT/Fumadocs docs edits; it delegates
+  universal page-quality guidance to `authoring-docs` and keeps local
+  navigation, generated-index, and validation expectations in scope.
+- When you add, remove, or rename docs pages, refresh the generated Fumadocs root index. It is a generated file-tree manifest that should be checked against authored `docs/**/index.md` maps, not hand-edited:
 
   ```bash
   pnpm -w run cli -- docs generate-index --docs-dir apps/oat-docs/docs --output apps/oat-docs/index.md
@@ -63,7 +67,7 @@ Documentation should ship with the code it explains. This page covers the core d
 
 - Treat `index.md` plus its `## Contents` section as the local discovery source of truth.
 - Prefer linking to source files and commands explicitly when documenting behavior.
-- Regenerate the docs surface index after adding or removing pages.
+- Regenerate or freshness-check the docs surface index after adding, removing, renaming, or reordering pages.
 
 ## Related Guides
 

package/assets/docs/docs-tooling/add-docs-to-a-repo.md

@@ -46,9 +46,10 @@ Legacy pack-specific path:
 oat init tools docs
 ```
 
-The docs pack installs `oat-docs-analyze`, `oat-docs-apply`,
-`oat-agent-instructions-analyze`, and `oat-agent-instructions-apply`. For this
-quickstart, the docs pair is the part you need immediately.
+The docs pack installs `authoring-docs`, `oat-docs-authoring`,
+`oat-docs-analyze`, `oat-docs-apply`, `oat-agent-instructions-analyze`, and
+`oat-agent-instructions-apply`. For this quickstart, the authoring and docs
+analysis/apply skills are the parts you need immediately.
 
 ## 3. Scaffold the docs app
 
@@ -76,7 +77,7 @@ What the skill adds over the raw CLI:
 - **Build verification.** Runs install + build, classifies failures against known patterns, stops on unknown errors rather than guessing.
 - **Config inspection.** Reads `.oat/config.json` back, verifies paths exist on disk, handles the nested-standalone dual-config case, and collects the `requireForProjectCompletion` opt-in explicitly.
 - **Root-build explanation.** When the CLI safely patches a compatible Turbo root `build` script, the walkthrough explains why the filter was added, shows the diff shape, and documents how to adjust or revert it. When the CLI skips the patch, the walkthrough relays the recommended manual snippet.
-- **Educational walkthrough.** Seven sections covering the `documentation` config, the two-`index.md` model, the `## Contents` contract (with extension discipline), the three agent-instruction surfaces (root `AGENTS.md` pointer / docs-app `AGENTS.md` / `docs/contributing.md`), Fumadocs internals (or MkDocs Minimum Contract), and the OAT docs ecosystem (`oat-project-document`, `oat-docs-analyze`, `oat-docs-apply`).
+- **Educational walkthrough.** Seven sections covering the `documentation` config, the authored-source/generated-navigation model, the `## Contents` contract (with extension discipline), the three agent-instruction surfaces (root `AGENTS.md` pointer / docs-app `AGENTS.md` / `docs/contributing.md`), Fumadocs internals (or MkDocs Minimum Contract), and the OAT docs ecosystem (`oat-project-document`, `oat-docs-analyze`, `oat-docs-apply`).
 - **Optional content kickoff.** Hands off to `oat-docs-analyze` + `oat-docs-apply` if you want to populate initial repo-specific content immediately.
 
 Capability-gated: every post-patch self-ratchets off as CLI fixes land upstream. The skill's labeled markers (`<!-- FP-NN patch -->`) are how you find them later when the CLI catches up.
@@ -115,25 +116,32 @@ root `build:docs` script is available for docs-only builds. Use
 `--no-root-patch` to opt out, or `--dry-run` to preview the diff without
 writing it.
 
-## 3a. Migrating from MkDocs (optional)
+### 3c. Existing MkDocs content
 
-If you have an existing MkDocs site and want to switch to Fumadocs, use the
-migration command after scaffolding:
+Bootstrap is not the migration workflow. If you have an existing MkDocs site
+and want to switch to Fumadocs, treat that as a separate migration workstream.
+The CLI migration helper can convert common Markdown syntax and frontmatter:
 
 ```bash
 oat docs migrate --docs-dir docs --config mkdocs.yml --apply
 ```
 
-This converts MkDocs admonitions to GFM callouts and injects frontmatter
-metadata. Run without `--apply` first to preview changes.
+Run without `--apply` first to preview changes. For a full MkDocs-to-Fumadocs
+refactor, use the assigned migration handoff guide or project plan; do not make
+`oat-docs-bootstrap` own that migration.
 
 ## 4. Start authoring docs with the OAT contract
 
+Use `oat-docs-authoring` for targeted OAT/Fumadocs content edits or local
+restructuring. It uses `authoring-docs` for the portable documentation baseline
+and adds the OAT-specific navigation, generated-index, and validation contract.
+
 Core rules:
 
 - every docs directory should have an `index.md`
 - every `index.md` should include a `## Contents` section
 - the `## Contents` section should map sibling pages and immediate child directories
+- `## Contents` links should use `.md`-suffixed relative targets, including `subdir/index.md` for child directories
 
 For **MkDocs** apps, regenerate navigation after adding or moving pages:
 
@@ -141,16 +149,18 @@ For **MkDocs** apps, regenerate navigation after adding or moving pages:
 oat docs nav sync --target-dir apps/my-docs
 ```
 
-For **Fumadocs** apps, the docs index is generated automatically via
-`predev`/`prebuild` hooks. You can also run it manually:
+For **Fumadocs** apps, the app-root docs index manifest is generated from the
+Markdown file tree automatically via `predev`/`prebuild` hooks. You can also
+run it manually:
 
 ```bash
 oat docs generate-index --docs-dir docs
 ```
 
 The generated app-root `index.md` is machine-owned and now starts with an
-`AUTOGENERATED` warning comment. Edit authored pages under `docs/`, not the
-generated root index.
+`AUTOGENERATED` warning comment. Edit authored pages and `## Contents` maps
+under `docs/`, then compare the generated manifest against those maps when
+checking freshness.
 
 ## 5. Analyze the docs surface
 
@@ -193,7 +203,7 @@ Important:
 1. `oat init --scope project`
 2. `oat tools install docs`
 3. `oat docs init --app-name my-docs`
-4. (optional) `oat docs migrate --docs-dir docs --config mkdocs.yml --apply`
+4. (optional) handle MkDocs migration as a separate workstream; use `oat docs migrate --docs-dir docs --config mkdocs.yml --apply` only for the syntax/frontmatter helper
 5. Author docs with `index.md` + `## Contents`
 6. `oat docs nav sync --target-dir apps/my-docs` (MkDocs) or `oat docs generate-index` (Fumadocs)
 7. `/oat-docs-analyze`

package/assets/docs/docs-tooling/commands.md

@@ -1,6 +1,6 @@
 ---
 title: Docs App Commands
-description: 'Docs scaffolding CLI surface for Fumadocs/MkDocs, migration, index generation, and nav sync.'
+description: 'Docs scaffolding CLI surface for Fumadocs/MkDocs, migration helpers, Fumadocs index generation, and MkDocs nav sync.'
 ---
 
 # Docs App Commands
@@ -11,20 +11,20 @@ and **MkDocs Material**.
 
 ## Quick Look
 
-- What it does: documents the docs-specific CLI surface for scaffolding apps, migrating markdown, generating indexes, and syncing navigation.
+- What it does: documents the docs-specific CLI surface for scaffolding apps, migrating markdown, generating Fumadocs app-root index manifests, and syncing MkDocs navigation.
 - When to use it: when you already know you are working on a docs surface and need the exact command-level behavior.
 - Primary commands: `oat docs init`, `oat docs migrate`, `oat docs generate-index`, `oat docs nav sync`
 
 ## Command surface
 
-| Command                   | Purpose                                                                              |
-| ------------------------- | ------------------------------------------------------------------------------------ |
-| `oat docs init`           | Scaffold a new docs app (Fumadocs or MkDocs).                                        |
-| `oat docs migrate`        | Convert MkDocs admonitions to GFM callouts and inject frontmatter.                   |
-| `oat docs generate-index` | Generate a docs index from the markdown file tree.                                   |
-| `oat docs nav sync`       | Regenerate `mkdocs.yml` navigation from directory `index.md` `## Contents` sections. |
-| `oat docs analyze`        | CLI entrypoint that points users to the `oat-docs-analyze` skill.                    |
-| `oat docs apply`          | CLI entrypoint that points users to the `oat-docs-apply` skill.                      |
+| Command                   | Purpose                                                                       |
+| ------------------------- | ----------------------------------------------------------------------------- |
+| `oat docs init`           | Scaffold a new docs app (Fumadocs or MkDocs).                                 |
+| `oat docs migrate`        | Convert MkDocs admonitions to GFM callouts and inject frontmatter.            |
+| `oat docs generate-index` | Generate a Fumadocs app-root docs index manifest from the Markdown file tree. |
+| `oat docs nav sync`       | Regenerate MkDocs `mkdocs.yml` navigation from directory `index.md` maps.     |
+| `oat docs analyze`        | CLI entrypoint that points users to the `oat-docs-analyze` skill.             |
+| `oat docs apply`          | CLI entrypoint that points users to the `oat-docs-apply` skill.               |
 
 ## `oat docs init`
 
@@ -109,9 +109,10 @@ oat docs migrate --docs-dir docs --config mkdocs.yml --apply
 
 ## `oat docs generate-index`
 
-Use `oat docs generate-index` to produce a markdown index from the docs file
-tree. The generated index lists all pages with titles and descriptions, organized
-by directory structure.
+Use `oat docs generate-index` to produce a generated Markdown manifest from the
+docs file tree. In Fumadocs apps this is the app-root `index.md`, outside the
+authored `docs/` source tree. The generated index lists all pages with titles
+and descriptions, organized by directory structure.
 
 Key behavior:
 
@@ -121,6 +122,7 @@ Key behavior:
 - outputs to app root (`index.md`) by default, not inside the docs directory
 - updates `documentation.index` in `.oat/config.json`
 - prepends an `AUTOGENERATED` warning comment to the output and rewrites the file on every run; do not hand-edit the generated `index.md`
+- should be freshness-checked against authored `docs/**/index.md` `## Contents` maps before treating it as navigation evidence
 - sorting: `index.md` first, then directories before files, then lexical
 
 Supported flags:
@@ -139,7 +141,7 @@ script hooks.
 
 ## `oat docs nav sync`
 
-Use nav sync after adding, removing, or renaming docs pages.
+Use nav sync for MkDocs apps after adding, removing, or renaming docs pages.
 
 The command reads only the reserved `## Contents` section from each directory
 `index.md` and regenerates the `nav:` block in `mkdocs.yml`.

package/assets/docs/docs-tooling/workflows.md

@@ -17,12 +17,18 @@ Install the workflow skills with `oat tools install docs` (preferred) or
 
 - `oat docs init` scaffolds a docs app (Fumadocs or MkDocs)
 - `oat docs migrate` converts MkDocs admonitions to GFM callouts and injects frontmatter
-- `oat docs generate-index` generates a docs index from the markdown file tree
-- `oat docs nav sync` regenerates mkdocs.yml nav from `index.md` `## Contents` sections
+- `oat docs generate-index` generates a Fumadocs app-root docs index manifest from the Markdown file tree
+- `oat docs nav sync` regenerates MkDocs `mkdocs.yml` nav from `index.md` `## Contents` sections
 - `oat docs analyze` and `oat docs apply` expose the workflow surface in CLI help
 
 ### Skills
 
+- `authoring-docs` is the provider-agnostic baseline for evidence-first
+  technical documentation: page types, information architecture, category
+  guidance, templates, and review rubrics
+- `oat-docs-authoring` layers the OAT/Fumadocs docs-app contract on top of
+  `authoring-docs` for targeted authoring, restructuring, link repair, and
+  local navigation maintenance inside an existing OAT docs app
 - `oat-docs-bootstrap` is the guided onramp for adding a docs app to a repo —
   wraps `oat docs init` with preflight detection, richer input gathering (site
   name distinct from package name), labeled post-patches for open CLI gaps,
@@ -55,15 +61,16 @@ skills.
 ## Typical flow
 
 1. Bootstrap a docs app with `oat-docs-bootstrap` (preferred — guided, includes post-scaffold patches and walkthrough) or `oat docs init` directly (CLI-only / non-interactive workflows)
-2. (Optional) If migrating from MkDocs: `oat docs migrate --docs-dir docs --config mkdocs.yml --apply`
-3. Author docs so every directory has an `index.md` with a `## Contents` section
-4. Keep local `## Contents` sections current
-5. Sync navigation:
+2. (Optional) If migrating from MkDocs, handle that as a separate migration workstream; `oat docs migrate --docs-dir docs --config mkdocs.yml --apply` is only the syntax/frontmatter helper
+3. Use `oat-docs-authoring` for targeted OAT/Fumadocs authoring work, with `authoring-docs` as the universal documentation-quality baseline
+4. Author docs so every directory has an `index.md` with a `## Contents` section
+5. Keep local `## Contents` sections current
+6. Refresh generated artifacts:
    - **MkDocs:** `oat docs nav sync`
    - **Fumadocs:** `oat docs generate-index` (runs automatically via `predev`/`prebuild` hooks)
-6. Run `oat-docs-analyze`; by default it verifies the generated analysis artifact
+7. Run `oat-docs-analyze`; by default it verifies the generated analysis artifact
    through `workflow.autoArtifactReview.analysis`
-7. Review the artifact and run `oat-docs-apply`
+8. Review the artifact and run `oat-docs-apply`
 
 ## Progressive disclosure
 

package/assets/docs/reference/docs-index-contract.md

@@ -1,17 +1,19 @@
 ---
 title: Docs Index Contract
-description: 'Navigation generation contract: index.md format and authoring guidance.'
+description: 'Docs source contract: authored index.md maps, generated Fumadocs manifests, and MkDocs nav sync.'
 ---
 
 # Docs Index Contract
 
-OAT docs navigation is generated from each directory `index.md`, not from hand-maintained `mkdocs.yml` trees.
+OAT docs navigation starts from authored `docs/**/index.md` files. Each `## Contents` section is the local source of truth for sibling pages and child directories. Generated artifacts are derived from docs source and should not be edited directly.
 
 ## Rules
 
 - Every documentation directory must contain an `index.md`.
 - Every `index.md` must include a `## Contents` section.
-- The `## Contents` section is the only machine-readable source used by `oat docs nav sync`.
+- Every `## Contents` link should use a `.md`-suffixed relative target, including child directory links such as `subdir/index.md`.
+- For Fumadocs, refresh or freshness-check the generated app-root manifest after adding, removing, or renaming Markdown files. Compare that manifest against authored `## Contents` maps for drift; reordering `## Contents` does not reorder the generated manifest's file-tree sort.
+- For MkDocs, run `oat docs nav sync` after adding, removing, renaming, or reordering pages. It regenerates `mkdocs.yml` from authored `## Contents` maps and preserves the order declared in each local map.
 
 ## `## Contents` format
 
@@ -28,23 +30,43 @@ Notes:
 
 - Links after `## Contents` can include short human-readable descriptions.
 - Child directories should link to their `index.md`.
+- Leaf pages should link to their `.md` filename.
 - Prose outside `## Contents` is ignored by nav generation and remains freeform.
 
 ## Navigation generation
 
-`oat docs nav sync --target-dir <docs-app-dir>` walks the docs tree from `docs/index.md` downward and regenerates `mkdocs.yml` `nav` entries from the discovered `index.md` files.
+Fumadocs and MkDocs use the same authored source, but they do not use the same generated artifact.
+
+For Fumadocs docs apps, `oat docs generate-index` walks the Markdown file tree under `docs/` and writes the app-root generated manifest, for example `apps/oat-docs/index.md`.
+
+```bash
+pnpm -w run cli -- docs generate-index --docs-dir apps/oat-docs/docs --output apps/oat-docs/index.md
+```
+
+For MkDocs docs apps, `oat docs nav sync --target-dir <docs-app-dir>` walks the docs tree from `docs/index.md` downward and updates the `nav:` entries in `mkdocs.yml`.
 
 Generated behavior:
 
 - Root `docs/index.md` becomes `Home`.
 - Child directory `index.md` files become section landing pages.
-- Nested entries are emitted in the order they appear under each local `## Contents` block.
+- Fumadocs generated entries are ordered by the file-tree generator: `index.md` first, directories before files, then lexical order.
+- MkDocs nested entries are emitted in the order they appear under each local `## Contents` block.
+- Fumadocs generated manifests should carry an autogen warning and are rewritten by `predev` / `prebuild`.
+- MkDocs `mkdocs.yml` may contain other configuration, but its `nav:` block is derived from authored `## Contents`.
+
+## Generated-file boundaries
+
+- Edit authored files under `docs/`, especially the nearest `index.md` and `## Contents`.
+- Do not hand-edit a Fumadocs app-root generated `index.md`; regenerate it from the docs source tree.
+- Do not hand-maintain MkDocs `nav:` entries when the local workflow uses `oat docs nav sync`.
+- If a Fumadocs generated manifest lists pages that are missing from authored `## Contents`, treat that as authored-source drift or intentional generator-inventory behavior to verify before relying on the generated file as navigation evidence.
 
 ## Authoring guidance
 
 - Use `index.md` as the local discovery surface for humans and agents.
 - Add a short topic description next to each link so agents can choose the right file without opening every page.
-- Update `## Contents` whenever you add, remove, or rename docs files in a directory.
+- Update `## Contents` whenever you add, remove, rename, or reorder docs files in a directory.
+- Refresh or freshness-check the generated artifact before committing structural docs changes.
 
 ## If You Are Trying To...
 

package/assets/docs/reference/index.md

@@ -13,7 +13,7 @@ Contributor how-to material now lives under `contributing/`, and user-facing rou
 
 - [CLI Reference](cli-reference.md) - Shallow map of the OAT command surface with links to owning sections.
 - [File Locations](file-locations.md) - Where core OAT files, assets, and artifacts live.
-- [Docs Index Contract](docs-index-contract.md) - Rules for directory `index.md` files and reserved `## Contents` sections.
+- [Docs Index Contract](docs-index-contract.md) - Authored `index.md` maps, `.md` links, generated Fumadocs manifests, and MkDocs nav sync boundaries.
 - [OAT Directory Structure](oat-directory-structure.md) - Canonical `.oat/` tree map and the role of each major directory.
 - [Troubleshooting](troubleshooting.md) - Common issues, diagnostics, and remediation guidance.
 

package/assets/docs/workflows/projects/implementation-execution.md

@@ -29,7 +29,7 @@ The approval decision covers both phase implementation and checkpoint review for
 
 The selected tier is reported to the user and locked for the remainder of the run:
 
-```
+```text
 [preflight] Checking subagent availability…
   → oat-phase-implementer + oat-reviewer: available
   → Selected: Tier 1 — Subagents

package/assets/docs/workflows/skills/index.md

@@ -23,7 +23,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
 - Run or receive reviews: `oat-project-review-provide`, `oat-project-review-receive`, or the non-project review variants
 - Capture a scoped, shippable backlog item: `oat-pjm-add-backlog-item` directly when the work is already scoped, or `oat-brainstorm` when the thought hasn't converged yet — the brainstorm dispatcher's "scoped backlog item" destination pre-fills the title / description / acceptance criteria / scope estimate / priority from the conversation and then runs `oat-pjm-add-backlog-item` with confirmed inputs
 - Manage the repo backlog and reference docs: `oat-pjm-update-repo-reference`, `oat-pjm-review-backlog`
-- Work on docs surfaces: `oat-docs-bootstrap` (guided bootstrap of a new docs app), `oat-docs-analyze`, `oat-docs-apply`, and `oat-project-document`
+- Work on docs surfaces: `authoring-docs` (general documentation baseline), `oat-docs-authoring` (targeted OAT/Fumadocs authoring), `oat-docs-bootstrap` (guided bootstrap of a new docs app), `oat-docs-analyze`, `oat-docs-apply`, and `oat-project-document`
 - Generate a shipping digest or scheduled recap: `oat-wrap-up`
 - Research a topic in depth: `deep-research`
 - Analyze an artifact, codebase, or document: `analyze`
@@ -83,6 +83,8 @@ Use this section when you want to choose the right OAT skill for a task. If you
 
 === "Docs and instructions"
 
+    - `authoring-docs`
+    - `oat-docs-authoring`
     - `oat-docs-bootstrap`
     - `oat-docs-analyze`
     - `oat-docs-apply`

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.21",
-  "docs-config": "0.1.21",
-  "docs-theme": "0.1.21",
-  "docs-transforms": "0.1.21"
+  "cli": "0.1.22",
+  "docs-config": "0.1.22",
+  "docs-theme": "0.1.22",
+  "docs-transforms": "0.1.22"
 }

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

@@ -0,0 +1,135 @@
+---
+name: authoring-docs
+version: 1.0.0
+description: Use when creating, restructuring, migrating, auditing, or reviewing technical documentation for software projects. Provides evidence-first, provider-portable Markdown authoring standards.
+argument-hint: '[docs task or target path]'
+disable-model-invocation: false
+allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
+user-invocable: true
+---
+
+# Authoring Docs
+
+Use this skill to produce technical documentation that is grounded in the
+repository, useful to humans, and explicit enough for future agents.
+
+The prime directive is simple: do not write plausible docs. Extract truth from
+code, configuration, schemas, tests, CI, deployment files, and existing docs;
+then organize that truth around reader tasks.
+
+## When to Use
+
+Use when:
+
+- Creating or improving docs for a software repository.
+- Migrating existing docs into a clearer Markdown structure.
+- Auditing docs for missing, stale, duplicated, or risky content.
+- Writing API, CLI, app, service, library, framework, architecture, operations,
+  or internal/public docs.
+- Reviewing a documentation change for accuracy, usefulness, or safety.
+
+## When NOT to Use
+
+Do not use by itself when:
+
+- The user only asks for copy editing that does not require repository evidence.
+- A repository-specific docs framework contract is the main problem; load the
+  local skill or instruction set alongside this baseline.
+- Generated reference output must be regenerated from a tool; run the generator
+  first and use this skill for review and surrounding prose.
+- Legal, policy, marketing, or brand copy needs domain-specific approval outside
+  the repository.
+
+## Workflow
+
+### Step 1: Resolve Scope and Evidence
+
+Identify the docs target, intended reader, and source of truth before editing.
+Inspect local instructions, existing docs, source files, config, schemas, tests,
+CI, deployment files, and scripts that support the claims you plan to make.
+
+Never invent commands, environment variables, endpoints, fields, deployment
+steps, ownership, escalation paths, compatibility promises, or security
+behavior. Mark useful but unverified facts as needing confirmation.
+
+### Step 2: Classify the Project and Reader Task
+
+Classify the project type and docs category: API, CLI, frontend app, backend
+service, worker, library, framework, monorepo, architecture, operations, or
+mixed. Identify the reader's job: first success, task completion, exact lookup,
+system understanding, safe operation, or review. Load
+`references/categories.md` when category-specific coverage matters.
+
+### Step 3: Choose the Right Page Type
+
+Use one primary page type per page:
+
+- Tutorial: first successful path.
+- How-to guide: complete one task.
+- Reference: exact facts and contracts.
+- Explanation: mental model, design, and tradeoffs.
+- Runbook: operational recovery with checks, mitigation, and verification.
+
+Small supporting sections are fine, but keep the page's primary job clear.
+
+### Step 4: Structure the Docs
+
+Prefer predictable information architecture: landing page, getting started,
+how-to guides, reference, concepts, and operations. Preserve useful existing
+intent, remove duplication, and avoid creating parallel docs when an existing
+page can be improved.
+
+### Step 5: Write Direct, Verifiable Markdown
+
+Use plain language, active voice, specific nouns, exact file paths, exact
+commands, code block language identifiers, expected output, and useful links.
+Document prerequisites, verification, rollback for risky operations, and
+uncertainty.
+
+### Step 6: Verify and Handoff
+
+Run relevant validation commands when available: docs build, link check, tests
+for generated examples, formatters, or local preview. In the final handoff,
+summarize files changed, sources inspected, verification run, unresolved facts,
+and recommended follow-ups.
+
+## Reference Map
+
+Load only the references needed for the current task:
+
+- `references/principles.md`: core documentation principles.
+- `references/workflow.md`: evidence gathering and writing workflow.
+- `references/information-architecture.md`: docs structure, naming, and links.
+- `references/page-types.md`: tutorial, how-to, reference, explanation, and
+  runbook guidance.
+- `references/categories.md`: API, CLI, app, service, library, framework,
+  monorepo, architecture, operations, and audience-specific guidance.
+- `references/writing-style.md`: plain technical writing and Markdown rules.
+- `references/templates.md`: reusable page and handoff templates.
+- `references/review-rubric.md`: readiness checklist and review rubric.
+
+## Examples
+
+Basic usage:
+
+```txt
+/authoring-docs docs/
+```
+
+Conversational triggers:
+
+```txt
+Audit this repo's docs and identify missing pages.
+Create a getting-started guide grounded in the package scripts.
+Improve the CLI reference without inventing flags or exit codes.
+Review this runbook for operational safety.
+```
+
+## Success Criteria
+
+- Claims are grounded in repository evidence or marked as uncertain.
+- The reader can complete the intended task without tribal knowledge.
+- Page type, location, and navigation are clear.
+- Commands, examples, paths, options, and references are accurate.
+- Risky operations include verification and rollback.
+- Internal-only or sensitive information is handled appropriately.