skills/film/SKILL.md

---
name: film
description: "Make a short narrative AI film — multiple scenes, recurring characters, a locked visual style — through a guided 11-stage production pipeline with gates. Use when the user wants to make a film, short film, movie, episode, or multi-scene story (\"make a short film about…\", \"I have a script\", \"a movie with two characters\"). Not for a single clip from a description, and not for stitching footage the user already has — each of those is a direct tool call, not an eleven-stage pipeline."
---

# ChatGPT and Codex integration

Apply these host conventions throughout this skill and its references.

- Discover the connected Picsart tools and use their actual names and schemas.
  The `picsart_*` names in the workflow identify tools, not a fixed host namespace.
  If the connection is missing, explain that Picsart must be connected; continue
  script and shot planning when possible. Never invent tool results or renders.
- Read board decisions from the current user message and attached widget context.
  Use `read_widget_context` only if the host actually exposes that tool. Do not
  assume ChatGPT has Claude's context reader. Treat a board's initial tool result
  and unsent widget state as previews, never as user approval. If a submitted
  decision has no accessible payload, explain briefly and use the text fallback
  to collect the missing decision; do not guess or repeat charged operations.
- Use the host's available question interface or one concise conversational
  question for preset choices.
- UI rendering and delivery of feedback are the remote MCP server's responsibility.
  If a board is unavailable, present its relevant options in text and record the
  user's selection using the same documented feedback fields. Do not claim that
  a plugin manifest makes Claude-specific widgets compatible with ChatGPT.
- Save `film.json` and artifacts in the user's writable project workspace, not
  the installed plugin directory. If persistent file tools are unavailable,
  keep a structured project checkpoint in the conversation and provide it for
  download when the host supports files. Never claim a file was saved without
  confirmation from a file tool.
- Honor the user's current instructions and already authorized scope. Preserve
  quoted spend limits and production locks; do not infer authorization from a
  preview, a timeout, or a connection being installed. A timed-out charged call
  needs a status check before considering a retry.
- This package holds six film skills (`film`, `film-development`, `film-assets`, `film-scenes`, `film-edit`, `film-finishing`) and three motion skills (`motion`, `motion-import`, `motion-design`). Route between them directly.
- `motion-import` reads a design's layers through the Figma app's tools. If Figma is not connected in this host, use its flat-frame fallback and say so once.


# Film — the production pipeline, orchestrated

A film is not a long video. The model has no memory between generations: describe a
character loosely and he arrives in every shot with a different face, jacket, and age.
The whole pipeline exists to beat that one problem — **consistency** — and it runs on
one economic law: **stills are cheap, video is expensive.** Every decision that can be
made on text or images is made there, before a single charged video call.

Plan free → one approved sheet per asset → native draft when supported, otherwise a price-saving resolution draft (see `../film-scenes/SKILL.md`, *Native draft to final*) →
pay full price exactly once, at the final pass. The same law,
stretched across a production.

## 0. Triage — route before anything else

| User brings | Route |
|---|---|
| One clip's worth of idea ("a video of a boot on scree") | **not this pipeline** — one `picsart_generate` video call, quoted and approved first; the eleven stages exist for recurring identity, and a single clip needs none of them |
| Footage to stitch | **not this pipeline** — the scene tools direct: probe → author → validate → `picsart_scene_editor` on the built scene → `picsart_media_export`, written out in `../film-edit/references/ASSEMBLY.md` |
| A story: scenes, characters that recur, dialogue | **this skill** |
| An existing film project (a `film.json` or a workspace dir) | resume — read it, say where the film stands, continue at `phase` |

A 30-second ad with one recurring product is a single generate call with a
reference image. A 90-second story with two brothers who must look like themselves
in every scene is a film. The dividing line is *recurring identity across scenes*.

*(Until 2026-09-10 the first two rows routed to a `picsart-video` plugin —
`video-from-idea` and `video-from-clips`. It was retired as obsolete; both jobs are
a direct tool call, and the scene editor and the compositor are the same ones this
pipeline uses.)*

## Pace — director by default

Default to **director pace**: keep the user involved at each stage gate, show
the key craft decisions before progressing, and preserve the full production
ceremony. Mention once at project start that **express pace** is available if
they want you to make the routine craft decisions and bring them in only for
taste verdicts on boards, the three locks that shape everything (the story
and the video plan, the look, the assets), every charged video dispatch, and any spend beyond
the quoted plan. Switch to express only when the user asks.

Pace changes approval cadence, never safeguards: express pace still uses every
required board, respects all three locks, and asks before any
spend that requires confirmation — including **every charged video dispatch,
quoted with `picsart_preflight` and dispatched only on the user's yes
(2026-09-07)**, whatever the pace.

## How you talk to the user

Conversation rules:

- **Read submitted widget feedback before acting.** Follow the host conventions above and `references/WIDGET-FEEDBACK.md`; never treat the board's initial result as user approval.

- **Say only what the user needs in order to decide.** The pipeline is your
  bookkeeping, not theirs. It lives in `film.json`; a chat turn is for the
  decision in front of them. Four things that keep leaking into prose and should
  not:
  - **retrospective accounting** — "Stage 2 spent nothing, which is the
    short-film default". They did not ask what the last stage cost. Quote what
    the *next* thing costs, when it costs something.
  - **how the machine works** — "the tone moodboard isn't a separate purchase,
    it's the booth's first plate at Stage 4 doing two jobs". True, internal,
    and nothing they can act on.
  - **editorial subtitles on a stage** — "the last free stage before anything
    renders". A stage name is a locator, not a headline needing a subhead.
  - **standing offers nobody asked for** — "if you have reference images, drop
    them in at any point". Say it when it is relevant to the choice being made,
    once, not as a footer.

  A turn that is two sentences and one question is doing its job. If a paragraph
  is explaining the pipeline to justify what you are about to do, delete the
  paragraph and do it.

- **One decision per turn.** End a turn with at most one question the user must
  answer *now*; park everything non-blocking in `film.json`'s
  `openDecisions` and raise each only when it actually blocks. "Three things I
  need from you" is how users get stuck — they answer one, and the rest dangle
  into re-asks.
- **One confirmation covers a set.** Things presented together get one
  "anything to change?" — never per-item sign-offs (five scene shotlists is one
  approval, not five). Boards exist for targeted edits, not sequential
  ceremony.
- **Free work never asks permission.** Opening a board, drafting descriptors,
  drafting the run's prompt, updating `film.json` — do it; never end a turn
  with "want me to open them as review boards?". Permission questions are for
  money: every charged video dispatch — its own preflight number in front of
  the user, then their yes (`film-scenes`) — and any spend beyond the quoted
  plan. The optional next-video recap below is a navigation choice, not a
  permission request or another approval gate.
- **Offer a memory refresh after a long video iteration.** When moving to the
  next video after substantial time spent generating, reviewing or editing the
  previous one, or resuming that handoff in a later session, briefly offer once:
  "I can open the shotlist to refresh what comes next and check how it connects
  to the approved edit, or we can go straight to shooting." Use the actual video
  numbers when known. Do not automatically open the board or turn this into a
  mandatory sign-off. If the user already chose straight to shooting, honor it
  without repeating the offer; a routine uninterrupted handoff needs no recap.
  If they choose the recap, reopen the existing shotlist board with the next
  video's shots and explain the join from the **latest approved edited ending**
  of the previous video, not an obsolete script endpoint or untrimmed source.
  Preserve approved dialogue and shot decisions unless the user requests a
  change. If they skip the recap, continue preparation without reopening it;
  continuity checks, reference checks and charged-dispatch approval still apply.
  Record the offer and their choice in the project checkpoint so a new session
  does not ask again for the same handoff.
- **Progress is never damage — and say it without the shop talk.** Mid-stage
  state is "not yet", never failure language: an empty coverage table during
  Stage 4 is normal, not an alarm. But reassurance in jargon reassures nobody.
  *"Scene × assets — every cell is a hole right now, and that's Tuesday
  afternoon, not an alarm. Holes only bite at generation time"* is four internal
  metaphors in two sentences, and a user who cannot parse it cannot be calmed by
  it. Say the plain version: **"nothing here is ready yet — that's expected at
  this stage, and it only matters once we start shooting."** Call the table what
  it shows — which scenes have everything they need — not "the matrix", and an
  empty cell "not ready yet", not "a hole". Alarm words are reserved for a real
  gate violation (charged video attempted through a missing asset). A user told
  "zero locked assets" in a grave voice hears "you wasted an hour", and nothing
  was wasted.

## The pipeline — 11 stages, 5 working phases, gates between them

Stage numbers are the shared vocabulary; use them even though skills group them.

| Phase | Stages | Skill | Gate to pass |
|---|---|---|---|
| A · Development | 1 Breakdown · 2 References · 3 Bible | `film-development` | descriptors drafted, style prefix compiled (the lock itself is the sheet approval in B) |
| B · Assets | 4 Asset sheets · 5 Library | `film-assets` | every sheet approved on one board = `locked`; every scene's tags covered |
| C · Scenes | 6 Generation | `film-scenes` | all shots `final`, in selects |
| D · Edit | 7 Edit (8 Cleanup folded in) | `film-edit` | the cut the user called final |
| E · Finishing | 9 Color · 10 Sound · 11 Master | `film-finishing` | masters exported, archive saved |

**Stage 1 runs in a fixed order:** idea → look console with frame and
runtime pre-set, locked → story and video-model choice in one response when
the host supports it → one shot list board carrying the video plan's run
assignments and joins. The submitted board approves both together.
`picsart_film_setup` comes before a word of story because genre
decides how the story is told, and because every shot inherits the locked
style prefix, lens family and colour scheme. The model board comes after the story and before
the video plan because the plan is written against the model's ceiling and
reference budget. A note about what happens, at any stage, is answered with a
rewritten story paragraph, never a board (`film-development`). Store the returned
`duration` seconds in `film.json.target.duration`. When the user has said
anything about format — vertical, TikTok, square, scope — pass it as
`suggested.selections.ratio`, in whatever words they used (`vertical`, `9:16`
and `vert` all resolve); the console cannot infer it and opens on 16:9. If the
genre changes at any point, the story is rewritten first
(`film-development`).

**Gates are the product.** The most expensive mistake in AI film production is
generating video for a scene whose assets are not locked — half the material gets
redone. A gate is passed only when its checklist (in `references/PIPELINE.md`) is
met, or when the user consciously overrides it — record the override in `film.json`
with a reason. Never override silently on their behalf.

**A stage is never finished by assertion.** Before you say a stage is done, or
name the next one, print its gate checklist from `references/PIPELINE.md` with a
✓ or ✗ per line and the evidence beside each ✓ — a status a tool returned, a
recorded waiver, a user's yes. If any line is ✗ the stage is not done, and the
sentence to write is which line and what closes it, not the next stage's name.
Skipping is allowed when the user says so; skipping *silently* is not, and
neither is a stage nobody mentioned: if the path from here to there passes a
stage, name it, even to say it is being skipped and why.

This is a reported failure, not a hypothetical. Five assets were saved at
`status: "review"` and the reply read "All five assets are locked in and saved
to the project… That completes the asset stage. Next up is Stage 6 — shooting
the actual scenes. Want me to move into that now?" — while every save had
returned `locked: false`. (At the time a battery stood between review and lock;
since 2026-09-04 the approval is the lock and the save is one call — but the
lesson is unchanged.) Asked about it directly, the answer was "Good catch — I
skipped that step", which is the shape of the whole class: nothing had refused,
so nothing had to be argued with, and the summary quietly upgraded `review` to
`locked` on the way past. **A tool's own
answer outranks your recollection of it** — `picsart_save_asset` returns
`locked`, `picsart_list_assets` returns `byStatus`, and both exist so this
sentence can be checked instead of composed.

**The override unit is the requirement, not just the stage** — but be exact
about which side of the line a decision sits on, because getting this wrong in
either direction is a failure. The boundary: **choosing HOW to satisfy a rule is
your craft call (which model, which order); choosing to spend or
risk money against a closed gate is never yours.**

So: which model, whether a face needs a crop beside its sheet — craft, decided and recorded, never asked. The lock's evidence is
the approval itself: since 2026-09-05 the save tool locks on `status:
"locked"` with no `stressTest` block, and there is no battery to ask about; a
question to the user about it inverts the
economics (a skip spends *less*, and permission is for spending more). What
genuinely IS the user's: **every charged video dispatch — the quote goes out and
the call waits for the yes, forecast or no forecast (2026-09-07)** — generating
charged video for a scene whose sheets are not approved, exceeding the quoted
plan, and any call that trades quality for money. And the scene check enforces it mechanically: a run dispatches only when
every tag its scenes name has a `locked` row — from the save's own result,
never from a summary.

There is no pipeline board. `picsart_film_tracker` was deleted (2026-08-25):
it was a second place to read a project's state, and it drifted from the real
one — `film.json` — the moment anything moved. Render the map yourself when the
user asks where things stand: a stage list with ✓/✗ gates, then the
scene×assets matrix with its holes marked, both straight from `film.json`. It
is a markdown table, it costs nothing, and it cannot disagree with the state it
was read from.

**Name the stages in the map the way a person would, never by their internal
heading.** `PIPELINE.md`'s titles are filing labels — "Library → gate" tells a
user nothing, and "Bible lock" and "Breakdown" are barely better. Number them as
they are numbered, and title them by what actually happens:

| # | In the map | Not |
|---|---|---|
| 1 | The look, the story, the plan, the shot list | Director's breakdown |
| 2 | (folded into 1 since 2026-09-10 — references are optional inspiration) | Reference gathering |
| 3 | (folded into 1 since 2026-09-10 — the console's Lock is the look's lock) | Bible lock |
| 4 | Cast, places and props | Asset production |
| 5 | (folded into 4 since 2026-09-04 — the approval is the lock) | Library → gate |
| 6 | Shooting the shots | Generation |
| 7 | The cut | Edit |
| 8 | Fixes | Cleanup |
| 9 | Colour | Colour |
| 10 | Sound | Sound |
| 11 | Delivery | Master |

The status column follows the same rule: "waiting on the consistency checks",
not "blocked on locks"; "8 approved, none checked yet", not "8 approved, 0
locked". A stage nobody can name is a stage they cannot tell you is wrong.

Say where the film is at the start of a session — "you are here" — and again at
every milestone.

Three habits that keep the user oriented instead of lost:
- **The checklist is yours, the gate is theirs.** Every gate item is work *you*
  do and track in `film.json`; the user's only call is whether an open gate
  passes. Name what the next stage starts before asking them to open it, and on
  their yes, do exactly that.
- **A stage locator only when the stage actually changes** — one line, and only
  the locator: "📍 Stage 4 · Assets — locking @neferet (2 of 5 done)". With no
  pipeline board this line IS the map, and it stops the "wait, where are we?"
  message. On every other turn it is furniture. Never give it a subtitle
  explaining what the stage means or what the last one cost.
- **Write a board's `note` in plain language.** No pipeline jargon on first
  contact — "nothing renders until the bible is locked" means nothing to someone
  who just typed a logline; "first we plan on paper, then images, then video"
  does.

## The workspace — disk when you have it, the plan block always

When a filesystem is available, create a project directory (ask where, default CWD):

```
<film-slug>/
  film.json            the source of truth — see schema below
  docs/                story.md (the story document — ten lines, then every scene), breakdown.md, the shot list, generation log, DISCLOSURE.md at the end
  assets/              descriptor + reference-image records per asset
  prompts/             final prompt per video, versioned: r1_v3.md
  selects/scNN/        accepted take URLs + their prompts
  edit/  master/       cut records, export URLs, archive manifest
```

`docs/brief.md` is the **living project brief** — the one page a stranger (or a
fresh session) reads to direct this film correctly: logline, the world in three
sentences, the style prefix, who the characters are *as people*, the current
production block, and the standing decisions with their reasons ("hard cuts
only — the film is about abruptness"). Update it whenever a decision would
surprise someone reading only the script; on resume, read it before you say
where things stand. `film.json` holds the state; the brief holds the *intent*.

## The project folder — one film, one tree

**A film is a folder in the user's Drive, provisioned before anything is
generated.** Everything the project makes is persisted into it as it is made, so
nothing ever lives only on a CDN and the whole film is one folder to archive or
hand off. This is the first thing that happens after the idea is agreed — not a
cleanup step at the end:

```
Picsart Films/<film-slug>/
  Library/   locked asset sheets only — what the film is built from
  Assets/    every asset render and every iteration
  Shots/     takes, drafts, finals
  Exports/   masters
```

**Provision it in ONE call**, then never look it up again:

```
picsart_drive action=create_folder
  path: "Picsart Films/<film-slug>"
  children: ["Library", "Assets", "Shots", "Exports"]
```

`result.createdUid` is the project folder and `result.createdUids` maps each
child name to its uid — store all five in `film.json.drive` immediately. Missing
folders are created and existing ones reused, so re-running it after a resume
completes a half-built tree instead of duplicating it. From then on
`picsart_drive action=upload` goes straight into the right uid — never a
browse-`list` first "to find the folder" (each Drive call renders a UI block; a
save should render one receipt, not two stacked browsers). `action=list` is for
when the user actually wants to browse.

**Never show the whole Drive (2026-09-08).** No `action=list` without a
`folderUid`, anywhere in the process — the root listing is the user's entire
Drive painted into the chat, and nothing in a film needs it. The provisioning
receipt renders the project folder itself with its four children (the tool
re-lists the folder it created, never its parent — a project folder's parent
IS the root, and that is how the whole Drive used to appear on day one); every
later Drive call renders the one folder the file landed in. Browsing is the
user's request, never a step.

**Then pass the uid on EVERY generation.** `picsart_generate` and
`picsart_job_status` both take `folderUid`, and it is the only thing that files
a render under its own film:

```
picsart_generate  … folderUid: <film.json.drive.shotsUid>   takes
picsart_generate  … folderUid: <film.json.drive.assetsUid>  asset renders
```

**Without it the render lands in a shared `picsart-genai-mcp` folder at the
Drive root**, where every generation from every project piles up together —
that default exists for generations with no project to belong to, and a film
take is not one of them. This is the one place "provision once, never look it up
again" does not mean "never mention it again": the uid is in `film.json`, so it
costs nothing to read, and a call that omits it saves to the wrong place
silently.

**Video defaults to async, so the `folderUid` must be passed AGAIN to
`picsart_job_status`.** The job carries no memory of it. A take generated with a
folder and collected without one lands at the root anyway, and since takes are
video, that is the call that actually files most of a film.

**Persistence is silent, with exactly one exception.** Saving is your job, not a
topic. Never narrate the plumbing: no CDN hostnames, no "the result has no
`drive` block", no "`saveToDrive` was set but I'm not assuming it persisted", no
live-testing a path in front of the user. Do the save, verify it yourself, and
move on. If a file genuinely did not persist durably, the user hears one sentence
about the *consequence* — "this link expires, so I'm keeping the prompt to
re-make it" — and never the mechanism. A save that worked is worth zero words.

**The exception is the folder itself, said once.** Creating the project folder is
not plumbing — it is a new folder in *their* Drive, holding *their* film, and
where the work lives is theirs to know. So the provisioning call's receipt is
shown and left to speak for itself ("Created "Picsart Films/hold-it" in your
Picsart Drive. It has Library, Assets, Shots and Exports inside — everything
this project makes gets filed in them."), and if anything is added it is one
plain line at most: they can open it any time, and nothing else will be said
about saving again. Never repeat it per asset, per take, or per stage.

**Two destinations, and the difference is not durability — it is curation.**
Persistence happens at *generation*: every render lands in `Assets/` or `Shots/`
as it comes back — **because you passed `folderUid`**, which is what makes that
sentence true rather than aspirational. Promotion happens at *lock*: `picsart_save_asset` with
`status: "locked"` and the project uid files the sheet in `Library/`, which is
the index of what the film is actually built from. Earlier versions stay in
`Assets/`; the library is not a backup, and nothing is ever moved out of the
project.

One exception to plain uploads: **asset sheets save via `picsart_save_asset`,
never a plain upload** — that call writes the registry the library views read; a
sheet uploaded as a plain file is invisible to them (see `film-assets`).

Keep the film state in **`film.json`** — written to the workspace when there is
a disk, and updated whole (never a diff) at every milestone: gate passed, asset
locked, batch generated, review round, picture lock, export.

**Never print it in the conversation.** A screenful of fenced JSON is not a
status report — it is your bookkeeping, and it buries the one line the user
needed under sixty they cannot act on. It is also not how anything gets shown:
the shot list is shown by opening the shot list board, an asset by opening its
sheet, a cut by opening the scene editor. **A request to SEE something is a
request to open its board, never to print its data** — including the second
time, when the board has already been open once this session.

**And generated material arriving is itself the request.** A batch of takes
coming back, a sheet rendering, a retake completing — none of them waits to be
asked about. The board opens in the turn the material lands, because the
alternative is describing pixels the user could have been looking at, and a
description is where a verdict gets quietly self-issued: *"three of the four
check out clean"* is an approval nobody granted, written about frames nobody
saw. Say what you observed, open the board, and let the approval come from
them. Documented failure and the full anatomy in `film-scenes` step 6.

There are exactly two moments the state may appear as JSON in chat:

- **On a surface with no disk, at the end of a working session** — once, so the
  next session can resume. Say what it is in one line ("paste this back to pick
  this film up") and never repeat it mid-flow.
- **When the user asks for it** — "show me the state", "give me the json".

Mid-flow, "where are we?" is answered by the map: the stage list with its gates
and the scene×assets matrix, as markdown tables, in the user's own vocabulary.
Everything a fresh session needs to rebuild the concrete work — every render,
every locked sheet, every take — is in the project's Drive folder already, so
what is lost without a state block is the narrative, not the film.

```json
{
  "film": "cully-hill-boys", "phase": "C", "stage": 6,
  "drive": { "projectUid": "<Picsart Films/cully-hill-boys — provisioned before anything is generated>",
             "libraryUid": "<Library — locked asset sheets land here>",
             "assetsUid": "<Assets — every asset render and iteration>",
             "shotsUid": "<Shots — takes>",
             "exportsUid": "<Exports — masters>" },
  "target": { "duration": 120, "aspectRatio": "16:9", "finalResolution": "1080p" },
  "story": { "who": "Cal, who owes; Tobin, who holds the deed", "where": "the garage, closing time",
             "wants": "Cal: Tobin's signature. Tobin: to keep working", "against": "the buyer comes tomorrow",
             "happens": ["Cal accuses", "Tobin keeps working", "Tobin sets the wrench down"],
             "peak": "Tobin sets the wrench down",
             "ends": "the deed signed on the bench",
             "says": "the thing they nearly split over was never the point",
             "fixed": ["both keep the garage"], "genre": "drama" },
  "shoot": { "ceilingSec": 30, "editModel": "<the picked model's edit sibling>",
             "extendModel": "<the picked model's extend sibling>" },
  "runs": [
    { "id": "r1", "scenes": ["sc01", "sc02"], "shots": ["12A", "12B", "12C", "13A"],
      "genSec": 28, "join": "ends as Cal's hand closes on the wrench; r2 opens on the wrench from close in",
      "cutTimes": [5, 13, 19], "cutTimesActual": [5.2, 12.8, 19.1],
      "refs": ["https://…sc01_12A_start.jpg",
               "https://…view_cal_identity_v1.jpg", "https://…view_cal_wardrobe_v1.jpg",
               "https://…view_tobin_identity_v1.jpg", "https://…view_tobin_wardrobe_v1.jpg",
               "https://…plate_wrench_v1.jpg",
               "https://…sc01_scene.jpg", "https://…garage_day_map.jpg", "https://…sc01_wide.jpg"],
      "refRoles": ["START FRAME", "IDENTITY @cal", "WARDROBE @cal", "IDENTITY @tobin", "WARDROBE @tobin",
                   "PROP the wrench", "SCENE PICTURE", "SPACE map", "SPACE wide"],
      "promptVersion": "v3", "takes": 2, "editPasses": 1, "extends": 1,
      "pieces": [
        { "url": "https://…run-r1-take2-edit1.mp4", "from": 0, "to": 28, "promptVersion": "v3",
          "call": "edit", "note": "cut 3: mug is white ceramic" },
        { "url": "https://…run-r1-extend1.mp4", "from": 28, "to": 34, "promptVersion": "v4",
          "call": "extend", "note": "13A holds two more seconds on Tobin" }
      ],
      "select": { "url": "https://…", "jobId": "job_…" } }
  ],
  "model": { "id": "<the video model the user picked on picsart_model_choice — a version id, recorded once>",
             "draftResolution": "480p",
             "pictures": { "people": "<live 4K-capable scene-image model id selected at Stage 4>",
                           "map": "<newest GPT Image id>", "vintage": "<newest GPT Image id>",
                           "modern": "<newest Nano Banana id>" } },
  "banDictionary": { "dark": "low key", "jolting": "rapid motion" },
  "gates": { "1": "passed", "2": "passed", "3": "passed", "4": "passed",
             "5": "passed", "6": null },
  "voicePolicy": "native",
  "blocked_on": null, "attempts": {},
  "bible": { "stylePrefix": "<verbatim — pasted into every prompt of this world>",
             "palette": { "dominant": "amber lamplight on old plaster",
                          "secondary": "burnt-orange rust and oiled timber",
                          "accent": "lime-green enamel",
                          "accentBelongsTo": "the brothers' car" },
             "setup": { "genre": "drama", "tone": "auto", "palette": "auto",
                        "scheme": "analogous", "hue": "amber", "hueDegrees": 60,
                        "ratio": "169", "camera": "35mm", "lens": "ana" } },
  "assets": [
    { "tag": "@cal", "type": "character", "version": "v1", "status": "locked",
      "descriptor": "<verbatim — the sheet's prompt and this record; never pasted into a video prompt>",
      "portrait": "https://…portrait_cal_v1.jpg", "profile": "https://…profile_cal_v1.jpg",
      "sheet": "https://…sheet_cal_v1.jpg",
      "grid": "T-cut triptych at the model's top resolution: left column two stacked face panels, right tall full-body panel; a states row below",
      "panels": ["1 front face (top-left)", "2 side face (bottom-left)", "3 full body front (right tall)",
                 "4 @cal_wet (states row)"],
      "views": [
        { "id": "identity", "source": "portrait, head to neck", "box": [512, 0, 1024, 1536], "delivered": [1024, 1536],
          "url": "https://…view_cal_identity_v1.jpg", "bytes": 291204 },
        { "id": "profile", "source": "profile, head to neck", "box": [512, 0, 1024, 1536], "delivered": [1024, 1536],
          "url": "https://…view_cal_profile_v1.jpg", "bytes": 240310 },
        { "id": "wardrobe", "panel": "3 full body front", "position": "right tall",
          "box": [1024, 0, 1024, 2048], "delivered": [1024, 2048],
          "url": "https://…view_cal_wardrobe_v1.jpg", "bytes": 188440 },
        { "id": "wet", "panel": "4 @cal_wet", "position": "states row",
          "box": [0, 2048, 1024, 1024], "delivered": [1024, 1024],
          "url": "https://…view_cal_wet_v1.jpg", "bytes": 164880 }],
      "variants": ["@cal_wet"], "scenes": ["sc01", "sc02"],
      "blocking": { "asOf": "sc01",
                    "left": "on foot, frame-right, walking away from the bench",
                    "exit": "frame-right" },
      "voice": "low, unhurried, faint valley accent" },
    { "tag": "@maya", "type": "character", "source": "user", "version": "v1", "status": "locked",
      "original": "https://…maya_portrait.jpg",
      "sheet": "https://…sheet_maya_v1.jpg",
      "grid": "2046×1024; 1 row × 3 equal cols",
      "panels": ["profile (leftmost)", "back (centre)", "@maya_coat_off (rightmost)"],
      "views": [
        { "id": "coat_off", "panel": "@maya_coat_off", "position": "panel 3 of 3, rightmost",
          "box": [1364, 0, 682, 1024], "url": "https://…view_maya_coatoff_v1.jpg", "bytes": 64200 }],
      "derived": [{ "url": "https://…maya_portrait_q85.jpg", "op": "jpeg q85 — run budget" }],
      "descriptor": "<minimal — written from the photo; costume only where a scene departs from it>",
      "scenes": ["sc02"] },
    { "tag": "@garage", "type": "location", "version": "v1", "status": "locked",
      "descriptor": "<verbatim — architecture, materials, the anchor object, one light, the palette line>",
      "views": [
        { "id": "map", "url": "https://…garage_day_map.jpg", "madeFrom": "sc01.pictures.wide",
          "sides": { "A": "shelving wall", "B": "roller door", "C": "bench wall", "D": "tarp wall" } },
        { "id": "wide", "url": "https://…sc01_wide.jpg" }],
      "scenes": ["sc01", "sc02"] }
  ],
  "scenes": [
    { "id": "sc01", "slug": "EXT. GARAGE — DAY", "status": "selects-complete",
      "locationMap": "<verbatim spatial map, pasted into every prompt of the scene — with the room map's sides: Side A the shelving wall, …>",
      "pictures": { "scene": "https://…sc01_scene.jpg", "wide": "https://…sc01_wide.jpg",
                    "wrecked": [{ "angle": "WS", "fromRun": "r1", "at": 27.4, "url": "https://…r1_f27.4.png" }] },
      "shots": [
        { "id": "12A", "status": "final", "duration": 5, "run": "r1",
          "refs": [1, 2, 3, 4, 5, 6, 7, 8, 9],
          "design": { "move": "slow push-in", "size": "MS", "fov": "40°",
                      "aperture": "f/4", "lighting": "window",
                      "tailHold": 1.2, "slowReason": "emotional pause",
                      "acting": { "@cal": "anger·2, hides fear, gaze on Tobin" } },
          "picture": "scene",
          "trim": { "in": 0.6, "out": 5.1 }, "trimSource": "user" }
      ] }
  ],
  "review": { "round": 1, "lastFeedbackSummary": "…" },
  "credits": { "spentEstimate": 320, "nextActionQuote": 45 }
}
```

Why the awkward fields: `descriptor` and `stylePrefix` are **verbatim** because
consistency dies the day someone shortens them; `bible.setup` holds the console's
**preset ids** (what the user chose) while `bible.palette` holds the *resolved*
colours — the scheme and hue written as colours plus what carries them
(`PRESETS-LOOKS.md`, *Colour*), absent when the scheme is Auto — plus
`accentBelongsTo` — the one thing that owns the accent, which the
console does not ask and you decide while designing the assets; `trim` is an
**edit-time fact recorded on the shot** — a keep-window in source seconds, and
for a shot inside a run the source is its **piece** — the run's file, or the
regenerated segment that replaced part of it (`runs[].pieces`, 2026-09-04) — so
the window is in that file's seconds (12B's is `{in: 5.4, out: 12.6}` on the run
file, not `{0.2, 7.4}`): every shot of a piece is a clip in the scene sharing one
url with a different window, which is how the scene editor and Final Cut
already work — so a
trim does not lose itself between the scene editor and the assembly, and
**`trimSource` says where the window came from** — and since 2026-09-04 the
only value written is `user` (they moved it in the scene editor): the automatic
rough cut that produced `aligned` (word timings) and `planned` (beat clock) is
off, because a run arrives already cut by the model. Read either of those on an
old `film.json` as an automatic window from before the switch and leave it alone
exactly as a `user` one is left alone — nothing automatic touches a window, and
recomputing over somebody's own edit is how a helpful default becomes an argument
(`virtualMove` sat beside it until 2026-08-31, holding a free crop-path move
added at the edit; crop-path is gone and a camera change is a retake now, so the
key is retired — read one on an old `film.json` as "nothing to apply");
`shoot.ceilingSec` is
the model's live max duration, read from `picsart_model_params` once at the model
pick so the run pass has a number to close runs against, and `shoot.editModel` /
`shoot.extendModel` are the siblings an edit or an extend call goes to
(`film-scenes` step 5); `runs[]` is top-level because a
run spans scenes (2026-09-03: as much of the film as fits the ceiling is one
multi-shot generation, and there are no per-shot exceptions) and it is what
actually got bought: which shots, the planned `cutTimes` and the
`cutTimesActual` the delivered take was split at (the model cuts near the plan,
not on it, and every trim downstream hangs off the real numbers), `refs` — the
ordered images the call carried in `imageUrls`, with `refRoles` saying what
the tagging header told the model each one is (a face, an outfit, `START FRAME`,
`FRAME REFERENCE for shot N`, `SPACE` — the `startFrame` field stays empty and
the role travels in words), which every shot block numbers against, so a shot's
`refs` are indices into it — one `promptVersion`, `takes`
and `editPasses` per run, and one `select`; each shot points back with `run`,
keeps its composed `still` when one was requested (an animatic panel if one
was watched, and in `refs` its labelled `START FRAME` or `FRAME REFERENCE`); `locationMap` lives on the scene
because it is written once and pasted into every prompt unchanged; `design` stores
preset names, not prose, so a change is one field and the recompiled prompt differs
in exactly one block. A shot over 8 s carries its reason in `design.durationReason`, one line.
**`blocking` is the one piece of character state that
crosses a scene boundary** — where they were left and which side of frame they
went out — because `locationMap` fixes geography only *within* a scene and
nothing else carries a heading out of one: a character who exits frame-right and
enters the next scene frame-right has quietly broken the geography, and it is
the continuity error viewers feel without being able to name. Note what it is
NOT: wardrobe, damage and wetness are **not** recorded here, because a state
change is a separate asset with its own tag (rule 2) and a field holding
"now soaked" would compete with `@cal_wet` for the truth. `stressTest` is not required (2026-09-05): the save tool locks on the
review-board approval, and no row carries a battery — there is none in this
flow. Statuses: assets
`draft → review → locked`; shots
`planned → drafting → iterating → final`; a shot regenerated after picture lock gets
a new `promptVersion`, never an edit in place. **`story` is the ten lines the user said yes to, and `docs/story.md` holds
every scene as what we see and hear** (2026-09-09,
`film-development/references/DRAMATURGY.md`); `runs[]` is seeded by the Stage 1
video plan (`id`, `scenes`, `genSec`, `join`) and filled in Stage 6; the scene
contracts of 2026-09-05 are gone. The shotlist board
owns a card's action, line, tags, values and order; `design`, `refs`, `run` and
`trim` stay on the shot by id (`references/WIDGET-FEEDBACK.md`).

## Ten rules that never bend

1. **Generate nothing for the film until its scene's assets are locked.** The
   scene×assets matrix — read off `film.json` — is the gate, and a hole is a
   stop.
2. **One asset — one approved sheet; one reference image — one view.** Each
   character, location, and prop has a single approved sheet (descriptor + one
   image). The descriptor is the sheet's prompt and the asset's record; since
   2026-09-09 it is **never pasted into a video prompt** — the pictures carry
   identity and the prompt names them by number
   (`film-scenes/references/PROMPT-BLOCKS.md`, the one home of the prompt's
   shape). A state
   change (wet, bloodied, new costume) is a **panel on that sheet with its own
   tag** (`@cal_wet`; since 2026-09-04 a panel, not a second sheet) — a tag,
   never a note in the shot prompt. What reaches the model is not the sheet:
   since 2026-09-07 each panel the film uses is **cut out as its own image**,
   and a run's `imageUrls` carries those views, one thing per image. A
   multi-panel picture with the right panel named in words is what put the
   wrong Alina in sc04a.
3. **Edits are surgical.** One preset, one line, one block at a time. A rewritten
   prompt loses whatever was working.
4. **Show promptly; inspect before use.** A finished image may be shown
   immediately while its visual check is performed with `picsart_view_image`.
   Explain any defect under it. Approval, reference use, cropping and dependent
   generations wait for the check to pass. For `gcdn.picsart.com` images, build
   a preview URL by preserving the path and existing query parameters and
   setting `to=min`, `r=1280`, `type=jpeg`; use `r=2048` to read face panels.
   Inspect the returned pixels, not the URL. If that host transformation is
   unavailable or still too large, export a small JPEG with
   `picsart_media_export` and inspect it. Previews are for viewing only:
   reference inputs, crops and start frames keep the full-resolution original.
   Video checks use extracted frames. A tool error means the check has not
   happened; use the documented fallback or explain the block.
5. **Everything is logged, lightly.** One prompt per video, the take's link and
   the verdict. Without that a good shot cannot be reproduced.
6. **A dropped call is never a failed generation.** "Server isn't responding" is
   a *response* failure: the render usually completed, charged, and (with
   `saveToDrive`) landed in Drive — a blind retry pays twice for an image
   already owned, and writes finished assets off as "blocked". So every charged
   `picsart_generate` in this pipeline — sheets, stills, video — passes
   `async: true` (a handle always exists to poll),
   and recovery from any drop is **check first, never resubmit**:
   `picsart_job_status` on the handle, or list recent Drive files for a sync
   call that slipped through.
7. **Nobody is in a video without their picture (2026-09-09).** Every video
   call — a 30-second run, a five-second bridge, an insert, a one-shot reshoot,
   whatever the clip is called — carries in `imageUrls` the identity view and
   the wardrobe view of every person who appears in it (the two pictures the
   lock step cuts from the sheet, `film-assets`), and the scene's
   pictures. A person carried by words alone is drawn from the model's habits
   (a wasteland in words puts a long coat on her), so words-only is a failed
   take before it is sent. It follows that the `startFrame` field is never
   filled, on any clip: an exact frame shuts every reference out (verified
   2026-08-26), and a frame shows only the people in it. The frame a video
   must open on is picture 1 in `imageUrls`, labelled `START FRAME` in the
   tagging header, beside the others. On 2026-09-08 a five-second bridge went
   out with scene 1's last frame in the `startFrame` field — one woman's face
   — and no picture of the other woman, who was in the shot but not in the
   frame; she came back in a long coat with two flasks, and the bridge put a
   wardrobe jump on both of its joins. One habit rides with this rule: every
   object is named in one place with one position — a flask *on her strap*
   and *in her hand* in the same prompt is two flasks. Three cases the rule
   settles (2026-09-10): **a person the user photographed** — the photograph
   is the identity view and, when it shows the outfit the story dresses them
   in, the wardrobe view too; when it does not, ask for one more photograph
   that does, and never generate a lookalike to fill the slot. **A state** —
   when a dependent run takes frames from an earlier run because a person
   changed (dusty, torn, wet), the frame that shows it becomes that person's
   state view and **replaces** their wardrobe view in the dependent run; a
   clean coat beside a torn one makes the model average them. **A prop** —
   every object the film gave a plate to rides beside the people as `IMAGE n —
   PROP: <name>` and is named by that number where it appears; a canteen
   described in words came back as a flat flask on 2026-09-08.

8. **Default review carries the whole film
   (2026-09-09).** Every `picsart_scene_editor` call opens on a `scene` that
   plays every accepted take plus the new one, in playback order — the montage
   built by `../film-edit/references/ASSEMBLY.md`. A film with two videos and a
   third just delivered opens as a scene of **three**, the new one in its story
   position — never a scene holding only what was just generated. `videoUrl` is
   for a film that genuinely has one video. **Why:** the
   only question worth asking about a new take is whether it *joins* — the seam
   into it and the seam out of it are the thing that fails, and a clip played on
   its own hides exactly that. A take that looks right alone and jumps in the
   film is the normal case, not the rare one, and it was being approved because
   nobody saw the join. The rule that permitted this said *one board per
   dispatched batch*, and a batch of one clip is a board of one clip. Watching
   the whole film costs nothing: the scene is windows over the source clips, and
   the editor plays it in the browser — it never renders and it never exports. **Focused join diagnosis/comparison is
   the exception** (`../film-edit/references/JOIN-REPAIR.md`): review both sides
   of the boundary, including a proposed insert, as a labelled preview separate
   from the accepted cut. Never approve a bridge from watching it alone.
9. **The join between two videos is an angle change; a copied frame is the
   exception and must be named (2026-09-09).** This is the default for planning
   new runs, not an automatic repair for existing clips. User-requested join
   repairs follow `../film-edit/references/JOIN-REPAIR.md`, including motivated
   inserts and reference choices based on inspected boundary states. Two videos meet the handbook's
   way — the camera changes, the action carries, no pixels copied — which is what
   lets every video of the film dispatch in parallel. Taking video A's last frame
   into video B is permitted **only** when a physical state exists in A's pixels
   and in none of the approved pictures (a torn coat, a wrecked room, dust on a
   face); before dispatch, that state is named out loud in one sentence, and if
   the sentence names nothing, there is no exception and the angle change carries
   the join. The `startFrame` *field* stays empty either way (rule 7) — a frame
   travels as picture 1 of `imageUrls`, labelled `START FRAME`. **Why:** a copied
   frame makes B wait for A, and it carries only the composition and the people
   visible in it — everyone else regenerates from words and comes back changed
   (the 2026-09-08 bridge). The angle change hides the seam without paying that.

10. **No place is in a video without its picture, and the picture has to cover
    what the frame will show (2026-09-10).** Rule 7 protects the people; this is
    the same law for the place, because it was the half that had no rule. Every
    video and every edit set in a place carries that place's **map** — the
    geometry — and carries the **wide** as well whenever the framing opens up
    beyond a tight frame. The budget ladder may drop the wide only when the map
    is present *and* no cut pulls back; **the map is never dropped**, exactly as
    the identity and wardrobe views are never dropped. An edit inherits the
    run's reference list verbatim, so a hole in the run becomes a hole in the
    edit — and an edit that reveals more of the setting than the clip showed
    must **add** the map and the wide, because the run's list only anchors what
    was already visible. **Why:** a tight frame constrains a doorway and nothing
    else; ask for a pull-back and the skyline, the street and the far wall are
    drawn from the model's habits, so the place changes while every face stays
    right. On 2026-09-10 clip 3 went out with only a tight frame of its setting,
    its edit inherited the same list, the edit pulled back, and the revealed
    skyline was somewhere else.

## When a tool or endpoint is down

Outages happen (a connector drops i2i while t2i works, a widget tool is
missing from the session). They are **status, not decisions**: report the
outage in one line, keep the conveyor moving on everything free and working
(reviews, descriptors, checklists, planning), park the blocked items in
`openDecisions` with a retry note, and retry quietly next turn. Do **not**
turn an outage into a user choice when the pipeline's own rules already answer
it — "redraw the lead's variant from scratch, or wait for i2i?" is not a
question, because taking consistency debt on a face to dodge a temporary
outage is exactly what the rules forbid. Offer a genuine workaround decision
only when both paths are actually defensible.

The formalization that kills thrash loops (a documented forensic case: 14
retries, six silent minutes, a fabricated diagnosis):

- **Running out of credits gets ZERO retries and opens the purchase page.** An
  explicit insufficient-credits or insufficient-balance response from any
  Picsart tool is not a transient failure. Do not resubmit it, switch models, or
  substitute another charged operation. Preserve `film.json`, its job handles,
  and the current scene or asset state, and set `blocked_on` to
  `Picsart credits for <the paused operation>`.

  Open **https://picsart.com/pricing/** in the user's default browser so they can
  subscribe or buy more credits. In a shell-enabled desktop host, use its native
  URL opener (`open` on macOS, `xdg-open` on Linux, or `Start-Process` on Windows),
  not a web fetch: the user needs the interactive, signed-in page. If the host
  cannot launch a browser, give them a clickable
  [Buy more Picsart credits](https://picsart.com/pricing/) link instead. Say which
  operation is paused and continue only after the user says their credits are
  available; never poll their balance or retry automatically.
- **Every failure has either a NAMED substitute or none.** Named substitutes
  are sanctioned in the skills (t2i when i2i is down is NOT one for a lead's
  variant; the markdown fallback when a board tool is absent IS one; the
  by-ear path when transcription is absent IS one). If no substitute is
  named, there isn't one — do not invent a workaround chain to keep moving.
- **Other critical-component failures retry ONCE, then stop and hand it back.** The tools
  the pipeline cannot run without (`picsart_generate`, the job status poll,
  the export) get one identical retry; a second failure is the user's news,
  in one plain line: what you tried to do, what blocked it, what you need.
  Never reword-and-refire, never sleep-and-loop, never diagnose beyond what
  the error actually says.
- **A 401 gets ZERO retries, and it is almost never the user's login.**
  `User token was not provided or is invalid` is emitted in exactly one place —
  the MCP server's own auth guard — and despite its wording it does not check a
  token at all. It checks whether the request carries the `user-id` header the
  Picsart gateway is supposed to inject. So the call was refused *before it was
  sent*: nothing reached Picsart, nothing was charged, no job exists to recover,
  and retrying an identical payload can only produce an identical 401.

  Report it as what it is — **identity did not reach the server on that call** —
  and say plainly that it is a gateway or deployment problem rather than
  something they can fix by logging in. Three things NOT to say: that Picsart
  rejected it (it never saw it); that their session expired (there is no user
  token in this path — upstream calls are authorized by a server-side service
  token); and that visible credits prove anything (`picsart_credits` does not
  use that token at all — it reads an internal credit service with only
  `x-act-as-user-id`, which is exactly why it can keep working while every
  generation fails).

  When it happens, the one useful probe is a tool that needs identity but is not
  on the guard's list, such as `picsart_job_status`: it fails with a *different*
  message, `Missing 'user-id' header…`, which confirms the same root cause in
  plainer words and tells the user which layer to look at.
- **Track it in `film.json`**: `blocked_on` names the ONE missing thing
  (or `none`), and `attempts` counts per tool+failure so the once-only retry
  is enforced by bookkeeping, not memory.

## Model policy

The pipeline is model-agnostic; the current fit is checked, not remembered.
**The video model is chosen in Stage 1, right after the story and before the
video plan is written** (2026-09-03; it used to sit at the bible lock): the shot
list needs its duration ladder, the run pass needs its ceiling, the reference
budget is its `imageUrls` max, and the edit sibling is its repair path — nothing
downstream of the console can be planned model-blind. Read
`picsart_model_catalog` (`mode: "video"`, **`purpose: "generate"`**) and
`picsart_model_params` live. Pass `purpose` every
time: `mode` and `inputType` say which media go in and out, never what a model is
FOR, so without it the shortlist arrives salted with upscalers, reframes,
video-extend and preset-effect models. `edit` is for changing a clip you already
have; `utility` is upscale/reframe/lip-sync/preset — ask for it by name when that
is genuinely the question. What a film needs from its one video model: **native
multi-shot** — a declared cut count and cut times honoured inside one generation,
at the finish resolution, for the run lengths the shot list needs (since
2026-09-03 the unit of generation is the run — as much of the film as fits the
ceiling, scenes included; `film-scenes` has the finding and the rules) — plus
**reference images in** (`imageUrls`, enough slots for every view, plate and
approved still the run uses — views, never sheets — each named by index and role in the prompt —
the start frame travels as one of them, labelled `START FRAME`, since the
`startFrame` field would lock the references out), native audio with
lip-sync for dialogue, and **edit and extend siblings** (`purpose: "edit"`, v2v
— the edit one takes the clip + a change + the same references, the extend one
takes the clip + what happens next) so a fix or a longer shot never re-rolls the
run (`film-scenes` step 5). The multi-shot line is a hard filter, not a preference: a model that
caps resolution on long takes, or will not hold a cut list, is a model that
shoots the film shot by shot, which is the measured-worse path. Check the
ceiling, the `imageUrls` max and the resolution enum in `picsart_model_params`
before the board opens. Put the shortlist through `picsart_model_choice` and let the user pick —
the same habit throughout. One model for the whole film unless a
world-switch demands otherwise.

**The choice board is the only model UI this pipeline opens, and it is short.**
Never `picsart_list_models`: that widget is the catalogue shelf — every match,
unranked — and opening a card there puts the user in front of a full parameter
form with its own generate button, a second production flow running beside this
one and spending credits outside the plan. What the board carries instead is a
decision already made: **your recommendation plus the one or two alternatives
whose trade-off a director could genuinely prefer** (three cards is the target,
four the ceiling), exactly one badged `recommended`, each `bestFor` written as
the trade — "one continuous 30s take, but tops out at 720p" — not as a spec
sheet. Narrowing eight candidates to three is your job, not theirs; a long board
is the catalogue handed back with extra steps.

The same rule binds **image** models for asset work: the film's target format
is a hard constraint. Filter the catalog by `supportedAspectRatios` containing
the film's aspect ratio *before* comparing anything else — never settle for a
model whose ratio enum lacks the finish format and let it "cap" the stills at
the nearest ratio it has.

**Image models are families, not ids (2026-09-10).** The docs name the family
the handbook uses for each job; the id is read off `picsart_model_catalog`
once, at Stage 4's first call, and recorded in `film.json.model.pictures` so
one film never changes model midway while the next film picks up a newer
version the day it lands (`references/PIPELINE.md`, Stage 4, *Image models
are families*):

- **`people`** — the 4K wide's model, selected from the live catalog and
  schema; Nano Banana is the current repo default. Seedream Pro is an
  alternate after identity failures, with any smaller crop disclosed;
- **`map`** — the room map, and a prop's plate: the GPT Image family
  (`gpt-image-*`; where a version ships in tiers, the fast one);
- **`vintage`** — the era tones' portrait and sheet: the GPT Image family (the
  premium tier where there is one — a face is cut from it);
- **`modern`** — the modern path and every profile: Nano Banana (Google's
  `gemini-*-flash-image`, never the `-lite`);
- a point fix on a sheet goes to an image **edit** model (`purpose: "edit"`,
  the newest that takes a mask); signs, letters and labels go to the model that
  can spell, as a separate task, never generated inside a shot.

A model id written anywhere in these docs is evidence with a date, not the
rule. One video model for the whole film still stands, chosen by the user on
`picsart_model_choice` and recorded with its edit and extend siblings.

## Stage details, checklists, and mistakes

`references/PIPELINE.md` holds all 11 stage cards: goal, input, output, exit
checklist, and the documented common mistakes. Load it when opening a stage or
judging a gate. `references/PRESETS-LOOKS.md` holds the film-setup vocabulary
(genres, tones, the colour scheme and hue, the frame, the camera and the lens
family) — lighting, focal length, aperture, palettes, shot length, camera
movement and framing are deliberately not setup decisions, because none of them
can honestly be decided once per film; they are per-shot calls (the palette
table lives on there as the shot's colour). Grain is
not a control either (2026-09-07): it is a property of the stock and rides in
the Camera preset's fragment. A **tone** is an era recipe (2026-09-07): it sets the
camera and lens to a named period of cinema and adds one clause of its own,
while colour remains independent,
so when the story names a period or a cinema tradition, pass its id as
`suggested.selections.tone` and let the console expand it.
`references/WIDGET-FEEDBACK.md` documents every film board's feedback payload.

## Cost ledger

| Free | Charged, no rollback |
|---|---|
| all planning, breakdown, prompts, presets, `picsart_model_catalog`, `picsart_model_params`, `picsart_preflight`, `picsart_media_validate_scene`, authoring and re-authoring the cut, **splitting a run at its cuts** (probe + bootstrap + validate; the scene editor plays the built scene, so it never exports), every board and console (`picsart_film_setup`, `picsart_shotlist_board`, `picsart_asset_review`, `picsart_scene_editor` — which renders nothing, `picsart_model_choice`), every `picsart_media_contact_sheet` and `picsart_media_export` (real GPU renders, so it costs time and leaves a file — **not credits**, 2026-09-07), and `picsart_final_cut` **including its render** — that one happens in the user's browser, so editing and exporting there are both free | every `picsart_generate` (images and video) |

## Traps

- Starting generation "just for one scene" before its assets pass the gate. That is
  the trap the whole pipeline exists to prevent.
- Dispatching video on the forecast. A forecast is a plan; the purchase needs a
  preflight number in front of the user and a yes after it — per dispatch, at
  any pace (`film-scenes`).
- Shortening a descriptor "for brevity" inside a prompt. Consistency dies right there.
- Building a state variant as its own asset with its own approval. Since
  2026-09-04 `@cal_wet` is a panel on @cal's sheet, and since 2026-09-07 a
  view cut from it and numbered in the references header like any other image — a separate
  *sheet* only when the change lasts most of the film.
- Handing the video model a multi-panel sheet, or a composite the user
  supplied, with the wanted panel named in words. Cut it into views at lock.
  No pointer works: sc04a and sc04b ran the same correct prompt and returned
  two different women, one frame blending two panels into a face not in the
  cast. A prompt that names a panel is a dispatch error (`film-assets`).
- Letting the registry go stale — two weeks later it lies, and consistency rests on
  one person's memory.
- Losing the project to an expired CDN link because nothing was saved to Drive
  — or, for a locked asset, recording the export's URL instead of the one
  `picsart_save_asset` handed back: the save re-hosts, the export URL expires
  (`film-assets`, step 4).
- Altering a user's own photo on the way in, or asking them to approve it on a
  board. Since 2026-09-04 the original is saved byte-for-byte (probe-matched)
  and is IMAGE 1 in every run; changed copies are derived files with the
  reason recorded, and a sheet is generated *from* the photo only when a card
  needs an angle it lacks (`film-assets`).