@open-agent-toolkit/cli 0.3.28 → 0.3.30

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(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
+allowed-tools: Read, Write, Bash(git:*), Bash(oat config:*), Bash(oat docs nav sync --check:*), Bash(oat docs check:*), Bash(oat docs literals:*), 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.3'
+  version: '1.7.4'
 ---
 
 # Docs Analysis
@@ -336,7 +336,8 @@ app's docs avoid merely mirroring implementation directories. Review coverage
 only for declared readers: Product features/journeys/screens/states; QA scenario
 tables with seeds and automation references; consumer first-success/task guides;
 agent entrypoints, canonical sources and verification commands. Do not demand
-these tracks from every repository or implement the later P24 source checks.
+these tracks from every repository. For an accepted triad, also perform the
+conditional source assessments below.
 
 Top-level IA misroutes a declared audience: `High` when the reader cannot find
 a normal first-success or required verification path; `Medium` when that path
@@ -389,6 +390,91 @@ Evidence standard for this step:
 - If multiple repo files are needed to verify a claim, cite all relevant sources.
 - If the canonical source is ambiguous, mark the claim `unverified` rather than guessing.
 
+### Conditional triad source assessments (P24)
+
+Run these six assessments only after the authored **accepted** IA decision and
+local Information architecture section agree with the mirror's
+`verification: triad`. Cite that agreement first. A mirror alone does not prove
+acceptance. For absent, `agent-only`, or `none` overlays, record not applicable
+and continue ordinary analysis unchanged. Missing/broken authored acceptance or
+a conflicting mirror blocks these assessments with `unverified` / `ask_user`;
+it does not block ordinary analysis or justify choosing an IA.
+
+Map Product, QA and Engineering feature subsets from the accepted decision,
+tracks/principles and local guidance, citing each mapping. Do not infer roles
+from fixed folder names or tracks array order. Engineering may mix domain
+contracts with feature pages: compare only its mapped feature subset. A grouped
+flat IA may have no per-feature triad; explain not applicable rather than invent
+folders. An unresolved mapping stays `unverified` / `ask_user` without new config.
+
+1. **Slug parity.** Compare relative feature/journey keys in the mapped subsets.
+   Exclude indexes, support pages, templates and Engineering domain contracts.
+   Cite missing/extra peers and the declared mapping before recommending repair.
+2. **Paired documentation.** Inspect each member's actual peer links, resolving
+   relative paths and anchors within the repository. Accept case-insensitive
+   Paired Documentation headings and QA's canonical Scope links when they point
+   to the appropriate Product/Engineering peers. A heading alone or an unrelated
+   resolving link is insufficient. Cite both link and target/anchor; unresolved
+   or wrong-peer links become evidence-backed findings.
+3. **Quoted literals and concepts.** Select Product/QA reader Markdown and narrow
+   canonical implementation directories from cited source references/local
+   guidance, then invoke the read-only helper (repeat one value per flag):
+
+   ```bash
+   oat docs literals --target-dir <resolved-target> \
+     --page <product-page> --page <qa-page> \
+     --source-root <implementation-dir> \
+     --source-exclude <generated-or-fixture-pattern> --json
+   ```
+
+   Pages are content-relative; roots and exclusions are repository-relative.
+   Never scan the repository root, dependencies, home or external sources.
+   Select implementation roots and exclusions that omit docs, templates,
+   generated/vendor output and example/test fixtures as evidence. The helper
+   does not automatically exclude documentation from selected source roots;
+   a match to documentation itself is not canonical implementation support.
+   Inspect the returned scope, searched files and skipped symlink/binary/non-UTF8
+   inputs; incomplete traversal or invalid selections fail visibly. Missing
+   canonical sources remain unverified; do not broaden scanning to manufacture
+   matches.
+
+   The helper extracts AST inline code, ignores fences, and performs exactly
+   one strict HTML entity decode per value and physical source line, followed
+   by case-sensitive substring matching. It reports the first lexical source
+   file/physical line, without snippets or a runtime verdict. CommonMark can
+   normalize multiline spans; source matching stays per physical line. It does
+   not fold whitespace/Unicode, decode JS escapes, evaluate interpolation or
+   load i18n/runtime values. A found substring can be in a comment, dead code,
+   fixture or longer text: read the citation and judge canonical relevance.
+   `not-found` is initially **unverified**, never automatic contradiction.
+   Require a differing canonical value before judging contradicted. Distinguish
+   intentionally explained concepts from UI literals; prose concepts need no
+   occurrence, while ambiguous backticked concepts require clarification or a
+   cited conceptual explanation. Exit 0 means completed candidates (including
+   not-found/not-applicable), not verified documentation.
+
+4. **Test-ID registry membership.** Locate the repository's actual canonical
+   test-ID registry and read its real format. Check exact member equality,
+   never substring occurrence in arbitrary source. Cite registry and docs.
+   Missing/ambiguous registry stays `unverified` / `ask_user`; do not invent a
+   registry path/schema or treat helper matches as membership proof.
+5. **Scoped scenario candidates.** Inspect QA tables for duplicate IDs and the
+   same scoped Given + When with different Then outcomes. Compare feature,
+   seed, platform and configuration preconditions before judging contradiction;
+   meaningful differences can explain the result. Cite both rows and scope.
+   Ambiguous scope stays unverified. This is judgment, not a scenario engine.
+6. **Templates in authored Contents.** Read raw authored `## Contents` links
+   before applying reader/nav exclusions. Flag links that expose drafting
+   templates as reader destinations even when `nonReaderPaths` makes nav/check
+   skip them; cite the map entry and template purpose/local declaration. Do not
+   infer safety from a clean generated nav or checker result.
+
+Record applicability, mappings, docs/source citations, candidates and judgments
+in the existing artifact's Accuracy Verification section. Use the existing
+severity and recommendation `approval: explicit | default` classes; missing
+mapping/registry evidence is not permission to add a schema or implementation.
+No P24 `oat docs check` rule is added, and its G5 JSON/rule IDs are unchanged.
+
 ### Step 5: Analyze Content Coverage Opportunities
 
 Add a coverage-gap pass after accuracy verification.

package/assets/skills/oat-docs-analyze/references/analysis-artifact-template.md

@@ -247,6 +247,29 @@ runtime-only behavior here.
 
 {Or: "No repo-checkable substantive claims required accuracy verification."}
 
+### Conditional triad source assessments (P24)
+
+- Gate: {accepted authored IA + local section citations and mirror agreement;
+  non-triad: not applicable; missing/conflict: unverified / ask_user}
+- Role/subset mapping: {Product, QA, Engineering feature roots and citations;
+  hybrid domain exclusions; flat applicability; never folder names/array order}
+- Literal helper: {exact invocation; scope, searched files and skipped reasons;
+  occurrence candidates only, not a runtime verdict}
+
+| Assessment                 | Docs / canonical evidence                                      | Candidate and judgment                                                                  |
+| -------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| Slug parity                | {mapped feature keys and missing/extra peers}                  | {verdict or unverified / not applicable}                                                |
+| Paired documentation       | {peer links + resolved target anchors; QA Scope accepted}      | {correct peers, not just any resolving link}                                            |
+| Quoted literals / concepts | {helper path:line + canonical source / conceptual explanation} | {found requires relevance judgment; not-found initially unverified}                     |
+| Test-ID registry           | {actual registry path:line + exact member}                     | {membership; absent registry unverified / ask_user}                                     |
+| Scoped scenarios           | {both rows + feature/seed/platform/config scope}               | {duplicate ID / same Given+When with differing Then candidate; explained or unresolved} |
+| Raw authored Contents      | {map entry + template purpose / nonReaderPaths}                | {flag reader links to templates even when nav excludes them}                            |
+
+Keep one strict HTML entity decode per side and physical-source-line matching
+limits visible. No JS/i18n evaluation, runtime claim, invented mapping/registry,
+or automatic contradiction from absence. Recommendations retain existing
+approval classes and docs/source citations.
+
 ## Coverage Review by Surface
 
 Summarize which documentable surfaces were proven by repo evidence and how well

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

@@ -55,6 +55,24 @@ Use this checklist when evaluating a docs surface.
 - Referenced paths exist.
 - Tooling/setup instructions are current.
 
+## Conditional triad source assessments (P24)
+
+- Authored accepted IA and local section agree with the mirror's triad overlay;
+  other overlays are not applicable, missing/conflicting evidence unverified / ask_user.
+- Roles and feature subsets come from cited decisions/local guidance, including
+  renamed tracks, hybrid Engineering and flat applicability; no folder/order inference.
+- Slug parity compares only mapped feature keys, excluding support/domain pages.
+- Peer links resolve to the correct member and anchor; QA Scope links count.
+- Product/QA literals use `oat docs literals` with explicit pages, narrow source
+  roots and source exclusions. Scope, searched files and skipped reasons are reviewed.
+- Once-decoded, case-sensitive physical-line occurrences receive canonical-source
+  judgment; not-found remains unverified and explained concepts are distinguished.
+- Test IDs use exact membership in the actual registry; absent registry stays unverified.
+- Duplicate IDs and same scoped Given+When/different Then candidates are judged
+  with seed/platform/configuration evidence, never automatically contradicted.
+- Raw authored Contents links to templates are flagged despite reader/nav exclusions.
+- Existing severity, citations and recommendation approval classes are preserved.
+
 ## Discoverability
 
 - Important pages are reachable from a parent `index.md` or site nav.

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.4'
+  version: '1.4.5'
 ---
 
 # Docs Bootstrap
@@ -120,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 `$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.
+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.
@@ -392,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
@@ -401,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.
@@ -436,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.
 
@@ -445,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.**

package/dist/commands/docs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/docs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUpC,wBAAgB,iBAAiB,IAAI,OAAO,CAU3C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/docs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAWpC,wBAAgB,iBAAiB,IAAI,OAAO,CAW3C"}

package/dist/commands/docs/index.js

@@ -4,12 +4,14 @@ import { createDocsApplyCommand } from './apply.js';
 import { createDocsCheckCommand } from './check/check.js';
 import { createDocsGenerateIndexCommand } from './index-generate/index.js';
 import { createDocsInitCommand } from './init/index.js';
+import { createDocsLiteralsCommand } from './literals/literals.js';
 import { createDocsMigrateCommand } from './migrate/index.js';
 import { createDocsNavCommand } from './nav/index.js';
 export function createDocsCommand() {
     return new Command('docs')
         .description('OAT documentation bootstrap and maintenance commands')
         .addCommand(createDocsCheckCommand())
+        .addCommand(createDocsLiteralsCommand())
         .addCommand(createDocsAnalyzeCommand())
         .addCommand(createDocsApplyCommand())
         .addCommand(createDocsGenerateIndexCommand())

package/dist/commands/docs/init/content.d.ts

@@ -0,0 +1,23 @@
+export declare const IA_PRESETS: readonly ['product-engineering-qa', 'consumer-maintainer', 'domain-engineering', 'task-type', 'toolkit-cli', 'flat-small'];
+export type IaPreset = (typeof IA_PRESETS)[number];
+export interface PresetSelection {
+    iaPreset?: IaPreset;
+    plannedPages?: number;
+}
+/** Validate the opt-in pair before planning or writing any scaffold files. */
+export declare function resolvePresetSelection(preset?: string, count?: string | number): PresetSelection;
+export declare function mergeTemplateExclusion(paths?: string[]): string[];
+/** Shared narrow content plan; bodies are loaded from the bundled canonical skill. */
+export declare function planPresetContent(options: PresetSelection & {
+    assetsRoot: string;
+    siteName: string;
+    siteDescription?: string;
+    markdown: boolean;
+}): Promise<{
+    files: {
+        name: string;
+        content: string;
+    }[];
+    guidance: string;
+} | null>;
+//# sourceMappingURL=content.d.ts.map

package/dist/commands/docs/init/content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/content.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,UAAU,YACrB,wBAAwB,EACxB,qBAAqB,EACrB,oBAAoB,EACpB,WAAW,EACX,aAAa,EACb,YAAY,CACJ,CAAC;AACX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AACnD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,8EAA8E;AAC9E,wBAAgB,sBAAsB,CACpC,MAAM,CAAC,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GACtB,eAAe,CAiBjB;AAmSD,wBAAgB,sBAAsB,CAAC,KAAK,GAAE,MAAM,EAAO,GAAG,MAAM,EAAE,CAErE;AAQD,sFAAsF;AACtF,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,eAAe,GAAG;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;CACnB,GACA,OAAO,CAAC;IACT,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC3C,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,IAAI,CAAC,CAwFR"}