What it is
A series is not a longer novel. It is a canon problem: names, ages, promises, and physical facts have to stay true across books written months or years apart, while each book still has to stand alone for a reader who starts there.
Vellum's library layer holds that canon explicitly instead of re-inventing it book by book. It lives outside every book project — project-setup never creates one, and library init refuses to run inside a book — so a single-book project keeps working byte-identically whether the layer is installed or not, and whether any book is linked.
The layer adds no fourth gate. Its findings are advisory; the three hard gates are unchanged.
What it stores
The library root is the only place series state exists:
- library.jsonThe manifest.
kind: "vellum-library"; unknown fields are rejected rather than ignored. - series/bible.jsonThe single source of truth for canon, with per-field
by-bookvalue maps. The effective value at a book ordinal is a map lookup — no log-walking, nocanon:mirror in any book file. - series/retcons.jsonlAn append-only audit log that records the author's words verbatim, never edited.
- series/exemptions.jsonSeries-scope dismissals. They never touch a book's
kb/exemptions.json. - series/errata.mdHuman-owned reader-facing errata posture, recorded once.
A linked book receives only an inert pointer sidecar, .vellum/series-link.json, plus an optional opt-in series-id: line on entity frontmatter. The layer never edits a linked book's kb/story.md, CLAUDE.md, or hooks.
The subcommand surface
Run through python scripts/library.py. Every subcommand takes an explicit --root; there is no filesystem discovery.
| Subcommand | Purpose |
|---|---|
library init <root> | Create the library tree outside any book project. Refuses inside a directory containing kb/, manuscript/, or state/. |
library link <book-root> / unlink | Attach or detach a book. Linking is idempotent and crash-recoverable: sidecar first, manifest second. |
library validate | Read-only integrity check — schemas, half-linked states, refs, series-id: joins, errata refs. --fix repairs sidecars. |
library bootstrap <book-root> | Deterministic canon capture with exact, alias, and [?] match tiers. [?] rows write nothing until you resolve them; --apply requires an approved plan. |
library retcon-check <book-root> | Run the detection catalog — dead-character reanimation, open-thread carry, knowledge anachronism, canon divergence. Read-only and advisory. |
library retcon-plan <book-root> | Draft a retcon plan report from templates/retcon-plan.md. |
library retcon --apply <plan> | Apply an approved plan row by row. Refuses without approved: true and your verbatim words on every row. |
library state <book-root> | Print the series state card. It is injected into vellum state when a book is linked. |
library timeline | Emit the stable E### master timeline, never renumbered. |
library handoff <book-root> | Generate the next book's handoff: frozen canon, iron facts, the do-not-re-explain register, open retcons, errata posture. |
library dismiss <id> --reason "…" | Record a series-scope dismissal in your own words. |
Inside Claude Code, /vellum:series routes you through the series skill, which owns the operator's manual and the finding catalog.
Doctrine
The gates stay three
Series findings are advisory and the layer adds no fourth blocker. Exit codes stay 0 clean, 1 findings or plan, 2 usage or schema error.
Published canon is frozen
Book status is draft | published | archived. For published books the default merge is retcon record required: the draft loses, never later-wins. Changing frozen canon needs your explicit override. Archived books are fully quiet.
No invention
Bootstrap matches only frontmatter fields and knowledge-base entity names, never chapter prose. Ambiguous rows are marked [?] and write nothing until you resolve them. The retcon log records your words verbatim.
No hidden coupling
A linked book is not rewritten. The layer adds one inert sidecar and, optionally, a join key. Uninstalling means library unlink per book, then deleting the library root — no hidden state remains.
Compatibility, enforced
The series layer had to prove it did not disturb the single-book tool that existed before it. A byte-identity golden suite snapshots the full v0.1.1 command surface before linking, after linking, after bootstrap, and after a retcon; it asserts the outputs are byte-identical except for the opt-in series-id: lines. A second test deletes the series modules and re-runs the same surface unchanged.
Read the semantics in DESIGN.md §18 and the validation record in VALIDATION.md.