baz

Create professional motion graphics and videos from the terminal. AI-powered composition with multi-track layering, choreography, voiceovers, and Lambda rendering. Gated 5-phase workflow ensures quality.

# baz CLI — Mandatory Video Generation Workflow

Use this skill when the user wants to create, edit, or export videos using the Bazaar CLI (`baz`).

**This is a GATED workflow.** You MUST complete each phase in order. Do NOT skip phases. Do NOT declare "done" until the completion checklist at the bottom passes.

---

## Getting Started (New Agents)

If you don't have a Bazaar account or API key yet, register programmatically:

```bash
# 1. Discover what Bazaar can do
curl https://bazaar.it/api/v1/capabilities

# 2. Register (one POST, no human needed)
curl -X POST https://bazaar.it/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{"email":"your-agent@example.com","name":"My Agent"}'
# Returns: api_key, auth header name, quickstart steps, endpoint URLs

# 3. Save your API key — authenticate all future requests with:
#    -H "x-api-key: <your-api-key>"

# 4. Check pricing before you start
curl https://bazaar.it/api/v1/pricing

# 5. Install the CLI
npm install -g bazaar.it
baz auth login <your-api-key>
```

**Balance starts at $0.** When you hit a paid operation, you'll get HTTP 402 with a `top_up_url` in the response body. Call `POST /api/v1/top-up` with `{"amount_cents": 500}` (minimum $5) to get a Stripe checkout URL.

**Shortcut:** If your human creates an account at bazaar.it, they get $4 to start with. Ask them to grab an API key from the dashboard and you can skip straight to step 5.

Already have an API key? Skip to Phase 1.

---

## When to Use

- User asks to create, edit, or export videos via CLI
- User wants to automate video generation
- User mentions "baz", "bazaar CLI", or "video generation from terminal"

## When to Use `baz prompt` vs Spar

- **Direct `baz prompt`** — Scene creation, edits, full agent orchestration
- **`baz prompt --spar`** — Planning-only conversation (no timeline mutations)

---

## Phase 1: Context (REQUIRED — do NOT skip)

You MUST set project context BEFORE generating any scenes. This gives the composition agent the information it needs to produce correct output on the first try.

### Minimum context required:
1. **Goal** — What is this video for? Who is the audience? What should they feel/do?
2. **Requirements** — Specific, verifiable things the video must contain
3. **Brand** — Colors, fonts, logo placement, visual style

```bash
# Create or select project
baz project create --name "Descriptive Name - Date/Purpose" --json
# OR
baz project use <id>

# Set goal (be specific — audience, purpose, desired outcome)
baz context add "Create 45-60 second feature announcement for [Product]. \
Audience: [who]. Key value: [what they get]." --label "goal"

# Add requirements (each one should be independently verifiable)
baz context add "Show [specific feature interaction]" --label "requirement"
baz context add "Include CTA: '[specific text]'" --label "requirement"
baz context add "Total duration: [range]" --label "requirement"

# Set brand guidelines
baz context add "Brand: [Name]. Primary [hex], accent [hex]. Font: [name]. \
[Logo placement]. [Visual style notes]." --label "brand"
```

### Verify context is set:
```bash
baz context list --json
```

**Gate:** Do NOT proceed to Phase 2 until `baz context list` shows at least one goal, one requirement, and one brand entry.

---

## Phase 2: Generate

Now prompt the agent to create scenes. You can use one big prompt or multiple scene-by-scene prompts.

```bash
# Option A: One comprehensive prompt
baz prompt "Create a video with: [scene 1 description], [scene 2], ..." --stream-json

# Option B: Scene-by-scene (more control)
baz prompt "Scene 1 (5s): Dark gradient intro, logo top-left, title slides up" --stream-json
baz prompt "Scene 2 (7s): Problem statement with mock UI..." --stream-json
baz prompt "Scene 3 (18s): Feature walkthrough..." --stream-json
```

Tips:
- Include duration in each prompt
- Be specific about animations, colors, layout
- Reference brand context set in Phase 1

### Choreography (REQUIRED for 3+ scene videos)

For videos with 3 or more scenes, plan choreography BEFORE generating. This prevents the "lockstep slideshow" pattern where all layers swap at the same frame boundary.

#### Actor Planning Template

Before prompting, plan your actors:

| Actor | Track | Lifetime | Role |
|-------|-------|----------|------|
| Background | 0 | Full duration | Evolving gradient, particles |
| Hero | 1 | 60-80% | Main UI, enters, demotes to corner, returns |
| Supporting | 1-2 | 20-40% | Cards/charts, appear during hero demotion |
| Text | 2+ | 10-30% | Headlines, arrive at beat points, explicit exits |

#### 5 Prompt Enrichment Rules

1. **Every content prompt includes exit instructions** (exempt: persistent backgrounds, final CTA)
2. **Prefer ONE background** on Track 0 for the full video duration
3. **Every overlay prompt includes position and size** — scenes that share screen time must not share screen space
4. **Specify spring animation** for hero elements (`spring() for hero entrance`)
5. **Include energy level hints** in prompts ("high energy entrance", "calm sustained section")

#### GOOD Example — context injection + one natural prompt:
```bash
baz context add "CHOREOGRAPHY: Every overlay scene must specify its position and size. \
  Use spring() for hero elements. Every non-final scene must have exit animations. \
  Prefer one continuous background." --label "instructions"

baz prompt "Create a 15-second product demo: dark theme intro with logo, \
  feature showcase with 3 cards, area chart showing growth, and a CTA. \
  Brand: #6366f1 purple, #10b981 green, Inter font." --stream-json
```

ONE natural prompt. The composition agent handles decomposition into tracks + spatial layout internally based on choreography context.

---

## Phase 3: Review & Verify (REQUIRED — NEVER skip)

After generation, you MUST run both review and verify. This is not optional.

### Step 1: Review
```bash
baz review --json
```

Read the output. Compare every requirement from Phase 1 against what was generated.

### Step 2: Verify
```bash
baz verify --criteria "requirement 1,requirement 2,requirement 3" --json
```

Pass ALL requirements from Phase 1 as comma-separated criteria. The verify command checks each one.

### Interpret results:

```json
{
  "passedAll": true,
  "results": [
    { "criteria": "...", "passed": true },
    { "criteria": "...", "passed": false, "reason": "..." }
  ]
}
```

**Gate:** If `passedAll: false`, you MUST proceed to Phase 4. Do NOT export. Do NOT declare done.

---

## Phase 4: Iterate (REQUIRED if Phase 3 fails)

Fix every failing criteria. Then re-verify.

```
LOOP:
  1. Read failing criteria from Phase 3
  2. Fix with: baz prompt "Fix: [specific issue]" --stream-json
  3. Re-run: baz review --json
  4. Re-run: baz verify --criteria "req1,req2,req3" --json
  5. If passedAll: false → GOTO 1
  6. If passedAll: true → proceed to Phase 5
```

Do NOT exit this loop until `passedAll: true`.

---

## Phase 5: Export (only if requested)

Only export if the user explicitly asked for a rendered video AND Phase 3/4 passed.

```bash
baz export start --wait --json
```

---

## Command Quick Reference

| Command | Purpose |
|---------|---------|
| `baz project create --name "..." --json` | Create new project |
| `baz project use <id>` | Set active project |
| `baz context add "..." --label "goal"` | Set project goal |
| `baz context add "..." --label "requirement"` | Add verifiable requirement |
| `baz context add "..." --label "brand"` | Set brand guidelines |
| `baz context list --json` | View all context entries |
| `baz prompt "..." --stream-json` | Generate or edit scenes |
| `baz prompt "..." --spar` | Planning-only conversation (no edits) |
| `baz review --json` | Get full project state for review |
| `baz verify --criteria "..." --json` | Verify specific criteria pass |
| `baz scenes list --json` | List all scenes |
| `baz export start --wait --json` | Render final video |

## Error Handling

| Category | Action |
|----------|--------|
| `tran