@open-agent-toolkit/cli 0.2.20 → 0.2.21

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

@@ -0,0 +1,47 @@
+# Project recap author brief
+
+## Audience
+
+Write for a busy team reader, including people who did not work on the project
+and are not deeply technical. One skim should explain what was requested, what
+changed, why the important choices were made, what evidence supports the
+result, and what remains.
+
+## Voice and editing
+
+Be direct, factual, and concise. Use short sentences, active voice, and
+concrete nouns. Define unavoidable jargon inline. Cut throat-clearing, hedges,
+forced triplets, nested parentheticals, em-dash chains, and “not just X but Y”
+constructions. Put enumerable material in bullets or tables. Turn PR and issue
+references into real links rather than bare numbers. Preserve every supported
+fact and citation; state uncertainty instead of inventing connective detail.
+Use the same terms, statuses, and numbers throughout.
+
+## Narrative intent
+
+- **Original request:** State the user-visible goal, original constraints, and
+  success criteria. Separate the request from the eventual implementation.
+- **Key agent decisions:** Explain the few decisions that materially shaped the
+  result. Pair each decision with its reason and consequence.
+- **As-built architecture:** Describe the delivered system and its boundaries.
+  Include at least one high-level architecture diagram, inline or standalone.
+- **Implementation record:** Summarize the work in an evidence table with
+  components, notable changes, and durable references.
+- **Validation evidence:** Use a table for commands, checks, observed results,
+  and any limits. Do not substitute “tests passed” for concrete evidence.
+- **Outcome:** Say what now works, what did not ship, and what the next reader
+  should do.
+
+## Floor
+
+Produce one rich narrative hub covering all six sections above. It must contain
+at least one high-level architecture diagram, structured lists where useful,
+and evidence tables for implementation and validation. The page should remain
+useful without any expansion artifact.
+
+## Expansion license
+
+Propose additional diagrams, a deep-dive, or a walkthrough deck when complexity
+earns it. Expansion should clarify a real boundary, flow, trade-off, or
+operational handoff that would overload the hub. Do not expand to repeat the
+same story in another format.

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