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.
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.
3. Skills ecosystem (docs/assets/diagram-skills-ecosystem.jpg)
48 skills as of 2026-06-13 (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.jpgpredates 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 toskills/catalog.jsonas 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).
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.
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.
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.
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).
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).
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.