@open-agent-toolkit/cli 0.2.19 → 0.2.21

package/assets/skills/explainer-kit/briefs/supporting-diagram.md

@@ -0,0 +1,28 @@
+# Supporting diagram author brief
+
+## Audience
+
+Create a visual for a reader who understands the parent explainer but needs one
+boundary, flow, dependency, or state transition made unmistakable.
+
+## Voice and visual intent
+
+Lead with the visual. Use short labels, consistent terminology, and a clear
+reading direction. Make the title state the question the diagram answers.
+Include a concise legend or annotation only when the visual vocabulary is not
+self-evident.
+
+## Floor
+
+Compose a complete, accessible HTML diagram from the supplied
+`diagram-shell`. Preserve its required anchors, theme tokens, and core scripts.
+The diagram must have an explicit title, meaningful labels, a visible primary
+flow, and a short text explanation that remains useful to screen-reader users.
+Do not encode essential meaning through color alone.
+
+## Expansion license
+
+Elaborate the shell's non-script markup and SVG freely when needed for
+legibility. Keep the scope to one coherent question. If the visual needs
+several unrelated panels or long prose to make sense, recommend a deep-dive
+instead.

package/assets/skills/explainer-kit/briefs/walkthrough-deck.md

@@ -0,0 +1,35 @@
+# Walkthrough deck author brief
+
+## Audience
+
+Build for a live or self-guided walkthrough with teammates who need the project
+story in a deliberate sequence rather than a reference document.
+
+## Voice and sequence
+
+Use one claim per slide and a clear narrative arc: context, change, system,
+evidence, outcome, next action. Keep text brief enough to scan at presentation
+distance. Use diagrams, comparisons, and evidence excerpts instead of
+shrinking prose to fit.
+
+## Floor
+
+Compose a complete HTML deck from the supplied `deck-shell`. Preserve required
+anchors, theme tokens, keyboard navigation, progress behavior, print behavior,
+and all core scripts exactly. Include:
+
+- an opening frame that states the project and reader promise;
+- a before/after or request/outcome frame;
+- a high-level architecture or execution-flow visual;
+- a decision or trade-off frame;
+- a validation-evidence frame;
+- a closing frame with outcome and next actions.
+
+Every slide must have a useful heading, readable contrast, and a sensible
+no-JavaScript and print order.
+
+## Shell-composition license
+
+The shell supplies safety and presentation mechanics. You may recompose and
+extend non-script markup and styling to fit the story. Do not add scripts,
+external active content, or inline event handlers.

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

@@ -2,33 +2,76 @@
 
 ## Original request
 
-Replace the nightly full rebuild with incremental indexing without changing the
-public query contract.
+Every correction to the fictional Atlas Index corpus had to wait for the next
+overnight window, and the cost of that window grew with the corpus. The team was
+asked to make indexing continuous without asking a single caller to change how
+they query.
+
+> [!IMPORTANT]
+> The query contract was frozen for the whole engagement. Any option that would
+> have reshaped a response was out of scope before it was evaluated.
 
 ## 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.
+| Decision                     | Alternative weighed          | Why it won                                         |
+| ---------------------------- | ---------------------------- | -------------------------------------------------- |
+| Checkpoint each partition    | A single global checkpoint   | Replay after a crash stays inside one partition    |
+| Make writes idempotent first | Deduplicate in each consumer | Retry safety belongs to the writer, not the reader |
+| Keep the rebuild as recovery | Delete it after cutover      | A proven fallback costs almost nothing to retain   |
+
+Each row records what was chosen and what it was chosen over, so a later reader
+can reconstruct the reasoning rather than just the result.
 
 ## 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.
+```diagram
+graph TD
+  reader[Change reader] --> queue(Batch queue)
+  queue --> worker[Index worker]
+  worker --> index[Search index]
+  audit{Drift beyond threshold} -->|yes| recovery[Recovery task]
+  index --> audit
+```
+
+The reader resumes from whichever checkpoint its partition last committed, so a
+restart repeats at most one batch. Workers apply batches by key, which makes a
+repeated batch indistinguishable from a first delivery. The audit closes the
+loop by sampling both sides on a schedule and opening a recovery task only when
+the difference clears the accepted threshold.
 
 ## Implementation record
 
-The team delivered checkpoint persistence, replay-safe workers, audit reporting,
-and the recovery runbook in three sequential milestones.
+```timeline
+2026-02-03 — Checkpoint persistence landed behind a flag
+2026-02-17 — Replay-safe workers replaced the batch writer
+2026-03-02 — Drift audit and the recovery runbook shipped
+```
+
+- The first milestone changed only bookkeeping, so it could ship dark.
+- The second made retries safe, which is what unlocked automatic recovery.
+- The third added the observability the operators asked for before cutover.
 
 ## Validation evidence
 
-Contract tests, interrupted-restart tests, duplicate-batch tests, and sampled
-parity checks passed. See the fictional
+| Suite              | Scope                                       | Result    |
+| ------------------ | ------------------------------------------- | --------- |
+| Contract           | Query responses across the fixture corpus   | Unchanged |
+| Restart            | Interruption at every checkpoint boundary   | No gaps   |
+| Duplicate delivery | The same batch applied twice                | No drift  |
+| Parity sampling    | Scheduled samples against the source record | In budget |
+
+The full logs sit in the fictional
 [evidence index](https://docs.example.com/atlas-index/evidence).
 
+> [!NOTE]
+> How long audit samples should be retained is still an open governance
+> question, and it is tracked outside this recap.
+
 ## Outcome
 
-Incremental indexing is active. The nightly rebuild is no longer part of normal
-operation and remains documented for recovery only.
+Corrections now reach readers in minutes instead of waiting for a nightly
+window, and the operational surface got smaller rather than larger.
+
+1. Continuous indexing is the normal path.
+2. The rebuild remains documented, exercised, and unused.
+3. Drift is a monitored quantity rather than an assumption.

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

@@ -0,0 +1,104 @@
+{
+  "schemaVersion": "explainer-kit.fact-base/v1",
+  "generatedAt": "2026-03-09T18:00:00Z",
+  "mode": "supplied",
+  "freshnessPolicy": "live-wins",
+  "sources": [
+    {
+      "id": "atlas-index-project",
+      "kind": "file",
+      "locator": "https://docs.example.com/atlas-index/project-record",
+      "hash": "sha256:1f0c4d2b8a6e5937c41d0b7a2e8f36154c9d0ab7e25f8341d6c07b9ae4315f28",
+      "observedAt": "2026-03-09T18:00:00Z"
+    }
+  ],
+  "claims": [
+    {
+      "id": "F-101",
+      "text": "Nightly full rebuilds were replaced by incremental indexing with no change to the public query contract.",
+      "status": "confirmed",
+      "sections": ["original-request"],
+      "citations": [
+        {
+          "sourceId": "atlas-index-project",
+          "locator": "project-record#request"
+        }
+      ]
+    },
+    {
+      "id": "F-102",
+      "text": "Checkpoints are partition-local, index writes are idempotent, and the full rebuild survives as a recovery path.",
+      "status": "confirmed",
+      "sections": ["key-agent-decisions"],
+      "citations": [
+        {
+          "sourceId": "atlas-index-project",
+          "locator": "project-record#decisions"
+        }
+      ]
+    },
+    {
+      "id": "F-103",
+      "text": "A checkpointed change reader feeds idempotent workers, and a scheduled audit samples both sides for drift.",
+      "status": "confirmed",
+      "sections": ["as-built-architecture"],
+      "citations": [
+        {
+          "sourceId": "atlas-index-project",
+          "locator": "project-record#as-built"
+        }
+      ]
+    },
+    {
+      "id": "F-104",
+      "text": "Checkpoint persistence, replay-safe workers, and the drift audit shipped across three sequential milestones.",
+      "status": "confirmed",
+      "sections": ["implementation-record"],
+      "citations": [
+        {
+          "sourceId": "atlas-index-project",
+          "locator": "project-record#milestones"
+        }
+      ]
+    },
+    {
+      "id": "F-105",
+      "text": "Contract, interrupted-restart, duplicate-batch, and sampled parity suites all passed before cutover.",
+      "status": "confirmed",
+      "sections": ["validation-evidence"],
+      "citations": [
+        {
+          "sourceId": "atlas-index-project",
+          "locator": "project-record#validation"
+        }
+      ]
+    },
+    {
+      "id": "F-106",
+      "text": "Incremental indexing is active and the nightly rebuild is documented as a recovery-only procedure.",
+      "status": "confirmed",
+      "sections": ["outcome"],
+      "citations": [
+        {
+          "sourceId": "atlas-index-project",
+          "locator": "project-record#outcome"
+        }
+      ]
+    }
+  ],
+  "unresolvedClaims": [
+    {
+      "id": "F-107",
+      "text": "Retention of audit samples beyond ninety days awaits a governance decision.",
+      "reason": "needs-confirmation",
+      "sections": ["validation-evidence"],
+      "citations": [
+        {
+          "sourceId": "atlas-index-project",
+          "locator": "project-record#open-questions"
+        }
+      ]
+    }
+  ],
+  "overrides": []
+}

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

@@ -1,22 +1,44 @@
 # Example fact base: Atlas Index recap
 
-This fictional fact base demonstrates a completed-project recap.
+This fictional fact base demonstrates a completed-project recap. The prose below
+is the human-readable view; `fact-base.json` beside it is the same evidence in
+the `explainer-kit.fact-base/v1` shape a run actually consumes, with each claim
+tagged to the narrative section it belongs to.
 
 ## 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
+- **F-102 — Decisions:** Checkpoints are partition-local, writes are idempotent,
+  and the full rebuild is retained as a recovery path.
+  Source: [decision log](https://docs.example.com/atlas-index/decisions).
+- **F-103 — 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.
+- **F-104 — Implementation:** Checkpoint persistence, replay-safe workers, and
+  the drift audit shipped across three milestones.
+  Source: [milestone record](https://docs.example.com/atlas-index/milestones).
+- **F-105 — Validation:** Contract, restart, duplicate-delivery, 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
+- **F-106 — 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).
 
+## Unresolved
+
+- **F-107 — Retention:** How long audit samples are kept is still a governance
+  question, so the recap reports it as unresolved rather than deciding it.
+
 ## Reconciliation notes
 
 An early plan proposed one shared checkpoint. Implementation evidence records a
 checkpoint per partition, so F-102 treats the implementation as authoritative.
+
+## Companion draft
+
+`content.md` is the authored floor draft this evidence supports. It is written
+for the v2 authoring model: tables, a fenced `diagram` block, a `timeline`,
+callouts, and lists, all of which the deterministic narrative renderer turns
+into real structured HTML rather than flat paragraphs.

package/assets/skills/explainer-kit/recipes/engineer-tour.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "explainer-kit.recipe/v1",
+  "schemaVersion": "explainer-kit.recipe/v2",
   "id": "engineer-tour",
   "version": "1",
   "sourceRoles": [
@@ -11,21 +11,38 @@
       "maxBindings": 1
     }
   ],
-  "requiredNarrative": [
-    "orientation",
-    "architecture",
-    "execution-flow",
-    "key-code",
-    "validation"
-  ],
-  "artifacts": [
+  "floor": [
     {
       "id": "engineer-tour",
       "type": "explainer",
+      "authoring": "html",
       "template": "engineer-tour",
-      "required": true
+      "required": true,
+      "briefRef": "briefs/engineer-tour.md",
+      "requiredNarrative": [
+        "orientation",
+        "architecture",
+        "execution-flow",
+        "key-code",
+        "validation"
+      ]
     }
   ],
+  "expansion": {
+    "profiles": [
+      {
+        "profileId": "supporting-diagram",
+        "type": "diagram",
+        "authoring": "html",
+        "briefRef": "briefs/supporting-diagram.md",
+        "shell": "diagram-shell",
+        "maxCount": 4
+      }
+    ],
+    "limits": {
+      "maxArtifacts": 4
+    }
+  },
   "discoveryLimits": {
     "consecutiveNoNewFindingsRounds": 2,
     "maxRounds": 8

package/assets/skills/explainer-kit/recipes/program-recap.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "explainer-kit.recipe/v1",
+  "schemaVersion": "explainer-kit.recipe/v2",
   "id": "program-recap",
   "version": "1",
   "sourceRoles": [
@@ -11,22 +11,46 @@
       "maxBindings": 1
     }
   ],
-  "requiredNarrative": [
-    "program-overview",
-    "wave-map",
-    "per-wave-outcomes",
-    "convention-evolution",
-    "aggregate-numbers",
-    "follow-up-ledger"
-  ],
-  "artifacts": [
+  "floor": [
     {
       "id": "program-recap",
       "type": "hub",
+      "authoring": "markdown",
       "template": "house-style",
-      "required": true
+      "required": true,
+      "briefRef": "briefs/program-recap.md",
+      "requiredNarrative": [
+        "program-overview",
+        "wave-map",
+        "per-wave-outcomes",
+        "convention-evolution",
+        "aggregate-numbers",
+        "follow-up-ledger"
+      ]
     }
   ],
+  "expansion": {
+    "profiles": [
+      {
+        "profileId": "supporting-diagram",
+        "type": "diagram",
+        "authoring": "html",
+        "briefRef": "briefs/supporting-diagram.md",
+        "shell": "diagram-shell",
+        "maxCount": 3
+      },
+      {
+        "profileId": "project-page",
+        "type": "explainer",
+        "authoring": "markdown",
+        "briefRef": "briefs/project-page.md",
+        "maxCount": 12
+      }
+    ],
+    "limits": {
+      "maxArtifacts": 12
+    }
+  },
   "discoveryLimits": {
     "consecutiveNoNewFindingsRounds": 2,
     "maxRounds": 8

package/assets/skills/explainer-kit/recipes/project-explainer.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "explainer-kit.recipe/v1",
+  "schemaVersion": "explainer-kit.recipe/v2",
   "id": "project-explainer",
   "version": "1",
   "sourceRoles": [
@@ -11,21 +11,38 @@
       "maxBindings": 1
     }
   ],
-  "requiredNarrative": [
-    "planned-architecture",
-    "decisions",
-    "risks",
-    "phases",
-    "validation-approach"
-  ],
-  "artifacts": [
+  "floor": [
     {
       "id": "project-explainer",
       "type": "hub",
+      "authoring": "markdown",
       "template": "house-style",
-      "required": true
+      "required": true,
+      "briefRef": "briefs/project-explainer.md",
+      "requiredNarrative": [
+        "planned-architecture",
+        "decisions",
+        "risks",
+        "phases",
+        "validation-approach"
+      ]
     }
   ],
+  "expansion": {
+    "profiles": [
+      {
+        "profileId": "supporting-diagram",
+        "type": "diagram",
+        "authoring": "html",
+        "briefRef": "briefs/supporting-diagram.md",
+        "shell": "diagram-shell",
+        "maxCount": 4
+      }
+    ],
+    "limits": {
+      "maxArtifacts": 4
+    }
+  },
   "discoveryLimits": {
     "consecutiveNoNewFindingsRounds": 2,
     "maxRounds": 8

package/assets/skills/explainer-kit/recipes/project-recap.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "explainer-kit.recipe/v1",
+  "schemaVersion": "explainer-kit.recipe/v2",
   "id": "project-recap",
   "version": "1",
   "sourceRoles": [
@@ -11,22 +11,54 @@
       "maxBindings": 1
     }
   ],
-  "requiredNarrative": [
-    "original-request",
-    "key-agent-decisions",
-    "as-built-architecture",
-    "implementation-record",
-    "validation-evidence",
-    "outcome"
-  ],
-  "artifacts": [
+  "floor": [
     {
       "id": "project-recap",
       "type": "hub",
+      "authoring": "markdown",
       "template": "house-style",
-      "required": true
+      "required": true,
+      "briefRef": "briefs/project-recap.md",
+      "requiredNarrative": [
+        "original-request",
+        "key-agent-decisions",
+        "as-built-architecture",
+        "implementation-record",
+        "validation-evidence",
+        "outcome"
+      ]
     }
   ],
+  "expansion": {
+    "profiles": [
+      {
+        "profileId": "supporting-diagram",
+        "type": "diagram",
+        "authoring": "html",
+        "briefRef": "briefs/supporting-diagram.md",
+        "shell": "diagram-shell",
+        "maxCount": 4
+      },
+      {
+        "profileId": "deep-dive",
+        "type": "explainer",
+        "authoring": "markdown",
+        "briefRef": "briefs/deep-dive.md",
+        "maxCount": 3
+      },
+      {
+        "profileId": "walkthrough-deck",
+        "type": "deck",
+        "authoring": "html",
+        "briefRef": "briefs/walkthrough-deck.md",
+        "shell": "deck-shell",
+        "maxCount": 1
+      }
+    ],
+    "limits": {
+      "maxArtifacts": 6
+    }
+  },
   "discoveryLimits": {
     "consecutiveNoNewFindingsRounds": 2,
     "maxRounds": 8

package/assets/skills/explainer-kit/references/contracts.md

@@ -30,13 +30,25 @@ claims, sources, overrides, and the freshness policy. It returns:
 No provider name, command, credential, or dispatch protocol is part of this
 contract.
 
-Every unattended run also requires a provider-neutral author callback. An
-in-process caller supplies `options.author(request)`; a JSON-only CLI caller
-uses `--author-module author.mjs`. The core invokes it once per recipe artifact
-with an `AuthorRequestV1` containing the exact narrative outline, reconciled
-fact base, and bounded-discovery context. It must return an `AuthorResultV1`
-with every required section in order, non-empty prose, and non-secret
-provenance. The executable callback is never persisted in `run-request.json`.
+Every run, interactive or unattended, also requires a provider-neutral author
+callback; a run without one fails `E_AUTHOR_REQUIRED`. An in-process caller
+supplies `options.author(request)`; a JSON-only CLI caller uses
+`--author-module author.mjs`. The core invokes it once per resolved artifact
+with an `explainer-kit.author-request/v2` payload containing the artifact
+identity and type, the artifact's authoring path, the inlined brief, the
+reconciled fact base, the resolved theme, the shell source for artistic
+artifacts, the required narrative sections for narrative floor artifacts, and
+bounded-discovery context. It must return an `explainer-kit.author-result/v2`
+carrying exactly one of `content.markdown` or `content.html`, matching the
+artifact's declared authoring path, plus non-secret provenance. A floor result
+may also carry `proposedArtifacts` of `{id, profileId, rationale}`; the
+referenced expansion profile supplies the type, authoring path, brief, and
+shell. The executable callback is never persisted in `run-request.json`.
+
+Unknown profile IDs and unsafe, duplicate, or floor-colliding artifact IDs are
+hard errors. Proposals beyond a profile's `maxCount` or the recipe's
+`expansion.limits.maxArtifacts` are rejected with a warning and the run
+continues.
 
 ## Explicit source forms
 
@@ -57,7 +69,8 @@ provenance. The executable callback is never persisted in `run-request.json`.
 An unattended request asserts that its explicit source artifacts are already
 approved. It does not prompt, and it fails before narrative serialization when
 the author is absent, returns an invalid result, or copies excessive verbatim
-source text. Interactive review and same-run approval/resume remain unchanged.
+source text. It auto-approves with `auto-drafted` marking once the artifacts are
+built and checked.
 
 ## Pipeline and retained package
 
@@ -65,19 +78,30 @@ The core executes:
 
 1. validate request and recipe
 2. reconcile or check the fact base
-3. apply bounded discovery and obtain or create recipe content
+3. apply bounded discovery
 4. resolve one theme
-5. render typed artifacts
-6. run structural and optional browser QA
-7. write the manifest and build record
+5. author each floor artifact against its brief, evaluate expansion proposals,
+   and author each accepted expansion artifact
+6. render typed artifacts through the narrative renderer or validate
+   agent-composed HTML, per each artifact's declared authoring path
+7. run structural, guideline, and optional browser QA
+8. resolve content approval — the interactive gate pauses here, after render and
+   QA and before anything is published or persisted externally
+9. write the manifest and build record
 
 The run package retains the privacy-safe `run-request.json`,
 `source/content-approval.json`, `source/fact-base.json`,
-`source/fact-base.md`, `source/content/*.md`, optional structured
-`source/author/*.json` results, `theme.resolved.json`, rendered `site/` files,
-`manifest.json`, and `build-record.json` as far as each stage succeeds. A stage
-failure records a structured error and recovery action without deleting earlier
-outputs. Raw art direction is omitted unless the request explicitly opts in.
+`source/fact-base.md`, authored content under `source/content/*.md` and
+`source/content/*.html`, structured `source/author/*.json` results,
+`theme.resolved.json`, rendered `site/` files, `manifest.json`, and
+`build-record.json` as far as each stage succeeds. A stage failure records a
+structured error and recovery action without deleting earlier outputs. Raw art
+direction is omitted unless the request explicitly opts in.
+
+Build-record stages are terminal once `passed` or `warned`. A rejected run that
+is later approved reopens the render and QA stages through a narrowly guarded
+record-level reset so the corrected sources are re-rendered and re-validated,
+leaving an auditable trail rather than approving stale artifacts.
 
 When a caller supplies `discover({ round, recipe, factBase })`, the callback
 returns the findings added in that round. The core stops after two consecutive
@@ -93,7 +117,7 @@ Durability and publishing are never implicit.
   `record-durability.mjs`; the core never creates commits. The first evidence
   commit must contain every path and byte hash in `manifest.immutableHashes`:
   the privacy-safe request, content approval, fact-base JSON and Markdown,
-  declared author results, all content Markdown, the resolved theme, and every
+  declared author results, all authored content, the resolved theme, and every
   built artifact retained in the package. Mutable `manifest.json` and
   `build-record.json` remain excluded for the separate evidence update.
   Schema-v1 manifests created before complete-package coverage are rejected
@@ -110,7 +134,9 @@ verified. Publishing remains independently human-gated by the caller.
 ## Result
 
 `runExplainer` returns the run root, manifest path, build-record path, outcome,
-warnings, and bounded-discovery summary. Input validation and unsupported
+warnings, approval status and marking, and bounded-discovery summary. The
+marking rides in the result and the approval record only; `manifest/v1` stays
+frozen and carries no marking field. Input validation and unsupported
 recipes reject before output mutation. Failures after initialization return a
 `failed` result with paths to the retained record and intermediates.