# lumilib

> The all-in-one, open-source writing/filming platform for agentic coding.
> A coding agent runs a serialized show end to end — story → screenplay →
> canon → storyboard → render → edit → publish — through MCP + one CLI.
> The human defines intent and reviews; the agent operates.

## Connect

- MCP endpoint: POST /api/mcp (Streamable HTTP, stateless)
- Auth: per-project bearer key (llk_…) from Console → Connect
- Claude Code: claude mcp add --transport http lumilib <origin>/api/mcp --header "Authorization: Bearer <key>"
- CLI RPC: POST /api/v1/rpc with { tool, args } and the same bearer key
- First move after connect: call the fetch-docs tool.

# lumilib — production conventions

No project is linked to this key yet.

lumilib is the agent-native writing/filming platform: seven stateful creative
primitives a coding agent operates end to end. The human defines intent and
reviews; you run the studio.

## The seven primitives (operate them in this order)

1. story      — ingest a premise, chapter or novel; chapters & events become state
2. screenplay — adapt the story into episodes with per-episode scripts
3. canon      — register characters / scenes / props and LOCK their visual identity
4. storyboard — board each episode into a shot list with continuity constraints
5. render     — enqueue image / video / audio renders bound to canon refs
6. edit       — compose shots, subtitles & score into an episode cut
7. publish    — export 9:16 masters and post to connected platforms

## Conventions

- Identity refs: every canon entity has a ref like `@mara.v3` or `@set.boardroom`.
  Every render MUST bind to the refs it depicts. Renders that drift from a locked
  ref will be flagged by the continuity Advisor.
- Shot codes: `S<ep>-<nnn>`, e.g. `S19-004` = episode 19, shot 4.
- The loop: after ordering renders, poll the queue; after an episode's renders
  land, run the Advisor audit (run-audit) BEFORE cutting. Fix fails, then cut,
  then publish.
- Everything you do is written to a machine-readable activity log the human
  reviews. Failed renders are held for the Advisor, not silently retried forever.

## Your first moves in a new session

1. fetch-docs (you are here)
2. read-project — pull config, episode state & pipeline status
3. read-canon — pull the identity registry before boarding or rendering

## MCP tools

- fetch-docs (discover): Read production conventions — every agent's first move.
- read-project (discover): Pull project config, episode state & pipeline status.
- ingest-story (story): Bring in a premise, a chapter, or a whole novel; extract chapters.
- adapt-episodes (screenplay): Break the ingested story into a season of episodes.
- read-canon (canon): Query the character / scene / prop registry + consistency.
- lock-identity (canon): Pin an entity's visual identity as the source of truth.
- board-episode (storyboard): Generate a shot list with continuity constraints.
- order-render (render): Enqueue image / video / audio against bound canon refs.
- poll-queue (render): Read render task status, retries and cost.
- run-audit (advisor): Run the deterministic continuity gate over a scope.
- cut-episode (edit): Compose shots, subtitles & score into an episode master.
- publish (publish): Export 9:16 and post to connected platforms.

## CLI

The same surface is drivable from any shell via the lumilib CLI
(`node bin/lumilib.mjs` in the repo, or the `lumilib` binary):

- lumilib login --key llk_… — Authenticate — or let the agent self-provision.
- lumilib link — Associate this directory with a project.
- lumilib story ingest <file> — Bring in a premise, chapter, or whole novel.
- lumilib screenplay adapt [n] — Break the story into a season of episodes.
- lumilib screenplay board <ep> — Break an episode into a constrained shot list.
- lumilib canon lock <ref> — Lock an identity every render must bind to.
- lumilib storyboard render <shots> — Enqueue renders for a shot range.
- lumilib render poll — Read the queue — status, retries, spend.
- lumilib diagnose advisor <ep> — Find continuity drift and get a proposed fix.
- lumilib cut <ep> — Compose the episode master.
- lumilib publish <ep> — Export 9:16 and post.

Machine-readable pricing lives at /llms.txt on this host. Budget before you
render: video ≈ $0.84/shot (veo-3), image ≈ $0.04 (fable-5-image), audio ≈ $0.02
(elevenlabs-v3) in the simulated gateway.