@a-company/atelier 0.36.0 → 0.38.0

package/university/content/notes/N-atel-101-easings.md

@@ -0,0 +1,97 @@
+---
+id: N-atel-101-easings
+title: Easings — linear, cubic-bezier, presets, spring, step
+type: note
+track: ATEL-101
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-101
+  - easings
+  - motion
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites:
+  - N-atel-101-states-and-deltas
+summary: Five easing kinds in Atelier. What each is, when to use it, and the one rule that prevents 90% of bad motion (don't use `linear` for organic movement).
+---
+
+## What an easing does
+
+An easing is a function `f(t: 0..1) → 0..1` that maps "fraction of time elapsed" to "fraction of value progress." `f(0) = 0`, `f(1) = 1`. What happens in between is the personality of the motion.
+
+Atelier supports five kinds:
+
+## 1. `linear`
+
+`f(t) = t`. Constant rate. Use for: progress bars, scrubbing, opacity crossfades where the perceived speed matters. **Do not use** for object motion — it looks robotic. Most "feels wrong" motion in the wild is `linear` doing the wrong job.
+
+```yaml
+easing: linear
+```
+
+## 2. Cubic-Bezier — `cubic-bezier(x1, y1, x2, y2)`
+
+The CSS-style four-control-point bezier. Full control over the shape. This is what every preset below desugars to.
+
+```yaml
+easing: cubic-bezier(0.4, 0.0, 0.2, 1.0)    # Material "standard"
+```
+
+If you've used CSS transitions, this is the same function.
+
+## 3. Ease presets
+
+Named shortcuts to common bezier curves. Use these instead of memorizing coefficients.
+
+| Preset | Bezier | Use for |
+|---|---|---|
+| `ease-in` | `(0.4, 0, 1, 1)` | Object accelerating off-screen |
+| `ease-out` | `(0, 0, 0.2, 1)` | Object decelerating on entrance (most UI entrance animation) |
+| `ease-in-out` | `(0.4, 0, 0.2, 1)` | Crossfades, value-to-value transitions where both endpoints are visible |
+| `ease` | `(0.25, 0.1, 0.25, 1)` | The CSS default — generic "feels OK" |
+
+Default for most UI motion: `ease-out` for entrances, `ease-in` for exits.
+
+## 4. Spring physics — `spring({ stiffness, damping, mass? })`
+
+Physics-based. Produces overshoot and oscillation that no bezier can match. Use for: anything that should feel tactile — toggles, drag-release, dismissals.
+
+```yaml
+easing:
+  type: spring
+  stiffness: 170
+  damping: 20
+  mass: 1
+```
+
+Stiffness controls how aggressively the spring pulls toward the target. Damping controls how quickly oscillation dies out. Atelier solves the spring numerically per-frame; the same `startFrame`–`endFrame` window still applies (the spring is clipped at `endFrame` and held at the resolved value after).
+
+When in doubt: `stiffness: 170, damping: 26` for a clean snap; `stiffness: 100, damping: 10` for visible oscillation.
+
+## 5. Step — `step(count)` or `step(count, position)`
+
+Discrete jumps. `step(4)` produces four equal jumps from `from` to `to`. Use for: spritesheet frame indexing (jump through frames at 12fps inside a 60fps composition), digital-readout counters, deliberate stop-motion feel.
+
+```yaml
+easing:
+  type: step
+  count: 4
+  position: start    # 'start' | 'end' | 'jump-none' | 'jump-both'
+```
+
+## The rule that prevents most bad motion
+
+> If a real physical object would do it, use spring or ease-out.
+> If a UI element is reporting progress, use linear.
+> Almost nothing else should be linear.
+
+Easings are why motion feels "designed" or "wrong." The engine doesn't care which you pick — the renderer interpolates whatever `f(t)` returns. But your viewer does care, every time.
+
+## Inspecting an easing
+
+The studio's easing-curve-editor (in PropertyPanel when you select a delta) shows the bezier curve, lets you drag control points, and previews the shape against the timeline. For springs, it samples the solver and plots the actual oscillation. There is no "easings preview file" — every delta you author can be inspected and tuned in place.
+
+That closes ATEL-101. You now know enough to read any `.atelier` document and predict what it will render. ATEL-201 covers the MCP tool surface — how an agent builds documents like this without ever touching YAML.

package/university/content/notes/N-atel-101-layers.md

@@ -0,0 +1,106 @@
+---
+id: N-atel-101-layers
+title: Layer anatomy
+type: note
+track: ATEL-101
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-101
+  - layers
+  - format
+difficulty: beginner
+estimatedMinutes: 5
+prerequisites:
+  - N-atel-101-the-atelier-format
+summary: Every field on the `Layer` type, what it does, what's required vs optional, and which fields are animatable through deltas.
+---
+
+## The minimum layer
+
+```yaml
+- id: title
+  visual:
+    type: text
+    content: Hello
+    style:
+      fontFamily: Inter, system-ui, sans-serif
+      fontSize: 48
+  frame:
+    x: 400
+    y: 300
+  bounds:
+    width: 600
+    height: 80
+```
+
+Four required fields: `id`, `visual`, `frame`, `bounds`. The rest are optional and default to sensible values.
+
+## The six visual types
+
+The `visual` field is a discriminated union on `type`:
+
+| `type` | Renders | Required sub-fields |
+|---|---|---|
+| `shape` | A geometric shape — rect, ellipse, polygon, path | `shape`, optional `fill` and `stroke` |
+| `text` | A string with typography | `content`, `style` (fontFamily required) |
+| `image` | A static image asset | `assetId` (and optional `src`, `sourceRect`, `spritesheet`) |
+| `video` | A video clip | `assetId`, optional `sourceOffset`, `sourceEnd`, `playbackRate` |
+| `group` | A container for child layers (via `parentId`) | none — just a container |
+| `ref` | A reference to another `.atelier` file rendered as a sub-document | `src`, optional `state` and `frame` |
+
+## Position, size, and anchor
+
+- **`frame: { x, y }`** — position of the anchor point in canvas pixels.
+- **`bounds: { width, height }`** — the layer's box.
+- **`anchorPoint: { x, y }`** — normalized 0–1 coordinate inside the bounds that `frame` positions. `{x: 0.5, y: 0.5}` centers the layer on `frame`. `{x: 0, y: 0}` puts the top-left at `frame`. Default is `{x: 0, y: 0}`.
+
+The anchor also defines the pivot for `rotation` and `scale`.
+
+## Animatable layer properties
+
+These can appear in deltas (`property: <name>`):
+
+| Property | Type | Default |
+|---|---|---|
+| `opacity` | number 0–1 | 1 |
+| `rotation` | degrees | 0 |
+| `scale` | `{ x, y }` | `{1, 1}` |
+| `frame.x`, `frame.y` | number | as authored |
+| `bounds.width`, `bounds.height` | number | as authored |
+| `tint.amount` | 0–1 (color tint strength) | 0 |
+| Any color, gradient stop, stroke width, shadow blur on the visual or its style | various | — |
+
+The full animatable list is 27 properties. The schema enforces that a delta's `property` path is reachable on the named layer's visual.
+
+## Non-animatable structural fields
+
+| Field | Purpose |
+|---|---|
+| `id` | Unique identifier |
+| `tags` | Namespace markers (used by pipelines for layer-tag isolation) |
+| `description` | Human-readable note, kept out of render |
+| `parentId` | Parents this layer to another for transform inheritance |
+| `visible` | Hard on/off (rendered if `true` or absent) |
+| `blendMode` | Canvas composite operation |
+| `clipPath` | A Shape that restricts rendering to its interior |
+| `motionPath` | A path the layer follows over time, with optional auto-rotate |
+| `interactions` | Event-driven trigger-action bindings (e.g. hover → state transition) |
+
+## Parent-child and transform inheritance
+
+Setting `parentId` on a layer makes its `frame`, `rotation`, and `scale` relative to the parent's transformed coordinate space. A `group` visual has no rendered output of its own — it exists purely to provide a parent transform. Use groups when you want to translate or rotate a cluster of layers as one unit.
+
+## Tags: the pipeline contract
+
+Tags are how the silence-trim, caption, and overlay pipelines find layers they own. Each pipeline writes a tag namespace:
+
+- `silence-trim` — clip layers produced by `atelier trim`
+- `caption`, `caption-word` — text layers produced by `atelier captions regenerate`
+- `overlay` — handle / page-number / recipe-driven decorative layers
+
+The invariant: re-running a pipeline drops only its own tagged layers and replaces them. Layers without that tag (user-authored, or owned by another pipeline) are never touched. This is what makes the human↔agent symbiotic loop safe (ATEL-501 covers this in depth).
+
+Next: states and deltas.

package/university/content/notes/N-atel-101-states-and-deltas.md

@@ -0,0 +1,94 @@
+---
+id: N-atel-101-states-and-deltas
+title: States, deltas, and `resolveFrame`
+type: note
+track: ATEL-101
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-101
+  - states
+  - deltas
+  - resolve-frame
+difficulty: beginner
+estimatedMinutes: 5
+prerequisites:
+  - N-atel-101-layers
+summary: A state is a named span of frames. A delta animates one property of one layer over a sub-range of that span. `resolveFrame(doc, stateName, frame)` is the function the renderer calls — knowing its shape demystifies everything else.
+---
+
+## A state is a named span
+
+```yaml
+states:
+  default:
+    duration: 60
+    deltas:
+      - layer: title
+        property: opacity
+        from: 0
+        to: 1
+        startFrame: 0
+        endFrame: 30
+        easing: ease-out
+```
+
+`default` is the state name. `duration: 60` means this state runs for 60 frames (one second at 60fps). Frames are 0-indexed, so this state spans `0..59` inclusive. The renderer plays through the state and either loops, transitions to another state, or stops, depending on configuration.
+
+A document always has at least one state. Most documents have only one. Multi-state documents are the foundation of interactive UI motion (`hover`, `active`, `pressed`) and segmented narratives.
+
+## A delta animates one property
+
+Every field on a delta exists for a reason:
+
+| Field | Meaning |
+|---|---|
+| `layer` | Which layer (by id) this delta animates |
+| `property` | Which animatable property (e.g. `opacity`, `frame.x`, `style.color`) |
+| `from` | Starting value at `startFrame` |
+| `to` | Ending value at `endFrame` |
+| `startFrame` | Frame within the state where this delta begins |
+| `endFrame` | Frame within the state where this delta ends |
+| `easing` | How the value interpolates between `from` and `to` |
+| `expression` | Optional override — a function of `t` (0..1) returning the interpolated value, for non-trivial animations |
+
+Outside `[startFrame, endFrame]`, the property holds its boundary value (clamped). Multiple deltas on the same `layer` + `property` are rejected by the schema's no-overlap gate — overlapping motion is almost always a bug; if you need composition, use two layers or a `group`.
+
+## `resolveFrame` is the whole engine in one function
+
+```ts
+const scene = resolveFrame(doc, stateName, frameNumber);
+// scene is { layers: ResolvedLayer[] } — every property concrete, no deltas
+```
+
+What it does, in order:
+
+1. Look up the state by name. If it doesn't exist, throw.
+2. For each layer in `doc.layers`, start with its authored values.
+3. For each delta in `state.deltas`:
+   - If `frameNumber < startFrame`, the layer's property stays at `from`.
+   - If `frameNumber > endFrame`, the layer's property stays at `to`.
+   - If between: compute `t = (frameNumber - startFrame) / (endFrame - startFrame)`, run `t` through the easing function (returning `t'`), then interpolate `from + (to - from) * t'`.
+4. Apply parent transforms (if a layer has `parentId`), motion paths, clip paths, tints.
+5. Return the resolved scene — every layer now has concrete property values ready for the renderer.
+
+The renderer (canvas, SVG export, Lottie export, video exporter) all consume the same `ResolvedLayer[]` output. Adding a new renderer is "consume one frame at a time"; adding a new animatable property is "add to the interpolation switch."
+
+## Hierarchical states and transitions
+
+States can declare a `parent` (extending another state's deltas) and a `transitions` block (named transitions from one state to another with their own duration, easing, and target deltas). This is the foundation of interactive UI motion — `hover` extends `default` with extra deltas, `pressed` transitions from `hover` with a 200ms ease-out. Full coverage in ATEL-401 (State Machines & Motion).
+
+## Inspecting a frame from the CLI
+
+```bash
+atelier preview hello.atelier --frame 15
+atelier preview hello.atelier --frame 15 --state hover
+```
+
+The output is the same `ResolvedLayer[]` array `resolveFrame` produces — perfect for debugging "what does the engine actually think this scene looks like at frame N?"
+
+For multi-frame inspection, `atelier_batch_preview` (MCP) or `atelier diff_frames` (CLI) compare two frames side by side.
+
+Next: easings.

package/university/content/notes/N-atel-101-the-atelier-format.md

@@ -0,0 +1,72 @@
+---
+id: N-atel-101-the-atelier-format
+title: The `.atelier` document format
+type: note
+track: ATEL-101
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-101
+  - format
+  - schema
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites:
+  - N-atel-001-first-render
+summary: The top-level shape of an `.atelier` YAML document — canvas, layers, states, assets, variables, presets, templates. Every field exists for one reason, named for what it means.
+---
+
+## The five required parts
+
+Every `.atelier` document is YAML with five mandatory top-level keys:
+
+```yaml
+name: My Animation                    # human-readable label
+canvas:                               # global render context
+  width: 800
+  height: 600
+  fps: 60
+  background: "#0F1115"               # optional, defaults to transparent
+layers: [ ... ]                       # ordered array of visual elements
+states:                               # named keyframes (always at least one)
+  default:
+    duration: 60                      # in frames
+    deltas: [ ... ]
+```
+
+That is the minimum. Validators accept it. The renderer can resolve any frame in the `default` state.
+
+## The optional parts
+
+Any of these can be absent. Add them when you need them.
+
+| Key | What it holds | When you need it |
+|---|---|---|
+| `assets` | External resources (images, videos, audio) referenced by `assetId` from layers | The moment you add an image or video layer |
+| `variables` | Named values referenced by `${name}` in templates and expression-driven deltas | When you want to parametrize a document or template |
+| `presets` | Reusable delta bundles applied by name | When the same animation pattern repeats across layers |
+| `templates` | Reusable layer subtrees instantiated by name with variable substitution | Carousels, lower-thirds, repeating motifs |
+| `audio` | Audio track + sync metadata | Video projects with sound |
+| `meta` | Free-form metadata (author, tags, source notes) | Anything you want a downstream tool to read |
+
+## The order of keys is not meaningful (to the engine)
+
+YAML is unordered for objects. The schema doesn't care whether `states` comes before `layers`. Conventionally we write them top-down — `name`, `canvas`, `assets`, `variables`, `presets`, `templates`, `layers`, `states`, `audio`, `meta` — because that order roughly matches "global setup → reusable bits → scene → motion → output."
+
+## The order of `layers` IS meaningful
+
+Layers render back-to-front. Index 0 is drawn first (background); the last layer is on top. This is also the order the layer panel shows them in the studio (top of the list = top of the stack, matching most design-tool conventions — the array is rendered bottom-up for display).
+
+## Layer IDs and references
+
+Every layer needs an `id` that is unique within the document. Deltas reference layers by id (`layer: title`). Parent-child relationships use `parentId`. Templates reference instance ids. The schema enforces uniqueness and rejects dangling references at validate time — you don't have to track them by hand.
+
+Conventionally, layer ids are kebab-case (`title`, `subtitle`, `clip-trim-1`, `caption-word-7`). Pipeline-generated layers carry a tag namespace prefix in the id: `silence-trim-N`, `caption-N`, `caption-word-N`, `overlay-N`. The tags drive the layer-tag isolation invariant (ATEL-501).
+
+## Reading order for the rest of ATEL-101
+
+1. **Layers** — anatomy of a single layer: visual, frame, bounds, anchor, opacity, rotation, scale, parent, visible, motion path, clip path, blend mode, shadow, tint, interactions
+2. **States and deltas** — what a state is, what a delta is, how `resolveFrame(doc, stateName, frame)` produces a renderable scene
+3. **Easings** — linear / cubic-bezier / ease presets / spring / step; the math you don't have to remember but should recognize

package/university/content/notes/N-atel-201-authoring-tools.md

@@ -0,0 +1,141 @@
+---
+id: N-atel-201-authoring-tools
+title: Authoring tools — document, layer, state, delta
+type: note
+track: ATEL-201
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-201
+  - mcp
+  - authoring
+difficulty: intermediate
+estimatedMinutes: 6
+prerequisites:
+  - N-atel-201-mcp-overview
+summary: The tools you reach for to build animations. Document lifecycle, layer composition, state machines, delta authoring. Annotated by which to call when.
+---
+
+## Document lifecycle
+
+```
+atelier_create        — make a new document with name + canvas
+atelier_load          — load a .atelier file from disk by path
+atelier_list          — list .atelier files in CWD
+atelier_info          — return name + canvas + layer count + state count
+atelier_validate      — schema-validate the current doc; returns errors with paths
+atelier_preview       — resolve one frame and return ResolvedLayer[]
+atelier_batch_preview — resolve multiple frames in one call (for thumbnail rows)
+atelier_diff_frames   — compare two resolved frames; return property-level diffs
+atelier_profile       — measure resolveFrame latency per state
+atelier_complexity    — count layers, deltas, refs, max nesting; flag perf risks
+```
+
+**When to use which:**
+
+- Starting from scratch: `atelier_create({ name, canvas: { width, height, fps }})`. Returns a minimal doc with one empty `default` state.
+- Resuming on an existing file: `atelier_load({ path })`. The store now holds that doc; subsequent calls operate on it.
+- Sanity-checking before you ship: `atelier_validate` then `atelier_complexity` — the first catches schema issues, the second flags renderer perf risks (1000+ layers, 10+ levels of group nesting, etc.).
+- Visual debugging: `atelier_preview({ frame: 30 })` returns the same `ResolvedLayer[]` the renderer consumes. Compare against `atelier_diff_frames({ from: 29, to: 31 })` to find what changes.
+
+## Layer composition
+
+```
+atelier_add_layer    — add a layer with visual + frame + bounds
+atelier_edit_layer   — edit non-visual layer properties (id, tags, parentId, etc.)
+atelier_remove_layer — remove a layer by id (and any deltas referencing it)
+atelier_reorder      — change layer z-order
+atelier_list_layers  — list all layer ids + types
+atelier_edit_visual  — replace or patch the visual block (shape→text, fill, etc.)
+```
+
+**Pattern:** build all layers first, then animate. Adding layers triggers immediate validation; adding deltas requires the target layer to exist. Reverse order works but emits more errors.
+
+**`atelier_edit_visual` is the underrated one.** It's the single tool for "I want this rect to become a text layer" or "change this image's `assetId`." Most edit-flow agents use this far more than the dedicated `atelier_set_*` family.
+
+## State machines
+
+```
+atelier_add_state           — name a new state with duration (frames)
+atelier_edit_state          — change duration, parent state, transitions
+atelier_remove_state        — remove a state (rejects if it's the only one)
+atelier_list_states         — list state names + durations + parent chain
+atelier_set_state_parent    — make a state inherit deltas from another
+atelier_configure_transition — define transition from state A→B with easing
+```
+
+**State machines are the foundation of interactive motion.** A `default` state shows the resting layout. `hover` extends `default` (via `set_state_parent`) with extra deltas. `pressed` transitions from `hover` with a 200ms ease-out (via `configure_transition`). Three states, total complexity stays low, the interactive feel is right.
+
+For non-interactive animations: one `default` state is fine. State-machine complexity is opt-in.
+
+## Delta authoring
+
+```
+atelier_add_delta    — animate one property of one layer
+atelier_edit_delta   — change from/to/easing/range of an existing delta
+atelier_remove_delta — remove a delta
+```
+
+`atelier_add_delta` takes:
+
+```ts
+{
+  state: "default",
+  layer: "title",
+  property: "opacity",        // or "frame.x", "style.color", "scale.x", ...
+  from: 0,
+  to: 1,
+  startFrame: 0,
+  endFrame: 30,
+  easing: "ease-out"          // or cubic-bezier(...), spring({...}), step(...)
+}
+```
+
+The **no-overlap gate** rejects two deltas on the same `layer` + `property` whose `[startFrame, endFrame]` ranges overlap. If you need composed motion (e.g. wobble overlaid on a slide), use two layers or a `group`. The error message names both deltas; the fix is obvious.
+
+**Easing as an object, not just a string.** The string form (`"ease-out"`) is the preset shortcut; the object form (`{ type: "spring", stiffness: 170, damping: 26 }`) is the full surface. Use the object form when you want spring physics or a custom cubic-bezier with specific control points.
+
+## A complete worked example
+
+Building "fade in title, slide subtitle from below, hold for 2 seconds" from zero:
+
+```ts
+const { documentId } = await atelier_create({
+  name: "Intro", canvas: { width: 1920, height: 1080, fps: 60 }
+});
+
+await atelier_add_layer({ documentId, layer: {
+  id: "title", visual: { type: "text", content: "Atelier",
+    style: { fontFamily: "Inter", fontSize: 120, color: "#F5F5F7" }},
+  frame: { x: 960, y: 480 }, bounds: { width: 1200, height: 160 },
+  anchorPoint: { x: 0.5, y: 0.5 }, opacity: 0
+}});
+
+await atelier_add_layer({ documentId, layer: {
+  id: "subtitle", visual: { type: "text", content: "AI-native animation",
+    style: { fontFamily: "Inter", fontSize: 40, color: "#9CA3AF" }},
+  frame: { x: 960, y: 580 }, bounds: { width: 1200, height: 60 },
+  anchorPoint: { x: 0.5, y: 0.5 }, opacity: 0
+}});
+
+await atelier_edit_state({ documentId, state: "default", duration: 180 });
+
+await atelier_add_delta({ documentId, state: "default", layer: "title",
+  property: "opacity", from: 0, to: 1, startFrame: 0, endFrame: 30,
+  easing: "ease-out" });
+
+await atelier_add_delta({ documentId, state: "default", layer: "subtitle",
+  property: "opacity", from: 0, to: 1, startFrame: 20, endFrame: 50,
+  easing: "ease-out" });
+
+await atelier_add_delta({ documentId, state: "default", layer: "subtitle",
+  property: "frame.y", from: 680, to: 580, startFrame: 20, endFrame: 50,
+  easing: { type: "spring", stiffness: 120, damping: 22 } });
+
+await atelier_validate({ documentId });
+await atelier_preview({ documentId, frame: 40 }); // inspect mid-motion
+```
+
+Eight calls. Two layers, three deltas, one validate, one preview. The agent never touched YAML.

package/university/content/notes/N-atel-201-mcp-overview.md

@@ -0,0 +1,86 @@
+---
+id: N-atel-201-mcp-overview
+title: MCP in the Atelier context
+type: note
+track: ATEL-201
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-201
+  - mcp
+  - architecture
+difficulty: intermediate
+estimatedMinutes: 4
+prerequisites:
+  - N-atel-101-easings
+summary: What the `atelier-mcp` server actually is, why every authoring tool maps to a single mutation on a single document store, and how the LLM↔Studio live-mutation bridge works without conflict.
+---
+
+## What `atelier-mcp` is
+
+`atelier-mcp` is a Model Context Protocol server. An AI agent connects to it (via stdio in Claude Desktop, or WebSocket when paired with `atelier studio`) and gains 61 tools across 15 groups. Each tool is a typed function the agent calls; each call is a single mutation against a shared in-memory `DocumentStore`. The server doesn't talk to the LLM; it just exposes the mutation surface and lets the LLM drive.
+
+The boundary is intentional: the agent does the planning, the server does the validating. If the agent asks `atelier_add_delta` to animate a property that doesn't exist on a layer, the Zod schema rejects the call with an AI-readable error message. The agent reads the error, fixes the request, retries. No invalid document ever reaches the renderer.
+
+## The single-store invariant
+
+There is **one** `DocumentStore` per project session. Every client — the MCP server's tool handlers, the `atelier studio` browser canvas, the WebSocket bridge between them — reads and writes the same store.
+
+This is why the live LLM-mutation feature works at all. When an agent calls `atelier_add_layer`, the store updates, fires `onChange`, and the bridge broadcasts the mutation to any connected Studio. The Studio applies the mutation via `applyMutation(op)` (with a suppress-notify flag for one tick so the change doesn't echo back as a human edit), re-renders the canvas, and shows a toast: *"agent added layer `title`"* with an Undo affordance.
+
+Conflict policy in v1: **last-write-wins**. Human edits during agent mutation overwrite the agent's pending change. No CRDT, no operational transform — Atelier is a single-author tool with an AI collaborator, not a real-time multiplayer canvas. Every op is tagged `source: "human" | "llm"` so the UI can attribute changes.
+
+## Tool conventions
+
+Every MCP tool follows the same conventions. Recognize the pattern once and you can read any tool's signature:
+
+| Convention | Example |
+|---|---|
+| `atelier_<verb>_<noun>` naming | `atelier_add_layer`, `atelier_edit_delta`, `atelier_remove_state` |
+| First argument is always `documentId` (or implicit if the server has a current doc) | `atelier_add_layer({ documentId, ... })` |
+| Mutations return the **updated document** (not just the changed fragment) | An agent doesn't have to re-fetch after every call |
+| Inspect tools return only what was asked for | `atelier_preview` returns resolved layers, not the whole doc |
+| Validation runs after every mutation; tool calls fail fast with field-level errors | Errors include the offending path: `layers[0].visual.style.fontSize: expected number` |
+| Tools that need a frame number accept either an absolute frame or `{ state, frame }` | Clarity over cleverness |
+
+## The 15 groups
+
+```
+document    — create, load, list, info, validate, preview, batch_preview,
+              profile, complexity, diff_frames, export, export_svg, export_lottie
+layer       — add, edit, remove, reorder, list, edit_visual
+state       — add, edit, remove, list, set_parent, configure_transition
+delta       — add, edit, remove
+visual      — set_shape, set_fill, set_stroke, set_shadow, set_blend_mode,
+              set_clip_path, set_motion_path, set_tint
+asset       — add, list, remove
+variable    — add, list, remove, find
+preset      — define, list, apply
+template    — instantiate
+interaction — add, list, remove
+ref         — set_ref, resolve_refs
+audio       — set_audio
+overlay     — add_handle, add_page_number   (Phase 1.5)
+recipe      — recipe_list, recipe_get, recipe_validate, recipe_save, recipe_apply
+import      — import_images
+```
+
+The next three notes cover the high-frequency tools — what to call and when. The full reference is `docs/mcp-reference.md` in the atelier repo (and at `https://atelier.dev/mcp`, when that lands).
+
+## Configuring the server
+
+```json
+{
+  "mcpServers": {
+    "atelier": {
+      "command": "atelier-mcp"
+    }
+  }
+}
+```
+
+That's it. No auth tokens. No project path — the server scans CWD for `.atelier` files and loads them lazily on `atelier_load`. To bind the server to a specific project directory, set `ATELIER_PROJECT_ROOT=/path/to/project` in the env.
+
+For the live Studio bridge, run `atelier studio` first; the MCP server detects the bridge's WebSocket endpoint and connects automatically. No config needed.