@a-company/atelier 0.29.0 → 0.37.0

package/university/content/notes/N-atel-801-live-bridge.md

@@ -0,0 +1,84 @@
+---
+id: N-atel-801-live-bridge
+title: The live bridge — WebSocket, MCP-over-WS, and source-tagged mutations
+type: note
+track: ATEL-801
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-801
+  - bridge
+  - mcp
+  - aspects
+difficulty: advanced
+estimatedMinutes: 6
+prerequisites:
+  - N-atel-201-mcp-overview
+summary: How an agent mutates the open studio document in real time — the /bridge WebSocket and /mcp MCP-over-WS transport, DocumentStore.onChange → broadcast, AtelierStudio.applyMutation, and the ~source-tagged-mutation aspect (human|llm|system; only llm broadcasts) that prevents echo loops and false attribution. Plus toast attribution and Cmd-Z undo of an agent edit.
+---
+
+## Two endpoints on one server
+
+`atelier studio` mounts two WebSocket endpoints on Vite's HTTP server:
+
+- **`/mcp`** — an MCP-over-WebSocket transport. An external MCP client (e.g. Claude Desktop running `atelier-mcp`) connects here and drives the same 61 tools it would over stdio. Each connection gets its own `McpServer`, but they all share **one** `DocumentStore`. The transport (`WebSocketServerTransport`) wraps a single `ws` socket as an MCP `Transport`: inbound frames parse to JSON-RPC and surface via `onmessage`; outbound SDK messages stringify and `ws.send`. A malformed inbound frame surfaces via `onerror` but does NOT close the connection.
+- **`/bridge`** — a thin broadcast channel to the browser. It carries typed envelopes (`hello`, `doc:loaded`, `doc:patch`, `llm:mutation`, `error`) at `BRIDGE_PROTOCOL_VERSION = 1`. v1 ships whole-document replacement so the envelope stays trivial; a JSON-patch op shape is v1.1, once the byte cost is measured on real docs.
+
+## The Origin asymmetry
+
+WS upgrades bypass Vite's connect middleware (Node fires `upgrade` before connect runs), so the bridge re-runs the Origin check itself on every upgrade — otherwise either endpoint would be cross-origin-reachable from any tab. The check is asymmetric:
+
+- **`/bridge`** demands a strict same-origin match (`isAllowedOrigin`) — it's a real browser origin, your own studio tab.
+- **`/mcp`** tolerates a **missing** Origin (`isAllowedMcpOrigin`) but still rejects a present-but-foreign one. Non-browser MCP clients send NO Origin header; under the strict check they'd all 403 and MCP-over-WS would be unreachable. A browser tab on evil.com still can't reach `/mcp` (it sends a foreign Origin). The loopback bind to `127.0.0.1` remains the primary protection.
+
+## The mutation loop
+
+The full agent→human loop:
+
+```
+LLM tool call ──► McpServer (per /mcp conn) ──► DocumentStore.set(source:"llm")
+                                                        │
+                                          onChange fires (source = "llm")
+                                                        ▼
+                              bridge broadcasts `llm:mutation` envelope
+                                                        ▼
+                          browser studio.applyMutation({ type:"doc:replace", doc, source })
+                                                        ▼
+                       canvas re-renders + toast attribution (Cmd-Z still works)
+```
+
+And the human→agent direction:
+
+```
+human edit ──► AtelierStudio.onDocumentChange ──► `doc:patch` envelope
+                                                        ▼
+                              bridge writes DocumentStore.set(source:"human")
+                                                        ▼
+                              onChange fires (source = "human") → NOT broadcast
+```
+
+`applyMutation` is whole-document replacement only in v1 — the op shape is exactly `{ type: "doc:replace", doc, source }`. It snapshots the current state into undo history first (so an agent edit is undoable from your seat), preserves the current state name and selected layer when they still exist in the new doc, and sets a one-tick `suppressNotify` flag so the resulting re-render doesn't echo the change back out as a "human" edit.
+
+## ~source-tagged-mutation — the aspect that makes the loop safe
+
+Every `DocumentStore` mutation carries a **source tag**: `"human" | "llm" | "system"`. This is the load-bearing convention behind the live bridge, and it answers one question: *which changes should the browser be told about?*
+
+The rule, expressed in code as `shouldBroadcastMutation(source)`, is: **broadcast only when `source === "llm"`.**
+
+| Source | Where it comes from | Broadcast? | Why |
+|---|---|---|---|
+| `llm` | An MCP tool call over `/mcp` | **Yes** | A genuine agent edit — show it, persist it, toast it |
+| `human` | The browser's own edit via `doc:patch` (or `POST /api/file`) | No | The browser is already current — broadcasting would echo the edit back to the tab that made it |
+| `system` | File-read hydration (a file the user just opened) | No | The bytes are already on disk and in the browser — broadcasting would fire a phantom "agent edited document" toast and a bogus undo entry on a plain file-open |
+
+Without this filter you'd get two failure modes: an **echo loop** (the browser's edit bounces back and re-applies) and **false attribution** (opening a file looks like an agent edited it). The tag travels end-to-end — the MCP-side `MutationSource`, the bridge envelope, and the studio-side `MutationSource` are the same three strings, so no translation happens between processes.
+
+It also pairs with **~copy-on-write-doc**: any code that mutates a document builds a NEW document object before calling `DocumentStore.set`, never mutating the stored object in place. That guarantees the bridge — a concurrent reader broadcasting to the browser — can never observe a half-mutated document mid-update.
+
+## Toast attribution and Cmd-Z
+
+When an `llm:mutation` lands and matches the file you're viewing, the studio applies it and shows a bottom-right toast: *"agent edited document (`<tool>`) — Cmd-Z to undo"*. Because `applyMutation` snapshotted before replacing, **Cmd-Z returns the prior state** — an agent's edit is just another entry in your undo history. The agent and you share one timeline.
+
+That shared, attributable, undoable timeline is the whole point. The next note ties it into a complete workflow.

package/university/content/notes/N-atel-801-studio-app.md

@@ -0,0 +1,72 @@
+---
+id: N-atel-801-studio-app
+title: '`atelier studio` — the local-first editor'
+type: note
+track: ATEL-801
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-801
+  - studio
+  - cli
+difficulty: advanced
+estimatedMinutes: 5
+prerequisites:
+  - N-atel-201-mcp-overview
+summary: What `atelier studio` launches — a Vite-backed browser editor bound to 127.0.0.1, the welcome.atelier scaffold on an empty directory, the sidebar file list + "+ New", and the autosave coordinator whose flush-on-switch prevents .atelier corruption. Flags — --port, --no-open.
+---
+
+## What the command does
+
+`atelier studio [file]` spins up a local Vite dev server, writes a tiny entry shim into a temp directory that imports the browser client (`bootStudioApp`), and opens your browser. The client is a real, typechecked TypeScript module — `src/web/inline-app.ts` — not a string. (It used to be a ~700-LOC template-literal string with no typecheck, no lint, no tests; two real bugs hid there precisely because the compiler never saw it. More on both below.)
+
+The server reads and writes `.atelier` files from your current working directory. There is no project file, no auth token, no cloud round-trip. You point it at a folder and edit.
+
+```
+atelier studio                          → browse all .atelier files in CWD
+atelier studio my-animation.atelier     → open a specific file
+atelier studio --port 8080              → custom port (default 4321)
+atelier studio --no-open                → don't auto-open the browser
+```
+
+Those are the flags the command actually registers: `-p, --port <number>` and `--no-open`. Nothing else.
+
+## ^localhost-only
+
+The server binds explicitly to `127.0.0.1` — not the string `"localhost"`. Vite's default already resolves to loopback, but pinning the literal IP makes the invariant intentional and auditable, and it defeats any future change in Vite's defaults. The dev server cannot be reached from another machine on the network.
+
+This matters because the studio exposes mutating endpoints (`POST /api/file` writes `.atelier` files into your CWD) and two WebSocket endpoints (`/bridge` and `/mcp`). Two layers protect them:
+
+1. **The loopback bind** — the primary protection. Off-machine traffic never arrives.
+2. **An Origin check** on every mutating REST request and on every WS upgrade. Without it, any browser tab on any site could `fetch('http://localhost:4321/api/file', { method: 'POST', ... })` and write files into your project. (The WS Origin check has a subtlety covered in the live-bridge note.)
+
+## The welcome scaffold
+
+Run `atelier studio` in an empty directory and you don't land on a dead-end empty-state. If CWD contains zero `.atelier` files, the command copies the bundled `welcome.atelier` template into the folder so you open onto something real. It skips files that already exist, so re-running never overwrites your work.
+
+The welcome scaffold ships a placeholder layer whose **id is `background`** — a specific id contract, not a fuzzy description. The first image you drop replaces that layer in place (see the editing-surface note). The scaffold is a 1080×1080 social-square so you start at the most common authoring size.
+
+## The sidebar and "+ New"
+
+The left sidebar lists every `.atelier` file under CWD (recursively, grouped by folder), fetched from `/api/files`. Click an entry to load it. The `+ New` button prompts for a name, writes a minimal-but-non-empty starter document (one centered text layer on a 1080×1080 canvas so the canvas isn't a confusing void), refreshes the list, and selects the new file. A "new file" is just a `POST /api/file` of a fresh starter doc followed by a list refresh — there's no special server-side create path.
+
+## Autosave and the save-race that corrupted files
+
+The studio autosaves on every document change with an **800ms debounce**. The status bar flips to "saving…" the instant you edit, then "✓ saved" once the write lands (with a click-to-retry affordance if the write fails).
+
+The debounce hides a bug that was real and nasty (`#cli-studio` autosave corruption):
+
+> Edit file A → switch to file B within the 800ms window. The pending timer closed over A's *doc* but read the GLOBAL current file at fire time — which by then was B — so A's bytes were written to B's path. Real `.atelier` corruption.
+
+The fix is twofold, and both halves matter:
+
+1. **Capture the target path AND serialized bytes in the timer closure.** A fired timer always writes the bytes it was given to the file it was scheduled for — never whatever the "current" file later becomes.
+2. **Flush the pending save before switching files.** `loadFile` calls `flushPendingSave()` at its very top, writing any in-flight edit to its OWN path, then clears the timer. No edit is dropped and no cross-file write can occur.
+
+This logic is extracted into a real, unit-testable class — `SaveCoordinator` (`schedule`, `flushPending`, `cancel`) — so the save-race can be reasoned about in isolation. The inline browser app embeds the **same manual debounce pattern** (it does not import the class); the path/bytes capture and the flush-on-switch are preserved verbatim so there's exactly one behavior to trust.
+
+## What you've got after boot
+
+A browser window bound to loopback, a file sidebar, an editing canvas, autosave you can trust across file switches, and — quietly — a WebSocket bridge already connected and waiting for an agent. The next note covers what you can do on the canvas; the one after covers the agent.

package/university/content/notes/N-atel-801-symbiotic-loop.md

@@ -0,0 +1,56 @@
+---
+id: N-atel-801-symbiotic-loop
+title: The symbiotic loop — ingest, compose, co-edit, export
+type: note
+track: ATEL-801
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-801
+  - workflow
+  - import
+  - vision
+difficulty: advanced
+estimatedMinutes: 6
+prerequisites:
+  - N-atel-201-mcp-overview
+summary: The whole vision in one workflow — an agent runs an external generator in chat, atelier_import_images brings the results into the open doc, the human watches them appear live and keeps or undoes them, recipes and overlays compose the set, and atelier carousel exports it. Atelier owns no generation; it ingests, composes, and lets the human and agent co-edit one document.
+---
+
+## Atelier owns no generation
+
+This is the thesis of the whole track: **Atelier does not generate images, video, audio, or text.** It has no diffusion model, no text-to-image tool, no in-process generator. What it owns is the part that's hard and durable — a declarative document model, a renderer, a recipe/overlay composition layer, and a live editing loop shared between a human and an agent.
+
+Generation lives outside Atelier, in whatever tool the agent chooses to shell out to. Atelier's job begins when the bytes exist: it **ingests** them, **composes** them, and lets you and the agent **co-edit** the result.
+
+## The loop, end to end
+
+Picture a single chat session with the studio open in your browser:
+
+1. **The agent generates — outside Atelier.** You ask for a set of images. The agent runs an external generator from chat — for example a Higgsfield CLI — and writes the results to a folder. None of this touches Atelier; it's the agent driving a separate tool.
+
+2. **`atelier_import_images` ingests.** The agent calls the import tool. Each image becomes an ImageVisual layer with a matching `doc.assets` entry, added to the open document via a source-tagged-`llm` mutation. (Like every document-mutating tool, import builds a new document before calling `DocumentStore.set` — ~copy-on-write-doc — so the bridge never reads a half-built doc.)
+
+3. **You watch them appear — live.** Because the mutation is `source: "llm"`, the bridge broadcasts it. The layers materialize on your canvas as the agent imports them, each with a toast: *"agent edited document — Cmd-Z to undo"*. You're not waiting for a render-and-refresh cycle; you're watching the document fill in real time.
+
+4. **You keep or undo — per edit.** This is the symbiosis. A generated image that lands wrong? Cmd-Z, and it's gone — the agent's import was just an undo entry. The ones you like, you keep. You're curating the agent's output as it arrives, not after a batch finishes.
+
+5. **Recipes and overlays compose.** Apply a recipe to lay out the kept images; add a handle and page-number via the overlay namespace. The layer-tag isolation invariant (ATEL-301) means re-running a recipe drops only its own tagged layers — your imported images and any manual tweaks survive. You and the agent can both restyle without erasing each other's work.
+
+6. **`atelier carousel` exports the set.** The composed, multi-page result exports as a carousel — the page-number overlay threads `currentIndex` / `totalCount` per page during the batch.
+
+## Why both editors at one canvas
+
+The agent is good at the mechanical breadth — running the generator, importing a dozen results, applying a recipe across all of them, threading per-page overlays. You're good at the judgment — *that* crop, *not* that one, nudge the handle two pixels. The live bridge and the source-tagged-mutation aspect exist so neither steps on the other:
+
+- Every change is **attributed** (`human` vs `llm`) so the UI never lies about who did what.
+- Every change is **undoable** from your seat, so the agent never makes an edit you can't take back.
+- Every change flows through **one document store**, so there's a single source of truth — no merge, no divergence, last-write-wins.
+
+## The shape of the thing
+
+Atelier is not a generator with an editor bolted on. It's a **composition surface** where a human and an agent edit the same document at the same time, with generation pushed to the edges. The agent brings breadth and the external tools; you bring taste and the veto; the document — declarative, rendered, source-tagged — is the contract between you.
+
+That closes ATEL-801. You now understand `atelier studio` from the loopback bind up through the live bridge, and why the whole stack is built so an agent and a human can sit at one canvas without getting in each other's way.

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

@@ -0,0 +1,21 @@
+id: LP-atel-001
+title: 'ATEL-001: Hello Atelier'
+description: Orientation track. What Atelier is, how to install it, how to launch the studio, and how to render a first animation from a hand-written `.atelier` document. ~12 minutes.
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-001
+  - orientation
+ordered: true
+steps:
+  - content: N-atel-001-what-is-atelier
+    required: true
+  - content: N-atel-001-install-and-launch
+    required: true
+  - content: N-atel-001-first-render
+    required: true
+  - content: Q-atel-001-orientation
+    required: true
+    passRequired: true

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

@@ -0,0 +1,22 @@
+id: LP-atel-101
+title: 'ATEL-101: Document Model Fundamentals'
+description: The vocabulary every Atelier user needs. The `.atelier` format, layer anatomy, states/deltas/resolveFrame, easings. After this track you can read any Atelier document and predict what it renders. ~18 minutes.
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-101
+ordered: true
+steps:
+  - content: N-atel-101-the-atelier-format
+    required: true
+  - content: N-atel-101-layers
+    required: true
+  - content: N-atel-101-states-and-deltas
+    required: true
+  - content: N-atel-101-easings
+    required: true
+  - content: Q-atel-101-document-model
+    required: true
+    passRequired: true

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

@@ -0,0 +1,23 @@
+id: LP-atel-201
+title: 'ATEL-201: Authoring via MCP'
+description: How an AI agent (or any MCP scripter) builds, edits, and inspects Atelier documents through the 51-tool surface. Covers the single-store invariant, the 16 tool groups, common authoring patterns, and the four most common agent mistakes. ~20 minutes.
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-201
+  - mcp
+ordered: true
+steps:
+  - content: N-atel-201-mcp-overview
+    required: true
+  - content: N-atel-201-authoring-tools
+    required: true
+  - content: N-atel-201-visual-and-effects
+    required: true
+  - content: N-atel-201-patterns
+    required: true
+  - content: Q-atel-201-mcp-authoring
+    required: true
+    passRequired: true

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

@@ -0,0 +1,22 @@
+id: LP-atel-301
+title: 'ATEL-301: Visual System'
+description: The non-motion visual surface — shapes, text, images, video, effects, composition, and the overlay namespace. After this track you can compose any static scene in Atelier and understand how recipes and the layer-tag isolation invariant make overlays safe across re-runs. ~20 minutes.
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-301
+ordered: true
+steps:
+  - content: N-atel-301-shapes-and-text
+    required: true
+  - content: N-atel-301-images-and-video
+    required: true
+  - content: N-atel-301-effects
+    required: true
+  - content: N-atel-301-composition-and-overlays
+    required: true
+  - content: Q-atel-301-visual-system
+    required: true
+    passRequired: true

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.'