Production administration from a session¶
python -S bin/studio_admin.py --help exposes production, scene, shot, card, document, gate, phase, lane-policy and world-address operations. It imports no app server and needs no third-party Python packages. Studio's corresponding handlers call these same operations; its cache refresh and notifications follow the durable commit.
Initialize a chosen workspace explicitly before creating productions:
python -m studio.workspace init C:/StudioWorkspace
python -S bin/studio_admin.py --workspace C:/StudioWorkspace create example ./production.json --operation-id example-create-01
python -S bin/studio_admin.py --workspace C:/StudioWorkspace show example
The request file can contain {"title":"Example","deliverable":"film","resolution":"480p"}. Resolution is a declaration, subsequently validated against the chosen model; it is not a universal model default. Creation inherits the selected workspace's doctrine stamp, refuses an existing production and writes a scene-structure manifest, schema-valid STATUS with no declared phase, an empty shot registry and creation history. An exact retry returns the original result. Creation recovery is recorded at the workspace's .studio/operations/; subsequent operations use the production's own journal. Preserve both locations. Empty standard folders are recreated on a creation retry, without replacing their contents.
Scene and shot requests¶
Each command below takes a JSON request file. show returns the registry, manifest, STATUS and their revision map without writing anything.
| Command | Example request | Meaning |
|---|---|---|
scene example scene.json |
{"id":"SC1","title":"Opening","at":0} |
Add an ordered scene; duplicate IDs refuse. |
shot example shot.json |
{"code":"S1","title":"Door opens","scene":"SC1","order":0} |
Register a shot; no principal declaration is inferred. |
shot-edit example edit.json |
{"code":"S1","title":"Door stays closed","scene":"SC1","order":1} |
Change title, scene or order while retaining gate artifacts. |
card example card.json |
{"code":"S1","card":null} |
Remove the card; an object instead uses the existing card validator and normalizer. Cards remain advisory. |
shot-set example settings.json |
{"code":"S1","duration":8,"principals":[]} |
Declare the designed duration and deliberately declare population-only casting. |
Append --operation-id <unique-id> to each write. shot-set also accepts plate, verdict, identity_source, aliases, deps, remove_deps and restamp. principals, aliases, deps and remove_deps are lists. Empty principals is an explicit creative statement; omit the field when nobody has declared the cast. A null duration or identity source removes that declaration. An empty aliases list clears aliases. Plate approval uses the existing I1 lock stamps and D1 dependency rules; missing identity evidence remains a reported gate blocker. A stamp or restamp requires the director's actual decision, not merely a desire to make a check pass.
Gates, phase, lane and documents¶
python -S bin/studio_admin.py --workspace C:/StudioWorkspace gate example ./gate.json --operation-id brief-close-01 --by director
python -S bin/studio_admin.py --workspace C:/StudioWorkspace phase example --operation-id phase-01 --by director
python -S bin/studio_admin.py --workspace C:/StudioWorkspace lane-policy example local-only --operation-id lane-01
python -S bin/studio_admin.py --workspace C:/StudioWorkspace doc example SCRIPT.md ./script.md --operation-id script-01
A gate request is {"gate":"0","verdict":"GO","evidence":["docs/BRIEF.md"]}. The shared close follows the ladder's standing rung, permits applicable skipped optional gates behind it, preserves board-signing checks, and calls the existing receipt writer for evidence hashing and countersign requirements. Gate 6c derives its evidence from landed takes through the existing engine. If STATUS has no phase, the close plans that initial declaration before hashing evidence and commits it with the receipt. A failed close leaves neither a partial receipt nor an implicit phase behind.
phase raises the claim only to the existing gate engine's entitlement. Optional --value N asserts the number you expect. Proposed STATUS bytes are checked before writing: a change that would invalidate the very receipts backing the new phase refuses and leaves STATUS unchanged. Re-close those gates over their actual evidence artifact first.
lane-policy writes STATUS and its manifest mirror as one recoverable operation. Values are any, local-only and hosted-only; any removes the explicit field. Repeating an already recorded declaration with a different operation ID refuses unless the manifest needs repair. It is never a lane-policy waiver.
doc writes one Markdown filename under docs/. For STATUS.md, the input replaces only the prose body and retains schema-owned frontmatter. Normal document edits can stale earlier gate evidence, as intended. Prompt versions use studio_prompt.py; the document route cannot overwrite them.
World, cast, dependency and deviation records¶
python -S bin/studio_admin.py --workspace C:/StudioWorkspace world-confirm example 03-world/location/frame.png --operation-id world-01 --by director
World confirmation clears a proposed address on the selected asset, preserves media bytes and provenance, and records the old proposal in history. It checks confinement and production ownership. It does not approve the asset or bind a world location to a shot.
Existing engine commands remain available where they already own the workflow:
| Need | Command family | Boundary |
|---|---|---|
| Inspect the ladder and blockers | python -S bin/phase_gate.py why <slug> / check <slug> |
Reads the actual receipts and evidence. |
| Countersign or record an explicit waiver | python -S bin/phase_gate.py sign ... / waive ... |
Existing director/signature and scope rules apply; consult --help. |
| Rule on a recorded review deviation | python -S bin/shots.py approve-deviation <slug> <shot> <id> --by director / reject-deviation ... |
Updates the named review deviation; a bound preflight must then be rerun. |
| Add/remove/re-stamp dependencies | studio_admin.py shot-set with deps, remove_deps, restamp |
Uses the existing shot dependency implementation. |
| Rebuild the generated cast-lock mirror | python -S bin/identity_lock.py export-locks |
Re-reads every piece's cast/CAST.md and the workspace's legacy bible (the same build as bin/cast.py build); does not elect or amend a lock. |
There is no supported cast-lock setter. Amend the authoritative character record through the shared creative workflow, then refresh its generated mirror. Optional cast proposal measurement remains a separate capability and is not required for the core session workflow.
Recovery and scope¶
Writes require a stable --operation-id. Retry the exact request and actor using that ID after a transport or I/O failure. Optional --expected takes the revision map from show; stale values refuse rather than overwriting newer work. Actor text is provenance, not authorization. Conflicts and lock timeouts exit 3, invalid requests/refusals exit 2, I/O failures exit 4. Read commands do not repair pending operations.
The shared commands require writable scene productions; they do not migrate or activate archives. Journals coordinate participating local writers and retain exact before/after states. Existing low-level engine commands, direct text edits, external canon changes and network shares are outside that coordination guarantee. Gate verification still rechecks external canon at use, so a later source change can legitimately stale a receipt or phase claim. Use shared commands for supported compound edits; do not run a legacy writer concurrently against the same files.