---
name: shot-grid
version: 0.1.0
description: Turn four to six scene beats into one original 16:9 storyboard contact sheet with deliberate changes in shot size, angle, movement and blocking, and consistent continuity across frames. Runs through SandBase with one image at 16:9 PNG per approved brief, recoverable execution state and bilingual reports.
---

# Cinematic Shot Grid

## Example and deliverable

The bundled brief has five beats of a rainy-night café scene with fixed wardrobe and props. The Skill renders one contact sheet with five frames of varied shot sizes and no labels. A successful execution produces `shot-grid.png`,
`report.json`, `report.en.html` and `report.zh-CN.html` in the selected
language. Reports show the actual dimensions, execution ID, recorded cost and
the remaining human review.

No official real run is bundled for this release; the sample reports are labelled
mock fixtures and no image was generated for them.

## When this fits

- a director, editor or writer needs a continuity-aware storyboard contact sheet for one scene;
- the shot plan should vary shot size, angle, movement and blocking on purpose.
- The user invokes `/shot-grid`.

Do not use this Skill for a text-only shot list, final lettered boards or recreations of existing films, actors or protected characters.

## Prepare the content

Use the bundled [English brief](assets/sample-brief.en.json) or
[Chinese brief](assets/sample-brief.zh-CN.json):

```json
{
  "beats": [
    "Wide: a rainy street at night, a small café glowing on the corner.",
    "Medium: a courier in a yellow raincoat pushes the café door open.",
    "Close-up: her wet glove sets a parcel on the counter.",
    "Over the shoulder: the barista reads the label and smiles.",
    "Wide from inside: the courier steps back into the rain, door swinging shut."
  ],
  "continuity": "Yellow raincoat and black gloves; brown paper parcel with red string; warm café light, cool blue street; the courier moves left to right.",
  "language": "en"
}
```

- `beats` (required, 4–6 lines, each at most 160 characters): Four to six beats in order, one per line.
- `continuity` (required, at most 500 characters): Wardrobe, key props, lighting and screen direction that must stay the same.

`language` sets the language of any on-image text and of the brief; `--lang`
chooses CLI and report copy. Both default to `en`; `zh` maps to `zh-CN`, and
unsupported locales fall back to English. Chinese limits apply only when
`language` is exactly `zh-CN`.

Read the [visual workflow](references/workflow.md) and
[runtime boundaries](references/runtime.md) before submitting. One approved brief
allows one submission. Never purchase an automatic replacement.

## Execute in isolation

Use Node.js 18+ in SandBase Sandbox; no dependencies need installation. Local
commands read `SANDBASE_API_KEY` only from the process environment. Optionally
set `SANDBASE_API_BASE` to an allowed SandBase HTTPS address. Never put a model
key in a brief, command argument or file.

```sh
node scripts/generate.mjs plan --brief assets/sample-brief.en.json --out /tmp/shot-plan
node scripts/generate.mjs run --brief assets/sample-brief.en.json --out /tmp/shot-run --lang en --budget 0.30
node scripts/generate.mjs resume --brief assets/sample-brief.en.json --out /tmp/shot-run --lang zh-CN
```

`plan` makes no network call. `run` uses `openai/gpt-image-2.5-flare` with high
quality, 2k resolution, 16:9 and PNG. The inspected estimate is USD 0.15 per image;
default and maximum preflight budget is USD 0.30. This cannot guarantee an
upstream transactional limit. Unknown cost remains `null`.

Existing output directories reuse their execution. A changed brief, version or
model is rejected. A submission interrupted before saving its ID requires
reconciliation in SandBase before a new approved output directory is created.
Do not erase the state to force another purchase.

## Review the result

PNG checks cover signature, chunks, CRCs, decompressed pixel stream, size and
dimensions. Native model rounding may differ from exact 16:9 by up to 2%; the
report states actual dimensions. There is no silent resize, crop or fixed text
overlay.

The image must carry no words, letters, numerals or pseudo-writing. Treat any
lettering the model adds as a defect. Inspect composition, palette and
contrast at full resolution and at 320 × 180. `validation.ok` verifies the
file contract; `text_accuracy: needs_review` preserves the human review. File
integrity is not visual approval, and no generated image may carry a logo,
mascot, signature, watermark, real person or trademarked silhouette.

## Hosted execution

The [hosted entrypoint](references/hosted.md) claims an ephemeral credential,
runs the same pipeline, uploads the PNG and returns both report languages.
Lab owns orchestration and storage; it does not duplicate the prompt.

## FAQ and failure boundaries

- **Exact result?** The visual direction is requested, not guaranteed. Review it.
- **Real people, brands or artists?** Not as subjects or style shortcuts. Invent
  new artwork; never reproduce a logo, mascot, campaign, interface or known work.
- **Resume cost?** Resume polls the same execution and downloads its result.
- **Broken output?** Keep state and ID. Resume transient downloads; a terminal
  model failure requires a decision before another approved attempt.
- **Secret storage?** None persistently. Reports, state and errors are redacted;
  model keys go only to allowed SandBase hosts, never media downloads.
- **Image branding?** No watermark is added. SandBase identity belongs to the
  package, Lab interface and reports.

See [report schema](references/report-format.md).