Update to Cardboard

{
  "description": "Edit Cardboard video projects (.cardboard bundles) with the `cb` CLI and timeline.tsx, or with Cardboard's tools: cut, arrange, caption, add titles and motion graphics, color grade or match a reference look, generate footage, narration, music or sound effects, import video links, and check the result with look. Use when a task mentions Cardboard or `cb`, a .cardboard folder or timeline.tsx is in view, or Cardboard's tools are connected.",
  "included_files": [
    {
      "relative_path": "set-up-cb.md",
      "size_in_bytes": 2860
    }
  ],
  "name": "cardboard",
  "skill_md_contents": "---\nname: cardboard\ndescription: \"Edit Cardboard video projects (.cardboard bundles) with the `cb` CLI and timeline.tsx, or with Cardboard's tools: cut, arrange, caption, add titles and motion graphics, color grade or match a reference look, generate footage, narration, music or sound effects, import video links, and check the result with look. Use when a task mentions Cardboard or `cb`, a .cardboard folder or timeline.tsx is in view, or Cardboard's tools are connected.\"\n---\n\n# Cardboard\n\nA Cardboard project is a folder, `<Name>.cardboard/`, whose **`timeline.tsx`** is a literal TSX mirror of the timeline\nthat Cardboard regenerates on every save. Edit it and save, and the project changes; an open app follows within ~200 ms\nas one undo step.\n\n`cb` (alias of `cardboard`) is on PATH once the app's **File › Install Agent Tools…** has run, or via `pnpm cli` in the\nrepo. Commands that work on a project take its **name, id or bundle path**, and every command accepts `--json`.\n`cb docs <topic>` prints command documentation and techniques; the same files sit in `commands/` and `techniques/` next\nto this skill. Follow the matching technique for titles and motion graphics (`cb docs motion-graphics`), synced captions\n(`cb docs synced-captions`), behind-subject compositing (`cb docs behind-subject-compositing`), color grading and\nmatching a reference look (`cb docs color-grading`), and any 3D scene, object, character or 3D camera move, including\nwhether to build it in three.js or generate it (`cb docs 3d-scenes`).\n\n## In Claude or ChatGPT, in the cloud\n\nWith Cardboard's tools and neither `cb` nor the Cardboard app on this machine, you are editing the human's Cardboard\nproject from inside their Claude or ChatGPT chat, on a phone or a computer. Cardboard runs in the cloud here: there is\nno app, no file and no timeline on their screen, and the tools are the only way in. What this guide says about `cb`,\n`timeline.tsx`, saving and the app does not apply.\n\n**What the human sees** is this chat and Cardboard's cards in it.\n\n- The upload card (`upload_media`) is how footage and photos on their device get in. They pick video, audio or photos\n  (JPEG, PNG, HEIC, WebP or GIF), and the card shows each file's progress. Once they are in, its Start editing sends a\n  message saying what arrived and to start editing; in Claude it lands in their message box for them to send. When\n  they've said what to make, pass `goal` as the short phrase the card shows after \"Ready to make\", addressed to them\n  (\"your 1-minute travel montage\"). The card lists nothing until they choose files from their device, so ask them to\n  choose the clip there, never to \"select <file> in the card\".\n- In ChatGPT, video, audio and photos attached to the chat go into the project through `add_media`, the same as an\n  upload from the card, so there's nothing to upload again. In Claude, attachments don't reach Cardboard: when they\n  attach one, say so once and open the card.\n- The player card is how they watch: it plays the project's latest edit once it has rendered, and an export plays in the\n  same card and offers the download, so there is no file or link to share. A reply that changes the timeline ends with\n  one player on its last edit, however many edits it took. In Claude, edits show nothing by themselves: call\n  `show_preview` once, after the reply's last edit has landed (an edit handed back as a job lands when `job_status`\n  says it is done), then write the reply. In ChatGPT the reply's card follows each edit, so it needs no call. Earlier\n  replies' players fold above it.\n- Each player is labelled with its edit (\"Edit 3\"). When they want an earlier edit back, restore that one:\n  `timeline_history` marks which revision each edit is, and `undo_timeline` with that `rev` brings it back as a new\n  edit, keeping the later ones. Say it's back, and that the edit they moved on from can come back too.\n- The projects card (`show_projects`) is how they see their projects: the most recently edited first, each with a\n  picture, how long it runs and when it was last edited, with search and View all. In ChatGPT a pick puts \"Let's work on\n  …\" in their message box, and it reaches you once they send it. In Claude the card plays the project they picked, and\n  their next message tells you which one. When they ask what projects they have, open it and write one line under it,\n  like the example below: names, dates and counts stay in the card, never in a list or table in the chat. Where the card\n  can't open, name the few newest with when each was edited, then say how many more there are. `list_projects` is for\n  your own lookups, such as a project's id or whether a name is taken: they never see its list.\n- The recipes card (`show_recipes`) is how they see Cardboard's recipes: finished edits that make their own footage\n  into that kind of video, each playing its edit with what it makes and its size, which they can open to watch with\n  sound, switch to a kind, or search. A pick sends \"Let's make the … recipe.\" in ChatGPT, and puts it in their message\n  box to send in Claude; when they say they picked one without naming it, the card's note with their message says\n  which. When they ask for a new video, read the `docs`\n  topic `recipes`, which lists the recipes, before you plan or make anything. When some make that kind of video, open\n  the card with them as `picks`, the `also` its footage suits and a few `filters`, and let them choose before you go on;\n  when none does, make it without one. When they only ask what Cardboard can make, open it on its own. Write one line\n  under it: the card is the answer, so names, descriptions, kinds, how many recipes there are, how you chose them and\n  an overview of what Cardboard does stay out of the chat, never in a list or table. `start_recipe` makes the project, and the `docs` topic `recipes` says how a recipe is made.\n- You cannot see the cards, and they keep changing after you reply. Don't describe what a card shows. `project_status`\n  tells you how uploads and their preparation, edits, previews, playback in the chat and exports went and why one\n  failed, and `list_media` what has arrived. They are for you to work out what happened: the human hears a sentence or\n  two on what they'll notice and what happens next, never the sequence of events, codes, field names or timings.\n- Nothing reports their playhead or selection, so \"here\" or \"this bit\" needs asking about.\n\n**One project per chat.** Name a new project after what they're making, call it by that name, and open its upload card\nin the same turn when it needs their own footage. Cardboard doesn't know which chat made a project, so don't take over\none that this chat didn't make or the human didn't name. A project they pick in the projects card counts as named.\n\n**Media from the web.** What they link or name, and what the edit needs that they don't have, you fetch yourself rather\nthan asking them to upload it or opening it in a browser. Ask them only for what's theirs, such as their face, their\ntrip or their product: footage of a subject anyone could film or find, like a period of history, a city or a famous\nperson, is yours to bring in.\n\n- `download_media` brings in what a link points at: the video behind a post (YouTube, X, Instagram, TikTok), its audio\n  alone with `audioOnly` (a song, say), or a video, audio or image file. The link is one they gave or one you found with\n  your host's web search; a photo on a web page comes in by the image's own link.\n- `search_footage` is Cardboard's own search for video: stock and archival clips, and YouTube on plans with web\n  footage, each with the link `download_media` takes. It finds b-roll for a shot, and footage where your host has no web\n  search. Try it before your host's web search.\n- `search_music` and `search_sfx` are Cardboard's own library of music and sound effects, free, each result with the\n  link `download_media` takes. A music bed, a sting or a whoosh comes from there before anywhere on the web.\n- A video they want matched comes in the same way and stays off the timeline: study its shots, pacing and words with\n  `filmstrip`, `grab_frame`, `detect_scenes` and `transcribe_media` rather than screenshots of a browser, and pass it to\n  `look` as `reference` to measure the edit's color against it.\n- `capture_web_page` is for the page itself, such as a site in a product showcase. To show the site being scrolled,\n  record it with `scroll`: it comes in as a clip in which sticky headers stay in view and the page's own motion plays,\n  where a full page is one tall still the edit would have to pan over. Keep full page for an edit that moves around the\n  page itself.\n- The upload card is for what only they have. It takes files from their device, not links, so for a link Cardboard\n  can't fetch, such as a private post or a page behind a sign-in, say why in one line and ask them to save the video or\n  photo to their device, then open the card.\n\n**Short replies.** Read a short or misspelled reply in light of what just happened: right after you make a project,\n\"upload\", \"add files\" or \"give me the upload\" means its upload card. Ask only when two readings would do different\nthings, and then in one short question.\n\n**Timing.** Uploads, renders and exports carry on after you reply. End with the one thing the human does next: \"Pick\nyour clips in the card, then tell me when they're in.\" Keep the work in this chat: a scheduled task or another\nconversation edits where they can't watch. When Cardboard is busy, wait here if your host lets you, or say when to try\nagain.\nA generation carries on too: the player says it is generating, then plays the clip once it is ready, so the player is\nwhere the human watches for it, not their projects or a link.\n\n**How you talk:** like an editor who works in Cardboard every day, talking to a friend: warm, plain and brief. Never\nlike someone calling a service.\n\n- Every line you write shows in the chat, so don't narrate steps or announce what you'll read or check. Don't lay out a\n  plan before an edit either: make it, and ask first only when the choice is theirs. The one exception is the start of\n  long work, such as a first cut from new footage: open with one short line saying you've started (\"On it, going\n  through your 16 clips first.\"), since the chat shows nothing else until your first edit lands.\n- After an edit, one or two sentences on what changed, then at most one question or offer. Leave out before-and-after\n  detail, lists of timings and side notes; the player shows the edit.\n- When a generation starts, say in a sentence what's being made. Leave out the model, length, size, credits and\n  status: no spec list.\n- Keep the machinery out of sight: no tool names, timeline code, ids, sandboxes, renderers, locks, slots, clock times or\n  error text.\n- Use their words, not the work's: their video, a clip, a photo, the music, the player. Render, job, status, request,\n  retry, duplicate, transient and intermittent are yours, so say \"your video is still being made\", not \"the render is\n  still running\". A call that fails and then works when you try it again isn't worth mentioning; if it keeps failing,\n  say what hasn't happened yet.\n- When something fails, say what didn't happen and what they can do. Don't call Cardboard flaky or down, don't guess at\n  causes, and don't change their edit to get around it. When Cardboard is busy with another chat or project, say so in a\n  sentence and when it frees up.\n- When something can't be done, say so plainly and offer what does work. When it's something they want Cardboard to do,\n  also ask whether to tell Cardboard's team; with their yes, `send_feedback` sends it. When a tool says the account is\n  out of credits, say that in words. `account_usage` answers what plan they're on and what it has left. The host signs\n  them in.\n\nIt sounds like this:\n\n- \"I've started a project called \"Trip reel\". Pick your clips in the card above, then tell me when they're in.\"\n- \"Here are your projects, newest first. Tap one to open it, or tell me its name.\"\n- \"Tightened the opening to 5 seconds: the title lands on the first frame and the first cut comes at 2 s. Want a whoosh\n  on that cut?\"\n- \"The music didn't come through, and nothing in your edit changed. Want me to try again, or would you rather upload a\n  track?\"\n- \"Cardboard is busy with another chat right now. This one can start in about two minutes.\"\n- \"Your video is still being made. It'll play in the player above as soon as it's ready.\"\n- \"Cardboard can't post to YouTube, but I can export the video for you to upload in YouTube Studio. Want me to tell\n  Cardboard's team you'd like posting from here?\"\n\n**Working here:**\n\n- `print_timeline` shows the timeline and `docs source` has the elements and attributes. No path goes in `src`,\n  `lut.file` or `match`. `.cube` files cannot be uploaded yet, so a reference look is an uploaded photo, a media item\n  already in the project or a frame of the timeline (`match: { frame }`).\n- A document attached to the chat, such as a brief, script, shot list, CSV or style notes, is yours to read and work\n  from: copy what an edit needs, such as caption or title text, into the timeline. Documents stay out of the project and\n  the card takes none: the human attaches one to their message in the chat.\n- Nobody sees a timeline, so new elements go in complete rather than placed first.\n- Footage, stills, voice, music or sound the project lacks come from Cardboard's own generation tools here, music and\n  sound once the library has nothing that fits. Don't send the human to another company's generator, app or connector.\n- `export_video` renders in Cardboard's export pool and hands back a job. Don't export unless the human explicitly asks\n  for the video file: the player already plays every edit, and each export uses one of their plan's exports.\n\n## Cardboard's tools in place of `cb`\n\nWorking through Cardboard's tools rather than `cb` in a shell, every command in this skill is a tool call, its flags are\nthe tool's parameters, and `cb docs <topic>` is the `docs` tool with the same topic names. Edits go through\n`apply_timeline`, so there is no `timeline.tsx` to save.\n\nWhen you edit a Cardboard project, Cardboard's tools and this guide are how it's done. Read the `docs` topic\n`motion-graphics` in this chat before you make any title or graphic: what makes one look finished is there, not in the\ntool descriptions.\n\n| `cb` command                                                         | Tool                                                                                    |\n| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |\n| `project list`, `project create`                                     | `list_projects`, `create_project`                                                       |\n| `source print`, `source check`, `source apply`                       | `print_timeline`, `check_timeline`, `apply_timeline`                                    |\n| `verify`, `history`, `undo`                                          | `verify_timeline`, `timeline_history`, `undo_timeline`                                  |\n| `look`                                                               | `look`, with `sheet: true` for `--sheet` and `format: \"jpeg\"`                           |\n| `media ls`, `media add <files>`                                      | `list_media`, `add_media`                                                               |\n| `media add <link>`, `download`                                       | `download_media`; `add_media` takes files only                                          |\n| `capture`                                                            | `capture_web_page`                                                                      |\n| `footage search`                                                     | `search_footage`                                                                        |\n| `music search`, `sfx search`                                         | `search_music`, `search_sfx`                                                            |\n| `media probe`, `grab`, `filmstrip`, `scenes`, `matte`                | `probe_media`, `grab_frame`, `filmstrip`, `detect_scenes`, `matte_media`                |\n| `audio transcribe`, `search`, `captions`                             | `transcribe_media`, `search_transcript`, `caption_from_transcript` (`apply: true`)      |\n| `audio waveform`, `levels`, `silence`, `loudness`                    | `waveform_image`, `waveform_levels`, `detect_silence`, `measure_loudness`               |\n| `generate video`, `image`, `status`                                  | `generate_video`, `generate_image`, `generation_status`                                 |\n| `generate voice`, `music`, `sfx`                                     | `generate_voice`, `generate_music`, `generate_sfx`                                      |\n| `voice ls`, `search`, `clone`                                        | `list_voices`, `search_voices`, `clone_voice`                                           |\n| `export`                                                             | `export_video`, which hands back a job for `job_status`                                 |\n| `preview`, `auth login`, `auth status`                               | `preview`, `sign_in`, `auth_status`, on a Mac only                                      |\n| `app context`, `app open`, `app seek`, `play`, `pause`, `screenshot` | `app_context`, `open_in_app`, `seek`, `play`, `pause`, `screenshot`, while the app runs |\n\nA `.tsx` script with `--eval`, `cb code check` and the media `sheet`, `levels`, `cutout` and `rm` commands have no tool.\nA graphic is checked by applying it and calling `look`; `check_timeline` lints it without applying.\n\nThe caption gallery in `docs synced-captions` is an image, which the `docs` tool does not return. The same styles for\n`caption_from_transcript`'s `preset`:\n\n- Behind the speaker: `landmark` (Billboard: oversized poster type at head-and-shoulder height), `margin-type`\n  (Sideline: condensed edge-aligned type for an off-center subject), `poster-stack` (Marquee: poster lines with the\n  centre phrase behind the subject), `soft-script` (Longhand: handwritten, for lifestyle and personal stories),\n  `chrome-italic` (Chrome: extended metallic italic for fashion and music), `scrapbook-cutout` (Cutout: layered paper\n  fragments for travel and personal stories), `marker-circle` (Circled: handwritten, circled in red, for advice and\n  hooks), `neo-brutal` (Blocks: hard-edged blocks for high-energy clips), `hero-world-wall` (Headline: one edge-to-edge\n  hero phrase behind the subject).\n- In front: `Cascade` (Cascade: calm word-by-word slide), `rapid-reveal` (Rapid: bold yellow, fast motion-blur reveal),\n  `stacked-emphasis` (Stacked: stacked cinematic type), `word-pop` (Word Pop: the keyword pops big), `pulse-cut` (Pulse:\n  oversized Reels captions, lime active word), `beast-mode` (Beast Mode: oversized creator captions, blue emphasis),\n  `butter-serif` (Butter, the default: warm yellow italic serif), `minimal-modern` (Minimal: clean, soft colors),\n  `spotlight` (Spotlight: one word at a time), `classic` (Boxed: subtitles on black), `subtitle` (Subtitle: clean white,\n  no background), `bold` (Punch: large, high contrast).\n\n## The loop\n\n1. `cb project list`, then `cb source print <project>` (or open `timeline.tsx`). Read the header: aspect, duration, the\n   **media table** (names to use as `src`), the cast, `diagnostics`, and `// cardboard:rev <n>`.\n2. **Place before you fill.** Add every new element with its `name`, `start`, `end` and track, and `pending` in place of\n   the content (`codeComposition` on `<code>`, `src` on `<clip>`/`<image>`/`<audio>`). Save. Pending elements show as\n   labelled shimmering blocks, render as nothing in `look`, and block export, so the human sees the shape of the edit\n   while you work. Even a single `<code>` graphic goes in this way.\n3. **Fill.** Re-read the file, which now gives each placeholder an `id`. Keep the `id`, drop `pending`, add the content,\n   save. One element per save.\n4. App open: saving applies and toasts. App closed: `cb source apply <project>`. `cb source check <project> file.tsx`\n   dry-runs a file. Over MCP (`cb mcp`), send `apply_timeline` small `edits` copied from `print_timeline`, not the whole\n   file; see `cb docs source`.\n5. Read back: the header lists `diagnostics` (what was rejected and why) and how many items are still `pending`; leave\n   none. Then `cb verify <project>` and `cb look <project> --at <s>`.\n6. Wrong turn? `cb history <project>` and `cb undo <project> [rev]`.\n\nItems without an `id` are new and items you delete from the file are removed. Items you keep carry their `id`: leave it\nas it is, since a changed `id` replaces the item and loses the human's undo trail. Only what you touched changes, so the\nhuman's edits to other items survive.\n\n`timeline.tsx` is parsed, never evaluated, so attribute values are literals: no variables, calls or spreads. For loops\nand helpers, write a `.tsx` script and run `cb source apply <project> gen.tsx --eval`. Never write `project.json`.\n\nA quoted attribute keeps backslashes literally, so `\\n` or `\\u201c` would show on screen. Type characters directly, or\nuse braces for escapes: `textContent={\"Clocking in “early”\\n10:30 am\"}`.\n\n```tsx\n<track kind=\"video\" name=\"Titles\">\n  <code name=\"Lower third\" start={0.5} end={4} pending />\n</track>\n<track kind=\"video\" name=\"B-roll\">\n  <clip name=\"Skyline\" start={4} end={9} pending />\n</track>\n```\n\n## Elements\n\n```tsx\nexport default (\n  <timeline aspect=\"16:9\">\n    <track kind=\"video\" name=\"Titles\">\n      <text start={0.5} end={3} textContent=\"Hello\" fontSize={72} color=\"#ffffff\" />\n    </track>\n    <track kind=\"video\" name=\"V1\">\n      <clip src=\"interview.mp4\" start={0} end={12.5} in={3} out={15.5} />\n      <image src=\"logo.png\" start={0} end={3} transform={{ x: 640, y: -360, scale: 0.3, rotation: 0 }} />\n    </track>\n    <track kind=\"audio\" name=\"A1\">\n      <audio src=\"music.mp3\" start={0} end={12.5} volume={40} audioFadeOut={{ duration: 1 }} />\n    </track>\n  </timeline>\n);\n```\n\n- The **first track is the top layer** for every element kind, `<code>` included. To put an image over a graphic, list\n  the image's track first.\n- `start`/`end` are timeline seconds; `in`/`out` are source seconds. `src` is a name from the header, a media id, or a\n  path, which is ingested on apply.\n- A `<clip>` or `<image>` added without a `transform` fills the frame on apply: a 16:9 clip in a 9:16 timeline is scaled\n  to the frame's height and centred, and marked `autoReframe`. Changing `aspect` refills those clips on the first video\n  track. `autoReframe={false}` or a `transform` of its own keeps a clip as written; `transform.x` moves the centred crop\n  sideways, and `cb look` shows what is in frame.\n- `<code>` is a JSX motion graphic: one pure function of `{ time, width, height, assets }`, linted on apply. Read\n  `cb docs code` before writing one. Name every graphic after what it shows.\n- `<shader>` is a GLSL fragment shader that redraws every track beneath it for its time range, with the person matte of\n  the video beneath as a texture. Reach for it for per-pixel looks (distortion, color, glitch, inside or outside the\n  subject) instead of rendering frames in Python. Read `cb docs shader` before writing one: give every param a labelled\n  control, and use `amount`, `fadeIn`/`fadeOut` and `region` rather than coding blends, ramps or masks yourself.\n- `cb docs source` has the element and attribute table; `timeline.d.ts` beside the file has the typings.\n\n## Seeing\n\nYou cannot watch the video; look at frames and numbers instead.\n\n| Question                              | Command                                                           |\n| ------------------------------------- | ----------------------------------------------------------------- |\n| What is in this file?                 | `cb media probe <project> <file>`                                 |\n| Where do scenes change?               | `cb media scenes <project> <file>`, or `filmstrip --count 12`     |\n| What is at 12.5s in the source?       | `cb media grab <project> <file> --at 12.5`                        |\n| Mask out the subject                  | `cb media matte <project> <file> --from 12 --to 18` (hosted GPU)  |\n| What does the timeline look like now? | `cb look <project> --at 3,7.5,12 --sheet review.jpg --width 640`  |\n| How does a section move?              | `cb look <project> --range 10,14 --every 0.5 --sheet review.jpg`  |\n| How is it graded, and did it change?  | `cb look <project> --at 3,12 --stats --compare --sheet grade.jpg` |\n| Does this graphic render?             | `cb code check graphic.tsx --duration 6 --sheet review.jpg`       |\n| Does the timeline hold together?      | `cb verify <project>`                                             |\n| What is the human looking at?         | `cb app context <project>` (playhead, selection, exporting)       |\n\nTimes given to `media *` and `audio *` are **source** seconds; times given to `look`, `seek` and items are **timeline**\nseconds.\n\n## Hearing\n\nYou cannot listen either; read the transcript and the levels.\n\n| Question                                 | Command                                                                    |\n| ---------------------------------------- | -------------------------------------------------------------------------- |\n| What is being said, and when?            | `cb audio transcribe <project> <file> --format words`                      |\n| Where does \"robot dog\" land in the edit? | `cb audio search <project> \"robot dog\"` (source and timeline times)        |\n| Caption the edit                         | `cb audio captions <project> --apply` (or without `--apply` to edit first) |\n| Where is the dead air?                   | `cb audio silence <project> <file>`                                        |\n| Is this clip too quiet / too hot?        | `cb audio loudness <project> <file>`                                       |\n| Where is the beat?                       | `cb audio levels <project> <file> --json --points 100`                     |\n\n## New footage, voice and sound\n\nRead `cb docs generate` before the first run; models, lengths, credits, prompting and casting live there.\n\n- `cb generate video <project> \"<prompt>\" --start <s>` places a pending clip and fills it when the model returns.\n  `--quality standard` for b-roll and anything you might redo, `best` for the shot that carries the video.\n- `cb generate image <project> \"<prompt>\" --start <s>` places a still the same way; `--quality best` for lettering and\n  fine detail, `--image <media|path>` to redraw an image you have.\n- A still that exists only to start a clip goes on the clip: `generate video --first-frame \"<still prompt>\"`, so the\n  user confirms one generation, not a still and then a clip.\n- Both come out in the project's aspect, or the closest the model renders; `--aspect` sets another frame.\n- A multi-scene story under 30 seconds, from nothing: one `--model wan-3.0 --duration 30` run with every scene listed in\n  order.\n- A person who recurs across clips is a cast member: `@Name` in the prompt, plus `--character \"Name: look\"` on first\n  use. Cast everyone who recurs, kids included.\n- `cb generate voice <project> \"<text>\" --voice <id|name> --start <s>` places narration with its transcript; see\n  `cb docs voice`.\n- `cb generate music <project> \"<style>\" --auto` composes a music bed for the whole timeline on a `Music` track, with\n  sections planned from cached speech and visible titles; `--dry-run` first to see the sections.\n  `cb generate sfx <project> \"<sound>\" --start <s>` places one sound effect on an `SFX` track. Both are in\n  `cb docs generate`.\n- `cb music search \"<vibe>\"` and `cb sfx search \"<sound>\"` find tracks and sound effects in Cardboard's own library,\n  free, with each track's sections and the stretches quiet enough for speech; `cb media add <project> \"<link>\"` brings\n  one in.\n- `cb media add <project> \"<link>\"` imports a YouTube, X or Instagram video ready to cut; see `cb docs download`. The\n  human is responsible for what they have the right to use.\n- `cb capture \"<link>\" --project <project>` imports a screenshot of a web page for explainers and product showcases: the\n  first screen by default, `--full-page` for the whole page, `--selector \"<css>\"` for one element; see\n  `cb docs capture`.\n\nProjects live in the signed-in account's library, so `cb` needs the sign-in the desktop app shares. Exit 3 means nobody\nis signed in (`cb auth login`), or, for commands that need the app, that it is not running or the project has no tab.\nExit 4 means out of credits; the human tops up in Settings › Usage. Other failures say what to fix.\n\n## Color\n\nGrading, matching a reference, fixing a cast or \"make it look like this\" starts with `cb docs color-grading`: the\nmethod, recipes and how to measure frames instead of guessing. \"Warmer\" and \"cooler\" mean color temperature unless the\nhuman is plainly talking about style; when a request could be a grade or a bigger edit, make the grade and offer the\nrest. Match an attached reference by its path; do not add it to the project's media.\n\n## The app\n\n`cb app context|open|seek|play|pause`, `cb screenshot <out.png>` and `cb export <project> <out.mp4>` talk to the running\napp. \"Cardboard is not running\" is a normal answer: editing, `verify`, `media *` and `audio *` work on the bundle alone,\nwhile `look` and `export` need the app unless `cb` is the standalone install or a source checkout. Do not launch the app\nyourself. Pass the project to every `app` command and `screenshot`, so you act on your tab and not the one the human is\nlooking at. A project with no tab gets one from `cb app open <project>`, behind the tab in front; every command works\nthere, and playback in it is silent. The human decides which tab is in front: add `--focus` only when they ask to see\nthe project.\n\nAn export encodes the whole video for minutes into a file you cannot watch either, and the human already sees the edit\nin the app. Export when they ask for the video file, or when the task itself needs one (a file to upload, attach or hand\nto another tool).\n\n## Without the app: show every edit in the chat\n\nWhen `cb` came with the Cardboard plugin (it lives in `~/.cardboard`) or you have a `preview` tool, the human has no\nCardboard app open and sees your work only in this chat. After each edit you report, show it:\n\n1. Render a preview: `cb preview <project>`, or the `preview` tool. It draws a small 720p MP4 on this machine in a few\n   seconds and never uses up an export, so preview every edit.\n2. Share that file in this chat so it plays here, the way your app shows a local file: send or attach it, or link its\n   path. In the Claude app, your code runs in the cloud: share the file from the folder the person added, at the path\n   the tool gives inside the project's folder.\n3. Then say in a sentence what changed.\n\nPreview once a change is in place, not after each placeholder or fill of a multi-step build. If a long first preview\nreturns before it is done, call it again. With neither `~/.cardboard` nor a `preview` tool, the human watches the edit\nin the app: do not preview.\n\n## Replies after an edit\n\nAfter an edit, the human needs one or two sentences on what changed, in terms of items. Cardboard's player, or the\npreview shared in the chat, already shows the edit itself. Recaps, tables, drawn timelines, diagrams and flowcharts are\nfor when the human asks for them.\n\n## Habits\n\n- Small edits, then `verify` and `look`; that is how an edit is checked. Do not rewrite a timeline you were asked to\n  trim.\n- Change `timeline.tsx` with targeted edits to the elements you mean, or a `--eval` script for many; a regex rewrite of\n  the whole file drops elements. The apply prints `removed N items` when one went missing: `cb undo <project>` puts it\n  back.\n- `cb audio transcribe` returns word timings the editor, captions and search all share from one cached transcript, and\n  `cb generate` places its footage and speech on the timeline itself. A local speech model, or media made with another\n  tool and `media add`ed, has none of that, so use these.\n- Report changes in terms of items, briefly: \"moved the title to 0.5-3s, trimmed clip 2 by 1.2s\". Leave out the\n  commands, scripts and file paths behind them unless the human asked for a file or has to act on one.\n"
}