---
name: manage-storyboard-projects
description: Create, find, inspect, update, or delete Codex Storyboard projects directly through MCP. Use when the user asks Codex to write a new video script or storyboard into the local storyboard app, add or revise shots, rename a project, change its aspect ratio, find an existing project, or delete one without browser automation.
---

# Manage Storyboard Projects

Use the Codex Storyboard MCP project tools. Never control the browser, never run `npm start` manually during normal use, and never edit data files directly.

For reference-driven generation, use `reverse_storyboard_from_reference` with a local reference image. It creates a continuous before/after shot sequence (nine shots by default), attaches the reference image to every image-generation task, and queues the shots automatically. Use `brief` when the user provides story context; use `replace: true` only when the user explicitly wants existing shots replaced.

For image refinement, use the Cowart bridge tools: call `prepare_storyboard_cowart_edit` for the selected shot, open the native Cowart canvas with the returned source image, preserve the original, and place the revised image beside it. After the user finishes editing, call `import_cowart_revision_to_storyboard` with the revised local image path. The import archives the previous shot image as a reference version and makes the revised image current; never overwrite the only copy of the original.

If the current Codex session does not expose Storyboard MCP tools such as `create_storyboard_project`, `list_storyboard_projects`, or `open_storyboard`, first use `tool_search` to search for `codex storyboard` and load the deferred tools. Only if `tool_search` is unavailable or cannot find them, tell the user to start a new Codex conversation or restart Codex so plugin tools are reloaded. Do not silently fall back to editing local data files directly.

## Open the storyboard

If the user asks to open, start, launch, or show Codex Storyboard:

1. Call `open_storyboard`.
2. Return the local URL as a clickable link.
3. Tell the user to open the link in the Codex side panel.
4. Do not launch Chrome, shell `open`, Computer Use, or Browser automation just to open the page.

The plugin starts the bundled local app automatically. Project data is stored outside the plugin cache by default.

## Create a project

1. Turn the user's request into a complete shot list before calling the tool.
2. Call `create_storyboard_project` once with the project title, aspect ratio, all shots, and optional absolute `designPath`.
3. Do not create shots one at a time.
4. Return the created project ID and the project URL from the tool result. Tell the user to open that URL or refresh the storyboard if it is already open.
5. If any shot uses `remotion` or `hyperframes`, mention that generation requires the corresponding plugin or local toolchain before processing assets.

Each shot should include:

- `rollType`: `A-ROLL` for primary presentation or spoken footage; `B-ROLL` for supporting visuals.
- `mediaType`: `image` or `video`.
- `duration`: seconds.
- `dialogue`: spoken line for the shot.
- `visualPrompt`: concrete visual description used for asset generation.
- `rawVisualPrompt`: the original visual text recognized from the script, preserved for traceability and not used directly for generation.
- `generator`: `manual`, `image-gen`, `hyperframes`, or `remotion`.
- `notes`: editing, pacing, transition, or production notes.

Choose `generator` deliberately:

- `manual`: recorded presenter footage, screen recordings, or existing local material.
- `image-gen`: a static generated visual.
- `hyperframes`: designed motion graphics or interface animation.
- `remotion`: programmatic React-based video composition.

## Prompt structure

When converting a script or screenplay, do not paste the whole scene, backstory, dialogue, or analysis into `visualPrompt`. First preserve the recognized text in `rawVisualPrompt`, then rewrite the generation prompt as one compact visible beat using this fixed template:

`主体：人物/物体及关键外观；动作：一个主要动作及结果；场景：地点、时间、关键环境；构图：景别、主体位置、画面重点；镜头：一个主要运镜或镜头语言；光色：光线、色彩、视觉风格；连续性：身份、服装、道具或空间关系；限制：无文字、无水印、无多余人物等必要约束。`

Keep each structured `visualPrompt` to roughly 80–180 Chinese characters and no more than one main action. Put spoken words only in `dialogue`; put sound, pacing, transitions, and editorial notes in `notes`. Keep the structured prompt concise enough to scan and edit in the storyboard table. Generation tasks must always use the structured `visualPrompt`, never `rawVisualPrompt`.

## Find and inspect

- Use `list_storyboard_projects` first when the project ID is unknown. Pass `query` when the user gives a title.
- Use `get_storyboard_project` only when complete shot content is needed.
- Do not fetch every full project merely to find one title.

## Update

Use one `update_storyboard_project` call:

- `title` or `aspectRatio` for project metadata.
- `appendShots` for new shots.
- `shotUpdates` for specific existing shots.
- `deleteShotIds` for removed shots.
- `designPath` to import or replace DESIGN.md.
- `removeDesign: true` to remove it.

Fetch the complete project first only when shot IDs or existing content are required.

## Delete

Project deletion permanently removes the project and its local media. Ask for explicit confirmation immediately before calling `delete_storyboard_project`.

## Token discipline

- Create the complete project with one MCP call.
- Prefer project summaries over full project reads.
- Return concise results instead of repeating the full script after it has been written.
