@a-company/atelier 0.36.0 → 0.38.0

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.

package/university/content/notes/N-atel-601-recipe-tools-and-apply.md

@@ -0,0 +1,84 @@
+---
+id: N-atel-601-recipe-tools-and-apply
+title: Recipe tooling — CLI verbs, MCP tools, and resolution
+type: note
+track: ATEL-601
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-601
+  - cli
+  - mcp
+difficulty: intermediate
+estimatedMinutes: 6
+prerequisites:
+  - N-atel-301-composition-and-overlays
+summary: The recipe surface — CLI verbs (recipe new/validate/show, apply-recipe, the --recipe flag on trim/transcribe/captions regenerate) and MCP tools (atelier_recipe_list/get/validate/save/apply). save refuses invalid recipes; apply wires only overlay_rules. The two-tier resolution chain and CLI-wins precedence.
+---
+
+## CLI: the recipe family
+
+```
+atelier recipe new <name>        scaffold a starter YAML with every default filled in
+atelier recipe validate <path>   validate against the schema (^valid-recipe gate)
+atelier recipe show <path>       print a recipe; --with-defaults overlays code defaults
+```
+
+**`recipe new`** scaffolds. It writes a starter `.recipe.yaml` (into `./.atelier/recipes/` by default, or `--dir`) with every Phase 1 field present and commented, so you learn the shape by editing. It refuses to overwrite an existing file, and it guards the footgun where `recipe new foo.recipe.yaml` would otherwise produce `foo.recipe.yaml.recipe.yaml`. Note: `new` only writes a template — it does *not* validate, because the scaffold is always valid by construction.
+
+**`recipe validate`** runs the recipe through `validateRecipe` and reports `PASS`/`FAIL`. It also surfaces forward-compat warnings for reserved Phase 3 fields. Add `--json` for machine-readable output.
+
+**`recipe show`** prints the recipe back as YAML. With `--with-defaults` it overlays the code defaults onto every omitted field, so you see the fully-resolved effective recipe.
+
+## CLI: applying a recipe
+
+A recipe touches a project two ways.
+
+**The `--recipe <name>` flag** on the individual pipelines:
+
+```
+atelier trim <project> --recipe my-style                  silence_policy as the baseline
+atelier transcribe <project> --recipe my-style            caption_style + caption_grouping
+atelier captions regenerate <project> --recipe my-style   caption_style + caption_grouping
+```
+
+Each flag pulls the relevant section from the recipe and uses it as the baseline for that pipeline. (The caption verb is `captions regenerate`, not a bare `captions`.)
+
+**The `apply-recipe` convenience verb** runs trim and transcribe against the same recipe in one shot:
+
+```
+atelier apply-recipe <project> <recipe>
+```
+
+In order: `atelier trim`, then `atelier transcribe`, then — if the recipe has `overlay_rules` — the overlay translator rewrites the project's `overlay`-tagged layers. Flags: `--reset` (destructive — discards existing user padding and transcript edits on both pipelines), `--no-trim`, `--no-transcribe`. Because `apply-recipe` is a single-frame apply with no carousel context, the page-number layer is silently skipped; the handle is applied if present.
+
+## MCP: the conversational surface
+
+Five tools let an agent view, edit, and apply recipes without shelling out:
+
+```
+atelier_recipe_list      enumerate discoverable recipes (project + user library)
+atelier_recipe_get       load a recipe; returns BOTH the parsed object and its YAML
+atelier_recipe_validate  validate a path OR inline YAML text
+atelier_recipe_save      write a recipe — refuses to write if invalid
+atelier_recipe_apply     apply overlay_rules to an in-store document
+```
+
+Two behaviors are worth internalizing.
+
+**`atelier_recipe_save` validates before writing.** It runs `validateRecipe` first and *refuses* to write an invalid recipe, returning the validation issues instead. This is the deliberate contrast with `recipe new`: `new` scaffolds an always-valid template; `save` is how an agent persists an *edited* recipe, and it guards the write so a malformed edit never lands on disk. It creates parent directories as needed and accepts either a recipe object or raw YAML text.
+
+**`atelier_recipe_apply` only applies `overlay_rules`.** This is the key agent mental-model point. The apply tool wires up *only* the handle + page-number overlays onto an in-store document (the result is stored back with `source: "llm"`). Silence-trim, transcribe, and caption application stay **CLI-only** — there is no MCP path for them. If the recipe requests a `page_number` but `currentIndex`/`totalCount` aren't passed, that layer is skipped and a warning is returned (same rule as the CLI translator).
+
+## Resolution chain and precedence
+
+A bare recipe name resolves through a two-tier chain (`resolveRecipePath` in `packages/cli/src/lib/recipe.ts`), checking these extensions at each tier — `.recipe.yaml`, `.recipe.json`, `.yaml`, `.yml`, `.json`:
+
+1. **Project-local:** `<projectDir>/.atelier/recipes/<name>.<ext>`
+2. **User library:** `~/.atelier/recipes/<name>.<ext>`
+
+The project directory is searched first, so a project can shadow a personal recipe of the same name. A path that is absolute or contains a slash skips resolution entirely and loads literally. `recipe new`, `recipe validate`, and `recipe show` all share this chain, so a name authored by `new` is found by `validate` and `show`.
+
+**CLI-wins precedence.** When a recipe is combined with explicit CLI flags, the CLI flag wins. In `applyRecipeToTrimOptions`, each field is `cliOptions.x ?? policy.x` — the recipe only fills in what the CLI left unspecified. So `atelier trim <project> --recipe my-style --noise -40dB` uses the recipe's silence policy as the baseline but honors the `-40dB` you typed. The recipe is a baseline; the command line is an override.

package/university/content/notes/N-atel-601-studio-recipe.md

@@ -0,0 +1,103 @@
+---
+id: N-atel-601-studio-recipe
+title: The Studio Recipe — style as a reusable preset
+type: note
+track: ATEL-601
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-601
+  - recipe
+  - presets
+difficulty: intermediate
+estimatedMinutes: 5
+prerequisites:
+  - N-atel-301-composition-and-overlays
+summary: A Studio Recipe is a reusable bundle of style defaults — silence policy, caption style, phrase grouping — authored once and applied to many projects. Phase 1 ships three implemented sections; partial recipes fall back to code defaults; six Phase 3 fields parse as opaque values for forward-compat.
+---
+
+## The value play
+
+A Studio Recipe is *your style, saved as a preset.* You spend an afternoon dialing in how your shorts look — how aggressively silence gets trimmed, what font and size the captions render at, how words group into phrases — and then you never tune it by hand again. You write those decisions into one YAML file and apply it to the next project, and the one after that.
+
+That's the whole pitch: **a recipe makes a look reproducible.** The same defaults, every project, until you decide to change them in one place.
+
+The type lives in `packages/types/src/recipe.ts` as `StudioRecipe`. The top of the file is metadata:
+
+```yaml
+version: "1.0"          # recipe format version — current is "1.0"
+name: "my-shorts-style"
+description: "Punchy captions, tight silence trim"
+author: "@me"
+tags: [shorts, vertical]
+```
+
+## The three Phase 1 sections
+
+Phase 1 implements three sections, each consumed by a different pipeline:
+
+```yaml
+silence_policy:           # consumed by `atelier trim`
+  noise: "-30dB"
+  min_silence: 0.35
+  default_padding_pre: 0.08
+  default_padding_post: 0.12
+  match_tolerance: 0.5
+
+caption_style:            # consumed by `atelier transcribe` / `captions regenerate`
+  font_family: "Inter"
+  font_size: 84
+  font_weight: "bold"     # normal | bold | numeric 100..900
+  text_align: "center"    # left | center | right
+  color: "#FFFFFF"
+  y_ratio: 0.85           # 0=top, 1=bottom
+  width_ratio: 0.9
+  fade_seconds: 0.05
+
+caption_grouping:         # consumed by `atelier transcribe` phrase grouping
+  max_words: 5
+  pause_gap: 0.4
+```
+
+**`silence_policy`** is the silence-trim baseline. Every field maps one-to-one onto an `atelier trim` option — `noise` is the `silencedetect` threshold, `min_silence` is the minimum gap that registers as a cut, the two `default_padding_*` values are the leading/trailing pad on new cuts, and `match_tolerance` is the timing window that preserves your hand-tuned padding when you re-run the trim (the detected-vs-user-edited invariant from ATEL-501).
+
+**`caption_style`** is the caption layer's visual presentation — font, color, vertical position as a ratio of canvas height, width as a ratio of canvas width, fade duration. The recipe is the canonical source for caption styling; the CLI doesn't expose per-invocation caption-style flags.
+
+**`caption_grouping`** controls how transcribed words clump into on-screen phrases: at most `max_words` per phrase, with a forced break whenever the gap between words exceeds `pause_gap` seconds.
+
+## Partial recipes fall back to code defaults
+
+Every section — and every field within a section — is optional. A recipe that only sets caption color is completely valid:
+
+```yaml
+version: "1.0"
+name: "just-the-color"
+caption_style:
+  color: "#FFD60A"
+```
+
+Omitted fields fall back to the code defaults baked into `renderRecipeWithDefaults` (in `packages/cli/src/lib/recipe.ts`). Those defaults are the same values the scaffold writes: `noise: -30dB`, `min_silence: 0.35`, caption `font_size: 84`, `max_words: 5`, and so on. The merge is shallow-per-section: your recipe's section overlays the defaults section, so setting one caption field doesn't wipe out the rest.
+
+To see the effective values — your recipe overlaid on the defaults — run `atelier recipe show <name> --with-defaults`. It prints the fully-resolved recipe so there's no guessing about what an omitted field will become.
+
+## Reserved Phase 3 fields parse as opaque values
+
+Five fields are declared in the type but not yet implemented:
+
+```
+caption_highlight    # per-word highlight color animation
+transition_kit       # transition defaults between clips
+palette              # brand colors / font set
+audio_policy         # ducking, music lane
+aspect_targets       # multi-aspect render targets
+```
+
+These are **reserved for Phase 3** (extraction-of-style-from-a-reference-video). They parse cleanly as opaque values — the schema accepts them as `unknown` — so a recipe that includes them today stays forward-compatible. Phase 1 simply ignores their contents.
+
+The one caveat: `atelier recipe validate` emits a forward-compat *warning* (not an error) when a reserved field is present, so you're never caught off-guard that a section you authored isn't doing anything yet. (`overlay_rules`, covered in the next note, was promoted out of this reserved set into first-class Phase 1.5 — it does *not* warn.)
+
+## Why a flat preset and not a template engine
+
+A recipe is deliberately *data, not behavior.* It carries no logic, no conditionals, no per-layer targeting — just a flat bag of style values that three pipelines read. That keeps recipes diffable, shareable, and safe to validate before they ever touch a document. The richer machinery (templates, presets, variables from ATEL-201) is what the pipelines use internally; the recipe is the human-facing dial.

package/university/content/notes/N-atel-701-choosing-output.md

@@ -0,0 +1,68 @@
+---
+id: N-atel-701-choosing-output
+title: Choosing an output — a decision guide by destination
+type: note
+track: ATEL-701
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-701
+  - delivery
+  - decision-guide
+difficulty: intermediate
+estimatedMinutes: 6
+prerequisites:
+  - N-atel-101-the-atelier-format
+summary: One decision guide across every exporter — pick the format by destination (social post, web embed, motion-design handoff, preview), hit the right aspect target, and know when to use the CLI versus the studio Export button.
+---
+
+## Start from the destination, not the format
+
+The mistake is asking "what can Atelier export?" The right question is "where is this going?" — and the destination picks the exporter for you.
+
+| Destination | Format | Command / surface |
+| --- | --- | --- |
+| Social image post | PNG | `atelier export-image` (or `atelier carousel` for a set) |
+| Open Graph / thumbnail / poster | PNG | `atelier export-image --width …` |
+| Web logo / icon that must scale | SVG | `atelier export-svg` |
+| Motion-design handoff (runtime / AE) | Lottie JSON | `atelier export-lottie` |
+| Social / web video | MP4 | `atelier render` or studio Export |
+| README / chat loop | GIF | `atelier render -f gif` |
+| Web video, modern browsers, small files | WebM | studio Export (WebCodecs) |
+| Frame inspection / debugging | JSON | `atelier still` (default format) |
+
+## The four common destinations, decided
+
+**Social post.** A still image, fixed pixel size, often square or portrait. → **PNG** via `atelier export-image`. Set your aspect with `--width`/`--height` (or design the canvas to the target). For a whole *set* of posts, see the carousel note below — don't loop the single-frame command.
+
+**Web embed.** Two cases. If it's a logo, icon, or any artwork that has to stay crisp at arbitrary sizes → **SVG** via `atelier export-svg`, inlined into markup (drop the `--xml-declaration`). If it's video → **MP4** for reach, **WebM** (studio) when the audience is modern browsers and file size matters.
+
+**Motion-design handoff.** You're giving the animation to a design or front-end team to drop into a product → **Lottie** via `atelier export-lottie`. It's the whole document as vector animation, tiny, and playable in every major runtime. Watch the stderr warnings: a clean export means the Lottie matches; a warning means a feature dropped and you should preview it in a player.
+
+**Preview.** You just want to see the current frame. → `atelier still` for the resolved-frame JSON (what the renderer sees), or `atelier still --format png` / `atelier export-image` for a quick pixel look. No FFmpeg, no canvas build — both raster previews run on a plain install.
+
+## Aspect targets
+
+Design the document canvas to the destination's aspect when you can — it's lossless. Common targets:
+
+- **1:1 (square)** — 1080×1080. Feed posts, carousels.
+- **4:5 (portrait)** — 1080×1350. Maximizes feed real estate.
+- **9:16 (vertical)** — 1080×1920. Stories, Reels, Shorts, TikTok.
+- **16:9 (landscape)** — 1920×1080. YouTube, web hero video, presentations.
+
+On a still export you can also retarget at export time: `atelier export-image hero.atelier --out card.png --width 1200` derives the height to preserve aspect. Override **both** `--width` and `--height` only when you deliberately want a non-aspect-preserving size — it will squash otherwise. For MP4, remember H.264 needs **even** dimensions; an odd canvas is rejected with the next even size suggested.
+
+## CLI or the studio Export button?
+
+Same artwork, two ways to get a file out:
+
+- **The studio Export button** encodes in the browser via WebCodecs — no FFmpeg, no node-canvas, nothing to install. Best for one-off exports while you're editing, and the only path that reaches WebM. Interactive, per-document.
+- **The CLI** (`export-image`, `export-svg`, `export-lottie`, `render`) is scriptable and batchable — wire it into a build, a script, a CI job. Raster and vector exports run on a plain install; **video (`atelier render`) additionally needs FFmpeg on `$PATH` and the `canvas` package** with its cairo/pango stack (see N-atel-701-video).
+
+Rule of thumb: editing and exporting one thing → studio. Automating or batching → CLI.
+
+## Batch image delivery — see ATEL-601
+
+When the job is *many* images at once — a folder of shots composed into a uniform set of posts with consistent overlays — that's `atelier carousel`, covered in **ATEL-601 (Studio Recipes)**. It drives the same single-frame raster path across every input and applies a recipe's handle + page-number overlays per image. This note doesn't re-teach it; reach for ATEL-601 when you need batch delivery rather than a single export.