@open-agent-toolkit/cli 0.3.12 → 0.3.14

package/assets/docs/workflows/waves/wave-workflows.md

@@ -0,0 +1,206 @@
+---
+title: Wave Workflows
+description: How OAT coordinates a corpus of external plans into waves while preserving project-lifecycle ownership and human judgment.
+---
+
+# Wave Workflows
+
+A wave is a program layer above the per-project OAT lifecycle. It groups external implementation plans into an ordered delivery unit, then runs that unit as a wrapper OAT project. The wrapper uses the normal project lifecycle rather than replacing it.
+
+Use wave workflows when a plan corpus is too large to execute as one project and needs durable sequencing across multiple projects, worktree groups, and merges.
+
+Terms used on this page:
+
+- **Wave:** one ordered batch of external implementation plans that is executed and merged together.
+- **Wrapper project:** the ordinary quick-mode OAT project that `oat-wave-execute` creates to run one wave. Its plan points to the wave's source plans.
+- **Worktree:** a separate Git checkout of the same repository on its own branch, so parallel lanes do not overwrite each other's files.
+- **Active project:** the project your checkout currently points to, stored as `activeProject` in `.oat/config.local.json`.
+- **Orchestrator:** the root agent session (with you) that makes the judgment calls the skills leave open.
+
+## The Two Wave Skills
+
+The workflow pack provides two complementary skills:
+
+- `oat-wave-program` 1.5.3 maintains the durable execution-program artifact over the full plan corpus. Its `new` mode inventories the corpus, verifies the coverage invariant, and records the orchestrator-composed, operator-approved first program; `refresh` adds newly landed plans to the artifact and records the orchestrator's re-composition of waves not yet started; and `wave-close` records a completed wave. Composing waves is the orchestrating agent's judgment; the skill records the result.
+- `oat-wave-execute` 1.9.5 runs one wave. It owns the repeatable mechanical layer: wrapper-project scaffolding, branch conventions, worktree bootstrap, briefs, gates, merge choreography, bookkeeping cadence, and closeout order.
+
+`oat-wave-program` records which plans belong to each wave. `oat-wave-execute` consumes that mapping and executes one wave through the project lifecycle.
+
+## Mechanical Work and Judgment
+
+The ownership split is load-bearing. The skills automate mechanics, but the orchestrator retains judgment.
+
+The skills own:
+
+- integration and phase branch naming
+- wrapper-project scaffolding
+- worktree bootstrap
+- merge choreography
+- artifact and ledger bookkeeping
+- repeatable verification and closeout sequencing
+
+The orchestrator owns:
+
+- wave and parallel-group composition
+- review-finding dispositions
+- verification of load-bearing worker claims
+- merge-order decisions under live drift
+- cross-lane and end-of-run synthesis
+- all user checkpoints
+
+Do not treat a generated grouping or a mechanically successful lane as a substitute for these decisions.
+
+## Composition With Project Implementation
+
+Each wave is scaffolded as a quick-mode wrapper project. Its plan points to the source plans while preserving their requirements, and `oat-project-implement` remains the lifecycle owner for phase execution, independent review, bounded fixes, checkpoints, and project state.
+
+For plan-declared parallel groups, `oat-wave-execute` invokes its bundled `scripts/bootstrap-group.sh` helper. The helper wraps the standard worktree bootstrap flow, creates phase worktrees at an explicit base, initializes each worktree, checks provider-view parity, and reports structured status. `oat-project-implement` then dispatches and verifies each phase in its assigned worktree. The wave layer owns the serialized fan-in and integration gates after those phases pass.
+
+This composition keeps the responsibilities separate:
+
+1. `oat-wave-program` records the program and wave membership.
+2. `oat-wave-execute` scaffolds and coordinates one wrapper project.
+3. `oat-project-implement` executes that project's phases.
+4. `oat-wave-program wave-close` updates the durable program after the wave merges.
+
+## Execution-Program Artifact Format
+
+The execution-program artifact is durable reference material under `.oat/repo/reference/external-plans/`. It is not an executable plan or an `oat-project-import-plan` target.
+
+The current format contains:
+
+- **Wave table:** one row per source plan, including its link, source index, assigned wave, ordering or dependency notes, and status (`pending`, `in-wave`, `done`, `deferred`, or `dropped`).
+- **Coverage invariant:** every plan in every source plan index appears in exactly one row. A deferred or dropped plan includes a reason and re-entry trigger; an omitted plan is an error.
+- **Wave sections:** the theme, lane list, intra-wave ordering, and cross-wave prerequisites for each wave.
+- **Status ledger:** each wave advances from composed to in-progress to merged, with the wrapper-project link, PR, merge SHA, and completion-record link recorded as they become available.
+
+> **Important:** This format is documented as a description, not a stable contract. Two related pieces of work are planned but not yet done: documenting the execution-program artifact as a stable OAT contract, and adding an `oat wave` family of lifecycle CLI commands.
+
+Until that grouped work ships, consumers should follow the bundled skill and template rather than depending on an independently versioned schema.
+
+## oat-wave-program
+
+Use program to record which external plans belong in each wave. The
+orchestrator composes the waves and retains dependency, risk, and concurrency
+judgment. The skill maintains the inventory and approved result.
+
+**Invocation:** Select `new`, `refresh`, or `wave-close <wave-id>` as the
+situation requires. With no mode, the skill runs `refresh` against the current
+artifact. These are agent-skill requests, not `oat` CLI commands. Providers
+with `$` syntax use `$oat-wave-program` instead of the slash name.
+
+```text
+/oat-wave-program new
+```
+
+```text
+/oat-wave-program refresh
+```
+
+```text
+/oat-wave-program wave-close wave-2
+```
+
+**Prerequisites:** Needs an active OAT project: no. New mode needs the external
+plan indexes and their actual plan files.
+Refresh needs the live execution-program artifact and current indexes.
+Wave-close needs the completed wave's merge and completion evidence. Missing
+indexed files stop the flow rather than being guessed from names.
+
+**What it does without asking:** every mode writes the execution-program
+artifact and commits it. New mode shows you the proposed wave map and waits
+for your approval before the first wave starts. When the final wave merges,
+the skill stops at one human-gated checkpoint that asks whether to run the
+deferred completion tail (archive, S3 upload, and active-project clear) for
+every wave's wrapper project; autonomous runs never answer that question
+themselves.
+
+**Example scenario:** Twelve reviewed external plans include a shared API
+foundation, client changes, and independent documentation work. Use `new` to
+inventory every indexed plan and record an operator-approved sequence. When
+three more plans arrive, use `refresh` to recompose only unstarted waves. After
+wave two merges, use `wave-close wave-2` to record that boundary instead of
+inventing another execution program.
+
+**Expected output:** A dated execution-program artifact under
+`.oat/repo/reference/external-plans/`, with exactly one row per indexed plan,
+explicit deferral reasons, ordered waves, dependencies, and a current status
+ledger. Started waves cannot be reshuffled, and merged membership is frozen
+history. Plan rows can become `done`; wave-ledger states are `composed`,
+`in-progress`, and `merged`.
+
+At final program close, recap and deferred wrapper completion receive explicit
+dispositions. The completion-tail checkpoint remains human-gated, including
+autonomous runs. Program bookkeeping is not an executable project plan or an
+import target.
+
+**Next step:** Invoke `oat-wave-execute` for an approved wave. Record each merge
+through wave-close, and resolve any program-end completion deferral with its
+named owner.
+
+## oat-wave-execute
+
+Use execute for one wave, not for composing the whole corpus. It prepares and
+coordinates a quick wrapper project while the normal project lifecycle owns
+phase implementation and review.
+
+**Invocation:** Name the wave. Its lanes normally resolve from the live program
+artifact, with plan-index hints used only when no program exists. You can also
+list specific plan names after the wave ID.
+
+```text
+/oat-wave-execute wave-2
+```
+
+**Prerequisites:** Needs an active OAT project: no. The skill creates the
+wrapper project itself and makes it the active project, which replaces any
+project that was active before. Start from an up-to-date `main` with a clean
+working tree. The named source plans must exist, and their drift checks must
+allow the lanes to proceed. You also need worktree tooling, reviewer
+capabilities, and permission for the Git operations listed below. The default
+concurrency ceiling is three worktrees at a time, and the operator can change
+it.
+
+**What it does without asking:** running this skill authorizes all of the
+following. It creates the `wave-N-execution` branch from `main`, installs
+dependencies, and runs the repository's build and type checks. It scaffolds
+the wrapper project and commits it. It dispatches a read-only recon subagent,
+creates one worktree per parallel lane on a `wave-N/pNN` branch, and, through
+`oat-project-implement`, dispatches implementer and reviewer subagents in
+those worktrees. It merges passing lane branches into `wave-N-execution` with
+`git merge --no-ff`, then deletes the merged worktrees and their branches. At
+closeout it archives the wave's backlog items with `oat backlog archive` and
+runs the configured closeout sequence (which can open the PR). It then stops
+once at a HiLL (human-in-the-loop) approval checkpoint before running the
+`oat-project-complete` process, including project archive and any configured
+S3 upload. After you merge the wave, it resets the working branch, deletes
+stale phase branches, and runs `oat-wave-program wave-close`. Merging the wave
+into `main` stays your decision.
+
+**Example scenario:** The approved second wave contains client changes after
+its API foundation merged. Execute refreshes drift against the current base,
+intersects every plan's write set, and records safe groups in the wrapper plan.
+Overlapping files force separate groups even when the plans looked independent
+when authored. Choose execute rather than program because wave membership is
+already approved and now needs verified delivery.
+
+**Expected output:** A `wave-N-execution` wrapper with source-plan pointers,
+drift evidence, a plan, discovery, and an orchestration log. Passing lanes produce
+verified task commits and review dispositions in isolated worktrees. Serialized
+fan-in is followed by integration gates, so individual lane passes are not
+presented as proof the integrated tree passes.
+
+Closeout writes end-of-run synthesis before archive work. Autonomous execution
+can defer a wrapper's archive tail to program close only with an explicit
+ledger disposition. That deferral does not satisfy the full completion tail.
+Source-plan requirements remain intact even when live drift changes a mechanism.
+
+**Next step:** Follow the wave's reported review and merge boundary. After the
+operator merges, reconcile the result and invoke program wave-close. Do not mark
+an unmerged wave `merged` or treat a deferred archive as completed.
+
+## Related
+
+- [Project lifecycle](../projects/lifecycle.md)
+- [Implementation execution](../projects/execution/implementation-execution.md)
+- [Project artifacts](../../reference/project-artifacts.md)

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.3.12",
-  "docs-config": "0.3.12",
-  "docs-theme": "0.3.12",
-  "docs-transforms": "0.3.12"
+  "cli": "0.3.14",
+  "docs-config": "0.3.14",
+  "docs-theme": "0.3.14",
+  "docs-transforms": "0.3.14"
 }

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

@@ -6,7 +6,7 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.0.3
+  version: 1.0.4
 ---
 
 # OAT Docs
@@ -91,21 +91,21 @@ Read the user's question from `$ARGUMENTS`. If no question was provided or the q
 
 Classify the question into one or more topic areas to guide the search:
 
-| Topic Area       | Docs Path                                   | Key Content                                  |
-| ---------------- | ------------------------------------------- | -------------------------------------------- |
-| Getting started  | `quickstart.md`, `guide/getting-started.md` | Installation, first project setup            |
-| Concepts         | `guide/concepts.md`                         | Core OAT concepts and terminology            |
-| CLI commands     | `guide/cli-reference.md`                    | Full CLI command reference                   |
-| Tool packs       | `guide/tool-packs.md`                       | Installing and managing skill packs          |
-| Skills           | `guide/skills/`                             | Skill authoring, SKILL.md format             |
-| Workflows        | `guide/workflow/`                           | Project lifecycle, state machine, artifacts  |
-| Ideas            | `guide/ideas/`                              | Idea capture and brainstorming               |
-| Provider sync    | `guide/provider-sync/`                      | Multi-provider sync, config, commands        |
-| Documentation    | `guide/documentation/`                      | Docs analysis and apply workflows            |
-| Contributing     | `contributing/`                             | Code contributions, design principles, hooks |
-| File locations   | `reference/file-locations.md`               | Where OAT puts things                        |
-| Directory layout | `reference/oat-directory-structure.md`      | `.oat/` and `.agents/` structure             |
-| Troubleshooting  | `reference/troubleshooting.md`              | Common issues and fixes                      |
+| Topic Area       | Docs Path                                                       | Key Content                                  |
+| ---------------- | --------------------------------------------------------------- | -------------------------------------------- |
+| Getting started  | `getting-started/quickstart.md`, `getting-started/bootstrap.md` | Installation, first project setup            |
+| Concepts         | `getting-started/concepts.md`                                   | Core OAT concepts and terminology            |
+| CLI commands     | `reference/cli-reference.md`                                    | Full CLI command reference                   |
+| Tool packs       | `getting-started/tool-packs.md`                                 | Installing and managing skill packs          |
+| Skills           | `contributing/skills.md`                                        | Skill authoring, SKILL.md format             |
+| Workflows        | `workflows/projects/`                                           | Project lifecycle, state machine, artifacts  |
+| Ideas            | `workflows/ideas/`                                              | Idea capture and brainstorming               |
+| Provider sync    | `provider-sync/`                                                | Multi-provider sync, config, commands        |
+| Documentation    | `docs-tooling/`                                                 | Docs analysis and apply workflows            |
+| Contributing     | `contributing/`                                                 | Code contributions, design principles, hooks |
+| File locations   | `reference/file-locations.md`                                   | Where OAT puts things                        |
+| Directory layout | `reference/oat-directory-structure.md`                          | `.oat/` and `.agents/` structure             |
+| Troubleshooting  | `reference/troubleshooting.md`                                  | Common issues and fixes                      |
 
 ### Step 3: Search and Read Documentation
 
@@ -143,7 +143,7 @@ Frame these as suggestions, not automatic actions. Let the user decide.
 ```
 Based on the docs, here's how OAT project workflows work: [answer]
 
-You can read more in `guide/workflow/lifecycle.md`.
+You can read more in `workflows/projects/lifecycle.md`.
 
 Would you like me to:
 - Start a new project? (I'd invoke oat-project-lite for single-sitting work, or oat-project-quick-start for a larger quick workflow)
@@ -181,7 +181,7 @@ Both create a project directory under your projects root
 state.md, plan.md, and implementation.md; quick and spec-driven modes also use
 discovery.md.
 
-See: guide/workflow/lifecycle.md, guide/getting-started.md
+See: workflows/projects/lifecycle.md, getting-started/quickstart.md
 
 Would you like me to create a project for you?
 ```
@@ -207,7 +207,7 @@ There are four packs:
 Install with: oat init tools
 Manage with: oat tools list, oat tools update, oat tools outdated
 
-See: guide/tool-packs.md
+See: getting-started/tool-packs.md
 
 Would you like me to check which packs you have installed? (I'd run /oat-doctor --summary)
 ```

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

@@ -1,11 +1,11 @@
 ---
 name: oat-docs-analyze
-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.
+description: Run when you need to evaluate documentation structure, navigation, and coverage against the OAT documentation contract. Produces a severity-rated analysis artifact for oat-docs-apply.
 disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Bash(oat docs nav sync --check:*), Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: 1.6.0
+  version: '1.6.2'
 ---
 
 # Docs Analysis
@@ -93,7 +93,11 @@ 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
+   - When tooling is `markdown`, record `docs-tree`; `documentation.root` is
+     the literal authored content root, even with a child named `docs`. The
+     configured `documentation.index` is authored, not a generated manifest.
+     Honor configured excludes and existing local instructions.
+   - For framework tooling, 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:
@@ -121,6 +125,12 @@ TRACKING=$(bash "$TRACKING_SCRIPT" read docs 2>/dev/null || true)
 - If the stored commit exists, run in `delta` mode and scope drift checks to changed docs directories.
 - Otherwise run in `full` mode.
 
+Configured tooling/root take precedence over discovery. Markdown needs no app
+package, site config, docs-root AGENTS, site build, or generated manifest. Read
+managed root guidance, contributing pages, and any existing local AGENTS files;
+do not mark their absence as a missing app shell. A successful adoption only
+establishes config/baseline/guidance; audit incomplete authored content normally.
+
 ### Step 1: Inventory the Docs Surface
 
 Build a complete inventory of:
@@ -155,7 +165,7 @@ 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:
+For configured Markdown and OAT/Fumadocs docs apps, check whether local guidance covers:
 
 - authored docs source location
 - generated root indexes or manifests and their no-hand-edit boundary
@@ -174,7 +184,7 @@ the current analyze/apply flow.
 
 Use `references/quality-checklist.md` and `references/directory-assessment-criteria.md`.
 
-For every documentation directory:
+For every non-excluded Markdown-bearing documentation directory:
 
 1. Verify `index.md` exists.
 2. Verify `index.md` includes a `## Contents` section.
@@ -190,6 +200,13 @@ For every documentation directory:
 9. Exempt asset-only directories that contain no Markdown content and are not
    linked as navigable docs sections.
 
+For Markdown, assess useful audience/scope context, nonempty title/description
+metadata, populated Contents, and relative `.md` links. Do not overwrite or
+recommend replacing existing context just to satisfy structure. Optional external
+manifests are separate derived artifacts: assess them only when local guidance
+actually declares one. Never require default generation or repoint an authored
+`documentation.index` to a manifest.
+
 For OAT/Fumadocs docs apps, also distinguish authored source maps from generated
 root indexes:
 
@@ -240,7 +257,7 @@ For each evaluated page or directory:
 
 1. Read the docs file plus the local evidence needed to validate its claims.
 2. Resolve every local relative Markdown link from the page where it appears.
-   Flag broken targets. In OAT/Fumadocs docs apps, flag extensionless local
+   Flag broken targets. In configured Markdown and 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
@@ -419,7 +436,10 @@ If `mkdocs.yml` exists:
 4. Flag directories whose `index.md` `## Contents` section appears inconsistent with nav structure.
 5. Flag docs guidance that claims structure, plugin support, or workflow rules not backed by current repo evidence.
 
-If neither `mkdocs.yml` nor a Fumadocs app exists, record whether the repo should be migrated to an OAT docs app.
+For Markdown, verify the authored Contents graph and file/link contract without
+site nav generation or builds. Lack of `mkdocs.yml`, a generated manifest, or an
+app package is expected, not a migration finding. For other unconfigured surfaces,
+record whether app migration is relevant only when evidence or user intent supports it.
 
 ### Step 7: Severity-Rate Findings
 

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

@@ -4,7 +4,10 @@ Use this checklist when evaluating a docs surface.
 
 ## Structure
 
-- Every docs directory has an `index.md`.
+- Every non-excluded Markdown-bearing docs directory has an authored `index.md`.
+- Authored entrypoints preserve useful audience, scope, ownership, and context.
+- Authored pages have nonempty `title` and `description` metadata.
+- Configured excludes and existing local instructions are respected.
 - Every `index.md` includes a `## Contents` section.
 - `## Contents` is useful content, not a placeholder comment, empty list, or
   generic "add links here" scaffold.
@@ -22,7 +25,7 @@ Use this checklist when evaluating a docs surface.
 ## Links
 
 - Local relative Markdown links resolve from the page where they appear.
-- OAT/Fumadocs docs apps use `.md`-suffixed local links for docs pages,
+- Configured Markdown and 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
@@ -58,7 +61,17 @@ Use this checklist when evaluating a docs surface.
 - Topic names are specific enough for agents to select the right page quickly.
 - Large sections summarize what each child page covers.
 
-## Docs App Contract
+## Documentation Surface Contract
+
+- For configured Markdown, `documentation.root` is the literal content root,
+  including when it contains a nested `docs` directory.
+- For Markdown, `documentation.index` is authored; optional generated manifests
+  live outside the full configured content tree and do not replace its entrypoint.
+- Markdown needs no app package, framework config, docs-root AGENTS, default
+  manifest, nav generation, installation, or site build. Use applicable existing
+  file/link/lint checks. Adoption alone is not proof of complete content conformity.
+- Managed root guidance, contributing guidance, and preserved local instructions
+  identify the root and authoring/audit/apply workflow.
 
 - For `mkdocs-app`, `mkdocs.yml` exists.
 - For `mkdocs-app`, navigation is consistent with the docs tree.

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

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash(git:*), Bash(gh:*), Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.3.2
+  version: '1.4.2'
 ---
 
 # Docs Apply
@@ -106,6 +106,12 @@ Validate that each recommendation in the artifact includes:
 
 If the artifact is missing that detail, stop and tell the user to re-run `oat-docs-analyze`.
 
+Resolve the artifact target against `.oat/config.json` and cited local guidance.
+With `documentation.tooling: markdown`, the configured root is the literal
+content tree even when it contains a child `docs`; the configured index is
+authored. Preserve excludes, useful audience/context/ownership prose and existing
+local AGENTS files. A changed or incompatible target requires fresh analysis.
+
 ### Step 1: Build the Recommendation Plan
 
 Read the analysis artifact and build the plan from its recommendations.
@@ -117,7 +123,8 @@ Common docs actions:
 - Add or repair `## Contents`
 - Convert `overview.md` usage to the `index.md` contract
 - Add or update `docs/contributing.md` plugin guidance
-- Scaffold an OAT docs app when no docs app exists
+- Route approved setup/adoption to `oat-docs-bootstrap`; a Markdown tree does
+  not require app scaffolding
 - Run `oat docs nav sync` after approved structural changes
 
 Carry forward the artifact's evidence refs, confidence, disclosure mode, and link targets into the apply plan.
@@ -214,7 +221,17 @@ Negative rules:
 
 ### Step 5: Verify and Sync Navigation
 
-Run the smallest relevant verification set based on what changed:
+For configured Markdown, check touched authored indexes/context, nonempty
+title/description metadata, Contents reachability, sibling `.md` and child
+`section/index.md` destinations, configured excludes and local instructions.
+Keep existing context while applying only approved repairs. Run documented
+existing file/link/lint/format checks; no install or site build is required.
+Do not invoke default `generate-index` or site `nav sync`. Regenerate an optional
+external manifest only when locally declared, with explicit output outside the
+full configured content tree; keep the authored config index unchanged.
+
+For framework apps, discover actual scripts and run the smallest relevant
+verification set based on what changed; these examples apply only when present:
 
 - `oat docs nav sync`
 - `pnpm --dir <docs-app> docs:lint` (no-op when no linter is configured)

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

@@ -1,28 +1,28 @@
 ---
 name: oat-docs-authoring
-description: Use when authoring or restructuring targeted content inside an existing OAT/Fumadocs docs app. Preserves OAT docs navigation, generated indexes, and validation boundaries.
+description: Use when authoring or restructuring targeted content inside an existing OAT Markdown surface or OAT/Fumadocs docs app. Preserves OAT docs navigation, generated indexes, and validation boundaries.
 argument-hint: '[docs task or target path]'
 disable-model-invocation: false
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 user-invocable: true
 metadata:
-  version: 1.0.2
+  version: '1.1.2'
 ---
 
 # OAT Docs Authoring
 
 Use this skill for targeted documentation authoring and small structural edits
-inside an existing OAT/Fumadocs docs app.
+inside an existing OAT Markdown surface or OAT/Fumadocs docs app.
 
 This is a thin wrapper over `authoring-docs`. Load `authoring-docs` for
 universal evidence gathering, page-type selection, writing style, templates,
-and review standards. Keep this wrapper focused on OAT/Fumadocs placement,
+and review standards. Keep this wrapper focused on OAT Markdown/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 repository already has an OAT Markdown surface, OAT/Fumadocs docs app,
+  or clearly identified documentation target 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.
 
@@ -31,7 +31,7 @@ navigation, generated artifacts, validation, and lifecycle boundaries.
 **OAT MODE: Docs Authoring Wrapper**
 
 **Purpose:** Author or restructure focused docs content while preserving the
-OAT/Fumadocs source-of-truth contract.
+OAT authored-source contract.
 
 **BLOCKED Activities:**
 
@@ -135,6 +135,10 @@ 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.
 
+Markdown uses its literal configured root and authored index; preserve context,
+excludes, and local instructions even with a nested `docs` directory. No app
+package or docs-root AGENTS creation is needed.
+
 ### Step 4: Check Generated Artifacts and Validation
 
 Regenerate or freshness-check derived docs artifacts using local scripts when

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: How to resolve Markdown content roots and OAT/Fumadocs app roots, authored docs roots, generated index outputs, and local instruction surfaces before editing.
 ---
 
 # OAT Docs Root Resolution
@@ -15,9 +15,15 @@ roots before editing.
      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.
+   - Declared tooling is authoritative. For `markdown`, `documentation.root`
+     is the literal authored content root, even with a child named `docs`, and
+     `documentation.index` is authored (normally `<root>/index.md`). Honor excludes.
+   - For framework tooling, prefer `documentation.root` as the docs app root.
+     Resolve authored source and generated ownership from app/local evidence;
+     a configured index alone is not proof that it is generated.
+   - Markdown requires no app package, framework config, site build, or manifest;
+     skip app-only discovery. An optional manifest must be external to the full
+     configured content tree and never replace the authored config index.
    - If config is incomplete, keep resolving from local files instead of
      guessing.
 3. Inspect package scripts in likely docs app directories.
@@ -34,7 +40,8 @@ roots before editing.
      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.
+   - Markdown uses the configured root itself. Framework apps commonly use
+     `<docs-app>/docs`, but local guidance is authoritative.
    - Find the top-level authored `index.md`, then follow `## Contents` maps to
      the target area.
 

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

@@ -10,13 +10,13 @@ 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. |
+| Request shape                                                                             | Owner                      | Why                                                                                                                        |
+| ----------------------------------------------------------------------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| New Markdown setup/adoption, 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:
 

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

@@ -5,13 +5,15 @@ description: Authored source, navigation, link, file-type, generated-index, and
 
 # OAT Fumadocs Authoring Contract
 
-The OAT/Fumadocs contract is tooling-critical. It is not just style.
+The authored-source rules below also apply to configured plain Markdown.
+Framework-specific generated output and metadata controls remain conditional.
 
 ## 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`.
+  app; configured Markdown uses `documentation.root` literally.
+- Every non-excluded Markdown-bearing content directory has an authored `index.md`.
+- Preserve useful audience/scope context, ownership notes, and local instructions.
 - Every authored `index.md` that represents a content directory has a
   `## Contents` section.
 - `## Contents` lists sibling pages and immediate child directories for that
@@ -42,6 +44,14 @@ the task scope or an approved recommendation covers that change.
 - Add or preserve at least `title` and `description` frontmatter on touched
   pages unless local guidance defines a stricter schema.
 
+## Markdown Authored Index Ownership
+
+With `documentation.tooling: markdown`, `documentation.index` is authored.
+Edit its context and Contents directly within approved scope. No manifest is
+required. Optional generation needs explicit output outside the full configured
+content tree and cannot overwrite the authored index, even with narrowed source
+flags. Never repoint the config index to generated output.
+
 ## Generated Root Indexes
 
 Many OAT/Fumadocs apps have an app-root generated `index.md` that rolls up the