videoclaw 3.0.0-alpha.1

package/docs/DIAGRAMS_SOURCE.md

@@ -0,0 +1,347 @@
+# 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`)
+
+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.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 (20)"]
+    direction TB
+    CON["concierge<br/>(canonical front door)"]:::entry
+    CON --> CB["clawbot (alias)"]
+    SM["studio-mode"]
+    Pipeline["pipeline"]
+    Worker["worker"]
+    DeepInterview["deep-interview"]
+    Deepsearch["deepsearch"]
+    Review["review"]
+    BuildFix["build-fix"]
+    AISlop["ai-slop-cleaner"]
+    SkillsAuditor["skills-auditor"]
+    WebClone["web-clone"]
+    ImprovementRun["improvement-run"]
+    Graphify["graphify"]
+    Skill["skill"]
+    Help["help"]
+    Doctor["doctor"]
+    Note["note"]
+    ConfigNotif["configure-notifications"]
+    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
+```

package/docs/DIRECTOR_BLUEPRINT.md

@@ -0,0 +1,94 @@
+# Director Blueprint (AI Animation Director)
+
+The **Project Blueprint** is VideoClaw's *director layer* — a project-level visual
+bible that locks the film language **above** the existing execution layer
+(`cinematography.ts`, `filmmaking-prompts.ts`). It is distinct from the
+[Story Bible](STORY_BIBLE.md): the story bible tracks **continuity** (cast,
+settings, props, scene timeline); the blueprint tracks **visual direction** (color
+system, lighting grammar, per-character camera language, environment atmosphere,
+the project camera bible).
+
+> Design principle (from the source "AI Animation Director" system): the blueprint
+> is *"a director layer ABOVE your existing camera reference, not a replacement for
+> it."* It does not change how prompts are composed — it locks the decisions they
+> express.
+
+## Generate it (the `ai-director` skill)
+
+Authoring a blueprint is a creative task, so it lives in the **`ai-director`
+skill** (`skills/ai-director/SKILL.md`), which runs the staged director
+master-prompt (intake → 8 sections) and emits a `project-blueprint.json`. The CLI
+is the deterministic half: it validates, normalizes, and persists that JSON, then
+the prompt composer consumes it.
+
+The eight locked sections:
+
+1. **Visual identity** — aesthetic, influences (what's borrowed), texture, scale, time-of-day, one-line thesis.
+2. **Master color system** — 4–6 named colors (where + emotional function), Kelvin range, warm/cool shift meaning, contrast, saturation, optional `gradeId`.
+3. **Lighting grammar** — key direction, quality, shadow strategy, practicals, and three signature setups (intimate / tension / hero).
+4. **Character blueprint** — per character: silhouette identity, signature detail, 3-color palette, costume, what the design communicates, a voice profile, and **power / vulnerability / signature camera framing**.
+5. **Environment blueprint** — per location: emotional function, visual anchors, scale, light/color, and the **5 sensory words** (1 smell + 1 texture + 1 sound + 2 feelings).
+6. **Project camera bible** — camera relationship, when it moves vs. locks, 3 dominant shots, rare shots, primary angles/movements, **forbidden movements**, focal feel, depth strategy, and **the one rule the camera must never break**.
+7. **Performance rules** — acting style, dialogue energy, silence usage, intensity scale, casting pattern, what to avoid.
+8. **Output notes** — runtime, aspect ratio, motion style, editing rhythm, 8–12 vibe keywords.
+
+## CLI
+
+```bash
+# Validate + persist a skill-authored blueprint JSON (writes artifacts/project-blueprint.json):
+vclaw video director-blueprint --project <slug> --from-json <path> --write
+
+# Print the persisted blueprint:
+vclaw video director-blueprint --project <slug> --show
+```
+
+`director-blueprint` only validates and stores — generation is the skill's job.
+Validation is lenient on sub-fields (missing strings → empty) but strict on the
+eight required sections, throwing a single `invalid_flag_value` error listing all
+missing sections. The artifact is managed + history-tracked
+(`artifacts/project-blueprint.json`, schema
+`schemas/video/artifacts/project-blueprint.schema.json`).
+
+## How it's consumed
+
+`vclaw video filmmaking-prompts` **auto-reads** `artifacts/project-blueprint.json`
+(graceful — absent → byte-identical legacy output) and enriches **every** scene
+packet:
+
+- A compact, prose-only addendum is appended **after** the canonical 10-block
+  Seedance body (so the block-order contract is preserved) and uses no Kelvin/hue
+  numerals (so the `prompt-lint` prose-register check passes):
+
+  ```
+  DIRECTOR — Palette: <master colors>. Look: <contrast/saturation + vibe keywords>.
+  Lighting: <scene's signature setup>. Subject: <present character — silhouette,
+  signature detail; signature framing>. Atmosphere: <5 sensory words>.
+  Rule: <the one rule>.
+  ```
+
+- The scene's signature lighting setup is selected from its text (tension words →
+  `tension`, reveal/hero words → `hero`, else `intimate`).
+- The camera bible's **forbidden movements** are validated against each scene's
+  prompt; a `forbidden-camera-movement` issue is raised per hit.
+- When the bible forbids `handheld`, the `storyboard-grid-reference` packet also
+  drops its default "Handheld camera moments may be used to boost realism"
+  boilerplate — so the prompt never instructs a forbidden move (and the checker
+  never flags its own boilerplate). No blueprint / handheld allowed → the clause
+  stays, byte-identical to legacy.
+
+The underlying camera/lighting vocabulary lives in `src/video/shot-grammar.ts`
+(shot-size emotional taxonomy, movement grammar with Seedance syntax, the
+sensory-words rule, the two-temperature technique helper in `cinematography.ts`).
+See `references/video/camera-bible.md` and
+`references/video/ai-director-blueprint.md`.
+
+## Modules
+
+| File | Role |
+|---|---|
+| `skills/ai-director/SKILL.md` | The staged director master-prompt (generation) |
+| `src/video/project-blueprint.ts` | Artifact type + validate/write/read |
+| `src/video/blueprint-prompt.ts` | Render the DIRECTOR addendum + forbidden-move detection |
+| `src/video/shot-grammar.ts` | Camera-bible shot/angle/movement taxonomy + sensory-words rule |
+| `src/video/filmmaking-prompts.ts` | Consumes the blueprint into every scene packet |
+| `schemas/video/artifacts/project-blueprint.schema.json` | Canonical artifact schema |

package/docs/GENERATION_TELEMETRY.md

@@ -0,0 +1,81 @@
+# Generation Telemetry
+
+`videoclaw` records generation telemetry as project events. The goal is
+simple: every provider submission and poll should leave enough machine-readable
+evidence to answer what route ran, how many tasks were sent, what it cost when
+the provider reports cost, how long it took, and how many outputs were ingested.
+
+## Where it is recorded
+
+Telemetry is appended to the existing event ledger:
+
+```text
+projects/<slug>/events/events.jsonl
+```
+
+Each record uses event type:
+
+```text
+generation.telemetry.recorded
+```
+
+The payload schema is versioned with `schemaVersion: 1`.
+
+## What is captured
+
+Each telemetry payload can include:
+
+1. `projectSlug`, `routeId`, `operationKind`, `status`, and `dryRun`
+2. `taskCount` and `sceneIndices`
+3. execution config such as aspect ratio, resolution, audio flag, output count,
+   average duration, prompt word count, and reference counts
+4. `externalJobId` when live submission or polling exposes one
+5. `outputsIngested` after polling
+6. provider-reported cost fields: `usd` and/or `creditsCharged`
+7. `generationTimeSec` when provider output exposes it
+8. `issues` for blocked, failed, or warning-bearing runs
+
+Dry-runs are recorded as telemetry, but they are not used as historical cost
+samples.
+
+## Cost-estimate integration
+
+`vclaw video cost-estimate` still uses the static Seedance defaults when there
+is no historical provider-reported USD data.
+
+When completed `seedance-direct` telemetry exists with both `cost.usd` and
+`taskCount`, project estimates can switch to:
+
+```json
+{
+  "estimateSource": "historical-telemetry",
+  "telemetry": {
+    "sampleCount": 1,
+    "matchedRouteId": "seedance-direct",
+    "averageSeedancePerSceneUsd": 0.5,
+    "lastRecordedAt": "2026-05-03T12:00:00.000Z"
+  }
+}
+```
+
+Credits are recorded but not converted to USD. Do not add a conversion unless
+the route has an explicit, verified conversion contract.
+
+## Operator guidance
+
+Use telemetry to tune estimates and investigate provider behavior, not to
+replace the execution report. The execution report remains the canonical
+artifact for the latest execution state; telemetry is the longitudinal ledger
+for submissions, polls, costs, durations, and failures.
+
+## Public helpers
+
+The package exports helpers for integration code:
+
+1. `appendGenerationTelemetry`
+2. `readProjectGenerationTelemetry`
+3. `readPortfolioGenerationTelemetry`
+4. `buildGenerationTelemetryFromReport`
+5. `buildGenerationTelemetryFromPoll`
+6. `findHistoricalSeedanceCostTelemetry`
+7. `extractProviderMetrics`

package/docs/IMPROVE_PROMPT.md

@@ -0,0 +1,76 @@
+# Improve-videoclaw prompt
+
+A reusable, Fable-5-tuned prompt for driving a comprehensive, high-leverage improvement
+pass over the whole `videoclaw-v3` codebase. Authored with the `prompting-fable-5` skill
+(give-the-reason, scope-guard tuned for improvement-not-churn, parallel-subagent fan-out,
+progress-grounding, a plan-gate checkpoint, fresh-context self-verification, no
+echo-your-reasoning).
+
+## How to run
+
+- Set effort to **xhigh** — this is hardest-range, end-to-end work.
+- Default shape is **discover → plan-gate → implement end-to-end**: it pauses once for
+  you to approve the ranked plan, then runs. For audit-only, replace the checkpoint
+  paragraph with a hard stop after the findings.
+
+## Prompt
+
+```text
+You're working on videoclaw-v3 (the `vclaw` CLI; npm package `videoclaw`) — a
+TypeScript/Node 20, strict-NodeNext-ESM, multi-provider video pipeline CLI targeting
+Veo (Flow/UseAPI/Omni), Seedance, Runway, and Dreamina. It's a solo-creator tool used
+to ship real client video work end-to-end: init → brief → storyboard → assets → review →
+publish, with an on-disk per-project folder as the source of truth and machine-readable
+JSON at every stage. I want you to make this codebase genuinely kick ass: more robust,
+more coherent, faster to work in, and harder to break — without changing what it does or
+relitigating its architecture decisions.
+
+Read first, then decide. Read CLAUDE.md, MERGE_PLAN.md, docs/ARCHITECTURE.md, the ADRs in
+docs/adr/, and the memory index at
+~/.claude/projects/-Users-davendrapatel-Documents-GitHub-videoclaw-v3/memory/MEMORY.md.
+These encode load-bearing decisions (no silent fallback across provider routes; on-disk
+project as source of truth; Seedance identity via Asset Library; director-mode approval
+gate; the review-state ladder; position-sensitive import.meta.url path math in handlers).
+Treat them as constraints, not suggestions — don't undo them.
+
+Then survey the whole project for the highest-leverage improvements. Use parallel
+subagents to explore independent areas concurrently (the CLI dispatch + handlers, the
+src/video/* domain modules, the provider transports/adapters, the schemas, the test
+suite, the docs, the smokes/guardrails) and keep working while they run; intervene if one
+goes off track. Look for: correctness bugs and silent-failure paths, missing or weak test
+coverage on critical seams (execution runtime, chain-from-prev, reference-budget
+preflight, the review-state ladder), schema/writer drift, inconsistent error handling,
+brittle path math, dead or duplicated code, gaps between docs and behavior, and developer-
+experience friction. Rank what you find by impact-over-effort and tell me the ranking
+before you start changing anything.
+
+This is an improvement task, but improvement is not churn. Make changes that raise
+correctness, robustness, test coverage, or clarity. Don't refactor for taste, don't
+introduce abstractions for hypothetical future needs, don't add error handling for cases
+that can't happen, and don't reformat files you aren't otherwise touching. Match the
+surrounding code's conventions exactly (kebab-case filenames, .js import extensions,
+2-space indent, machine-readable JSON output, node:test with assert/strict). When you add
+or change a CLI command or artifact, follow the full registration checklist in CLAUDE.md
+(handler + dispatch + schema + cli-schema COMMANDS + count assertion + test + README +
+docs/CLI_REFERENCE.md).
+
+Checkpoint before you commit to a direction: present your ranked findings and a short
+plan, and pause for me there — that's a real scope decision only I should make. After I
+approve the plan, proceed end-to-end without pausing for reversible steps. Only stop again
+for genuinely destructive or irreversible actions or a true change of scope.
+
+Hold a hard quality bar and verify against it. Build with `npm run build`; run `npm test`;
+run the relevant smokes and `npm run check:release-readiness-lite` as your pre-flight
+before declaring any batch of changes done. Verify your work with fresh-context verifier
+subagents against the specification and the existing tests — separate verification from
+the change, don't self-approve in the same pass. Every improvement ships with a test that
+would have caught the problem.
+
+Before reporting progress, audit each claim against an actual tool result from this
+session: if tests fail, show the output; if a check was skipped, say so; state only what
+you can point to evidence for. Don't claim a smoke passed unless you ran it.
+
+When you finish, lead with the outcome — what's measurably better and how you proved it —
+then the supporting detail. Write the summary for someone who didn't watch you work: plain
+sentences, each file or command its own clause, no working shorthand.
+```