@open-agent-toolkit/cli 0.2.5 → 0.2.7

package/assets/docs/cli-utilities/configuration.md

@@ -100,6 +100,46 @@ oat config set tools.project-management true
 
 The `tools.*` keys are primarily maintained by `oat tools install`, `oat tools update`, and `oat tools remove`, but they are intentionally visible through `oat config` so workflows and operators can inspect or override pack-state signals when needed.
 
+### Explainer configuration
+
+The `oat-explainer-kit` adapter owns two typed config groups. Build and publish
+plumbing uses `explainers.*`; project lifecycle preferences use
+`workflow.explainers.*`.
+
+| Key                                    | Type                 | Stored scopes       | Default   |
+| -------------------------------------- | -------------------- | ------------------- | --------- |
+| `explainers.defaults.palette`          | non-empty string     | local, shared, user | `neutral` |
+| `explainers.defaults.visualProfile`    | non-empty string     | local, shared, user | `clean`   |
+| `explainers.defaults.themeBundlePath`  | path                 | local, shared       | unset     |
+| `explainers.publish.provider`          | `s3-static`          | shared              | unset     |
+| `explainers.publish.s3Uri`             | `s3://` URI          | shared              | unset     |
+| `explainers.publish.publicBaseUrl`     | HTTPS URL            | shared              | unset     |
+| `explainers.publish.awsRegion`         | non-empty string     | shared              | unset     |
+| `explainers.publish.awsProfile`        | non-empty string     | local, user         | unset     |
+| `workflow.explainers.projectExplainer` | `always\|ask\|never` | local, shared, user | `ask`     |
+| `workflow.explainers.projectRecap`     | `always\|ask\|never` | local, shared, user | `ask`     |
+
+Stored values resolve `local > shared > user > default` where the key permits
+each scope. Explicit runtime inputs take precedence for one invocation without
+mutating stored config. Use `oat config get <key> --json` to inspect both the
+resolved value and its source, and `oat config describe <key>` for its exact
+scope and type contract.
+
+Shared theme-bundle paths must be repository-relative. Local paths may be
+repository-relative or absolute; user config cannot set a theme-bundle path.
+A supplied bundle takes precedence over named palette and profile defaults and
+produces a warning.
+
+Publishing remains build-only when `explainers.publish.provider` is unset.
+When it is `s3-static`, `s3Uri`, `publicBaseUrl`, and `awsRegion` are all
+required. `awsProfile` is optional; when absent, the standard AWS credential
+chain applies. Config never starts publishing by itself: lifecycle callers must
+still select publish durability explicitly, and publishing remains
+human-gated. Raw AWS credentials are not config keys.
+
+See [Explainer Kit](../workflows/skills/explainer-kit.md) for recipes, artifact
+locations, lifecycle behavior, and durability.
+
 Workflow gate objects are structured config and use their own command group
 instead of the scalar `oat config set` surface. See
 [Workflow Gates](workflow-gates.md) for the full command surface and examples.

package/assets/docs/cli-utilities/tool-packs.md

@@ -45,6 +45,37 @@ present without the utility engine, it fails closed and reports the missing
 dependency instead of inventing a fallback route. Non-project analytical
 skills can use the utility engine directly.
 
+### Cross-pack explainer dependency
+
+The public explainer family also spans two packs:
+
+- `utility` owns `explainer-kit`, the destination-neutral core with its
+  contracts, recipes, themes, templates, render QA, durability verifier, and
+  optional publishing connector.
+- `workflows` owns `oat-explainer-kit`, the adapter that resolves OAT config,
+  project artifacts, output paths, and lifecycle intent.
+
+Install the core at user scope before using the adapter:
+
+```bash
+oat tools install utility --scope user
+oat tools install workflows
+```
+
+The dependency is one-way: the adapter invokes the core, while the core remains
+usable without OAT. The adapter checks the installed canonical core path and
+minimum compatible version before reading config or running. If the core is
+missing it fails closed with the utility install command; if it is too old it
+reports:
+
+```bash
+oat tools update --pack utility --scope user
+```
+
+It never falls back to a source checkout or copies core logic into the
+workflows pack. See [Explainer Kit](../workflows/skills/explainer-kit.md) for
+the usage and lifecycle contract.
+
 ## `oat tools` command group
 
 The `oat tools` command group provides a unified interface for managing installed tools (skills and agents) across scopes.

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

@@ -31,6 +31,33 @@ Mode-sensitive notes:
 - `references/imported-plan.md`: preserved source plan for import mode
 - `references/split-plan.json`: persisted split plan for a coordination parent, used as the durable resume source when `oat-project-split` is interrupted
 
+### Explainer artifacts
+
+[Explainer Kit](../skills/explainer-kit.md) writes project runs under
+`<resolved-project-path>/explainers/<slug>/`. The two project products have
+different retention contracts:
+
+- A `project-explainer` is a working artifact. In a shared project it can be
+  tracked while the project is active, but project completion removes it from
+  the tracked branch with the active project tree. It remains only in the local
+  archived project.
+- A selected final `project-recap` is a durable completion record. Before a
+  shared project is removed, archive copies the complete selected run to
+  `.oat/repo/reference/project-recaps/<YYYYMMDD-project-slug>/`, verifies its
+  manifest artifact hashes, and reports that tracked export path. Summary and
+  PR links use this export, never the gitignored local archive.
+
+The archive exports at most one selected recap package. It preserves structured
+failure outcomes and successful intermediates, rejects an existing dated
+destination, and fails before deleting the active project if copy or hash
+verification fails.
+
+Local-scope projects are not archived through this export path. Their explainer
+packages inherit the local project's untracked posture and remain
+`built-not-durable` unless independent publish evidence exists. Non-project OAT
+explainer runs use `.oat/repo/reference/explainers/<slug>/`; direct core callers
+must provide their own explicit output root.
+
 ### Gate review frontmatter
 
 Review artifacts produced by `oat gate review` use the normal review fields plus

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

@@ -0,0 +1,125 @@
+---
+title: Explainer Kit
+description: 'Build destination-neutral visual explainers directly or from OAT project lifecycle artifacts.'
+---
+
+# Explainer Kit
+
+The public explainer family separates a destination-neutral core from an
+OAT-aware adapter:
+
+- `explainer-kit` validates explicit versioned inputs, reconciles one cited fact
+  base, applies a recipe and theme, renders and checks the artifact set, and
+  records a manifest and build outcome.
+- `oat-explainer-kit` resolves OAT configuration, project intent, source
+  artifacts, and canonical output paths before invoking the same core.
+
+The core does not read OAT, user, vault, or destination configuration. Direct
+callers provide a complete `ExplainerRunRequestV1` and an explicit output root.
+OAT lifecycle callers use the adapter.
+
+## Recipes
+
+The v1 project recipes serve different lifecycle jobs:
+
+| Recipe              | Lifecycle 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 |
+
+Both recipes bind one project source set. The adapter binds `plan.md`,
+`design.md`, and `spec.md` for a project explainer; a project recap can also
+include `implementation.md` and `summary.md`.
+
+## Themes
+
+Every artifact set uses one resolved theme. The bundled defaults are the
+`neutral` palette and `clean` visual profile. The core also ships the `ocean`,
+`ember`, `forest`, and `violet` palettes plus `editorial` and `technical`
+profiles.
+
+A caller may select named palette/profile values, supply a validated theme
+bundle, or provide per-run art direction. A supplied bundle takes precedence
+over named selections. The resolved concrete bundle is retained with the run;
+raw art-direction text is not retained by default. Themes contain validated
+light and dark modes, while the render strategy chooses either the default mode
+or a user-switchable result.
+
+## Build, durability, and publish
+
+Missing publish configuration means build-only. A completed build writes the
+source package, resolved theme, `manifest.json`, `build-record.json`, and the
+rendered `site/` tree. Rendering or publishing failures preserve successful
+intermediates and recovery information.
+
+Build success and durability are separate:
+
+- `built-not-durable` means artifacts exist but verified commit or publish
+  evidence is absent.
+- `built-durable` requires verified evidence for every required
+  non-rebuildable artifact.
+- `failed` records a failed run without treating partial output as success.
+
+The core verifies caller-supplied commit or publish evidence; it never creates
+Git commits. Publishing is always explicitly requested and human-gated. The
+public `s3-static` connector validates corresponding S3 and HTTPS roots with a
+run-unique sentinel, uploads only manifest-declared `site/` files, verifies the
+content type and SHA-256 response bytes at public URLs, and writes
+`publish-receipt.json`. Public roots cannot contain credentials, queries, or
+fragments. Publishing is additive and does not run a root-wide destructive
+sync.
+
+Release validation drives the bounded palette/profile/template matrix in a real
+installed Chromium browser and retains machine-readable viewport, clipping,
+motion, keyboard, no-JavaScript, and print measurements. The gate fails closed
+when no supported browser executable is available.
+
+Frozen RC runs require both the identity record and the explicit retained
+tarball directory:
+
+```bash
+node tools/release/run-explainer-rc.mjs \
+  --rc-manifest .oat/repo/reference/explainer-kit-acceptance/v1/rc.json \
+  --artifacts-dir dist/explainer-kit-rc \
+  --entry scripts/run.mjs \
+  --record /path/to/sanitized-execution.json \
+  -- --request /path/to/request.json
+```
+
+The packaged CLI emits one complete JSON result document; pretty-printed
+multiline JSON is valid, while progress text and line-by-line guessing are not.
+The resulting execution record binds the canonical request and child-reported
+manifest to the core run ID without retaining private argument values.
+Wrapper-created receipt evidence is produced only after core execution and is
+validated separately against the immutable execution record and manifest.
+
+## OAT lifecycle policy
+
+Interactive project explainer and recap preferences resolve independently from
+`workflow.explainers.projectExplainer` and
+`workflow.explainers.projectRecap`. Each accepts `always`, `ask`, or `never`;
+the built-in default is `ask`. A resolved project decision in `state.md`
+outranks those preferences.
+
+Autonomous mode has stricter policy: it always attempts a project recap, while
+a project explainer runs only when the kickoff request explicitly asks for
+one. Lifecycle-triggered runs do not publish automatically, and recap failure
+does not block project completion.
+
+See [Project Artifacts](../projects/artifacts.md) for active and durable output
+locations, and [Configuration](../../cli-utilities/configuration.md) for the
+typed adapter settings.
+
+## Private wrappers
+
+Private integrations use the core boundary directly: resolve private inputs
+before the run, construct one versioned request, invoke the core once, then
+publish or link the versioned manifest after the run. Wrapper acceptance reads
+the complete post-run `PublishReceiptV1`, verifies every manifest artifact and
+the core run ID, and rejects foreign or stale receipts. Presets, private source
+systems, external-document synchronization, and personal destinations remain
+wrapper-owned.
+
+V1 exposes no plugin registry or private mid-pipeline hook. Unsupported
+contract majors and identity mismatches fail closed instead of being guessed
+or coerced.

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

@@ -11,6 +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.
 - [Repo Improve](repo-improve.md) - Source modes, external-plan boundaries, optional tracking, and OAT import handoff.
 
 ## Key Skills by Use Case
@@ -25,6 +26,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
 - Capture a scoped, shippable backlog item: `oat-pjm-add-backlog-item` directly when the work is already scoped, or `oat-brainstorm` when the thought hasn't converged yet — the brainstorm dispatcher's "scoped backlog item" destination pre-fills the title / description / acceptance criteria / scope estimate / priority from the conversation and then runs `oat-pjm-add-backlog-item` with confirmed inputs
 - Manage the repo backlog and reference docs: `oat-pjm-update-repo-reference`, `oat-pjm-review-backlog`
 - Turn a repo audit, maintainability review, backlog review, backlog directory, or backlog item into standalone external implementation plans: `oat-repo-improve`. Plans land under `.oat/repo/reference/external-plans/`; execute them directly or optionally pass one to `oat-project-import-plan` for tracked OAT execution.
+- Build visual project explainers and final project recaps: `oat-explainer-kit`, backed by the destination-neutral `explainer-kit` core. See [Explainer Kit](explainer-kit.md).
 - Work on docs surfaces: `authoring-docs` (general documentation baseline), `oat-docs-authoring` (targeted OAT/Fumadocs authoring), `oat-docs-bootstrap` (guided bootstrap of a new docs app), `oat-docs-analyze`, `oat-docs-apply`, and `oat-project-document`
 - Generate a shipping digest or scheduled recap: `oat-wrap-up`
 - Run a wave program over a corpus of external plans: `oat-wave-program` (durable program artifact: new/refresh/wave-close) and `oat-wave-execute` (one wave as a wrapper project) — see [Wave Workflows](../wave-workflows.md)
@@ -70,6 +72,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
     - `oat-project-pr-progress`
     - `oat-project-pr-final`
     - `oat-project-document`
+    - `oat-explainer-kit`
     - `oat-wrap-up`
     - `oat-project-complete`
     - `oat-wave-program`
@@ -120,6 +123,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
 
 === "Scaffolding and utility"
 
+    - `explainer-kit`
     - `oat-worktree-bootstrap`
     - `oat-worktree-bootstrap-auto`
     - `create-oat-skill`

package/assets/migration/pjm-restructure.md

@@ -22,6 +22,7 @@
 > when the installed CLI lacks the support; the JUDGMENT gates (STEP 4-6) always need you.
 >
 > **Non-negotiable safety rules — read before doing anything:**
+>
 > 1. **Dry-run first, always.** Produce the full plan and the two judgment proposals BEFORE
 >    any write. Do not write/move/delete until the user explicitly approves.
 > 2. **Idempotent.** If the repo is already in the new shape, report that and stop.
@@ -231,6 +232,7 @@ Decision / Consequences exactly as they appeared>
 ```
 
 Rules:
+
 - **Preserve the body byte-for-byte** (minus the heading line, which becomes `title`/the
   frontmatter). Do not summarize or reformat.
 - `legacy_id` keeps the original `ADR-NNN`/`DR-NNN` so inbound references still resolve.
@@ -270,6 +272,7 @@ proposals, operator-steps, profile-baselines, rollouts, wrap-ups, technical`, pl
 non-canonical `*.md` in the reference root.
 
 For each, infer a classification by skimming its contents:
+
 - **Project-scoped** (content is about one specific project/feature) → propose moving into
   that project's reference dir: `.oat/projects/<scope>/<project>/reference/`.
 - **Repo-wide / durable** → propose the canonical destination:
@@ -291,6 +294,7 @@ For each, infer a classification by skimming its contents:
 ```
 
 Rules:
+
 - Ambiguous/unknown → default to **"leave in place, flag"**, never guess.
 - After the user confirms, `git mv` each approved row. Skip rows the user rejects.
 - Optional canonical folders (`research/`, `brainstorms/`, `external-plans/`, `decks/`) are
@@ -389,6 +393,7 @@ optional folders are created on demand, not pre-created.
   be left, refreshed for the two-layer layout, or archived under `reference/archive/`.
 
 ## IDs
+
 - Decisions: `DR-YYMMDD-slug`. Backlog: `BL-YYMMDD-slug`. **ID == filename stem.** The `YYMMDD`
   prefix gives chronological + file-explorer ordering. Allocator-free (no scan, no counter):
   collision only on same-day + same-slug. Migrated records keep their original id in `legacy_id:`.
@@ -396,14 +401,17 @@ optional folders are created on demand, not pre-created.
   (`a, an, the, of, for, and, to, in, on, as, with`) trimmed, so choose concise, meaningful titles.
 
 ## Skill / content DESTINATIONS
+
 - `oat-brainstorm` → `reference/brainstorms/`
 - `oat project import-plan` → `reference/external-plans/` (already its target)
 - research / deep-research → `reference/research/`
 
 ## Generated indexes — regenerate on conflict
+
 `pjm/backlog/index.md` and `reference/decisions/index.md` are generated and COMMITTED (not
 gitignored, no merge driver). They render deterministically from the record files. On a merge
 conflict: run the regenerate command, then `git add`:
+
 - backlog: `oat backlog regenerate-index`
 - decisions: `oat decision regenerate-index`
 
@@ -470,6 +478,7 @@ test -f .oat/repo/README.md && echo "present: README.md (allowed by doctor; leav
 > (see STEP 4.5) — report it, don't flag it as broken.
 
 **Print the final migration report** covering:
+
 - files moved (old → new), backlog items re-id'd (old id → new id, any date fallback used),
 - decisions split (old ADR/DR → new `DR-YYMMDD-slug`, count parity),
 - ad-hoc folders reconciled (confirmed destinations),
@@ -497,4 +506,7 @@ test -f .oat/repo/README.md && echo "present: README.md (allowed by doctor; leav
 - Treat `.oat/projects/**` writes (project-scoped folder moves) as confirmed-only.
 - This prompt is safe to re-run: STEP 0's idempotency probe short-circuits an
   already-migrated repo.
+
+```
+
 ```

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.5",
-  "docs-config": "0.2.5",
-  "docs-theme": "0.2.5",
-  "docs-transforms": "0.2.5"
+  "cli": "0.2.7",
+  "docs-config": "0.2.7",
+  "docs-theme": "0.2.7",
+  "docs-transforms": "0.2.7"
 }

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

@@ -0,0 +1,95 @@
+---
+name: explainer-kit
+version: 1.0.0
+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__*
+---
+
+# Explainer Kit
+
+Build visual explainer artifact sets from explicit inputs without reading OAT,
+user, vault, or destination configuration.
+
+## Responsibilities
+
+- Validate versioned run, source, theme, artifact, durability, and publishing
+  contracts.
+- Reconcile one cited fact base before producing narrative content.
+- Render neutral, self-contained artifacts from bundled recipes and templates.
+- Record build outcomes and verify caller-supplied durability evidence.
+- Publish only through an explicitly requested, human-gated connector.
+
+## Dependency Direction
+
+This skill is the canonical core. It must not depend on `oat-explainer-kit` or
+OAT project state. Adapters and private wrappers may construct a core run
+request and consume its manifest, build record, and optional publish receipt.
+
+## Wrapper Extension Seam
+
+Wrappers own private pre-resolution and post-run work. They resolve presets,
+vaults, external documents, and personal destinations before translating the
+result into one `ExplainerRunRequestV1`; after the core run, they consume the
+versioned manifest and optional receipt to create links or companion records.
+They must not inject private work between core stages or expose private lanes as
+public config. See `references/extension-contract.md` for the frozen sequence,
+version policy, and compatibility fixture.
+
+## Asset Resolution
+
+Resolve schemas, recipes, templates, scripts, examples, and references relative
+to this installed skill directory. Never resolve runtime assets from a source
+checkout or from absolute operator-specific paths.
+
+## Core Run
+
+Construct a complete `ExplainerRunRequestV1`, then invoke the packaged core:
+
+```bash
+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.
+
+Unattended calls use explicit, already-approved source artifacts, persist their
+review provenance in `source/content-approval.json`, and never prompt.
+
+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:
+
+```bash
+node scripts/run.mjs \
+  --request /path/to/request.json \
+  --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.
+
+Durability and publishing run only when the request selects them and the caller
+supplies the matching callback. The core does not create commits, discover
+destinations, or publish automatically. A successful build remains
+`built-not-durable` until caller-supplied evidence is verified.
+
+## Progress Indicators
+
+For interactive runs, show a concise banner and stage updates:
+
+```text
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+EXPLAINER KIT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Report validation, fact-base, content, theme, render, QA, durability, and
+publish stages as they begin and complete. Keep unattended output structured
+and non-interactive.

package/assets/skills/explainer-kit/examples/project-explainer/content.md

@@ -0,0 +1,31 @@
+# Signal Relay project explainer
+
+## Planned architecture
+
+Signed events enter through a narrow HTTP boundary. The service validates each
+envelope before placing it on a durable queue; workers own downstream delivery
+and isolate exhausted retries in a review queue.
+
+## Decisions
+
+- Keep ingestion stateless so instances can scale independently.
+- Persist accepted events before acknowledging them.
+- Use bounded retries and a separate review queue instead of retrying forever.
+
+## Risks
+
+The primary risk is an incompatible producer envelope. Contract tests and a
+shadow-ingestion period detect that drift before cutover.
+
+## Phases
+
+1. Validate contracts against fixtures.
+2. Run shadow ingestion without downstream delivery.
+3. Enable canary delivery and compare outcomes.
+4. Move remaining traffic after recovery drills pass.
+
+## Validation approach
+
+The release gate combines contract tests, duplicate-delivery tests, queue
+recovery drills, and operator sign-off. Supporting evidence is linked from
+[the example validation plan](https://docs.example.com/signal-relay/validation).

package/assets/skills/explainer-kit/examples/project-explainer/fact-base.md

@@ -0,0 +1,22 @@
+# Example fact base: Signal Relay
+
+This fictional example demonstrates a pre-implementation project explainer. All
+organizations, systems, and links are illustrative.
+
+## Reconciled claims
+
+- **F-001 — Planned architecture:** The relay accepts signed events, validates
+  their envelopes, and writes accepted events to a durable queue.
+  Source: [architecture proposal](https://docs.example.com/signal-relay/architecture).
+- **F-002 — Delivery:** Workers retry transient delivery failures with bounded
+  backoff and move exhausted events to a review queue.
+  Source: [delivery design](https://docs.example.com/signal-relay/delivery).
+- **F-003 — Validation:** Contract, retry, and recovery tests must pass before
+  traffic can move from the existing path.
+  Source: [validation plan](https://docs.example.com/signal-relay/validation).
+
+## Reconciliation notes
+
+The proposal gives the queue ownership to the platform team while an older
+meeting note assigns it to the application team. The proposal is newer, so
+F-001 follows it and records the older assignment as superseded.

package/assets/skills/explainer-kit/examples/project-recap/content.md

@@ -0,0 +1,34 @@
+# Atlas Index project recap
+
+## Original request
+
+Replace the nightly full rebuild with incremental indexing without changing the
+public query contract.
+
+## Key agent decisions
+
+- Use partition-local checkpoints to bound replay.
+- Make index writes idempotent before enabling automatic retries.
+- Retain the full rebuild as a documented recovery path.
+
+## As-built architecture
+
+A change reader resumes from each partition checkpoint and hands batches to
+idempotent workers. A scheduled audit compares source and index samples and
+raises a recovery task when drift exceeds the accepted threshold.
+
+## Implementation record
+
+The team delivered checkpoint persistence, replay-safe workers, audit reporting,
+and the recovery runbook in three sequential milestones.
+
+## Validation evidence
+
+Contract tests, interrupted-restart tests, duplicate-batch tests, and sampled
+parity checks passed. See the fictional
+[evidence index](https://docs.example.com/atlas-index/evidence).
+
+## Outcome
+
+Incremental indexing is active. The nightly rebuild is no longer part of normal
+operation and remains documented for recovery only.

package/assets/skills/explainer-kit/examples/project-recap/fact-base.md

@@ -0,0 +1,22 @@
+# Example fact base: Atlas Index recap
+
+This fictional fact base demonstrates a completed-project recap.
+
+## Reconciled claims
+
+- **F-101 — Request:** Replace a nightly full rebuild with incremental indexing
+  while preserving the existing query contract.
+  Source: [approved request](https://docs.example.com/atlas-index/request).
+- **F-102 — As built:** A checkpointed change reader feeds idempotent index
+  workers; a scheduled audit detects drift.
+  Source: [as-built record](https://docs.example.com/atlas-index/as-built).
+- **F-103 — Validation:** Contract, restart, and sampled parity checks passed.
+  Source: [validation evidence](https://docs.example.com/atlas-index/evidence).
+- **F-104 — Outcome:** Incremental indexing is active and the nightly rebuild
+  remains available only as a recovery procedure.
+  Source: [outcome record](https://docs.example.com/atlas-index/outcome).
+
+## Reconciliation notes
+
+An early plan proposed one shared checkpoint. Implementation evidence records a
+checkpoint per partition, so F-102 treats the implementation as authoritative.

package/assets/skills/explainer-kit/examples/theme-bundle.json

@@ -0,0 +1,87 @@
+{
+  "schemaVersion": "explainer-kit.theme/v1",
+  "name": "neutral-clean",
+  "defaultMode": "light",
+  "modes": {
+    "light": {
+      "surface": {
+        "canvas": "#ffffff",
+        "panel": "#f3f4f6",
+        "elevated": "#e5e7eb"
+      },
+      "ink": { "primary": "#111827", "muted": "#4b5563", "inverse": "#ffffff" },
+      "accent": { "primary": "#374151", "secondary": "#4b5563" },
+      "status": {
+        "success": "#166534",
+        "warning": "#854d0e",
+        "danger": "#991b1b",
+        "info": "#1e40af"
+      },
+      "diagramSeries": ["#374151", "#1e40af", "#166534", "#854d0e"]
+    },
+    "dark": {
+      "surface": {
+        "canvas": "#111827",
+        "panel": "#1f2937",
+        "elevated": "#374151"
+      },
+      "ink": { "primary": "#f9fafb", "muted": "#d1d5db", "inverse": "#111827" },
+      "accent": { "primary": "#d1d5db", "secondary": "#e5e7eb" },
+      "status": {
+        "success": "#86efac",
+        "warning": "#fde047",
+        "danger": "#fca5a5",
+        "info": "#93c5fd"
+      },
+      "diagramSeries": ["#d1d5db", "#93c5fd", "#86efac", "#fde047"]
+    }
+  },
+  "provenance": {
+    "palette": "neutral",
+    "visualProfile": "clean",
+    "derived": false
+  },
+  "typography": {
+    "sans": ["system-ui", "-apple-system", "BlinkMacSystemFont", "sans-serif"],
+    "serif": ["ui-serif", "Georgia", "serif"],
+    "mono": ["ui-monospace", "SFMono-Regular", "Consolas", "monospace"],
+    "scale": {
+      "caption": "0.875rem",
+      "body": "1rem",
+      "title": "1.5rem",
+      "display": "2.25rem"
+    },
+    "lineHeight": { "caption": 1.4, "body": 1.6, "title": 1.25, "display": 1.1 }
+  },
+  "spacing": {
+    "unit": 4,
+    "scale": { "xs": 4, "sm": 8, "md": 16, "lg": 24, "xl": 40 }
+  },
+  "geometry": {
+    "radius": { "sm": 4, "md": 8, "lg": 12 },
+    "borderWidth": 1
+  },
+  "elevation": {
+    "shadows": {
+      "low": "0 1px 2px rgb(0 0 0 / 0.08)",
+      "high": "0 12px 28px rgb(0 0 0 / 0.16)"
+    }
+  },
+  "density": "comfortable",
+  "motion": {
+    "enabled": true,
+    "durationMs": { "fast": 120, "normal": 200, "slow": 320 },
+    "easing": {
+      "standard": "ease",
+      "emphasized": "cubic-bezier(0.2, 0, 0, 1)"
+    },
+    "reducedMotion": "disable-nonessential"
+  },
+  "diagrams": {
+    "lineWidth": 2,
+    "nodeGap": 32,
+    "arrowStyle": "straight",
+    "labelTreatment": "boxed"
+  },
+  "bundleHash": "sha256:7e7b935c2a6d1603fe4e9fb6bdd32859d3a8fc558db38a7b3289d78e8c1396b3"
+}