# Novel to production

Use this workflow to turn source prose into a populated World and a shot-ready Episode. Media generation is a separate, gated stage.

## 1. Resolve Project and World

1. Call `list_projects` and `list_worlds`.
2. Reuse the target when the user named or selected one.
3. Otherwise create a Project and, when needed, a World.
4. Bind the Project to its active World with `set_project_active_world`.
5. Call `get_world` before extracting or creating entities.

## 2. Extract candidate assets

Call `extract_novel_assets` with source text, locale when needed, and a bounded `maxCandidates` only when the user asks for a limit.

For every candidate, retain:

- original name and aliases;
- source evidence;
- narrative role;
- stable visual facts;
- proposed image prompt;
- confidence and any existing World match.

Do not treat a candidate as canonical until it has been reconciled with the loaded World.

## 3. Reconcile and populate the World

Reuse a World entity when identity evidence, aliases, role, and existing metadata support the match. Do not merge distinct people merely because names collide; do not duplicate one person merely because an alias differs.

Create only missing canonical entities:

- character: `create_character` with reusable DNA, appearance facts, and voice profile;
- scene: `create_scene` with reusable location facts;
- prop: `create_prop` with reusable design/state facts.

Keep a candidate-to-canonical-id map for Shot binding.

Generate reusable reference images only when requested. Submit the complete image batch with `worldId + targetAsset`, then poll all tasks together. Never generate every candidate by default.

## 4. Generate the script

Call `generate_script` with:

- source prose in `sourceText`;
- a concise user instruction in `prompt` when supplied;
- the canonical `worldId`;
- source language or locale;
- planning constraints only when the user specified them.

The script phase should preserve plot order, names, dialogue, props, and source language. Each Shot should have one screenshot-provable narrative job, one primary action, and a concrete opening/end state.

## 5. Persist Episode and Shots

1. Call `upsert_episode` with Project id, title, source refs, and stable `sourceScriptWindowId` when available.
2. Map script rows to complete Shot inputs.
3. Call `replace_episode_shots` once with the full prepared list.
4. Call `list_shots` to obtain canonical Shot ids and verify each persisted reference policy against the prepared Shot asset ledger.
5. Repair any missing or extra binding with `update_shot`, read it back, and call `assemble_shot_references` before video generation or `sync_episode_to_canvas`.

For every Shot, bind all visible identity-bearing assets through canonical ids:

- `characterRefs`: every on-screen or speaking character;
- `sceneRef`: the one canonical location used by the camera setup;
- `propRefs`: every plot, continuity, or interaction-critical prop visible in the Shot.

Do not leave a reference class empty merely because its names already appear in the prompt. An empty class is valid only when the Shot truly contains none of those assets. If the assembled set lacks a planned canonical asset or its required media, stop before video submission and report the exact Shot and asset id.

Use the following defaults unless source logic requires otherwise:

- dependency: `independent`;
- music: `global_post`;
- speech: true only when the Shot contains dialogue/narration intended for native generation;
- continuity states: concrete T0/T2 ledgers;
- transition: explicit cut or motivated transition, not an implicit inheritance promise.

## 6. Materialize and optionally generate

Call `sync_episode_to_canvas` after canonical Episode/Shot records exist when the user wants the workflow visible on the canvas.

For requested video production:

1. Read [shot-directing.md](shot-directing.md) and [reference-authority.md](reference-authority.md).
2. Assemble each selected Shot's references.
3. Validate dependency mode and continuity media.
4. Submit all executable parallel Shots in one batch.
5. Poll the full task set.
6. Review returned takes before using them as continuation sources.

## Completion report

Return Project/World/Episode ids, reused and created entity counts, Shot count, generated task ids, terminal outcomes, and the exact review scope left to the user.
