Metadata-Version: 2.4
Name: northnoir
Version: 2.2.0
Summary: Local AI-drawn video: Ruvil 2.1 code-drawn scenes rendered on your machine, local assembly of Ruvil 7.3 frame images, and optional per-asset generation on your own provider keys. Whole-film generation is the North Noir MCP server's job.
Author: North Noir
License: Proprietary
Project-URL: Homepage, https://northnoir.com/cli
Project-URL: Documentation, https://northnoir.com/cli
Project-URL: Source, https://github.com/syver777/NorthNoir/tree/main/packages/northnoir-cli
Keywords: ai-drawn-video,animation,cli,playwright,ffmpeg
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: playwright==1.63.0
Requires-Dist: Pillow==12.3.0
Requires-Dist: numpy==2.5.3; python_version >= "3.12"
Requires-Dist: numpy==2.2.6; python_version < "3.12"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Provides-Extra: ncel
Requires-Dist: northcel[fit]>=0.7.2; extra == "ncel"

# northnoir — the local CLI for AI-drawn video

## Before you spend anything — ask first

**The CLI assembles your film on your machine. North Noir MCP (or your own
provider keys) makes the images and the sound.**

Before spending anything, **ask the user ONE message with these questions and
wait for the answers (never choose silently)**:

1. **Drawing model:** Ruvil 2.1 (code-drawn, runs locally, free, no key) or
   Ruvil 7.3 (every frame is its own image).
2. **For Ruvil 7.3, where the images come from:**
   - **(A) North Noir MCP — recommended.** Billed at actual cost × 1.4, about
     **$0.40 per image** at the default model, so a 15 s film (90 images at
     6 fps) is roughly **$36** before retries. Needs one North Noir key.
   - **(B) Their own OpenAI key:** local `northnoir image`, no North Noir
     charge.
   - **(C) Another image model only if the user names one** — and say plainly
     if it is not available through A or B.

   Which image model: recommend `gpt-image-2.6-sunburst`; the other choices
   come from `list_drawn_video_options`.
3. **Sound:** none (the default for whole runs) or which sound-effects and
   music models (`northnoir models --sound`). Per-asset MCP calls default to
   Mirelo SFX 2.0 (effects) and Mureka V9 (music) when called.
4. **Show the estimated cost and get a yes before the first paid call.**

**Do not use `create_drawn_video`, `plan_drawn_video`, `confirm_drawn_video`,
`get_job`, `get_drawn_video_frames` or `reroll_drawn_video_frames` unless the
user explicitly asks for the whole film to be made in North Noir's cloud.**
Those run the whole film on North Noir's servers (planning, drawing, review,
rendering). For the local path use only `generate_frame_image`, `generate_sfx` /
`generate_sfx_batch`, `generate_music` plus the CLI's `northnoir sfx-track` and
`northnoir draw --cels`.

### The local path, in order

1. Install or update the CLI: `pip install --upgrade --no-cache-dir northnoir`
   (or `pipx install northnoir`), then check `northnoir --version`.
2. One `generate_frame_image` per frame — no numerals and never the word "cel"
   in the prompt; reference as a `data:` URL via `northnoir ref data-url` or a
   public HTTPS URL.
3. One `generate_sfx_batch` for the cues (or none). Keep the same
   `request_id` when retrying: a completed cue replays for free, a failed cue
   is retried and its stored failure replaced. Send the default mirelo-sfx-2 up
   to 4 cues per batch, or stable-audio-open 3–4 cues (that route runs 3 at a
   time and can queue under load).
4. One `generate_music` for the bed (or none).
5. `northnoir sfx-track --cue … --duration N -o sfx/sfx-track.wav` builds the
   one SFX track.
6. `northnoir draw --model latest --cels cels --plan plan.json --sfx-file
   sfx/sfx-track.wav --music-file music/music.mp3 --out film`.

`northnoir` is the tool you run **on your own machine**. It draws, checks and
renders AI-drawn video locally. Anything that has to happen in North Noir's
cloud is done by the **MCP server** from your chat/agent harness — not by this
CLI.

Two modes, one meaning each:

| Mode | What it means | Where it runs |
|---|---|---|
| **per-asset** | **one frame, one cue, one music bed** — "generation only", exactly what a local render needs | North Noir's cloud via **MCP** (recommended), or a local command on your own provider key (`northnoir image` / `sfx` / `narration` / `draw --music`) |
| **whole-project** | **plan → draw → review → deliver**, executed as one film in North Noir's cloud | North Noir's cloud, called by **MCP** (never the CLI) |

The render itself always stays on your machine: `northnoir draw` (Ruvil 2.1) and
`northnoir draw --model latest --cels …` (Ruvil 7.3 assembly) use your CPU and
disk and call no provider and no North Noir API. For the per-asset pieces a film
needs, four **local** commands can call **your own** provider keys — `northnoir
image` (frames), `northnoir sfx`, `northnoir narration`, and `draw --music
"<prompt>"` (the music bed) — and the exact matrix is below. A labelled,
non-recommended REST backend also exists for non-MCP clients (`northnoir api …`);
the **MCP server is the supported way** to generate anything the local process
cannot draw. **The CLI has no cloud generation command**, and no command
silently bills North Noir.

## Install

Recommended (isolated, puts `northnoir` on your PATH):

```sh
pipx install northnoir
northnoir doctor --install   # installs Chromium via Playwright, then verifies
northnoir doctor             # Chromium, ffmpeg, pinned libraries (SHA256)
```

With NorthCel, for `.ncel` scenes and `northnoir polish` (the Ruvil 7.3 →
20 fps workflow):

```sh
pipx install "northnoir[ncel]"
```

The `ncel` extra installs [NorthCel](https://github.com/syver777/northcel), a
separate project, as `northcel[fit]>=0.7.2`: the vector language, its renderer
and the contour fitting the CLI drives. The current NorthCel release line is
0.7.x. To bring an existing install up to the newest NorthCel, reinstall with
`pipx install --force "northnoir[ncel]"` (pipx) or run
`pip install -U "northcel[fit]"` in the same environment (pip).

Alternatives:

```sh
uv tool install northnoir    # same PyPI package, via uv
pip install northnoir        # into the current Python environment
```

On a machine with a stale pip index or cache, `pip install -U northnoir` can
report "Requirement already satisfied" for an outdated version. Use the CLI's
own updater, which knows how this copy was installed:

```sh
northnoir update             # prints the exact command for this install
northnoir update --yes       # runs it
northnoir --version --check  # compare with PyPI (quiet when offline)
```

The underlying commands, if you would rather run them yourself:

```sh
pipx upgrade northnoir                                        # pipx
uv tool upgrade northnoir                                     # uv
python3 -m pip install --user --upgrade --no-cache-dir northnoir        # pip --user
python3 -m pip install --user --upgrade --no-cache-dir --break-system-packages northnoir
                                                              # Debian/Ubuntu system Python
```

From source: `git clone https://github.com/syver777/NorthNoir.git`, then
`pipx install ./NorthNoir/packages/northnoir-cli`.

Requirements: Python 3.10+, `ffmpeg` on PATH (`brew install ffmpeg` on macOS,
`sudo apt install ffmpeg` on Debian/Ubuntu). Chromium is installed for you by
`northnoir doctor --install` (Playwright). Docker is an optional transparent
fallback when a local `ruvil-js-renderer:local` image exists.

The npm package is **not published**; `bin/northnoir.js` is a repo-only thin
Node shim over the Python package.

## Quickstart: Ruvil 2.1, fully local

Ruvil 2.1 (`ruvil_2_1`, Code-drawn / `.js`-drawn) is the default AI-drawn model.
You (or your agent) write a `.js` canvas drawing program (`scene.html`), the CLI
renders every frame in headless Chromium, and the frames become an H.264 MP4
with procedural stereo audio. **No provider keys, no North Noir key and no
network call to North Noir are involved** — the drawing code is yours, the
`.js` canvas paints every frame, and this costs nothing from North Noir and
nothing from any provider.

```sh
northnoir init shot --duration 2 --fps 24
# Edit shot/scene.html, then look at the still and motion checks.
northnoir check shot/scene.html --still
northnoir check shot/scene.html
northnoir render shot/scene.html -o shot/video.mp4

# Equivalent explicit model route (writes output/scene.mp4):
northnoir draw --model ruvil_2_1 --scene shot/scene.html --out output
# Omitted --model means Ruvil 2.1 too:
northnoir draw --scene shot/scene.html --out output
```

The **Ruvil 2.1 4-step agent loop** is the product:

1. **Author** — `scene.html` paints every frame of a 1920×1080 canvas; frame 0
   already shows the finished scene.
2. **Still check** — `northnoir check scene.html --still`, then *view*
   `frame-0000.png`. Fix composition, scale and contrast before animating.
3. **Motion check** — `northnoir check scene.html`, view `contact-sheet.png`,
   read the readability/collision/composition flags, fix, re-check (up to 3
   improvement rounds; keep the best version).
4. **Render** — `northnoir render scene.html -o out.mp4`, view the poster,
   verify with `ffprobe` (1920×1080, H.264, declared duration, stereo audio).

Ruvil 2.1 in **NorthCel (`.ncel`)** is an explicit opt-in language
(`pip install "northnoir[ncel]"`): compact flat cel/ink, palette colour,
deterministic boil and one editable film per cut (`mix` colours, `morph`,
`frame A..B` ranges, `opacity`, plus groups, `transform`, `warp` and `nudge`
for editable deltas). It is not Ruvil 7.3 images as frames. The bundled
`NCEL-GUIDE.md` and `NCEL-SPEC.md` (find them with `northnoir skill --json`)
cover the syntax.

```sh
northnoir init ink --language ncel --duration 3 --fps 24
northnoir check ink/scene.ncel --still
northnoir check ink/scene.ncel
northnoir render ink/scene.ncel -o ink/video.mp4
```

## Providers: the exact matrix

This table is generated from the code (`providers.PROVIDER_MATRIX`) and
checked by a test, so it cannot drift from what the CLI accepts. **route**
`local` = one call from your machine on **your** key; `api` = the
non-recommended North Noir REST backend; `mcp` = the recommended way.

| Slot | Route | Provider | Command / flag | Env var | Status |
|---|---|---|---|---|---|
| frames | local | openai | `northnoir image --prompt ... -o cel.jpg` | `OPENAI_API_KEY` | supported |
| frames | local | fal | `—` | `FAL_KEY` | not wired: no fal image adapter exists in the CLI |
| frames | api | northnoir | `northnoir api image --prompt ...` | `NORTHNOIR_API_KEY` | not recommended (API backend) |
| frames | mcp | northnoir | `MCP generate_frame_image` | `nn_live_... key` | recommended |
| sfx | local | elevenlabs | `northnoir sfx --provider elevenlabs` | `ELEVENLABS_API_KEY` | supported |
| sfx | local | fal | `northnoir sfx --provider fal` | `FAL_KEY` | supported |
| sfx | local | code | `northnoir sfx --provider code` | `none` | supported (procedural, free) |
| sfx | api | northnoir | `northnoir api sfx --prompt ...` | `NORTHNOIR_API_KEY` | not recommended (API backend) |
| sfx | mcp | northnoir | `MCP generate_sfx` | `nn_live_... key` | recommended |
| music | local | elevenlabs | `northnoir draw --cels <dir> --music "<prompt>"` | `ELEVENLABS_API_KEY` | supported (local bed, cut to the film) |
| music | local | fal | `northnoir draw --cels <dir> --music "<prompt>" --music-model <route>` | `FAL_KEY` | supported (local bed, cut to the film) |
| music | api | northnoir | `northnoir api music --prompt ...` | `NORTHNOIR_API_KEY` | not recommended (API backend) |
| music | mcp | northnoir | `MCP generate_music` | `nn_live_... key` | recommended |
| narration | local | elevenlabs | `northnoir narration --voice <voice-id>` | `ELEVENLABS_API_KEY` | supported |
| narration | local | openai | `northnoir narration --provider openai --voice alloy` | `OPENAI_API_KEY` | supported |
| narration | local | file | `northnoir mix --narration narration.wav` | `none` | supported (a file you already have) |
| narration | api | northnoir | `northnoir api voice --text ...` | `NORTHNOIR_API_KEY` | not recommended (API backend) |
| narration | mcp | northnoir | `MCP generate_narration` | `nn_live_... key` | recommended |

Printed offline by `northnoir models --providers` (add `--json` for the same
rows as JSON).

### Local per-asset generation (your own keys)

```sh
# Frames: one OpenAI image per call, saved in cel order for Ruvil 7.3 assembly.
northnoir image --prompt "a hand-drawn boy looking left, loose ink lines, \
   no text, no writing, no numbers, no paper edges, no borders" \
  --model gpt-image-2.6-sunburst --size 1536x1024 --quality high \
  --ref start-face.jpg -o cels/f0001.jpg

# Sound effects: ElevenLabs direct (default), fal, or free procedural foley.
northnoir sfx --prompt "soft wind and a duck quacking" --seconds 6 -o sfx.mp3
northnoir sfx --provider fal --prompt "rain on a tin roof" --seconds 4 -o rain.mp3
northnoir sfx --provider code --prompt "footsteps on tile" --seconds 2 -o steps.wav

# Narration: ElevenLabs (needs --voice) or OpenAI speech.
northnoir narration --provider elevenlabs --voice <voice-id> --text "..." -o voice.mp3
northnoir narration --provider openai --voice alloy --text "..." -o voice.mp3

# Music bed: ElevenLabs direct (default) or a fal route, cut to the film.
northnoir draw --model latest --cels cels --out film \
  --music "warm playful orchestral bed, instrumental"        # ELEVENLABS_API_KEY
northnoir draw --model latest --cels cels --out film \
  --music "a quiet piano bed" --music-model sa3-medium       # FAL_KEY
```

Every call prints one JSON receipt with `provider`, `model`, `file`,
`bytes_written` and `provider_calls`, and appends the attempt to the run ledger
(`cost-ledger.json` beside the output). Keys are read from the environment or
`~/.config/northnoir/keys.json`: `OPENAI_API_KEY`, `ELEVENLABS_API_KEY`,
`FAL_KEY`. A paid send is **never retried automatically** — a timeout after the
request reports `outcome_unknown` instead of possibly double-billing. `northnoir
sfx --provider code` sends nothing at all. `northnoir image` writes JPEG, so name
its output `.jpg`/`.jpeg`; a run receipt (`cost-ledger.json`) is written only
when you pass an explicit `-o`.

Not available locally, and why:

- **fal image models** — the CLI has an OpenAI image adapter only.
- **An automatic vision judge for generated frames** — the CLI has no local
  review loop; you (or your agent) look at the frames. Whole-project MCP runs
  include North Noir's own review.
- **Video-to-sound routes** (Sonilo/Mirelo/Kling/PixVerse/Hunyuan) — they score a
  finished film and are offered by MCP `generate_sfx` only.

### The REST API backend — not recommended

`northnoir api …` drives the same public REST API (`https://northnoir.com/api/v1`)
with one `nn_live_…` key: `models`, `voices`, `generate`/`video`, `estimate`,
`wait`, `frames` (with `--reroll`), `flagged`, `download`, `image`, `sfx`,
`voice`, `music`, `jobs`. It is opt-in, never the default, prints a
**NOT RECOMMENDED — use MCP** notice on every call, and is labelled that way in
`--help`.

```sh
northnoir api estimate --prompt "a lighthouse keeper" --seconds 8
northnoir api generate --prompt "a lighthouse keeper" --seconds 8 --out film/
```

**Use the MCP server instead** (`https://mcp.northnoir.com/mcp`): it is the
supported path, it plans and reviews whole films, and it needs no shell
plumbing. The API backend exists for non-MCP clients and scripts only. Exit
codes: `0` ok, `1` failed, `2` invalid input, `3` no/invalid key, `4` no credit,
`5` wait timeout (the job keeps running; `northnoir api wait JOB` resumes).

## Connect MCP to your harness

Cloud work — every generated frame image, the sound effects, and whole film
runs — goes through the North Noir **MCP server** (a music bed can also be
generated locally on your own key; see the Ruvil 7.3 section):

- Endpoint: `https://mcp.northnoir.com/mcp`
- Auth: `Authorization: Bearer nn_live_…` (create a key at
  [northnoir.com/developer](https://northnoir.com/developer); clients that
  support MCP OAuth can sign in through the browser instead)
- Expose these tools to your agent (the pipeline plus the per-asset ones):
  `plan_drawn_video`, `confirm_drawn_video`, `generate_frame_image`,
  `generate_sfx`, `generate_music`, `get_drawn_video_frames` — plus
  `create_drawn_video_project` and `get_job` for whole-project runs.

Keep keyed configs out of version control, and never paste a key into chat.
`northnoir auth nn_live_...` (alias `northnoir login`) saves the key in
`~/.config/northnoir/keys.json` (0600) as one local place to manage it; the MCP
client config still needs the key (or OAuth).

**Claude Code**

```sh
claude mcp add --transport http \
  --header "Authorization: Bearer nn_live_YOUR_KEY" \
  north-noir https://mcp.northnoir.com/mcp
# OAuth instead: omit --header, then run /mcp inside Claude Code.
```

**Claude Desktop / Claude web** — add a custom connector with the URL
`https://mcp.northnoir.com/mcp` and approve the browser sign-in. Consumer Claude
connectors require OAuth; they cannot use a static `nn_live_` header.

**opencode** (`.opencode/opencode.json` or `~/.config/opencode/opencode.json`):

```json
{
  "mcp": {
    "north-noir": {
      "type": "remote",
      "url": "https://mcp.northnoir.com/mcp",
      "headers": { "Authorization": "Bearer nn_live_YOUR_KEY" },
      "enabled": true
    }
  }
}
```

**Any other MCP client** — a Streamable HTTP MCP server at
`https://mcp.northnoir.com/mcp`. Send `Authorization: Bearer nn_live_…` on every
request; `GET /health` answers `{"ok":true}` without auth so you can check
reachability. The same config shape works for Cursor (`.cursor/mcp.json`).

## Ruvil 7.3, no keys: MCP for frames, local assembly

Ruvil 7.3 (`ruvil_7_3`, public alias `latest`) is Hand-drawn frame-by-frame:
**each frame is drawn/generated as its own 2D image** (images as frames, 6 fps,
classical hand-drawn timing). With no provider keys at all, the split of work is
deliberate and this is the **recommended** path:

- **MCP draws every cel** — one `generate_frame_image` call per frame image,
  plus `generate_sfx` / `generate_music` when you want sound. Those are the only
  paid calls: **each cel is billed as a per-asset call** (200,000 NorthNoir
  tokens per image with the North Noir key — $0.40 at $2 per 1M — and zero
  provider tokens with BYOK). Nothing is billed for planning a strip you write
  yourself.
- **The CLI assembles locally, free** — each cel is held at `--cel-fps` into
  24 fps H.264, centre-cropped to your aspect, the sound files are mixed, and
  the MP4 is written on your machine. No North Noir call: the receipt says
  `"provider_calls": 0` — unless you asked for a generated music bed
  (`--music "<prompt>"`), which is made on your own ElevenLabs or fal key and is
  still not a North Noir call (see
  [the music bed](#the-music-bed-local-by-default-never-a-silent-north-noir-call)).

**Local alternative for the cels:** with an `OPENAI_API_KEY`, `northnoir image`
generates each frame image directly on your machine (one call per cel, `--ref`
for identity continuity) and you run the same local assembly. The MCP route
above stays the recommended one; the provider matrix lists both.

Whole-project runs (MCP plans, draws, reviews and delivers the film in the
cloud) are the other Ruvil 7.3 path — see
[Whole-project in the cloud](#whole-project-in-the-cloud-mcp-only). Use it when
you want North Noir's planner and review; use the local assembly below when you
want every frame and every edit on your own machine.

### The sequence, in order

```text
# 1. The plan. Either take the one MCP planned for you, or write it yourself.
#    a) MCP plan_drawn_video -> get_job: save the job's `plan` block as plan.json
#    b) or write the minimal plan (this is what the CLI reads):
#       {"cel_fps": 6, "sections": [{"start": 0, "duration": 2, "brief": "..."}]}

# 2. Cels — ONE MCP call per frame. 6 fps × 2 s = 12 cels.
generate_frame_image(prompt="a hand-drawn boy looking left, loose ink lines, "
                            "no text, no writing, no numbers, no paper edges, no borders",
                     size="1536x1024", quality="high",
                     reference_image="<`northnoir ref data-url start-face.jpg`>",  # or public HTTPS
                     response_format="url")
#    NEVER put a frame number ("cel 1 of 12") or the words "animation cel" in the
#    prompt: the model inks the number into the picture and draws a paper sheet
#    with a peg hole for "animation cel". Say "frame", never a numeral, and end
#    with the no-text clause. The server strips those phrases for you and returns
#    prompt_adjustments listing every change.
#    Save the returned bytes as cels/f0001.jpg, then repeat for f0002, f0003, …
#    image_url is a signed URL that EXPIRES IN ONE HOUR: download it at once.
#    (jpg, png and webp are accepted; the order of the files is the film order)

# 3. Sound — opt-in, default none. Either let MCP generate it and save the files
generate_sfx(prompt="soft wind and a duck quacking", duration_seconds=2,
             sfx_model="mirelo-sfx-2")         # omitted = mirelo-sfx-2
generate_music(prompt="warm playful orchestral bed", duration_seconds=2,
               music_model="mureka-9")          # omitted = mureka-9
#    Mirelo bills per output second (7,000 tokens/s after x1.4: 2 s ≈ 14,000
#    tokens); stable-audio-open is a flat 12,485 tokens for a 1–4 s clip.
#    -> sfx.mp3, music.mp3
#    … or generate the bed locally on your own key (no North Noir call):
#    --music "warm playful orchestral bed, instrumental"  with ELEVENLABS_API_KEY/FAL_KEY

# 4. Assemble locally — no cloud call, no North Noir charge.
northnoir draw --model latest --cels cels --plan plan.json \
  --sfx-file sfx.mp3 --music-file music.mp3 --out film
#    … or, with a locally generated bed instead of music.mp3:
#    northnoir draw --model latest --cels cels --plan plan.json \
#      --sfx-file sfx.mp3 --music "warm playful orchestral bed, instrumental" --out film

# 5. Look at the result.
northnoir doctor                       # ffmpeg/ffprobe present
ffprobe film/film.mp4                  # H.264, 24 fps, AAC when sound is on
```

`generate_frame_image` returns compact metadata plus `image_url` (a signed URL
into a private bucket, valid for **one hour**) and small native image content
for the widget; save the bytes yourself (download `image_url` immediately, or
use the MCP preview/save widget). Anything that needs the same reference again
more than an hour later must fetch/publish it again. Leave `response_format`
unset — the default already carries `image_url`. `1536x1024` landscape (or
`1024x1536` portrait) is centre-cropped to the output aspect; use `quality`
`medium` or `high` for cels.

**References are public HTTPS or `data:` URLs — a local path is not accepted.**
Make a data URL from a local file offline (no upload, no key, no public bucket):

```sh
REF=$(northnoir ref data-url start-face.jpg)   # under the gateway's 10 MiB limit
northnoir ref data-url start-face.jpg --json   # receipt: bytes, mime, recompressed
```

It recompresses (and, if needed, downscales) to fit; a file that already fits
passes through unchanged. `--max-bytes` chooses a smaller ceiling.

### The file layout the CLI expects

```text
plan.json                      the timed sections (see below)
cels/f0001.jpg                 cel 1  (the first frame)
cels/f0002.jpg                 cel 2
…                              one image per cel, in order
sfx.mp3  music.mp3             optional, from generate_sfx / generate_music
film/film.mp4                  the assembled film
```

- **Naming.** The natural order of the filenames is the film order. `f0001`… is
  the convention; any name works when its frame number is the integer before
  the extension (`s01_f0007.png` is frame 7, and in `p1_f01_r1.jpg` the frame is
  1 — a trailing `_r2` is a version, not the frame).
- **`--plan` times and checks the strip.** The section's `duration` (seconds)
  is the film length; the expected cel count is `duration × cel-fps` and the
  strip must be numbered contiguously from 1. A short strip, an extra cel or a
  gap fails with the exact frame names, so a two-second section cannot quietly
  become a one-second film:
  `--plan: section 1 is 2 s at 6 cels/s = 12 cels, but cels has 11: missing
  frame(s) f0012.` Draw the missing cel and rerun, or pass `--seconds` /
  `--cel-fps` to assemble with different timing (that override is recorded in
  `film.json` and skips the check).
- **`--section N`** picks one section of a multi-section plan (1-based). A plan
  with several sections requires it — one `--cels` directory is one section of
  the film; assemble each section and concatenate if you want the whole film.
- **Plan shapes.** The CLI accepts the JSON you wrote, the `plan` block of an MCP
  `get_job` payload (`{"plan": {"graphics": [{"start", "duration", "brief"}]}}`),
  or a saved workflow row (`{"options": {"plan": …}}`). `sections`, `graphics`
  and `beats` are read the same way; a section needs `duration` (or `seconds`,
  or `start` + `end`) and may carry `brief`. `summary`/`title`, `style_slug`
  and `aspect` are kept as provenance in `film.json`.
- **Defaults.** `--cel-fps` comes from the plan's `cel_fps` (else 6, the Ruvil
  7.3 image rate); each cel is held `24 ÷ cel-fps` delivery frames, so use a
  rate that divides 24 (6, 8, 12, 4). `--aspect` comes from the plan when the
  plan has one, else 16:9 — an explicit `--aspect` always wins. `--sfx-file` is
  mixed at full level, the music bed is ducked under it (`--music-gain-db`,
  default −14 dB), the mix is loudness-normalised to −16 LUFS and fitted to the
  picture. A generated bed (`--music "<prompt>"`) is cut to that same length
  with a fade-out before mixing; see the music-bed section below.
- Without `--plan` the film length is simply the cel count (`--seconds` trims).
- **`--sfx-file` is ONE track, not a list of files.** MCP delivers each cue as
  its own file; `northnoir sfx-track` places them at their times, peak-normalises
  each cue (default −4 dBFS) and sums them without re-normalisation:

  ```sh
  northnoir sfx-track --cue sfx/duck.mp3@13.7 --cue sfx/wind.mp3@0 \
    --duration 15 --peak-db -4 -o sfx/sfx-track.wav
  ```

  It is local and free (ffmpeg only, no key, no network) and prints a receipt
  with each cue's measured peak and applied gain.

Output: `film/film.mp4`, `film/film.poster.jpg` and `film/film.json` (cel count,
holds, audio files, stream probe, the `plan` block with its check result, and
`"provider_calls": 0` — or `1` when a local music bed was generated, with a
`music_bed` receipt naming the provider, the route, the returned length and the
trim/fade applied to it).

The CLI does **not** generate Ruvil 7.3 frames from `draw`: `northnoir draw
--model latest` without `--cels` exits 2. Get the cels from MCP
`generate_frame_image` (recommended) or from the local `northnoir image`
command on your own OpenAI key, then assemble them here.

### The music bed: local by default, never a silent North Noir call

`--music "<prompt>"` generates the bed **on your own key** and cuts it to the
film length with a fade-out before mixing. Resolution order:

1. **your own provider key** — `ELEVENLABS_API_KEY` (ElevenLabs Music direct,
   the default route `elevenlabs-music`) or `FAL_KEY` (the fal music routes,
   default `eleven-music`); pick any of the 15 routes with `--music-model`;
2. **`--music-file <audio>`** — an existing local file, including one you
   downloaded from MCP `generate_music`;
3. **one clear error** naming both options above (and MCP `generate_music`).

| What you want | Flag | Key / file |
|---|---|---|
| a bed from your own ElevenLabs key | `--music "<prompt>"` | `ELEVENLABS_API_KEY` |
| a bed on a specific route | `--music "<prompt>" --music-model sa3-medium` | `FAL_KEY` (all routes except `elevenlabs-music`) |
| an existing bed file | `--music-file bed.mp3` | the file, cut to the film with a fade-out (no key, no call) |
| MCP generates the bed | `generate_music` → save → `--music-file bed.mp3` | North Noir key in MCP only |
| bill North Noir explicitly | `--music "<prompt>" --music-provider northnoir` | `NORTHNOIR_API_KEY` |

A `--music-file` is **cut to the film with a fade-out** exactly as a generated
bed is. A bed's reported length can exceed its audible music, so the CLI
measures it: when the file's own audio stops more than a second before the film
ends, `northnoir draw` prints a warning and
records it as `music_tail_warning` in `film.json`; it pads and fades the tail
rather than regenerating anything (a retry is a new paid call).

MCP `generate_sfx` / `generate_music` take `sfx_model` / `music_model`
(omitted = `mirelo-sfx-2` / `mureka-9`; `elevenlabs-sfx-v2` and
`elevenlabs-music` select the ElevenLabs routes). Mirelo is billed per output
second (7,000 NorthNoir tokens per second after x1.4, so a 2 s cue is about
14,000 tokens); `stable-audio-open` is a flat 12,485 tokens for a 1–4 s clip.
Every effect is peak-normalised to −4 dBFS server-side, so the per-cue levels
in the downloads are consistent; `northnoir sfx-track` is the local way to place several cues on one
timeline.

North Noir is **never** contacted implicitly: `--music-provider northnoir` is
the only way to reach `/v1/audio/music` from the CLI, it is billed like any API
call, and `--help` says so. `northnoir models --sound` lists the same 15 music
routes offline. A music bed belongs to the cel render, so a `--scene` (Ruvil
2.1) run that passes `--music` exits 2 with that explanation.

### Six aspect ratios

`--aspect` (alias `--ar`) selects the output; omitted/unknown values use
Desktop. The local render centre-crops each cel to the exact output size.

| Format | Aspect | Output pixels |
|---|---|---|
| Desktop (default) | `16:9` | 1920×1080 |
| Phone | `9:16` | 1080×1920 |
| Square | `1:1` | 1080×1080 |
| Portrait feed | `4:5` | 1080×1350 |
| Cinematic | `21:9` | 2520×1080 |
| Retro TV | `4:3` | 1440×1080 |

### Draw modes

`--draw-mode` (alias `--medium`): **`image` (default)** is the product mode:
images as frames, generated by MCP (or `northnoir image`) and assembled here.
`js` and `copy` are accepted only as internal/experimental flags for
user-facing training R&D work; they have no user-facing path: `.js`-drawn is
exclusively Ruvil 2.1 (the default), and a custom-trained model that draws
Ruvil 7.3 frame images is in R&D.

For Ruvil 7.3, `northnoir draw` assembles cels and never draws them: a
`--brief` passed with `--model latest` does not generate frames. Plan the film
yourself or with MCP `plan_drawn_video`, and pass the plan with `--plan`.

## Polish Ruvil 7.3 cels into a 20 fps NorthCel film

A Ruvil 7.3 film is one image per frame at 6 fps. `northnoir polish` turns
that folder of cels into **one editable NorthCel film** at 20 fps: every cel
becomes vector shapes in one shared palette, and the frames between them are
written as NorthCel in-betweens you can read and edit. The CLI assembles and
renders locally; **it never calls an image model**. Install the extra first:
`pipx install "northnoir[ncel]"`.

The workflow, in order:

1. `northnoir polish palette check` — prove the shared palette can paint every
   cel before fitting starts.
2. `northnoir polish` — fit, match, plan, render, review.
3. `northnoir polish verify` — measure the rendered frames against their
   drawings; open `faces.jpg` and `keys_vs_source.jpg`.
4. Open the review sheets and frames; read `needs_keys.json`.
5. Optional AI in-between images: gate them with `northnoir polish keys`, add
   them with `--extra-keys`, polish again.
6. Author vector in-betweens with `northnoir polish inbetween`.
7. `northnoir polish assemble` — overlay the authored frames and render the
   final film.

### 1. `northnoir polish`

```console
northnoir polish --cels cels --fps 20 --src-fps 6 \
  --palette film-palette.json --extra-keys extra/extra.json \
  --config polish-config.json \
  --audio-from original/original.mp4 --out polish/
```

What it does:

- **Fit.** Every cel is traced with `northcel fit --stacked` into
  painter's-order shapes using **one shared palette** (`--palette auto` or a
  JSON file of `[[r,g,b], …]`), so the same shirt stays the same colour from
  cel to cel. Paper scenes are framed whole; full-bleed scenes are cropped, and
  shapes touching the source border bleed to the canvas edge (`--width` /
  `--height`, default 1920×1080; `--last-paper N` marks cels 1..N as paper
  scenes when auto-detection needs a hint).
- **Match.** Neighbouring drawings are matched shape by shape; byte-identical
  consecutive cels become holds.
- **Plan.** Each gap becomes a hold, a `morph`/`mix` in-between, a dissolve or
  a cut, according to match quality, displacement and `--config`.
- **Emit.** One compact `film.ncel` (each key a `def`, holds as `frame A..B`
  ranges, in-betweens as `morph`/`mix`/`opacity`) plus `receipt.json`, which
  records every key's source image, the cels directory, the plan and the film
  path.
- **Render.** All frames render locally into `frames/` and an H.264
  `film.mp4`.
- **Review.** Labelled sheets for every transition
  (`review/all-transitions-*.jpg`, plus `review/cuts-*.jpg` when there are
  cuts or dissolves) and `needs_keys.json`.
- **Audio.** `--audio-from` muxes the original track (copyable AAC/MP3 is
  copied, anything else becomes 192k AAC).

`needs_keys.json` has two lists. `authored` holds the automatic
cut/dissolve gaps: try a **vector in-between** there first, even when match
confidence is low or unknown, motion is large or contours are unmatched —
contour statistics cannot prove a new image is needed. `transitions` holds only
the needs you confirm in `--config`, each with both reference images, a ready
image prompt and a `suggested_extra` entry:

```json
{"needs_keys": [{"from": 1, "to": 2, "category": "new_angle",
                 "reason": "Explain why a vector delta cannot bridge it"}]}
```

Categories are `new_angle`, `new_pose`, `unseen_prop` and `topology`.

**Extra keys.** `--extra-keys` adds AI in-between drawings:
`[{"id": 101, "a": 12, "b": 16, "src": "extra/m12_16.jpg", "u": 0.5}]`
(1-based cel numbers `a`/`b`, an id ≥ 100, position `u` between them). Each
extra is fitted as the **measured figure** — paper, sky and clouds the ink
touches stay out — with a 4 px ink outline backing, then normalised by its
figure box to the neighbours' interpolated size and centre in canvas
coordinates. A paper-scene drawing is shifted, never scaled, to stay on canvas.
The receipt's `normalisations` records both boxes and any clamp. When a gap
genuinely needs a new image, generate ONE with MCP `generate_frame_image`
(recommended `gpt-image-2.6-sunburst`), save it as the `suggested_extra.src`,
add the entry to `--extra-keys` and polish again.

Useful flags: `--no-render` (plan and write `film.ncel`, `receipt.json` and
`needs_keys.json` only, for fast iteration), `--workers`, `--crf`,
`--progress`. `--config` accepts `force_cut`, `force_morph`, `force_dissolve`,
`min_match`, `max_disp`, `transition_s`, `match_cost`, `colour_changes`,
`tolerance`, `min_area`, `gap_fraction`, `underpaint_min_area`, `aa`,
`easing`, `fallback`, `name` and `needs_keys`.

**Always open the review sheets and full-size frames.** A shape match proves
contours can interpolate, not that the pose is right: a crouch morphed into a
jump reads wrong even when every contour matches.

### Check the palette first: `northnoir polish palette check`

```console
northnoir polish palette check --cels cels --palette film-palette.json \
  --suggest polish/palette-suggested.json
```

Every cel is checked for painted regions whose nearest palette colour is
further away than `--threshold` (default 60, Euclidean RGB) and whose area is
at least `--min-area` (default 150 px²). Two 3×3 openings remove anti-aliasing
before 8-connected regions are measured. The report lists regions per cel and
in total, with the region's median colour, nearest palette colour, distance,
area and bbox. `--suggest` writes the original palette plus suggested colours;
pass that file to `--palette` to fix the gaps. Exit is `0` normally and `2` with
`--strict` when anything is found. `--json` prints the full report.

A plain `northnoir polish` runs the same check on its cels and palette, prints
one summary line when gaps exist, and writes `palette_gaps.json` into `--out`.
It is read-only: the fitted palette and the film are unchanged.

### Verify the rendered film: `northnoir polish verify`

```console
northnoir polish verify --frames polish/frames --plan polish/receipt.json \
  --cels cels --extra-keys extra/extra.json --out polish/verify
```

The plan maps each frame to its drawing: keys with `id < 100` are cel number
`id` in `--cels`; keys with `id >= 100` are in `--extra-keys` (`src` is relative
to the cels' parent). A frame uses the last key at or before it, so an authored
in-between holds the previous key's drawing; the checks compare features, not
pixels. Four checks run:

- **Mouth present** — from the first drawn head, the frame keeps the mouth its
  drawing has (hole, white, red or ink-stroke fallback).
- **Eye style** — dot or ring eyes per frame; a ring-eye frame or a class change
  between consecutive frames fails.
- **Figure continuity** — a figure cut off at a frame edge (within 40 px) when
  the drawing itself has a margin all round, a figure filling the frame, a
  missing head, or a size jump against the neighbouring frames.
- **Basics** — frame count and size match the plan; no blank frame.

`polish verify` writes `report.json`, `report.md`, `faces.jpg` (every frame's
head crop, labelled) and `keys_vs_source.jpg` (each key beside its drawing),
prints one verdict line per check and exits non-zero if any check fails.
`--json` prints the full report.

### 2. Gate AI in-between keys: `northnoir polish keys`

```console
northnoir polish keys check --plan polish/receipt.json --out polish/keys_report.json
northnoir polish keys normalise --plan polish/receipt.json --out polish/normalised \
  --extra-keys extra/extra.json --out-extra-keys extra/extra_normalised.json
northnoir polish keys gate --plan polish/receipt.json --reviews polish/reviews.json \
  --out polish/keys_gate.json
```

- `check` measures every extra key against both neighbours: figure box, scale
  error, centre offset, silhouette IoU in a uniformly scaled common frame,
  colour distribution of material pixels and ink fraction. **Framing** and
  **pose** are hard numeric gates; **style** (colour, line weight) is flagged
  for a vision reviewer.
- `normalise` rewrites framing-only differences into new PNGs and, with
  `--out-extra-keys`, an `--extra-keys` file that points at them.
- `gate` combines the numeric result with the reviewer's verdicts
  (`{"101": {"verdict": "pass", "notes": "..."}}`). A key is accepted only when
  both pass. Rejected keys go to `needs_keys.json` beside `--out`, each with
  references, a specific replacement prompt and a `suggested_extra`.
  `--allow-large-pose` lets named keys inside a genuinely large pose change sit
  far from both neighbours.

The CLI never calls an image or vision model: the reviewer is you or your
agent, looking at the candidate beside both neighbours at full size.

### 3. Author a vector in-between: `northnoir polish inbetween`

```console
northnoir polish inbetween --plan polish/receipt.json --from 12 --to 16 \
  --u 0.5 --out polish/inbetweens/m12_16_u50
# edit m12_16_u50/inbetween.ncel: key A is copied; change only the delta
python3 polish/inbetweens/m12_16_u50/verify.py
```

`--from`/`--to` are key ids from `receipt.json`/`needs_keys.json` (an index
works when no id matches); any consecutive pair works, including a morph gap
whose automatic motion is wrong. `--u` (strictly between 0 and 1) picks the
frame inside the transition window. The scaffold copies key A into the plan's
global `frame N { ... }` in `inbetween.ncel`, lists the named paints and
groups in `shapes.json`, copies both neighbour images, and writes `brief.md`
with the method: **observe → decompose → copy / move / warp / recolour /
redraw → edit the delta → verify → iterate**. It also writes `manifest.json`,
`README.md`, standalone key scenes, `verify.py` and `tools.md`.

Edit with NorthCel groups, `transform`, `warp` and `nudge` (spec
0.5.0-draft; needs `northcel` 0.7 or newer). `verify.py` renders the frame and
writes an A | authored | B comparison plus onion blends; `tools.md` lists the
exact `northcel diff` / `onion` (against both neighbours, `--against IMAGE -o
OUT`), `continuity` (`--group NAME`, on the assembled film) and `distinct` (on
the assembled film) commands. These measurements are advisory; look at the
frames.

### 4. Assemble: `northnoir polish assemble`

```console
northnoir polish assemble --plan polish/receipt.json \
  --inbetweens polish/inbetweens --out polish/assembled \
  --audio-from original/original.mp4
```

`assemble` copies the authored frame blocks into the original film — vector,
no re-fit, no raster — keeps the original keys, holds, cuts, dissolves,
morphs, fps, frame count and audio, then renders. The contract:

- Keep the film's canvas, fps, frames, precision and seed.
- Use self-contained global `frame N` or inclusive `frame A..B` blocks; local
  `def`/`use` and palettes are allowed, top-level defs and paint are rejected.
  New top-level palette names merge when they do not conflict.
- Only non-key frames inside a transition window may be replaced. Overlaps
  across files and stale source fingerprints fail.
- The assembled film declares `northcel "0.5.0-draft"`, so authored blocks use
  spec 0.5 constructs (the default smooth `warp`, not `mode: arap`).
- Unauthored frames keep the original plan; assembly invents no missing
  tweens. Use other `--u` values and separate folders for more frames of the
  same gap.
- Audio defaults to the receipt's source (`--audio-from` overrides). Short
  audio never truncates the video; long audio is trimmed. `--no-render` writes
  only `film.ncel` and `assembly.json`.

Genuinely new angles, poses, props or topology still need one generated key
image (step 1, extra keys); everything else is authored in code.

## Whole-project in the cloud (MCP only)

A whole film can be planned, drawn, reviewed and delivered by North Noir's own
models, with the coding agent only driving. No CLI command does this.

```text
create_drawn_video_project(title="The lighthouse keeper")
plan_drawn_video(project_id=…, brief="A lighthouse keeper climbs the stairs…",
                 seconds=8, aspect="16:9")
#    -> report the sections and token cost; wait for approval
confirm_drawn_video(job_id=…)
get_job(job_id=…)                       # poll until delivered
get_drawn_video_frames(job_id=…)        # inspect/re-download the kept frames
```

Frames that stay imperfect are **kept and flagged for the creator**, never
blocked. Re-roll one frame at a time with `reroll_drawn_video_frames` after
`get_drawn_video_frames` gives you the frame number. Estimates are estimates;
the charge is settled at **actual cost × 1.4** when the job finishes (BYOK
components are waived).

## Sound is opt-in: default none

SOUND IS OPT-IN: sfx_model and music_model BOTH DEFAULT TO none. A run that omits them gets no generated sound effects and no background music, and is not billed for either; "none" is the explicit off switch. Music models (music_model, 15, instrumental background bed, cut to the film length with a short fade-out when the route returns a whole song): mureka-9 (Mureka V9, whole song 150-200 s), mureka-95 (Mureka V9.5, 165-180 s), lyria-3-pro (Lyria 3 Pro, 45-90 s), lyria-35 (Lyria 3.5, 60-180 s), lyria-2 (Lyria 2, fixed 32.8 s), elevenlabs-music (ElevenLabs Music direct, exact length), eleven-music (Eleven Music via fal, exact length), eleven-music-v2 (Eleven Music v2), eleven-music-v25 (Eleven Music v2.5), minimax-25 (MiniMax Music 2.5+, 90-120 s), minimax-26 (MiniMax Music 2.6, 90-280 s), minimax-3 (MiniMax Music 3.0, duration-bounded), sa3-medium (Stable Audio 3 Medium), stable-25 (Stable Audio 2.5), stable-3-small (Stable Audio 3 Small). Sound-effects models (sfx_model, 19, one effect per cue unless marked video): stable-audio-open (Stable Audio Open, best score in the 8-cue listening benchmark), mirelo-sfx-2 (Mirelo SFX 2.0 text), mmaudio-v2-text (MMAudio V2 text), seed-audio-1 (ByteDance Seed Audio 1.0; no duration control, cut to the cue), sonilo-v1-1-sfx (Sonilo v1.1 text), sa3-medium-base (Stable Audio 3 Medium Base), sa3-small-sfx (Stable Audio 3 Small SFX), elevenlabs-sfx-v2 (ElevenLabs Sound Effects v2), sa3-medium (Stable Audio 3 Medium, general audio), cassetteai-sfx (CassetteAI), stable-audio-2-5 (Stable Audio 2.5), audiogen (AudioGen on Replicate, charged by returned predict time), audioldm (AudioLDM on Replicate, cut to the cue), sonilo-v1-1-video (video), mirelo-sfx-2-video (video), kling-v2a (Kling video-to-audio, film must be 3-20 s), pixverse-sfx (video), mirelo-sfx-video (video, first 10 s of the film), hunyuan-video-foley (video). The six video routes score the FINISHED film after drawing and the sound is muxed into the delivered mp4. Ruvil 2.1 also accepts sfx_model "code" (procedural sound drawn inside the scene). If the user's request implies music or sound effects, ask which model they want or whether to keep none; never choose one silently. Full catalogue with labels, benchmark scores and prices: the sound_models block of the models list (API: GET /v1/models; MCP: list_drawn_video_options; CLI: northnoir models --sound).

The same block is printed offline by `northnoir models --sound` (the block's
"CLI" line still names the pre-1.6 command; the local command is
`northnoir models --sound`).

## `northnoir auth` and `northnoir models`

```sh
northnoir auth nn_live_...     # save the key (alias: northnoir login)
northnoir auth --status        # configured? (--logout removes it)
northnoir models               # offline: models, MCP endpoint/tools, what runs where
northnoir models --sound       # offline: the sound catalogue + the opt-in block
northnoir models --providers   # offline: the slot x provider x flag x env-var matrix
northnoir models --json
```

`auth` keeps one file for the key (`~/.config/northnoir/keys.json`, 0600) and
never prints the value — only a masked hint. You can also export
`NORTHNOIR_API_KEY`. The default/local commands make no North Noir call; the key
is what you give your MCP client, or what the opt-in `northnoir api` backend
uses. It is **not** needed for `draw`, `check`, `render`, `mix` or `models`.

Provider keys matter only for the **local per-asset commands** and for BYOK on
the MCP server: `OPENAI_API_KEY` (frames, OpenAI narration), `ELEVENLABS_API_KEY`
(SFX, narration, and the generated music bed `draw --music`), `FAL_KEY` (SFX and
the fal music routes), `OPENROUTER_API_KEY` (the local `author` writer). Put them
in the environment or in `~/.config/northnoir/keys.json`; a missing key is
reported before anything is sent, never guessed.

## Local narration and SFX mix

`northnoir mix` is entirely local: no provider calls, no API key, no cloud
tokens. It opens the scene with the same isolated browser and `SCENE.init()`
contract as `northnoir check`, reads the declared `SCENE.cues`, places the audio
files you provide, ducks the SFX under the narration and normalises to −14 LUFS.

```sh
northnoir mix --scene scene.html --sfx-dir sounds --narration narration.wav -o final.mp4
```

`--sfx-dir` holds `<cue-id>.mp3` files and a `cues.manifest.json`; a cue list can
also be given with `--cues cues.json --video render.mp4`. The video is copied
without re-encoding and must match the declared scene duration. Loudness
measurements are printed as JSON.

## Commands

| Command | What it does |
|---|---|
| `northnoir draw --scene scene.html --out <dir>` | Ruvil 2.1 local render (default); `--model ruvil_2_1` explicit. |
| `northnoir draw --model latest --cels <dir> [--plan plan.json [--section N]] --out <dir> [--sfx-file f] [--music "<prompt>" \| --music-file f] [--music-model r] [--cel-fps 6] [--aspect 16:9]` | Ruvil 7.3 local assembly of frame images generated by MCP. `--plan` times the section and checks the strip is complete; the music bed is generated on your own ElevenLabs/fal key (or given as a file). |
| `northnoir r73` / `northnoir draw-frames` | Same local Ruvil 7.3 assembly; no `--model` needed. |
| `northnoir polish --cels <dir> --fps 20 --src-fps 6 --palette <json> [--extra-keys f] [--config f] [--audio-from f] --out <dir>` | Local: fit Ruvil 7.3 cels into one editable NorthCel film, plan in-betweens, render, review and mux audio. Never calls an image model. |
| `northnoir polish palette check --cels <dir> --palette <json> [--threshold 60] [--min-area 150] [--suggest out.json] [--strict] [--json]` | Find painted regions with no suitable palette colour; report per cel and in total, optionally write the palette with suggestions appended. `--strict` exits 2 on any gap. |
| `northnoir polish verify --frames <dir> --plan receipt.json --cels <dir> [--extra-keys f] --out <dir> [--json]` | Measure rendered frames against their drawings: mouth, eye style, figure continuity and basics; writes `report.json`, `report.md`, `faces.jpg` and `keys_vs_source.jpg`. |
| `northnoir polish keys check\|normalise\|gate --plan receipt.json …` | Measure AI in-between keys against both neighbours, rewrite framing-only differences, and accept only numeric-plus-reviewer passes. |
| `northnoir polish inbetween --plan receipt.json --from A --to B --u 0.5 --out <dir>` | Scaffold one vector in-between (copied key + delta brief, shapes, references, `verify.py`). |
| `northnoir polish assemble --plan receipt.json --inbetweens <dir> --out <dir>` | Overlay authored vector frames on the original film and render; keys, holds, timing and audio are preserved. |
| `northnoir auth [nn_live_…] [--status] [--logout] [--api-url URL]` (alias `login`) | Save/show/remove the one NorthNoir API key in `~/.config/northnoir/keys.json` (0600). |
| `northnoir models [--sound] [--json]` | Offline model catalogue: AI-drawn, image (MCP), sound, MCP endpoint/tools, what runs where. |
| `northnoir mix --scene scene.html --sfx-dir <dir> --narration narration.wav -o final.mp4 [--video render.mp4]` | Local cue placement, voice ducking and two-pass −14 LUFS normalization; H.264 copy + AAC. |
| `northnoir image --prompt "..." -o cel.jpg [--model gpt-image-2.6-sunburst] [--size 1536x1024] [--quality high] [--ref IMG]` | **Local, your OpenAI key**: generate one frame image (`OPENAI_API_KEY`); `--ref` (max 4) uses `/images/edits`. |
| `northnoir sfx --prompt "..." [--provider auto\|elevenlabs\|fal\|code] [--seconds 4] [-o sfx.mp3]` | **Local, your key**: one sound effect (`ELEVENLABS_API_KEY` / `FAL_KEY`), or free procedural foley with `--provider code`. |
| `northnoir narration --text "..." [-o narration.mp3] [--provider auto\|elevenlabs\|openai] [--voice ID] [--model M]` | **Local, your key**: speak the script (`ELEVENLABS_API_KEY` or `OPENAI_API_KEY`). |
| `northnoir models --providers [--json]` | Offline: the slot × route × provider × flag × env-var matrix (same rows as this README). |
| `northnoir api <models\|voices\|generate\|estimate\|wait\|frames\|flagged\|download\|image\|sfx\|voice\|music\|jobs>` | **NOT RECOMMENDED — use MCP**: the North Noir REST API backend with one `nn_live_…` key. |
| `northnoir doctor [--install] [--json]` | Verify Chromium/Playwright, `ffmpeg`/`ffprobe`, and the pinned scene libraries (SHA256). |
| `northnoir init <dir> [--title "..."] [--duration 5] [--fps 24] [--style <id>] [--force] [--json]` | Scaffold `<dir>/scene.html` (working `window.SCENE` starter) + `<dir>/.northnoir/`. |
| `northnoir check <scene.html> [--still] [--frames 0,12,24,...] [--out <dir>] [--json]` | Deterministic observer + quality + audio check; full-res PNGs, contact sheet, `report.json`. |
| `northnoir render <scene.html> [-o <output.mp4>] [--fps 24] [--duration <sec>] [--no-audio] [--json]` | Render every frame at 1920×1080, render `SCENE.audio` offline, mux H.264 + AAC. |
| `northnoir styles [--json]` | List the 31 AnidoodleDraw style ids and the RuvilMarks helpers. |
| `northnoir skill [install] [--install] [--json]` | Print the bundled `northnoir-draw` skill path; `install` copies it into agent skill folders. |
| `northnoir --version` | Print the CLI version. |

Exit codes for local commands: `0` on success/`ok`, `1` on scene/encode or
provider failure (and on a failed `polish verify` check), `2` on usage errors
(including a missing provider key) or `polish palette check --strict` with a
gap. `northnoir api` uses its own codes (`0`/`1`/`2`/`3`/`4`/`5`, above).

`check` JSON: `ok`, `still_only`, `errors`, `quality` (readability / collision /
composition + `flags`), `cues`, `cue_errors`, `audio_ok`, `metrics`
(deterministic, canvas size, blank/frozen frames), `frame_paths`,
`contact_sheet_path`, `report_path`. Quality flags are review evidence — they
do not by themselves flip `ok`.

`render` JSON: `ok`, `output_mp4`, `poster_png`, `contact_sheet_png`,
`frames_rendered`, `duration_s`, `fps`, `has_audio`, `size_bytes`, `elapsed_s`.

## The `window.SCENE` contract (cheat-sheet)

- Canvas is **1920×1080**. Declare `SCENE.fps`, `SCENE.frames` (or
  `SCENE.duration`), `SCENE.width/height`, and `SCENE.canvas`.
- `SCENE.renderFrame(n)` is a **pure function of `n`**: no unseeded randomness,
  no wall-clock reads for drawing decisions (the renderer re-seeds per frame,
  so renders are deterministic and re-renders are byte-identical).
- `SCENE.init()` bakes textures once and registers subjects/blockers:
  `window.__ruvilSubjects.register(id, role, boxFn)` /
  `window.__ruvilBlockers.register(...)`, keeping the declarative
  `SCENE.subjects` / `SCENE.blockers` mirrors in sync. Draw the main subject
  inside `window.__ruvilSubjects.draw('hero', () => { ... })` so the checker
  can measure it.
- `SCENE.cues`: `[{ t, prompt, seconds }]` — timed sound beats, validated
  against the scene duration.
- `SCENE.audio(ctx, info)`: procedural audio scheduled on the
  `OfflineAudioContext` you are given (48 kHz stereo out). Keep peaks ≤ 0.7,
  seed every noise source, sync hits to your cues.
- Only five pinned library URLs may be loaded — every other network request is
  blocked by the renderer:
  `https://libs.ruvil/p5.min.js`, `rough.min.js`, `simplex-noise.js`,
  `ruvil-marks.js`, `anidoodle-draw.js` (served offline from the package,
  SHA256-verified by `doctor`).

## Kit reference

- **RuvilMarks** (`ruvil-marks.js`): `paper(ctx, o)` (bake the paper ground
  once in `init()`), `wash`, `stipple` (blue-noise dots; density = tone),
  `hatch` (spacing = tone), `rng(seed)` (mulberry32), `hash(a, b)` (boil
  outlines 1–3 px via `hash(boilIndex, strokeId)`).
- **AnidoodleDraw** (`anidoodle-draw.js`): `AnidoodleDraw.draw('<id>', ctx,
  frame, W, H)` plates one of 31 finished style scenes under your scene;
  `AnidoodleDraw.styles` lists the ids at runtime. Run `northnoir styles`.

## The agent skill

```sh
northnoir skill install
```

copies the bundled `northnoir-draw` skill into `.claude/skills/`,
`.agents/skills/`, `~/.config/opencode/skills/` and `~/.claude/skills/`, so
Claude Code, OpenCode, Codex, Gemini CLI and Cursor agents learn the contract,
the 4-step loop, the quality-flag fix table, the MCP hand-off and the craft
rules before they draw. `northnoir skill` prints the bundled path.

## Troubleshooting

- **`doctor` says Chromium will not launch** — run `northnoir doctor
  --install`. On Linux you may also need Playwright's system libraries:
  `python3 -m playwright install-deps chromium` (asks for sudo; the CLI never
  runs sudo itself).
- **`ffmpeg` missing** — install it with your OS package manager (above);
  `doctor` prints the exact hint for your platform.
- **`draw --model latest` exits 2** — it wants `--cels`: generate the frame
  images with MCP `generate_frame_image` first (see the worked sequence).
- **A library SHA256 fails** — the vendored runtime is corrupted or hand-edited.
  Reinstall the package; maintainers refresh it with `tools/sync_runtime.py`.
- **Slow renders** — rendering is deterministic software rendering; heavy
  full-canvas grain costs time per frame. Check `avg_ms_per_frame` in the check
  report before rendering long scenes.

## Development

```sh
python3 tools/sync_runtime.py   # refresh northnoir_cli/runtime from cloudrun/
python3 -m pytest tests/ -q     # end-to-end suite (doctor/styles/init/check/render/cels)
python3 northnoir_cli/cli.py doctor   # or: ./bin/northnoir doctor
```

## Licenses

The CLI code is proprietary North Noir software (see `pyproject.toml`). The
bundled scene libraries keep their own licenses, shipped beside them in
`northnoir_cli/runtime/libs/`: `LICENSE.p5.txt` (p5.js), `LICENSE.roughjs.txt`
(rough.js), `LICENSE.simplex-noise.txt` (simplex-noise), `LICENSE.anidoodle.txt`
(AnidoodleDraw / RuvilMarks). Their pinned SHA256 digests are in
`northnoir_cli/runtime/libs/SHA256SUMS` and verified by `northnoir doctor`.
