@a-company/atelier 0.36.0 → 0.38.0

package/templates/workspace/SETUP.md

@@ -0,0 +1,127 @@
+# Workspace setup runbook
+
+> **For the agent team.** When the creator asks to "get set up" (or "run the
+> setup checklist", "am I ready to render", "check my environment"), work
+> through this file top to bottom. For each item: run the **Check**, judge it
+> against **Pass**, and if it fails, walk the creator through the **Fix** — then
+> re-run the Check to confirm. Do NOT skip steps silently. End with the
+> **Report** at the bottom: a ✓/✗/– line per item plus the single next action.
+>
+> Run the checks with the `Bash` tool. Surface command output verbatim when an
+> item fails — don't paraphrase errors. Detect the OS first (`uname`) so you
+> give the right install command (the Fixes below show macOS/Homebrew; on Linux
+> use the distro package manager, on Windows use winget/scoop or the installer
+> links).
+
+---
+
+## Required — the creator cannot render without these
+
+### 1. Claude Code
+- **Check:** You're running inside it, so this passes by definition.
+- **Pass:** This session exists.
+- **Fix:** n/a.
+
+### 2. Node.js 22+
+- **Check:** `node --version`
+- **Pass:** major version ≥ 22. (Everything below runs through `npx`, which needs
+  Node — so check this first.)
+- **Fix:** Install Node 22 LTS from <https://nodejs.org> (or `nvm install 22 && nvm use 22`).
+  Re-run the Check.
+
+### 3. Hyperframes + the render toolchain  ← the important one
+Hyperframes is the render engine (Iris drives it via `npx hyperframes preview` /
+`render`). There is **no manual install** — `npx` auto-fetches the published
+`hyperframes` package on first run. It ships its own dependency checker; use it
+as the authoritative check for the whole render toolchain:
+
+- **Check:** `npx --yes hyperframes doctor`
+- **Pass:** read the `✓ / ✗` lines it prints. You want `✓` on **FFmpeg**,
+  **FFprobe**, and **Chrome** (the three render-critical deps), plus Node and
+  adequate Disk/Memory.
+  > ⚠️ **`doctor` exits 0 even when a check fails.** Do NOT trust the exit code —
+  > judge by the `✗` markers in the output. Surface any `✗` line verbatim.
+- **Fix**, per failing line:
+  - **FFmpeg / FFprobe ✗** → macOS `brew install ffmpeg` (ships both); Debian/Ubuntu
+    `sudo apt install ffmpeg`; Windows `winget install Gyan.FFmpeg`. Required for the
+    render → `.mp4`/`.mov`/`.webm` mux and all audio. Re-run `doctor`.
+  - **Chrome ✗** → `npx --yes hyperframes browser install` (Hyperframes renders by
+    driving headless Chrome). Re-run `doctor`.
+  - **Low Memory / Disk ⚠** → renders may fail or run slowly; have the creator free
+    resources. Not a hard blocker.
+  - **`npx hyperframes` errors entirely** → confirm step 2 passed and the first run
+    can reach the npm registry (a corporate proxy may need `npm config set proxy`).
+
+---
+
+## Optional — enhances the workflow, not required to render
+
+### 5. Whisper (transcription)
+- **Check:** `whisper-cli --help 2>/dev/null || whisper-cpp --help 2>/dev/null || echo MISSING`
+- **Pass:** either binary responds. (Only needed if the creator will drop raw
+  recordings into `projects/<name>/media/` for auto-transcription.)
+- **Fix:** macOS `brew install whisper-cpp`; otherwise build whisper.cpp from
+  <https://github.com/ggerganov/whisper.cpp>. Safe to skip until the first recording.
+
+### 6. Paradigm learning loop (cross-session memory)
+- **Check:** `ls ~/.paradigm/notebooks/quill ~/.paradigm/notebooks/lux ~/.paradigm/notebooks/iris 2>/dev/null || echo MISSING`
+- **Pass:** all three notebook dirs exist → the team accumulates learning across
+  sessions. If MISSING, the agents still work fully from their workspace shims;
+  they just don't persist learning between sessions.
+- **Fix:** Install the Paradigm plugin and the Atelier personas (Quill / Lux /
+  Iris) into `~/.paradigm/`. This is optional — only set it up if the creator
+  wants the agents to get smarter over time. Don't block setup on it.
+
+---
+
+## Workspace verification — is THIS workspace intact?
+
+### 7. Scaffold integrity
+- **Check:** confirm these exist (use `Glob`/`ls`):
+  `workspace.atelier`, `_brand/`, `_packs/`, `projects/`,
+  `.claude/agents/atelier-quill.md`, `atelier-lux.md`, `atelier-iris.md`,
+  `.paradigm/personas/_shared/cascade-merge.md`, `CLAUDE.md`.
+- **Pass:** all present.
+- **Fix:** re-run `atelier workspace` in this folder — it's idempotent and
+  refreshes scaffold files without touching authored brand artifacts.
+
+### 8. Brand artifacts authored (not placeholders)
+- **Check:** read `_brand/DESIGN.md`, `_brand/SCRIPT.md`, `_brand/STORYBOARD.md`
+  and `_brand/.atelier-brand.yaml`; look for remaining `TODO` markers or template
+  placeholder text.
+- **Pass:** the brand reflects the creator's real palette / typography / voice.
+- **Fix:** offer to have **@atelier-quill** (voice + design) and **@atelier-lux**
+  (visual patterns) interview the creator and fill these in. Placeholders are not
+  a hard failure — flag them and move on.
+
+### 9. Fonts staged (if the brand uses custom fonts)
+- **Check:** if `_brand/.atelier-brand.yaml` names non-system fonts, confirm the
+  files exist under `_assets/fonts/<family>/`.
+- **Pass:** every named custom font is present locally.
+- **Fix:** stage the font files into `_assets/fonts/<family>/`. This is the
+  font-staging pattern — Hyperframes' render step does NOT reliably load web-CDN
+  fonts, so brand fonts must be local or renders fall back to a generic sans.
+
+---
+
+## Report
+
+Summarize like this, then state the single next action:
+
+```
+Atelier setup check
+  ✓ Node.js 22+              v22.x
+  ✓ Hyperframes             0.6.x (npx)
+  ✓ ffmpeg                  present
+  – Whisper                 not installed (optional — needed for transcription)
+  – Paradigm learning loop  not installed (optional)
+  ✓ Workspace scaffold      intact
+  ⚠ Brand artifacts         still has TODO placeholders
+  ✓ Fonts                   n/a (system fonts only)
+
+Next: your brand still has placeholders — want @atelier-quill to draft your
+voice + @atelier-lux your visual patterns? Or jump straight to a first project.
+```
+
+Use ✓ pass, ✗ required-and-failing (must fix before render), ⚠ works-but-attention,
+– optional-and-absent.

package/templates/workspace/_brand/.atelier-brand.yaml

@@ -0,0 +1,34 @@
+# {{WORKSPACE_NAME}} — structured brand overlay
+#
+# Agents read this for fields the markdown doesn't structure cleanly.
+# DESIGN.md / SCRIPT.md / STORYBOARD.md are the source of truth for prose;
+# this overlay captures the things agents query as data (palette, fonts,
+# whitelists, etc).
+#
+# Cascade: project-tier `projects/<name>/.atelier-overlay.yaml` extends this
+# per `.paradigm/personas/_shared/cascade-merge.md` (lists extend, scalars
+# override, maps override-at-key).
+
+name: "{{WORKSPACE_NAME}}"
+
+voice:
+  register: TODO         # one short phrase, e.g. clinical-editorial
+  tone: TODO             # e.g. confident-not-cocky
+  exemplars: []          # quill mirrors these tonally
+  do: []                 # tonal moves to make
+  dont: []               # tonal moves to never make
+
+visual:
+  primary_palette: [paper, ink, accent]
+  typography:
+    display: Inter
+    body: Inter
+  treatment:
+    photos: TODO         # e.g. high-key, generous negative space
+    motion: TODO         # e.g. gentle ease-out, never bounce
+  aspect: 9:16           # default canvas aspect (1080:1920); override per project
+
+techniques_whitelist:
+  - TODO
+techniques_blacklist:
+  - TODO

package/templates/workspace/_brand/DESIGN.md

@@ -0,0 +1,56 @@
+# {{WORKSPACE_NAME}} — Brand Design
+
+> **Workspace-tier brand design.** This file describes the durable visual + tonal
+> brand identity for **every** project under this workspace. Project-tier
+> `projects/<name>/DESIGN.md` overrides + extends per the cascade rules
+> (`.paradigm/personas/_shared/cascade-merge.md`).
+
+## Audience
+
+<!-- Who is this brand FOR? Specifics, not generics. Replace this placeholder. -->
+TODO — who watches / reads / interacts with this brand?
+
+## Voice register
+
+<!-- The tonal posture. One short paragraph. Examples: "clinical-editorial,
+     confident-not-cocky" / "warm-conversational, never preachy" / etc. -->
+TODO — describe the voice register.
+
+## Visual register
+
+<!-- The visual posture. One short paragraph. Examples: "editorial generosity,
+     restrained palette, type-led" / "kinetic-bold with primary-color blocks" -->
+TODO — describe the visual register.
+
+## Palette
+
+<!-- Brand colors with semantic roles. Hex values. Lux reads these to make
+     palette decisions; Iris emits these as `--brand-palette-<role>` CSS vars
+     in every Hyperframes scaffold. -->
+- `paper` — `#FFFFFF` — primary background
+- `ink` — `#000000` — primary foreground / text
+- `accent` — `#FF6B35` — single accent color used sparingly
+
+## Typography
+
+<!-- Brand fonts with usage. Lux reads these for typography staging; Iris emits
+     these as `--brand-font-<usage>` CSS vars. Use Hyperframes-compatible
+     fonts when possible (see https://hyperframes.mintlify.app/docs/fonts). -->
+- `display` — Inter — large headlines, hero copy
+- `body` — Inter — captions, body text, secondary copy
+
+## Constraints
+
+<!-- Hard rules. Lux and Iris MUST respect these. Examples:
+     - never use stock photography
+     - aspect is portrait 9:16 unless explicitly requested otherwise
+     - no exclamation marks in any on-screen copy -->
+- TODO — list the brand hard rules.
+
+## Success criteria
+
+<!-- How do we know a finished video is "on brand"? Specific signals creator
+     uses to evaluate output. Examples:
+     - viewer can identify the brand from the first 1.5s without a logo
+     - palette restraint never exceeds 3 hues per frame -->
+- TODO — list signals of brand-correct output.

package/templates/workspace/_brand/SCRIPT.md

@@ -0,0 +1,41 @@
+# {{WORKSPACE_NAME}} — Brand Voice
+
+> **Workspace-tier voice exemplars + do/don't.** Quill reads this as the
+> default voice for every project. Project-tier `projects/<name>/SCRIPT.md`
+> overrides + extends per the cascade rules.
+
+## Voice exemplars
+
+<!-- Real phrases that exemplify the brand voice. Quill mirrors these tonally
+     when drafting. Concrete > abstract. Three to five is enough.
+     Replace these placeholders with actual brand-voice samples. -->
+- TODO — exemplar 1 (real phrase the brand would say)
+- TODO — exemplar 2
+- TODO — exemplar 3
+
+## Do
+
+<!-- Tonal moves the brand SHOULD make. -->
+- TODO — e.g. "lead with the metric, not the brag"
+- TODO — e.g. "end on the actionable beat, not the inspirational one"
+
+## Don't
+
+<!-- Tonal moves the brand should NEVER make. -->
+- TODO — e.g. "no exclamation marks"
+- TODO — e.g. "no hype adjectives (amazing, incredible, game-changing)"
+
+## Default structure
+
+<!-- The brand's default short-form structure. Quill uses this unless overridden.
+     Default is hook → story → proof → CTA — replace if the brand prefers
+     a different shape. -->
+- hook
+- story
+- proof
+- CTA
+
+## Sign-off
+
+<!-- The brand's canonical closing beat / tagline / sign-off. Optional. -->
+TODO — closing beat if the brand has one (otherwise delete this section).

package/templates/workspace/_brand/STORYBOARD.md

@@ -0,0 +1,33 @@
+# {{WORKSPACE_NAME}} — Brand Storyboard Patterns
+
+> **Workspace-tier visual patterns.** Lux reads this for recurring storyboard
+> primitives the brand favors. Project-tier `projects/<name>/STORYBOARD.md`
+> overrides + extends per the cascade rules.
+
+## Signature transitions
+
+<!-- Named transitions the brand uses. Lux selects from this whitelist when
+     deciding scene-to-scene transitions. Each entry: name + when-to-use. -->
+- TODO — e.g. "hard-cut: between distinct beats"
+- TODO — e.g. "fade-under-vo: when voiceover continues across visual change"
+
+## Recurring frames
+
+<!-- Named frames the brand uses across episodes (intro shells, outro shells,
+     hero compositions). Lux references these by name in project storyboards
+     instead of redescribing each time. -->
+- TODO — e.g. "swiss-grid-3up: 3-column comparison hero"
+- TODO — e.g. "ken-burns-restrained: photographic still with gentle zoom"
+
+## Technique whitelist
+
+<!-- Visual techniques the brand allows. Lux picks from this list. -->
+- TODO — e.g. swiss-grid
+- TODO — e.g. ken-burns-restrained
+- TODO — e.g. fade-under-vo
+
+## Technique blacklist
+
+<!-- Visual techniques the brand never uses (overrides any whitelist). -->
+- TODO — e.g. glitch
+- TODO — e.g. kinetic-typography-heavy

package/templates/workspace/_packs/README.md

@@ -0,0 +1,54 @@
+# Asset Packs
+
+Asset packs are **folders + sidecars**. Each subdirectory here is a pack.
+Anywhere else on disk works too — register external folders via:
+
+```sh
+atelier pack register ~/Dropbox/Shared/CompanyBrand
+```
+
+(`atelier pack register` ships in a later release. For now, register by
+editing `workspace.atelier`'s `packs.external` list.)
+
+## Pack structure
+
+```
+_packs/<pack-name>/
+├── .atelier-pack.yaml         # required — sidecar describes what/when/how
+├── logos/                     # category folders (yours to name)
+├── photos/
+├── transitions/
+└── ...
+```
+
+## Sidecar shape
+
+See `.paradigm/personas/lux/skills/walk-asset-packs.md` for the canonical
+schema. Quick reference:
+
+```yaml
+name: swiss-grid
+owner: you
+vibe: editorial, clinical, generous whitespace
+categories:
+  logos:
+    when: full-screen reveals, watermarks
+    when_not: inline with body copy
+    treatment: monochrome on photos; full color on solid paper
+restrictions:
+  - never combine logos/ with grids/ in same frame
+```
+
+## Who reads packs
+
+- **Lux** (Cinematographer) walks `_packs/*/` to resolve asset slots when
+  storyboarding. Cites pack-relative paths or category descriptors in
+  STORYBOARD.md.
+- **Iris** (Composer) symlinks the cited pack assets into
+  `projects/<name>/assets/` at scaffold time.
+
+## What NOT to put here
+
+- Bytes you want to share publicly — packs are local-first (`TD-2026-05-26-271`)
+- Generated outputs — those live in `projects/<name>/out/`
+- Per-project raw recordings — those live in `projects/<name>/media/`

package/templates/workspace/projects/README.md

@@ -0,0 +1,49 @@
+# Projects
+
+Each subdirectory here is one **output series** — typically one video or a
+small batch of related variants (teaser-15s / trailer-30s / full-spot-60s
+sharing the same beat).
+
+## Project structure
+
+```
+projects/<name>/
+├── DESIGN.md                  # project overrides to workspace _brand/DESIGN.md
+├── SCRIPT.md                  # this project's actual script
+├── STORYBOARD.md              # this project's shot list
+├── .atelier-overlay.yaml      # optional — structured overrides to brand .yaml
+├── media/                     # raw recordings for this project
+├── transcripts/               # auto-generated from media/
+├── _packs/                    # optional — project-only packs (rare)
+└── (Iris emits these as needed)
+    ├── index.html             # Hyperframes composition
+    ├── assets/                # symlinks into media/ + _packs/
+    └── out/                   # final renders
+```
+
+## Creating a project
+
+Ask Quill in a Claude Code session:
+
+> @atelier-quill draft a 15s teaser for `<project-name>`
+
+Quill will scaffold `projects/<name>/` with starter DESIGN.md / SCRIPT.md /
+STORYBOARD.md that inherit the workspace `_brand/` voice + visual register
+via the cascade rules.
+
+## Cascade rules (TL;DR)
+
+When agents work in `projects/<name>/`, the **effective brand** they read is
+`_brand/<file>` (workspace) overlaid with `projects/<name>/<file>`:
+
+- **Strings** → project overrides workspace
+- **Lists** → project extends workspace (additive)
+- **Map bindings** → project overrides at the key, leaves siblings intact
+
+Full rules: `.paradigm/personas/_shared/cascade-merge.md`.
+
+## What NOT to put here
+
+- Brand-level rules (those go in `_brand/` — agents will prompt promotion when
+  they see something repeat across projects)
+- Pack bytes (those go in `_packs/<pack-name>/` or external pack folders)

package/templates/workspace/workspace.atelier

@@ -0,0 +1,22 @@
+# Atelier v2 workspace manifest.
+# Created by `atelier workspace`. Edit fields freely.
+#
+# A workspace is a brand container. It holds:
+#   - _brand/      brand artifacts (DESIGN/SCRIPT/STORYBOARD + .atelier-brand.yaml)
+#                  inherited by every project
+#   - _packs/      asset packs (folders with .atelier-pack.yaml sidecars)
+#                  visible to every project
+#   - projects/    output series (each a self-contained brief + Hyperframes scaffold)
+#
+# Agents (Quill / Lux / Iris) read the workspace from cwd. There is no
+# `.atelier/active.yaml` in v2 — explicit project arg or cwd determines scope.
+
+version: 2.0.0
+name: "{{WORKSPACE_NAME}}"
+created: "{{ISO_DATE}}"
+
+# External pack pointers — register folders anywhere on disk so agents can
+# resolve them under `_packs/<pack>/`. Add via `atelier pack register <dir>`.
+# (`atelier pack register` ships in a later release; for now edit by hand.)
+packs:
+  external: []

package/university/content/notes/N-atel-001-first-render.md

@@ -0,0 +1,114 @@
+---
+id: N-atel-001-first-render
+title: Render your first animation
+type: note
+track: ATEL-001
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-001
+  - first-render
+  - cli
+difficulty: beginner
+estimatedMinutes: 5
+prerequisites:
+  - N-atel-001-install-and-launch
+summary: Create a minimal `.atelier` document by hand, preview a frame, and export to PNG — three CLI calls, no studio needed. Demystifies the document format before the visual surfaces hide it.
+---
+
+## The smallest possible document
+
+Save this as `hello.atelier` in any directory:
+
+```yaml
+name: Hello
+canvas:
+  width: 800
+  height: 600
+  fps: 60
+  background: "#0F1115"
+layers:
+  - id: title
+    visual:
+      type: text
+      content: Hello, Atelier
+      style:
+        fontFamily: Inter, system-ui, sans-serif
+        fontSize: 64
+        fontWeight: 600
+        color: "#F5F5F7"
+    frame:
+      x: 400
+      y: 300
+    bounds:
+      width: 600
+      height: 100
+    anchorPoint:
+      x: 0.5
+      y: 0.5
+    opacity: 0
+states:
+  default:
+    duration: 60
+    deltas:
+      - layer: title
+        property: opacity
+        from: 0
+        to: 1
+        startFrame: 0
+        endFrame: 30
+        easing: ease-out
+```
+
+That's a full Atelier document. One text layer, one state, one delta that fades the title in over 30 frames.
+
+## Validate it
+
+```bash
+atelier validate hello.atelier
+```
+
+The schema catches malformed easings, references to nonexistent layers, out-of-range frame numbers, missing required fields. Validation runs against a Zod schema with AI-readable error messages — if you ever ship a corrupt document, the validator will point at the field, not just say "invalid YAML."
+
+## Preview a frame
+
+```bash
+atelier preview hello.atelier --frame 15
+```
+
+Outputs the resolved layer state at frame 15: the title at 50% opacity, mid-fade. This is the same `resolveFrame` call the renderer makes; `preview` lets you inspect it without rendering.
+
+## Export
+
+```bash
+atelier export-image hello.atelier --frame 30 --out hello.png
+```
+
+PNG export from a single frame, via the `@napi-rs/canvas` rasterizer (prebuilt binaries — no native build, works on a plain `npm install`). For video, use `atelier render`:
+
+```bash
+atelier render hello.atelier --format mp4 --out hello.mp4
+```
+
+The CLI's `render` uses FFmpeg (must be on `$PATH`) and outputs MP4 or GIF. The browser studio exports via WebCodecs (MP4 / WebM / GIF, no FFmpeg dependency). Vector output is `atelier export-svg` and `atelier export-lottie` — see ATEL-701.
+
+## What you just learned about the format
+
+- **Canvas** sets dimensions, frame rate, background — the global render context.
+- **Layers** are visual elements with an ID, a `visual` (shape/text/image/video/group/ref), a `frame` (position), `bounds` (size), `anchorPoint`, and animatable properties (opacity, rotation, scale).
+- **States** are named keyframes. Each has a `duration` (in frames) and `deltas` (interpolations).
+- **Deltas** animate one property of one layer from a `from` value to a `to` value across `startFrame`–`endFrame`, with an `easing`.
+
+That's the mental model. Layers describe what exists. States describe how long. Deltas describe how things change. Everything else — easings, presets, templates, interactions, refs — extends these primitives.
+
+## Where to go next
+
+- **ATEL-101**: Document Model Fundamentals — every layer type, every easing, the resolveFrame interpolation model
+- **ATEL-201**: Authoring via MCP — the 61 tools an agent uses to build documents like this without touching YAML
+- **ATEL-301**: Visual System — shapes, typography, images, video; fills, strokes, shadows, blend modes, motion paths
+- **ATEL-501**: Video Project Pipeline — silence-trim, transcribe, captions, parametric cuts
+- **ATEL-601**: Studio Recipes — bundle silence policy + caption style + overlay rules + palette into a reusable preset
+
+You can also just run `atelier studio hello.atelier` and edit this document in the browser. Anything you change in the studio writes back to the same file.

package/university/content/notes/N-atel-001-install-and-launch.md

@@ -0,0 +1,84 @@
+---
+id: N-atel-001-install-and-launch
+title: Install Atelier and launch the studio
+type: note
+track: ATEL-001
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-001
+  - install
+  - cli
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites:
+  - N-atel-001-what-is-atelier
+summary: One npm install gives you three commands — `atelier` (CLI), `atelier-mcp` (MCP server for AI agents), and `atelier studio` (local browser editor). Walks through install, what each command does, and how the three relate.
+---
+
+## Install
+
+```bash
+npm i -g @a-company/atelier
+```
+
+That single install gives you three executables on your `$PATH`:
+
+| Command | What it does | When you use it |
+|---|---|---|
+| `atelier` | CLI for validating, inspecting, rendering, and processing `.atelier` files | Scripts, CI, Makefiles, ad-hoc inspection |
+| `atelier-mcp` | MCP server an AI agent can connect to for authoring | Configure once in Claude Desktop or any MCP-aware client |
+| `atelier studio` | Boots a local browser editor on `localhost` | Hands-on editing; image overlays; watching an agent mutate live |
+
+You only need Node 20+ and a modern browser. No native build, no cloud account, no signup.
+
+## Launch the studio
+
+```bash
+atelier studio
+```
+
+That command:
+
+1. Probes a free port starting at `4321` (override with `--port 5000` or `--port-range 4321-4340`)
+2. Boots a local HTTP server bound to `127.0.0.1` (never `0.0.0.0`)
+3. Opens your default browser to `http://localhost:<port>` (suppress with `--no-open`)
+4. Watches the current working directory for `.atelier` files and lists them in the sidebar
+5. If the directory is empty, scaffolds a `welcome.atelier` so you land in a real document instead of an empty shell
+
+The studio runs entirely on your machine. Nothing is sent anywhere.
+
+## Configure the MCP server (for AI agents)
+
+In your Claude Desktop config (or any MCP client):
+
+```json
+{
+  "mcpServers": {
+    "atelier": {
+      "command": "atelier-mcp"
+    }
+  }
+}
+```
+
+The agent now has 61 tools across 15 groups — document/layer/state/delta operations, visual configuration, asset and variable management, presets, templates, exports, and more. ATEL-201 covers the full tool surface and when to use which.
+
+## How the three commands relate
+
+They share a single underlying engine (`@atelier/core`) and document store. Mutations made by `atelier-mcp` are observable by `atelier studio` running in the same project — when you wire the live-mutation bridge (the WebSocket transport between the MCP store and the studio), an agent's tool calls appear in the studio canvas in real time, with a toast attributing each change to its source.
+
+This is the symbiotic loop Atelier is built for: the agent proposes, you tweak, the agent re-proposes, your tweaks survive. The detected-vs-user-edited convention from ATEL-501 (video pipelines) is the same idea generalized — every channel (silence-trim, captions, overlays, agent mutations) carries a source tag, and re-runs preserve human authorship.
+
+## Sanity-check your install
+
+```bash
+atelier --version
+atelier list
+```
+
+`atelier list` enumerates the `.atelier` files in CWD. If there are none and you haven't launched the studio yet, that's expected — the welcome scaffold only happens on `atelier studio` first run.
+
+Next: render your first animation.

package/university/content/notes/N-atel-001-what-is-atelier.md

@@ -0,0 +1,51 @@
+---
+id: N-atel-001-what-is-atelier
+title: What is Atelier?
+type: note
+track: ATEL-001
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-001
+  - orientation
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+summary: Atelier is an AI-native animation engine — a declarative YAML format authored through MCP tools, runnable from a CLI, embeddable as a widget, and now bootable as a local browser editor with `atelier studio`.
+---
+
+## The short version
+
+Atelier is an **animation engine that an AI agent can author through tool calls**. A `.atelier` document is plain YAML describing layers (shapes, text, images, video, groups), states, and deltas (per-frame interpolations). An agent calling `atelier_create`, `atelier_add_layer`, `atelier_add_state`, `atelier_add_delta` builds a document the same way a human would in a GUI — except every step is structured, validated, and reproducible.
+
+Once a document exists, Atelier can:
+
+- **Resolve** any frame by interpolating delta values through easings (linear, cubic-bezier, ease presets, spring physics, step)
+- **Render** to Canvas 2D, SVG strings, or Lottie JSON
+- **Export** to PNG, MP4, WebM, GIF — from a browser (WebCodecs) or the CLI (FFmpeg)
+- **Edit** in a browser studio with a canvas preview, layer panel, property panel, and YAML view
+- **Trim, transcribe, caption** video projects with the silence-detect + Whisper + caption pipelines
+
+## What makes it "AI-native"
+
+Three things, in order of importance:
+
+1. **The document format was designed for an agent to write.** Layers have descriptive IDs, deltas reference layers by ID, states reference each other by name. There is no "drag this onto the canvas" — there is `atelier_add_layer({ id: "title", visual: { type: "text", content: "Hello", style: {...} } })`. The schema gives AI-readable validation errors when the agent gets it wrong.
+2. **61 MCP tools cover the full authoring surface.** An agent doesn't compose YAML by hand and pray it parses. It calls typed tools that mutate a document store, validate after each mutation, and return the updated document. Mistakes are caught at the tool boundary, not at render time.
+3. **The detected-vs-user-edited convention.** When a pipeline (silence-trim, captions) generates layers from analysis, those layers are tagged. User edits set `userEdited` / `userAdded` / `hidden` flags. Re-running the pipeline preserves user fixes by matching on timing tolerance. The human and the agent can both edit the same document forever without one erasing the other.
+
+## What it is not
+
+- **Not a code framework.** It does not ship React components, runtime hooks, or HTTP handlers.
+- **Not a cloud product.** Everything runs locally. There is no signup, no SaaS, no telemetry by default.
+- **Not a replacement for After Effects.** It is a programmable, AI-author-first format. You will not draw bezier paths with a mouse here (yet). You will describe them in YAML or generate them via tool calls.
+
+## Who uses Atelier today
+
+- **AI agents** authoring social-media-ready motion graphics, explainer animations, and short-form video composition
+- **Developers** scripting animations via the Builder API (`@atelier/core`) or driving the CLI from a Makefile
+- **Content creators** in `atelier studio` for hands-on layer editing with AI assistance live in the loop
+
+The rest of this track shows you how to install Atelier and render your first animation in under two minutes.