@open-agent-toolkit/cli 0.1.20 → 0.1.22

package/assets/agents/oat-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-reviewer
-version: 1.1.0
+version: 1.1.2
 description: Unified reviewer for OAT projects - mode-aware verification of requirements/design alignment and code quality. Writes a review artifact to disk by default, or returns structured findings in-memory when dispatched in structured-output mode.
 tools: Read, Bash, Grep, Glob, Write
 color: yellow
@@ -10,10 +10,11 @@ color: yellow
 
 You are an OAT reviewer. You perform independent reviews for OAT projects.
 
-You may be asked to do either:
+You may be asked to do one of:
 
 - **Code review**: verify implementation against spec/design/plan + pragmatic code quality.
 - **Artifact review**: review an artifact (spec/design/plan) for completeness/clarity/readiness and alignment with upstream artifacts.
+- **Analysis review**: fact-check a severity-rated analysis artifact for evidence accuracy, justified severity, and actionable recommendations.
 
 **Critical mindset:** Assume you know nothing about this project. Trust only written artifacts and code. Do NOT trust summaries or claims - verify by reading actual files.
 
@@ -44,10 +45,11 @@ Some findings are artifact drift rather than implementation defects. If shipped
 You will be given a "Review Scope" block including:
 
 - **project**: Path to project directory (e.g., `.oat/projects/shared/my-feature/`)
-- **type**: `code` or `artifact`
-- **scope**: What to review (`pNN-tNN` task, `pNN` phase, `pNN-pMM` contiguous phase range, `final`, `BASE..HEAD` range, or an artifact name like `spec` / `design`)
+- **type**: `code`, `artifact`, or `analysis`
+- **scope**: What to review (`pNN-tNN` task, `pNN` phase, `pNN-pMM` contiguous phase range, `final`, `BASE..HEAD` range, an artifact name like `spec` / `design` / `plan`, or an analysis sub-kind: `docs` / `agent-instructions`)
 - **commits/range**: Git commits or SHA range for changed files. For code review, this is the authoritative review surface.
 - **files_changed**: Optional orientation hint listing files believed to be modified in scope. If this disagrees with the commit range, trust the commit range.
+- **analysis_artifact**: For `type: analysis`, path to the severity-rated analysis artifact to fact-check.
 - **workflow_mode**: `spec-driven` | `quick` | `import` (default to `spec-driven` if absent)
 - **artifact_paths**: Paths to available artifacts (spec/design/plan/implementation/discovery/import reference)
 - **tasks_in_scope**: Task IDs being reviewed (if task/phase scope)
@@ -89,7 +91,10 @@ Read available artifacts to understand what SHOULD have been built:
    - `spec-driven`: read `spec.md` and `design.md`.
    - `quick`: read `discovery.md` and `plan.md`; read `spec.md`/`design.md` only if they exist.
    - `import`: read `plan.md` and `references/imported-plan.md` (if present); read `spec.md`/`design.md` only if they exist.
-3. In your notes and review summary, explicitly list which artifacts were available and used.
+3. For `type: analysis`, read `analysis_artifact` and then inspect only the cited evidence sources needed to verify its findings:
+   - `scope: docs`: consult the docs contract, docs navigation/index files, and cited docs source files relevant to the analysis.
+   - `scope: agent-instructions`: consult the repo/root instruction files, provider instruction files, and cited skill/agent instruction files relevant to the analysis.
+4. In your notes and review summary, explicitly list which artifacts were available and used.
 
 ### Step 2: Verify Scope
 
@@ -149,6 +154,7 @@ Treat the artifact as a product deliverable. Verify it is:
      - `spec-driven`: spec + design
      - `quick`: discovery (+ spec/design if present)
      - `import`: imported-plan reference (+ discovery/spec/design if present)
+   - For import-mode `plan` reviews, bias findings toward canonical-format conformance and completeness. Do not rewrite the imported author's intent merely to match OAT house style.
 
 4. **Actionable**
    - Clear next steps and readiness signals
@@ -156,6 +162,15 @@ Treat the artifact as a product deliverable. Verify it is:
    - For design: requirement-to-test mapping exists and includes concrete scenarios
    - For plan: tasks have clear verification commands and commit messages
 
+5. **Plan-specific checklist**
+   - Canonical-format conformance: required frontmatter and sections are present, the Reviews table exists, and artifact/code rows are shaped consistently.
+   - Stable task IDs: task headings use `pNN-tNN`, IDs are monotonic within each phase, and review-generated tasks do not reuse prior IDs.
+   - Required sections: the plan includes Reviews, Implementation Complete, and References sections without placeholder-only critical content.
+   - Review-table preservation: existing review rows are preserved; never require deleting rows to "clean up" the table.
+   - Task atomicity and verifiability: each task is independently committable, has bounded file scope, and declares verification that can actually be run.
+   - Coverage of design/discovery: every in-scope design component or discovery decision is mapped to at least one task or explicitly deferred/out of scope.
+   - Parallelism-claim sanity: any parallel phase group or parallelism statement is consistent with declared file boundaries and dependency order.
+
 ### Step 5: Verify Design Alignment
 
 This step applies to **code reviews** only.
@@ -181,6 +196,29 @@ For each design decision relevant to scope:
    - When the implementation is defensible, write the finding as stale-artifact alignment guidance instead of a code defect.
    - Include enough rationale for `oat-project-review-receive` to convert the finding into an artifact-alignment task or explicit deferral.
 
+### Step 5.5: Verify Analysis Accuracy
+
+This step applies to **analysis reviews** only.
+
+Review the analysis artifact as a fact-checking target, not as a rewrite request. Verify:
+
+1. **Evidence exists**
+   - Every severity-rated finding cites real evidence with file/line references or an equivalent precise artifact pointer.
+   - Open each cited file/location that materially supports the finding; if the cited evidence is absent, stale, or unrelated, add a finding.
+
+2. **Severity is justified**
+   - Critical/Important findings must describe concrete user-visible, workflow, correctness, security, or maintainability impact.
+   - Medium/Minor findings must not be inflated solely because they are easy to fix.
+
+3. **Recommendations are accurate**
+   - Suggested fixes must match the actual repo contracts and existing file conventions.
+   - For `docs` analysis, do not invent docs-app contract checks; cite the docs contract or source file that establishes the rule.
+   - For `agent-instructions` analysis, do not invent provider or instruction-file requirements; cite the relevant instruction file, skill, agent, or provider reference.
+
+4. **No hallucinated contract checks**
+   - If the analysis asserts a required section, schema field, version rule, provider behavior, or workflow invariant, verify that the contract exists in repo artifacts or authoritative cited sources.
+   - If a recommendation is stylistic or optional, ensure the analysis labels it as such instead of treating it as a hard contract.
+
 ### Step 6: Verify Code Quality
 
 This step applies to **code reviews** only.
@@ -256,11 +294,11 @@ Write the review artifact to the specified path.
 oat_generated: true
 oat_generated_at: YYYY-MM-DD
 oat_review_scope: { scope }
-oat_review_type: { code|artifact }
+oat_review_type: { code|artifact|analysis }
 oat_project: { project-path }
 ---
 
-# {Code|Artifact} Review: {scope}
+# {Code|Artifact|Analysis} Review: {scope}
 
 **Reviewed:** YYYY-MM-DD
 **Scope:** {scope description}
@@ -351,9 +389,9 @@ Return to your main session and run the `oat-project-review-receive` skill.
 
 ## Structured-Output Mode
 
-When the dispatch payload sets `oat_output_mode: structured`, the output sink changes — nothing else does. Run the full review (Steps 1-7) exactly as in artifact mode, then:
+When the dispatch payload sets `oat_output_mode: structured`, the output sink changes — nothing else does. Run the full review (Steps 1-7, including Step 5.5 for `type: analysis`) exactly as in artifact mode, then:
 
-1. **Do NOT write a review artifact.** Skip Step 8 entirely. In this mode you MUST NOT write to any path under `{project}/reviews/` (or anywhere else). The caller — the project-rail `oat-project-review-provide-remote` skill's Tier 1 dispatch — consumes your return value in-memory and posts it to GitHub itself; GitHub is the source of truth on that rail, so a local artifact would be redundant and is explicitly disallowed.
+1. **Do NOT write a review artifact.** Skip Step 8 entirely. In this mode you MUST NOT write to any path under `{project}/reviews/` (or anywhere else). The caller consumes your return value in-memory, whether that caller posts to GitHub, runs an auto artifact-review loop, or performs another structured workflow.
 2. **Instead of Step 9's confirmation, return a `StructuredFindings` object** as your response. Do not also return the artifact-mode confirmation block.
 
 **`StructuredFindings` return shape** (canonical schema: `design.md` → Data Models → StructuredFindings):
@@ -381,7 +419,7 @@ interface StructuredFindings {
 - `id` prefixes follow the existing convention (`C`/`I`/`M`/`m`) and are stable within a single dispatch — no renumbering.
 - `verification_commands` carries what Step 8's "Verification Commands" section would have carried, as an array of command strings.
 
-Default behavior is unaffected: when `oat_output_mode` is absent or set to anything other than `structured`, follow Steps 8-9 and write the artifact exactly as before.
+Default behavior is unaffected: when `oat_output_mode` is absent or set to anything other than `structured`, follow Steps 8-9 and write the artifact exactly as before. Analysis reviews MUST honor `oat_output_mode: structured` whenever supplied by an auto-review loop: return the `StructuredFindings` object and write no artifact.
 
 ## Critical Rules
 

package/assets/docs/cli-utilities/config-and-local-state.md

@@ -76,6 +76,18 @@ Tool-pack installation state also lives here as shared repo config:
 
 Use `oat config get tools.<pack>` when you need an explicit installed-capability signal for workflows or troubleshooting.
 
+Workflow automation preferences are also visible through `oat config` and can be set at local, shared, or user scope. Notable review-loop keys:
+
+- `workflow.autoArtifactReview.plan` - default-on bounded artifact review for generated `plan.md` files before implementation handoff
+- `workflow.autoArtifactReview.analysis` - default-on bounded accuracy review for generated docs and agent-instructions analysis artifacts before apply workflows consume them
+
+Use `oat config describe workflow.autoArtifactReview.plan` or `oat config describe workflow.autoArtifactReview.analysis` to inspect precedence, defaults, and writable surfaces. Set either key to `false` only when you intentionally want to bypass that generated-artifact review loop:
+
+```bash
+oat config set workflow.autoArtifactReview.plan false --shared
+oat config set workflow.autoArtifactReview.analysis false --local
+```
+
 When archive settings are configured, completion uploads dated archive snapshots to S3, exports dated summary snapshots into the configured summary reference directory, and lets `oat-wrap-up` write tracked wrap-up reports into the configured wrap-up directory.
 
 Use these reference pages for file ownership and schema details:

package/assets/docs/cli-utilities/configuration.md

@@ -255,13 +255,26 @@ Workflow preference keys live under the `workflow.*` namespace:
 - `workflow.reviewExecutionModel` — `subagent`, `inline`, or `fresh-session`. Default final-review execution model in `oat-project-implement`. `subagent` and `inline` run automatically. `fresh-session` is a soft preference: the skill prints guidance to run the review in another session but still offers escape hatches to `subagent` or `inline` if you change your mind. When unset, the skill prompts.
 - `workflow.autoReviewAtHillCheckpoints` — boolean. Automatically run the extra lifecycle review when a HiLL checkpoint is reached. This does not control Tier 1 per-phase `oat-reviewer` gates, which run after each phase in Tier 1 regardless of this setting. When unset, the skill prompts.
 - `workflow.autoNarrowReReviewScope` — boolean. Auto-narrow re-review scope to fix-task commits only in `oat-project-review-provide`. When unset, the skill prompts.
+- `workflow.autoArtifactReview.plan` — boolean, default `true`. Automatically run the bounded artifact-review loop for generated `plan.md` files before implementation handoff. Set to `false` only when you intentionally want to skip the plan artifact review.
+- `workflow.autoArtifactReview.analysis` — boolean, default `true`. Automatically run the bounded accuracy-review loop for generated docs and agent-instructions analysis artifacts before the matching apply workflow consumes them.
 - `workflow.dispatchCeiling.preset` — `balanced`, `maximum`, or `cost-conscious`. Convenience preset that compiles to per-provider values at write time. Setting this key is the recommended way to configure the ceiling.
 - `workflow.dispatchCeiling.providers.codex` — `low`, `medium`, `high`, or `xhigh`. Concrete Codex ceiling. Set automatically when a preset is selected; also settable directly for Advanced (no preset) configurations. Provider default effort is informational for base/unpinned roles and is not treated as this ceiling.
 - `workflow.dispatchCeiling.providers.claude` — `haiku`, `sonnet`, or `opus`. Concrete Claude ceiling. Set automatically when a preset is selected; also settable directly for Advanced configurations. Claude has no separate per-dispatch effort axis, so the effort axis remains `not-applicable`.
 
+### Auto artifact-review preferences
+
+`workflow.autoArtifactReview.*` controls the artifact-quality loops that run before downstream workflow steps consume generated artifacts. Both keys are default-on. Only an explicit `false` disables the matching loop:
+
+| Key                                    | Default | Controls                                                                 |
+| -------------------------------------- | ------- | ------------------------------------------------------------------------ |
+| `workflow.autoArtifactReview.plan`     | `true`  | `plan.md` artifact review after plan authoring and before implementation |
+| `workflow.autoArtifactReview.analysis` | `true`  | Accuracy review for generated docs and agent-instructions analysis files |
+
+The loops use `oat-reviewer` structured-output mode. They do not write standalone review artifacts unless the calling workflow records an outcome row or tracking metadata. The retry bound comes from the project `oat_orchestration_retry_limit` setting and defaults to `2`.
+
 ### Three-layer resolution
 
-Workflow preferences resolve through three config surfaces, with `env > local > shared > user > default` precedence per key. This is the same generic resolution used by `oat config dump`:
+Workflow preferences resolve through three config surfaces, with `local > shared > user > default` precedence per key. `oat config dump` can also report an `env` source for keys that have explicit environment aliases, such as `projects.root` and `worktrees.root`; `workflow.autoArtifactReview.plan` and `workflow.autoArtifactReview.analysis` do not have environment aliases and use config-file/default resolution.
 
 - **User-level** (`~/.oat/config.json`): personal defaults that apply to every repo. This is where most power users should start — set preferences once, never worry about them again.
 - **Shared repo** (`.oat/config.json`): team decisions for this repo. Overrides user defaults when present.
@@ -282,16 +295,20 @@ oat config set workflow.autoReviewAtHillCheckpoints true --user
 oat config set workflow.autoNarrowReReviewScope true --user
 oat config set workflow.designMode selective --user
 oat config set workflow.dispatchCeiling.preset balanced --user
+oat config set workflow.autoArtifactReview.plan true --user
+oat config set workflow.autoArtifactReview.analysis true --user
 
 # Shared repo: team decision for this repo
 oat config set workflow.createPrOnComplete false --shared
 oat config set workflow.designMode collaborative --shared
 oat config set workflow.dispatchCeiling.preset balanced --shared
+oat config set workflow.autoArtifactReview.plan false --shared
 
 # Repo-local: personal override for this repo (default when no flag)
 oat config set workflow.hillCheckpointDefault every
 oat config set workflow.designMode draft
 oat config set workflow.dispatchCeiling.providers.codex medium  # Advanced: per-provider override
+oat config set workflow.autoArtifactReview.analysis false
 ```
 
 Default (no flag) targets `.oat/config.local.json` for workflow keys. Pass at most one of `--user`, `--shared`, or `--local`. Structural keys (`projects.root`, `worktrees.root`, `git.*`, `documentation.*`, `archive.*`, `tools.*`) are still shared-only regardless of flag.
@@ -312,6 +329,7 @@ Some preferences are **genuinely personal** — their correct value is the same
 
 Other preferences **depend on per-repo configuration** to be safe. These should be set at `--shared` (in each repo where they apply), not `--user`:
 
+- `workflow.autoArtifactReview.plan` / `workflow.autoArtifactReview.analysis` — default to `true`; use shared config only when a repo intentionally opts out of generated-artifact review loops, and local config for one-off debugging or emergency bypasses.
 - `workflow.archiveOnComplete` — correctness depends on the repo's `archive.s3Uri` / `archive.s3SyncOnComplete` being configured. A user-level `true` would try to archive in repos that aren't set up for it.
 - `workflow.postImplementSequence` — correctness depends on `documentation.requireForProjectCompletion`. Setting `pr` at user level would foot-gun you in any repo that requires docs, because completion would later block on the docs gate while the PR is already open.
 - `workflow.createPrOnComplete` — this key is almost always redundant with `postImplementSequence`-driven flows. When it's meaningful, its correctness depends on the same per-repo docs and PR gates. Prefer shared scope, or omit it entirely and rely on `postImplementSequence: pr` or `docs-pr` to handle PR creation at the end of implement.

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,18 +17,26 @@ 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,
   build verification, config inspection, and an educational walkthrough
 - `oat-docs-analyze` evaluates a docs surface for structure, drift, coverage,
-  contributor guidance, and docs-app contract issues
+  contributor guidance, and docs-app contract issues, then runs the shared
+  auto artifact-review loop to verify the generated analysis artifact's
+  evidence, severities, and recommendations
 - `oat-docs-apply` consumes the analysis artifact and applies only approved,
   evidence-backed recommendations
 - `oat-project-document` performs post-implementation docs sync for a tracked project,
@@ -42,6 +50,9 @@ Install the workflow skills with `oat tools install docs` (preferred) or
 The docs workflow mirrors the agent-instructions analyze/apply split:
 
 - Analyze owns discovery, evidence gathering, confidence, and disclosure decisions
+- Analyze also owns accuracy verification of the generated analysis artifact
+  through the shared auto artifact-review loop before the apply workflow consumes
+  it
 - Apply consumes the artifact, asks for approval, and must not invent new docs conventions
 
 This keeps deterministic behavior in the CLI and judgment-heavy behavior in the
@@ -50,14 +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`
-7. Review the artifact and run `oat-docs-apply`
+7. Run `oat-docs-analyze`; by default it verifies the generated analysis artifact
+   through `workflow.autoArtifactReview.analysis`
+8. Review the artifact and run `oat-docs-apply`
 
 ## Progressive disclosure
 

package/assets/docs/reference/cli-reference.md

@@ -33,6 +33,7 @@ The CLI is also a standalone value path. You can use `oat init`, `oat sync`, `oa
 | `oat docs ...`                                  | Docs app bootstrap, migration, index generation, nav sync, and docs workflow entrypoints.                                               | [Docs Tooling Commands](../docs-tooling/commands.md)                           |
 | `oat status` / `oat sync` / `oat providers ...` | Provider sync, drift inspection, provider configuration, and adoption behavior.                                                         | [Provider Sync](../provider-sync/index.md)                                     |
 | `oat project ...` / `oat cleanup ...`           | Project scaffolding, active-project status inspection, tracked-project listing, plan validation, archive creation, and project/artifact cleanup commands. | [Workflow & Projects](../workflows/projects/index.md)                          |
+| `oat review ...`                                | Review artifact discovery helpers, including latest-review resolution for project and ad-hoc review flows.                             | [Reviews](../workflows/projects/reviews.md)                                    |
 | `oat repo ...`                                  | Repository-level workflows such as archive sync and PR-comment analysis.                                                                 | [Repository Analysis](../workflows/projects/repo-analysis.md)                  |
 
 Notable commands introduced in the current CLI surface:
@@ -42,6 +43,7 @@ Notable commands introduced in the current CLI surface:
 - `oat project status --field <path>` - print one arbitrary dot-path field from the same status payload, e.g. `project.workflowMode` or `project.timestamps.stateUpdated`. Missing/null fields print `null`; object and array fields print compact JSON.
 - `oat project status --project-path <path>` - read from a repo-relative or absolute project path instead of `.oat/config.local.json`'s active project pointer. Combine it with `--field` or `--shell` when a skill has already resolved the target project path.
 - `oat project status --shell NAME=path ...` - print shell-safe assignments for one or more fields from one status read, e.g. `WORKFLOW_MODE='quick'`. This is the preferred multi-field read API for skills. See [Writing Skills → Reading project state](../contributing/skills.md#reading-project-state) for examples and the `npx`-backed `oat` shim contract.
+- `oat review latest --json` - find the newest review artifact by `oat_generated_at`, scanning the active or specified project's `reviews/` and `reviews/archived/` directories plus ad-hoc review locations. Same-time candidates use target priority, then lifecycle recency (`final` > higher phase/task > lower phase/task). The JSON contract returns `path`, `scope`, `generatedAt`, and `kind` (`project` or `adhoc`), with `null` values when no review exists.
 - `oat project list --json` - summary state for tracked projects under the configured projects root
 - `oat project complete-state <project-path>` - apply the canonical completed-state mutation to a project's `state.md`; used by `oat-project-complete` during lifecycle closeout
 - `oat project archive [project-path]` - archive a tracked project through the same local move, summary export, and optional S3 upload path used by completion. When omitted, the project path falls back to the active project.
@@ -63,7 +65,7 @@ Per-key restrictions apply: structural keys can only be written at shared scope,
 
 ## `workflow.*` preference keys
 
-The `workflow.*` namespace holds user-facing workflow preferences that let you answer repetitive confirmation prompts once and have OAT skills respect the answer automatically. Seven keys:
+The `workflow.*` namespace holds user-facing workflow preferences that let you answer repetitive confirmation prompts once and have OAT skills respect the answer automatically. Common keys:
 
 - `workflow.hillCheckpointDefault` (`every` | `final`) — default HiLL checkpoint behavior in `oat-project-implement`
 - `workflow.archiveOnComplete` (`boolean`) — skip the archive prompt in `oat-project-complete`
@@ -72,5 +74,7 @@ The `workflow.*` namespace holds user-facing workflow preferences that let you a
 - `workflow.reviewExecutionModel` (`subagent` | `inline` | `fresh-session`) — default final-review execution model
 - `workflow.autoReviewAtHillCheckpoints` (`boolean`) — auto-run the extra lifecycle review at HiLL checkpoints
 - `workflow.autoNarrowReReviewScope` (`boolean`) — auto-narrow re-review scope to fix-task commits
+- `workflow.autoArtifactReview.plan` (`boolean`, default `true`) — auto-run the bounded `plan.md` artifact-review loop before implementation handoff
+- `workflow.autoArtifactReview.analysis` (`boolean`, default `true`) — auto-run the bounded accuracy-review loop for generated analysis artifacts before apply workflows consume them
 
-All seven keys resolve through the 3-layer precedence chain (`env > local > shared > user > default`). See [Workflow preferences in the Configuration guide](../cli-utilities/configuration.md#workflow-preferences-workflow) for full descriptions, surface guidance, and cross-repo foot-gun examples.
+These workflow keys resolve through config files and defaults (`local > shared > user > default`). Some config keys have explicit environment aliases, but `workflow.autoArtifactReview.plan` and `workflow.autoArtifactReview.analysis` do not. See [Workflow preferences in the Configuration guide](../cli-utilities/configuration.md#workflow-preferences-workflow) for full descriptions, surface guidance, and cross-repo foot-gun examples.

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