3D Breakdown

# 3D Breakdown Wiggly Repo

This Repo packages the recipe behind Wiggly's existing 3D Breakdown Format. It does not create a second renderer or a second creative pipeline.

## Send the link to an agent

You can send an agent only this Repo link.

The agent should ask:

1. `What brand or website is this for?`
2. `Do you want Guide Me or Turbo?`
3. `What should the video focus on?`

The agent asks one question at a time.

**Guide Me** shows each big step and waits for you.

**Turbo** makes the choices after you approve one clear run estimate. The estimate lists each provider step, its call count, its current cost, the total cost, and the expected time. Turbo covers one normal attempt per step. Retries still need a new yes.

The agent never asks for a budget. It never asks you to choose tools or models.

Before planning, watch the packaged FinalStraw reference first, then Grüns, Kiala Nutrition, and Theragun, and read `goldens.json`. FinalStraw is the canonical Style B reproducibility target. These references teach structure, not claims, shots, or copy to reuse.

## What it makes

1. Five story directions from website evidence.
2. One selected Style B script and scene.
3. One six-frame storyboard contact sheet.
4. Four full-quality 9:16 video endpoints: frames 1, 3, 4, and 6.
5. After separate approval, two coherent 10-second 480p clips with three readable visual beats each.
6. One Fish narration and one final 20-second MP4 rendered through `AdRenderSurface`.

The storyboard is a planning reference. Its small panel crops must never become video endpoints.
Your coding agent authors the story slate, script, and scene plan. The packaged prompt commands provide the exact contracts; imports validate them locally before any media call. No NVIDIA NIM account or separate LLM API key is required. Coding-agent usage still applies.

Extract the ZIP, enter its v3 directory, run npm install, then npm run smoke. For research, use the research object in public/format-repositories/three-d-breakdown-v1/fixtures/agent-cookie-gift.json as a structural example, not as facts to reuse. Write sourced brand, offer, audience, buyer moments, evidence receipts, and optional products with real URLs. Null is allowed for unavailable brand images; use empty arrays for unavailable optional facts. An existing Wiggly export also works.

## Commands

```bash
npm run format:three-d -- check --stage=plan
npm run format:three-d -- init --run=my-run --research=/absolute/path/research.json --subject=brand
npm run format:three-d -- prompt --run=my-run --stage=directions
# Read the saved prompt, then author directions.json with your coding agent.
npm run format:three-d -- directions --run=my-run --input=/absolute/path/directions.json
# Choose a direction, then author script.json using this prompt.
npm run format:three-d -- prompt --run=my-run --stage=script --direction=idea-1
npm run format:three-d -- script --run=my-run --direction=idea-1 --input=/absolute/path/script.json
# Review the script, then author plan.json using this prompt.
npm run format:three-d -- prompt --run=my-run --stage=plan --direction=idea-1
npm run format:three-d -- select --run=my-run --direction=idea-1 --input=/absolute/path/plan.json
npm run format:three-d -- validate --run=my-run
npm run format:three-d -- inspect --run=my-run
```

Failed imports do not advance the run. Correct the authored JSON and retry locally; there is no planning provider call. Once the scene is assembled, start a new run to change it so existing media and reviews stay intact.

Image commands always create one image:

```bash
npm run format:three-d -- image --run=my-run --kind=storyboard --approve-image
npm run format:three-d -- review --run=my-run --asset=storyboard --decision=approve
npm run format:three-d -- image --run=my-run --kind=anchor --frame=1 --approve-image
npm run format:three-d -- review --run=my-run --asset=anchor-1 --decision=approve
npm run format:three-d -- image --run=my-run --kind=anchor --frame=3 --approve-image
npm run format:three-d -- review --run=my-run --asset=anchor-3 --decision=approve
npm run format:three-d -- image --run=my-run --kind=anchor --frame=4 --approve-image
npm run format:three-d -- review --run=my-run --asset=anchor-4 --decision=approve
npm run format:three-d -- image --run=my-run --kind=anchor --frame=6 --approve-image
npm run format:three-d -- review --run=my-run --asset=anchor-6 --decision=approve
```

Each image command makes one attempt-specific file. Approve a good current result, or reject it with a useful reason and generate a replacement:

```bash
npm run format:three-d -- review --run=my-run --asset=anchor-4 --decision=reject --reason="The demonstrator identity drifted."
```

Video commands create one paid clip at a time:

```bash
npm run format:three-d -- video --run=my-run --clip=1 --approve-video
npm run format:three-d -- review --run=my-run --asset=clip-1 --decision=approve
npm run format:three-d -- inspect --run=my-run
npm run format:three-d -- video --run=my-run --clip=2 --approve-video
npm run format:three-d -- review --run=my-run --asset=clip-2 --decision=approve
npm run format:three-d -- inspect --run=my-run
```

If Replicate is still processing after the local wait ends, the runner saves the prediction ID instead of failing the clip. Run the same `video` command again to check and collect that exact job. A saved active job never requires another approval and never creates a replacement generation.

If clip 2 is creatively good but its meaningful action lands after the 16-second end-card boundary, retime the existing file locally instead of buying another generation:

```bash
npm run format:three-d -- retime-clip --run=my-run --clip=2 --action-seconds=6 --approve-local-retime
npm run format:three-d -- review --run=my-run --asset=clip-2 --decision=approve
```

The original provider file remains preserved. The retimed result requires a new review and makes no provider call.

Finish with one approved voice call and a local render:

```bash
npm run format:three-d -- check --stage=voice
npm run format:three-d -- voice --run=my-run --approve-voice
npm run format:three-d -- check --stage=final
npm run format:three-d -- render --run=my-run
npm run format:three-d -- inspect --run=my-run
npm run format:three-d -- finalize --run=my-run --approve-final
```

`render`, `inspect`, and `finalize` are local and make no provider calls. Regenerating any upstream media invalidates the old final report. Do not finalize just because rendering completed; watch the video first.

Compare the result with FinalStraw and at least one supporting reference before finalizing. A file can pass resolution, duration, and audio checks while still failing as an ad.

Never paste keys into prompts, files, run records, or chat. Add the required key names to `.env.local`.

## Important boundary

The official renderer remains `features/formats/three-d-breakdown/render.tsx`, consumed through `AdRenderSurface`. Do not rebuild it. The Repo runner writes the same `ThreeDBreakdownAdScene` contract that `/create`, preview, download, and share already understand.

---
name: three-d-breakdown-format
description: Use the official Wiggly 3D Breakdown recipe to plan and prepare a 20-second evidence-backed 3D explainer.
---

# 3D Breakdown Format

Use this skill when a user asks an agent to make, inspect, or improve a Wiggly 3D Breakdown.

## Start from one link

When the user sends only this Repo link:

1. Say: `I can make this ad for you.`
2. Ask: `What brand or website is this for?`
3. Wait for the answer.
4. Ask: `Do you want Guide Me or Turbo?`
5. Wait for the answer.
6. Research the site with your web tools.
7. Save the facts in `research.json` with the `StoredWebsiteResearchResult` shape shown by the research object in `fixtures/agent-cookie-gift.json`. Replace all fixture facts and URLs.
8. Ask: `What should the video focus on?`
9. Offer product, brand story, customer problem, custom idea, or `Pick for me`.
10. If the user picks product, ask which product in the next message.
11. Show the run estimate.
12. Ask: `Ready to start?`

Ask only one question in each message. Use short sentences and simple words. Never ask for a budget or spend limit. Never ask the user to pick a model, tool, or technical setting.

If you cannot browse the web, ask for a Wiggly research export. Do not ask for anything else in that message. Turn the research into the provided `StoredWebsiteResearchResult` input. Keep a source URL for each fact. Never invent a fact.

## Progress

Use this line during the run:

`Research → Story → Script → Images → Clips → Final`

Start every work update with `Step X of 6: Name`. Never send a work update without it. Add the current item when a step has more than one part:

- `Step 4 of 6: Images — Storyboard`
- `Step 4 of 6: Images — Key image 2 of 4`
- `Step 5 of 6: Clips — Clip 1 of 2`
- `Step 6 of 6: Final — Done`

Keep the update short. In Turbo, send an update after each step but do not ask a question unless blocked.

## Work modes

### Guide Me

- Show each big deliverable.
- Explain it in plain words.
- Ask for approval before the next big step.
- Ask before each paid call.
- Show all five story ideas.
- Let the user pick the idea.

### Turbo

- Pick the strongest story and creative choices.
- Show the run estimate before any provider call.
- `Ready to start?` is approval for one normal attempt at each listed step.
- Do not ask again during a clean run.
- Stop if work looks wrong, a tool fails, or a retry is needed.
- Explain the problem in one short note.
- Ask before any retry or replacement call.

## Run estimate

Before `Ready to start?`, check the current provider prices and show:

```text
Run estimate

- Story ideas and plan: your coding agent — no additional provider charge
- Storyboard: 1 image — about $X
- Key images: 4 images — about $X
- Video clips: 2 clips, 10 seconds each — about $X
- Voice: 1 voice track — about $X
- Final video: local render — $0

Total: about $X
Time: about X-Y minutes
```

Use current prices. Do not guess. If a price is not public, say `price not listed`. The estimate covers one attempt per item. A retry needs a new estimate and a new yes.

## Rules

- Read `requirements.json`, `inputs.json`, `pipeline.json`, `scene-contract.json`, `assets.json`, `goldens.json`, and `quality.json`.
- Watch FinalStraw first, then the supporting videos in `goldens/`. They show the creative bar; do not copy their brands, claims, shots, or wording.
- Use the packaged runner and the canonical Wiggly modules. Do not rebuild the renderer, timing model, prompt builders, or scene contract.
- Product focus requires a catalog product with a usable image. Brand and customer-problem stories do not require a product.
- Treat website research as evidence. A custom brief changes the creative focus but does not authorize new factual claims.
- In Guide Me, show the five story directions before selecting one. In Turbo, save all five and pick the strongest one.
- Validate the selected plan before any image call.
- In Guide Me, one explicit approval covers one image call only. In Turbo, the approved run estimate covers one attempt for each listed image. Never batch provider requests. Record a separate approve or reject review for every current artifact.
- In Guide Me, ask once before the two planned video clips. In Turbo, use the approved run estimate. Submit one clip at a time and inspect clip 1 before spending on clip 2.
- Generate one explicitly approved Fish narration only after both clips pass inspection.
- Render the final MP4 locally through the packaged Remotion entry and `AdRenderSurface`. Never rebuild or replace the renderer.
- Never print secret values. Report only missing key names.
- Fail loudly. Do not switch media providers, retry paid calls automatically, or hide an error. Fix validation errors in your own planning JSON and re-import locally; never bypass a validator.

## Agent loop

1. Run `check --stage=plan`.
2. Run `init` with the research you authored (or an existing Wiggly export) and the chosen story subject.
3. Follow the exact command sequence in README. Run `prompt --stage=directions`, read the saved prompt, author its JSON yourself, then import it with `directions --input`. Do not call a separate LLM or ask for an NVIDIA key.
4. In Guide Me, show all five directions and let the user choose. In Turbo, pick the strongest saved direction.
5. Run `prompt --stage=script --direction=idea-N`, author its JSON, and import with `script --direction=idea-N --input`. Review that script. Then run `prompt --stage=plan --direction=idea-N`, author its JSON, and import with `select --direction=idea-N --input`. Run `validate`. All these commands also need `--run`. Keep the same direction throughout.
6. Compare the selected direction with the production references. State the concrete hook, the job of the blue explanation world, the visible transformation, the product or subject carried through the story, and the final payoff. If any answer is vague, revise before an image call.
7. Let the user inspect the script, storyboard plan, image prompts, and CTA. The MVP runner does not edit these fields; if the plan is wrong, stop and start a new run from the saved research instead of spending on media.
8. In Guide Me, ask before each `image` command. In Turbo, use the approved run estimate.
9. Generate and review the storyboard first, then generate and review full-quality endpoint frames 1, 3, 4, and 6, one approved image call at a time. All six frames stay in one Style B blue/cyan blueprint-grid explanation world while camera, scale, props, and physical state change.
10. Run `inspect`.
11. After explicit approval, generate video clip 1, review it, then generate video clip 2. Each clip may use motivated cuts or transitions to deliver three readable visual beats, but it must keep the approved world and demonstrator identity.
    - If a clip is still processing, its Replicate prediction ID is saved. Run the same command again without new approval to check that job; never submit a replacement.
    - If a ready clip is wrong, reject the current attempt with a reason before explicitly approving one replacement generation.
    - Clip 2 must complete meaningful action by global second 16 because the final four seconds belong to the product and CTA.
    - If clip 2 is good but late, use the packaged local `retime-clip` command and review the retimed file instead of buying another generation.
12. Run `inspect` again and review `video-contact-sheet.jpg`.
13. Run `voice --approve-voice`, then `render`.
14. Run `inspect`, watch the final MP4, and compare it with at least two production references. Technical completion alone is not a pass.
15. Use `finalize --approve-final` only if the creative result is genuinely usable, then return the finalized MP4 to the user.

## Good result

- The story is understandable without knowing the brand.
- The first two seconds show a concrete product, customer tension, or false assumption. An abstract brand fact is not enough.
- Every factual claim maps to the saved website evidence.
- The five beats sound spoken, not like production notes or AI copy.
- The six-frame plan shows different physical actions in one coherent blue-grid CGI world. Object-only frames do not invent people.
- The blue world explains an invisible mechanism or change. It is not a decorative background.
- Every major narration beat causes a visible action, object change, or result.
- The approved product or subject remains recognizable through the world change and returns in the payoff.
- All four video endpoints are sharp, use the approved recurring subjects, and show the exact intended start or end state.
- Storyboard panel crops guide endpoint generation but never become Seedance inputs.
- Both 480p clips use three readable visual beats, follow the approved physical actions, and do not jump to another person, unapproved setting, or visual style.
- Renderer captions preserve the exact approved script words.
- Narration ends before the 20-second video ends and is not clipped.
- The final MP4 is 1080×1920, 20 seconds, contains exactly one audio stream, and preserves the approved two-clip story.
- A finished file that cannot credibly sit beside the Kiala and Theragun production references must not be finalized.

{
  "environment": {
    "REPLICATE_API_TOKEN": {
      "requiredFor": [
        "images",
        "video"
      ],
      "secret": true,
      "purpose": "Create the storyboard, four production endpoints, and later video clips."
    },
    "FISH_STUDIO_APIKEY": {
      "requiredFor": [
        "voice"
      ],
      "secret": true,
      "purpose": "Create the final narrator voice after the video gate opens."
    }
  },
  "tools": {
    "node": {
      "requiredFor": [
        "plan",
        "images",
        "voice",
        "video",
        "final"
      ]
    },
    "ffmpeg": {
      "requiredFor": [
        "voice",
        "video",
        "final"
      ]
    },
    "ffprobe": {
      "requiredFor": [
        "voice",
        "video",
        "final"
      ]
    },
    "remotion": {
      "requiredFor": [
        "final"
      ]
    }
  },
  "disabledStages": {},
  "notes": [
    "Your coding agent authors directions, script, and plan locally. No separate LLM provider or API key is required. Coding-agent usage still applies."
  ]
}

{
  "required": [
    {
      "id": "research",
      "label": "Website research",
      "type": "StoredWebsiteResearchResult",
      "description": "The coding agent researches the website and writes this structure, or imports an existing Wiggly export. See the research object in fixtures/agent-cookie-gift.json for the complete shape. Replace all fixture facts and URLs. No Wiggly account or NIM key is required."
    },
    {
      "id": "storySubject",
      "label": "Story focus",
      "type": "product | brand | customer-problem | custom",
      "description": "What the 3D Breakdown should explain."
    }
  ],
  "conditional": [
    {
      "when": "storySubject is product",
      "field": "productHandle",
      "rule": "The chosen product must exist in the catalog and have a usable image."
    },
    {
      "when": "storySubject is custom",
      "field": "brief",
      "rule": "The brief must be at least eight characters and remains creative direction, not factual evidence."
    }
  ]
}

{
  "stages": [
    {
      "id": "directions",
      "output": "Exactly five host-agent-authored, locally validated evidence-backed story directions",
      "paidMedia": false,
      "approvalRequired": true
    },
    {
      "id": "selected-plan",
      "output": "One host-agent-authored Style B script and six-frame scene plan, imported through the shared validators",
      "paidMedia": false,
      "approvalRequired": true
    },
    {
      "id": "storyboard",
      "output": "One reviewed 2-by-3 storyboard contact sheet",
      "paidMedia": true,
      "approvalRequired": true,
      "oneCallAtATime": true
    },
    {
      "id": "production-endpoints",
      "output": "Four individually reviewed, identity-locked full-quality 9:16 video endpoints",
      "paidMedia": true,
      "approvalRequired": true,
      "oneCallAtATime": true
    },
    {
      "id": "video-clips",
      "output": "Two individually reviewed 10-second 480p clips with three readable visual beats each",
      "paidMedia": true,
      "approvalRequired": true,
      "oneCallAtATime": true,
      "resumePolicy": "Persist each Replicate prediction ID. If local polling ends first, keep the clip processing and collect that same prediction on the next video command. A rejected ready clip may be replaced only after its rejection reason is recorded.",
      "enabled": true
    },
    {
      "id": "voice-and-final",
      "output": "Fish voice and one 20-second final MP4",
      "paidMedia": true,
      "approvalRequired": true,
      "enabled": true
    }
  ]
}

{
  "fixed": [
    {
      "id": "style-master",
      "label": "Style B master reference",
      "localPath": "assets/ecommerce-teardown-style-reference-clean-v7.jpg",
      "sourcePath": "/three-d-breakdown/references/ecommerce-teardown-style-reference-clean-v7.jpg",
      "purpose": "Locks feature-animation CGI rendering, materials, and finish without overriding the approved story setting or subject."
    },
    {
      "id": "production-reference-set",
      "label": "FinalStraw canonical proof plus Grüns, Kiala Nutrition, and Theragun supporting references",
      "localPath": "goldens/",
      "sourcePath": "See goldens.json for source filenames and SHA-256 hashes.",
      "purpose": "FinalStraw locks the reproducible Style B recipe; the other videos broaden the comparison set. These videos are references to compare against, not assets to copy into a new ad."
    }
  ],
  "variable": [
    "Selected product packshot when the story is product-led",
    "Up to two usable brand images when no product packshot is available",
    "One generated storyboard contact sheet",
    "Four generated full-quality production endpoints"
  ]
}

{
  "planning": [
    "The scene passes validateThreeDBreakdownScene.",
    "The selected style is presenter-teardown-vsl.",
    "The script has five correctly timed beats.",
    "The storyboard has six distinct physical actions in one coherent bright blue/cyan blueprint-grid CGI world.",
    "The clip plan has two 10-second clips mapped to frames 1-3 and 4-6."
  ],
  "creative": [
    "The agent watches all three packaged production references before choosing a direction.",
    "The first two seconds establish a concrete product, customer tension, or false assumption.",
    "The blue explanation world makes an invisible mechanism or change easy to see instead of acting as decoration.",
    "Every major narration beat causes a visible action, object change, or result.",
    "The approved product or subject remains recognizable through the world change and returns in the payoff.",
    "Before finalization, the agent compares the finished video with at least two production references and records why it is or is not credible beside them."
  ],
  "images": [
    "The storyboard is a 2-by-3 contact sheet with no readable generated text.",
    "The approved recurring subject, exact demonstrator identity, product category, and blue-grid world survive all six planned frames.",
    "Object-only frames do not invent a face or full person.",
    "Frames 1, 3, 4, and 6 each have one approved full-quality production endpoint.",
    "Every endpoint is sharp and matches its intended subject, setting, and story state.",
    "No video call happens during image inspection."
  ],
  "videoGate": [
    "The storyboard and all four production endpoints are present and explicitly approved for their current attempt.",
    "Storyboard panel crops are planning references only and are never sent to video generation.",
    "Every generated asset has provenance and an attempt number.",
    "The user explicitly approves paid video generation in a later phase."
  ],
  "video": [
    "Generate clip 1 before clip 2 and inspect each result before another paid call.",
    "Each clip uses its approved full-quality start and end production frames.",
    "Each clip is rendered at 480p as one coherent sequence with three readable visual beats and motivated cuts or transitions inside the approved blue-grid world.",
    "Each clip is within one second of its planned 10-second duration.",
    "The contact sheet preserves the approved blue-grid world, exact demonstrator identity, subjects, and recurring objects across both clips.",
    "Clip 2 completes meaningful action by global second 16 because the end-card overlay occupies seconds 16-20.",
    "No voice or final composition is generated during clip inspection."
  ],
  "final": [
    "Narration is generated only after both clips are explicitly approved, targets 18.1 seconds, and may be locally retimed only within the documented safe ratio.",
    "Renderer captions preserve every spoken word in the five script beats.",
    "The final MP4 is rendered locally through AdRenderSurface with no background music.",
    "The final MP4 is 1080 by 1920, 20 seconds long, and contains an audio stream.",
    "An agent watches the final video and explicitly approves it before finalization.",
    "Passing duration, resolution, and audio checks does not override a failed creative comparison."
  ]
}

{
  "purpose": "Production references that teach an agent what a usable 20-second 3D Breakdown feels like. FinalStraw is the canonical reproducibility target; the others are supporting comparisons, not shots or claims to copy.",
  "contactSheet": "goldens/contact-sheet.jpg",
  "canonicalContactSheet": "goldens/finalstraw-contact-sheet.jpg",
  "contactSheetRows": [
    "Grüns at 2, 9, and 16 seconds",
    "Kiala Nutrition at 2, 9, and 16 seconds",
    "Theragun at 2, 9, and 16 seconds"
  ],
  "sharedQualityBar": [
    "The first two seconds establish a concrete product, customer tension, or false assumption.",
    "The blue explanation world makes an invisible mechanism or change easy to see; it is not decorative filler.",
    "Every major narration beat causes a visible action, object change, or result.",
    "The product or subject remains recognizable while the world changes.",
    "The final seconds return to a clear product payoff and direct buyer action."
  ],
  "examples": [
    {
      "id": "finalstraw",
      "brand": "FinalStraw",
      "role": "Canonical Style B reproducibility target",
      "videoPath": "goldens/finalstraw.mp4",
      "sourceFilename": "finalstraw-3d-breakdown-day-5.mp4",
      "sourceSha256": "1c36bd36015a703e7db46dbce26cbd8f8bfe04ef770b84a6b6db76ab94b5cc2d",
      "packageSha256": "961d846faac089dfbba09c5b053e6d1cb20bf19655cabdffdd2cb702abda0a7f",
      "durationSeconds": 20,
      "resolution": "540x960",
      "reviewedTranscript": "This keychain-sized case is hiding a full-sized stainless-steel straw. A reusable straw only works if you actually remember to bring it. Inside, linked stainless-steel segments unfold until the whole thing snaps straight. When you're done, it collapses into its case and clips back onto your keys. Carry FinalStraw and skip the plastic.",
      "whyItWorks": [
        "One recognizable blue-grid world carries the entire story while camera, scale, props, and physical states keep changing.",
        "The silent demonstrator remains visually consistent while an omniscient narrator explains the product.",
        "The product mechanism is shown through readable physical actions rather than generic science imagery.",
        "The final product and buyer-action CTA get a designed four-second hold."
      ],
      "productionLessons": [
        "Clip 2 was rejected and regenerated before approval.",
        "Voice and late clip action were retimed locally instead of spending on replacement provider calls.",
        "Captions match the approved script wording exactly."
      ],
      "knownWeaknesses": []
    },
    {
      "id": "gruns",
      "brand": "Grüns",
      "role": "Earlier Wiggly baseline",
      "videoPath": "goldens/gruns.mp4",
      "sourceFilename": "gruns-caption-refresh.mp4",
      "sourceSha256": "1f716a2b3612284392bb0fb2abdc50852094d9ea0c40a65f47e087e388f4bb3a",
      "packageSha256": "579ec70e526ee6051123f20e87b68f37cd7d2b8005a2b1200e440198e9d97d55",
      "durationSeconds": 20,
      "resolution": "540x960",
      "reviewedTranscript": "A clinical trial can prove a supplement works, but that does not mean the one in your hand will. Stomach acid turns the route into the hidden problem. Grüns makes the hidden product path visible, clinically tested in 2025 in a randomized, double-blind, placebo-controlled study. The hidden route finally matters. Start your daily habit.",
      "whyItWorks": [
        "The real pouch appears immediately and returns in the final product card.",
        "The journey through the body gives the blue world a specific explanation job.",
        "The product payoff is visually clean and easy to recognize."
      ],
      "productionLessons": [
        "The saved caption-free clips and original narration were re-rendered through AdRenderSurface so captions and the end card use the current sans-serif system.",
        "Grüns-specific caption breaks keep phrases such as product path visible and clinically tested in 2025 intact."
      ],
      "knownWeaknesses": [
        "The opening line starts with an abstract credential instead of a concrete customer moment.",
        "Some middle shots repeat the same tunnel idea instead of showing a stronger product-specific mechanism."
      ]
    },
    {
      "id": "kiala",
      "brand": "Kiala Nutrition",
      "role": "Routine-compression reference",
      "videoPath": "goldens/kiala.mp4",
      "sourceFilename": "kiala-nutrition-3d-breakdown-final.mp4",
      "sourceSha256": "621fa12733cb9198961820298fbb248b529922409a362d81d480d570f8cb19d4",
      "packageSha256": "07329d96c8977a93fa4c88e686d468827402eb407c767087151f43ca762d16a0",
      "durationSeconds": 20.053,
      "resolution": "540x960",
      "reviewedTranscript": "You organize your morning supplements and assume swallowing a handful covers your bases. But keeping 45 different superfoods stocked creates daily routine friction. A combined system provides 45-plus superfoods, adaptogens, and enzymes. All those scattered bottles assemble into a single unified scoop of greens. Shop Kiala Nutrition greens powder.",
      "whyItWorks": [
        "The opening bottle pile makes the customer problem visible before explaining anything.",
        "The blue world compresses many scattered objects into one product system.",
        "The final packshot resolves the same clutter shown in the hook."
      ],
      "knownWeaknesses": [
        "The narration carries several product details quickly and needs careful evidence review."
      ]
    },
    {
      "id": "theragun",
      "brand": "Theragun",
      "role": "Physical-mechanism reference",
      "videoPath": "goldens/theragun.mp4",
      "sourceFilename": "theragun-3d-breakdown-no-blocks (1).mp4",
      "sourceSha256": "ae1d00fc59a21c1c245d3863f883cc343b4b2b598010c475c196afe4a20af570",
      "packageSha256": "acf8b2063c6ea0b946569cb34b181ce39515f410d9b1e81df53f36e8b9ad61b8",
      "durationSeconds": 20,
      "resolution": "540x960",
      "reviewedTranscript": "You press a massage gun against a knot and assume force alone will release it. But cold percussion just bounces off tight tissue. A heated attachment drives warm percussion into the muscle. Heat-enhanced percussive therapy preps tight muscles three times faster than massage alone. Get the Theragun heated massage gun.",
      "whyItWorks": [
        "The hook begins with an action the customer already understands.",
        "The cutaway makes the difference between cold and heated percussion physically visible.",
        "The internal product view connects the mechanism to the final device."
      ],
      "knownWeaknesses": [
        "The measurable claim must remain tied to saved brand evidence."
      ]
    }
  ]
}

{
  "id": "three-d-breakdown",
  "version": "1.6.0",
  "title": "3D Breakdown",
  "description": "Turn one evidence-backed brand story into a reviewed 20-second 3D explainer with a six-frame plan, four identity-locked video endpoints, two clips, and one exact-caption voice track.",
  "status": "complete-runner",
  "canonicalRenderer": "features/formats/three-d-breakdown/render.tsx",
  "canonicalSceneContract": "features/scene/types.ts#ThreeDBreakdownAdScene"
}

{
  "name": "wiggly-three-d-breakdown-format-kit",
  "private": true,
  "version": "1.6.0",
  "type": "module",
  "engines": {
    "node": ">=22"
  },
  "scripts": {
    "check:kit": "node kit-smoke.mjs",
    "format:three-d": "node --import tsx scripts/three-d-breakdown-format.ts",
    "smoke": "node --import tsx scripts/smoke-three-d-breakdown-format.ts",
    "test": "node --import tsx tests/three-d-breakdown-repo.test.ts && node kit-smoke.mjs"
  },
  "dependencies": {
    "@remotion/bundler": "4.0.473",
    "@remotion/media": "4.0.473",
    "@remotion/renderer": "4.0.473",
    "jpeg-js": "0.4.4",
    "lucide-react": "0.546.0",
    "react": "19.0.1",
    "react-dom": "19.0.1",
    "remotion": "4.0.473",
    "tsx": "4.20.6"
  }
}

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "jsx": "react-jsx",
    "esModuleInterop": true,
    "resolveJsonModule": true
  }
}

# Real production proof

## v1.6.0 host-agent planning migration

- The Repo's directions, script, and scene are now authored by the host coding agent and imported through the existing shared validators. The separate Wiggly `/create` planning provider is unchanged.
- Two synthetic offline regression inputs (wooden-toy history and cookie gifting) reach a validated official scene without API keys or network calls. Invalid directions, evidence IDs, scene plans, and mismatched script selections are rejected before media generation.
- These are planning and runtime checks, not newly generated or creatively approved videos. The production references below keep their original provenance.
- An independent extracted-package check exposed a missing JSX configuration: source-tree smoke passed by inheriting the app's config, while the standalone renderer reported `React is not defined`. The kit now includes its own `tsconfig.json`, and its commands use `node --import tsx` without an IPC launcher. Archive tests guard against missing config and stale packaged runtime files.
- After that fix, a fresh extraction passed the standard `npm run smoke` using dependencies installed independently from the kit's package manifest, rather than the Wiggly workspace dependencies.

## Canonical successful proof

The FinalStraw Day 5 video is the current Style B reproducibility target.

- Script: five concise beats moving from hidden product to customer friction, mechanism, resolved use, and buyer-action CTA.
- World: one bright blue/cyan blueprint-grid explanation stage across the entire story.
- Demonstrator: one silent semi-stylized 3D man with a dark backward cap, white sunglasses on the cap, pink polo, and tan cargo shorts.
- Media: one six-frame storyboard, full-quality anchors at frames 1, 3, 4, and 6, and two 10-second Seedance clips.
- Human review: clip 2 was rejected and regenerated before approval.
- Post-production: existing voice and late clip action were retimed locally rather than buying replacement provider calls; captions preserve the approved script wording.
- Final: one 1080×1920, 20-second MP4 with one audio stream and a four-second product/CTA hold.

See `goldens/finalstraw.mp4`, `goldens/finalstraw-contact-sheet.jpg`, and `fixtures/finalstraw-reproducibility.json`.

## Supporting creative quality evidence

The Repo also includes three earlier Wiggly production references in `goldens/`, with provenance, reviewed narration, strengths, and known weaknesses in `goldens.json`.

- **Grüns:** the earlier Wiggly baseline. It proves the product can travel into an explanation world and return to a clean payoff, but its abstract hook and repeated tunnel shots remain weaknesses to beat.
- **Kiala Nutrition:** the clearest routine-compression example. A pile of separate supplements becomes one unified product system.
- **Theragun:** the clearest physical-mechanism example. A familiar customer action becomes a cutaway that shows why heat changes the result.

FinalStraw establishes the reproducibility target. The supporting references broaden the comparison set. None authorize copying brand claims, wording, or shots.

## LEGO technical proof

- Input: LEGO's documented company-origin article.
- Direction: rewind from a modern brick to the first documented 1932 wooden-toy product line.
- Planning: five directions, one selected Style B script, six storyboard frames, and two 10-second clip plans.
- Paid image attempts: one storyboard plus full-quality frame-1 and frame-4 starts. The old runner then enlarged tiny storyboard panels into frame-3 and frame-6 endpoints.
- Video: two 10-second Seedance 2.0 Mini clips were generated in one attempt from those mixed-quality inputs.
- Result: `failed-paid-media-quality`.
- Human review: the clips are not good enough to run as ads. Their ending images are visibly soft, the payoff appears too early, and clip 2 invents a different CGI person and setting.
- Root cause: planning thumbnails were used as production media, while old prompt rules forced a recurring presenter and three hard-cut subshots even when the approved story was object-led.
- Historical correction: the runner was changed to require four independently generated endpoints (frames 1, 3, 4, and 6), preserve object-only frames, and request 480p. The later FinalStraw proof showed that forcing one continuous transformation was itself too restrictive.
- Technical note: the old clips are 10.042 seconds at 496×864 and contain no audio stream. Passing those mechanical checks did not make them creatively acceptable.

See `agent-runs/lego-origin-proof/` for the inputs, scene contract, images, attempt history, and quality report.

### Corrected 480p proof

- Direction: a failed carpentry livelihood turns heavy wooden work into the first easy-to-sell toys.
- Planning: the locked GLM 5.2 path produced a 48-word script, six-frame plan, and two continuous clip contracts.
- Paid image attempts: one Nano Banana 2 Lite storyboard plus four separate full-quality endpoints at frames 1, 3, 4, and 6.
- Video: two 10-second Seedance 2.0 Mini clips at 480p, generated and inspected one at a time.
- Result: `continuity-passed-style-b-failed`.
- Human review: the ladder, carpenter, workshop, wood, and toy car remain coherent; both clips use continuous physical motion; the final car is sharp; no unrelated person appears. However, both clips stay in the warm workshop and omit Style B's recognizable blue explanation stage.
- Technical review: both clips are 10.042 seconds at 496×864, the duration gate passes, and the quality report contains no problems.
- Historical correction: this run introduced a lifestyle-to-blue-to-lifestyle world sequence. The successful FinalStraw proof later replaced that rule with one coherent blue-grid world across all six frames.
- Boundary: no voice or final 20-second composition was generated.

See `agent-runs/lego-origin-quality-proof/` for the scene, four production endpoints, both clips, contact sheet, attempt history, and quality report.

### Style B world-arc technical proof

- Direction: LEGO survives the 1930s downturn by turning difficult-to-sell carpentry into simple wooden toys.
- Planning: the approved scene moves from the warm workshop into the blue/cyan breakdown world, then returns to the workshop for the payoff.
- Paid image attempts: one Nano Banana 2 Lite storyboard, four accepted full-quality endpoints, and one replacement for a rejected final endpoint that contained fake article text.
- Video: two separately approved 10-second Seedance 2.0 Mini clips at 480p, with no retry or duplicate generation.
- Result: `style-b-clips-passed`.
- Human review: clip 1 keeps the carpenter and wooden objects coherent while moving from the workshop into the blue grid. Clip 2 assembles the wooden car in the blue world, returns to the same workshop, and ends with a finished wooden-toy collection. Neither clip invents visible text or an unrelated person.
- Technical review: both clips are 10.042 seconds, the duration gate passes, and the Repo inspector reports `clips-ready`.
- Provider finding: the first Replicate prediction took 319 seconds and the second took 1,725 seconds. The foreground runner incorrectly stopped polling before both healthy predictions completed. Their exact prediction outputs were recovered without retries. A future runner must persist and resume provider prediction IDs instead of extending a foreground timer.
- Voice: one Fish S2.1 Pro Free narration, 19.193 seconds.
- Final: one 1080×1920, 20-second MP4 with audio, rendered locally through `AdRenderSurface`.
- Final result: `technical-passed-marketing-failed`. The automated report found no mechanical problems and the contact sheet preserves the approved world arc, but the hook does not quickly establish LEGO or a strong viewer problem. The finished file is evidence that the pipeline works, not evidence that the ad is good enough to run.
- Spend note: the final proof reused the accepted clips and made no new Replicate call.

See `agent-runs/lego-origin-world-arc-proof/` for the accepted endpoints, rejected endpoint evidence, scene, clips, narration, final MP4, contact sheets, attempt history, and quality report.

## David's Cookies stopped attempt

- Input: a selected blueberry-pie product from a real saved site-research run.
- Result: stopped before selection or image generation.
- Reason: the proposed directions relied on unsupported product claims because the available evidence did not specifically support the chosen product.
- Lesson: product-led stories must validate that their evidence belongs to the selected product before approving a direction.

See `agent-runs/davids-blueberry-pie-proof/` for the research, proposed directions, and stopped state.

{
  "format": "three-d-breakdown",
  "visualStyle": "presenter-teardown-vsl",
  "durationMs": 20000,
  "scriptBeats": [
    { "role": "consequence", "startMs": 0, "endMs": 3000 },
    { "role": "context", "startMs": 3000, "endMs": 7000 },
    { "role": "mechanism", "startMs": 7000, "endMs": 12000 },
    { "role": "revelation", "startMs": 12000, "endMs": 16000 },
    { "role": "punchline", "startMs": 16000, "endMs": 20000 }
  ],
  "storyboard": {
    "frameCount": 6,
    "roles": ["problem", "escalation", "mechanism-setup", "wow-reveal", "payoff", "final-state"],
    "layout": "2 columns by 3 rows",
    "worldSequence": [
      {
        "frameIndexes": [1, 2, 3, 4, 5, 6],
        "role": "blue-breakdown",
        "world": "one recognizable bright blue/cyan blueprint-grid explanation stage; vary camera, scale, props, and physical state without changing visual worlds"
      }
    ]
  },
  "productionAnchors": {
    "frameIndexes": [1, 3, 4, 6],
    "count": 4
  },
  "clips": [
    { "clipIndex": 1, "frameIndexes": [1, 2, 3], "startMs": 0, "endMs": 10000 },
    {
      "clipIndex": 2,
      "frameIndexes": [4, 5, 6],
      "startMs": 10000,
      "endMs": 20000,
      "meaningfulActionCompleteByMs": 16000
    }
  ],
  "endCard": {
    "startMs": 16000,
    "endMs": 20000,
    "rule": "The product and CTA overlay occupy the final four seconds, so clip 2 must finish its meaningful action by 16 seconds."
  }
}