@open-agent-toolkit/cli 0.3.28 → 0.3.30

package/README.md

@@ -45,10 +45,14 @@ Additional useful entry points:
 
 `oat docs init --framework fumadocs --app-name my-docs` creates a docs app with app-root `AGENTS.md`, a reader-first Getting Started stub and contributor/toolchain guides. The CLI owns these templates for both Fumadocs and legacy MkDocs; the bootstrap skill guides inspection and setup. Existing files and plain Markdown adoption are preserved.
 
+For an approved fresh reader model, pass `--ia-preset <preset> --planned-pages <count>` together. The six presets materialize reader tracks at 15 or more anticipated pages, or grouped flat headings below 15; `flat-small` always stays flat. Canonical page templates go under excluded `contributing/templates/`, with a track table in framework app-root AGENTS or Markdown contributing guidance. Existing surfaces route to analyze/apply. See [preset selection and template subsets](../../apps/oat-docs/docs/docs-tooling/commands.md#approved-preset-readers). Direct init without both inputs retains its starter; selection does not create an IA decision.
+
 Fumadocs static exports include `llms.txt`, `llms-full.txt` and `llms/<page-slugs>/content.md` (root `llms/content.md`) for loaded `.md` readers. These retain authored Markdown and source-relative-link guidance; configured non-readers and MDX are excluded. Use authored Contents maps and `oat docs nav sync`, followed by `--check`, for navigation changes.
 
 `oat docs check [--target-dir <dir>] [--rule <id>...] [--json]` performs read-only reader, navigation, contributor-command and Mermaid/SVG checks without a site build. Errors exit 1; warnings exit 0. Configure validated severities, numeric thresholds and reason-bearing exceptions under `documentation.check`. Mermaid syntax parsing lazily uses a real DOM with strict sanitization and no script/resource execution; Node 22.17 remains the minimum. See [checker rules and configuration](../../apps/oat-docs/docs/docs-tooling/check.md).
 
+`oat docs literals [--target-dir <dir>] --page <content-relative-reader.md> --source-root <repo-relative-dir> [--source-exclude <pattern>] --json` supplies read-only inline-code occurrence candidates for a matching triad IA mirror. Repeat each single-value selection flag as needed. Sources stay within narrow explicit implementation roots; searched/skipped evidence and first source physical lines are reported. Once-only strict HTML entity decoding and case-sensitive line-local substring matching do not establish runtime validity; analyze judges canonical relevance and authored IA acceptance. Completed not-found/not-applicable exits 0, input/config errors 1, unexpected failures 2. See [literal helper scope and limits](../../apps/oat-docs/docs/docs-tooling/commands.md#oat-docs-literals).
+
 Fumadocs starters constrain `mdast-util-to-markdown` to 2.1.2 for the current upstream handler compatibility defect. New independent install roots get `pnpm-workspace.yaml`; workspace members get manual setup advice for the existing root YAML, with approval/conflict preservation in bootstrap. No member-local boundary or root dependency-policy merge is performed; `--no-root-patch` still controls build scripts only. Keep the effective policy and lockfile and verify actual resolution before building.
 
 Framework starters expose `docs:check` and run it before build; MkDocs `test` is a real check. Bootstrap proposes approved PR CI edits with explicit generated-manifest freshness. Markdown needs neither an app build nor a default manifest.

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.3.28"
+  "oatVersion": "0.3.30"
 }

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

@@ -63,6 +63,8 @@ Choose Markdown files or a framework app, using the guided skill or direct CLI.
 
 The docs-bootstrap skill offers Markdown, Fumadocs, and MkDocs. Configured tooling is authoritative; framework evidence is checked before plain-directory evidence. A root README alone does not trigger adoption, and an empty selected target stays fresh setup. Markdown uses file checks and an adopt/audit handoff, with no app questions, dependencies, framework patches, docs-root AGENTS, or site build.
 
+For fresh empty targets, the skill obtains explicit IA approval with an anticipated reader-page count, probes `--ia-preset` and `--planned-pages`, then passes both to CLI init. The CLI materializes the selected model at 15 or more pages and collapses it into grouped root headings below 15 (always flat for `flat-small`). It also supplies relevant non-reader page templates. Existing surfaces use analyze and individually approved apply; adoption receives no preset flags. See [preset mappings and template subsets](commands.md#approved-preset-readers). Selection guidance does not replace the existing IA decision/adoption flow.
+
 For framework apps, it wraps `oat docs init` with a seven-step guided flow: preflight detection (repo shape + existing-setup conflict surfacing), richer input gathering (including a site name distinct from the package name), the CLI invocation itself, CLI-owned scaffold inspection, install + build verification, post-scaffold config inspection, and a chunked educational walkthrough.
 
 What the framework path adds over the raw CLI:

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

@@ -13,7 +13,7 @@ or **MkDocs Material**.
 
 - What it does: documents the docs-specific CLI surface for scaffolding apps, migrating markdown, generating Fumadocs app-root index manifests, and syncing MkDocs or Fumadocs 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`, `oat docs check`
+- Primary commands: `oat docs init`, `oat docs migrate`, `oat docs generate-index`, `oat docs nav sync`, `oat docs check`, `oat docs literals`
 
 ## Command surface
 
@@ -24,6 +24,7 @@ or **MkDocs Material**.
 | `oat docs generate-index` | Generate a manifest from Markdown files, outside authored content.                    |
 | `oat docs nav sync`       | Regenerate `mkdocs.yml` nav or Fumadocs `meta.json` from `index.md` maps.             |
 | `oat docs check`          | Read-only reader, navigation, command and diagram checks; errors fail, warnings pass. |
+| `oat docs literals`       | Read-only occurrence candidates for explicitly selected Product/QA pages in a triad.  |
 | `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.                       |
 
@@ -60,9 +61,53 @@ Key behavior:
 - for framework apps, when the repo root exposes a compatible Turbo `scripts.build`, patches it to exclude the new docs app from the default root build and adds a root-level `build:docs` script
 - prints a unified diff before writing the root `package.json` change and returns a manual snippet when the patch is skipped because the build script is missing, non-Turbo, or ambiguous
 
-Markdown setup:
+### Approved preset readers
+
+Opt into an approved reader model with `--ia-preset <preset> --planned-pages <count>`.
+Both flags are required together; the count is an integer of at least 1 and covers
+anticipated reader pages, excluding contributor/toolchain/template content. No flags
+keeps the existing starter. Preset init requires an empty target and refuses existing
+docs config/ownership; use analyze and individually approved apply for existing trees.
+
+| Preset                   | Reader directories at 15 or more anticipated pages    | Templates                                   |
+| ------------------------ | ----------------------------------------------------- | ------------------------------------------- |
+| `product-engineering-qa` | `product/`, `engineering/`, `qa/`                     | All ten                                     |
+| `consumer-maintainer`    | `consumer/`, `maintainer/`                            | Six support shapes                          |
+| `domain-engineering`     | `engineering/`                                        | Engineering feature plus six support shapes |
+| `task-type`              | `tutorials/`, `how-to/`, `reference/`, `explanation/` | Six support shapes                          |
+| `toolkit-cli`            | `tools/`, `workflows/`                                | Six support shapes                          |
+| `flat-small`             | Always grouped headings in one flat root index        | Six support shapes                          |
+
+Below 15 pages, each model uses grouped root headings and flat reader pages while
+retaining its template subset. Track entries have purpose, entry principle and
+useful sections. Engineering is hybrid: domain/implementation contracts alongside
+paired feature pages; Product/QA enter by feature or journey.
+
+Templates live under `contributing/templates/`: Product feature, Engineering
+feature, QA validation, conditional Screen spec, Alert runbook, incident Solution
+record, Command reference, Skill or command guide, Decisions pointer and Per-area
+AGENTS. The six support shapes are the last six in that list. Screen pages and
+per-track AGENTS are never automatically instantiated. Bodies come from canonical
+`authoring-docs` assets, with verified-literal rules and separate planned automation,
+implemented assertions and dated execution evidence.
+
+The CLI merges `contributing/templates/**` into `documentation.nonReaderPaths`
+before nav generation. These drafts stay out of reader Contents, navigation,
+checker inventory and manifests; `excludes` remains manifest-only. Pinned MkDocs
+1.4.2 can still render excluded routes and retains `use_directory_urls: false`.
+Framework app-root AGENTS gets the track table; Markdown uses `contributing.md`,
+with no docs-root AGENTS, dependencies, sidebar, build or default manifest.
+Selection guidance is not a persisted IA decision: bootstrap still requires explicit
+approval and the existing adoption/`record-ia` flow, without implicit PJM adoption.
 
-- Creates only authored root `index.md` and `contributing.md` baseline pages,
+```bash
+oat docs init --framework markdown --ia-preset toolkit-cli --planned-pages 14 --yes
+oat docs init --framework fumadocs --ia-preset product-engineering-qa --planned-pages 30 --yes
+```
+
+### Default Markdown setup
+
+- Without preset inputs, creates only authored root `index.md` and `contributing.md` baseline pages,
   with metadata, context and real relative `.md` Contents links.
 - Records literal root/tooling/authored index and managed root guidance; no
   docs-root AGENTS, app package, dependencies, package/Turbo patch or site build.
@@ -112,6 +157,7 @@ Supported flags:
 - `--framework <markdown|fumadocs|mkdocs>` (default: `fumadocs` in non-interactive mode)
 - `--site-name <name>` (site display title or Markdown documentation title)
 - `--description <text>` (documentation description, optional)
+- `--ia-preset <preset>` and `--planned-pages <count>` (approved fresh selection; pair required, integer count >= 1)
 - `--lint <none|markdownlint-cli2>`
 - `--format <oxfmt|none>`
 - `--adopt` (Markdown only; add missing baseline files, preserve existing bytes)
@@ -270,6 +316,68 @@ Related reference:
 
 - [`../reference/docs-index-contract.md`](../reference/docs-index-contract.md)
 
+## `oat docs literals`
+
+After `oat-docs-analyze` confirms the authored accepted IA and config mirror
+agree on `verification: triad`, select Product/QA reader pages and narrow
+canonical implementation directories:
+
+```bash
+oat docs literals --target-dir manual \
+  --page experience/save.md --page verify/save.md \
+  --source-root src/ui --source-exclude src/ui/generated/ --json
+```
+
+`--target-dir` is optional and uses the same configured-root/app/content
+resolution as check. `--page` and `--source-root` are required, repeatable
+single-value flags. Pages are content-relative Markdown (`.md` or `.mdx`,
+without evaluating JSX); roots are repo-relative directories, never the repo
+root. Source roots must also use their canonical on-disk spelling (including case).
+Pages must use their canonical on-disk spelling (including case) and be
+readable readers within the real content tree, outside `nonReaderPaths`,
+with no symlink components below the resolved content root
+(including page files and directory aliases). Sources must remain within the
+repository; nested symlinks are skipped, never traversed. Invalid/escaping selections, unreadable traversal
+and an empty effective text inventory fail visibly. Select implementation
+roots and explicit exclusions to omit docs, fixtures, generated output and
+vendor code 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 citation and judge its relevance.
+
+`--source-exclude` is optional/repeatable, using the existing bounded POSIX
+exclusion grammar in **repository** coordinates: segment `*`, whole-segment
+`**`, trailing `/` for directories; other metacharacters are literal. Parent
+segments, absolute patterns and backslashes are invalid. `documentation.excludes`
+remains manifest-only; `nonReaderPaths` remains content-relative.
+
+Only a matching mirror declaring triad enables extraction. Other overlays,
+absent IA or an unrelated explicit target return `not-applicable` with reason
+and empty candidates before selected pages/sources are read. This gate does
+not establish authored acceptance; the skill judges that separately.
+
+JSON completion has `status: ok`, `scope: {contentRoot, pages, sourceRoots,
+sourceExcludes}`, `searched` source paths, `skipped: [{path, reason}]`, and
+`literals: [{path, line, literal, normalized, status, source?}]`. Candidate
+status is `found` or `not-found`; source is `{path, line}`. Docs locations are
+content-relative; contentRoot/source scope is repo-relative POSIX. Duplicate
+pages/overlapping inventories are deduplicated. Page order and source file
+order are lexical, then physical line order; the first source occurrence is
+reported. Skipped reasons include symlink, binary, non-UTF8 and non-regular.
+No source snippets, severity or runtime verdict are emitted.
+
+Extraction uses Markdown AST inline code and ignores fenced blocks. Matching
+applies one strict HTML entity decode to each value and each physical source
+line, then a case-sensitive substring search. CommonMark may normalize multiline
+spans; source matching stays per physical line. There is no whitespace/Unicode
+folding, JS escape decoding, interpolation, i18n loading or runtime evaluation.
+A comment, dead code or longer text can match. Inspect canonical relevance;
+`not-found` starts as unverified, and explained concepts require judgment.
+
+Exit 0 means completed evidence, including not-found/not-applicable; exit 1 is
+an actionable input/config error; exit 2 is an unexpected runtime failure.
+Global `--json`/`--cwd` work as usual. This helper is separate from check's G5
+rules, and `oat docs analyze` remains a guidance entrypoint.
+
 ## `oat docs analyze` and `oat docs apply`
 
 These CLI commands intentionally reserve the docs workflow surface without

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

@@ -508,6 +508,22 @@ consumer and agent coverage. A top-level misroute is High when it blocks normal
 first success/verification, Medium when it causes material detours; cosmetic
 organization stays Low. Missing IA/owner raises `ask_user`.
 
+When the authored accepted IA and its mirror agree on triad verification,
+analyze also checks six source-related concerns: mapped feature slug parity,
+real peer links/anchors (including QA Scope pairing), quoted literals versus
+explained concepts, exact membership in the repository's own test-ID registry,
+scoped duplicate/contradictory scenarios, and raw Contents links to templates
+even when nav excludes them. Roles come from the decision/local guidance,
+including renamed tracks and hybrid Engineering; flat layouts may be not
+applicable. Missing mapping/registry stays unverified / `ask_user`. Other
+overlays continue ordinary analysis unchanged.
+
+The [literal occurrence helper](commands.md#oat-docs-literals) supplies bounded
+text candidates for selected Product/QA pages. A found substring requires
+canonical-source judgment; not-found is initially unverified. It cannot prove
+runtime behavior, registry membership or scenario correctness. Accepted IA,
+source citations and existing recommendation approval classes still govern.
+
 For framework apps, offline drift compares installed `@open-agent-toolkit/docs-*` packages to the
 running CLI's bundled `public-package-versions.json`, never registry latest.
 Missing installations are unverified. The recommendation includes the exact

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

@@ -80,6 +80,8 @@ Lifecycle](../workflows/backlog-and-planning/backlog-lifecycle.md).
 
 `oat docs check [--target-dir <dir>] [--rule <id>...] [--json]` validates reader structure, links, navigation, contributor commands and diagrams without a site build. Errors exit 1; warning-only exits 0. See [Check Documentation](../docs-tooling/check.md) for rules/config and JSON.
 
+`oat docs literals --page <reader.md> --source-root <implementation-dir> [--target-dir <dir>] [--source-exclude <pattern>] --json` reports bounded inline-code occurrence candidates for triad IA mirrors. Pages and roots are repeatable single-value flags in content/repository coordinates respectively. Found candidates require canonical-source judgment. See [literal helper scope, JSON and limits](../docs-tooling/commands.md#oat-docs-literals).
+
 ## Command Groups
 
 | Command group                                   | What it covers                                                                                                                                                                                                             | Go deeper                                                                                   |

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.3.28",
-  "docs-config": "0.3.28",
-  "docs-theme": "0.3.28",
-  "docs-transforms": "0.3.28"
+  "cli": "0.3.30",
+  "docs-config": "0.3.30",
+  "docs-theme": "0.3.30",
+  "docs-transforms": "0.3.30"
 }

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

@@ -6,7 +6,7 @@ disable-model-invocation: false
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 user-invocable: true
 metadata:
-  version: 1.1.0
+  version: 1.2.0
 ---
 
 # Authoring Docs
@@ -116,7 +116,7 @@ Load only the references needed for the current task:
 - `references/categories.md`: API, CLI, app, service, library, framework,
   monorepo, architecture, operations, and audience-specific guidance.
 - `references/writing-style.md`: plain technical writing and Markdown rules.
-- `references/templates.md`: reusable page and handoff templates.
+- `references/templates.md`: reusable page and handoff templates, linking canonical copyable Markdown under `references/page-templates/`. Fresh approved preset init consumes those same bodies; local templates remain preferred.
 - `references/review-rubric.md`: readiness checklist and review rubric.
 
 ## Examples

package/assets/skills/authoring-docs/references/information-architecture.md

@@ -123,8 +123,11 @@ use filename/slug parity for paired features and reciprocal links. A Product
 feature must link to its QA validation and Engineering counterpart (and back).
 Quote exact UI literals only when verified against source; distinguish a user
 concept from literal screen text. Do not fabricate test IDs or independent
-verification needs. Feature and QA validation page templates are not included here;
-use the page-type guidance and IA Proposal template to plan their content.
+verification needs. Use the [Product feature](page-templates/product-feature.md),
+[Engineering feature](page-templates/engineering-feature.md) and
+[QA validation](page-templates/qa-validation.md) templates alongside the page-type
+guidance and IA Proposal template. A shared screen spec is conditional on several
+journeys using the same screen; do not manufacture one per feature.
 
 ## Navigation Principles
 

package/assets/skills/authoring-docs/references/page-templates/alert-runbook.md

@@ -0,0 +1,63 @@
+---
+title: Alert runbook
+description: Triage, recovery and verification for a specific operational alert.
+---
+
+# Alert runbook
+
+## When to use and entry criteria
+
+Name the alert/symptoms and checks that establish this runbook applies.
+
+## Production context
+
+Identify environment, affected components, customer impact and access prerequisites.
+
+## Ownership
+
+Name the responding role, escalation route and owner-review gaps.
+
+## First-five-minutes triage
+
+| Signal             | Check             | Interpretation             | Next action                   |
+| ------------------ | ----------------- | -------------------------- | ----------------------------- |
+| <observed symptom> | <read-only check> | <supported interpretation> | <numbered step or escalation> |
+
+## Procedure
+
+1. Establish scope with a read-only check.
+   **Verify:** state the expected observation and stop/escalate condition.
+2. Perform the reviewed recovery action.
+   **Verify:** state the successful observation and failure response.
+
+Warn immediately before any destructive command, state its scope and require the
+reviewed dry run first. Do not invent runnable production commands or dry-run flags.
+
+## Why this approach
+
+Explain the evidence and tradeoffs behind the recovery sequence.
+
+## Rollback
+
+Describe the inverse action, recovery prerequisites and verification, or state why
+rollback is unavailable and give the escalation route.
+
+## Verification checklist
+
+- Confirm service health and the original alert condition.
+- Confirm customer-visible recovery and absence of new side effects.
+- Record dated evidence and unresolved owner-reviewed 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/page-templates/command-reference.md

@@ -0,0 +1,55 @@
+---
+title: Command reference
+description: Verified command inputs, outputs and mutation boundaries.
+---
+
+# Command reference
+
+Source: <source location for the command registration and handler, or unknown>
+
+## Production impact
+
+State affected environments, access and operational risks; say unknown when unknown.
+
+## Command group index
+
+| Command               | Purpose       | Mutates                    |
+| --------------------- | ------------- | -------------------------- |
+| <verified invocation> | <reader goal> | <yes/no/unknown and scope> |
+
+## Shared flags
+
+List verified spelling, defaults, accepted values and applicability.
+
+## Per-command arguments
+
+For each command, describe positional arguments, flags, required combinations,
+validation and defaults. State unknown rather than inferring behavior from a name.
+
+## Outputs and JSON
+
+Describe human output and the verified --json schema where supported; otherwise
+state unsupported or unknown. Show examples only when verified from source or a run.
+
+## Exit codes
+
+List known categorical outcomes and their codes, including partial results.
+
+## Side effects
+
+Name file, config, service and remote mutations, overwrite behavior and dry-run
+support. Mark unverified effects unknown and identify the reviewing owner.
+
+## 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/decisions-pointer.md

@@ -0,0 +1,44 @@
+---
+title: Decisions pointer
+description: A curated guide to consequential decisions, not a ledger or an ADR.
+---
+
+# Decisions pointer
+
+## Where records live
+
+Link the repository's authoritative decision store. This page is not a ledger and
+is not an ADR; it routes readers to records without copying their full content.
+
+## How records are created
+
+Describe the existing repository process and required review. Do not initialize a
+new decision system or imply adoption because this template was scaffolded.
+
+## Selected decisions
+
+Curate 3–8 real records relevant to this audience, each with a one-line consequence.
+Remove the drafting row and do not fabricate records to fill a quota.
+
+| Record             | Consequence                          | Staleness flag                    |
+| ------------------ | ------------------------------------ | --------------------------------- |
+| <real record link> | <current effect on reader decisions> | <current/superseded/needs review> |
+
+## Staleness and review
+
+Identify superseded guidance, last verification and owner-review gaps. Keep the
+canonical record authoritative when this pointer becomes stale.
+
+## 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/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.