@open-agent-toolkit/cli 0.2.20 → 0.2.22

package/assets/docs/workflows/projects/artifacts.md

@@ -58,7 +58,7 @@ failure outcomes and successful intermediates, rejects an existing dated
 destination, and requires the selected path to stay under the project's
 `explainers/` directory with a `project-recap` manifest. Verification covers
 the exact retained bytes for the privacy-safe request, content approval, fact
-base JSON and Markdown, declared author results, authored Markdown, resolved
+base JSON and Markdown, declared author results, authored content, resolved
 theme, and every built artifact. Canonical fact-base and theme hashes remain
 normalized-object identities; `manifest.immutableHashes` independently covers
 serialized file bytes. Missing, stale, or tampered coverage fails before the

package/assets/docs/workflows/skills/explainer-kit.md

@@ -20,14 +20,21 @@ OAT lifecycle callers use the adapter.
 
 ## Recipes
 
-The core ships four versioned recipes:
-
-| Recipe              | Use                                                    | Required narrative                                                                                                    |
-| ------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
-| `project-explainer` | Working explanation after project planning             | planned architecture, decisions, risks, phases, and validation approach                                               |
-| `project-recap`     | Final record after implementation and final review     | original request, key agent decisions, as-built architecture, implementation record, validation evidence, and outcome |
-| `program-recap`     | Bird's-eye record of a multi-wave delivery program     | program overview, wave map and outcomes, convention evolution, aggregate numbers, and follow-up ledger                |
-| `engineer-tour`     | Engineer-facing orientation to a codebase and its flow | orientation, architecture, execution flow, key code, and validation                                                   |
+The core ships four versioned recipes on the `explainer-kit.recipe/v2` file
+schema. Each recipe's own `version` selector remains `"1"`, so `{id, version}`
+callers and manifest cross-checks are unaffected by the schema move.
+
+A v2 recipe declares a **floor** — the artifacts every run must produce — plus
+a licensed **expansion** set, instead of one exact artifact list. The floor is
+identical to the artifact set each recipe produced before, so no published URL
+changes:
+
+| Recipe              | Use                                                    | Floor artifact                | Required narrative                                                                                                    |
+| ------------------- | ------------------------------------------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `project-explainer` | Working explanation after project planning             | one Markdown `hub`            | planned architecture, decisions, risks, phases, and validation approach                                               |
+| `project-recap`     | Final record after implementation and final review     | one Markdown `hub`            | original request, key agent decisions, as-built architecture, implementation record, validation evidence, and outcome |
+| `program-recap`     | Bird's-eye record of a multi-wave delivery program     | one Markdown `hub`            | program overview, wave map and outcomes, convention evolution, aggregate numbers, and follow-up ledger                |
+| `engineer-tour`     | Engineer-facing orientation to a codebase and its flow | one HTML-composed `explainer` | orientation, architecture, execution flow, key code, and validation                                                   |
 
 The OAT project lifecycle owns `project-explainer` and `project-recap`. Both
 bind one project source set. The adapter binds `plan.md`, `design.md`, and
@@ -36,25 +43,183 @@ bind one project source set. The adapter binds `plan.md`, `design.md`, and
 set for `program-recap`; direct core callers can use `engineer-tour` without
 adding an OAT dependency.
 
+### Expansion profiles
+
+Each recipe declares the expansion it licenses as a list of profiles. A profile
+fixes everything the pipeline needs to build a follow-up author request —
+artifact `type`, authoring path, brief, optional shell, and a mandatory
+`maxCount`. Every recipe also carries a mandatory `expansion.limits.maxArtifacts`
+that caps the whole expansion set; floor artifacts do not count against it.
+
+| Recipe              | Profiles (max per profile)                                  | `maxArtifacts` |
+| ------------------- | ----------------------------------------------------------- | -------------- |
+| `project-recap`     | `supporting-diagram` 4, `deep-dive` 3, `walkthrough-deck` 1 | 6              |
+| `program-recap`     | `supporting-diagram` 3, `project-page` 12                   | 12             |
+| `project-explainer` | `supporting-diagram` 4                                      | 4              |
+| `engineer-tour`     | `supporting-diagram` 4                                      | 4              |
+
+`supporting-diagram` produces an HTML-composed `diagram` on the diagram shell,
+`walkthrough-deck` an HTML-composed `deck` on the deck shell, and `deep-dive`
+and `project-page` Markdown `explainer` pages. Every declared type stays inside
+the frozen `manifest/v1` enum — narrative sub-pages use `explainer` rather than
+introducing a new type.
+
 ## Content authoring and review
 
-Every unattended run requires one provider-neutral author. The core invokes
-the author once per recipe artifact with the exact narrative outline,
-reconciled fact base, and bounded-discovery context. It accepts only a
-schema-valid result with the required section IDs, substantive prose, and
-non-secret provenance. Each section is checked independently for excessive
-verbatim overlap with the fact base so one copied section cannot be hidden by
-otherwise original prose.
+### Two authoring paths
+
+Each artifact is authored on exactly one of two paths, and the **recipe**
+chooses which — the author never does:
+
+- **Narrative path** (`authoring: markdown`). The author writes Markdown. The
+  core parses it to a validated AST and renders it deterministically through a
+  themed block library: headings with anchors, GFM tables, lists including task
+  lists, strikethrough, GFM alert callouts (`> [!NOTE]`, `> [!TIP]`,
+  `> [!IMPORTANT]`, `> [!WARNING]`, `> [!CAUTION]`), fenced ` ```timeline `
+  blocks, code blocks, and figures. Fenced ` ```diagram ` blocks are rendered to
+  inline SVG at build time with no client-side script. Raw HTML passthrough and
+  links that violate the publish contract are hard errors; style findings are
+  warnings.
+- **Artistic path** (`authoring: html`). The author composes a complete HTML
+  document, starting from a curated shell delivered inside the request. The core
+  validates the result at the DOM level rather than re-rendering it. Non-script
+  markup is free within the allowlist, so decks, standalone diagrams, and tours
+  keep full visual latitude.
+
+Script safety on the artistic path is enforced by hash pinning rather than a
+blanket ban, because the bundled shells legitimately contain scripts. The
+validator derives an ordered multiset of script hashes from the declared core
+shell and requires the authored document's scripts to match it exactly — same
+hashes, same count, same order, compared over exact bytes. Missing, added,
+duplicated, reordered, replaced, or mutated scripts all hard-fail, as do inline
+event-handler attributes and external active content.
+
+### Briefs carry the editorial bar
+
+Quality expectations live in versioned prose briefs shipped with the core under
+`briefs/`, not in the content schema. There is one brief per floor entry and one
+per expansion profile. A brief states audience, voice, per-section intent, the
+artifact's depth floors (for example "at least one high-level architecture
+diagram"), and the expansion license. The core inlines the brief into every
+author request, so an unattended author receives everything it needs in one
+payload. Changing a brief changes output expectations with no contract
+migration.
+
+### The author seam
+
+Every run requires one provider-neutral author callback, in **both** modes —
+there is no synthetic content model to fall back on. A run without one fails
+with `E_AUTHOR_REQUIRED`.
 
 In-process core callers supply `options.author`; core CLI callers use
 `--author-module`. The OAT adapter accepts either an in-process `author` or an
-`authorModulePath` and rejects zero or two seams for unattended runs before it
-invokes the core. Callback and module paths are transient. Validated results
-are retained under `source/author/` and covered by the run's immutable hashes.
-
-Interactive runs may omit an author. They pause after writing
-`source/content/*.md`, require an explicit content-review decision, and resume
-the same run only after approval. Content approval never authorizes publishing.
+`authorModulePath`, and rejects zero or two seams before it invokes the core.
+Callback and module paths are transient and never persisted in the run request.
+Validated results are retained under `source/author/` and authored content under
+`source/content/<artifact>.md` or `.html`; both are covered by the run's
+immutable hashes.
+
+The core invokes the author once per artifact with an
+`explainer-kit.author-request/v2` payload carrying the artifact identity and
+type, its authoring path, the inlined brief, the reconciled fact base, the
+resolved theme, the shell source for artistic artifacts, and — for narrative
+floor artifacts — the required narrative section IDs. It accepts only a
+schema-valid `explainer-kit.author-result/v2` containing exactly one of
+`content.markdown` or `content.html` plus non-secret provenance. Authored
+content is still checked for excessive verbatim overlap with the fact base.
+
+### Content-driven expansion
+
+An author that judges the material to warrant more than the floor may return
+`proposedArtifacts` on the floor result, where each entry is only
+`{id, profileId, rationale}`. Proposals deliberately cannot carry an authoring
+path, brief, or shell — those are read from the referenced profile, so policy
+stays recipe-owned.
+
+The pipeline validates each proposal, enforces the per-profile and recipe-level
+caps, then issues one author request per accepted proposal. The two outcomes are
+distinct on purpose:
+
+- A **malformed** proposal — unknown `profileId`, unsafe or duplicate `id`, or a
+  collision with a floor artifact ID — is a hard error, because it signals a
+  broken author rather than thin content.
+- An **over-limit** proposal is rejected with a stable warning and the run
+  continues.
+
+Accepted expansion artifacts render to ID-bearing paths
+(`site/{directory}/{slug}/{artifactId}/index.html`) and are linked from the floor
+hub, while floor artifacts keep their existing paths unchanged.
+
+### Approval and marking
+
+The interactive approval gate sits **after** theme, render, safety validation,
+the guideline checker, and render QA — immediately before publish and
+durability. Rendering is local and non-destructive, and nothing leaves the
+machine before approval, so the reviewer now approves the rendered artifacts and
+the complete warning set instead of raw prose.
+
+An interactive run therefore stops with an `incomplete` outcome once the
+artifacts are built and checked. Review the rendered `site/` tree, the sources
+under `source/content/`, and the accumulated warnings, then supply an explicit
+JSON decision and rerun the same request. A rejection persists its correction
+list; after the sources are edited, approving resumes the same run, which
+re-renders and re-runs QA against the edited sources before approval is
+processed rather than publishing the stale render.
+
+Unattended runs — including recaps triggered by automated project completion —
+flow through end-to-end and auto-approve. The approval record distinguishes the
+two honestly: `explainer-kit.content-approval/v2` carries
+`marking: human-approved` for an interactive approval and `auto-drafted` for an
+unattended run, and the marking is surfaced in the core and adapter run results.
+It is deliberately **not** written to the manifest, which stays frozen on
+`manifest/v1`.
+
+The approval record is also the durable source of truth for the resolved
+artifact set. It records every floor and accepted expansion artifact for all
+approval states, including pending and rejected, so a paused expanded run
+rehydrates with stable artifact IDs, paths, hub links, and hashes without
+re-invoking the author.
+
+Content approval never authorizes publishing.
+
+## Warnings and QA severity
+
+QA findings are split by severity, and the split is what lets thin content ship
+visibly instead of failing a run. Safety and provenance violations — unsafe DOM
+or AST content, external assets, link-form violations, unresolved tokens,
+denylisted strings, tag imbalance, cohesion breaks, and source dumping — still
+throw `E_QA` and fail the run. Editorial and layout findings append stable
+warning identifiers to the manifest's `warnings[]` array and let the run
+succeed in both modes.
+
+| Warning ID                               | Meaning                                                         |
+| ---------------------------------------- | --------------------------------------------------------------- |
+| `guideline-narrative-coverage-missing`   | A required narrative section is not covered by the artifact     |
+| `guideline-architecture-diagram-missing` | No architecture diagram, inline or standalone, was produced     |
+| `guideline-structured-depth-missing`     | The artifact lacks the structured blocks its floor expects      |
+| `expansion-profile-limit-exceeded`       | A proposal was rejected against its profile's `maxCount`        |
+| `expansion-artifact-limit-exceeded`      | A proposal was rejected against `expansion.limits.maxArtifacts` |
+| `render-qa-document-overflow`            | The document overflows the viewport at a probed width           |
+| `render-qa-inner-container-overflow`     | An inner container overflows horizontally                       |
+| `render-qa-viewport-clipping`            | Content is clipped and unreachable                              |
+| `render-qa-heading-unreadable`           | A heading fails the readability probe                           |
+| `render-qa-animations-enabled`           | Animation remained active where it should be suppressed         |
+| `render-qa-reduced-motion`               | The reduced-motion preference was not honored                   |
+| `render-qa-keyboard-navigation`          | Keyboard navigation did not reach expected targets              |
+| `render-qa-theme-toggle`                 | The theme toggle did not behave as expected                     |
+| `render-qa-deck-no-js-layout`            | A deck degrades incorrectly without JavaScript                  |
+| `render-qa-deck-print-layout`            | A deck degrades incorrectly in print layout                     |
+| `render-qa-skipped-no-probe`             | Render QA was skipped because no browser probe was supplied     |
+
+Render QA is opt-in. When a caller supplies a browser probe, the stage serves
+the built site directory, loads each artifact with animations disabled, and runs
+the layout-probe battery at representative widths. Viewport clipping
+deliberately exempts content inside a horizontally scrollable ancestor, so
+intentionally paged deck slides are not reported as clipped while genuinely
+unreachable content still is. The core never launches a browser on its own:
+without an injected probe the stage records the single
+`render-qa-skipped-no-probe` warning and the run continues rather than failing
+closed.
 
 ## Curated styles and themes
 
@@ -87,7 +252,7 @@ intermediates and recovery information.
 
 `manifest.immutableHashes` covers the exact retained bytes for
 `run-request.json`, content approval, fact-base JSON and Markdown, declared
-author results, authored Markdown, the resolved theme, and every built
+author results, authored content, the resolved theme, and every built
 artifact. Canonical fact-base and theme hashes identify normalized objects;
 they are intentionally distinct from serialized file-byte hashes. The mutable
 manifest and build record are excluded from their own durability evidence and

package/assets/docs/workflows/skills/index.md

@@ -11,7 +11,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
 
 - [Writing Skills](../../contributing/skills.md) - Contributor guide to skill authoring, contracts, and governance.
 - [Docs Workflows](../../docs-tooling/workflows.md) - How docs CLI helpers and docs skills work together.
-- [Explainer Kit](explainer-kit.md) - Core and OAT adapter usage, recipes, themes, lifecycle policy, durability, and publishing.
+- [Explainer Kit](explainer-kit.md) - Core and OAT adapter usage, recipes and expansion profiles, the two authoring paths, warnings and QA severity, themes, lifecycle policy, durability, and publishing.
 - [Repo Improve](repo-improve.md) - Source modes, external-plan boundaries, optional tracking, and OAT import handoff.
 
 ## Key Skills by Use Case

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.20",
-  "docs-config": "0.2.20",
-  "docs-theme": "0.2.20",
-  "docs-transforms": "0.2.20"
+  "cli": "0.2.22",
+  "docs-config": "0.2.22",
+  "docs-theme": "0.2.22",
+  "docs-transforms": "0.2.22"
 }

package/assets/skills/explainer-kit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: explainer-kit
-version: 1.0.2
+version: 2.0.1
 description: Use when building destination-neutral visual explainer artifacts from explicit, versioned inputs.
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Agent, mcp__*
@@ -16,7 +16,11 @@ user, vault, or destination configuration.
 - Validate versioned run, source, theme, artifact, durability, and publishing
   contracts.
 - Reconcile one cited fact base before producing narrative content.
+- Author every artifact against a bundled brief on one of two paths, and scale
+  the artifact set with the content through recipe-declared expansion profiles.
 - Render neutral, self-contained artifacts from bundled recipes and templates.
+- Report editorial and layout findings as manifest warnings while keeping
+  safety and provenance violations hard failures.
 - Record build outcomes and verify caller-supplied durability evidence.
 - Publish only through an explicitly requested, human-gated connector.
 
@@ -51,25 +55,63 @@ node scripts/run.mjs --request /path/to/request.json
 ```
 
 The core composes validation, fact-base processing, bounded recipe/content
-discovery, theme resolution, rendering, QA, and manifest/build-record
-persistence. It runs without OAT files or ambient configuration. Supplied fact
-bases receive only lightweight consistency/freshness checks. Federated inputs
-require a provider-neutral critic callback and invoke it exactly once.
-Optional claim `sections` tags route facts to matching recipe narrative
-sections; untagged claims remain shared context for every required section.
-
-Unattended calls use explicit, already-approved source artifacts and require a
-provider-neutral author callback once per recipe artifact. In-process callers
-supply `options.author`; JSON-only CLI callers supply `--author-module`. The
-core validates exact narrative sections and non-secret author provenance,
-rejects excessive verbatim source overlap, retains each validated result under
-`source/author/`, persists review provenance in
-`source/content-approval.json`, and never prompts. Keep executable callback
-references out of the persisted run request.
-
-Interactive runs stop with an `incomplete` outcome after writing
-`source/content/*.md`. Review and correct that Markdown, then provide an
-explicit JSON decision and rerun the same request:
+discovery, authoring, theme resolution, rendering, QA, approval, and
+manifest/build-record persistence. It runs without OAT files or ambient
+configuration. Supplied fact bases receive only lightweight
+consistency/freshness checks. Federated inputs require a provider-neutral
+critic callback and invoke it exactly once. Optional claim `sections` tags
+route facts to matching recipe narrative sections; untagged claims remain
+shared context for every required section.
+
+## Authoring
+
+Every run requires a provider-neutral author callback in **both** modes; there
+is no synthetic content model. A run without one fails `E_AUTHOR_REQUIRED`.
+In-process callers supply `options.author`; JSON-only CLI callers supply
+`--author-module`. Keep executable callback references out of the persisted run
+request.
+
+The recipe — never the author — selects each artifact's authoring path. Floor
+entries and expansion profiles declare `authoring: markdown` for the narrative
+path or `authoring: html` for the artistic path. The core invokes the author
+once per artifact with an `explainer-kit.author-request/v2` payload carrying the
+artifact identity and type, its authoring path, the inlined brief from
+`briefs/`, the reconciled fact base, the resolved theme, the shell source for
+artistic artifacts, and the required narrative sections for narrative floor
+artifacts. It accepts only a schema-valid
+`explainer-kit.author-result/v2` with exactly one of `content.markdown` or
+`content.html` plus non-secret provenance, rejects excessive verbatim source
+overlap, retains each validated result under `source/author/` and its content
+under `source/content/<artifact>.md` or `.html`, and never prompts.
+
+Markdown content is parsed to a validated AST and rendered through the themed
+block library, including GFM tables and task lists, GFM alert callouts, fenced
+`timeline` blocks, and fenced `diagram` blocks rendered to inline SVG at build
+time. HTML content is validated at the DOM level: the authored document's
+scripts must match the declared core shell's ordered multiset of script hashes
+exactly, and inline event handlers and external active content are rejected.
+Non-script markup stays free within the allowlist.
+
+A floor artifact may return `proposedArtifacts` of `{id, profileId, rationale}`
+to grow the set when the content earns it. The referenced profile supplies the
+type, authoring path, brief, and shell, so the author never chooses policy.
+Unknown profiles and unsafe, duplicate, or floor-colliding IDs are hard errors;
+proposals over a profile's `maxCount` or the recipe's
+`expansion.limits.maxArtifacts` are rejected with a warning and the run
+continues. Accepted expansion artifacts render to
+`site/{directory}/{slug}/{artifactId}/index.html` and are linked from the floor
+hub; floor artifacts keep their existing paths.
+
+## Review, Approval, and Warnings
+
+Approval runs after theme, render, safety validation, the guideline checker, and
+render QA, immediately before publish and durability — so a reviewer approves
+rendered artifacts and the complete warning set, not raw prose.
+
+Interactive runs stop with an `incomplete` outcome once artifacts are built and
+checked. Review the rendered `site/` tree, the sources under `source/content/`,
+and the accumulated warnings, then provide an explicit JSON decision and rerun
+the same request:
 
 ```bash
 node scripts/run.mjs \
@@ -77,11 +119,31 @@ node scripts/run.mjs \
   --reviewed-source /path/to/content-review.json
 ```
 
-An approval decision resumes the existing run at theme/render; a rejection
-persists its correction list and leaves downstream stages pending. Approval
-does not authorize publishing: a publish request still requires the separate
-human-gated publisher callback. See `references/contracts.md` for source
-formats, callback modules, retained intermediates, and result semantics.
+An approval decision resumes the existing run; a rejection persists its
+correction list, and a later approval re-renders and re-runs QA against the
+edited sources before proceeding. Approval does not authorize publishing: a
+publish request still requires the separate human-gated publisher callback.
+
+Review provenance persists in `source/content-approval.json` as an
+`explainer-kit.content-approval/v2` record. It carries
+`marking: human-approved` for interactive approval and `auto-drafted` for
+unattended runs, surfaced in the run result and never written to the manifest,
+plus the complete resolved artifact set so a paused expanded run rehydrates
+without re-invoking the author.
+
+Safety and provenance violations fail the run with `E_QA`. Editorial and layout
+findings — narrative-coverage, architecture-diagram, and structured-depth
+guideline misses, rejected over-limit proposals, and render-QA layout findings —
+append stable warning IDs to the manifest's `warnings[]` and let the run
+succeed.
+
+Render QA is opt-in. It runs only against an injected `browserProbe`, and the
+core never launches a browser of its own — reviewing the rendered output in a
+browser is the generating agent's job. Without a probe the stage records
+`render-qa-skipped-no-probe` and the run continues.
+
+See `references/contracts.md` for source formats, callback modules, retained
+intermediates, and result semantics.
 
 Durability and publishing run only when the request selects them and the caller
 supplies the matching callback. The core does not create commits, discover

package/assets/skills/explainer-kit/briefs/deep-dive.md

@@ -0,0 +1,35 @@
+# Deep-dive author brief
+
+## Audience
+
+Write for a technical reader who already understands the parent project recap
+and needs enough detail to evaluate or work on one subsystem.
+
+## Voice
+
+Be precise without becoming encyclopedic. Start with the question this page
+answers and the boundary it covers. Use evidence tables, code or data examples,
+and diagrams where they reduce explanation time. Define assumptions and call
+out unresolved behavior.
+
+## Section intent
+
+Structure the page around:
+
+1. the subsystem's purpose and boundary;
+2. its inputs, outputs, and dependencies;
+3. the important execution or data flow;
+4. the decisions and trade-offs that shaped it;
+5. failure modes, operational concerns, and validation evidence.
+
+## Floor
+
+Produce a self-contained Markdown explainer that adds information not already
+present in the parent hub. Include at least one structured evidence block and
+link claims back to durable sources when available.
+
+## Expansion license
+
+Depth is licensed, repetition is not. Add inline diagrams, examples, tables,
+and callouts when they make a difficult mechanism easier to verify. Keep
+adjacent topics in the parent hub or a separate justified artifact.

package/assets/skills/explainer-kit/briefs/engineer-tour.md

@@ -0,0 +1,45 @@
+# Engineer tour author brief
+
+## Audience
+
+Write for an engineer entering an unfamiliar codebase who needs a reliable
+mental model before making a change.
+
+## Voice
+
+Teach through concrete paths and execution flows. Use exact symbols and file
+references when supported by the fact base, but explain why each location
+matters. Distinguish architecture from incidental folder structure. Keep the
+tour navigable rather than exhaustive.
+
+## Narrative intent
+
+- **Orientation:** Explain the product purpose, runtime shape, and where a new
+  engineer should begin.
+- **Architecture:** Show the major components and dependency direction.
+- **Execution flow:** Walk one representative request, command, or event from
+  entry point to observable result.
+- **Key code:** Highlight the small set of files, modules, and extension seams
+  that carry the design.
+- **Validation:** Explain how to run the relevant checks and how failures
+  surface.
+
+## Floor
+
+Compose one complete HTML engineer tour from the supplied `engineer-tour`
+shell. Cover all five sections, include a high-level architecture view, and
+provide enough concrete navigation that a reader can locate the described
+code. Keep all required shell anchors, theme tokens, and core scripts intact.
+
+## Shell-composition license
+
+The shell is a safe starting canvas, not a slot-filling ceiling. You may
+recompose and enrich non-script markup, layout, diagrams, and navigation when
+the codebase warrants it. Preserve the supplied core scripts exactly and do
+not add scripts, event-handler attributes, or external active content.
+
+## Expansion license
+
+Propose a supporting diagram when a subsystem or execution path needs a
+dedicated visual. The diagram must answer a specific onboarding question that
+the main tour cannot answer cleanly.

package/assets/skills/explainer-kit/briefs/program-recap.md

@@ -0,0 +1,41 @@
+# Program recap author brief
+
+## Audience
+
+Write for program sponsors, project leads, and teammates who need the whole
+program at a glance before following a specific project.
+
+## Voice
+
+Use plain language, active voice, and consistent program vocabulary. Lead with
+the aggregate story, then support it with concrete project evidence. Prefer
+maps, tables, and short lists to dense status prose. Distinguish confirmed
+outcomes from forecasts and unresolved follow-up.
+
+## Narrative intent
+
+- **Program overview:** Explain the shared objective, scope, current state, and
+  definition of done.
+- **Wave map:** Show the ordering and dependency structure across waves.
+- **Per-wave outcomes:** Summarize what each wave delivered, deferred, or
+  learned. Keep statuses comparable.
+- **Convention evolution:** Record standards or working agreements that changed
+  as the program progressed and why.
+- **Aggregate numbers:** Present totals and trends in an evidence table with
+  clear units and source context.
+- **Follow-up ledger:** List remaining work with owner or owning group, status,
+  dependency, and next action when known.
+
+## Floor
+
+Produce one self-contained narrative hub covering all six sections. Include a
+program-level map or architecture diagram and at least one table that makes
+cross-project comparison easy.
+
+## Expansion license
+
+Propose a project page when a project's evidence, decisions, or remaining work
+cannot be summarized accurately in the hub. Propose a supporting diagram when
+the program's wave or dependency structure needs a dedicated visual. Every
+project page must add project-specific substance and link cleanly back to the
+program story.

package/assets/skills/explainer-kit/briefs/project-explainer.md

@@ -0,0 +1,38 @@
+# Project explainer author brief
+
+## Audience
+
+Write for reviewers, implementers, and stakeholders who need to understand a
+planned project before or during delivery.
+
+## Voice
+
+Be concrete and decision-oriented. Explain technical terms in place. Separate
+settled choices from assumptions and open risks. Use tables for alternatives,
+phases, and verification coverage. Avoid repeating the same claim across
+sections.
+
+## Narrative intent
+
+- **Planned architecture:** Show the proposed components, boundaries, data
+  flow, and external dependencies. Include a high-level architecture diagram.
+- **Decisions:** Explain each load-bearing choice, its rationale, rejected
+  alternatives, and consequences.
+- **Risks:** State the failure mode, likelihood or trigger, impact, and
+  mitigation. Do not soften unknowns.
+- **Phases:** Describe the delivery sequence, dependencies, and observable
+  completion conditions.
+- **Validation approach:** Map important requirements and risks to specific
+  tests, checks, or review evidence.
+
+## Floor
+
+Produce one narrative hub covering all five sections. It must stand alone,
+contain at least one architecture diagram, and make phase and validation
+coverage scannable.
+
+## Expansion license
+
+Propose a supporting diagram when one subsystem, protocol, or execution flow
+needs more visual detail than the hub can carry. Add no expansion solely for
+decoration.

package/assets/skills/explainer-kit/briefs/project-page.md

@@ -0,0 +1,38 @@
+# Program project-page author brief
+
+## Audience
+
+Write for a program reader who followed a link from the program recap and now
+needs the evidence and decisions for one project.
+
+## Voice
+
+Keep program terminology and statuses consistent with the parent hub. Be
+specific about this project's scope, dependencies, and outcome. Avoid
+repeating program-wide context unless it changes how this project should be
+understood.
+
+## Section intent
+
+Cover:
+
+- the project's objective and place in the program;
+- delivered scope and current status;
+- architecture or dependency details unique to this project;
+- load-bearing decisions and their consequences;
+- validation evidence and known limits;
+- remaining work, owner or owning group, and next action.
+
+## Floor
+
+Produce a self-contained Markdown explainer with a clear route back to the
+program story. Include at least one structured table for delivery or
+validation evidence and enough source references for a reader to verify the
+status.
+
+## Expansion license
+
+Use inline diagrams, callouts, and evidence blocks when this project's
+substance warrants them. Stay within the single-project boundary. If a detail
+applies across the program, improve the parent recap instead of duplicating it
+here.