@a-company/atelier 0.36.0 → 0.38.0

package/university/content/paths/LP-atel-401.yaml

@@ -0,0 +1,22 @@
+id: LP-atel-401
+title: 'ATEL-401: State Machines & Motion'
+description: 'From states-as-data to interactive, physically-tuned, reusable motion. Hierarchical states and their merge rule, transitions and the interaction layer, the motion deep dive (springs, expression-valued deltas, motion paths), and the preset-vs-template distinction. After this track you can build and package interactive UI motion in Atelier. ~27 minutes.'
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-401
+ordered: true
+steps:
+  - content: N-atel-401-hierarchical-states
+    required: true
+  - content: N-atel-401-transitions
+    required: true
+  - content: N-atel-401-motion-deep-dive
+    required: true
+  - content: N-atel-401-presets-and-templates
+    required: true
+  - content: Q-atel-401-state-machines
+    required: true
+    passRequired: true

package/university/content/paths/LP-atel-501.yaml

@@ -0,0 +1,22 @@
+id: LP-atel-501
+title: 'ATEL-501: Video Project Pipeline'
+description: 'The video pipeline — silence trimming with parametric cuts, Whisper transcription, the transcript edit family, and caption generation. Two aspects make the loop safe: detections are immutable while your overrides survive every re-run, and each pipeline touches only its own tagged layers. After this track you can drive a VideoProject end to end and re-run any stage without losing human work. ~24 minutes.'
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-501
+ordered: true
+steps:
+  - content: N-atel-501-silence-trim
+    required: true
+  - content: N-atel-501-transcribe-and-captions
+    required: true
+  - content: N-atel-501-detected-vs-user-edited
+    required: true
+  - content: N-atel-501-layer-tag-isolation
+    required: true
+  - content: Q-atel-501-video-pipeline
+    required: true
+    passRequired: true

package/university/content/paths/LP-atel-601.yaml

@@ -0,0 +1,22 @@
+id: LP-atel-601
+title: 'ATEL-601: Recipes, Overlays & Carousel'
+description: 'Style as a reusable preset — the Studio Recipe, anchored handle and page-number overlays, the CLI/MCP tooling and precedence, and the carousel batch driver that turns a folder of images into a numbered, branded post deck. After this track you can author a recipe, apply it through the CLI and MCP, and batch-compose a carousel. ~22 minutes.'
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-601
+ordered: true
+steps:
+  - content: N-atel-601-studio-recipe
+    required: true
+  - content: N-atel-601-overlay-rules
+    required: true
+  - content: N-atel-601-recipe-tools-and-apply
+    required: true
+  - content: N-atel-601-carousel
+    required: true
+  - content: Q-atel-601-recipes
+    required: true
+    passRequired: true

package/university/content/paths/LP-atel-701.yaml

@@ -0,0 +1,22 @@
+id: LP-atel-701
+title: 'ATEL-701: Export & Delivery'
+description: Getting work out of Atelier — single-frame raster (PNG), vector (SVG and Lottie), and video (MP4/GIF via FFmpeg, WebM via the studio), then a decision guide that picks a format by destination. After this track you can choose the right exporter for any target and know which paths need extra dependencies. ~25 minutes.
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-701
+ordered: true
+steps:
+  - content: N-atel-701-png-and-frames
+    required: true
+  - content: N-atel-701-vector
+    required: true
+  - content: N-atel-701-video
+    required: true
+  - content: N-atel-701-choosing-output
+    required: true
+  - content: Q-atel-701-export
+    required: true
+    passRequired: true

package/university/content/paths/LP-atel-801.yaml

@@ -0,0 +1,22 @@
+id: LP-atel-801
+title: 'ATEL-801: Studio & the Live Agent Loop'
+description: 'The live editing loop — `atelier studio` as a local-first browser editor, the editing surface (layer-type picker, image drop, slider commit-gating), the WebSocket bridge + MCP-over-WS transport that lets an agent mutate the open document in real time, and the symbiotic pattern where the human and agent co-edit the same single-store doc. After this track you understand how Atelier turns a chat conversation into a live, undoable canvas. ~22 minutes.'
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-801
+ordered: true
+steps:
+  - content: N-atel-801-studio-app
+    required: true
+  - content: N-atel-801-editing-surface
+    required: true
+  - content: N-atel-801-live-bridge
+    required: true
+  - content: N-atel-801-symbiotic-loop
+    required: true
+  - content: Q-atel-801-studio-loop
+    required: true
+    passRequired: true

package/university/content/quizzes/Q-atel-001-orientation.yaml

@@ -0,0 +1,66 @@
+id: Q-atel-001-orientation
+title: 'ATEL-001: Hello Atelier — Orientation'
+description: Verify the foundations from ATEL-001 — what Atelier is, how the three commands relate, and the shape of a minimal document.
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-001
+difficulty: beginner
+passThreshold: 0.7
+questions:
+  - id: q1
+    question: Which of the following best describes what makes Atelier "AI-native"?
+    choices:
+      A: It uses an LLM at render time to generate frames procedurally
+      B: It ships with a chat interface bolted onto a traditional editor
+      C: Its document format and 52 MCP tools are designed for an agent to author directly, with typed mutations and schema-validated errors
+      D: It runs only when an AI assistant is connected, refusing programmatic CLI use
+    correct: C
+    explanation: Atelier is AI-native because the document format and the MCP tool surface were designed for an agent to author. Mutations go through typed tools (atelier_add_layer, atelier_add_state, etc.) that validate against a Zod schema with readable errors. The engine itself is deterministic — no LLM is involved at render time, and the CLI and Builder API are first-class for programmatic use.
+  - id: q2
+    question: After running `npm i -g @a-company/atelier`, which three commands are on your PATH and what is each one's primary role?
+    choices:
+      A: '`atelier` (CLI), `atelier-mcp` (MCP server for AI agents), `atelier studio` (local browser editor) — all share one engine and document store'
+      B: '`atelier` (only CLI) — the MCP server and studio require separate npm packages'
+      C: '`atelier` (CLI), `atelier-cloud` (sync to SaaS), `atelier-render` (rendering daemon)'
+      D: '`atelier-cli`, `atelier-server`, `atelier-gui` — three independent binaries that do not share state'
+    correct: A
+    explanation: One install provides three executables that share `@atelier/core`. The CLI is for scripts and inspection, the MCP server is what an AI agent connects to, and `atelier studio` boots a local browser editor. They all read and write the same `.atelier` files and, with the live bridge enabled, observe each other's mutations.
+  - id: q3
+    question: In a minimal `.atelier` document, what is the relationship between a layer, a state, and a delta?
+    choices:
+      A: 'A layer is a keyframe; a state is a property; a delta is a layer parented to another layer'
+      B: 'A layer describes what exists; a state names a duration; a delta interpolates one property of one layer over a frame range with an easing'
+      C: 'A layer is an export format; a state is a render preset; a delta is a diff between two documents'
+      D: 'They are interchangeable names for the same concept — pick whichever reads best'
+    correct: B
+    explanation: Layers describe what exists in the scene (shape/text/image/video). States are named keyframes with a duration in frames. Deltas animate one property of one layer from a `from` value to a `to` value across `startFrame`–`endFrame` with an easing. Everything else in Atelier — easings, presets, templates, interactions, refs — extends these three primitives.
+  - id: q4
+    question: 'The "detected-vs-user-edited" convention in Atelier is a design pattern that solves which problem?'
+    choices:
+      A: 'How to compress YAML files so they download faster'
+      B: 'How to let an AI agent and a human edit the same document repeatedly without one erasing the other'
+      C: 'How to detect whether a user is logged in to Atelier Cloud'
+      D: 'How to choose between Canvas 2D and WebGL at render time'
+    correct: B
+    explanation: 'When an Atelier pipeline (silence-trim, captions, agent mutations) generates layers, those layers carry a tag identifying their source. User edits set `userEdited` / `userAdded` / `hidden` flags. When the pipeline re-runs (re-transcribe, re-detect silence, re-propose layout), it matches existing entries by timing tolerance and preserves the user''s edits. The same idea generalizes to any source — human, agent, or pipeline — so the symbiotic loop never destroys authorship.'
+  - id: q5
+    question: What does `atelier studio` bind to by default, and why?
+    choices:
+      A: '0.0.0.0 — to let teammates connect from the same WiFi network'
+      B: '127.0.0.1 — to keep the editor local-only and prevent drive-by writes from any browser tab'
+      C: 'A randomized public IP — for cloud sync'
+      D: 'It does not bind to a port; it uses raw IPC'
+    correct: B
+    explanation: '`atelier studio` binds to 127.0.0.1 (loopback) so the server is only reachable from the same machine. Mutating endpoints additionally check the Origin header to reject cross-origin POSTs from random browser tabs. There is no LAN or cloud exposure by default — Atelier is a local-first tool.'
+  - id: q6
+    question: You ran `atelier preview hello.atelier --frame 15`. What did it output, and what is it equivalent to inside the engine?
+    choices:
+      A: 'A rendered PNG of frame 15 saved to disk — equivalent to `atelier export --frame 15`'
+      B: 'The resolved layer state at frame 15 (interpolated property values), the same as what the renderer calls `resolveFrame(doc, "default", 15)` produces'
+      C: 'A live video stream starting from frame 15'
+      D: 'Nothing — `preview` requires the studio to be running'
+    correct: B
+    explanation: '`atelier preview` calls the same `resolveFrame` function the renderer uses. It returns the interpolated layer state at that frame — every animatable property resolved through its delta and easing. Use it to inspect what the renderer would draw without actually rasterizing. For PNG output, use `atelier export --frame N --out file.png`.'

package/university/content/quizzes/Q-atel-101-document-model.yaml

@@ -0,0 +1,66 @@
+id: Q-atel-101-document-model
+title: 'ATEL-101: Document Model Fundamentals'
+description: Verify the document model — format shape, layer anatomy, states/deltas/resolveFrame, easings.
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-101
+difficulty: beginner
+passThreshold: 0.7
+questions:
+  - id: q1
+    question: What are the five mandatory top-level keys in every `.atelier` document?
+    choices:
+      A: '`name`, `canvas`, `assets`, `variables`, `presets`'
+      B: '`name`, `canvas`, `layers`, `states`, plus at least one state with a `duration`'
+      C: '`title`, `description`, `frames`, `tracks`, `outputs`'
+      D: '`document`, `scene`, `keyframes`, `easings`, `version`'
+    correct: B
+    explanation: The minimum valid document has `name`, `canvas` (width/height/fps), `layers` array, and `states` with at least one named state containing a `duration`. `assets`, `variables`, `presets`, `templates`, `audio`, `meta` are all optional and added only when needed.
+  - id: q2
+    question: 'A layer has `frame: {x: 400, y: 300}`, `bounds: {width: 600, height: 80}`, and `anchorPoint: {x: 0.5, y: 0.5}`. Where on the canvas does the center of the layer sit?'
+    choices:
+      A: At canvas pixel (0, 0)
+      B: At canvas pixel (400, 300) — the anchor is the pivot, and `frame` positions the anchor
+      C: At canvas pixel (700, 380) — bottom-right of the layer
+      D: At canvas pixel (100, 260) — top-left of the layer
+    correct: B
+    explanation: '`anchorPoint` is normalized 0–1 inside the layer''s `bounds`. `{0.5, 0.5}` puts the anchor at the layer''s center. `frame` then positions that anchor on the canvas. So the layer''s center sits exactly at the `frame` coordinates (400, 300). The anchor is also the pivot for `rotation` and `scale`.'
+  - id: q3
+    question: Two deltas in the same state target the same layer and property, with overlapping `startFrame`/`endFrame` ranges. What happens?
+    choices:
+      A: The engine merges them by averaging the values
+      B: The second delta silently wins over the first
+      C: The schema rejects the document — the no-overlap gate blocks overlapping motion at validate time
+      D: Both deltas play simultaneously and the renderer additively combines them
+    correct: C
+    explanation: Atelier's `no-overlap` gate (in the document-builder) rejects overlapping deltas on the same layer+property because the result is almost always a bug. If you need composed motion, use two layers or a group. The error message names the conflicting deltas so you can fix them quickly.
+  - id: q4
+    question: 'What does `resolveFrame(doc, stateName, frameNumber)` return?'
+    choices:
+      A: A rendered PNG buffer
+      B: 'A ResolvedLayer array — every layer with all animatable properties interpolated through their deltas and easings to concrete values for that frame, ready for any renderer'
+      C: The list of deltas active at that frame
+      D: A diff against the previous frame
+    correct: B
+    explanation: '`resolveFrame` is the engine''s core: it returns a fully-resolved scene where every animatable property has a concrete value. Canvas 2D, SVG export, Lottie export, and the video exporter all consume this same array. Adding a new renderer is "consume ResolvedLayer[] one frame at a time."'
+  - id: q5
+    question: You want a UI element to slide in from the right and feel natural. Which easing is the right default?
+    choices:
+      A: '`linear` — constant rate is the cleanest'
+      B: '`ease-out` — decelerating motion is how organic things arrive (entrance animation convention across the industry)'
+      C: '`step(4)` — discrete jumps look modern'
+      D: '`ease-in` — acceleration into the final position'
+    correct: B
+    explanation: '`ease-out` (CSS cubic-bezier(0, 0, 0.2, 1)) is the de facto standard for UI entrance animation. The element decelerates as it arrives, mimicking a physical object losing momentum. `ease-in` is correct for exits, `linear` is correct for scrubbing/progress bars, and `step()` is for sprite-frame indexing or digital-readout feel. The general rule: if a physical object would do it, use spring or ease-out.'
+  - id: q6
+    question: Why do pipeline-generated layers carry tags like `silence-trim`, `caption`, or `overlay`?
+    choices:
+      A: 'Cosmetic — the tags only affect what color the layer appears as in the layer panel'
+      B: 'For pricing — each tag corresponds to a separately billed feature'
+      C: 'To enforce the layer-tag isolation invariant — re-running a pipeline drops only its own tagged layers; user-authored layers and other pipelines'' outputs are never touched'
+      D: 'For sorting alphabetically'
+    correct: C
+    explanation: Tags are how the pipelines (silence-trim, captions, overlays, future agent-driven pipelines) find layers they own. When `atelier captions regenerate` runs, it drops layers tagged `caption` and `caption-word` and writes fresh ones — but never touches layers tagged `silence-trim` or `overlay`, and never touches user-authored untagged layers. This is the load-bearing invariant that makes the human↔agent symbiotic loop safe.

package/university/content/quizzes/Q-atel-201-mcp-authoring.yaml

@@ -0,0 +1,66 @@
+id: Q-atel-201-mcp-authoring
+title: 'ATEL-201: Authoring via MCP'
+description: Verify the MCP tool surface — the single-store invariant, tool naming conventions, common authoring patterns, and the most-common agent mistakes.
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-201
+difficulty: intermediate
+passThreshold: 0.7
+questions:
+  - id: q1
+    question: An AI agent calls `atelier_add_layer` while a human is editing the same document in `atelier studio`. The Studio's canvas re-renders within a frame. What architectural pattern makes this work?
+    choices:
+      A: The Studio polls the MCP server every 100ms for changes
+      B: 'There is one DocumentStore shared by both the MCP tool handlers and the Studio; mutations fire onChange, the WebSocket bridge broadcasts to Studio, Studio applies via applyMutation(op) with a suppress-notify flag'
+      C: The agent and the human edit separate copies that are merged by an operational-transform algorithm
+      D: 'The Studio receives a full document diff via HTTP long-poll on every keystroke'
+    correct: B
+    explanation: 'Atelier is single-author with an AI collaborator, not a multiplayer canvas. One in-memory DocumentStore is shared; mutations fire onChange; the bridge broadcasts to any connected Studio; the Studio applies via applyMutation(op) with a one-tick suppress-notify flag so the change does not echo back as a human edit. Conflict policy is last-write-wins, tagged source: "human" | "llm" so the UI can attribute changes.'
+  - id: q2
+    question: 'You are an agent. You call `atelier_add_delta` to animate `style.borderRadius` on a TextVisual layer. The tool returns an error. What is the correct response?'
+    choices:
+      A: 'Retry the same call — transient errors are common'
+      B: 'Read the error verbatim, recognize that borderRadius is not animatable on a text layer, choose a real text property (style.fontSize, style.color, opacity) and call again'
+      C: 'Edit the document file directly with `fs.writeFile` to bypass the validator'
+      D: 'Suppress the error and continue — the schema validation is advisory'
+    correct: B
+    explanation: 'The schema rejects animatable-property mismatches with AI-readable errors naming the exact field. The correct flow is read the error, fix the request, retry. Bypassing the validator is not possible (every tool call validates); editing files directly defeats the LLM↔Studio bridge and produces drift. The four most common agent mistakes are documented in the patterns note — this is mistake #1.'
+  - id: q3
+    question: 'Which two-tool pairing covers "I want this fade-in pattern on every title layer in three different states"?'
+    choices:
+      A: '`atelier_add_delta` called 9 times, once per (layer, state) pair — there is no other way'
+      B: '`atelier_define_preset` once to bundle the deltas, then `atelier_apply_preset` per layer per state with an optional offset for staggering'
+      C: '`atelier_instantiate_template` — templates are how repeated motion is expressed'
+      D: '`atelier_set_motion_path` once on each layer — motion paths handle all repetition'
+    correct: B
+    explanation: 'Presets bundle deltas; templates bundle layer subtrees. For "same motion on N layers" the right tool is `atelier_define_preset` + `atelier_apply_preset` with the `offset` parameter for staggering. Templates are for "same layer subtree" (group + children with variable substitution). One-of-a-kind motion should be hand-authored.'
+  - id: q4
+    question: How are layers in the overlay namespace (handle, page-number) protected from being destroyed when a recipe is re-applied?
+    choices:
+      A: They are stored in a separate file outside the document
+      B: 'They are tagged `overlay`; the `applyRecipeToOverlay` translator drops only overlay-tagged layers before re-adding, leaving user-authored layers and other pipelines'' outputs untouched'
+      C: A locking mechanism prevents re-application unless the user confirms
+      D: They are recreated identically every time; user edits are discarded by design
+    correct: B
+    explanation: 'Layer-tag isolation is the load-bearing invariant. Each pipeline owns a tag namespace (`silence-trim`, `caption`, `caption-word`, `overlay`) and re-running a pipeline drops only its own tagged layers. User-authored layers (untagged) and other pipelines'' outputs (different tag) are never touched. The same idea generalizes to agent mutations via the `source: "human" | "llm"` op tagging.'
+  - id: q5
+    question: 'Two `atelier_add_delta` calls target the same layer and the same property, with overlapping `startFrame`–`endFrame` ranges. What happens?'
+    choices:
+      A: The second call replaces the first silently
+      B: The values are averaged
+      C: 'The no-overlap gate rejects the second call with a field-level error naming both deltas; the agent must split into adjacent ranges or use two layers'
+      D: Both run additively at render time
+    correct: C
+    explanation: 'The no-overlap gate lives in the document builder and rejects overlapping deltas on the same layer + property. Overlapping motion is almost always a bug. The error message names both conflicting deltas so the fix is obvious — split into adjacent ranges, or compose by adding a second layer or a group.'
+  - id: q6
+    question: An agent is configuring a Claude Desktop client. The MCP config entry needed to connect to atelier-mcp is which of the following?
+    choices:
+      A: '`{ "mcpServers": { "atelier": { "command": "atelier-mcp" }}}` — that is the full config'
+      B: 'Requires an API token from atelier.dev'
+      C: 'Requires running `atelier login` first to provision credentials'
+      D: 'Requires manually starting `atelier-mcp serve` as a background process; the config points to its port'
+    correct: A
+    explanation: 'Atelier is local-first. The MCP config entry is one line — Claude Desktop spawns the `atelier-mcp` stdio process on demand. No tokens, no login, no separate daemon. To pin the project root, set `ATELIER_PROJECT_ROOT` in the env. To pair with `atelier studio` for live mutation, just run the studio — the bridge connection is auto-detected.'

package/university/content/quizzes/Q-atel-301-visual-system.yaml

@@ -0,0 +1,66 @@
+id: Q-atel-301-visual-system
+title: 'ATEL-301: Visual System'
+description: Verify the visual surface — shapes, text, images/video, effects (fills/strokes/shadows/blends/clips/motion paths/tints), composition (groups/refs), and the overlay namespace.
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-301
+difficulty: intermediate
+passThreshold: 0.7
+questions:
+  - id: q1
+    question: 'For text to render consistently across the browser studio and the CLI PNG export, what is the recommended pattern?'
+    choices:
+      A: Set `fontFamily` to a generic name like `sans-serif` and let each renderer pick
+      B: 'Ship the font as an asset (`atelier_add_asset({ kind: "font", src: "fonts/Inter.woff2" })`) and reference it by PostScript name in `fontFamily`'
+      C: Use only system fonts that ship with macOS, Windows, and Linux
+      D: Convert all text to SVG paths before rendering
+    correct: B
+    explanation: Without font assets, the studio uses browser-available fonts and the CLI PNG export uses node-canvas with whatever's installed on the machine. Renders diverge. Registering the font as an asset and referencing its PostScript name in `fontFamily` makes the renderer load the same font everywhere. The CSS-style fallback chain still works for graceful degradation.
+  - id: q2
+    question: 'You want to crop an image to show only its center 50% in a layer that sits in a 1080×1080 layout. The source image is 2000×1500. Which approach fits the "cropping vs scaling" model best?'
+    choices:
+      A: Pre-process the image with a tool like ImageMagick and ship the cropped version
+      B: 'Set `sourceRect: {x: 500, y: 375, width: 1000, height: 750}` to pick the center 50% from the source; the layer''s bounds and the image''s drawn region handle the rest'
+      C: 'Set `Layer.scale.x: 2.0` and `Layer.scale.y: 2.0` to zoom in'
+      D: Resize the layer's `bounds` to be smaller than the image
+    correct: B
+    explanation: '`sourceRect` is the right tool — it picks a sub-rectangle from the source image in source pixels. The center 50% of a 2000×1500 image is `{x: 500, y: 375, width: 1000, height: 750}`. Layer.scale stretches the rendered layer (lossy zoom). Layer.bounds changes the destination size (the renderer fits per objectFit). Pre-processing forfeits the ability to animate the crop later (ken-burns pan/zoom via deltas on sourceRect).'
+  - id: q3
+    question: A `motionPath` is set on a layer that also has a delta animating `frame.x`. What happens?
+    choices:
+      A: The delta wins; the motion path is ignored
+      B: 'The motion path wins; the frame.x delta is ignored — animate `motionProgress` instead'
+      C: They additively combine, producing a sum trajectory
+      D: 'The schema rejects the document at validate time'
+    correct: B
+    explanation: When a motion path is present, the layer's frame.x and frame.y are overridden — the path is the trajectory. Deltas on frame.x conflict with the path and are ignored at render time. To control speed along the path, animate `motionProgress` (0..1). If you want a custom trajectory, you've already chosen the motion path — express speed/timing through motionProgress + easings, not through frame deltas.
+  - id: q4
+    question: 'Why do overlay layers (handle, page-number) carry `tags: ["overlay"]` instead of being plain text layers?'
+    choices:
+      A: For sidebar grouping in the studio's layer panel only
+      B: 'So the `applyRecipeToOverlay` translator can drop only overlay-tagged layers when re-running — user-authored layers and other pipelines'' tagged outputs are never touched'
+      C: 'For pricing tier enforcement — overlay layers count toward a quota'
+      D: 'Because TextVisual without the tag has reduced rendering quality'
+    correct: B
+    explanation: 'The `overlay` tag is part of the layer-tag isolation invariant. Each pipeline owns a tag namespace; re-running a pipeline drops only its own tagged layers. Without the tag, re-applying a recipe would either destroy the user''s authored text layers (bad) or fail to clear stale overlay layers (also bad). With the tag, recipes are idempotent and human edits survive re-runs.'
+  - id: q5
+    question: 'A `RefVisual` layer references `./lower-third.atelier`. You edit the referenced file in another editor. What does `atelier studio` do?'
+    choices:
+      A: 'Nothing — refs are resolved once at load time'
+      B: The studio file-watches every referenced file; on change, it re-renders the parent composition with the updated ref
+      C: It throws a stale-ref error and forces a reload
+      D: 'It requires the user to re-import the ref manually'
+    correct: B
+    explanation: '`RefVisual` is how Atelier expresses single-source-of-truth for reusable scenes (lock-ups, lower-thirds, carousel templates). The studio file-watches every referenced `.atelier` file and re-renders parent compositions automatically. Editing the source once updates every composition that uses it.'
+  - id: q6
+    question: 'A `page_number` overlay rule has `format: "{current:02d}/{total:02d}"`. You apply the recipe to a single-frame composition (no carousel context). What happens?'
+    choices:
+      A: The page-number layer is created with content `"{current:02d}/{total:02d}"` (template not rendered)
+      B: 'The applyRecipeToOverlay translator skips the page-number layer (logger warns) — page-numbers don''t make sense on standalone compositions; handle still gets added if configured'
+      C: It throws an error halting the whole apply-recipe pipeline
+      D: It picks defaults (`current=1`, `total=1`) and renders `"01/01"`
+    correct: B
+    explanation: 'Page-numbers require carousel context (`currentIndex`, `totalCount`). On single-frame applies, the translator skips the page-number layer with a logger warning — by design, since `01/01` on a standalone post is misleading. The handle overlay is unconditional and still gets added. When the carousel batch driver eventually applies the same recipe per page, it threads the current/total values into the apply context and the page-number renders correctly.'

package/university/content/quizzes/Q-atel-401-state-machines.yaml

@@ -0,0 +1,66 @@
+id: Q-atel-401-state-machines
+title: 'ATEL-401: State Machines & Motion'
+description: 'Verify hierarchical states, transitions and the interaction layer, motion (springs, expressions, motion paths), and the preset-vs-template distinction.'
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-401
+difficulty: intermediate
+passThreshold: 0.7
+questions:
+  - id: q1
+    question: 'A state `hover` has `parent: default`. `default` animates `title:opacity` with a spring. `hover` adds its own `title:opacity` delta with a linear easing. What does `resolveFrame` use for the title''s opacity on `hover`?'
+    choices:
+      A: 'The child''s linear delta only — the parent''s spring delta for that layer+property is dropped entirely'
+      B: 'Both deltas, additively combined into one curve'
+      C: 'The parent''s spring, because parents take precedence over children'
+      D: 'A field-level merge: the child''s easing with the parent''s from/to values'
+    correct: A
+    explanation: 'Inheritance merges per layer+property group, not per field. Deltas are grouped by a `layer+property` key, and the most-derived state''s group wins outright. Because `hover` declares any `title:opacity` delta, the parent''s `title:opacity` group is dropped wholesale — there is no field-level patching. To keep the parent''s spring and add motion, the child must animate a different property or layer.'
+  - id: q2
+    question: 'You configured `atelier_configure_transition` from `default` to `hover`. Does the reverse transition (`hover` to `default`) now exist?'
+    choices:
+      A: 'Yes — configuring one direction auto-creates the symmetric reverse'
+      B: 'No — transitions are directional; you must configure `hover` to `default` separately'
+      C: 'Yes, but only if both states share a parent'
+      D: 'No — transitions cannot point back to a previously visited state'
+    correct: B
+    explanation: 'Transitions are directional. `default` to `hover` and `hover` to `default` are configured independently, and they usually differ in duration and easing — entrances ease-out, exits ease-in. There is no auto-symmetry.'
+  - id: q3
+    question: 'A layer has a `click` interaction whose action is `go-to-state` targeting `pressed`. No transition is configured from the current state to `pressed`. What happens on click?'
+    choices:
+      A: 'The click is ignored because the transition is missing'
+      B: 'It plays a default 300ms ease-in-out transition'
+      C: 'The runtime cuts directly to `pressed` frame 0 — the action fires, but there is no bridge to animate across'
+      D: 'The schema rejected the document at validate time, so the click never wired up'
+    correct: C
+    explanation: 'Interactions decide when; transitions decide how it looks getting there. A `go-to-state` action runs the configured transition for that state pair. With no transition configured, the action still fires but the runtime snaps to the target state''s frame 0. A click that appears to "do nothing" is almost always a missing transition for that pair, not a missing interaction.'
+  - id: q4
+    question: 'In a spring easing `{ type: spring, stiffness: 100, damping: 10 }`, what most directly determines whether the motion visibly overshoots and bounces?'
+    choices:
+      A: 'Damping relative to stiffness — low damping against high stiffness oscillates; high damping glides in with no overshoot'
+      B: 'The `mass` field alone — higher mass always adds bounce'
+      C: 'The delta''s frame range length'
+      D: 'Whether `position: start` or `position: end` is set'
+    correct: A
+    explanation: 'Bounce is governed by damping relative to stiffness. Low damping against high stiffness oscillates; raising damping at the same stiffness removes overshoot and the spring glides in. Mass adds inertia and lag, not bounce. `position` belongs to step easings, not springs.'
+  - id: q5
+    question: 'You want a layer to follow a defined curved trajectory and control its speed along that curve. Which approach matches Atelier''s model?'
+    choices:
+      A: 'Animate `frame.x` and `frame.y` with matching deltas; the engine infers the curve'
+      B: 'Use an expression on `frame.x` that returns the full 2D path'
+      C: 'Define the path as a preset and apply it to the layer'
+      D: 'Set a `motionPath` on the layer and animate the `motionPath.progress` property; `frame.x`/`frame.y` deltas would be overridden by the path'
+    correct: D
+    explanation: 'A motion path overrides the layer''s `frame.x`/`frame.y` — the path is the trajectory, so frame deltas conflict and are ignored at render time. You control position along the path by animating `motionPath.progress` (0 to 1); that delta''s easing shapes speed along the curve. `autoRotate` can additionally bank the layer into the tangent.'
+  - id: q6
+    question: 'What is the difference between a preset and a template in Atelier?'
+    choices:
+      A: 'A preset is a bundle of deltas applied to an existing layer; a template is a layer subtree instantiated (with variable bindings) into a new document'
+      B: 'A preset is for export; a template is for the studio editor'
+      C: 'A preset creates new layers; a template animates existing ones'
+      D: 'They are interchangeable names for the same reuse mechanism'
+    correct: A
+    explanation: 'Presets = delta bundles; templates = layer subtrees. `atelier_define_preset` then `atelier_apply_preset` stamp motion onto a layer that already exists (expanding `offset` windows relative to `startFrame`). `atelier_instantiate_template` resolves `{{variable}}` placeholders against bindings and creates a new document with the structure. Motion from one mechanism, structure from the other.'

package/university/content/quizzes/Q-atel-501-video-pipeline.yaml

@@ -0,0 +1,66 @@
+id: Q-atel-501-video-pipeline
+title: 'ATEL-501: Video Project Pipeline'
+description: 'Verify the video pipeline — silence trimming with parametric cuts, Whisper transcription and the transcript edit family, caption generation, and the two re-run safety aspects (detected-vs-user-edited, layer-tag-isolation).'
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-501
+difficulty: intermediate
+passThreshold: 0.7
+questions:
+  - id: q1
+    question: 'In a CutEntry, which two fields are the immutable AI detections, and which two are the user-tunable overrides?'
+    choices:
+      A: 'paddingPre/paddingPost are detected; rawStart/rawEnd are user-tunable'
+      B: 'rawStart/rawEnd are detected (immutable); paddingPre/paddingPost are the user-tunable overrides'
+      C: 'All four are detected; the user edits the layers directly'
+      D: 'All four are user-tunable; nothing is detected'
+    correct: B
+    explanation: 'rawStart and rawEnd are the detected speech boundaries from silencedetect — you do not edit them by hand. paddingPre and paddingPost are your editorial overrides; the effective cut is [rawStart - paddingPre, rawEnd + paddingPost]. Keeping them in separate fields is what lets a re-detect regenerate the raw boundaries while preserving your padding.'
+  - id: q2
+    question: 'You run `atelier trim ./proj --loosen 120`. What happens?'
+    choices:
+      A: 'The 120 is treated as seconds and added to every paddingPre/paddingPost'
+      B: 'Every cut padding increases by 120 milliseconds (0.12s), composing with any existing per-cut overrides; padding still floors at 0'
+      C: 'Only cut #120 is loosened'
+      D: 'The raw boundaries shift outward by 120 frames'
+    correct: B
+    explanation: '`--tighten` and `--loosen` take milliseconds. 120ms is converted to 0.12s and added to the current padding of every cut, so it composes with overrides you already set rather than clobbering them. `--tighten` subtracts; padding is floored at 0 so you cannot drive a cut negative. Per-cut targeting is done with `--cut <index>`, not `--loosen`.'
+  - id: q3
+    question: 'What does `atelier transcript delete ./proj --word 7` actually do?'
+    choices:
+      A: 'Removes word 7 from transcript.json entirely'
+      B: 'Deletes the caption layer at index 7'
+      C: 'Sets hidden=true on word 7 — it stays in the transcript but is skipped when captions are built'
+      D: 'Lowers word 7 confidence below the caption threshold'
+    correct: C
+    explanation: 'delete is a soft, reversible cut. It sets hidden on the word; the word remains in transcript.json (so a future re-transcribe can re-recognize it) but groupIntoPhrases skips hidden words, so it never appears in a caption. To truly remove it you would have to edit it back in — by design, nothing is destroyed.'
+  - id: q4
+    question: 'A re-transcribe must decide whether to carry your correction forward to a fresh detection. Both conditions must hold for the override to be re-attached. Which pair?'
+    choices:
+      A: 'Same word index AND same segment'
+      B: 'Timing within tolerance (0.3s) AND the detected string is unchanged'
+      C: 'Same confidence value AND same language'
+      D: 'Identical text AND identical start time to the millisecond'
+    correct: B
+    explanation: 'mergeTranscriptWithExisting matches a fresh detection to an old entry on timing within 0.3s AND an unchanged detected string. Timing alone is not enough — if Whisper now hears a different word at that timestamp, carrying the old fix forward would graft it onto the wrong word. Requiring the detected string to match guarantees you are editing the same finding. (Cuts use the same idea with a 0.5s tolerance on both raw boundaries.)'
+  - id: q5
+    question: 'You added a word with `atelier transcript add` that Whisper never heard. On the next `atelier transcribe`, what happens to it?'
+    choices:
+      A: 'It is dropped — there is no matching fresh detection'
+      B: 'It is converted into a detected word with confidence 1.0'
+      C: 'It blocks the re-transcribe until you remove it'
+      D: 'It is preserved as a userAdded orphan and re-inserted into the right segment by its timing'
+    correct: D
+    explanation: 'A userAdded word has no fresh detection to match against by definition — Whisper did not produce it. The merge collects these orphans and re-inserts each into the segment that contains its timing. Your manual additions survive a re-transcribe just like your text corrections do.'
+  - id: q6
+    question: 'You run `atelier transcribe`, which rewrites caption layers. You also have hand-authored title layers and silence-trim layers in the same document. Why are your titles safe?'
+    choices:
+      A: 'transcribe only ever appends; it never removes layers'
+      B: 'Layer-tag isolation — the rewrite drops only caption-tagged layers; untagged (user-authored) and silence-trim-tagged layers fall into the preserved set and pass through unchanged'
+      C: 'Title layers are stored in a separate file from caption layers'
+      D: 'The schema locks all non-caption layers during a transcribe run'
+    correct: B
+    explanation: 'rewriteCaptionLayers partitions the document: everything that is NOT caption-tagged is preserved, and only the caption set is dropped and rebuilt. Your untagged titles and the silence-trim-tagged cut layers are untouched. Each pipeline owns exactly one tag namespace and cleans up only after itself — the invariant the test suite asserts directly.'

package/university/content/quizzes/Q-atel-601-recipes.yaml

@@ -0,0 +1,66 @@
+id: Q-atel-601-recipes
+title: 'ATEL-601: Recipes, Overlays & Carousel'
+description: 'Verify the Studio Recipe surface — what a recipe is and how partial recipes fall back, overlay_rules (handle + page_number, anchors, format templates), the CLI/MCP tooling and precedence, and the carousel batch driver.'
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-601
+difficulty: intermediate
+passThreshold: 0.7
+questions:
+  - id: q1
+    question: 'You author a recipe that sets only `caption_style.color`. What happens to the silence policy and the rest of the caption style when you apply it?'
+    choices:
+      A: 'The apply fails — a recipe must declare every Phase 1 section to be valid'
+      B: 'Omitted fields fall back to the code defaults (e.g. noise -30dB, font_size 84); the merge is shallow per section, so setting one caption field does not wipe the others'
+      C: 'Only the color is applied and all other styling is cleared to empty/zero'
+      D: 'The recipe silently does nothing because it is incomplete'
+    correct: B
+    explanation: 'Every section and every field is optional. Omitted fields fall back to the code defaults baked into renderRecipeWithDefaults, and the merge overlays your section over the defaults section — so setting one caption field leaves the rest of the defaults intact. Run `atelier recipe show <name> --with-defaults` to see the fully-resolved effective recipe.'
+  - id: q2
+    question: 'A recipe includes a `palette` section. You run `atelier recipe validate` on it. What is the result?'
+    choices:
+      A: 'FAIL — palette is not a recognized field'
+      B: 'PASS with no remarks — palette is fully implemented'
+      C: 'PASS, but with a forward-compat warning that palette is a reserved Phase 3 field that Phase 1 ignores'
+      D: 'It strips the palette section and rewrites the file'
+    correct: C
+    explanation: 'palette is one of the six reserved Phase 3 fields. They parse cleanly as opaque (unknown) values so recipes stay forward-compatible, but Phase 1 ignores their contents. validate emits a forward-compat warning (not an error) so you are not caught off-guard that the section is inert. Note overlay_rules was promoted to first-class Phase 1.5 and does NOT warn.'
+  - id: q3
+    question: 'A `page_number` rule has `format: "{current:02d}/{total:02d}"` and you apply the recipe to a single-frame composition via `atelier apply-recipe` (no carousel context). What renders?'
+    choices:
+      A: 'A page-number layer with the literal content `{current:02d}/{total:02d}` (template not substituted)'
+      B: 'The page-number layer is skipped with a warning; the handle is still applied if present'
+      C: 'It defaults to current=1, total=1 and renders `01/01`'
+      D: 'The whole apply-recipe pipeline throws and halts'
+    correct: B
+    explanation: 'applyRecipeToOverlay only emits the page-number layer when both currentIndex and totalCount are in its context. A single-frame apply has no carousel context, so the page-number is skipped with a one-shot warning — `01/01` on a standalone post would be misleading. The handle overlay is unconditional and still gets added. The carousel driver is what threads current/total in.'
+  - id: q4
+    question: 'In the four-corner anchor math, what does the `anchor` value `bottom-right` map to (with margin m on a canvas of width W and height H)?'
+    choices:
+      A: 'frame `{ x: m, y: m }`, anchorPoint `{ x: 0, y: 0 }`'
+      B: 'frame `{ x: W - m, y: H - m }`, anchorPoint `{ x: 1, y: 1 }`'
+      C: 'frame `{ x: W - m, y: m }`, anchorPoint `{ x: 1, y: 0 }`'
+      D: 'frame `{ x: W / 2, y: H / 2 }`, anchorPoint `{ x: 0.5, y: 0.5 }`'
+    correct: B
+    explanation: 'anchorToFrame pairs the frame position with a matching anchorPoint so the corner sticks. bottom-right places frame at `{ W - margin, H - margin }` and sets anchorPoint `{ 1, 1 }`, so the overlay anchors its own bottom-right corner at the canvas bottom-right-minus-margin point and grows inward regardless of text length. The anchor doubles as the rotation/scale pivot.'
+  - id: q5
+    question: 'How does `atelier_recipe_save` (MCP) differ from `atelier recipe new` (CLI), and why does it matter for an editing agent?'
+    choices:
+      A: 'They are identical; save is just the MCP alias for new'
+      B: 'new writes an always-valid scaffold template; save validates BEFORE writing and refuses to write an invalid recipe — so an agent persisting an edited recipe cannot land a malformed file on disk'
+      C: 'save writes without validating; new validates first'
+      D: 'new can only write YAML, save can only write JSON'
+    correct: B
+    explanation: 'recipe new scaffolds a starter template that is valid by construction and does not validate. atelier_recipe_save is how an agent persists an EDITED recipe, so it runs validateRecipe first and refuses to write if invalid, returning the issues instead. That validate-before-write guard is what keeps a malformed agent edit from ever reaching disk.'
+  - id: q6
+    question: 'The carousel driver loops over a sorted folder of N images. For image at loop position n (0-based), what index does it thread into the page-number overlay, and how is the output filename prefixed?'
+    choices:
+      A: 'index = n (0-based); filename prefixed with the raw loop counter, no padding'
+      B: 'index = n + 1 (1-based); filename prefixed with a zero-padded number of width max(2, digits-in-N)'
+      C: 'index is a random uuid; filename uses the original image name unchanged'
+      D: 'index = N - n (counts down); filename prefixed with the total count'
+    correct: B
+    explanation: 'The driver computes `const index = n + 1` (1-based) and passes `{ currentIndex: index, totalCount: total }` so the page-number renders i/N. The output name is zero-padded to `Math.max(2, String(total).length)` digits then carries the original stem, so files sort in deck order. Both the page-number content and the filename prefix derive from the same 1-based index, keeping what the viewer sees and how files sort in agreement.'