# The production bible

> In short: The production bible records what "the same" means for each recurring character, place, prop or look, with the reference images that define it, and whether you have the right to use each. The Bible tab is where you build it; CODA can add to it and draft its rights, and only you affirm them.

Applies to: v0.10 · Last reviewed: 2026-11-02 · Canonical: https://docs.zymcos.com/product/production-bible/

A twenty-minute film is hundreds of shots, and what makes them feel like one film is that the
same character has the same face in every one of them. The production bible is where you record
what "the same" means: one entry for each recurring character, place, prop or look, with the
reference images that define it, and a record of why you may use each.

Those references are then supplied to every generation that involves that entry. The bible is
not documentation *about* your production — it is the input your production runs on.

## The Bible tab

The **Bible** tab sits in the middle of the workspace, between **Script** and **Viewport**. It is
a list on the left and the entry you choose on the right.

The list has four sections, one for each kind of entry:

| Section | What it is for |
| --- | --- |
| **Characters** | People you want to look the same in every shot. The entry whose face has to hold. |
| **Places** | Sets and locations that scenes return to and that should stay recognisable. |
| **Props** | Objects that have to match every time they appear. |
| **Looks** | A look supplied as conditioning to hold across the production. Not an identity, and never scored as one. |

A new production's Bible is empty, and each section says what it is for and offers a button to
make the first one ("New character", "New place", "New prop", "New look"). The API and the glossary
call each entry an *entity*; on screen it is always a character, a place, a prop or a look.

Across the top of the tab is the **lock strip**: where the Bible's lock is, the **Lock version N**
button and **History** (see [Locking](#locking-a-snapshot-not-a-state)). Each row shows its name and
up to three small labels: where its lock is, where its identity checks are (once it has been locked)
and where its rights are (all explained below). Choose a row and its details open beside the list, in
the order you need them: its name, its rights, its references, and what has been locked.

- **Make one.** Choose the section's "New …" button, type a name (1 to 200 characters) and create
  it. A name is unique within its kind in a production, so "which Maya?" is never a guess; if the
  name is taken the tab says so and nothing is made. The pack starts empty.
- **Rename it** in place with the pencil beside the name. Enter saves and Escape leaves it as it
  was. A rename does not need the rights re-affirming.
- **Delete it**, while it has never been locked. A confirmation names what goes. Once an entry has
  been locked into the Bible, shots may have been made from it, so the tab shows no Delete and says
  why in one line; the lock is the record of what your finished shots were made from.
- **Its kind does not change.** If you made a place that should have been a prop, delete it (while
  it has never been locked) and make the prop.
- **A voice** a character has is shown ("Has a voice") and cannot be changed from the tab.

Anything you have started typing in the tab (a new name, a rename, a rights form) counts as unsaved
work: the workspace will not switch to another tab on its own (for example when a take finishes
generating) while it is open, and shows a small marker on the Viewport instead.

## What the small labels mean

**Where the lock is.** Locking the Bible takes a numbered snapshot (see below), and each row says
how its entry stands against the newest one:

- **Not locked yet.** It has never been in a snapshot.
- **In version 3.** It was snapshotted in version 3 of the Bible and has not changed since. The
  number is the Bible's, the same one on the **Lock version** button, not a count of how often this
  entry has changed.
- **Edited since version 3.** It has changed since that snapshot, so locking again would make a new
  version of it.

"Edited since" is worked out by Zymcos, with the rule the lock itself uses, not by the screen.

**Where the identity checks are.** After a lock, Zymcos measures each locked character, place and
prop from its pictures, so that shots can be checked against how it looks (see [The continuity
gate](https://docs.zymcos.com/product/continuity-gate/)). It does this by itself, a few minutes after the lock, and the row
says where it has got to. A look has no identity checks and shows no label.

- **Identity checks: preparing.** The measuring has not finished. Nothing is wrong; give it a few
  minutes. Until it is ready, nothing says shots are being held to this entry.
- **Identity checks: ready.** Shots made with this entry are checked against its pictures.
- **Identity checks: can't be measured.** Zymcos looked at the pictures and could not find what it
  measures: no clear face in a character's pictures, or no usable picture of a place or prop. The
  label's hover text and the details beside the list say which. Shots can still use the entry, but how
  well a shot matches it is reported as **not measured**, never as a pass. The fix is better pictures
  (a clear, front-on face for a character), then a new lock; the same pictures will not measure
  differently later.
- **Identity checks: unavailable.** The checks could not run for the moment, because of a fault on
  Zymcos's side, and Zymcos tries again by itself. Nothing is wrong with your pictures.

**Where the rights are.** One of the four choices below, in plain words; **Rights not set** when none
has been affirmed; or **Rights withdrawn** when the permission behind the newest locked version was
withdrawn.

## Recording the rights

A person's likeness, a place or an object is someone's property, and the first question a studio's
counsel asks about an AI-assisted production is whether every character in it has a documented
basis. The **Rights** form in an entry's details is where you record it. There are four choices:

| Choice | What it says |
| --- | --- |
| **I made it** | You or your team made it, so the production may use it as its own. |
| **I have a licence** | A licence covers this use. Say what it covers. |
| **The person agreed** | A real person agreed to be shown. Record who agreed and how. |
| **AI-made, no real person** | Made with AI and not based on a real person. |

Beside the choice there is one line, **What does this cover?** (up to 200 characters): "all uses in
this production", "licensed to 2027, film and trailer".

**For "The person agreed" you also record who agreed and how it was recorded** ("signed release,
filed 12 March"). Both are required, and Zymcos refuses the save without them, naming the missing
one beside its field: a consent with nothing recorded is worse than no basis at all, because it reads
as permission and shows nothing a person could be asked for.

You can also attach the file that evidences the consent, such as a photo of the signed release. Under
**Evidence (optional)**, **Choose or upload a file** opens the same dialog the reference pack uses, for
one file: pick one of the production's pictures, or upload one from your computer. The chosen file's
name is shown with a **Clear**, and it is kept with the consent record. An attached file is evidence
and nothing more: it does not make the consent true, and attaching one grants no rights. A file already
attached is kept when you affirm again.

**Affirm rights** is the one button, and the click is the attestation: you are saying it is true. It
stays dimmed while the form matches what is already saved, and wakes when you change something.
Nothing else records a basis. In particular **CODA never does** (see below).

Two things to know about how it behaves:

- **No basis is not an error.** A draft legitimately exists before the paperwork does. The form says
  so, and also says what it costs: a shot cannot be cast with an entry until a basis is affirmed.
  Zymcos records your basis; it does not judge whether it is enough. What it does enforce is that
  an entry with no basis, or whose rights have been withdrawn, never reaches a shot, so nothing you
  pay to generate is conditioned on an undocumented likeness.
- **Re-curating a pack clears the rights.** Consent names specific images, so changing which images
  an entry uses invalidates the permission that described the old ones. After you save a changed pack
  the entry reads **Rights not set** again, and you affirm it again in this tab, unless you chose to
  keep the rights when you saved (see the next section).

### When someone else changed it while you were editing

If a teammate (or CODA) changed the entry after you opened it, your save is **refused rather than
overwriting theirs**, and the tab says so: "Maya changed while you were editing. This is what it says
now." What the entry says now is shown above the form, **what you typed is kept in the fields**, and
nothing is merged for you. Look at it, change what you need to, and affirm again: that save is
against the version you have now seen.

## Asking CODA

CODA can work on the Bible with you, and it always knows which entry you mean when you have one
selected in the tab:

- **Add, rename and delete.** "Make a character called Mara" and "rename her to Maya" are done at
  once, and CODA's reply shows what it did with an **Undo** (a made entry is undone by deleting it, a
  rename by putting the old name back). If you ask in your own words, "delete the prop Mug", and the entry holds no pictures and no rights,
  CODA deletes it and says so. If CODA suggested the deletion and you answered "ok", or the entry holds
  pictures or rights, you get a confirmation card instead, and **nothing is deleted until you click Delete on
  it**. CODA will not offer to delete an entry that has been locked.
- **Stage a rights draft.** "She signed a release on 12 March" gets a card in CODA with the basis,
  what it covers and who agreed, in your words, and one button: **Open in the Bible**. That selects
  the entry, switches to the tab and fills the form with the draft. **Nothing is saved until you click
  Affirm rights.** CODA cannot set a basis, a scope or a consent itself, and it cannot change an
  entry's kind, voice or pack from here: an attestation is a click, not an inference from a sentence.
- **Add a still.** The Viewport's **Add to Bible** (or "put this in Mara's pack" to CODA) puts a still
  into an entry's reference pack. If you ask CODA in your own words ("add that picture to Mara's
  references"), it adds it and says so, with the note that her rights need affirming again. If adding it was
  CODA's idea and you answer "ok", the card reads *Add this picture to Mara's references* (or the
  picture's name, when it has one) over an **Add to references** button, and nothing changes until you
  press it. When it is done the note offers **Open in the Bible**. With no entry
  yet, the dialog sends you to the tab to make one first. A pack that already holds twelve pictures is
  marked full in that dialog and cannot be chosen.
- **Take one out, or make one the main reference.** "Take the hat photo out of Mara's references" and
  "make the side view her main reference" are done at once when you ask for them, and CODA's reply says
  what it did with an **Undo**, which puts the earlier pictures back (when it was CODA's own idea and
  you answered "ok", you get a card first). Like any change to a pack, it clears the entry's
  rights, and CODA says so; **Undo clears them again**. CODA can only take pictures out and reorder
  the ones already there (to add a picture it uses Add to Bible, and uploading is yours to do in the
  tab), and it never keeps the rights for you: only you can tick that box.

- **Lock the Bible.** Ask for it in your own words ("lock version 1", "ok go ahead and lock it", "freeze it")
  and CODA runs the lock's **check** and puts the lock card in the conversation, the same card the Bible
  tab's strip opens, with what is still open and the **Lock version N** button. **CODA never locks for
  you, even when you ask**: a lock is one-way, so nothing is locked until you click, and on autopilot she
  does not lock either. The lock needs the same permission as the Bible tab's own button, and CODA
  **never affirms rights** for you: that click is yours. If a lock would be refused (the Bible is
  empty, entries have no references, nothing has changed), CODA says what is missing. A card left in the
  conversation goes quiet once its version has been locked.

Type **`@`** in the message box to insert a character, place, prop or look by its exact name, once it
has been locked into the Bible. CODA's cards say what the locked Bible contributed to a proposal, or
why it could not.

## Reference packs, and why they matter

An entry's **reference pack** is the list of pictures that define it. The **References** section of
its details is where you build it: the pictures are shown as a row, in order, with a count against the
limit ("6 of 12").

Today's generation models hold identity from references rather than from a description. Give
them the same three photographs of a character in shot after shot and the character stays
recognisable; describe her in words instead and she drifts. Everything else here (versions,
locking, the continuity check) exists to make sure the right references reach the right shot.

### The first four are the ones shots use

**Order is meaning.** A shot is offered the **first four** pictures of an entry's pack, in order, and
the first of them is the one the others support. Each of the first four says **Counts as a reference**. Any
after the fourth are drawn quieter and say **Kept, not used**: they are spares you can bring forward,
and the section says so in one line ("Shots are held to the first four. Drag, or use Move earlier
and Move later, to change which."). When you drag a picture a line shows where it will land (before the one you
are over), and a *Last in the pack* box appears at the end.

A pack holds **12 pictures at most**: four are used, the rest are spares, and a limit stops the
fingerprint of an entry drifting toward whatever was added last. When a pack is full, **Add
references** waits and says why.

### Changing a pack

Everything you do in the section is a **draft**. Nothing is saved until you choose **Save references**
(or throw the draft away with **Discard**), so a drag, a removal and an addition are one decision. A
draft counts as unsaved work, so the workspace will not switch tabs on its own while you have one.

- **Reorder** by dragging a picture to a new place, or with the keyboard: each picture has **Move
  earlier** and **Move later** buttons. Moves are announced to a screen reader ("Side moved to
  position 3 of 6").
- **Remove** takes a picture out of the pack. The picture itself stays in Files.
- **Add references** opens a dialog with two ways in:
  - **From your files** lists this production's pictures. Tick as many as you like; ones already in
    the pack are marked and cannot be added twice, and the dialog stops at the room the pack has left.
    The filter above the list searches the pictures that are loaded, which it says; **Load more**
    widens it. Withdrawn and erased files are not offered.
  - **Upload** takes one or more pictures from your computer (JPEG, PNG or WebP, up to 20 MB each).
    Each is sent in turn, shows its own state, and is refused in plain words if it cannot be used: a
    HEIC photo, a file that is too large, a full workspace, too many uploads at once. A file that
    finishes is added to your choice.

**What an upload is.** An uploaded picture becomes a file of this production, in Files. It stays
there **even if you discard the draft or never save it**. Uploading records that the file was put
here; it does not grant any right to use what is in it. The rights of an entry are the entry's own,
and you affirm them.

Only pictures can be references. Zymcos refuses, and says why, a file that is not an image, a file
that is withdrawn or erased when it is being added, and a thirteenth picture.

### Withdrawn and erased pictures

A picture already in a pack can later be withdrawn or erased in Files. It is **not dropped**: a pack
that changed behind your back would be worse. It stays in the row, marked **Withdrawn: not used in
shots** or **Erased**, each with its Remove, and neither is ever counted among the pictures shots use.
A picture the production no longer returns reads **Not found**, and can be removed the same way.

### Saving a changed pack clears the rights, and the section says so first

When an entry has a rights basis and you have a draft, the section says: "Changing the references
clears this entry's rights. You will affirm them again." Above Save there is one choice, **off by
default**: **Keep the current rights (I confirm they cover these references)**. Leave it off and the
rights are cleared when you save, and you affirm them again. Tick it and the current basis, scope and
consent are sent in the same save, which is you saying they still cover the new pictures. The tick is
your attestation, as **Affirm rights** is; CODA can never tick it. An entry with no basis has nothing
to clear, so it shows neither the sentence nor the box.

Practical guidance:

- **Several references beat one.** The identity fingerprint is built from the whole pack, not
  from whichever image happens to be first, so a varied pack is more robust than a single hero
  image.
- **Duplicates are dropped, order is kept.** Sending the same image twice does not weight it
  twice.
- **Show the thing you want measured.** A character whose pack is only back-of-head shots has no
  face to compare against, and her identity simply cannot be checked. That is reported honestly
  rather than passed silently, but it is easier to fix in the pack than in a shot.
- **A reference must belong to the same project.** An image id from anywhere else is rejected.

### When two people edit one pack

Each entry carries a **pack revision**, a number that goes up every time its pack, its voice or
its rights change. The Bible tab sends back the revision it was looking at when you affirm rights, and
so does anything you build against the API (`expected_pack_revision`, required whenever a request
sets `reference_asset_ids`, `voice` or a rights field; renaming needs none). A request that omits it
is answered with `428 Precondition Required`, and the revision may instead be sent as the standard
header `If-Match: "<revision>"`.

If someone else changed the pack after you read it, your change is **refused rather than
overwriting theirs**: the answer is a 409 `stale_pack` carrying the pack as it stands now, so you
can look at it and decide whether your change is still wanted. In the Bible tab the section says the
entry changed while you were editing, **keeps your draft in the order you left it**, and shows the
pictures the pack holds now; **Save references** again to replace them, or **Discard** to see them.
Nothing is merged for you, and nothing of yours is saved. Adding a take to a pack from the Files tab, or asking CODA to, follows
the same rule: if the pack moved in between, you are told and nothing is added.

## Locking: a snapshot, not a state

A locked version's pictures are not edited in place. In an entry's References, while the pictures are
exactly what a version locked, a line says **These are the references locked in version 3. Changing
them starts a new version; version 3 stays as it is until you lock again.**

**Locking the bible takes a numbered snapshot of the whole registry.** Every entity in the
project gets a fresh, immutable version carrying the pack and the rights it had at that moment,
and the snapshot itself is recorded as version 1, 2, 3 and so on. Shots you make from then on are
held to those versions as they were on that day.

The word "lock" is film vocabulary, and it can mislead here, so it is worth being precise:

- **Nothing is frozen.** Your entities stay editable after a lock. That is deliberate — a
  production keeps developing, and only the version a finished shot was made from must not move.
- **There is no unlock, because there is no state to leave.** Correcting a mistake means editing
  the entities and locking again. Versions accumulate, which is intended and costs nothing.
- **A version, once minted, never changes.** That is what makes a retake reproducible: a shot
  redone six weeks later uses exactly the references it used the first time, even if the entity
  has moved on since. It is also what makes drift attributable — you can point at a specific
  locked reference rather than at a moving target.

### The lock strip

The strip across the top of the Bible tab says where the Bible's lock is, in one line: **Version 3
locked 2 October**, or **Not locked yet**. Beside it are **History** and the **Lock version 4**
button, which always names the version the next lock would make. The strip is drawn from what Zymcos
reports about the Bible now, so it never offers a lock that would be refused:

- **Lock version 4** is available when a lock would do something new.
- **Nothing has changed since version 3.** The button waits. A lock where nothing differs would only
  repeat the last one. (Renaming an entry on its own is not a change to what shots are held to: a name
  is not part of a locked version.)
- **2 entries need references.** The button opens the card, which names them (see below).
- **The Bible has no entries yet.** The button waits.

**History** opens a list of every lock so far, newest first: its version, its date and how many
entries it took. It is a list to read; there is no comparing two versions and no going back to one.

### The lock card: check, then one click

Pressing **Lock version 4** opens the **lock card** right there, under the strip. Nothing is locked
yet. Its first line says what it would do: **Lock version 4: 12 entries, 3 changed since version 3,
2 without rights.** Under it is the lock's **check**, one row for each thing a lock cares about, each
with a word (**fine**, **open** or **stops it**) and, where something is open, the names with a
**Show me** link that opens the place:

- **Entries**, **Pictures** (entries with no pictures stop the lock), **Rights** (entries without a
  basis, which can still be locked, and a shot cannot be cast with them until one is affirmed) and
  **Changes** since the last lock;
- a line at the end of the check: **Nothing is open. You can lock.** or **These are still open. You can
  lock anyway.**;
- what a lock means: **Shots you make from now on are held to these as they are today. You can keep
  editing and lock again; a lock is never undone.**

The check is a compact box tinted by its verdict, green when nothing is open, amber when something is and red when the lock would be
refused. On a wide panel each row's detail sits to the right of its label, so the whole check fits without scrolling. The lock buttons
carry a padlock, and a locked script's **Unlock** button an open one.

When the check found things open the button says **Lock anyway**; when nothing is open it says **Lock
version 4**. It is the second step, and the only one that locks. **Cancel** closes the
card and puts you back on the strip's button; nothing was saved. Afterwards the strip says **Version 4
locked**, and the rows' labels change by themselves.

If the card says a lock cannot go ahead, it says why. When the reason is that entries have no
references, each is listed with **Add references**, which selects that entry and takes you to its
References section, where you add pictures; then come back and lock.

If someone else locks version 4 while you are looking, the card says **Version 4 was locked while you
were looking; this is the new state.** and shows what a lock would take now. Nothing is lost and
nothing was locked twice.

A member who can only view the production sees the strip, the card and History, and the card's lock
button waits with a sentence saying locking is for members who can curate.

### What an entry shows of its locks

**What has been locked**, in an entry's details, lists the versions a lock took of that entry, newest
first: the Bible's version it was in, the date, the rights it was locked with (or that it had none,
or that they were withdrawn), where its identity checks were, and its pictures. The newest version
shows its pictures at once; **Show pictures** opens the others. An entry with a long history shows the
latest 50 and says how many there are.

### When a lock is refused

A snapshot covers the whole registry, so it refuses rather than quietly skipping. The strip and card
say each of these before you press, and again if one arrives after:

- **An entity with an empty reference pack.** The card names the unfinished entities. An entity with
  no references cannot condition a generation and cannot be checked for continuity; the lock is the
  cheapest moment to notice that.
- **A project with no entities at all.** There is nothing to snapshot.
- **Nothing has changed.** No entry differs from the last lock and none was added.
- **A version someone else just took.** Two people locking at the same moment is resolved by
  refusing the second rather than silently creating two near-identical snapshots. The card shows the
  new state; lock again if there is still something to lock.

### What a lock reports rather than refuses

A lock tells you how many entities it snapshotted and how many of them have **no rights basis
yet** — "12 entries, 2 without rights". It is a report, not a blocker. Drafts legitimately exist
before the paperwork does, and a bible you cannot snapshot until every release form is signed would
stop all creative work on a legal dependency.

The refusal that protects you arrives later and more precisely: a shot cannot commit to a
version with no basis, so nothing is *generated* from it.

## Casting a character into a shot

A shot is held to the entries you **cast** in it: the pictures of each are what a generation of that
shot is made from, and what its continuity is measured against. You cast from the **shot editor**
(the **Edit** button on a shot in the Script tab), in its **Cast** section: one row for each entry of
the Bible, grouped as Characters, Places, Props and Looks, each saying where it stands for this shot.

- **Not in this shot** has a **Cast** button. It casts the entry's newest locked version, at once,
  and an **Undo** follows.
- **In this shot** says which version of the Bible it was cast from ("As locked in version 3") and has
  **Take out**.
- **In this shot, with a newer version in the Bible** says both numbers and offers **Update**. A shot
  never moves to a newer version by itself: a shot with takes made against version 2 is a different shot
  once it is held to version 3, so that is your click. Update swaps the two in one step, so the shot is
  never left uncast between them.
- **Not locked into the Bible yet** offers **Lock first**, which opens the Bible on that entry. The editor
  never locks anything for you.
- **A shot cannot be cast with this until a basis is affirmed** offers **Rights**, which opens the Bible.
  An entry whose rights were **withdrawn** cannot be cast, and the editor offers no way round it.

A cast shot is **held**: a take made for it is made on a model that takes character pictures, and its card says **Holds Mara's look from Bible v2**. If no model on your plan can hold a cast character, no card is made and nothing is spent (see [Create](https://docs.zymcos.com/product/create/)).

Under the section a line says what the cast does to a generation: "Held to 7 pictures; 2 did not
travel", and for each picture that did not, why (withdrawn, erased, or beyond the first four a shot is
held to). Changing the cast does not change takes already made: each score keeps the version it was
measured against.

You can ask CODA in words: "put Maya in shots 2 and 3" or "take Maya out of shot 2". It casts the newest
locked version into each shot you name (at most twelve at a time), says which shots it changed and
which it did not, and offers Undo. Casting never locks the Bible and never sets rights to make a cast
possible: if an entry cannot be cast it says why, and you ask for the lock or do the rights yourself.

## Withdrawing rights

If a permission is withdrawn, the affected version is marked as revoked. This is the one change
that is ever made to a locked version, and it is **not retroactive**:

- shots that already committed to it stand — they are the record of what happened, and rewriting
  history would destroy the provenance the record exists to give you;
- new commitments to that version are refused from that moment on.

## What happens after a lock

Locking is also what makes continuity measurable. After a lock, Zymcos reduces each version's
reference pack to a compact fingerprint by itself, one for a character's face, one for a figure or
prop, one for a set, and the continuity check compares generated frames against those. The row's
**Identity checks** label says where that has got to (see "What the small labels mean"). A pack that
yields nothing usable leaves that fingerprint absent, and the check says so rather than inventing a
result.

That side of the system is described in [The continuity gate](https://docs.zymcos.com/product/continuity-gate/).
