# Diagrams Source

This file is the **canonical source** for the diagrams used in `README.md`,
`docs/ARCHITECTURE.md`, and other top-level docs. The Mermaid blocks below
are the human-readable, version-controlled source of truth. The
corresponding JPGs in `docs/assets/diagram-*.jpg` are rendered from these
sources (via Go Bananas Pro `workflow-diagrams` skill, or any Mermaid
renderer).

If a diagram looks out of date in the rendered JPG, update the Mermaid
here first, then regenerate the JPG.

---

## 1. Architecture (`docs/assets/diagram-architecture.jpg`)

Shows the request flow from operator/agent through the CLI into the
domain layer, the artifact/event ledger, the execution runtime, and the
adapter tier. Plus the two opt-in sidecars (`vclaw-cli/` Bun package and
`skills/video-replicator/scripts/` Python pipeline) that the main
TypeScript repo invokes via subprocess when needed.

```mermaid
flowchart TD
  Operator(["Operator / AI Agent"]) --> CLI["vclaw CLI<br/>(src/cli/vclaw.ts)"]
  CLI --> Domain["Domain modules<br/>(src/video/*.ts)"]
  Domain --> Artifacts[("artifacts/<br/>JSON canonical")]
  Domain --> Checkpoints[("checkpoints/<br/>stage approvals")]
  Domain --> Events[("events/events.jsonl<br/>append-only ledger")]
  Domain --> Runtime["Execution runtime<br/>(execution-runtime.ts)"]
  Runtime --> Adapter["Adapter layer<br/>(provider-adapter-runner.ts)"]
  Adapter --> Native["Native in-process<br/>native-veo · native-seedance · native-runway"]
  Adapter --> Shim["Command shim<br/>(VCLAW_*_SUBMIT_CMD)"]
  Adapter --> Custom["Custom adapter binary<br/>(VCLAW_*_ADAPTER)"]
  Native -.optional sidecar.-> VclawCli["vclaw-cli/<br/>Bun · Google Flow + UseAPI"]
  Domain -.optional sidecar.-> Python["skills/video-replicator/scripts/<br/>Python 3.10+ · 122 modules"]

  classDef entry fill:#d4ed5b,stroke:#1a1815,color:#1a1815,stroke-width:2px
  classDef core fill:#1a1815,stroke:#1a1815,color:#faf8f5
  classDef store fill:#f0ece6,stroke:#7a756d,color:#1a1815
  classDef sidecar fill:#fff,stroke:#c4450c,color:#c4450c,stroke-dasharray: 5 3
  class Operator entry
  class CLI,Domain,Runtime,Adapter,Native,Shim,Custom core
  class Artifacts,Checkpoints,Events store
  class VclawCli,Python sidecar
```

---

## 2. Provider routing (`docs/assets/diagram-routing.jpg`)

Decision tree the dispatcher walks for each route. Hard-fails by design
if no path resolves — no silent fallback across materially different
provider paths.

```mermaid
flowchart TD
  Start(["Provider route selected<br/>(veo-useapi · seedance-direct ·<br/>runway-useapi · dreamina-useapi)"]) --> Q1{"VCLAW_*_ADAPTER<br/>env var set?"}
  Q1 -->|Yes| Custom["✅ Custom adapter binary<br/>stdin → JSON, stdout → JSON"]
  Q1 -->|No| Q2{"Built-in adapter<br/>supports route?<br/>(seedance-direct · veo-useapi ·<br/>runway-useapi · dreamina-useapi)"}
  Q2 -->|No| Fail1["❌ Hard fail<br/>no silent fallback"]
  Q2 -->|Yes| Q3{"VCLAW_*_SUBMIT_CMD<br/>set?"}
  Q3 -->|Yes| Shim["✅ Command shim<br/>through built-in adapter"]
  Q3 -->|No| Q4{"Native creds available?<br/>SUTUI_API_KEY (seedance) ·<br/>local vclaw-cli (veo) ·<br/>USEAPI_API_TOKEN (runway)"}
  Q4 -->|Yes| Native["✅ Native in-process transport"]
  Q4 -->|No| Fail2["❌ Hard fail"]

  classDef decision fill:#d4ed5b,stroke:#1a1815,color:#1a1815
  classDef terminal fill:#1a1815,stroke:#1a1815,color:#faf8f5
  classDef fail fill:#c4450c,stroke:#1a1815,color:#faf8f5
  class Q1,Q2,Q3,Q4 decision
  class Custom,Shim,Native,Start terminal
  class Fail1,Fail2 fail
```

---

## 3. Skills ecosystem (`docs/assets/diagram-skills-ecosystem.jpg`)

38 skills as of 2026-06-25 (an earlier 2026-06-10 cull removed 12 generic
workflow skills that duplicated the operator's global plugin set — autopilot,
ralph/ralph-init/ralplan, team, cancel, trace, hud, git-master, code-review,
security-review, omx-setup; the catalog has since grown with new video skills),
grouped by purpose. The current canonical source is `skills/catalog.json` —
this diagram is illustrative.

> **Note on the rendered JPG:** the current `diagram-skills-ecosystem.jpg`
> predates the 2026-06-10 workflow-skill cull (and its header count was
> already off by one). A v3 regeneration was attempted earlier and produced
> WORSE artifacts (hallucinated headers and misplaced cards), so the v2
> render is kept. The footnote in the JPG already directs readers to
> `skills/catalog.json` as the authoritative index; regenerate from the
> Mermaid above (Go Bananas Pro) the next time a clean render is achievable.

Two canonical entry points (highlighted): **`video-framework`** for
generic video requests (delegates to specialist children), and
**`brand-presenter`** for branded host/presenter videos (specialized
by bunty / davendra / nex profiles).

```mermaid
flowchart LR
  subgraph Video["Video & Production skills (28, incl. presenters)"]
    direction TB
    VF["video-framework<br/>(canonical entry)"]:::entry
    VF --> VS["video-storyboard"]
    VF --> VAT["video-analyze-template"]
    VF --> VCA["video-clone-ad"]
    VF --> MD["movie-director"]
    VF --> MSP["multi-shot-prompt"]
    VF --> UGC["ugc"]
    VF --> HG["higgsfield-generate"]
    VF --> VPO["video-portfolio-ops"]
    VF --> VPH["video-production-handoff"]
    VF --> VRR["video-release-readiness"]
    VF --> VRQ["video-review-ui-qa"]
    VF --> VP["video-post"]
    VF --> VTL["video-thumbnail-lab"]
    VF --> MR["motion-reel"]
    VF --> AID["ai-director"]
    VF --> AIF["ai-filmmaking"]
    VF --> BA["brand-agency"]
    VF --> CAD["character-ad"]
    CC["character-creator"] --> CL["character-library"]
    SP["seedance-prompts"]
    YA["youtube-audio"]
    VR["video-replicator<br/>(deprecated → video-framework)"]
  end

  subgraph Presenters["Presenter skills (brand-presenter + aliases)"]
    direction TB
    BP["brand-presenter<br/>(canonical entry)"]:::entry
    BP --> BUNTY["bunty (alias)"]
    BP --> DP["davendra-presenter (alias)"]
    BP --> NP["nex-presenter (alias)"]
  end

  subgraph Workflow["Workflow & dev skills (9)"]
    direction TB
    CON["concierge<br/>(canonical front door)"]:::entry
    CON --> CB["clawbot (alias)"]
    Deepsearch["deepsearch"]
    AISlop["ai-slop-cleaner"]
    SkillsAuditor["skills-auditor"]
    WebClone["web-clone"]
    ImprovementRun["improvement-run"]
    Graphify["graphify"]
    UIUX["ui-ux-pro-max"]
  end

  classDef entry fill:#d4ed5b,stroke:#1a1815,color:#1a1815,stroke-width:2px
```

---

## 4. Story Bible generation (`docs/assets/diagram-story-bible.jpg`)

The deterministic continuity bible. `story-bible.ts` derives one
machine-readable reference (cast, settings, props, scene timeline,
continuity notes) from the brief, the storyboard, and the character
profiles — purely, spending no credits and calling no providers. It is
auto-generated at storyboard-write time by every storyboard-producing
command (`video create`, `storyboard`, `clone-execute`,
`storyboard-from-clone`, `storyboard-review`, and
`director-preflight --apply-content-fixes`), recorded in the storyboard
checkpoint and the `artifact.storyboard.written` event, validated by
`doctor`, and consumed downstream to keep generation consistent across
scenes and regenerations.

```mermaid
flowchart TD
  Cmd(["Storyboard-producing command<br/>(create · storyboard · clone-execute ·<br/>storyboard-from-clone · storyboard-review ·<br/>director-preflight --apply-content-fixes)"]) --> Builder["story-bible.ts<br/>buildStoryBibleArtifact (deterministic)<br/>writeStoryBibleForProject"]
  Brief[("artifacts/brief.json")] --> Builder
  Storyboard[("artifacts/storyboard.json")] --> Builder
  Characters[("characters/characters.json<br/>character profiles + refs")] --> Builder
  Builder --> Bible[("artifacts/story-bible.json<br/>schemaVersion 1 · cast · settings ·<br/>props · scene timeline · continuity notes")]
  Bible --> Checkpoint[("storyboard checkpoint<br/>artifacts['story-bible'] · storyBiblePath event")]
  Bible --> Doctor["doctor validation<br/>(validateStoryBibleArtifact)"]
  Bible --> Downstream["Downstream continuity<br/>consistent generation across<br/>scenes / regenerations"]

  classDef entry fill:#d4ed5b,stroke:#1a1815,color:#1a1815,stroke-width:2px
  classDef core fill:#1a1815,stroke:#1a1815,color:#faf8f5
  classDef store fill:#f0ece6,stroke:#7a756d,color:#1a1815
  class Cmd entry
  class Builder,Doctor,Downstream core
  class Brief,Storyboard,Characters,Bible,Checkpoint store
```

---

## 5. Assemble pipeline (`docs/assets/diagram-assemble.jpg`)

The post-execution assembly stage order behind `vclaw video assemble`
(`assemble/assemble.ts` `assembleProject`). TTS narration is planned
first because its real per-scene `durationMs` drives the per-slide
segment durations (the `narration-fit` planner speeds the voice within a
natural tempo threshold, else loops/caps the visual bed). The pipeline
ends with `stitch` -> a non-dry-run `media-qc` pass that ffprobes every
clip plus the master, and emits the `assemble-report` artifact carrying
the QC block.

```mermaid
flowchart TD
  Assemble(["vclaw video assemble<br/>(assembleProject)"]) --> PDF["(opt) extractPdfSlides<br/>deck -> slide images"]
  PDF --> Title["(opt) generateTitleCard"]
  Title --> TTS["generateTts<br/>per-scene narration<br/>(real durationMs)"]
  TTS --> Fit["narration-fit<br/>planNarrationFit<br/>tempo · loopVideo · -t cap"]
  Fit --> Animate["animateSlide per slide<br/>segment durations from narration"]
  Animate --> Music["(opt) generateMusic<br/>background bed"]
  Music --> Stitch["stitch -> final MP4"]
  Stitch --> QC["media-qc (non-dry-run)<br/>runAssembleMediaQc<br/>ffprobe clips + master"]
  QC --> Report[("artifacts/assemble-report.json<br/>+ qc block<br/>(pass · warning · fail)")]
  QC -.surfaced as.-> Warnings["assemble warnings<br/>qc.&lt;code&gt;[scope]: message"]

  classDef entry fill:#d4ed5b,stroke:#1a1815,color:#1a1815,stroke-width:2px
  classDef core fill:#1a1815,stroke:#1a1815,color:#faf8f5
  classDef store fill:#f0ece6,stroke:#7a756d,color:#1a1815
  classDef sidecar fill:#fff,stroke:#c4450c,color:#c4450c,stroke-dasharray: 5 3
  class Assemble entry
  class PDF,Title,TTS,Fit,Animate,Music,Stitch,QC core
  class Report store
  class Warnings sidecar
```

---

## 6. Project lifecycle (`docs/assets/diagram-lifecycle.jpg`)

The canonical stage flow `init → brief → storyboard → assets → review → publish`,
with the `readiness → plan → produce`/`execute` runtime layer between assets and
review, and the director-mode preflight + approval gate sub-branch.

```mermaid
flowchart LR
    init([init]) --> brief([brief])
    brief --> sb([storyboard])
    sb --> ready{{readiness}}
    ready -->|storyboard mode| runPlan([plan / produce])
    ready -->|director mode| pre{{director-preflight<br/>content · refs · pronouns}}
    pre -->|hazards| fix[auto-fix or<br/>storyboard-review]
    fix --> pre
    pre -->|pass| gate{{approval gate<br/>VIDEOCLAW_APPROVE_STORYBOARD=1}}
    gate -.awaiting-approval.-> ops[(ops queue:<br/>needs-review)]
    gate -->|approved| runPlan
    runPlan --> execStatus([execute-status<br/>poll adapter])
    execStatus --> ingest[[ingest outputs]]
    ingest --> assets([assets])
    assets --> review([review])
    review --> publish([publish])
    execStatus -. operator .-> cancel([execute-cancel])
```

---

## 7. Obsidian daily operator loop (`docs/assets/diagram-obsidian-loop.jpg`)

The five-step circular operations loop the portfolio Obsidian export supports
(`docs/OBSIDIAN.md`).

```mermaid
flowchart LR
  change["1 · Make changes<br/>(brief · storyboard · produce · review ·<br/>publish · set-meta · approve)"] --> sync["2 · Sync vault<br/>(vclaw video sync-obsidian)"]
  sync --> dash["3 · Read Dashboard<br/>(Dashboard · Active · Health · Needs Review)"]
  dash --> triage["4 · Triage queue<br/>(Next Actions, urgency-ordered)"]
  triage --> meta["5 · Update metadata<br/>(set-meta · approve)"]
  meta -.loop.-> change

  classDef write fill:#d4ed5b,stroke:#1a1815,color:#1a1815,stroke-width:2px
  classDef read fill:#f0ece6,stroke:#7a756d,color:#1a1815
  class change,meta write
  class sync,dash,triage read
```

---

## 8. Obsidian vault layout (`docs/assets/diagram-obsidian-vault.jpg`)

The exported vault under `ops/obsidian/`: 14 dashboard notes, a seed-once
`Templates/` + `Views/`, and a `Projects/` folder with one note per project slug
(`docs/OBSIDIAN.md`).

```mermaid
graph TB
  vault["ops/obsidian/<br/>(vault root)"]
  vault --> dash["14 dashboard notes:<br/>Dashboard · Active · Needs Review · Blocked ·<br/>Complete · Metrics · Health · Next Actions ·<br/>Dependencies · Timeline · Trends · History ·<br/>Changes · Owner Workload"]
  vault --> templates["Templates/<br/>(seeded once)"]
  vault --> views["Views/<br/>(seeded once)"]
  vault --> projects["Projects/<br/>(one note per project slug)"]
  projects --> p1["&lt;slug&gt;.md"]
  projects --> p2["…"]

  classDef root fill:#d4ed5b,stroke:#1a1815,color:#1a1815,stroke-width:2px
  classDef container fill:#f0ece6,stroke:#7a756d,color:#1a1815
  classDef leaf fill:#1a1815,stroke:#1a1815,color:#faf8f5
  class vault root
  class templates,views,projects container
  class dash,p1,p2 leaf
```

---

## 9. Studio goals → commands (`docs/assets/diagram-studio-goals.jpg`)

The `vclaw studio` front door: each of the 10 goals (`src/video/studio/types.ts`)
resolves through the planner (`recipes.ts`) into a recipe of the underlying
`vclaw video …` commands. Plan-only by default; `--execute` shells out to those
same commands.

```mermaid
flowchart LR
  subgraph Goals["vclaw studio --goal …  (10 goals + short aliases)"]
    direction TB
    G1["create-video"]
    G2["copy-reference"]
    G3["presenter-video"]
    G4["music-video"]
    G5["character-video"]
    G6["ugc-campaign"]
    G7["brand-campaign"]
    G8["existing-project"]
    G9["review-regenerate"]
    G10["publish-deliver"]
  end
  Goals --> Planner{{"Studio planner<br/>recipes.ts → StudioPlan<br/>(plan-only; --execute shells out)"}}
  Planner --> R1([init · brief · storyboard])
  R1 --> R2([assets · readiness])
  R2 --> R3([plan · produce / execute])
  R3 --> R4([assemble])
  R4 --> R5([portal · publish-preview])

  classDef entry fill:#d4ed5b,stroke:#1a1815,color:#1a1815,stroke-width:2px
  classDef core fill:#1a1815,stroke:#1a1815,color:#faf8f5
  classDef decision fill:#f0ece6,stroke:#7a756d,color:#1a1815
  class Goals entry
  class Planner decision
  class R1,R2,R3,R4,R5 core
```