@open-agent-toolkit/cli 0.3.14 → 0.3.15

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.3.14"
+  "oatVersion": "0.3.15"
 }

package/assets/docs/contributing/markdown-features.md

@@ -62,6 +62,44 @@ Fenced code blocks with `mermaid` are rendered as diagrams.
       A[Read docs tree] --> B[Generate index]
     ```
 
+Rendered Mermaid diagrams use the site palette. Click or tap one to open it
+full screen at a legible size; on a phone, pan to see the rest. Press Escape,
+the close button, or click again to close it.
+
+## Images and Diagram SVGs
+
+Every Markdown image opens in a zoom view when clicked. SVG images open full
+screen at a legible size, like Mermaid diagrams. Put images under
+`public/` and link them with a root-relative path such as
+`/diagrams/name.svg`; the site adds its base path.
+
+Name a pair of files `<name>-light.<ext>` and `<name>-dark.<ext>` to show one
+image per site theme. Place both images together; each is shown only in its
+theme.
+
+A diagram that needs to read well, especially on a phone, gets a hand-drawn SVG
+pair next to its Mermaid source. Mermaid stays the source of truth: when you
+change the Mermaid, update both SVGs in the same change.
+
+=== "Syntax"
+
+    ````text
+    === "Diagram"
+
+        ![What the diagram shows](/diagrams/name-light.svg)
+        ![What the diagram shows](/diagrams/name-dark.svg)
+
+    === "Mermaid source"
+
+        ```mermaid
+        flowchart LR
+          A[Read docs tree] --> B[Generate index]
+        ```
+    ````
+
+The alt text describes what the diagram shows and claims nothing the Mermaid
+does not.
+
 ## Tabs
 
 Tab groups use the existing tab transform syntax:

package/assets/docs/contributing/smoke-testing.md

@@ -22,19 +22,26 @@ outcome of any particular run.
 
 ## Data flow
 
-```mermaid
-flowchart TD
-  F["Fixture template\ntools/smoke/fixture/"] --> PRE["Preflight\ninstall + auth + fixture + local oat"]
-  PRE -->|blocked| STOP["Exit before provisioning"]
-  PRE -->|ready| PREP["Prepare / provision\ndisposable worktree + isolated config + manifest"]
-  PREP --> DRIVE["Drive\nper-harness protocol"]
-  DRIVE --> AUTO["Automated: runner launches provider"]
-  DRIVE --> OP["Operator: printed command + prompt"]
-  AUTO --> COLLECT["Collect\nevidence bundle + report"]
-  OP --> COLLECT
-  COLLECT --> CLEAN["Cleanup\nmanifest-scoped"]
-  COLLECT -.->|--keep| SKIP["Cleanup skipped"]
-```
+=== "Diagram"
+
+    ![Smoke-test flow: fixture template, preflight (exit before provisioning if blocked), prepare and provision, drive automatically or by an operator, collect evidence, then manifest-scoped cleanup, skipped with --keep](/diagrams/smoke-testing-light.svg)
+    ![Smoke-test flow: fixture template, preflight (exit before provisioning if blocked), prepare and provision, drive automatically or by an operator, collect evidence, then manifest-scoped cleanup, skipped with --keep](/diagrams/smoke-testing-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart TD
+      F["Fixture template\ntools/smoke/fixture/"] --> PRE["Preflight\ninstall + auth + fixture + local oat"]
+      PRE -->|blocked| STOP["Exit before provisioning"]
+      PRE -->|ready| PREP["Prepare / provision\ndisposable worktree + isolated config + manifest"]
+      PREP --> DRIVE["Drive\nper-harness protocol"]
+      DRIVE --> AUTO["Automated: runner launches provider"]
+      DRIVE --> OP["Operator: printed command + prompt"]
+      AUTO --> COLLECT["Collect\nevidence bundle + report"]
+      OP --> COLLECT
+      COLLECT --> CLEAN["Cleanup\nmanifest-scoped"]
+      COLLECT -.->|--keep| SKIP["Cleanup skipped"]
+    ```
 
 Collection runs even when the drive stage fails, so a broken run still produces
 an evidence bundle before cleanup reclaims its resources.

package/assets/docs/docs-tooling/workflows.md

@@ -66,25 +66,32 @@ skills.
 
 Diagram: bootstrap once, then analyze, approve and apply only agreed improvements.
 
-```mermaid
-flowchart TD
-  SETUP["Bootstrap once\nConfirm inputs, then oat docs init"]
-  MD["Markdown\nValidate files and config"]
-  APP["Docs app\nInstall and verify build"]
-  AN["Analyze\nRead docs, write findings"]
-  PLAN["Plan from findings\nNo docs writes yet"]
-  Q{"Approve changes?"}
-  APPLY["Apply approved items\nNew branch, verify, offer PR"]
-  STOP["Skip all\nNo docs changed"]
-  SETUP --> MD
-  SETUP --> APP
-  MD -.-> AN
-  APP -.-> AN
-  AN --> PLAN
-  PLAN --> Q
-  Q -->|"approved"| APPLY
-  Q -->|"all skipped"| STOP
-```
+=== "Diagram"
+
+    ![Bootstrap once with oat docs init into plain Markdown or a docs app, then analyze, plan, and either apply approved changes or stop when all are skipped](/diagrams/docs-workflows-light.svg)
+    ![Bootstrap once with oat docs init into plain Markdown or a docs app, then analyze, plan, and either apply approved changes or stop when all are skipped](/diagrams/docs-workflows-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart TD
+      SETUP["Bootstrap once\nConfirm inputs, then oat docs init"]
+      MD["Markdown\nValidate files and config"]
+      APP["Docs app\nInstall and verify build"]
+      AN["Analyze\nRead docs, write findings"]
+      PLAN["Plan from findings\nNo docs writes yet"]
+      Q{"Approve changes?"}
+      APPLY["Apply approved items\nNew branch, verify, offer PR"]
+      STOP["Skip all\nNo docs changed"]
+      SETUP --> MD
+      SETUP --> APP
+      MD -.-> AN
+      APP -.-> AN
+      AN --> PLAN
+      PLAN --> Q
+      Q -->|"approved"| APPLY
+      Q -->|"all skipped"| STOP
+    ```
 
 - **Setup, once.** `oat-docs-bootstrap` checks the repo without writing, asks
   you to confirm its inputs, then runs `oat docs init`. Plain Markdown setup validates authored files,

package/assets/docs/getting-started/concepts.md

@@ -9,17 +9,24 @@ OAT combines a provider-sync layer, reusable skills and CLI tooling, and an opti
 
 ## Choose What to Adopt
 
-```mermaid
-flowchart LR
-  GOAL["What do you\nneed first?"] --> SYNC["Align coding tools\nProvider Sync"]
-  GOAL --> SKILLS["Help with one task\nReusable Skills"]
-  GOAL --> WORK["Resume longer work\nWorkflows"]
-  GOAL --> DOCS["Maintain documentation\nMarkdown or a docs site"]
-  SYNC -.-> LATER["Add another path\nwhenever useful"]
-  SKILLS -.-> LATER
-  WORK -.-> LATER
-  DOCS -.-> LATER
-```
+=== "Diagram"
+
+    ![Four independent starting points: align coding tools with Provider Sync, help with one task with reusable skills, resume longer work with workflows, or maintain documentation; add another path whenever useful](/diagrams/adoption-paths-light.svg)
+    ![Four independent starting points: align coding tools with Provider Sync, help with one task with reusable skills, resume longer work with workflows, or maintain documentation; add another path whenever useful](/diagrams/adoption-paths-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart LR
+      GOAL["What do you\nneed first?"] --> SYNC["Align coding tools\nProvider Sync"]
+      GOAL --> SKILLS["Help with one task\nReusable Skills"]
+      GOAL --> WORK["Resume longer work\nWorkflows"]
+      GOAL --> DOCS["Maintain documentation\nMarkdown or a docs site"]
+      SYNC -.-> LATER["Add another path\nwhenever useful"]
+      SKILLS -.-> LATER
+      WORK -.-> LATER
+      DOCS -.-> LATER
+    ```
 
 - **Provider Sync:** `oat init --scope project`, choose providers, then `oat sync --scope project`.
 - **Reusable skills:** `oat tools install --scope user`; no repository initialization is needed.
@@ -36,16 +43,23 @@ Continue with [Provider Sync](../provider-sync/index.md), [Tool Packs](tool-pack
 
 OAT keeps canonical assets in repo-controlled locations and projects provider-specific views from that source of truth. The canonical form is what you edit and review directly; provider views are synchronized outputs that let Claude Code, Cursor, Copilot, Gemini, and Codex consume the same intent in their native layouts.
 
-```mermaid
-flowchart LR
-  SKILLS[".agents/skills/"] --> OAT["oat sync"]
-  AGENTS[".agents/agents/"] --> OAT
-  RULES[".agents/rules/"] --> OAT
-  OAT --> CLAUDE[".claude/"]
-  OAT --> CURSOR[".cursor/"]
-  OAT --> COPILOT[".github/"]
-  OAT --> CODEX[".codex/"]
-```
+=== "Diagram"
+
+    ![Canonical skills, agents and rules in .agents/ flow through oat sync into provider views under .claude/, .cursor/, .github/ and .codex/](/diagrams/provider-views-light.svg)
+    ![Canonical skills, agents and rules in .agents/ flow through oat sync into provider views under .claude/, .cursor/, .github/ and .codex/](/diagrams/provider-views-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart LR
+      SKILLS[".agents/skills/"] --> OAT["oat sync"]
+      AGENTS[".agents/agents/"] --> OAT
+      RULES[".agents/rules/"] --> OAT
+      OAT --> CLAUDE[".claude/"]
+      OAT --> CURSOR[".cursor/"]
+      OAT --> COPILOT[".github/"]
+      OAT --> CODEX[".codex/"]
+    ```
 
 Gemini CLI is a native read-only consumer; OAT does not generate a `.gemini/` view through sync.
 

package/assets/docs/provider-sync/manifest-and-drift.md

@@ -15,23 +15,30 @@ This page explains how OAT remembers what it manages and how it distinguishes cl
 
 Diagram: canonical assets produce provider views and a manifest; status reports what changed and how to resolve it.
 
-```mermaid
-flowchart TD
-  CANON["Canonical assets\nEdit .agents/"]
-  SYNC["oat sync\nGenerate views"]
-  VIEWS["Provider views"]
-  MANIFEST["Sync manifest"]
-  STATUS["oat status\nInspect before resolving"]
-  TRACKED["Tracked views\nin_sync / drifted / missing"]
-  STRAY["Unmanaged files\nstray"]
-  CANON --> SYNC
-  SYNC --> VIEWS
-  SYNC --> MANIFEST
-  MANIFEST --> STATUS
-  VIEWS --> STATUS
-  STATUS --> TRACKED
-  STATUS --> STRAY
-```
+=== "Diagram"
+
+    ![You edit canonical assets in .agents/; oat sync generates provider views and the sync manifest; oat status reads both and reports tracked views as in_sync, drifted or missing, and unmanaged files as stray](/diagrams/sync-and-drift-light.svg)
+    ![You edit canonical assets in .agents/; oat sync generates provider views and the sync manifest; oat status reads both and reports tracked views as in_sync, drifted or missing, and unmanaged files as stray](/diagrams/sync-and-drift-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart TD
+      CANON["Canonical assets\nEdit .agents/"]
+      SYNC["oat sync\nGenerate views"]
+      VIEWS["Provider views"]
+      MANIFEST["Sync manifest"]
+      STATUS["oat status\nInspect before resolving"]
+      TRACKED["Tracked views\nin_sync / drifted / missing"]
+      STRAY["Unmanaged files\nstray"]
+      CANON --> SYNC
+      SYNC --> VIEWS
+      SYNC --> MANIFEST
+      MANIFEST --> STATUS
+      VIEWS --> STATUS
+      STATUS --> TRACKED
+      STATUS --> STRAY
+    ```
 
 - **What you edit.** Only the canonical files under `.agents/` (skills, agents,
   rules). `oat sync` reads them and writes provider views as symlinks or copies

package/assets/docs/reference/project-state-machine.md

@@ -15,26 +15,33 @@ This page is the compact contract for how project lifecycle state and review sta
 
 ## State Transition Map
 
-```mermaid
-flowchart TD
-  D["Discovery in progress"] --> RS["Ready for spec"]
-  RS --> S["Spec in progress"] --> RD["Ready for design"]
-  RD --> G["Design in progress"] --> RP["Ready for plan"]
-  RP --> P["Plan in progress"] --> RI["Ready for implement"]
-  RI --> I["Implement in progress"] --> IC["Implement complete"]
-  IC --> PRO["PR open (pr_open)"]
-  PRO --> REV["Revise (in_progress)"]
-  REV --> PRO
-  PRO --> C["Complete"]
-
-  I --> RV["Review received"]
-  RV --> FA["Fixes added"]
-  FA --> FC["Fixes completed"]
-  FC --> PASSED["Review passed"]
-  PASSED --> I
-
-  LITE["Lite: batched interview\n(no discovery/spec/design)"] -. entry point .-> P
-```
+=== "Diagram"
+
+    ![Project state machine: discovery, spec, design, plan and implementation phases, then PR open and complete; a review loop returns to implementation, a revise loop runs from PR open and back, and lite enters at planning](/diagrams/project-state-machine-light.svg)
+    ![Project state machine: discovery, spec, design, plan and implementation phases, then PR open and complete; a review loop returns to implementation, a revise loop runs from PR open and back, and lite enters at planning](/diagrams/project-state-machine-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart TD
+      D["Discovery in progress"] --> RS["Ready for spec"]
+      RS --> S["Spec in progress"] --> RD["Ready for design"]
+      RD --> G["Design in progress"] --> RP["Ready for plan"]
+      RP --> P["Plan in progress"] --> RI["Ready for implement"]
+      RI --> I["Implement in progress"] --> IC["Implement complete"]
+      IC --> PRO["PR open (pr_open)"]
+      PRO --> REV["Revise (in_progress)"]
+      REV --> PRO
+      PRO --> C["Complete"]
+
+      I --> RV["Review received"]
+      RV --> FA["Fixes added"]
+      FA --> FC["Fixes completed"]
+      FC --> PASSED["Review passed"]
+      PASSED --> I
+
+      LITE["Lite: batched interview\n(no discovery/spec/design)"] -. entry point .-> P
+    ```
 
 The solid chain is the spec-driven progression. Lite enters at **Plan in
 progress** and never sets `oat_phase` to `discovery`, `spec`, or `design`;

package/assets/docs/workflows/advanced/evidence-layers.md

@@ -19,21 +19,28 @@ never gates a conclusion on its own.
 
 ## Layer map
 
-```mermaid
-flowchart TD
-  L1["Layer 1 — Policy resolution\nnamed ceiling · candidates · capped/uncapped mode"]
-  L2["Layer 2 — Launcher-owned configured invocation\nroute · target/model/effort axes · selection reason ·\ncandidates considered · launch acceptance"]
-  L3["Layer 3 — Runtime-observed identity (optional)\nproducer + model, only under trusted provenance"]
+=== "Diagram"
 
-  L1 --> L2 --> L3
+    ![Three evidence layers: policy resolution, launcher-owned configured invocation, and optional runtime-observed identity; assertions check layers 1 and 2 and only record layer 3, which resolves to reported or not-reported](/diagrams/evidence-layers-light.svg)
+    ![Three evidence layers: policy resolution, launcher-owned configured invocation, and optional runtime-observed identity; assertions check layers 1 and 2 and only record layer 3, which resolves to reported or not-reported](/diagrams/evidence-layers-dark.svg)
 
-  A["Assertions"] -->|assert on| L1
-  A -->|assert on| L2
-  A -.->|record only| L3
+=== "Mermaid source"
 
-  L3 --> R["reported\n(both present + trusted provenance)"]
-  L3 --> NR["not-reported\n(anything else normalizes here)"]
-```
+    ```mermaid
+    flowchart TD
+      L1["Layer 1 — Policy resolution\nnamed ceiling · candidates · capped/uncapped mode"]
+      L2["Layer 2 — Launcher-owned configured invocation\nroute · target/model/effort axes · selection reason ·\ncandidates considered · launch acceptance"]
+      L3["Layer 3 — Runtime-observed identity (optional)\nproducer + model, only under trusted provenance"]
+
+      L1 --> L2 --> L3
+
+      A["Assertions"] -->|assert on| L1
+      A -->|assert on| L2
+      A -.->|record only| L3
+
+      L3 --> R["reported\n(both present + trusted provenance)"]
+      L3 --> NR["not-reported\n(anything else normalizes here)"]
+    ```
 
 Assertions bind to Layers 1 and 2. Layer 3 is recorded as `reported` or
 `not-reported`; its absence never invalidates Layer 2.

package/assets/docs/workflows/advanced/orchestration-model.md

@@ -29,25 +29,32 @@ Terms used on this page:
 
 ## Default Topology
 
-```mermaid
-flowchart TD
-  Root["Project root\nlifecycle owner"]
-  Adapter["Project dispatch adapter"]
-  Engine["Provider-neutral dispatch engine"]
-
-  Root --> Adapter --> Engine
-  Engine --> P["Phase implementer\none per phase"]
-  P --> T1["Planned task commit"]
-  P --> T2["Planned task commit"]
-  P -. optional .-> Recon["Recon / specialist / isolated fanout"]
-
-  Root -. independent review lane .-> Adapter
-  Engine -. exact reviewer route .-> R["Phase reviewer"]
-  R -->|blocking findings| Root
-  Root -->|resume bounded fix| P
-
-  Root -. external gate lane .-> G["Configured cross-runtime gate"]
-```
+=== "Diagram"
+
+    ![Default topology: the project root goes through the dispatch adapter and provider-neutral engine to one phase implementer per phase, which makes planned task commits and optionally a recon or specialist fanout; the engine routes an exact phase reviewer whose blocking findings return to the root, which resumes a bounded fix; dashed lanes show independent review and an external cross-runtime gate](/diagrams/orchestration-model-1-default-topology-light.svg)
+    ![Default topology: the project root goes through the dispatch adapter and provider-neutral engine to one phase implementer per phase, which makes planned task commits and optionally a recon or specialist fanout; the engine routes an exact phase reviewer whose blocking findings return to the root, which resumes a bounded fix; dashed lanes show independent review and an external cross-runtime gate](/diagrams/orchestration-model-1-default-topology-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart TD
+      Root["Project root\nlifecycle owner"]
+      Adapter["Project dispatch adapter"]
+      Engine["Provider-neutral dispatch engine"]
+
+      Root --> Adapter --> Engine
+      Engine --> P["Phase implementer\none per phase"]
+      P --> T1["Planned task commit"]
+      P --> T2["Planned task commit"]
+      P -. optional .-> Recon["Recon / specialist / isolated fanout"]
+
+      Root -. independent review lane .-> Adapter
+      Engine -. exact reviewer route .-> R["Phase reviewer"]
+      R -->|blocking findings| Root
+      Root -->|resume bounded fix| P
+
+      Root -. external gate lane .-> G["Configured cross-runtime gate"]
+    ```
 
 The solid implementation lane is mandatory. The dotted nested lane is
 benefit-driven. A run does not fail merely because the phase agent cannot or
@@ -83,21 +90,28 @@ matrix. The lifecycle workflow remains authoritative for classification,
 selection judgment, synthesis, and state mutation. The dispatch engine does
 not edit `plan.md`, `implementation.md`, or project state.
 
-```mermaid
-sequenceDiagram
-  participant Root as Project root
-  participant Adapter as Project adapter
-  participant Engine as Dispatch engine
-  participant Record as Run record in implementation.md
-  participant Phase as Phase implementer
-
-  Root->>Adapter: Phase + lifecycle authority
-  Adapter->>Engine: Provider-neutral dispatch request
-  Engine-->>Root: Exact route + request ID
-  Root->>Phase: Phase Scope
-  Root->>Record: Accepted or blocked-before-start result
-  Phase-->>Root: Phase report + commits
-```
+=== "Diagram"
+
+    ![Dispatch layers sequence: the project root passes phase and lifecycle authority to the adapter, the adapter sends a provider-neutral request to the engine, the engine returns the exact route and request ID, the root sends the phase scope and records the accepted or blocked result in implementation.md, and the implementer returns its report and commits](/diagrams/orchestration-model-2-dispatch-layers-light.svg)
+    ![Dispatch layers sequence: the project root passes phase and lifecycle authority to the adapter, the adapter sends a provider-neutral request to the engine, the engine returns the exact route and request ID, the root sends the phase scope and records the accepted or blocked result in implementation.md, and the implementer returns its report and commits](/diagrams/orchestration-model-2-dispatch-layers-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    sequenceDiagram
+      participant Root as Project root
+      participant Adapter as Project adapter
+      participant Engine as Dispatch engine
+      participant Record as Run record in implementation.md
+      participant Phase as Phase implementer
+
+      Root->>Adapter: Phase + lifecycle authority
+      Adapter->>Engine: Provider-neutral dispatch request
+      Engine-->>Root: Exact route + request ID
+      Root->>Phase: Phase Scope
+      Root->>Record: Accepted or blocked-before-start result
+      Phase-->>Root: Phase report + commits
+    ```
 
 ## Phase Execution
 

package/assets/docs/workflows/ideas/lifecycle.md

@@ -22,31 +22,38 @@ Each level has its own independent backlog, scratchpad, and active-idea config v
 
 Start in the home that matches how formed the thought is. Every home is a fine place to stop. Dashed arrows are optional moves.
 
-```mermaid
-flowchart TD
-  Q{"How formed is\nthe thought?"}
-  BS["oat-brainstorm\n(may end inline\nor as a doc)"]
-  SP["Scratchpad seed\n.oat/ideas/\nscratchpad.md"]
-  ID["Idea\n.oat/ideas/{idea}/\ndiscovery.md"]
-  SUM["Summarized idea\n.oat/ideas/{idea}/\nsummary.md"]
-  BL["Backlog item\n.oat/repo/pjm/\nbacklog/items/"]
-  PR["Project\n.oat/projects/\n{scope}/{slug}/"]
-  SPLIT["Parent +\nchild projects"]
-
-  Q -->|unsure| BS
-  Q -->|seed| SP
-  Q -->|explore| ID
-  Q -->|scoped| BL
-  Q -->|ready| PR
-  BS -.-> ID
-  BS -.-> BL
-  BS -.->|"project(s)"| PR
-  SP -.->|optional| ID
-  ID -.->|optional| SUM
-  SUM -.->|optional| PR
-  BL -.->|optional| PR
-  PR -.->|"optional\n(spec-driven)"| SPLIT
-```
+=== "Diagram"
+
+    ![Where a thought starts depending on how formed it is: oat-brainstorm when unsure, a scratchpad seed, an idea, a backlog item, or a project, with optional moves between them and an optional spec-driven split into parent and child projects](/diagrams/ideas-lifecycle-light.svg)
+    ![Where a thought starts depending on how formed it is: oat-brainstorm when unsure, a scratchpad seed, an idea, a backlog item, or a project, with optional moves between them and an optional spec-driven split into parent and child projects](/diagrams/ideas-lifecycle-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart TD
+      Q{"How formed is\nthe thought?"}
+      BS["oat-brainstorm\n(may end inline\nor as a doc)"]
+      SP["Scratchpad seed\n.oat/ideas/\nscratchpad.md"]
+      ID["Idea\n.oat/ideas/{idea}/\ndiscovery.md"]
+      SUM["Summarized idea\n.oat/ideas/{idea}/\nsummary.md"]
+      BL["Backlog item\n.oat/repo/pjm/\nbacklog/items/"]
+      PR["Project\n.oat/projects/\n{scope}/{slug}/"]
+      SPLIT["Parent +\nchild projects"]
+
+      Q -->|unsure| BS
+      Q -->|seed| SP
+      Q -->|explore| ID
+      Q -->|scoped| BL
+      Q -->|ready| PR
+      BS -.-> ID
+      BS -.-> BL
+      BS -.->|"project(s)"| PR
+      SP -.->|optional| ID
+      ID -.->|optional| SUM
+      SUM -.->|optional| PR
+      BL -.->|optional| PR
+      PR -.->|"optional\n(spec-driven)"| SPLIT
+    ```
 
 Where to start:
 

package/assets/docs/workflows/projects/execution/implementation-execution.md

@@ -38,21 +38,28 @@ and updates project state.
 
 Tasks execute serially in one worktree for the phase.
 
-```mermaid
-flowchart LR
-  Root["Project root\nlifecycle owner"] --> P["Phase implementer\none per phase"]
-  P --> T1["Task 1\nbounded commit"]
-  P --> T2["Task 2\nbounded commit"]
-  P -. optional benefit-driven .-> N["Recon / specialist child"]
-
-  P --> Report["Phase report\nverification + commits"]
-  Report --> Root
-  Root --> Ledger["Commit task ledger\npre-review bookkeeping"]
-  Ledger --> R["Independent phase reviewer"]
-  R -->|pass| Book["Review-outcome bookkeeping\n+ next phase"]
-  R -->|blocking findings| Fix["Resume phase implementer\nbounded fix scope"]
-  Fix --> R2["Fresh root-owned review round"]
-```
+=== "Diagram"
+
+    ![Phase execution: the project root dispatches one phase implementer, which makes bounded task commits and optionally a recon or specialist child, then reports back; the root commits the task ledger, an independent reviewer passes the phase or sends blocking findings to a resumed implementer for a bounded fix and a fresh review round](/diagrams/implementation-execution-1-quick-look-light.svg)
+    ![Phase execution: the project root dispatches one phase implementer, which makes bounded task commits and optionally a recon or specialist child, then reports back; the root commits the task ledger, an independent reviewer passes the phase or sends blocking findings to a resumed implementer for a bounded fix and a fresh review round](/diagrams/implementation-execution-1-quick-look-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart LR
+      Root["Project root\nlifecycle owner"] --> P["Phase implementer\none per phase"]
+      P --> T1["Task 1\nbounded commit"]
+      P --> T2["Task 2\nbounded commit"]
+      P -. optional benefit-driven .-> N["Recon / specialist child"]
+
+      P --> Report["Phase report\nverification + commits"]
+      Report --> Root
+      Root --> Ledger["Commit task ledger\npre-review bookkeeping"]
+      Ledger --> R["Independent phase reviewer"]
+      R -->|pass| Book["Review-outcome bookkeeping\n+ next phase"]
+      R -->|blocking findings| Fix["Resume phase implementer\nbounded fix scope"]
+      Fix --> R2["Fresh root-owned review round"]
+    ```
 
 ## Ownership
 
@@ -443,21 +450,28 @@ The new dispatch record links to the original `request_id` through the existing
 `continuation_events` field. This is a new fix scope, not replacement of an
 accepted failed launch and not a new schema version.
 
-```mermaid
-sequenceDiagram
-  participant Root
-  participant Phase as Phase implementer
-  participant Review as Phase reviewer
-
-  Root->>Phase: Phase Scope (request_id=A)
-  Phase-->>Root: DONE + task commits
-  Root->>Review: Review phase commit range
-  Review-->>Root: Critical / High findings
-  Root->>Phase: Resume A in fix mode
-  Phase-->>Root: Fix commit + verification
-  Root->>Review: New independent review round
-  Review-->>Root: Pass
-```
+=== "Diagram"
+
+    ![Fix continuity sequence: root sends the phase scope with request_id A, the implementer returns DONE with task commits, the reviewer returns Critical or High findings, root resumes request A in fix mode, the implementer returns a fix commit, and a new independent review round passes](/diagrams/implementation-execution-2-fix-continuity-light.svg)
+    ![Fix continuity sequence: root sends the phase scope with request_id A, the implementer returns DONE with task commits, the reviewer returns Critical or High findings, root resumes request A in fix mode, the implementer returns a fix commit, and a new independent review round passes](/diagrams/implementation-execution-2-fix-continuity-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    sequenceDiagram
+      participant Root
+      participant Phase as Phase implementer
+      participant Review as Phase reviewer
+
+      Root->>Phase: Phase Scope (request_id=A)
+      Phase-->>Root: DONE + task commits
+      Root->>Review: Review phase commit range
+      Review-->>Root: Critical / High findings
+      Root->>Phase: Resume A in fix mode
+      Phase-->>Root: Fix commit + verification
+      Root->>Review: New independent review round
+      Review-->>Root: Pass
+    ```
 
 ## Parallel Phase Groups
 

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

@@ -35,14 +35,21 @@ For a one-page view of where people approve and what runs automatically in each
 
 ## Lifecycle Map
 
-```mermaid
-flowchart LR
-  D["Discovery"] --> S["Spec"] --> G["Design"] --> P["Plan"]
-  P --> I["Implement (oat-project-implement)"]
-  I --> R["Review loop"] --> PR["PR flow"]
-  PR --> DOC["Docs sync (optional)"]
-  DOC --> C["Complete"]
-```
+=== "Diagram"
+
+    ![Project lifecycle map: discovery, spec, design, plan, implement, review loop, PR flow, optional docs sync, complete](/diagrams/project-lifecycle-1-lifecycle-map-light.svg)
+    ![Project lifecycle map: discovery, spec, design, plan, implement, review loop, PR flow, optional docs sync, complete](/diagrams/project-lifecycle-1-lifecycle-map-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart LR
+      D["Discovery"] --> S["Spec"] --> G["Design"] --> P["Plan"]
+      P --> I["Implement (oat-project-implement)"]
+      I --> R["Review loop"] --> PR["PR flow"]
+      PR --> DOC["Docs sync (optional)"]
+      DOC --> C["Complete"]
+    ```
 
 This map shows the spec-driven default. The quick, lite, import, and capture
 lanes each skip part of it — see [Lane diagrams](#lane-diagrams) below. Lite in
@@ -340,12 +347,19 @@ See [Implementation Execution](execution/implementation-execution.md) for the fu
 
 ### Spec-Driven workflow lane
 
-```mermaid
-flowchart LR
-  D["Discover"] --> S["Spec"] --> G["Design"] --> P["Plan"]
-  P --> I["Implement (oat-project-implement)"]
-  I --> R["Review"] --> PR["PR"] --> Doc["Docs (optional)"] --> C["Complete"]
-```
+=== "Diagram"
+
+    ![Spec-driven lane: discover, spec, design, plan, implement, review, PR, optional docs, complete](/diagrams/project-lifecycle-2-spec-driven-light.svg)
+    ![Spec-driven lane: discover, spec, design, plan, implement, review, PR, optional docs, complete](/diagrams/project-lifecycle-2-spec-driven-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart LR
+      D["Discover"] --> S["Spec"] --> G["Design"] --> P["Plan"]
+      P --> I["Implement (oat-project-implement)"]
+      I --> R["Review"] --> PR["PR"] --> Doc["Docs (optional)"] --> C["Complete"]
+    ```
 
 During the Design step, `oat-project-design` asks how to work through the document unless a mode was selected by argument, environment, or `workflow.designMode`. The three full-design choices are collaborative, selective collaborative, and draft-and-review.
 
@@ -365,15 +379,22 @@ effort controls.
 
 ### Quick lane
 
-```mermaid
-flowchart LR
-  Q["Quick Start\n(adaptive discovery)"] --> D{"Design depth?"}
-  D -->|Straight to plan| P["Plan"]
-  D -->|Lightweight design| LD["Design (quick)"] --> P
-  D -->|Promote| SD["→ Spec-Driven lane"]
-  P --> QI["Implement (oat-project-implement)"]
-  QI --> QR["Review / PR"]
-```
+=== "Diagram"
+
+    ![Quick lane: quick start with adaptive discovery, then a design-depth choice (straight to plan, lightweight design, or promote to spec-driven), plan, implement, review and PR](/diagrams/project-lifecycle-3-quick-lane-light.svg)
+    ![Quick lane: quick start with adaptive discovery, then a design-depth choice (straight to plan, lightweight design, or promote to spec-driven), plan, implement, review and PR](/diagrams/project-lifecycle-3-quick-lane-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart LR
+      Q["Quick Start\n(adaptive discovery)"] --> D{"Design depth?"}
+      D -->|Straight to plan| P["Plan"]
+      D -->|Lightweight design| LD["Design (quick)"] --> P
+      D -->|Promote| SD["→ Spec-Driven lane"]
+      P --> QI["Implement (oat-project-implement)"]
+      QI --> QR["Review / PR"]
+    ```
 
 Quick lane lightweight design intentionally keeps a smaller collaborative/draft choice. Selective collaborative becomes available only after promotion into the full spec-driven design lane.
 
@@ -386,13 +407,20 @@ should use the dispatch-policy names, including explicit `Uncapped` and
 
 ### Lite lane
 
-```mermaid
-flowchart LR
-  L["Lite interview\n(one batched round)"] --> P["Single-phase plan\n(one approval)"]
-  P --> I["Implement (oat-project-implement)"]
-  I --> R["Final review"] --> PR["PR (default closeout)"]
-  P -->|Scope grows| Q["Promote to Quick"]
-```
+=== "Diagram"
+
+    ![Lite lane: one batched interview, a single-phase plan with one approval, implement, final review and PR, with promotion to quick if scope grows](/diagrams/project-lifecycle-4-lite-lane-light.svg)
+    ![Lite lane: one batched interview, a single-phase plan with one approval, implement, final review and PR, with promotion to quick if scope grows](/diagrams/project-lifecycle-4-lite-lane-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart LR
+      L["Lite interview\n(one batched round)"] --> P["Single-phase plan\n(one approval)"]
+      P --> I["Implement (oat-project-implement)"]
+      I --> R["Final review"] --> PR["PR (default closeout)"]
+      P -->|Scope grows| Q["Promote to Quick"]
+    ```
 
 Lite keeps planning and validation in `plan.md`. The interview selects a
 `minimal`, `product`, `technical`, or `both` content shape and records the
@@ -420,29 +448,36 @@ from its five core sections plus any adaptive Product Behavior and Technical
 Design, a **fresh** quick template takes over the `plan.md` path, and `state.md`
 is **rewritten** to quick mode.
 
-```mermaid
-flowchart LR
-  subgraph Before
-    LPLAN["plan.md\nfive core sections plus adaptive\nProduct Behavior / Technical Design"]
-    LSTATE["state.md\noat_workflow_mode: lite"]
-  end
-
-  CMD["oat project promote\n--to quick"]
-
-  subgraph After
-    DISC["discovery.md\nderived from the lite plan\noat_ready_for: oat-project-quick-start"]
-    REF["references/lite-plan.md\noriginal lite plan, preserved"]
-    QPLAN["plan.md\nfresh quick-start template"]
-    QSTATE["state.md\noat_workflow_mode: quick\noat_phase: discovery (complete)\noat_ready_for: oat-project-quick-start"]
-  end
-
-  LPLAN --> CMD
-  LSTATE --> CMD
-  CMD -->|derive| DISC
-  CMD -->|move| REF
-  CMD -->|scaffold| QPLAN
-  CMD -->|rewrite| QSTATE
-```
+=== "Diagram"
+
+    ![Promoting a lite project to quick: oat project promote --to quick derives discovery.md from the lite plan, moves the original to references/lite-plan.md, scaffolds a fresh quick plan.md, and rewrites state.md to quick mode](/diagrams/project-lifecycle-5-promote-lite-to-quick-light.svg)
+    ![Promoting a lite project to quick: oat project promote --to quick derives discovery.md from the lite plan, moves the original to references/lite-plan.md, scaffolds a fresh quick plan.md, and rewrites state.md to quick mode](/diagrams/project-lifecycle-5-promote-lite-to-quick-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart LR
+      subgraph Before
+        LPLAN["plan.md\nfive core sections plus adaptive\nProduct Behavior / Technical Design"]
+        LSTATE["state.md\noat_workflow_mode: lite"]
+      end
+
+      CMD["oat project promote\n--to quick"]
+
+      subgraph After
+        DISC["discovery.md\nderived from the lite plan\noat_ready_for: oat-project-quick-start"]
+        REF["references/lite-plan.md\noriginal lite plan, preserved"]
+        QPLAN["plan.md\nfresh quick-start template"]
+        QSTATE["state.md\noat_workflow_mode: quick\noat_phase: discovery (complete)\noat_ready_for: oat-project-quick-start"]
+      end
+
+      LPLAN --> CMD
+      LSTATE --> CMD
+      CMD -->|derive| DISC
+      CMD -->|move| REF
+      CMD -->|scaffold| QPLAN
+      CMD -->|rewrite| QSTATE
+    ```
 
 The project slug, directory, and branch are untouched, so history and any open
 work continue uninterrupted. `oat_ready_for` is stamped on **both** `discovery.md`
@@ -455,21 +490,35 @@ categorical `reason` and exit non-zero. See
 
 ### Import lane
 
-```mermaid
-flowchart LR
-  I["Import Plan"] --> II1["Implement (oat-project-implement)"]
-  II1 --> IR["Review / PR"]
-```
+=== "Diagram"
+
+    ![Import lane: import a plan, implement, then review and PR](/diagrams/project-lifecycle-6-import-lane-light.svg)
+    ![Import lane: import a plan, implement, then review and PR](/diagrams/project-lifecycle-6-import-lane-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart LR
+      I["Import Plan"] --> II1["Implement (oat-project-implement)"]
+      II1 --> IR["Review / PR"]
+    ```
 
 ### Capture lane
 
 Retroactive project creation for work done outside the OAT project workflow. Common scenario: mobile/cloud sessions where you brainstorm and implement with an agent, then want to open a PR and review from your desktop.
 
-```mermaid
-flowchart LR
-  W["Work on branch\n(no project)"] --> Cap["oat-project-capture"]
-  Cap --> R["Review / PR"]
-```
+=== "Diagram"
+
+    ![Capture lane: work on a branch without a project, run oat-project-capture, then review and PR](/diagrams/project-lifecycle-7-capture-lane-light.svg)
+    ![Capture lane: work on a branch without a project, run oat-project-capture, then review and PR](/diagrams/project-lifecycle-7-capture-lane-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart LR
+      W["Work on branch\n(no project)"] --> Cap["oat-project-capture"]
+      Cap --> R["Review / PR"]
+    ```
 
 Entry point: `/oat-project-capture` (skill-only, no CLI command — requires agent conversation context).
 

package/assets/docs/workflows/projects/reviews/review-flavors.md

@@ -38,29 +38,36 @@ for the deep review request/receive mechanics.
 
 ## Flow map
 
-```mermaid
-flowchart TD
-  subgraph Planning
-    PL["Planning-phase\nartifact self-review"] --> PLR["Inherit planning parent"]
-    PLR --> PLT["Parent model\n(root already at/above ceiling)"]
-  end
-
-  subgraph Implementation
-    IM["Root-owned phase\nself-review"] --> IMR["Resolve dispatch ceiling"]
-    IMR --> IMPIN["At-ceiling pin\n(ceiling final candidate)"]
-    IMR --> IMINH["Inherit\n(only if dispatcher known at/above ceiling)"]
-    IMR --> IMCLI["Exact CLI reviewer\n(selected pre-launch)"]
-  end
-
-  subgraph Gates
-    PG["Phase review gate\n(external)"] --> PGR["Configured exec target\n(gates.execTargets)"]
-    PGR --> PGT["Separate reviewer CLI\n(prefers another model family;\nfalls back with a warning)"]
-
-    LG["Lifecycle / final gate"] --> LGR["Configured exec target\n(gates.execTargets)"]
-    LGR --> LGT["Separate reviewer CLI\n(never replaced by self-review;\nfalls back with a warning)"]
-    LGT -. may spawn .-> LGN["Nested managed\nreviewer child inside gate"]
-  end
-```
+=== "Diagram"
+
+    ![Review flavors: planning self-review inherits the planning parent; implementation self-review resolves the dispatch ceiling to an at-ceiling pin, inherit, or an exact CLI reviewer; phase and lifecycle gates run a separate reviewer CLI from a configured exec target, and the lifecycle gate's reviewer CLI may spawn a nested reviewer child](/diagrams/review-flavors-light.svg)
+    ![Review flavors: planning self-review inherits the planning parent; implementation self-review resolves the dispatch ceiling to an at-ceiling pin, inherit, or an exact CLI reviewer; phase and lifecycle gates run a separate reviewer CLI from a configured exec target, and the lifecycle gate's reviewer CLI may spawn a nested reviewer child](/diagrams/review-flavors-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart TD
+      subgraph Planning
+        PL["Planning-phase\nartifact self-review"] --> PLR["Inherit planning parent"]
+        PLR --> PLT["Parent model\n(root already at/above ceiling)"]
+      end
+
+      subgraph Implementation
+        IM["Root-owned phase\nself-review"] --> IMR["Resolve dispatch ceiling"]
+        IMR --> IMPIN["At-ceiling pin\n(ceiling final candidate)"]
+        IMR --> IMINH["Inherit\n(only if dispatcher known at/above ceiling)"]
+        IMR --> IMCLI["Exact CLI reviewer\n(selected pre-launch)"]
+      end
+
+      subgraph Gates
+        PG["Phase review gate\n(external)"] --> PGR["Configured exec target\n(gates.execTargets)"]
+        PGR --> PGT["Separate reviewer CLI\n(prefers another model family;\nfalls back with a warning)"]
+
+        LG["Lifecycle / final gate"] --> LGR["Configured exec target\n(gates.execTargets)"]
+        LGR --> LGT["Separate reviewer CLI\n(never replaced by self-review;\nfalls back with a warning)"]
+        LGT -. may spawn .-> LGN["Nested managed\nreviewer child inside gate"]
+      end
+    ```
 
 The dotted branch marks the only flavor that may **spawn a nested managed
 reviewer child** inside the gate exec target: the lifecycle/final gate.

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.3.14",
-  "docs-config": "0.3.14",
-  "docs-theme": "0.3.14",
-  "docs-transforms": "0.3.14"
+  "cli": "0.3.15",
+  "docs-config": "0.3.15",
+  "docs-theme": "0.3.15",
+  "docs-transforms": "0.3.15"
 }

package/assets/templates/docs-app-fuma/app/[[...slug]]/page.tsx

@@ -1,11 +1,23 @@
-import { DocsPage, Mermaid, Tab, Tabs } from '@open-agent-toolkit/docs-theme';
+import {
+  DocsPage,
+  Mermaid,
+  Tab,
+  Tabs,
+  ZoomImage,
+} from '@open-agent-toolkit/docs-theme';
 import defaultComponents from 'fumadocs-ui/mdx';
 import type { Metadata } from 'next';
 import { notFound } from 'next/navigation';
 
 import { source } from '@/lib/source';
 
-const mdxComponents = { ...defaultComponents, Mermaid, Tab, Tabs };
+const mdxComponents = {
+  ...defaultComponents,
+  Mermaid,
+  Tab,
+  Tabs,
+  img: ZoomImage,
+};
 
 type PageProps = {
   params: Promise<{ slug?: string[] }>;

package/assets/templates/docs-app-fuma/app/globals.css

@@ -3,6 +3,7 @@
 @import 'fumadocs-ui/css/preset.css';
 
 @source '../node_modules/fumadocs-ui/dist/**/*.js';
+@source '../node_modules/@open-agent-toolkit/docs-theme/dist/**/*.js';
 
 /* remark-github-blockquote-alert callout styling (fd-* design tokens) */
 @layer base {

package/dist/release/public-package-contract.js

@@ -149,7 +149,7 @@ const PUBLIC_PACKAGE_CONTRACTS = [
         requiredPackedTextFiles: [],
         forbiddenPathPatterns: [...COMMON_FORBIDDEN_PATH_PATTERNS],
         versionPolicyAdditionalRoots: [],
-        versionPolicyIgnorePatterns: [],
+        versionPolicyIgnorePatterns: ['src/**/*.test.ts'],
     },
     {
         workspaceDir: 'packages/docs-transforms',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.3.14",
+  "version": "0.3.15",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -34,7 +34,7 @@
     "ora": "^9.0.0",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.3.14"
+    "@open-agent-toolkit/control-plane": "0.3.15"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",