@a-company/atelier 0.36.0 → 0.37.0

package/university/content/notes/N-atel-401-transitions.md

@@ -0,0 +1,94 @@
+---
+id: N-atel-401-transitions
+title: Transitions and the interaction layer
+type: note
+track: ATEL-401
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-401
+  - transitions
+  - interactions
+  - state-machine
+difficulty: intermediate
+estimatedMinutes: 6
+prerequisites:
+  - N-atel-101-easings
+summary: A transition is the timed bridge from one state to another. Interactions are the triggers that fire those transitions. Together they turn a pile of states into an interactive state machine.
+---
+
+## A transition is a bridge with its own timing
+
+States are destinations. A transition is *how you get from A to B* — with a duration and easing that belong to the move, not to either state.
+
+```ts
+atelier_configure_transition({
+  id,
+  stateName: "default",
+  targetState: "hover",
+  transition: {
+    duration: 12,
+    easing: "ease-out",
+  },
+});
+```
+
+Read it as: "from `default`, the transition to `hover` takes 12 frames, eased-out." The `duration` is in frames (a positive integer) and the `easing` accepts the same forms you already know — `"ease-out"`, `{ type: "cubic-bezier", x1, y1, x2, y2 }`, `{ type: "spring", stiffness, damping }`, `{ type: "step", steps }`.
+
+Transitions are **directional**. `default → hover` and `hover → default` are configured separately, and they usually differ — entrances ease-out, exits ease-in. Pass `transition: null` to remove a configured transition. A state cannot transition to itself, and the target state must already exist (the tool checks both).
+
+## Interactive motion: default → hover → pressed
+
+The classic button is three states and the transitions between them:
+
+```ts
+// states
+atelier_add_state({ id, stateName: "hover",   duration: 30 });
+atelier_add_state({ id, stateName: "pressed", duration: 30 });
+// (hover and pressed typically set parent: "default" — see hierarchical states)
+
+// transitions, each with timing that fits the move
+atelier_configure_transition({ id, stateName: "default", targetState: "hover",   transition: { duration: 10, easing: "ease-out" } });
+atelier_configure_transition({ id, stateName: "hover",   targetState: "pressed", transition: { duration: 6,  easing: "ease-in"  } });
+atelier_configure_transition({ id, stateName: "pressed", targetState: "hover",   transition: { duration: 8,  easing: "ease-out" } });
+atelier_configure_transition({ id, stateName: "hover",   targetState: "default", transition: { duration: 14, easing: "ease-in"  } });
+```
+
+At this point the document *describes* a state machine — but nothing fires the transitions yet. States and transitions are pure data. Something has to say "go."
+
+## The interaction layer — triggers that fire transitions
+
+`atelier_add_interaction` attaches a **trigger → action** binding to a layer. The trigger is the event; the action is what happens.
+
+```ts
+atelier_add_interaction({
+  id,
+  layerId: "button",
+  interactionId: "to-hover",
+  trigger: { type: "hover" },
+  action: { type: "go-to-state", state: "hover" },
+  description: "Lift the button when the pointer enters",
+});
+```
+
+Triggers: `click`, `hover`, `pointerdown`, `pointerup`, `timer` (needs a `delay` in ms), `signal` (needs a `signal` name). Actions: `go-to-state` (needs a `state`), `emit-signal`, `set-variable`, `toggle-visibility`. For the button you wire `hover → go-to-state hover`, `pointerdown → go-to-state pressed`, `pointerup → go-to-state hover`.
+
+A `go-to-state` action does **not** snap. It runs the **transition** you configured from the current state to the target — with that transition's duration and easing. Interactions decide *when*; transitions decide *how it looks getting there*. If no transition is configured for that pair, the runtime cuts to the target's frame 0.
+
+## Two-trigger patterns worth knowing
+
+- **Auto-advance:** a `timer` trigger with `delay` plus `go-to-state` — an intro state that walks itself to the main state after N milliseconds, no input required.
+- **Decoupled choreography:** one layer's `click` action is `emit-signal`; another layer has a `signal` trigger that does `go-to-state`. The clicker doesn't know who's listening. This is how a single tap drives several layers into new states without hard-wiring them together.
+
+## Inspecting an interaction
+
+```ts
+atelier_list_interactions({ id });            // every layer
+atelier_list_interactions({ id, layerId: "button" });  // one layer
+```
+
+The studio's interaction inspector shows each binding and lets you fire it manually to watch the transition play. If a click "does nothing," it is almost always a missing transition for that state pair — the action fired, but there was no bridge to animate across.
+
+Next: the motion deep dive — springs, expressions, and motion paths.

package/university/content/notes/N-atel-501-detected-vs-user-edited.md

@@ -0,0 +1,76 @@
+---
+id: N-atel-501-detected-vs-user-edited
+title: Detected vs. user-edited — why your fixes survive a re-run
+type: note
+track: ATEL-501
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-501
+  - video
+  - aspects
+difficulty: intermediate
+estimatedMinutes: 6
+prerequisites:
+  - N-atel-101-layers
+summary: The `~detected-vs-user-edited` aspect — detections are immutable, but your overrides (padding, userEdited/userAdded/hidden, corrected text) are re-attached across re-runs by matching on timing tolerance plus unchanged detected text.
+---
+
+## The problem this aspect solves
+
+The video pipeline is meant to be re-run. You re-transcribe after swapping the audio; you re-detect after a re-cut. But every re-run regenerates the machine's findings from scratch. If a re-run wiped your corrections, you'd never trust it — you'd transcribe once, then refuse to touch it.
+
+`~detected-vs-user-edited` is the invariant that makes re-running safe:
+
+> AI-detected content is immutable. User overrides are preserved across re-runs by matching fresh detections to existing entries on timing tolerance **plus** unchanged detected text.
+
+Detected and edited values live in *separate fields* so the two never collide. A transcript word carries both:
+
+```json
+{ "detected": "atelyer", "text": "atelier", "start": 3.40, "end": 3.72, "userEdited": true }
+```
+
+`detected` is what Whisper heard — the machine's column. `text` is what renders — yours. The same split exists on a cut: `rawStart`/`rawEnd` are detected, `paddingPre`/`paddingPost` are yours.
+
+## How a re-run re-attaches your edits
+
+When you re-run, the merge walks the **fresh** detections and asks, for each one: did the user override a matching old entry? "Matching" means two conditions, both required:
+
+1. the timing is within a tolerance, **and**
+2. the `detected` string is unchanged.
+
+| Pipeline | Tolerance | Second condition |
+|---|---|---|
+| Transcript (`mergeTranscriptWithExisting`) | `0.3s` | `detected` string identical |
+| Cuts (`mergeWithExisting`) | `0.5s` | both `rawStart` and `rawEnd` within tolerance |
+
+If both hold, the old override (`text`, `userEdited`, `hidden`, or the cut's padding and label) is copied onto the fresh detection. If they don't, the fresh default wins — because the underlying audio genuinely changed there, and your old correction may no longer make sense.
+
+Requiring **unchanged detected text** is the subtle part. Timing alone isn't enough: if Whisper now hears a different word at that timestamp, blindly carrying your old correction forward would graft a fix onto the wrong word. Matching the `detected` string guarantees you're editing the same finding you edited before.
+
+## userAdded words are orphans — and they're kept
+
+A word you inserted with `atelier transcript add` has no fresh detection to match — Whisper never heard it. These `userAdded` words are preserved as orphans and re-inserted into the right segment by their timing. Your additions don't evaporate just because they aren't in the new Whisper output.
+
+`hidden` words (from `atelier transcript delete`) follow the same rule as edits: matched on timing + unchanged `detected`, then the `hidden` flag rides along.
+
+## Concrete: fix a misheard word, re-transcribe, fix survives
+
+```
+# Whisper hears "atelyer" at word 12
+atelier transcript fix ./proj --word 12 --text 'atelier'
+#   → word 12 now { detected: "atelyer", text: "atelier", userEdited: true }
+
+# later — re-transcribe (swapped a louder take of the same audio)
+atelier transcribe ./proj
+#   → fresh detection at ~3.40s still hears "atelyer"
+#   → matches on 0.3s timing + unchanged detected "atelyer"
+#   → your text:"atelier" + userEdited:true are re-attached
+
+atelier transcript list ./proj
+#   [  12]    3.40s  "atelier" ← "atelyer" [edited]
+```
+
+The same shape holds for cuts: nudge `--cut 3 --pad-post 0.4`, re-run `atelier trim`, and as long as cut #3's raw boundaries land within `0.5s` of where they were, your `0.4s` of trailing padding rides through. Re-detect freely; the human's editorial layer is sticky by construction.

package/university/content/notes/N-atel-501-layer-tag-isolation.md

@@ -0,0 +1,62 @@
+---
+id: N-atel-501-layer-tag-isolation
+title: Layer-tag isolation — pipelines that never step on each other
+type: note
+track: ATEL-501
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-501
+  - video
+  - aspects
+difficulty: intermediate
+estimatedMinutes: 5
+prerequisites:
+  - N-atel-101-layers
+summary: The `~layer-tag-isolation` aspect — each content pipeline owns a tag namespace and on re-run drops ONLY its own tagged layers, never touching another pipeline's output or user-authored layers. Proven by tests.
+---
+
+## One document, many writers
+
+A `project.atelier` is written by several actors at once: `atelier trim` owns the cut layers, `atelier transcribe` owns the caption layers, recipes own the overlay layers — and *you* hand-author whatever else the scene needs. They all live in the same `layers` array. Re-running any one of them must not disturb the others.
+
+`~layer-tag-isolation` is the rule that makes that work:
+
+> Every content pipeline owns a layer tag-namespace and, on re-run, drops ONLY its own tagged layers before re-adding them — never touching user-authored (untagged) layers or other pipelines' outputs.
+
+This is the load-bearing invariant of the whole human-and-agent loop. Without it, every regenerate would be a gamble; with it, you can re-run a pipeline a hundred times and lose nothing you didn't ask it to touch.
+
+## The namespaces
+
+| Tag | Owner | Status |
+|---|---|---|
+| `silence-trim` | `atelier trim` | Actively written |
+| `caption` | `atelier transcribe` / `atelier captions regenerate` | Actively written |
+| `caption-word` | reserved for per-word caption layers | Reserved in the isolation contract |
+| `overlay` | Studio Recipes (handle, page-number, decoration) | Written by the recipe pipeline |
+
+`silence-trim` and `caption` are what the commands in this track produce. `caption-word` is a reserved slot in the isolation contract — the namespace is claimed so that a future per-word caption mode can't collide with phrase-level `caption` layers. `overlay` belongs to the recipe pipeline (ATEL-301 covers it). Anything **untagged** is yours, and no pipeline ever touches it.
+
+## How a rewrite stays isolated
+
+The mechanism is one line of intent: **filter by tag before rewriting.** When the caption builder rewrites, it partitions the document:
+
+```ts
+// keep everything that ISN'T a caption layer
+const preserved = doc.layers.filter((l) => !(l.tags ?? []).includes("caption"));
+// build fresh caption layers from the current transcript
+const { layers: captionLayers } = buildCaptionLayers(transcript, doc.canvas, options);
+return { ...doc, layers: [...preserved, ...captionLayers] };
+```
+
+`silence-trim` layers, `overlay` layers, and your untagged layers all fall into `preserved` and pass through unchanged. Only the `caption` set is dropped and rebuilt. `atelier trim` does the identical thing for its `silence-trim` tag. Two pipelines, two namespaces, zero overlap.
+
+The same care extends to deltas: when captions are rebuilt, only the deltas keyed to the caption layers being replaced are dropped — every other delta in the state survives.
+
+## Proven by tests, not just by convention
+
+Layer-tag isolation isn't an honor system. The test suite asserts the invariant directly: it seeds a document with a user-authored layer plus one pipeline's tagged layers, re-runs the *other* pipeline, and checks that the user layer and the sibling pipeline's layers are byte-for-byte present afterward. A regression that let `transcribe` clobber a `silence-trim` layer — or a hand-authored title — would turn the suite red.
+
+That's the contract you get to lean on: tag a layer with a pipeline's namespace and that pipeline owns it; leave a layer untagged and it's untouchable. Regenerate as often as you like. The machine only ever cleans up after itself.

package/university/content/notes/N-atel-501-silence-trim.md

@@ -0,0 +1,98 @@
+---
+id: N-atel-501-silence-trim
+title: Silence trimming with parametric cuts
+type: note
+track: ATEL-501
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-501
+  - video
+  - trim
+difficulty: intermediate
+estimatedMinutes: 6
+prerequisites:
+  - N-atel-101-layers
+summary: How `atelier trim` turns ffmpeg silencedetect output into parametric video cuts — the immutable-boundary + tunable-padding model, the `--tighten`/`--loosen`/`--cut` overrides, and the `cuts.json` artifact.
+---
+
+## What `atelier trim` does
+
+```
+atelier trim ./my-video-project
+```
+
+A VideoProject is a folder: a source clip, a `project.atelier` composition, and the pipeline artifacts (`cuts.json`, `transcript.json`). `atelier trim` reads the source, finds the silence, and rewrites the `silence-trim` tagged layers in `project.atelier` so the timeline plays only the parts where someone is talking.
+
+It does this in a fixed pipeline:
+
+1. Probe that ffmpeg has the `silencedetect` filter.
+2. `ffprobe` the source duration.
+3. Run `silencedetect` → silence intervals.
+4. Invert silence into the gaps between it — the **speech intervals**.
+5. Build a fresh `CutEntry[]` with default (or recipe) padding.
+6. Merge with the existing `cuts.json` to preserve user padding (unless `--reset`).
+7. Apply `--tighten` / `--loosen` / `--cut` overrides.
+8. Resolve overlaps at silence midpoints.
+9. Clamp boundaries to `[0, duration]`.
+10. Write `cuts.json` and rewrite the `silence-trim` layers.
+
+## The detect step
+
+`silencedetect` is a threshold detector: anything quieter than `--noise` for at least `--min-silence` seconds is silence.
+
+| Flag | Default | Meaning |
+|---|---|---|
+| `--noise <dB>` | `-30dB` | Below this level counts as silence |
+| `--min-silence <seconds>` | `0.35` | Shortest gap that registers as silence |
+
+Atelier never stores the silence directly — it inverts it. Leading silence (before the first detected gap) and trailing silence (after the last) are handled so the very start and end of a clip aren't accidentally cut.
+
+## Immutable boundary, tunable padding
+
+This is the core idea of the cut model. A `CutEntry` is four numbers:
+
+```json
+{ "rawStart": 4.21, "rawEnd": 9.83, "paddingPre": 0.08, "paddingPost": 0.12 }
+```
+
+- **`rawStart` / `rawEnd`** are the *detected* speech boundaries. They are the machine's findings and you don't edit them by hand.
+- **`paddingPre` / `paddingPost`** are *yours*. They widen (or tighten) the cut around the raw boundary so a clip doesn't snap shut on the first or last syllable.
+
+The effective cut is `[rawStart - paddingPre, rawEnd + paddingPost]`. Defaults are deliberately asymmetric — `paddingPre` is `0.08s`, `paddingPost` is `0.12s` — because a hair more room after a phrase reads more natural than room before it.
+
+Why separate the two? Because re-running detection regenerates `rawStart`/`rawEnd` from the audio, but your padding is an editorial decision that should survive. That separation is the `~detected-vs-user-edited` aspect, and note 3 covers exactly how the padding gets re-attached after a re-detect.
+
+## The three padding overrides
+
+You tune padding without ever touching a raw boundary:
+
+| Flag | Effect |
+|---|---|
+| `--tighten <ms>` | Reduce padding on **every** cut by N milliseconds |
+| `--loosen <ms>` | Increase padding on **every** cut by N milliseconds |
+| `--cut <index>` | Scope `--pad-pre` / `--pad-post` to **one** cut |
+
+`--tighten` and `--loosen` are in **milliseconds** — they're converted to seconds (`ms / 1000`) and added to current padding, which is why they compose with whatever per-cut overrides already exist instead of clobbering them. Padding floors at zero; you can't tighten a cut into a negative span.
+
+```
+atelier trim ./proj --loosen 120          # everything breathes a bit more
+atelier trim ./proj --cut 3 --pad-post 0.4  # cut #3 lingers; the rest unchanged
+```
+
+`--pad-pre` / `--pad-post` without `--cut` set the *default* padding applied to freshly-detected cuts.
+
+## Overlap and clamp
+
+After overrides, two adjacent cuts can have padding that overruns the silence between them. `resolveOverlaps` splits the gap at its **midpoint** — neither cut wins, each takes its half. Then `clampBoundaries` pulls the first cut's `paddingPre` and the last cut's `paddingPost` back inside `[0, duration]` so nothing reaches past the clip.
+
+## `cuts.json` is the source of truth
+
+```
+atelier trim ./proj --dry-run   # print computed cuts, write nothing
+atelier trim ./proj --json      # emit the result as JSON for piping
+```
+
+`cuts.json` (version `1.1`) is the durable artifact. The `silence-trim` layers in `project.atelier` are *derived* from it — a re-run drops and rebuilds them. Edit padding through the CLI, not by hand-editing the layers, and your intent persists across every re-detect.

package/university/content/notes/N-atel-501-transcribe-and-captions.md

@@ -0,0 +1,98 @@
+---
+id: N-atel-501-transcribe-and-captions
+title: Transcription, transcript editing, and captions
+type: note
+track: ATEL-501
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-501
+  - video
+  - captions
+difficulty: intermediate
+estimatedMinutes: 7
+prerequisites:
+  - N-atel-101-layers
+summary: '`atelier transcribe` (Whisper), the `atelier transcript` edit family (fix/add/delete/merge/split/list), and `atelier captions regenerate` — how spoken audio becomes word-level caption layers you can correct by hand.'
+---
+
+## Transcribe
+
+```
+atelier transcribe ./my-video-project
+```
+
+This runs Whisper over the source clip, writes `transcript.json`, and rewrites the `caption` tagged `TextVisual` layers in `project.atelier`. The pipeline:
+
+1. Probe a Whisper backend.
+2. Run Whisper → raw transcript JSON.
+3. Parse into the `VideoTranscript` shape (segments → words).
+4. Merge with the existing transcript to preserve your edits (unless `--reset`).
+5. Write `transcript.json`.
+6. Unless `--no-captions`: rebuild the caption layers.
+
+### Backend probe order
+
+The probe checks, in order:
+
+1. **`whisper-cpp`** — if `whisper-cli` is on your PATH (`brew install whisper-cpp`).
+2. **`openai-api`** — if `OPENAI_API_KEY` is set. Reserved for an opt-in path; it currently throws "not yet implemented." Install whisper.cpp for local transcription.
+3. **`none`** — nothing available; the command throws with install guidance.
+
+| Flag | Default | Meaning |
+|---|---|---|
+| `--model <name>` | `base.en` | `tiny`/`base`/`small`/`medium`/`large-v3` (and `.en` variants) |
+| `--language <code>` | autodetect | BCP-47 hint; omit to autodetect |
+| `--reset` | off | Discard existing edits; full fresh transcript |
+| `--no-captions` | off | Write `transcript.json` only; skip caption layers |
+
+whisper.cpp is run with `--word-thold 0.01` so it emits word-level timestamps. When only segment-level boundaries come back, word timing is synthesized by an even split across the segment — captions still get per-word timing to animate against.
+
+## The transcript edit family
+
+Whisper mishears. `atelier transcript` is the family of subcommands that correct it without re-running the model. Words are addressed by a **global index** across all segments — start with `list`:
+
+```
+atelier transcript list ./proj          # every word, its index, start time, and flags
+```
+
+| Subcommand | What it does |
+|---|---|
+| `fix` | Correct text — `--replace 'wrong=right'` (batch) or `--word <idx> --text '...'` (single) |
+| `add` | Insert a user-added word — `--after-word <idx> --text '...'` (`--duration` default `0.15s`) |
+| `delete` | Hide a word — `--word <idx>` (kept in transcript, dropped from captions) |
+| `merge` | Join words `i` and `i+1` — `--word <i>` |
+| `split` | Split one word at a fraction — `--word <idx> --at <0–1>` |
+
+```
+atelier transcript fix ./proj --replace 'atelyer=atelier' --replace 'lottie=Lottie'
+atelier transcript fix ./proj --word 42 --text 'parametric'
+atelier transcript delete ./proj --word 7
+```
+
+Two behaviors worth burning in:
+
+- **`delete` doesn't delete.** It sets `hidden` on the word. The word stays in `transcript.json` (so a re-transcribe can re-recognize it) but is skipped when captions are built. This is a soft, reversible cut.
+- **`split --at` must be strictly between 0 and 1.** Exactly `0` or `1` is rejected — there's nothing to split off. Timing prorates across the split point; text defaults to slicing at the character midpoint, overridable with `--first` / `--second`.
+
+Every edit subcommand regenerates the caption layers after writing the transcript, unless you pass `--no-regenerate`.
+
+## Captions: phrases and word-level timing
+
+Captions aren't one layer per word — words are grouped into **phrases**, one `caption` tagged layer each. A new phrase starts whenever any of these is true:
+
+- the phrase reaches the max-words ceiling (default 5),
+- the current word ends in `. ! ? , ; :`, or
+- the gap to the next word exceeds the pause threshold (default `0.4s`).
+
+Hidden words are skipped during grouping. Each phrase layer is a `TextVisual` placed in the lower third (`yRatio` default `0.85`) with `opacity: 0`, and gets a fade-in / fade-out delta pair keyed to its start and end times.
+
+## Regenerate without re-running Whisper
+
+```
+atelier captions regenerate ./proj
+```
+
+When you only change *styling* — font, size, position, phrase grouping — there's no reason to transcribe again. `captions regenerate` re-derives the caption layers from the current `transcript.json`. Its only flag is `--recipe <name>`, which applies a Studio Recipe's `caption_style` + `caption_grouping`. Whisper stays untouched; your transcript edits stay intact.

package/university/content/notes/N-atel-601-carousel.md

@@ -0,0 +1,71 @@
+---
+id: N-atel-601-carousel
+title: The carousel driver — a folder of images into posts
+type: note
+track: ATEL-601
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-601
+  - carousel
+  - batch
+difficulty: intermediate
+estimatedMinutes: 5
+prerequisites:
+  - N-atel-301-composition-and-overlays
+summary: atelier carousel takes a recipe plus a folder of images and composes one PNG per image, threading currentIndex/totalCount into the page-number overlay so each post reads "i/N". The folder → posts → destination workflow, the 1-based index, fit-to-canvas composition, and zero-padded sortable output names.
+---
+
+## The workflow: folder into posts
+
+A carousel is the multi-image-post format — a swipeable deck where each frame is its own image with consistent branding and a "where am I in the deck" indicator. The `atelier carousel` command is the batch driver for exactly that:
+
+```
+atelier carousel <recipe> --inputs <glob> --out-dir <dir>
+```
+
+The shape of the workflow is **folder → posts → destination.** Point `--inputs` at a folder of images, hand it a recipe, name a `--out-dir`, and it composes one recipe-overlaid PNG per image. Short forms `-i` / `-d` exist; `--width` / `--height` set the canvas (default 1080×1080), and `-f` / `--frame` pick the frame to render.
+
+```
+atelier carousel my-style --inputs ./shots --out-dir ./posts
+atelier carousel my-style -i "shots/*.png" -d ./posts --width 1080 --height 1350
+```
+
+`--inputs` accepts a directory (every image inside), a single file, or a single-segment `*`-glob in the final path component (`shots/*.png`). Multi-segment and recursive globs are out of scope — point it at a directory instead. Accepted extensions are `.png`, `.jpg`, `.jpeg`, `.webp`. The matched list is sorted lexicographically so ordering is stable and predictable.
+
+## Per-image composition
+
+For each image, `composeCarouselFrameDoc` builds a minimal single-frame document: a canvas-sized doc with a background and one fit-to-canvas `ImageVisual` layer (anchored centered at `{0.5, 0.5}`). The image's natural dimensions aren't known until node-canvas decodes the file, so the bounds start at the canvas extent and are re-fitted (`refitImageBounds`) once the real dimensions are available at render time.
+
+Then the recipe's `overlay_rules` are applied on top of that base doc — the handle (if any) and, crucially, the page-number.
+
+## currentIndex / totalCount threaded into page-number
+
+This is what makes the carousel a carousel. The driver loops over the sorted inputs and, for image `n`, applies the recipe with a **1-based** index:
+
+```
+const index = n + 1;       // 1-based
+applyRecipeToOverlay(baseDoc, recipe, { currentIndex: index, totalCount: total });
+```
+
+`totalCount` is the count of matched images. Because both context values are present, the page-number layer *is* emitted (unlike a single-frame `apply-recipe`), and `renderPageNumberFormat` substitutes them into the format string. A recipe whose `page_number.format` is `"{current:02d}/{total:02d}"` produces `01/05`, `02/05`, … across a five-image deck. This is the one place page-numbers come fully alive — the carousel batch is the natural carrier of the `i/N` context.
+
+## Output names: zero-padded and sortable
+
+Each composed PNG is written to `--out-dir` (created if missing) with a zero-padded, sortable name (`carouselFileName`):
+
+```
+03-myphoto.png      # prefix = index, zero-padded to max(2, digits-in-N)
+```
+
+The prefix width is `Math.max(2, String(total).length)` — always at least two digits, widening when the deck has 100+ images — so the files sort in deck order in any file browser or upload picker, then carry the original stem and a `.png` extension. The page-number *content* and the filename *prefix* both derive from the same 1-based index, so what the viewer sees and how the files sort stay in agreement.
+
+## Where it sits in the pipeline
+
+The carousel driver renders through the same shared export-image path the rest of the CLI uses, so it inherits node-canvas's font and image handling. It needs node-canvas available; if the optional native renderer is missing, it fails with a clear `CanvasUnavailableError` rather than a cryptic crash.
+
+The carousel is the culmination of the recipe story: one authored style, one folder of raw images, and a complete branded, numbered, swipeable deck out the other end — every overlay placed by the same `overlay_rules` translator and the same layer-tag isolation invariant that protects every other Atelier pipeline.
+
+That closes ATEL-601. You can now author a Studio Recipe, apply it through the CLI and through MCP, attach anchored handle and page-number overlays, and batch a folder of images into a finished carousel.

package/university/content/notes/N-atel-601-overlay-rules.md

@@ -0,0 +1,96 @@
+---
+id: N-atel-601-overlay-rules
+title: Overlay rules — anchored handle and page-number presets
+type: note
+track: ATEL-601
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-601
+  - overlays
+  - recipe
+difficulty: intermediate
+estimatedMinutes: 6
+prerequisites:
+  - N-atel-301-composition-and-overlays
+summary: overlay_rules (Phase 1.5) declares two anchored text presets — handle and page_number. Page-number formats support {current}/{total} and zero-padded {current:02d}/{total:02d}. Anchors map to four corners via frame + anchorPoint. Overlays live in the overlay tag namespace and the translator builds a brand-new document (~copy-on-write-doc).
+---
+
+## The overlay_rules block
+
+`overlay_rules` was promoted from the reserved Phase 3 set into first-class **Phase 1.5**. It declares anchored text overlays that mark a composition. There are two sub-blocks, both optional:
+
+```yaml
+overlay_rules:
+  handle:
+    text: "@username"
+    anchor: "bottom-left"
+    margin: 32
+    style:
+      font_family: "Inter"
+      font_size: 36
+      font_weight: "bold"
+      color: "#FFFFFF"
+  page_number:
+    format: "{current:02d}/{total:02d}"
+    anchor: "bottom-right"
+    margin: 32
+    style:
+      font_family: "Inter"
+      font_size: 18
+      font_weight: "normal"
+      color: "#9CA3AF"
+```
+
+The translator that turns these rules into layers is `applyRecipeToOverlay` (in `packages/cli/src/lib/recipe.ts`). It builds at most one `handle` layer and one `page_number` layer, both `TextVisual`.
+
+## handle — a static marker
+
+A `handle` is a literal text overlay: a social handle, a credit, a watermark. Its `OverlayHandleRule` shape is `{ text, anchor, margin?, style? }`. The `text` is rendered verbatim — template variables are reserved for later, so today `text` is exactly the string that appears.
+
+The built layer always gets the stable id **`overlay-handle`** and `tags: ["overlay"]`. The handle is *unconditional*: if `overlay_rules.handle` is present, the handle layer is always produced, on single frames and carousel pages alike.
+
+## page_number — a parameterized template
+
+A `page_number` is a template, not a literal. Its `OverlayPageNumberRule` shape is `{ format, anchor, margin?, style? }`, and `format` is a string with placeholders:
+
+```
+"{current}/{total}"           -> "3/5"
+"{current:02d}/{total:02d}"   -> "03/05"
+"Page {current} of {total}"   -> "Page 3 of 5"
+```
+
+Two placeholder forms are recognized: bare `{current}` / `{total}`, and the zero-padded `{current:0Nd}` / `{total:0Nd}` form (the `N` is the pad width, so `{current:02d}` pads to two digits). The schema (`^valid-recipe` gate) enforces the syntax at validate time and requires **at least one** of `{current}` / `{total}` to appear — a format with neither is rejected. Render-time substitution happens in `renderPageNumberFormat`, which is a regex replace over those two placeholder shapes.
+
+The built layer gets the stable id **`overlay-page-number`** and `tags: ["overlay"]`.
+
+**Page-number needs carousel context.** `applyRecipeToOverlay` only emits the page-number layer when both `currentIndex` and `totalCount` are passed in its context argument. On a single-frame apply (no carousel), the context is absent, so the layer is skipped with a one-shot warning — `01/01` on a standalone post is misleading, so skipping is by design. The handle is unaffected. The carousel driver (next note) is what threads `currentIndex`/`totalCount` in.
+
+## The four-corner anchor math
+
+`anchor` is one of `top-left | top-right | bottom-left | bottom-right` (the `OverlayAnchor` type). The translator's `anchorToFrame` maps each corner to a `frame` position plus an `anchorPoint`, with `margin` (default 24px) insetting from the anchored edges:
+
+| `anchor` | `frame` | `anchorPoint` |
+|---|---|---|
+| `top-left` | `{ x: margin, y: margin }` | `{ x: 0, y: 0 }` |
+| `top-right` | `{ x: canvas.width - margin, y: margin }` | `{ x: 1, y: 0 }` |
+| `bottom-left` | `{ x: margin, y: canvas.height - margin }` | `{ x: 0, y: 1 }` |
+| `bottom-right` | `{ x: canvas.width - margin, y: canvas.height - margin }` | `{ x: 1, y: 1 }` |
+
+The pairing of `frame` and `anchorPoint` is what makes the corner stick. A `bottom-right` overlay anchors its own bottom-right corner (`anchorPoint {1, 1}`) at the canvas's bottom-right-minus-margin point — so the text grows inward, away from the edge, regardless of how long it is. The anchor also doubles as the rotation/scale pivot if you later animate the overlay.
+
+The `style` block is a partial `OverlayTextStyle` (`font_family`, `font_size`, `font_weight`, `color`) and merges over a runtime baseline of `Inter / 24px / 600 / #F5F5F7` — so an overlay with no `style` still renders legibly.
+
+## The overlay tag namespace and ~copy-on-write-doc
+
+Two invariants govern how overlays touch a document.
+
+**Layer-tag isolation (`~layer-tag-isolation`).** Every overlay layer carries `tags: ["overlay"]`. Before appending the freshly-derived overlays, `applyRecipeToOverlay` filters out *every* existing `overlay`-tagged layer: `doc.layers.filter((l) => !(l.tags ?? []).includes("overlay"))`. Re-applying a recipe drops the prior overlay set and re-adds — idempotent, repeatable. User-authored (untagged) layers, caption-pipeline layers (`tags: ["caption"]`), and silence-trim layers are never touched. The stable ids (`overlay-handle`, `overlay-page-number`) mean a re-apply replaces in place rather than stacking duplicates.
+
+**Copy-on-write (`~copy-on-write-doc`).** The translator never mutates the input. It constructs a *new* document — spreads the doc, swaps in a new layers array — and returns it: `return { ...doc, layers: [...preserved, ...overlayLayers] }`. The input document is left untouched. This guarantees a concurrent reader (notably the studio's live WebSocket bridge) can never observe a half-mutated document mid-update.
+
+## One translator, two homes
+
+`applyRecipeToOverlay` exists in two places: the canonical version in `packages/cli/src/lib/recipe.ts` and a deliberate duplicate in `packages/mcp/src/tools/recipes.ts`. The MCP package does *not* depend on the CLI package — importing it would risk a cli↔mcp dependency cycle — so the overlay translator (and `renderPageNumberFormat`) are re-implemented on top of the shared schema package. The duplication is intentional and documented in the MCP file; both implementations honor the same two invariants above.