@open-agent-toolkit/cli 0.3.27 → 0.3.29

package/assets/skills/authoring-docs/references/page-templates/engineering-feature.md

@@ -0,0 +1,53 @@
+---
+title: Engineering feature
+description: Implementation contracts and testing seams for one feature.
+---
+
+# Engineering feature
+
+## Routes and params
+
+List verified routes, parameters, defaults and validation boundaries.
+
+## Primary files
+
+Link implementation entry points and explain each file's responsibility.
+
+## Data and state
+
+Describe ownership, lifecycle, persistence and shared contracts; link domain references.
+
+## Flags
+
+List verified flags and rollout/configuration behavior; state unknown when unverified.
+
+## Failure modes and constraints
+
+Describe failure propagation, recovery and supported limits with source references.
+
+## Testing seams
+
+Identify setup, injection boundaries and observable assertions without claiming coverage.
+
+## Paired documentation
+
+Link the Product feature and QA validation pages. Engineering is hybrid: domain and
+implementation contracts coexist with paired feature pages, without duplicating facts.
+
+## Source references
+
+Cite source paths and symbols supporting each implementation claim.
+
+## Writing and evidence rules
+
+Use backticks only for literals verified verbatim in source, such as commands,
+errors, labels and identifiers. Write concepts in ordinary prose. Cite the
+source location for each verified literal; label unknown facts as unknown.
+Remove drafting prompts before publishing and retain owner-review gaps explicitly.
+
+Keep these three evidence classes separate:
+
+- Planned automation: intended coverage, with owner and remaining work.
+- Implemented assertions: the test path and the exact assertion it implements.
+- Dated execution evidence: date, environment/configuration, result and evidence
+  location. Implemented assertions alone do not prove a successful execution.

package/assets/skills/authoring-docs/references/page-templates/per-area-agents.md

@@ -0,0 +1,42 @@
+---
+title: Per-area AGENTS
+description: Local authoring instructions excluded from reader navigation.
+---
+
+# Per-area AGENTS
+
+## Audience
+
+Name the reader and agent work contexts this area serves.
+
+## Voice
+
+Describe the area's vocabulary, level of detail and evidence expectations.
+
+## Belongs here versus elsewhere
+
+State the entry principle, canonical facts owned here and routes to adjacent areas.
+
+## Cross-area triggers
+
+Name changes requiring paired Product/Engineering/QA pages or shared-contract review.
+
+## Verification
+
+List the actual checks and review process for this area. Keep this instruction file
+out of reader Contents and navigation. This copyable template does not automatically
+create per-track AGENTS files; reconcile ancestor instructions before adopting it.
+
+## Writing and evidence rules
+
+Use backticks only for literals verified verbatim in source, such as commands,
+errors, labels and identifiers. Write concepts in ordinary prose. Cite the
+source location for each verified literal; label unknown facts as unknown.
+Remove drafting prompts before publishing and retain owner-review gaps explicitly.
+
+Keep these three evidence classes separate:
+
+- Planned automation: intended coverage, with owner and remaining work.
+- Implemented assertions: the test path and the exact assertion it implements.
+- Dated execution evidence: date, environment/configuration, result and evidence
+  location. Implemented assertions alone do not prove a successful execution.

package/assets/skills/authoring-docs/references/page-templates/product-feature.md

@@ -0,0 +1,49 @@
+---
+title: Product feature
+description: Intended behavior and reader-visible boundaries for one feature or journey.
+---
+
+# Product feature
+
+## Availability and entry points
+
+Describe who can use the feature, prerequisites and supported entry points.
+Identify unavailable contexts without guessing rollout status.
+
+## Expected journey
+
+Describe the reader's goal, starting state, numbered actions and observable result.
+
+## Behavior rules
+
+State the rules and permissions that determine the result; link canonical shared rules.
+
+## States and edge cases
+
+Cover loading, empty, success, denied and failed states that source supports.
+
+## External boundary
+
+Name external systems and where this feature stops owning behavior.
+
+## Paired documentation
+
+Link the Engineering feature and QA validation pages using matching feature names.
+
+## Evidence and owner-review gaps
+
+Cite implementation/product evidence and name unconfirmed behavior and its reviewer.
+
+## Writing and evidence rules
+
+Use backticks only for literals verified verbatim in source, such as commands,
+errors, labels and identifiers. Write concepts in ordinary prose. Cite the
+source location for each verified literal; label unknown facts as unknown.
+Remove drafting prompts before publishing and retain owner-review gaps explicitly.
+
+Keep these three evidence classes separate:
+
+- Planned automation: intended coverage, with owner and remaining work.
+- Implemented assertions: the test path and the exact assertion it implements.
+- Dated execution evidence: date, environment/configuration, result and evidence
+  location. Implemented assertions alone do not prove a successful execution.

package/assets/skills/authoring-docs/references/page-templates/qa-validation.md

@@ -0,0 +1,59 @@
+---
+title: QA validation
+description: Reproducible behavioral validation for one feature or journey.
+---
+
+# QA validation
+
+## Scope
+
+Name the behavior, supported platforms and paired Product and Engineering pages.
+
+## Named seeds
+
+Name each reproducible account/data seed, setup procedure and preconditions. Do not
+include credentials or real personal data; document safe provisioning instead.
+
+## Configuration matrix
+
+List relevant versions, flags, permissions, data states and platform combinations.
+
+## Scenarios
+
+| ID          | Priority   | Given                  | When     | Then (exact copy)                       | Evidence                       | Automation                              |
+| ----------- | ---------- | ---------------------- | -------- | --------------------------------------- | ------------------------------ | --------------------------------------- |
+| <stable ID> | <priority> | <named seed and state> | <action> | <verified observable result or unknown> | <dated result link or not run> | <planned or implemented test reference> |
+
+## Ready signal
+
+State the observable signal that setup and asynchronous work are ready before acting.
+
+## Cleanup
+
+Give reset/removal steps and verify that seeds and side effects are cleaned up.
+
+## Platform deltas
+
+Document supported differences, including locators and expected results.
+
+## External boundary
+
+Name external behavior that requires another owner or test environment.
+
+## Out of scope
+
+Explain excluded behaviors and who verifies them. Keep owner-review gaps visible.
+
+## Writing and evidence rules
+
+Use backticks only for literals verified verbatim in source, such as commands,
+errors, labels and identifiers. Write concepts in ordinary prose. Cite the
+source location for each verified literal; label unknown facts as unknown.
+Remove drafting prompts before publishing and retain owner-review gaps explicitly.
+
+Keep these three evidence classes separate:
+
+- Planned automation: intended coverage, with owner and remaining work.
+- Implemented assertions: the test path and the exact assertion it implements.
+- Dated execution evidence: date, environment/configuration, result and evidence
+  location. Implemented assertions alone do not prove a successful execution.

package/assets/skills/authoring-docs/references/page-templates/screen-spec.md

@@ -0,0 +1,51 @@
+---
+title: Screen spec
+description: Shared visible-state contract only for screens serving several journeys.
+---
+
+# Screen spec
+
+## When to use
+
+Create this page only when one screen serves several journeys. Otherwise keep the
+state contract in its feature pages and avoid a second canonical description.
+
+## Route and params
+
+List verified route identity, parameters, validation and defaults.
+
+## Entry points
+
+Name the journeys and deep links reaching this screen and their preconditions.
+
+## Visible states
+
+Describe loading, empty, content, permission and error states supported by source.
+
+## Locators
+
+| Element           | Test ID                  | A11y label                  | Literal text               | Source path       |
+| ----------------- | ------------------------ | --------------------------- | -------------------------- | ----------------- |
+| <element concept> | <verified ID or unknown> | <verified label or unknown> | <verified text or unknown> | <source location> |
+
+## Transitions
+
+Describe actions, state changes and visible results; link journey-specific behavior.
+
+## Back behavior
+
+Explain back, dismissal, restoration and cancellation for each supported entry path.
+
+## Writing and evidence rules
+
+Use backticks only for literals verified verbatim in source, such as commands,
+errors, labels and identifiers. Write concepts in ordinary prose. Cite the
+source location for each verified literal; label unknown facts as unknown.
+Remove drafting prompts before publishing and retain owner-review gaps explicitly.
+
+Keep these three evidence classes separate:
+
+- Planned automation: intended coverage, with owner and remaining work.
+- Implemented assertions: the test path and the exact assertion it implements.
+- Dated execution evidence: date, environment/configuration, result and evidence
+  location. Implemented assertions alone do not prove a successful execution.

package/assets/skills/authoring-docs/references/page-templates/skill-command-guide.md

@@ -0,0 +1,44 @@
+---
+title: Skill or command guide
+description: A reader task guide for invoking one skill or command.
+---
+
+# Skill or command guide
+
+## Invocation
+
+Give the verified invocation and how to provide the required inputs.
+
+## Prerequisites
+
+Describe setup, access, repository state and authority needed for this invocation.
+
+## Example scenario
+
+Explain one concrete input, goal and expected result without invented product facts.
+
+## What it does without asking
+
+State automatic actions, mutation scope, approval boundaries and stop conditions.
+
+## Expected output
+
+Describe resulting files, messages or state and how to verify success or partial work.
+
+## Next step
+
+Name the next reader action, review or recovery route and link canonical guidance.
+
+## Writing and evidence rules
+
+Use backticks only for literals verified verbatim in source, such as commands,
+errors, labels and identifiers. Write concepts in ordinary prose. Cite the
+source location for each verified literal; label unknown facts as unknown.
+Remove drafting prompts before publishing and retain owner-review gaps explicitly.
+
+Keep these three evidence classes separate:
+
+- Planned automation: intended coverage, with owner and remaining work.
+- Implemented assertions: the test path and the exact assertion it implements.
+- Dated execution evidence: date, environment/configuration, result and evidence
+  location. Implemented assertions alone do not prove a successful execution.

package/assets/skills/authoring-docs/references/page-templates/solution-record.md

@@ -0,0 +1,43 @@
+---
+title: Solution record
+description: An incident diagnosis and fix, distinct from a capability solution guide.
+symptoms: []
+root_cause: unknown
+component: unknown
+severity: unknown
+date: null
+---
+
+# Solution record
+
+## Problem
+
+Describe impact, reproduction and observed symptoms. Keep the frontmatter symptoms
+verbatim from observed errors; do not invent an incident, date or severity.
+
+## Root cause
+
+Explain the causal chain with source/evidence references and remaining uncertainty.
+
+## Fix
+
+Describe the actual change, affected component, verification and rollback.
+
+## Prevention
+
+Separate proposed prevention from implemented assertions and dated execution results.
+Name follow-up owners and unresolved review gaps.
+
+## Writing and evidence rules
+
+Use backticks only for literals verified verbatim in source, such as commands,
+errors, labels and identifiers. Write concepts in ordinary prose. Cite the
+source location for each verified literal; label unknown facts as unknown.
+Remove drafting prompts before publishing and retain owner-review gaps explicitly.
+
+Keep these three evidence classes separate:
+
+- Planned automation: intended coverage, with owner and remaining work.
+- Implemented assertions: the test path and the exact assertion it implements.
+- Dated execution evidence: date, environment/configuration, result and evidence
+  location. Implemented assertions alone do not prove a successful execution.

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

@@ -551,8 +551,8 @@ docs/
 ## IA Proposal
 
 Use for bootstrap or an existing-tree `--ia` analysis. This proposes structure;
-it neither persists an IA decision nor materializes a preset. Feature and QA
-validation page templates are not included; use the page-type guidance to
+it neither persists an IA decision nor materializes a preset. Use the copyable
+page assets below and the page-type guidance to
 plan their content.
 
 ````markdown
@@ -601,3 +601,23 @@ questions. Record an explicit choice before replacement or a second app.
 Existing docs default to analyze → apply of approved recommendations.
 No private exemplar text, copied external contents or unapproved moves.}
 ````
+
+## Copyable page assets
+
+These Markdown bodies are the canonical source for approved preset scaffolds under
+`contributing/templates/`. They are drafts, excluded from reader navigation and
+manifest inventories through `documentation.nonReaderPaths`. Prefer local templates
+when present; remove prompts and unneeded sections before publishing a reader page.
+A Solution record captures an incident diagnosis, unlike the solution page type; a
+Decisions pointer routes to records and never substitutes for an ADR.
+
+- [Product feature](page-templates/product-feature.md) - Intended behavior and reader-visible boundaries for one feature or journey.
+- [Engineering feature](page-templates/engineering-feature.md) - Implementation contracts and testing seams for one feature.
+- [QA validation](page-templates/qa-validation.md) - Reproducible behavioral validation for one feature or journey.
+- [Screen spec](page-templates/screen-spec.md) - Shared visible-state contract only for screens serving several journeys.
+- [Alert runbook](page-templates/alert-runbook.md) - Triage, recovery and verification for a specific operational alert.
+- [Solution record](page-templates/solution-record.md) - An incident diagnosis and fix, distinct from a capability solution guide.
+- [Command reference](page-templates/command-reference.md) - Verified command inputs, outputs and mutation boundaries.
+- [Skill or command guide](page-templates/skill-command-guide.md) - A reader task guide for invoking one skill or command.
+- [Decisions pointer](page-templates/decisions-pointer.md) - A curated guide to consequential decisions, not a ledger or an ADR.
+- [Per-area AGENTS](page-templates/per-area-agents.md) - Local authoring instructions excluded from reader navigation.

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

@@ -4,9 +4,9 @@ description: Run when you need to evaluate documentation structure, navigation,
 argument-hint: '[target] [--ia] [--ia-guidance <path|url>]'
 disable-model-invocation: true
 user-invocable: true
-allowed-tools: Read, Write, Bash(git:*), Bash(oat config:*), Bash(oat docs nav sync --check:*), Bash(pnpm:*), Bash(bash:*), Bash(jq:*), Bash(node:*), Bash(mkdir:*), Bash(date:*), Bash(echo:*), Bash(cd:*), Bash(pwd:*), Glob, Grep, AskUserQuestion, Task
+allowed-tools: Read, Write, Bash(git:*), Bash(oat config:*), Bash(oat docs nav sync --check:*), Bash(oat docs check:*), Bash(pnpm:*), Bash(bash:*), Bash(jq:*), Bash(node:*), Bash(mkdir:*), Bash(date:*), Bash(echo:*), Bash(cd:*), Bash(pwd:*), Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: '1.7.2'
+  version: '1.7.3'
 ---
 
 # Docs Analysis
@@ -457,6 +457,17 @@ where the docs should live, and what specific subtopics the codebase shows shoul
 
 ### Step 6: Check Navigation and Drift
 
+Probe the installed `oat docs check --help`, then run its read-only
+`oat docs check --target-dir <resolved-root> --json` (or the repo’s documented
+source/local CLI equivalent). Retain exact findings and exit; errors fail while
+warning-only passes. Use stable rule IDs/locations as evidence for recommendations,
+including reader limits, contributor commands, Mermaid/SVG and provenance. It
+executes no page code or documented commands and needs no build. Missing capability
+or unusable Git diagram base is explicitly unverified. Preserve specialized local
+validators; portable success does not establish coverage or claim accuracy. Review
+narrow reason-bearing exceptions from actual config, never invent blanket
+suppressions or automatic navigation ownership.
+
 If a generated root index or manifest exists:
 
 1. Compare generated entries with the authored `## Contents` graph.

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

@@ -6,7 +6,7 @@ disable-model-invocation: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 user-invocable: true
 metadata:
-  version: '1.2.0'
+  version: '1.2.1'
 ---
 
 # OAT Docs Authoring

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

@@ -45,6 +45,10 @@ When navigation, file placement, or `## Contents` changes:
 If generated output is ignored, absent by policy, or cannot be produced in the
 current environment, record the exact reason in the handoff.
 
+## Portable checker
+
+Run the installed `oat docs check --target-dir <resolved-root> --json` when available, or the repository’s documented source/local CLI equivalent. It is read-only and needs no site build. Keep findings and exit: errors fail, warning-only passes. Review warnings, repair authored metadata/maps/links and explicitly sync owned navigation; never add blanket exclusions to pass. Missing CLI capability is unverified, not a successful check. Preserve existing app-specific validators. See the installed checker command docs for stable rule IDs and narrow reason-bearing `documentation.check` exceptions.
+
 ## Local Contract Checks
 
 Before finishing:

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

@@ -6,7 +6,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 metadata:
-  version: '1.4.3'
+  version: '1.4.5'
 ---
 
 # Docs Bootstrap
@@ -40,6 +40,8 @@ Bootstrap or adopt documentation in this repo and guide the user through underst
 - Inspecting native scaffold capabilities and reporting missing current-template guidance without rewriting it
 - Running install + build and classifying failures against known patterns
 - Reading `.oat/config.json` back to verify paths and prompting for `requireForProjectCompletion`
+- Presenting concrete PR CI edits from `references/pr-ci.md`, writing only the approved diff while preserving existing workflows
+- Presenting the exact effective-install-root compatibility policy below and writing only that approved root-policy edit while preserving existing settings/conflicts
 - Narrating the scaffolded output as a chunked educational walkthrough
 - Delegating optional initial content population to `oat-docs-analyze` + `oat-docs-apply`
 
@@ -118,8 +120,8 @@ The detailed framework procedures below apply to Fumadocs/MkDocs. When the selec
 2. **Gather inputs:** Offer “Markdown (plain files), Fumadocs, or MkDocs?” Collect documentation title (`--site-name`), dedicated relative target directory (default `docs` in every repo shape), and optional description. Reuse an existing compatible configured Markdown root. Ask no app/package name, package-manager, site-runtime, or dependency questions. Lint and format default to `none`; describe selected existing repository tools only, without installing them. Validate a nonempty title and a dedicated in-repository target, excluding the repository root and escaping symlinks. Confirm fresh setup or additive adoption, title, root, and audit handoff. `appName` is absent and `conflictResolution` is `adopt`, `audit`, `abort`, or null for this path.
    Before Markdown CLI invocation, run **Step 2.5** for fresh setup and explicitly selected adoption; it is not bypassed by this condensed path.
 
-3. **Invoke CLI:** Probe `$CLI_CMD docs init --help` and require advertised Markdown/`--adopt` support before invocation; if missing, report the needed CLI update rather than fabricating scaffold files. Run `$CLI_CMD docs init --framework markdown --target-dir <root> --site-name <title> --description <description> --lint none --format none --yes`, adding `--adopt` only for explicit adoption. Pass the selected lint/format values when using existing tools. Never pass app-only flags. An optional `--dry-run` previews file/config/guidance changes without writes; it does not count as a completed bootstrap. Capture terminal/JSON results, exact exit, created/preserved files, config changes, guidance action, and audit advice. `partial`/exit 1 with manual-required or blocked guidance means unresolved guidance; real runs may have created files, whereas dry-runs have only planned files. Report actual state and stop before claiming completion. Other refusals also stop without template repairs. For success, read config back to resolve the actual content root and authored index.
-4. **Verify files:** Print `[4/7] Verifying files…`. Check config root/index, baseline file existence, nonempty `title`/`description`, useful audience/scope context and populated `## Contents` links resolving to actual sibling pages or child `index.md`s. Honor excludes and asset-only exceptions; preserve local AGENTS instructions. Fresh setup creates only authored `index.md` and `contributing.md` in the target; verify no docs-root AGENTS, app package, framework config, dependencies, or root build changes. Run already documented lint/link/format checks when applicable; otherwise inspect files/links directly. Adoption preserves existing bytes and may leave missing child indexes, metadata, context, or links: record these as audit gaps for analyze/apply rather than repairing them or calling the tree fully conformant. Distinguish successful setup verification from content-conformance findings.
+3. **Invoke CLI:** For fresh setup, pass the explicitly approved nearest preset and anticipated reader-page count together as `--ia-preset <preset> --planned-pages <count>` only when both are advertised. Adoption never receives these flags. Probe `$CLI_CMD docs init --help` and require advertised Markdown/`--adopt` support before invocation; if missing, report the needed CLI update rather than fabricating scaffold files. Run `$CLI_CMD docs init --framework markdown --target-dir <root> --site-name <title> --description <description> --lint none --format none --yes`, adding `--adopt` only for explicit adoption. Pass the selected lint/format values when using existing tools. Never pass app-only flags. An optional `--dry-run` previews file/config/guidance changes without writes; it does not count as a completed bootstrap. Capture terminal/JSON results, exact exit, created/preserved files, config changes, guidance action, and audit advice. `partial`/exit 1 with manual-required or blocked guidance means unresolved guidance; real runs may have created files, whereas dry-runs have only planned files. Report actual state and stop before claiming completion. Other refusals also stop without template repairs. For success, read config back to resolve the actual content root and authored index.
+4. **Verify files:** Print `[4/7] Verifying files…`. Check config root/index, baseline file existence, nonempty `title`/`description`, useful audience/scope context and populated `## Contents` links resolving to actual sibling pages or child `index.md`s. Honor excludes and asset-only exceptions; preserve local AGENTS instructions. Without preset inputs, fresh setup creates only authored `index.md` and `contributing.md` in the target. For approved preset runs, compare the actual reader tree with the accepted selection: selected track directories at 15 or more anticipated reader pages, grouped root Contents and flat reader pages below 15, and flat structure for `flat-small` at any count. Inspect purpose, entry principle, useful section guidance and Contents links to actual pages. Verify the applicable `contributing/templates/` subset (all ten for triad, Engineering feature plus the six operations/reference/agent shapes for domain, six for other presets), retained when flat; `documentation.nonReaderPaths` includes `contributing/templates/**` without losing prior settings, and templates stay outside reader Contents and any separately configured manifest. Check the track table and accepted-selection guidance in `contributing.md`, separate from later IA persistence. In every Markdown run, verify no docs-root AGENTS, app package, framework config, dependencies, sidebar, site build, default manifest, or root build changes. Run `$CLI_CMD docs check --target-dir <literal-root>` and already documented lint/link/format checks when applicable. Errors block conformance; warnings remain review items. Use `references/pr-ci.md` to present checker-only PR wiring with empty build/manifest inputs unless a generated external manifest was separately configured; apply only the approved workflow diff. Adoption preserves existing bytes and may leave missing child indexes, metadata, context, or links: record these as audit gaps for analyze/apply rather than repairing them or calling the tree fully conformant. Distinguish successful setup verification from content-conformance findings.
 5. **Inspect config:** `documentation.tooling` is the string `markdown`; `root` is the literal content directory; `index` is its authored entrypoint, normally `<root>/index.md`. Markdown introduces no `documentation.config`. Preserve unrelated config/excludes/completion settings. Verify deterministic managed root Documentation guidance names that root, Markdown tooling, authored index, and `<root>/contributing.md`; preserve manual/local guidance and surface unresolved disposition. The Step 5e completion opt-in remains available using the docs root rather than an app name, without silently changing an existing value. No nested app-config reconciliation or framework patch inspection applies.
 6. **Walkthrough:** In short chunks, show actual config and `<root>/index.md`: useful context plus the Contents map, title/description metadata, sibling `page.md` and child `section/index.md` links, exclusions and asset-only exceptions. Explain adding a page/section and updating the nearest authored map without overwriting existing context. Root AGENTS Documentation guidance and `<root>/contributing.md` establish agent/human conventions; a preexisting local AGENTS file remains authoritative, but bootstrap creates none. Authored indexes are edited directly. Optional generated inventories require explicit external output, e.g. `$CLI_CMD docs generate-index --docs-dir <root> --output .oat/docs-manifest.md`; output must stay outside the full configured content root and cannot overwrite the configured authored index even with a narrowed `--docs-dir`. Generation does not repoint `documentation.index`. Markdown bootstrap never generates a manifest automatically. Skip framework deep dives and preview-server/build commands.
 7. **Audit handoff and summary:** Offer `oat-docs-analyze` against the literal configured root, followed by `oat-docs-apply` only for approved repairs. An adopted incomplete tree needs that audit; config/guidance alone prove no full conformance. Explain `oat-project-document` for source-backed project deltas. Summarize tooling, actual root/authored index, created/preserved files, guidance/config disposition, ordered IA guidance locators/provenance and proposal recommendation/conflicts, file-check outcomes, unresolved audit gaps, optional manifest ownership, and exact skill handoff. For dry-run/partial/refusal, label the outcome accordingly rather than printing BOOTSTRAP COMPLETE. No app, install, build, patch, or dev-command fields apply.
@@ -390,7 +392,7 @@ through `oat-docs-analyze --ia`; it does not return to scaffold afterward.
    `ask_user` with local/external source citations. Non-repo guidance stays read-only
    and private exemplars are never copied. Cite ordered sources in the proposal
    and final summary, including the built-in path when it wins.
-6. Obtain explicit approval of the selected IA before persistence. After setup,
+6. Include the anticipated total reader-page count in the proposal (exclude contributor, template and toolchain pages). Obtain explicit approval of the selected IA and count before fresh preset materialization or persistence. For a fresh empty target, transport the approved nearest preset and count using the capability-gated flags below. Existing surfaces and explicit adoption retain their preserve-and-analyze flow without preset flags. After setup,
    use apply's `record-ia` procedure: target-repo `oat pjm doctor --json` and
    adoption check before `oat decision new`, an Information architecture section
    in the framework docs-app AGENTS.md or Markdown contributing page, and shared
@@ -399,7 +401,7 @@ through `oat-docs-analyze --ia`; it does not return to scaffold afterward.
    it unrecorded. Do not silently initialize PJM. For an existing surface, hand
    off an analysis artifact plus approved recommendation IDs to apply, with
    individual approval for explicit record/restructure/tooling items.
-   This IA selection stage does not materialize preset trees or change ownership for an existing app.
+   Preset materialization is CLI-owned and only for fresh empty targets; it does not record an IA decision or change ownership for an existing app.
    Sidebar ownership is separately chosen for existing framework apps; absent
    remains undeclared, Markdown ignores it, and no automatic nav generation is
    authorized by IA approval alone.
@@ -416,7 +418,7 @@ Print `[3/7] Scaffolding…` at the start of this step.
 
 For an explicitly fresh Fumadocs/MkDocs app, current CLI init writes `documentation.navOwner: nav-sync` and generates navigation after successful scaffold/config. An explicitly selected new app in a repository with prior docs config is fresh creation; preserve the old app's authored files. This does not authorize regeneration of an existing app: keep undeclared/hand-authored ownership untouched and use the existing analyze/apply handoff. IA approval alone never authorizes navigation writes. Markdown and dry runs run no nav sync.
 
-Inspect the generated package scripts rather than adding a duplicate patch: Fumadocs `prebuild` and MkDocs `docs:build` run `nav sync --check`, using external `oat` from the app directory with `--target-dir .`, or source-workspace CLI with the explicit quoted repo-relative app. A stale navigation check requires fixing authored Contents and explicitly syncing owned navigation before retrying, not deleting the check or silently regenerating an undeclared owner.
+Inspect the generated package scripts rather than adding a duplicate patch: `docs:check` runs the portable checker and MkDocs `test` runs the same real check. Framework builds run the checker before navigation/build. Fumadocs `prebuild` and MkDocs `docs:build` run `nav sync --check`, using external `oat` from the app directory with `--target-dir .`, or source-workspace CLI with the explicit quoted repo-relative app. A stale navigation check requires fixing authored Contents and explicitly syncing owned navigation before retrying, not deleting the check or silently regenerating an undeclared owner.
 
 **3a. Assemble CLI flags.**
 
@@ -434,6 +436,7 @@ Base flags (always passed):
 
 Capability-gated flags (added only when the Capability Probe reports support):
 
+- `--ia-preset {preset}` and `--planned-pages {count}` — pass together only for an explicitly approved fresh empty target, after both capabilities are advertised. IDs: `product-engineering-qa`, `consumer-maintainer`, `domain-engineering`, `task-type`, `toolkit-cli`, `flat-small`. Count is an integer of at least 1, with no implicit preset/default or interactive CLI choice. If either capability is absent, stop this handoff and recommend a CLI update. Do not substitute a file-write plan, copy templates manually, or use preset init to replace an existing surface.
 - `--site-name {siteName}` — only if `capabilities.siteNameFlag === true`. If absent, stop before scaffolding and recommend updating the CLI; do not rewrite the older template output.
 - `--no-root-patch` — only if `capabilities.noRootPatchFlag === true` and the Preflight / Conflict Resolution result says root package mutation should be skipped. This is recommended for no-root-package repositories or when the user explicitly chose no root mutation; current CLI builds also auto-skip when no root `package.json` exists, so the flag is optional documentation of intent, not a recovery mechanism.
 
@@ -443,12 +446,17 @@ Do not pass flags the CLI doesn't advertise. Never assume a flag exists because
 
 Before CLI invocation, run `$CLI_CMD docs init --help` once. Record:
 
+- `iaPresetFlag` and `plannedPagesFlag`: whether `--ia-preset` and `--planned-pages` are both advertised. Require both for the approved fresh selection, including the Markdown path.
 - `siteNameFlag`: whether `--site-name` is advertised.
 - `agentsMdScaffold`: whether the installed framework template file list confirms native app-root `AGENTS.md` scaffolding; if unavailable, record unknown and verify actual output after invocation. Do not infer a CLI flag from this capability.
 - `noRootPatchFlag`: whether `--no-root-patch` is advertised.
 
 If the probe fails or returns no help, stop with the verbatim error and recommend updating or repairing the CLI. Never guess capabilities.
 
+After preset init, inspect actual files and config before claiming success. At 15 or more anticipated reader pages, verify the selected track directories: triad `product/`, `engineering/`, `qa/`; consumer/maintainer `consumer/`, `maintainer/`; domain `engineering/`; task type `tutorials/`, `how-to/`, `reference/`, `explanation/`; toolkit `tools/`, `workflows/`. Below 15, or for `flat-small` at any count, verify grouped root Contents and flat reader pages instead. The exact CLI cutoff implements the approximate authoring heuristic, without selecting a different reader model. Track indexes own purpose, entry principle and useful section headings; they do not manufacture every section directory.
+
+Verify the track table/accepted-selection guidance in framework app-root AGENTS, or Markdown `contributing.md`. Engineering stays hybrid (domain/implementation contracts alongside paired features); Product/QA enter by feature or journey. Check the applicable `contributing/templates/` subset: all ten for triad, Engineering feature plus the six operations/reference/agent shapes for domain, six for other presets. Size collapse retains the subset. Screen specs and per-area AGENTS are copyable only, never automatically instantiated. Verify `documentation.nonReaderPaths` includes `contributing/templates/**` without losing prior settings, and templates stay out of Contents, sidebar and manifest. `excludes` remains manifest-only; pinned MkDocs may still render non-reader routes and retains `use_directory_urls: false`. Run the real checker and framework nav `--check`; repair failures without suppressing rules. Keep approved-selection evidence separate from the later `record-ia` persistence/adoption result.
+
 After scaffolding, inspect `<appRoot>/AGENTS.md`: absence is a missing-capability finding with analyze/manual upgrade advice; any existing file is preserved. No missing-file bridge is permitted. Check template output against the current scaffold contract. Older output with missing metadata, unresolved Node-version advice, missing generated-files guidance, extension-less Contents links, duplicated agent instructions, or a Fumadocs wrapper that loses static export settings becomes a finding under `oat-docs-analyze`'s legacy scaffold checks (load that skill from installed scope and resolve `references/legacy-scaffold-checks.md` from its own directory). Record the observed path and evidence, then offer analyze; do not reinstate template patches. Ambiguous or user-authored shapes are reported for review, never overwritten.
 
 **3c. Invoke the CLI.**
@@ -516,6 +524,40 @@ Print `[4/7] Verifying build…` at the start of this step.
 
 Skip this step entirely if `Scaffold Result.scaffoldSucceeded !== true` — a failed scaffold produces an undefined state; installing and building on top of it makes things worse.
 
+**4a prerequisite: inspect and approve Fumadocs install-root policy.**
+
+Before running install, read the CLI's `installationAdvice` and the generated
+toolchain guide. Locate the actual pnpm installation root, including any enclosing
+`pnpm-workspace.yaml`; a workspace member's package is not that root. Current
+Fumadocs loses handler properties added by `mdast-util-to-markdown` 2.2.0, so valid
+bold/italic content can fail compilation. Preserve all content and framework APIs.
+The required compatibility constraint is exactly 2.1.2 in the effective root's
+`pnpm-workspace.yaml`:
+
+```yaml
+overrides:
+  mdast-util-to-markdown: 2.1.2
+```
+
+A newly scaffolded independent app has its own root YAML (`packages: []` plus
+this override); inspect it and install there. The CLI never creates this boundary
+in monorepo mode or under an enclosing pnpm workspace. For an existing workspace
+root, PRESENT the exact concrete YAML diff and obtain explicit approval before
+writing it. Preserve package globs and all unrelated settings; add the entry to
+an existing `overrides` map, never duplicate the map or replace the file. A
+conflicting existing pin requires the owner's decision; a declined/skipped edit
+stays a manual setup requirement and verification remains pending. Do not create
+a local boundary that splits a workspace member. Do not implement a policy merger
+or silently extend CLI root-package patching: it changes build scripts only,
+and `--no-root-patch` neither sets nor approves dependency policy.
+
+Honor the selected manager (pnpm 10+); effective-root YAML works in pnpm 10 and 12.
+A member-only override is ignored in 10, and 12 also ignores `package.json`'s
+`pnpm.overrides`. After install, inspect actual `pnpm why mdast-util-to-markdown`
+from that root, confirm 2.1.2, retain the root config/lockfile, then run checker and
+build. Label this a constrained fresh install; do not promise unconstrained
+resolution, change user-scope pnpm, or delete bold/italic to avoid the failure.
+
 **4a. Install dependencies.**
 
 Command varies by repo shape (from Preflight Result) and framework (Fumadocs only uses pnpm; MkDocs uses Python tooling — handled in the MkDocs Minimum Contract, Step 6):
@@ -526,6 +568,8 @@ Command varies by repo shape (from Preflight Result) and framework (Fumadocs onl
 
 For Fumadocs, capture both stdout and stderr. Print a start line (`Installing dependencies…`) and a completion line with duration.
 
+Before building, run `$CLI_CMD docs check --target-dir <configured-root>` from the repo root. Keep its JSON/findings and exit; metadata/maps/links, contributor commands and real Mermaid syntax are checked without executing page code. Errors stop verification; review warnings and route content repairs through analyze/apply. Never add blanket suppressions to pass bootstrap.
+
 **4b. Build.**
 
 Command varies by shape:
@@ -572,6 +616,7 @@ Record internally for the Post-Scaffold Inspector and Walkthrough:
 
 ```
 Verification Result:
+  installRootPolicy: { path, disposition: 'scaffolded' | 'approved' | 'manual' | 'conflict', resolvedVersion } | null
   installSucceeded: boolean
   buildSucceeded: boolean
   knownIssues: Array<{ pattern, severity: 'benign' | 'flagged' | 'surface-only' | 'auto-fixed', detail }>
@@ -670,6 +715,16 @@ Inspection Result:
 
 The Walkthrough's Section D (Configuration readback) references `issues[]` verbatim — format it so it reads cleanly when printed to the user.
 
+**PR CI wiring (after config inspection):** Load `references/pr-ci.md` now.
+Resolve its concrete inputs from the inspected config/scripts, present the exact
+workflow diff, and write only after approval. Preserve existing workflow content
+and use full-history checkout/fetch for the applicable diagram base. Execute its
+checker, real framework build and configured-manifest freshness commands locally;
+record exits and unverified portions. Markdown follows the same recipe with no
+build/default manifest. Include the approved workflow path or declined/pending
+status in the exit summary. This is bootstrap setup authority, not permission to
+rewrite an existing app or introduce deployment.
+
 ### Step 6: Educational Walkthrough
 
 Narrate the scaffolded docs app as a chunked conversation, not a wall of text. The Walkthrough's job is to turn the user from "I ran a scaffold" into "I know how this docs app works". It is **not** a re-explanation of the CLI's output, nor a recitation of the AGENTS.md content — both are live files the user can read; the Walkthrough contextualizes them.
@@ -883,6 +938,8 @@ Agent guidance:
 Build:
   - Install: {ok | known-issue: ...}
   - Build:   {ok | known-issue: ...}
+  - Install policy: {effective-root YAML + resolved 2.1.2 | manual/conflict/pending; constrained install}
+  - PR CI: {approved workflow path + checker/build/freshness exits | declined | pending}
   - Known issues (from Verification Result.knownIssues): {list or 'none'}
 
 Inspection: