Contents

M3 showrunner for world-building

M3 makes Reelwright something you talk to:

"Create a new show: a comedic starship crew, Saturday-morning 80s style."

In reply you get a theme, a style, a crew and a bridge, each as a proposed change set with previews. You approve, tweak, lock, undo or ask for variations ("give me 4 options", "the second one, but taller"). It works from Claude Code (MCP) and from Reelwright Studio.

Read with ARCHITECTURE §10–§11 and ADRs 0003, 0005, 0007 and 0011, and schemas/v1/changeset.schema.json.

Layers

Studio / editor dock (Godot UI)   Claude Code / Desktop (MCP client)   reelwright chat (terminal)
            │ session protocol (JSON-RPC 2.0, WebSocket)   │ MCP (stdio)            │ in-process
            └──────────────────────────────┬───────────────┴────────────────────────┘
                                    core: Showrunner agent (LLM)  ← not used over MCP (the client is the LLM)
                                           │ tool calls
                                    core: ToolRegistry  ── one registry for every surface
                                           │
                   ChangeStore · DependencyGraph · PreviewService · CostMeter
                                           │
                        Show Pack on disk (+ git)       engine jobs (previews)

ToolRegistry (core/src/studio/tools/)

A tool is a name, a description written as a prompt, an input schema, and a handler.

• Input schemas are $defs in schemas/v1/tools.schema.json (e.g. ReviseInput: an id plus a list of {pointer, value} edits). ToolRegistry in registry.ts validates every input before a handler runs. bundleSchema inlines cross-file refs for Claude and MCP.
• Strict tools have a budget. Claude compiles all the strict schemas in one request together, within at most 20 tools, 24 optional parameters and 16 union parameters.
  • Only small inputs are strict: true: ids, pointer edits, generation options.
  • Tools that author whole documents (create_theme, create_style, create_*_pattern, create_props) are non-strict. The full schema is still sent; validation and the repair loop catch mistakes.
  • The strict flavor (strictToolSchema) moves constraints Claude does not enforce into descriptions, the way the SDKs do.
  • The limits count every strict schema the request carries, a tool found by search included (the grammar is built from the whole toolset). So only the tools in view (coreTools, below) are sent strict: 10 tools and 3 optional parameters on the demo. A tool found by search goes non-strict whatever its registry flag, and ToolRegistry.call checks its input, with repairs. What a turn sends on the demo is tested against strictLimits (showrunner-agent.test.ts).
• Tools found on demand (core/src/showrunner/tool-search.ts). Every request carries every tool's definition, but only a dozen are in Claude's view from the start (coreTools): show_summary, get_document, list_documents, search_canon, show_memory, estimate_cost and the everyday revisions (revise_character, revise_set, revise_theme, revise_style, write_bible_entry, vary). The rest carry defer_loading: true, and Claude finds one with the API's tool search (tool_search_tool_bm25_20251119, a plain-words query), which loads its definition then. A system block between the rules and the show context names every searchable tool, so Claude knows what there is. A first message on the demo is about 9,100 tokens; with every tool in view it was about 128,500. Deferred tools stay out of the cached prefix, so a search does not break the cache; the search's blocks (server_tool_use, tool_search_tool_result) go back to Claude as they came.
  • Over MCP (reelwright mcp, the web service's endpoint) the same tools, with studio_context and list_shows, carry _meta: {"anthropic/alwaysLoad": true}: Claude Code keeps an MCP server's other tools behind its own tool search.
• Handlers are pure over (show state, input) → result. They never write specs. A proposing tool returns a ChangeSet (status proposed) plus preview references.
• The same registry backs every surface: MCP, the showrunner agent, the session protocol and the CLI.

Removing, renaming and copying. Any document or sound below the show can be removed, renamed or copied (core/src/studio/tools/documents.ts, core/src/studio/references.ts), one change set each, undone like any other, in the person's hands and the showrunner's:

• A rename takes every reference with it: strings that are the id anywhere in another document (an episode's cast and cues, a set's props and links, the bible's about, memory), the files that move (an episode's folder, screenplay and outline, a sound's file), and the screenplays' character cues (a cue that called a character by its name, first name, short name or id slug says the new one; one through the episode's castMap stays) and scene headings that named a set by its name, in scripts, episodes and outlines alike. A character's short name that was only its name or first name ("PIP ROOK" or "PIP" for Pip Rook) follows a new name, in its own case; one of its own ("SKIPPER") stays. Action lines and parentheticals say the new names too ("Ibden looks up." → "Wren looks up.", an introduction in capitals in capitals), whole words only; what is spoken stays as recorded, so no take goes stale. A recorded sound's name is the title its FLAC carries (its TITLE comment): sounds.import and import_sound name it from the file it came in as ("Fog_Horn.wav" is "Fog Horn"), and a rename rewrites the title, the audio byte for byte as it was.
• A remove is refused with every use (document.in_use, each use a diagnostic naming the file), unless replaceWith puts another of its kind in its place everywhere (cues and headings follow), or anyway drops it from the lists that name it and leaves the rest for validation. An episode goes with its folder. The active style is switched first.
• A copy gets <id>_copy (numbered), " copy", no locks and fresh provenance.
• Locks hold: a locked document is neither moved nor removed, and a locked reference is never rewritten.
• Change sets carry files of bytes (Content type binary, by SHA-256 in the objects store), so a recorded sound is added, moved and taken back byte for byte.

Decide tools belong to the human.

• In Studio they are buttons, and the agent is never given them.
• Over MCP they are exposed with destructiveHint, and their descriptions say they must only be called after the user explicitly asks.
• The CLI has reelwright changes approve|reject|undo|redo.

ChangeStore (core/src/studio/changes/)

• Proposals live in <show>/.reelwright/changes/<id>.json, validated against changeset.schema.json. Each operation carries the file's base hash. A proposal whose base no longer matches the file on disk becomes stale and is never applied.

  • A tool reads one snapshot of the show (readShow) and proposes against it: base hashes are those of the bytes the tool read, however long it worked (a generate_characters waits seconds for the engine). If a file it writes changed on disk meanwhile, nothing is proposed (change.stale), since the proposal would be stale at birth.

• Approve applies every operation atomically: write temp files, then rename, and roll back on failure. Every written document goes through the canonical formatter and must validate (schema + semantic) as a whole show before anything is written. The status becomes applied.

  • Each target is compared with its base again as it is set aside, just before the new file is renamed in, and once more after every rename. A save that lands after the stale check (while the show validates, say) is put back, and the change becomes stale. A backup is deleted only while it still holds the base; one that changed is kept, and the applied change's history names it.
  • A change file is checked against the schema whenever it is acted on, and every path again when it is written: inside the show, no .., no dot-folder (.git, .reelwright), and never through or onto a symbolic link.
  • If the Show Pack is a git repository, approve also commits the change as the git user configured in that repo. The message is the change's title and rationale, with a trailer Reelwright-Change: <id>.
  • Only a show that is the top of its own repository is committed. A show that sits inside another repository is not committed there; the change's history says why. reelwright init gives a new show its own repository, even inside another one, and never touches the outer one.
  • Git runs with no GIT_* variable and no EMAIL from the environment, and with user.useConfigOnly, so the identity is always one configured in git. Without one, nothing is staged or committed, and the history says so.

• Undo proposes and applies the inverse change set (inverseOf). History is never rewritten. Redo re-applies an undone change if its bases still match.

  • The exact bytes of every file a change replaces are kept in .reelwright/changes/objects/, named by their SHA-256 (baseBytes) and checked against it whenever they are written or read; a damaged copy is refused, never restored. Undo writes them back byte for byte (bytes), so a hand-formatted file comes back as it was, and removes the folders the change created (createdDirs) if they are empty.

• Statuses say what is on disk. A change and its undo changes form a family, and at most one member is in effect: whenever a member is applied, any other member that was applied becomes reverted. approved is transient: it is recorded in history between the decision and the write, never kept as a status. Every sequence of up to four approvals, undos and redos of two changes is tested against disk (core/test/change-store.test.ts, "ChangeStore statuses").

  Status	On disk	approve	reject	undo	redo
  proposed	nothing written	writes it: applied (variation siblings rejected); bases moved: stale	rejected	refused	its rejection was undone: rejected again; otherwise refused
  stale	nothing written	refused	rejected	refused	its rejection was undone: rejected again; otherwise refused
  rejected	nothing written	refused	refused	the person's own rejection: it waits again, proposed, or stale when its files moved since (noted rejection undone); one rejected by another decision (an option chosen, a revision approved): refused, since undoing that decision is what takes it back	refused
  applied	its edit is in effect	refused	refused	a change: a new undo change is applied and it becomes reverted; an undo change: the change it undid is re-applied (applied) and it becomes reverted. Refused if its files changed since.	refused
  reverted	its edit is not in effect	refused	refused	refused	re-applied if its bases still match: applied, and the family member that was applied becomes reverted; otherwise refused and still reverted

• Variation groups: vary and generate_characters --options N create N proposals sharing a variationGroup. Approving one rejects its siblings.

• Revisions (M7): a proposal may name one still waiting that it supersedes (only a proposed or stale one). Approving it rejects that one and whatever it superseded in turn, each noted superseded by <id>; until then the person can choose any of them. A proposal that names none supersedes the newest one still waiting by the same author whose files it all writes (a second screenplay draft, a set built again), since approving it would leave that one stale; a variation, an undo or a lock never does. direct_episode and edit_episode name the newest proposal still waiting for the same episode file, so re-directing an episode leaves one live proposal, not a pile.

• Locks: lock and unlock are change sets too, editing meta.locks or meta.status, so they are undoable. Any proposal that would modify a locked pointer is refused at proposal time with the lock named. They are the only changes that may lock or unlock: any other proposal that would add, remove or edit meta.locks, or make meta.status become or stop being locked, is refused (change.lock_edit), so no tool can unlock a pointer in one proposal and change it in the next.

Versions (core/src/studio/versions.ts)

The product audit's #20: a show had no named versions, no restore points and no show-wide history, and Ctrl+Z covered one session.

• A version is what every document and script of the show held at a moment: their bytes, kept by SHA-256 in .reelwright/changes/objects/ (the copies undo writes back, so a file kept by both is kept once), and a record in .reelwright/versions/<id>.json with a name, a note, who saved it (the web service's person) and when. Comments are talk about the show: no version keeps or restores them. Recorded takes and assets are named by their own hash and never written over, so the documents that name them are enough. Nothing needs git: a show with no git identity, or a machine with no git, has versions too. The version also keeps the newest still the show's previews hold, as a picture of it then (no render is made for it).
• Comparing two versions, or one and now (versions.diff), lists every document or script added, removed or changed, with its field count; asked for one document, its fields pointer by pointer (as a proposal's are) and a script's lines in stretches. Formatting alone is no difference: JSON documents compare by what they hold.
• Restoring is a change set like any other (restore_version): the files that differ are written back byte for byte, and restoring the whole show removes documents made since. The person's own (Studio's tools.call) is applied as made, in History and undone with Ctrl+Z; the showrunner's, or an assistant's through MCP, waits as a proposal. Locks hold: a restored document keeps the locks it has now, and a locked field that would change refuses the restore with the lock named. Nothing to restore is refused (version.same).
• Restore points are versions the ChangeStore takes by itself just before it writes a risky change: a restyle, an OTIO import, one that removes a file, or a bulk edit (three files or more, or twenty fields of one). An undo or a restore puts things back and takes none. The change's history says restore point <id> taken first. The newest 20 are kept; named versions stay. A store that cannot take one says so in the history and the change goes ahead.
• Roles: versions.list and versions.diff read, so a viewer or a reviewer browses and compares; versions.save and restore_version write, for the owner and editors. version.event tells everyone in the show of a version saved, with who saved it.
• Tools: list_versions and compare_versions (read) and restore_version (propose) serve the showrunner (Studio's chat and reelwright chat) and MCP.
• Ctrl+Z across sessions is Studio's: its stack of the person's own changes is kept with the show's place (RwProjectState, per person on the web service, in the browser), the newest 100 applied and undone, so it outlasts a restart. Ctrl+Z goes past a change that can no longer be undone (undone by someone else since, or overtaken) to the one before it.

Dependency graph (core/src/studio/graph.ts)

Nodes are documents; edges come from references and meta.derivation: pattern → instance, style → everything rendered, set → episodes, character → episodes.

• impact(id) lists what re-derives or re-renders if id changes.
• status lists instances whose pattern hash drifted, and locked characters whose model sheet no longer matches the approved one (canon drift, ADR-0007). Approved model sheets are stored by hash in .reelwright/approved/.

Previews (core/src/studio/previews.ts)

• Previews run through engine jobs and are cached by (the jobs as the engine draws them, engine fingerprint, kind) in <show>/.reelwright/previews/<key>/. A job embeds only the documents it draws, so editing another one keeps the preview; stills key on the compiled Timeline, so a compiler change that moves a frame renders again. Captions and document ids come from the request. One engine job runs at a time per service; the rest queue, and an AbortSignal drops a queued request or kills its job.
• Kinds:
  • model sheet (existing task);
  • line-up: the model sheet's line-up panel with the whole cast (existing task);
  • set views (existing);
  • storyboard stills (existing);
  • style swatch: a new engine task, style_swatch, that renders a fixed sample (a character bust, a set corner, sparks) in a given style, so a style can be judged before any show uses it.
• Previews are files. Surfaces reference them by path over the session protocol, or return them as MCP image content (downscaled JPEG).

Showrunner agent (core/src/showrunner/)

• Provider interface (LlmProvider): the Anthropic implementation uses the official @anthropic-ai/sdk.
  • Defaults:
    • claude-opus-5-5;
    • adaptive thinking;
    • streaming;
    • per-stage effort from show.json;
    • no forced tool_choice (current models reject it): tools are strict: true and the prompt names the tool;
    • server-side refusal fallbacks enabled.
  • The key comes from ANTHROPIC_API_KEY, then a key file ($REELWRIGHT_ANTHROPIC_KEY_FILE, else ${XDG_CONFIG_HOME:-~/.config}/reelwright/anthropic-api-key, refused unless only its owner can read it), then the macOS Keychain (security find-generic-password -s reelwright -a anthropic -w), then the SDK's own chain. It is never logged or written, except by reelwright key set, which saves a key to the key file (folder 0700, file 0600, written whole) after asking Anthropic whether it works with a free models.list call; key status says where the key in use comes from and key forget removes the file. Output names a key only as sk-ant-… and its last four characters. Studio's "Connect Claude" dialog runs key set --check --json with the key on stdin, never on a command line, then starts the show's daemon again. Its other way, the person's own Claude plan through the Claude Code on their computer, is Using a Claude plan. A Claude subscription's sign-in token (sk-ant-oat…) is refused on this path wherever it turns up, with the way to use a plan.
  • A daemon whose showrunner has no credentials keeps it for dry runs, but leaves chat out of session.hello's capabilities (Showrunner.canTalk), so a UI offers to connect Claude instead of letting a first turn fail.
  • A stream that breaks partway (malformed tool input, a dropped connection) is sent again at most twice. Each attempt is planned against the budget and billed, and the surface never sees the same text twice.
• Loop: user turn → model → tool calls (run in parallel when read-only) → tool results → … until the model ends its turn. Proposals stream to the surface as they appear.
• Repair. Tool input that fails schema or semantic validation returns an is_error tool result with the diagnostics (pointer + hint). Schema failures are repairs: at most 3 per tool, counted once per model call however many of its calls failed; then the tool fails visibly. A handler's own failure (an unknown id) is an ordinary error result.
• Unfinished turns. A turn that is cancelled, refused or cut off at max_tokens is taken back out of the conversation, so the next turn neither inherits the abandoned request nor shows a declined one to the classifiers again. Proposals it made reach the next turn as show updates. Nothing before it is edited.
• Context and caching.
  • Cached prefix, in this order: the tools in view, then the system prompt (role, rules, tone), the names of the tools found by search, then the show context block. Both breakpoints (the rules, the show context) are kept an hour (cache_control.ttl: "1h", SHOWRUNNER_CACHE_TTL): writing the prefix for an hour costs 2x its input price instead of 1.25x, once, and a person's next message seldom comes within five minutes. On the demo the first message writes its ~9,100 tokens for $0.07 and each one within the hour reads them for $0.002 (with every tool in view, $1.03 and $0.03). The show context holds the theme, a style summary, the bible, a cast digest (ids, names, roles, one line each) and showrunner/NOTES.md.
  • Everything volatile (the conversation, fresh tool results) comes after the last cache_control breakpoint.
  • Long context plus caching replaces retrieval until a show outgrows it.
• Where the person is (core/src/showrunner/page.ts, brief.ts, suggestions.ts). Studio says where the person is with each message and as they move (ChatContext): a page path (StudioPage: world/theme.marigold, cast/char.otto, sets/set.marigold_bridge/setups/wide, timeline/ep.x, script/<path>, memory/gags, change/<id>), its title ("World › Theme") and what is open, selected and in view there.
  • resolvePage turns it into one of twenty page kinds against the show's documents (the Show, its settings, World, the theme, a style, the bible, Cast, a character, a pattern, Sets, a set, a prop, an effect, a graphic, the timeline, Episodes, a script, Memory, a proposal, the booth); an old context (a document, the timeline's episode, a script) still resolves.
  • The page brief is said before the person's message as a <studio-focus> block: the page and what is open, what Studio says is in view, facts about the page drawn compactly from the show (a theme's premise, tone, rules and catalog; a style's palette and settings; a character's card; a set's marks, setups, lighting and elements, the part in view first and whole; the episode at the playhead with its shot and lines; a memory entry; a proposal's diff), the tools that act there (only those the registry has), and how to link a place ([Open the theme](reelwright:world/theme.marigold)). It is deterministic (core/test/fixtures/page-briefs/ snapshots each kind on the demo show) and within 1,200 tokens: facts are cut last first, ending with how to read the rest; the person's selected lines are never cut. It is part of the turn, not the cached prefix, so the system prompt, the show context and the recorded fixtures are unchanged, and the API's Showrunner and the plan's PlanChat say it alike.
  • Suggestions for each page, three to five, in the show's own words ("Give Otto a winter costume.", "Tighten sh020.", "Try a warmer variant of Saturday Morning.", "Build the show's first set." on an empty Sets), with no model; where no page applies, the show-level ones Studio always offered.
  • Answers that take you there: after a turn's proposal the daemon sends studio.navigate with the place it changes (pageOfChange: the document's page, a new document's section, a script, Memory), and after the reply each place it linked that the show has. Studio shows a proposal's as a button on its card, and a linked place as a link in the words.
• Memory. showrunner/NOTES.md in the Show Pack holds durable preferences. The agent proposes edits to it like any other document. Transcripts go to .reelwright/sessions/<id>.jsonl.
• Budgets.
  • show.json budget caps spend per request, per episode and per month.
  • Before every call the agent counts tokens and prices the worst case: the whole prompt as cache writes (at the rate of how long it is kept) and all of max_tokens. With the refusal fallback on, each model of the chain may bill both in turn, so a call goes with fallbacks: "default" only while the whole chain's worst case leaves room for 4,096 output tokens. Otherwise it goes to its one model without the fallback and is priced on that model alone: a refusal stays a refusal, never a bill past the cap. It cuts max_tokens to fit, or stops with a clear message.
  • The demo caps a request at $3 (examples/shows/marigold/show.json): a first turn of three calls costs about $0.13, and the whole fallback chain fits. Its $2 cap once stopped the first message before it was sent, when every tool was in view: the chain's worst case was $2.54.
  • The monthly ledger (.reelwright/spend/<YYYY-MM>.jsonl) is shared by every process on the show. Each check re-reads it, and a call in flight holds its worst case there until its real cost replaces it.
  • --dry-run shows the plan and the estimate without calling the model: the tools in view and those found by search, the strict schemas against the limits, the prompt's tokens (counting only what is in view, as Claude sees it) and how many are the cached prefix, what turn 1 costs to write it, what a turn within the hour costs to read it, and whether the first call fits the caps.
  • The CostMeter records usage (input, cache read and write, output) from each billed attempt, including cancelled and broken streams.
• Recorded fixtures (tests never need a key).
  • RecordingProvider and ReplayProvider key each call by SHA-256 of the canonical request, excluding volatile fields. Fixtures live in core/test/fixtures/llm/.
  • CI uses replay only, and a missing fixture fails with the command to record it.
  • Recording is explicit (reelwright fixtures record <scenario>) and spends real money, so it needs a key and a budget.

Session protocol (schemas/v1/session.schema.json)

JSON-RPC 2.0 over a localhost WebSocket. The daemon (reelwright serve --show <dir>) prints {"port":…,"token":…} on stdout. Clients send the token in session.hello; before it nothing else is answered and batches are refused. Upgrades whose Origin is not a loopback one (a web page) are refused with 403.

Server notifications: chat.event, change.event (proposed, applied, rejected, stale; once applied, with note, who did what in a sentence: "Ada edited the Lighthouse's script."), doc.event (changed on disk, including edits made outside Reelwright, detected by watching files), preview.event, render.event (a render's stage as it starts, the frames drawn every second while it draws them with the speed and the time left, then done with its video and how long it took, failed with why in words and what to do, cancelled, or paused), render.queue (the render queue whenever it changes), agent.event (what an AI working on the show through Reelwright did, live: from its link's agent.activity, or the recent of a reelwright mcp's presence file, to the Studios of the person it works for that say 1.19), chat.asks (what the person asked their own Claude from the chat, waiting or taken and by which client, to their Studios that say 1.19, when it changes), assist.event (an assist.write's text as it is written, revising when it starts again, done when it ends), comment.event (a thread created, replied to, edited, deleted, resolved or reopened, by whom, and the thread as it is now), studio.navigate (a place a chat turn's answer points at: label, page, frame or line, its turnId, and change when it is where a proposal lives), request.working (the id of a request the daemon still works on, every 20 seconds until its answer goes, to a Studio that says 1.23: long work, such as the style lab's directions from Claude Code on the person's plan, waits as long as it is said, RwSessionClient.request_long). A file that cannot be read (its permissions, say) is still a doc.event, and a diagnostic (show.unreadable_file) when the show is read; nothing the watcher meets ever stops it or the process.

Every message has a schema. The core validates both directions. The Godot client uses the generated RwSpecSession* classes.

UI (ADR-0011): engine/addons/reelwright/ui/

Plain Control scenes, with no editor APIs, talking only through RwSessionClient (WebSocketPeer + JSON-RPC):

• RwChatPanel: the conversation, streaming text, tool activity, inline proposal cards. (implementation) Its header says where the person is ("Looking at: World › Theme"), with "Ask about the whole show" to leave the place out of what is sent (and "Use this page" to put it back; moving elsewhere puts it back too). It asks its host where the person is four times a second and tells the daemon (chat.focus) once a place has held for 0.4 s, the playhead's frame and what is in view aside, so a playhead running through shots is told once it stops; the chips are the answer, in the empty chat and, the first three, over the message box under a conversation. A studio.navigate becomes a button that goes there (on a proposal's card when it is the proposal's place), a [label](reelwright:<page>) in a reply a link, and both are kept with the thread.
• RwPlace (implementation): where the person is has one source, Studio's route (RwStudioRoute, what Back and Forward go through): the page path is its parts after the show (RwStudioRoute.page_of). Every view that fills the main area adds what it alone knows (chat_place(): the title, what is open, selected and in view, and deeper parts below the route: a document's part at the top of its scroll, a memory group or entry), and finds them again (show_place(deeper, frame, line)). RwStudio.chat_context puts the route and the view's words together; RwStudio.go_to_place goes to the route a page path starts with (RwStudioRoute.of_page, through go_to_route, so Back returns from it) and hands the view the rest. The views: the Show section, World, Cast and Sets (the browser and its document), the timeline, Episodes, the script editor, Memory, Settings, a proposal and the booth. A new view (a set explorer, a character studio) adds its places, a camera included, by answering the two, with no switch to change.
• RwProposalView: title, rationale, a per-document diff (readable field-level, not raw JSON), previews, approve/reject, lock toggles. Variation groups show side by side. Each card reads as what changes for a person: the document by name, ids in values by name (RwValueFormat.id_words), no JSON pointer under a field (in its name's tooltip); what a document keeps for itself (kind, schema version, id, its meta but for description, tags and notes) folds under the card's Details with its id and file (RwProposalView.is_bookkeeping), and a commit's hash is only in the status line's tooltip.
• RwPreviewGallery: model sheets, set views, style swatches; zoom.
• RwShowOverview (implementation): Studio's Show section, the first thing a showrunner sees. The show's poster (its cast as a line-up, previews.get lineup on the show; with no cast, a frame that says the cast lines up there), title and premise (the theme's: "Borrowed from the … theme" with Write your own when the theme is the kit's), its counts, and New episode, Write with Claude, Render… and Record lines. Next steps: what the show lacks, each with the one action that deals with it, in order: a first character and a first set, the showrunner's proposals waiting (a variation group as one), each decided on its row without opening it: what it changes in a line (changes.get: the document and the field, its new value when short), who proposed it and when, then Approve, Reject and Review. Approve is held, the row saying why, for options to choose between (Reject rejects them all), for one gone stale (its drift folded into its row) and for one proposed with warnings ("2 warnings: look first": diagnostics on changes.get, session protocol 1.16, which Review lists under Before you decide, a kind of note as one card saying how many more are like it, warnings first, past the first two kinds folded behind "N more notes" so the change stays on the first screen; the chat's proposal card holds its Approve the same way); Ctrl+Enter and Ctrl+Backspace (changes.approve, changes.reject in the key map) decide the row with the focus, which then goes on to the next one waiting. A decided row stays where it was, as tall as it was, until the page is left ("Approved · …" or "Rejected · …" with Undo, "Taken back · …" with Redo, following change.event), so nothing under the pointer moves up into its place. Each decision is the person's own, as in Review: its row's Undo is Studio's Ctrl+Z for that change (RwStudio.undo_change, redo_change), and Ctrl+Z takes an approval back and brings a rejection back. Then what an episode needs (Make it runs its make call as the person's own change), an episode that does not play, drift, each episode's next step (write the outline's script, direct the script, voice its silent lines with episode.voice, finish recording, render a preview), memory updates to review and episodes not in memory (both open Memory); six, then Show N more; All caught up when nothing waits. Episodes as cards: a still at stillFrame (previews.get still), the running time, scenes and lines, and how far it has got (Outline, Script, Directed, Voiced, Recorded N/M, Rendering, Rendered, Does not play); a card opens the timeline, the script, or starts the outline's script. The latest decisions on the showrunner's proposals, each with its picture (changes.get). Every part is asked at once and drawn as its answer comes, a placeholder until then; it refreshes on change.event, doc.event, render.event and memory.event, and asks a still again only for an episode a change touched. With no episodes, its Episodes part offers Write your first episode.
• RwEmptyState (implementation): what a place holds while it is empty and the action that fills it: Cast (Create your first character, or with no pattern Ask the showrunner), Sets (Build your first set), Episodes (Write your first episode), the Timeline with no episode (Go to Episodes, New episode), the booth on an episode with no lines (Open the script, Back). "Ask the showrunner" puts words in the chat's message box for the person to send (RwChatPanel.prefill), or offers Connect Claude with no model; on the web with no showrunner there is no such button. A host that does not answer a view's button gets none.
• RwCoachMarks (implementation): Studio's first-run tour, five marks shown one at a time (the rail, writing a script with its read-along and Write with Claude, the timeline's inspector, the showrunner, Ctrl+K and Ctrl+/), each outlining what it is about with its card beside it; Next, Done, Skip tour. It takes no clicks but its card's and never the focus. Shown the first time Studio opens a show (RwUiSettings.tour_seen, [tour] seen, kept when it starts), again from the palette ("Show the tour again") or the foot of the shortcut sheet. Only the app turns it on by itself (RwStudio.tour_on_first_open): tests and review tools host Studio without it.
• RwShowBrowser: theme, style, cast, sets, props, bible, with lock state and drift badges. Opening a document reads it with docs.form into RwDocumentView, where every field is edited by hand (RwFieldForm, through the document's revise tool) and its locks are set. Each row's ⋯ renames, duplicates or deletes it (RwDocActions); "More" makes a prop, an effect, a bible entry of any kind, or a copy of a pattern, from library/templates/. (implementation) Cast has "New character" and Sets "New set" (RwCreateDialog): pick one of the show's patterns, how many (characters) or what scene headings call it (a set), and generate_characters or build_set runs through tools.call with the seed one more than how many the show has, so each is new, and no model; the person's own change, applied as made, Ctrl+Z to undo, and the first one made opens.
• RwEpisodesView: each episode with its latest render and preview, to watch in the system's player or find in its folder; "Render preview" and "Render" start one (renders.start), whose stage, frames, time left and Cancel show on the episode while it runs. Renders wait their turn in the show's render queue, shown over the list (RwRenderQueue, docs/design/render-queue.md), and run one at a time in the daemon (core/src/studio/renders.ts), each into a version of its own (docs/design/review-loop.md). (implementation) "Script" opens an episode's screenplay in RwScriptEditor; screenplays no episode was directed from yet are listed too, "not directed yet" (the demo's Salvage Claim had never shown anywhere); "New episode" asks for a title and starts episodes/<slug>/<slug>.fountain with the show's first set and two of its cast. An outline from the writers' room whose episode's folder has no script yet is listed as well, with "Write the script", which starts <folder>/<folder name>.fountain.
• RwScriptEditor (ui/script/): the screenplay in a code editor, Fountain colored as it is typed by RwFountainHighlighter, which reads lines as the core's parser does. Save (Ctrl+S) is write_screenplay; Direct (Ctrl+Enter) is direct_episode with heuristic and the text: the heuristic director, free and with no model. Both go through tools.call, so they are the person's own changes, applied as made and undone with Ctrl+Z; then "Timeline" shows the episode, to play. A Studio audit found no way to write a script in Studio: only the showrunner could, and only with an API key.
• RwBooth (ui/booth/, docs/design/m6-recording.md): actors record an episode's lines. A prompter, a count-in, Record and Stop (Space) with a live input meter, the line's takes with waveforms to play alone or against the picture, choose, trim, gain, normalise, clean or delete, and Previous and Next through a character's lines. Opened from a line in the timeline's inspector ("Record a take", "Takes…") or an episode's "Record lines…".
• RwUiTheme: the one Theme (dark, Inter, a 2 px focus ring on everything focusable).
• RwShowSession: what a host owns. It runs the daemon (RwDaemonSupervisor: reads the endpoint line, restarts with backoff, stops only its own child) and holds the one RwSessionClient every component binds to. RwSessionStatus says how it is doing. switch_to moves it to another show and keeps the one left running in its RwDaemonPool: the daemon, and the open socket itself (RwSessionClient.hand_over), so what that show says while away (a render done, a chat turn's events, proposals) is heard, and switching back hands the same socket back with no new start and no new hello. When the socket comes back for the same show (after a drop, the daemon started again, or a first hello that came after a view had asked), the client says reconnected and every open view reads its document again (its reload): a document, a set, a character, a style, a script (unsaved text kept), a proposal, the booth's line; the timeline, memory and settings read the show again on every hello. Another show's hello, or a socket handed over, reloads nothing.

Hosts:

• Reelwright Studio (engine/app/studio.tscn): a standalone window that starts reelwright serve and supervises it.
  • Launch: tools/studio.sh [--show <dir>] [--daemon "<command>"], which runs the scene in the engine project (godot --path engine res://app/studio.tscn -- …). The project's main scene stays the engine CLI, which renders depend on. An exported Studio will set its own main scene per export preset once export templates join the toolchain.
  • Daemon command: node <repo>/core/src/cli/main.ts serve in a checkout, else reelwright serve; --daemon or the welcome screen changes it, and Studio appends --show <dir>. Recent shows and the command live in user://reelwright-ui.cfg, shared with the editor plugin.
  • Switching shows ((implementation) RwProjectSwitcher, RwProjectState, RwDaemonPool): Ctrl+Shift+O, the show at the top of the rail, or "Switch show…" in the palette lists the recent shows, the open one first and then the most recent, each with its picture (the timeline's still where it was left, else its style swatch, drawn while it was away, else its initial), its folder (its account on the web), when it was last opened and what changed since (proposals waiting, renders finished, an unsaved script). Typing filters, Enter opens, Shift+Delete takes one off the list; then Open another folder…, New show…, Try the demo show. The show left stays running: the last two warm (RwDaemonPool.CAPACITY), put away after 10 idle minutes, the least recently used first when a third is left, never one that works (a render, voicing or a chat turn). What finishes in one while away is said in a toast that stays ("Render of “The Lighthouse” finished in The Night Watch." with Open), by its episode's name: the pool reads the show's names first, and what finishes before they come waits for them, in order, and keeps the show from being put away as idle. A daemon that stops first is asked again once started again; one that stops twice before saying them, a show put away, or one that refuses has what waited said by its ids. Each show comes back where the person left it, on the next launch too: the section, the document, change or script open, the script's unsaved text (kept as its draft, marked unsaved, written only by Save), caret and scroll, the writing assistant open beside it, the booth's line (a take being counted in or recorded when the person switches is dropped: it was the other show's), the timeline's episode, playhead, zoom and scroll, the chat and the message being written, all in user://reelwright-projects.json. The shortcut sheet lists the switcher's keys. A show that cannot open (its folder gone, its daemon failing before it answers) says why and leaves the person where they were.
  • Layout: a rail (Show, World, Cast, Sets, Timeline, Episodes, Memory, Settings), the Show section's dashboard (RwShowOverview), the browser, the timeline, the episodes, the show's settings ((implementation) RwShowSettings: its title, logline, cover, style and theme, render format, director, memory and writing settings, storage, and Duplicate, Export as Show Pack, Archive and Delete, the same on the web; read-only for a reviewer or a viewer of a shared show, and Delete its owner's alone) or a proposal in the main area, and the chat on the right. Both side columns fold for room, sliding over 0.15 s: the rail to its icons (Ctrl+B, the chevron at its foot; each icon's tooltip names its place and key, the show keeps its picture and the status its dot), the chat to a strip at the window's edge that brings it back on a click (Ctrl+Alt+B or Ctrl+Shift+L, the chevron in its header). The chat's left edge drags it between 340 and 720 px (a double-click gives it its 400 px); Studio keeps both folds and the width, and the web edition keeps them for each person in their browser. Keys: Ctrl+O, Ctrl+Shift+O (switch show), Ctrl+1–8, Ctrl+B (rail), Ctrl+Alt+B (chat), Ctrl+L (message box), Ctrl+K ((implementation) RwCommandPalette: every document, script, section and command, each word typed starting a word of its name or kind; Enter goes there: an episode to the timeline, a document to its section, open), Esc (back), Ctrl+Enter (approve, only with the focus in the proposal), Ctrl+= / Ctrl+- (UI size).
• Editor plugin: the same components in EditorDocks. The Showrunner dock is the chat, the Show dock the browser, and a Reelwright main-screen tab shows the proposal under review. plugin.gd only places them; their content is plain Controls in editor/.
• Screenshots for review: tools/studio-screenshots.sh drives Studio from the recorded protocol messages and writes docs/images/m3/. (implementation) What a new user meets, against the real daemon: godot --path engine -s res://tests/support/rw_first_look_tour.gd -- --show <dir> --out <dir> (each tour mark, the Show section once its pictures have come, and Cast, Sets, Episodes and the Timeline as that show has them).

MCP server (core/src/mcp/)

reelwright mcp --show <dir> runs over stdio, using the official @modelcontextprotocol/sdk.

• Tools: the ToolRegistry, with annotations readOnlyHint and destructiveHint. (implementation) And studio_context, the MCP server's own (read only): where the person is in Studio on this show now, from the place the daemon keeps (.reelwright/studio/focus.json, core/src/session/studio-focus.ts), with that page's brief, the tools that act there and Studio's suggestions; "Studio has not said where the person is" when Studio is not open on the show. Claude Code (and the plan's chat, whose tools are this server's) can ask what "this" is. The web service's MCP server answers it for the person signed in to the session (createMcpServer person; their focus-<person>.json), reading the show through its daemon. Given a context (a chat message's, checked against ChatContext), it answers that place's brief as a turn carries it: the web edition's plan bridge asks it for each message, so a chat on a plan through the person's computer hears the same brief as the daemon's showrunner.
• Resources: reelwright://show, reelwright://doc/<id>, reelwright://changes/<id>.
• Proposal results carry the change id, a readable diff summary and preview images.
• A .mcp.json example for Claude Code ships in the docs.

To use it from Claude Code, put a .mcp.json in the directory you start Claude Code in (paths are relative to it). The client is the LLM, so no API key is needed:

{
  "mcpServers": {
    "reelwright": {
      "type": "stdio",
      "command": "node",
      "args": ["core/src/cli/main.ts", "mcp", "--show", "shows/my-show"]
    }
  }
}

• Or add it once with reelwright claude connect --show shows/my-show, which runs claude mcp add in the show's folder with this Reelwright's absolute command (an installed release or a checkout alike). Claude Code then works on the show with your own Claude plan: see Using a Claude plan, which also covers Claude Desktop and Studio's opt-in chat on a plan.
• The everyday tools (coreTools) and studio_context carry _meta: {"anthropic/alwaysLoad": true}, so Claude Code keeps them in view; it finds the others with its tool search.
• Decide tools carry _meta: {"anthropic/requiresUserInteraction": true}, so Claude Code asks the person before each one. Proposals the server writes reach a running Studio as change.events: the studio watches .reelwright/changes/.
• Point it at your own Show Pack, not examples/shows/marigold: approving a proposal writes to the show, and the demo show is canon for tests.
• Previews arrive as JPEGs at most 768 px on the long edge (ffmpeg downscales them); without ffmpeg the result names the image file instead.

Tests

• Registry: every tool's input schema passes the structured-output lint, and every handler is pure: the same state and input give the same ChangeSet bytes.
• ChangeStore: atomic apply with rollback; stale detection; undo/redo round trips to byte-identical files; variation groups; locks refused with the lock named; git commits authored by the repo's configured user, carrying the trailer.
• Graph: impact and drift on the demo show.
• Agent: replayed fixtures for the watch-it conversation. The repair loop (a fixture whose first tool input is invalid) and the budget stop.
• Session protocol: schema-validated in both directions; a scripted client drives chat, approval and undo against a daemon using the replay provider.
• MCP: an in-process client lists tools, calls generate_characters, gets a change id and images, and approves it.
• UI (gdUnit): components render proposal cards and diffs from recorded protocol messages, and Studio starts a fake daemon and completes session.hello.

Watch it (M3 done when)

1. From Claude Code, with the MCP server configured, one conversation creates a new Show Pack. Theme, style, a crew of four and a bridge are each proposed with previews, approved, and committed. "Make the engineer older and grumpier" becomes a proposal with before/after model sheets. Undo works.
2. In Reelwright Studio, the same flow runs through the chat panel with the showrunner agent, with proposal cards, previews, "give me 4 options" as variation cards, and lock/unlock.
3. CI replays the recorded conversation and the protocol tests. No key is needed.