@open-agent-toolkit/cli 0.3.28 → 0.3.29

package/README.md

@@ -45,6 +45,8 @@ 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).

package/assets/bundle-metadata.json

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

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

@@ -60,9 +60,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 +156,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)

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.29",
+  "docs-config": "0.3.29",
+  "docs-theme": "0.3.29",
+  "docs-transforms": "0.3.29"
 }

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.

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.