# Studio

`vclaw studio` is the human-friendly planning front door for VideoClaw.

It does not replace the low-level CLI. It builds a production plan from a goal,
then shows the exact commands and artifacts that will be used.

## Start With A Dry Run

```bash
vclaw studio --dry-run --goal create-video --project demo --intent "Create a 30 second product ad"
```

The Phase 1 Studio command is plan-only. It does not call providers, run FFmpeg,
or spend credits.

## Goals

| Goal | Use When |
|---|---|
| `create-video` | Original video from a brief |
| `copy-reference` | Adapt a reference video or ad |
| `presenter-video` | Bunty, Nex, Davendra, or generic presenter episode |
| `music-video` | Multi-shot cinematic or music video planning |
| `character-video` | Identity-locked character ad or episode (locked Go Bananas / Flow character) |
| `ugc-campaign` | Belief-driven UGC campaign |
| `brand-campaign` | Brand DNA from a website URL → seed the brief → plan an on-brand campaign |
| `existing-project` | Continue a project and get next actions |
| `review-regenerate` | Review, reroll, or approve scenes |
| `publish-deliver` | Build and publish a portal |

`brand-campaign` (aliases: `brand`, `website`) takes the site URL via `--input`; its
plan chains `brand-extract` → `brief --from-brand-dna` → `storyboard` → `readiness`.

<p align="center"><img src="./assets/diagram-studio-goals.jpg" alt="Studio goals to commands — the ten vclaw studio goals route through the studio planner (recipes.ts) into a recipe of the underlying vclaw video commands: init, brief, storyboard, assets, readiness, plan, produce/execute, assemble, portal, publish-preview" width="100%" /></p>

## Examples

```bash
vclaw studio --dry-run --goal presenter-video --project demo --input deck.pdf --client "Acme"
vclaw studio --dry-run --goal music-video --project dhuaan --duration 60
vclaw studio --dry-run --goal existing-project --project demo
vclaw studio --dry-run --goal publish-deliver --project demo --client "Acme"
vclaw studio --dry-run --goal brand-campaign --project demo --input https://acme.com
```

Use `--write-session` to persist the planned handoff under the project:

```bash
vclaw studio --dry-run --goal presenter-video --project demo --input deck.pdf --write-session
```

This writes `projects/<slug>/artifacts/studio-session.json`.

## Execution (`--execute`)

By default Studio is plan-only — it prints the commands but runs nothing. Add
`--execute` to **run the emitted plan** step-by-step. Studio does not re-implement
any orchestration; it shells out to the same `vclaw video …` commands the plan
already lists, so the plan stays the source of truth.

```bash
vclaw studio --execute --goal existing-project --project demo
```

### Three modes (you choose at run time)

| Command | What runs | Credits |
|---|---|---|
| `--execute` | **Dry.** Free steps + spend steps with `--dry-run`. Pauses at the real director storyboard gate (surfaced as a `blocked` step). | none |
| `--execute --confirm-spend` | **Real render, human-gated.** Promotes the dry spend steps to real (strips `--dry-run`). The render still needs the storyboard approved out-of-band — the runner does not auto-approve. | spends on approval |
| `--execute --confirm-spend --auto-approve-storyboard` | **Unattended render.** Also sets `VIDEOCLAW_APPROVE_STORYBOARD`, so a single command runs the whole pipeline through the real render with no human checkpoint. | spends unattended |

Credit-safety guarantees:

- The default `--execute` is **provably dry** — a spend subcommand
  (`execute`/`produce`/`seedance-register-assets`/`batch-submit`/`publish-preview`/`publish-portal-index`)
  lacking `--dry-run` is **refused** (`blocked-spend`), and the dry steps keep `--dry-run`.
- Real spend requires the **explicit** `--confirm-spend`; unattended real spend
  requires **both** `--confirm-spend` and `--auto-approve-storyboard` (never accidental).
- Without `--auto-approve-storyboard` the runner strips `VIDEOCLAW_APPROVE_STORYBOARD`
  from the child env, so the director gate keeps blocking a real render.
- Fails fast — a blocked or failed step stops the run with no partial spend.
- `--from-step <id>` resumes after you have approved the storyboard out-of-band.

The result is reported under an `execution` block in the JSON output: the `mode`
(`dry` / `confirm-spend` / `auto-render`), per-step `status` (`ran` /
`blocked-spend` / `blocked` / `failed` / `skipped-before-resume`), the
`stopReason`, a `hint` (in dry mode) on how to render for real, and any surfaced
storyboard `markdownPath`.

## Agent Contract

When stdout is piped, Studio outputs JSON. Progress and warnings stay out of
stdout. The plan-only default performs no provider work; `--execute` runs only
dry-run/free steps and pauses at approval/spend points (see above).