@atomcut/mcp 3.1.0

package/README.md

@@ -0,0 +1,24 @@
+# @atomcut/mcp
+
+Let **Claude Code**, **Claude Desktop**, **Cursor** — any [MCP](https://modelcontextprotocol.io) client — drive a running [AtomCut](https://atomcut.net) editor: design, animate, edit video, generate media, all live on your canvas.
+
+| Your agent app | Add AtomCut |
+|---|---|
+| Claude Code | `claude mcp add -s user atomcut -- npx -y @atomcut/mcp` |
+| Codex | `codex mcp add atomcut -- npx -y @atomcut/mcp` |
+| Gemini CLI | `gemini mcp add -s user atomcut npx -y @atomcut/mcp` |
+| VS Code | `code --add-mcp '{"name":"atomcut","command":"npx","args":["-y","@atomcut/mcp"]}'` |
+| Cursor · Claude Desktop · anything else | a stdio server: command `npx`, args `["-y", "@atomcut/mcp"]` |
+
+Then in AtomCut: **Agents ▸ Use your agent app ▸ Link**. That's it — the tab stays linked and reconnects whenever your agent starts a session. Ask for anything: "cut the pauses out of this interview and caption it".
+
+It works with whatever model your agent app runs — MCP is between the app and AtomCut, not the model.
+
+What your agent gets:
+
+- **Every editor verb as a tool** — the same ~70 commands AtomCut's own agent uses (create and style layers, keyframes, effects, grading, timeline edits, captions, AI media jobs), with live JSON schemas.
+- **Eyes** — `view_render` / `view_frames` return real renders as images, so it checks its own work.
+- **The AtomCut skill** as resources (`atomcut://skill/SKILL.md` and references) — how to work well in the app, plus the default design system.
+- **Safety** — the bridge listens on `127.0.0.1` only and trusts only AtomCut's own origins (`app.atomcut.net`, the desktop app, `localhost`); a tab served from anywhere else must present the pairing token printed on start (also in `~/.atomcut-mcp`; extra origins via `ATOMCUT_MCP_ORIGINS`); every change is labelled with your agent's name in AtomCut's Undo menu, one step per request.
+
+MIT licensed.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@atomcut/mcp",
+  "version": "3.1.0",
+  "type": "module",
+  "description": "Drive a running AtomCut editor from Claude Code, Claude Desktop, Cursor or any MCP client \u2014 every editor verb as a tool, renders as images, the AtomCut skill as resources.",
+  "bin": {
+    "atomcut-mcp": "./src/cli.mjs"
+  },
+  "exports": {
+    "./protocol": {
+      "types": "./src/protocol.ts",
+      "default": "./src/protocol.ts"
+    }
+  },
+  "scripts": {
+    "start": "node src/cli.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepack": "node scripts/pack-skill.mjs"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2"
+  },
+  "dependencies": {
+    "ws": "^8.21.3"
+  },
+  "license": "MIT",
+  "keywords": [
+    "atomcut",
+    "mcp",
+    "model-context-protocol",
+    "claude-code",
+    "motion-design",
+    "video-editing"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/novincode/atomcut"
+  },
+  "homepage": "https://atomcut.net/docs/ai/claude-code",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src/cli.mjs",
+    "src/protocol.ts",
+    "skill",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skill/design-systems/atomcut-default/DESIGN.md

@@ -0,0 +1,107 @@
+---
+name: AtomCut Default
+description: The default design system for work made in AtomCut — a type scale, spacing, safe areas, colour roles and motion tokens that make any comp look deliberate. Replace it with a brand's own system when there is one.
+version: 1.0.0
+---
+
+# AtomCut Default design system
+
+Tokens are **relative to the comp** so one system serves a 1080×1920 reel and a 3840×2160 film. `U` = the comp's **short side / 100** (10.8px on 1080×1920 and 1920×1080; 21.6px on 4K).
+
+## Grid and safe areas
+
+- **Margin**: 6U from each edge for primary content (≈ 65px at 1080). Title-safe = 90% of the frame; action-safe = 95%.
+- **Vertical video (9:16)**: keep text out of the bottom 15% and the right 12% — platform UI lives there. Top 8% is for status bars.
+- **Columns**: landscape 12 columns, gutter 2U; vertical 4 columns, gutter 2U. Align edges to columns; centre only what stands alone.
+- **Rhythm**: vertical spacing in multiples of 1U; related items 1–2U apart, groups 4–6U apart.
+
+## Type scale (steep, ≈×1.6 — hierarchy has to read in the half-second a viewer gives it)
+
+| Role | Size | Weight | Tracking | Leading |
+|---|---|---|---|---|
+| Display | 16U | 800 | −3% | 0.95 |
+| Title | 10U | 700–800 | −2% | 1.0 |
+| Heading | 6.5U | 700 | −1% | 1.1 |
+| Body | 4U | 400–500 | 0 | 1.4 |
+| Caption (on video) | 4.5–5.5U | 700 | 0 | 1.15 |
+| Kicker / label (caps) | 2.6U | 700 | +18% | 1.0 |
+| Fine print | 2.2U | 500 | +2% | 1.3 |
+
+- Display fits **≤ 12 characters a line** (≤ 8 on 9:16); longer lines step down to Title. Never more than three sizes in one shot.
+- Numbers in data or timers: tabular figures (`fontFeatures` `tnum`).
+
+Families: **Inter** for workhorse text; **Space Grotesk** or **Sora** for geometric display; **Playfair Display** / **Fraunces** when editorial or luxury; **JetBrains Mono** for code and data. Two families at most per piece.
+
+## Colour roles
+
+A composition uses roles, not arbitrary colours:
+
+| Role | Default | Use |
+|---|---|---|
+| `ground` | `#0B0B12` | background (dark default; invert for light pieces) |
+| `surface` | `#15151E` | cards, pills, panels |
+| `ink` | `#F4F4FA` | primary text |
+| `ink-2` | `#A9A9C4` | secondary text |
+| `accent` | `#9C7CFF` | one focal colour per shot |
+| `accent-2` | `#FF5C8A` | rare second accent (states, highlights) |
+| `line` | `#FFFFFF1F` | hairlines and dividers |
+
+Light pieces swap the ground and ink: `ground #F6F5F2`, `surface #FFFFFF`, `ink #121218`, `ink-2 #5B5B6E`, `line #1212181A`; the accents stay.
+
+- One accent per shot, used on 5–10% of the frame.
+- Text contrast ≥ 4.5:1 against what is actually behind it (check the render).
+- Gradients stay within a hue family: ground → a deeper or warmer version of itself.
+- On footage, text sits on a scrim (ground at 40–60% alpha), a pill (`surface`), or with a soft shadow (0 2U 6U #000 at 50%).
+
+## Shape language
+
+- Corner radius: 1.5U small (chips, tags), 3U cards, full (height/2) pills.
+- Strokes: 0.2U hairlines, 0.5U emphasis. Round caps for anything drawn on.
+- Shadows: soft and low — one light source, top-left.
+
+## Motion tokens
+
+| Token | Duration | Easing |
+|---|---|---|
+| `micro` | 200ms | ease-out |
+| `enter` | 600ms | ease-out-expo |
+| `enter-large` | 900ms | ease-out-expo |
+| `exit` | 400ms | ease-in |
+| `move` | 700ms | ease-in-out |
+| `settle` | 500ms | ease-out-back (sparingly) |
+
+- **Stagger**: letters 18ms · words 90–120ms · lines 150ms · list items 80ms.
+- **Distance**: entrances travel 2–4U; big reveals up to 8U. Nothing slides in from off-frame unless it is a transition.
+- **Order**: kicker → title → supporting text → decoration. The eye should never have two things arriving at once.
+- **Holds**: a finished title holds ≥ 1.2s (+ 50ms per word) before anything changes.
+- **Loops**: continuous drift uses `linear` or `sin()` expressions at 0.1–0.3 Hz — calm, not busy.
+
+## Captions
+
+- Focus word: `ink`, weight 800, with an `accent` pill (radius full, padding 0.6U × 0.3U) or an accent colour — one or the other, not both.
+- Read words: `ink` at 100%; unread words: `ink` at 55% (lyrics: read 35%, upcoming 55%).
+- 2 lines at most on screen; 3–5 words a caption for talk, 1–2 for punchy social.
+
+## Imagery and generated media
+
+When drawing or shooting with AI, brief it in the system's terms so it belongs next to the type:
+
+- **Palette**: name `ground` and `accent` in the prompt ("deep ink-blue shadows, a single violet accent light"); avoid saturated rainbow scenes.
+- **Light**: one motivated key, soft fill, gentle falloff; cinematic contrast, not HDR.
+- **Composition**: leave the title's area calm (say where: "empty upper third"); subject on a third, not dead centre, unless it is a product hero.
+- **Finish**: natural film grain at most; no text, logos or watermarks in the image — type is set in AtomCut.
+- **Footage**: slow, deliberate camera moves (push-in, lateral track); 24–30 fps feel; 4–8 s shots.
+- **Voice**: warm, clear, mid-pace; conversational rather than announcer. **Music**: minimal and modern, 90–110 bpm, instrumental under voice, clean ending.
+
+## Sound tokens
+
+- UI pops and clicks: volume 0.15–0.35, randomness 0.4–0.6, pitch 0.9–1.2. Never on every letter — per word or per element.
+- Whooshes on big moves only; one per transition.
+- Voice sits at full level; music ducks under it (−12 dB).
+
+## Do / don't
+
+- Do align to the grid and share edges; don't nudge by eye.
+- Do let one element lead; don't animate everything at once.
+- Do check the busiest frame for legibility; don't trust a single still.
+- Don't stack more than two effects on text. Don't use pure `#000`/`#FFF` for large fields — use `ground`/`ink`.

package/skill/skills/atomcut/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: atomcut
+description: How to design, animate and edit inside AtomCut — the motion design and video studio — through its command API. Use for any request to create or change anything in an AtomCut project.
+version: 1.0.0
+---
+
+# Working in AtomCut
+
+AtomCut is a motion design and video studio: an infinite canvas of **comps** (artboards, each with its own timeline and fps), layers that animate, effects, colour grading, captions, sound and export. You drive it through commands (tools). The user sees every change live, can undo your whole turn in one step, and can message you while you work.
+
+You are the senior motion designer, video editor and art director on the job. The bar is: **it looks intentional**. Hierarchy, rhythm, restraint, and motion that means something.
+
+## The loop
+
+1. **Orient** — `doc_overview` first (comps, sizes, selection). `layers_list` for the comp you will touch. Read no more than the task needs.
+2. **Plan in one breath** — what the result looks like, the layers, the timing. For anything with more than two layers, decide the layout grid and type scale before creating anything (see the design system).
+3. **Build** — prefer one `api_batch` per idea (a card and its contents, a set of staggered keys). Use `$0.id` to reference earlier results inside a batch.
+4. **Look** — `view_render` after visible changes; `view_frames` for anything that moves. Pick the cheapest detail that answers your question (`glance` for layout, `look` default, `inspect` for type).
+5. **Refine** — fix what you saw: overlaps, cramped margins, weak contrast, jumpy easing, text off the safe area. Look again.
+6. **Report** — tell the user what you made in two or three sentences, and `report_issue` anything you could not do.
+
+## Coordinates, time, identity
+
+- Comp space, **origin at the comp's centre, +y down**. A 1080×1920 comp spans x −540…540, y −960…960. `transform.x/y` place the layer's **pivot** (centre by default).
+- Auto layout containers are the exception: their box is placed by its **top-left** (`layout.x/y`).
+- Times are **milliseconds**. Layer start/end are comp time; **keyframe times are relative to the layer's start** (use `clock: "comp"` in `keyframes_set` to think in comp time).
+- Layers are addressed by id (`clip_…`, `group_…`). Commands also accept an exact, unique layer **name** — name things well and you can refer to them by name.
+
+## The command map
+
+| Job | Commands |
+|---|---|
+| Read | `doc_overview`, `layers_list`, `layer_get`, `layer_properties`, `media_list` |
+| Learn the shape of anything | `api_describe` (any type, any path), `catalog_list` / `catalog_get` (effects, animations, templates, transitions, easings) |
+| Make layers | `layer_create` (text · shape · path from SVG `d` · media · nested comp · adjustment) |
+| Change values | `layer_set` (property paths; keys when keyed), `text_set`, `text_style` (a word or range) |
+| Change structure | `layer_patch` (anything else in a layer's data, schema-validated), `template_apply` |
+| Motion | `animation_set` (in/out presets), `keyframes_set` / `keyframes_clear`, `expression_set` |
+| Effects & colour | `effects_add` / `effects_update`, `grade_node` / `grade_effect` / `grade_read` |
+| Structure | `layers_group` (+ auto layout), `layout_set`, `layers_nest`, `layers_restack`, `layers_duplicate`, `layers_delete` |
+| Time | `timeline_move`, `timeline_trim`, `timeline_split`, `timeline_cut_ranges` (cut + ripple in sync), `timeline_close_gaps`, `transition_add`, `audio_detach` / `audio_rejoin` (J/L-cuts) |
+| Comps | `frame_create`, `frame_update`, `frame_delete` |
+| See | `view_render`, `view_frames` |
+| Media | `media_import`, `media_inspect`, `audio_analyze`, `font_install`, `sounds_list` |
+| Words from sound | `media_transcribe` (text · pauses · captions · `lyrics` timing), `media_remove_pauses` |
+| Make with AI | `generate_image` (draw · edit · references), `generate_video` (from words · a still · footage), `generate_speech` + `voices_list`, `generate_sound`, `generate_music` |
+| Fix with AI | `media_remove_background` (cut-out), `media_upscale`, `audio_isolate` (clean voice) |
+| Session | `session_set` (select, playhead, open a comp, working range) |
+| Many steps | `api_batch` |
+| Diagnose / improve | `app_console`, `report_issue`, `history_undo` (your own steps only) |
+
+Commands you do not see in your tool list are not available in this session. An AI media job whose provider is not connected fails with a hint naming who can do it — pass that on to the user rather than improvise.
+
+## Three levels of writing — use the highest that fits
+
+1. **Verbs** (`layer_create`, `animation_set`, `effects_add`, `layers_group`…) — they keep invariants you would otherwise break (placement, key rules, caption cues, ids).
+2. **`layer_set` by property path** — any animatable value: `x`, `y`, `rotation`, `scale`, `opacity`, `fontSize`, `fill.<paintId>.color`, `lfx.<effectId>.<field>`, `stroke.<id>.width`… `layer_properties` lists every path a layer has, with current values and ranges. After Effects rule: once a property has keys, writing it adds a key at `atMs`.
+3. **`layer_patch`** — everything else (lists, modes, options): `set`, `merge`, `insert`, `remove`, `move` by path (`effects[id=lfx_1].enabled`, `fills[0]`, `strokes[-]`). Missing ids are minted for you. The whole layer is re-validated; an invalid patch changes nothing and names the wrong field. `api_describe` first when you have not written that shape before.
+
+The API describes itself from the live schemas, so nothing in it is ever out of date: a field or effect that ships next month appears in `api_describe`, `layer_properties` and `catalog_list` the day it lands. Trust them over memory.
+
+## Craft, in brief
+
+Read the references for depth. The non-negotiables:
+
+- **Hierarchy**: one focal point per moment. Size, weight, colour and motion all agree on what matters most.
+- **Type**: two families at most, a clear scale (see the design system), tight tracking on big display type, generous line height on body. Never set on-screen text under ~3% of the comp's short side for video.
+- **Space**: consistent margins from a grid; keep text inside title-safe (90%). Align edges; do not eyeball what should share an edge — use auto layout.
+- **Motion**: every move has a reason and an easing. Entrances ease **out**, exits ease **in**, moves between two rests ease **in-out**. Stagger 30–80ms per unit. Overlap actions; nothing starts from a dead stop in unison unless that is the point.
+- **Colour**: a restrained palette — a dominant, a neutral, one accent. When text sits on imagery, fix contrast with a scrim, shadow or highlight pill before adding weight.
+- **Restraint**: one hero effect per shot. Glow, glass and grain are seasoning.
+
+## Knowledge on demand
+
+Read with `skill_read` (pack "atomcut") when the task touches the subject — not before:
+
+- `references/api.md` — conventions, batching, property path grammar, errors and recovery
+- `references/layers-and-layout.md` — layer kinds, transforms and pivots, groups, auto layout, nesting, components, masks and booleans
+- `references/type-and-captions.md` — typography, ranges, text effects, templates, text on a path, captions, lyric styles
+- `references/motion.md` — animation principles, presets, keyframes, easing, motion paths, expressions, modulators, motion blur
+- `references/fills-strokes-vectors.md` — paints, gradients, patterns, strokes and draw-on, shapes, pen paths, booleans, drawing and flipbooks
+- `references/color-and-grading.md` — palettes, contrast, the grade graph, building a look from a feeling
+- `references/effects.md` — the effect families and when each earns its place
+- `references/editing.md` — cutting, pacing, dead air, J/L-cuts, speed, reframing, long → short, versions
+- `references/sound.md` — audio layers, sounds on animation, audio effects, voiceover
+- `references/media-and-generation.md` — attachments, import, references; drawing and editing images, shooting and editing video, voices, sound effects, music, cut-outs, upscaling, provenance
+- `references/review.md` — looking efficiently, and the checklist before you call anything done
+- `references/recipes.md` — worked builds: title card, lower third, lyric captions, kinetic type, reel, promo, logo reveal
+- `references/reporting.md` — when and how to file `report_issue`
+
+The enabled design system (`<design_system>`) sets the tokens: type scale, spacing, colour roles, motion timing. Follow it unless the user asks otherwise; a user's own design system wins over the default.
+
+## When you cannot do something
+
+Say so plainly, do what you can, and `report_issue` with an honest analysis — what you tried, what happened, what should have happened, and the fix in API or skill terms. Reports are how this skill and the API improve. Never fake a result, and never claim something looks right that you did not look at.

package/skill/skills/atomcut/references/api.md

@@ -0,0 +1,88 @@
+# The API — conventions and patterns
+
+Every command is a tool. Names use `_` in tool calls (`layer_create`) and `.` inside `api_batch` (`layer.create`); both work anywhere a command id is accepted.
+
+## Results and errors
+
+- Results are compact JSON. Reads summarise; ask for more with `fields`, a narrower `path`, or a `group`.
+- A failed call changes nothing. Errors say which field is wrong and what to do: read the `Hint:` line, fix, retry. Three kinds:
+  - **input** — the arguments did not match the schema (`style.fontSize: Expected number`). Fix the named field.
+  - **api** — the request was valid but cannot apply (`No layer with id…`, `"glow" does not apply to a shape`). The hint names alternatives.
+  - **internal** — a bug. Retry once with a different approach, then `report_issue` (category `api-bug`).
+- Typos get "Did you mean": `rotaton` → `rotation`.
+
+## Reading, cheapest first
+
+| Need | Call |
+|---|---|
+| Comps, sizes, selection, playhead | `doc_overview` |
+| What is in a comp, where, when | `layers_list` (bounds and flags per layer) |
+| One layer's data | `layer_get` (bulky parts folded — ask with `fields: ["subpaths"]`) |
+| What a layer can animate, and current values | `layer_properties` (optionally one `group`) |
+| The exact shape of a type | `api_describe {type, path}` — e.g. `{type:"text", path:"style"}`, `{type:"layerEffect", path:"[type=glass]"}`, `{type:"paint"}`, `{type:"layout"}` |
+| What exists to choose | `catalog_list {catalog, query}` then `catalog_get` for fields/knobs |
+
+## Batching
+
+`api_batch` runs calls in order and returns every result. Reference an earlier result with a string that is exactly `$<index>` or `$<index>.<path>`:
+
+```json
+{ "calls": [
+  { "command": "layer.create", "input": { "kind": "shape", "shape": "rect", "width": 640, "height": 180, "fill": "#15151C", "cornerRadius": 28 } },
+  { "command": "layer.create", "input": { "kind": "text", "text": "New drop", "placement": { "above": "$0.id" } } },
+  { "command": "layers.group", "input": { "ids": ["$0.id", "$1.id"], "name": "Chip", "layout": { "padding": { "top": 24, "right": 40, "bottom": 24, "left": 40 } } } }
+] }
+```
+
+Stops at the first failure (later calls are skipped and listed) unless `continueOnError: true`. Batches do not nest. Up to 40 calls.
+
+Parallel tool calls in one turn also work: reads run together; writes run in the order you wrote them.
+
+## Property paths (`layer_set`, `keyframes_set`, `expression_set`)
+
+One grammar everywhere — keyframes, drivers, expressions, modulators, the node board:
+
+| Path | Means |
+|---|---|
+| `x` `y` `rotation` `scale` `scaleY` `skewX` `skewY` `anchor.x` `anchor.y` | transform (scaleY present = non-uniform) |
+| `opacity` `feather` `borderRadius.tl…` `crop.top…` `content.x/y/scale/rotation` | layer box and picture |
+| `width` `height` `radius.tl…` | shape geometry |
+| `fontSize` `letterSpacing` `lineHeight` `color` `fontFamily` `fontWeight` `italic` `maxWidth` `text` | typography (text layers) |
+| `fill.<paintId>` / `fill.<paintId>.opacity` / `fill.<paintId>.stop.<stopId>.color` | paints |
+| `stroke.<strokeId>.width` / `.trim.end` … | strokes |
+| `lfx.<effectId>.<field>` | a layer effect's field |
+| `tfx.<effectId>.<field>` | a text effect's field |
+| `afx.<effectId>.<field>` | an audio effect's field |
+| `lfx.<gradeCard>.n.<node>.fx.<effect>.<field>` | a value inside a colour grade node |
+| `audioMix.volume` `playback.speed` | sound level; playback speed |
+| `mblur.*` | the layer's shutter |
+
+Never guess a path: `layer_properties` lists them for the actual layer, with ranges.
+
+## Patching (`layer_patch`)
+
+Ops: `set` (replace), `merge` (shallow-merge an object), `insert` (into a list; `index` or append), `remove`, `move` (`to` index). Path steps: `a.b`, `[2]`, `[id=fx_1]` (prefer — stable), `[type=glass]`, `[-]` (append).
+
+```json
+{ "id": "Title", "ops": [
+  { "op": "merge", "path": "style", "value": { "align": "left", "textCase": "upper" } },
+  { "op": "insert", "path": "strokes", "value": { "paint": { "type": "solid", "color": "#000000" }, "width": 6, "align": "outside" } },
+  { "op": "set", "path": "effects[type=shadow].enabled", "value": false }
+] }
+```
+
+Missing `id`s in anything you insert are minted. The whole layer is re-validated; nothing lands unless all of it is valid. Some fields belong to verbs and are refused here: `text` (use `text_set`), timing (`timeline_*`), `frameId`, `kind`, `id`.
+
+## Timing rules
+
+- `startMs`/`durationMs` are comp time; placement floors a new layer onto the comp's frame grid.
+- Keyframe `at` is **layer-relative** by default. A key can sit before 0 or after the end (it still shapes the curve).
+- Easing on a key shapes the segment **leaving** it. Shorthand: `"linear"`, a preset (`ease-out`, `ease-in`, `ease-in-out`, `ease-out-quart`, `ease-out-expo`, `ease-out-back`, `ease-in-out-back`, `ease-out-elastic`) or `"cubic-bezier(x1,y1,x2,y2)"`.
+
+## Undo
+
+All your writes in one user request are ONE undo step, labelled "AI · <their request>". If the user edits in between, your next writes start a new step. `history_undo` reverts your own most recent step only — useful to back out a wrong direction wholesale.
+
+## When something is missing
+
+If no verb, path or patch can express what you need, that is an API gap: do the closest honest thing, tell the user, and `report_issue` (`api-gap`) with the exact capability you needed.

package/skill/skills/atomcut/references/color-and-grading.md

@@ -0,0 +1,45 @@
+# Colour and grading
+
+## Palettes
+
+- Build from roles: ground, surface, ink, secondary ink, one accent (the design system names them). Use the accent on 5–10% of the frame.
+- Harmonies that stay tasteful: **analogous** (neighbours on the wheel) for calm; **complementary accent** (one small warm spot in a cool scene) for focus; **monochrome + one accent** for premium.
+- Dark scenes: never pure black — tint the ground toward the accent's hue (`#0B0A12` for violet, `#0A0F12` for teal).
+- Saturation budget: one saturated element; everything else muted.
+- Contrast: body text ≥ 4.5:1 against what is behind it *at the busiest frame*.
+
+## The grade graph
+
+A colour grade is an effect card (`grade`) holding a node graph, like DaVinci Resolve: **Source → correctors → Output**. Each corrector holds an ordinary stack of colour effects; nodes can run in series, in parallel (mixed back in), or as an "outside" node (the inverse of another node's key — grade the background of a secondary).
+
+1. `grade_node {id, name: "Balance"}` — creates the grade with its first corrector.
+2. `grade_effect {id, nodeId, type, values}` — put colour cards in it. `catalog_list layer-effects` with query `color` lists them (`adjust`, `colorGrade`, `gradientMap`, `vignette`, `posterize`, `overlay` …); `catalog_get` shows each field and range.
+3. More nodes in order: `grade_node {after: <nodeId>, name: "Look"}`; parallel: `{parallelTo}`; secondary background: `{outsideOf}`.
+4. `grade_read` shows the graph. Every value keyframes at `lfx.<card>.n.<node>.fx.<effect>.<field>` — animate a grade (a look that warms as the sun comes up).
+
+Keys (qualifier by hue/sat/lum, depth, power windows that can follow a tracker) limit a node to part of the picture: edit with `layer_patch` on the node's `key` (`api_describe {type:"layerEffect", path:"[type=grade]"}`).
+
+Grade the **whole edit** with an adjustment layer on top (`layer_create {kind:"adjustment"}`) and put the grade on it.
+
+## Node order that works
+
+1. **Balance** — exposure and white balance: neutral whites, blacks just above clipping, contrast to taste.
+2. **Match** — make shots agree (same skin, same sky) before styling.
+3. **Look** — the creative intent (below).
+4. **Secondaries** — skin protection, sky, a product colour — keyed nodes.
+5. **Finish** — vignette, grain, halation-style glow, gentle sharpening.
+
+## A look from a feeling
+
+| The user says | Move |
+|---|---|
+| warm, nostalgic, golden hour | temperature +, highlights toward amber, shadows toward teal-brown, saturation −10%, lifted blacks, soft grain |
+| cinematic, blockbuster | teal shadows / orange skin (keep skin natural), contrast +, saturation of blues/greens down, slight vignette |
+| clean, commercial, Apple-ish | neutral whites, high clarity, gentle contrast, saturation natural, no grain |
+| moody, noir, tense | exposure −, contrast +, desaturate toward monochrome, cool shadows, crushed blacks, vignette |
+| dreamy, soft, romantic | lifted blacks, low contrast, pastel highlights (pink/peach), glow/bloom, grain |
+| retro 70s film | warm mids, faded blacks, greens toward olive, posterized highlights slightly, strong grain |
+| cyberpunk, neon night | magenta/cyan split, saturated highlights, deep blue shadows, glow on lights |
+| documentary, honest | neutral, restrained contrast, preserve skin, nothing stylised |
+
+Always look at the result (`view_render` at `inspect` on a frame with a face or the key subject). Skin is the reference — if faces look wrong, the grade is wrong.

package/skill/skills/atomcut/references/editing.md

@@ -0,0 +1,51 @@
+# Editing video like a professional
+
+## Reading the material first
+
+- `media_list` and `layers_list` for what exists; `media_inspect` on a video for a contact sheet of its content.
+- Speech: `media_transcribe {id}` gives the words and the pauses (in comp time for a layer). This is the script you edit against.
+- Sound: `audio_analyze {id}` gives loudness and every silent stretch (`compSilences` for a layer).
+
+## Cutting
+
+- **`timeline_cut_ranges {id, ranges, ripple}`** takes stretches of comp time out of a layer in one step (one undo): razor, delete, ripple. `ripple: "sync"` (default) keeps the comp in sync like an NLE's sync-lock — captions and titles after a cut slide back with their words, a music bed spanning it is shortened instead of jumping. `"lane"` closes only this layer's lane; `"none"` leaves holes for B-roll.
+- **Dead air**: `media_remove_pauses {id, minGapMs: 600, padMs: 120}` hears the words and cuts every longer pause plus the dead head and tail. `dryRun: true` returns the ranges first. Leave natural pauses after a punchline or a question — raise `minGapMs` (900–1200) for a calm interview, lower it (350–450) for punchy social.
+- **"Cut the bullshit"** — the editorial loop:
+  1. `media_transcribe {id}`; decide what stays (the strongest lines, in an order that tells the story);
+  2. from the word timings, collect the ranges that go — cut in the pauses, ~100ms after the last kept word and ~80ms before the next;
+  3. `timeline_cut_ranges {id, ranges}` — one call, the comp stays in sync.
+- For a single cut: `timeline_split {id, atMs}`, `layers_delete`, `timeline_close_gaps {ids}`.
+- Cut on action or on a sentence boundary, never mid-word. A cut in the middle of a movement hides the join.
+- Jump cuts on a talking head are fine for social; soften them with a punch-in (below) or a B-roll cover.
+
+## J-cuts and L-cuts
+
+The audio leads (J) or trails (L) the picture across a cut — it is what makes an edit flow. `audio_detach {id}` separates a video's own sound into a linked audio layer (the video is muted, the sound stays in sync). Then trim the sound on its own: for a J-cut, extend the incoming shot's audio to start 300–800ms before its picture (`timeline_trim` its start earlier) and let the outgoing picture run over it; for an L-cut, let the outgoing sound run past the picture cut. `audio_rejoin` puts a sound back. A separate music or voice layer just needs `timeline_move` / `timeline_trim`.
+
+## Pacing
+
+- Social: a new visual beat every 1.5–3s; the hook in the first 1s (the most striking line or image first, not the intro).
+- Explainers: 3–6s per shot; let key visuals hold.
+- Music: cut on beats (downbeats for big changes, off-beats for energy). Place cuts on the frame of the transient.
+
+## Speed
+
+`layer_set {values: {"playback.speed": 1.5}}` changes a clip's playback speed; key `playback.speed` for ramps (fast through the boring part, slow into the moment). Keep speech between 0.9× and 1.15× (voice keeps pitch on voice-tagged audio). Slow motion needs high-fps footage to look smooth.
+
+## Reframing and punch-ins
+
+- A vertical cut from horizontal footage: `frame_create {width:1080, height:1920}`, then `layer_create {kind:"comp", sourceFrameId: <original comp>}` or the media itself, scaled to cover (`scale` ≈ 1920/1080 = 1.78 for 16:9 → 9:16) and positioned on the subject; key `x` to follow the action.
+- Punch-in on a talking head: key the picture's `content.scale` 1 → 1.12 at a cut point (hard, not eased) to fake a second camera; or ease `content.scale` slowly (1 → 1.05 over the shot) for a push-in.
+- Crop without moving the picture: `crop.*`; move the picture inside the window: `content.x/y`.
+
+## Transitions
+
+Mostly hard cuts. `transition_add` for a reason: `cross-dissolve` for time passing, `dip-to-color`/`fade` for section breaks, `whip-pan`/`push` for energy between similar shots, `zoom`/`glitch-cut`/`shake-cut` for social beats. 200–500ms. One transition style per piece.
+
+## Versions (long and short)
+
+Build the long version first. For a short version: duplicate the comp's content into a new comp (`frame_create` + nest, or `layers_duplicate` then move), keep the hook and the peak, cut everything between to fit the target (15s, 30s, 60s), re-time music to end on a beat. Same captions and look — only the edit changes. Offer both aspect ratios when the destination is social.
+
+## Captions and titles in an edit
+
+Caption every social cut (most watch muted): `media_transcribe {id, captions: {maxWords: 3}}`, then style consistently. Lower thirds for names: 1.5–3s after the person starts talking, hold ≥ 3s.

package/skill/skills/atomcut/references/effects.md

@@ -0,0 +1,32 @@
+# Effects
+
+Effects are ordered stacks; the first card applies first. Three domains:
+
+- **Layer effects** (`effects`, path `lfx.<id>.<field>`) — process the whole layer's pixels.
+- **Text effects** (`style.textEffects`, `tfx.…`) — per-glyph: shadow, glow, extrude, echo. They move with each letter's animation.
+- **Audio effects** (`audioEffects`, `afx.…`) — EQ, reverb, echo, compressor, saturator.
+
+`effects_add {id, domain, type, values}` · `effects_update {id, effectId, values|enabled|index|remove}` · `catalog_list layer-effects` (with `query`) · `catalog_get layer-effects <type>` for fields, ranges and defaults. Every numeric field keyframes and can be driven by an expression or modulator.
+
+## The families and when they earn a place
+
+| Family | Types | Use for |
+|---|---|---|
+| Shadow & glow | shadow, innerShadow, glow, longShadow | separation from the background (soft shadow), neon and light (glow), graphic depth (long shadow) |
+| Blur | blur, directionalBlur, zoomBlur, spinBlur, sharpen | depth of field on backgrounds, speed (directional), impact (zoom), focus pulls (animated blur) |
+| Colour | adjust, grade, colorGrade, gradientMap, posterize, overlay, vignette | correction and looks (see colour-and-grading.md) |
+| Material | glass | liquid-glass panels over busy backgrounds — refracts what is behind; one pane per shot |
+| Light | shine, lightRays, lensFlare, lightning | a sweep across a logo (shine), god rays, a flare on a reveal, energy |
+| Analog | grain, filmDamage, scanlines, noise | texture and era; grain at low strength ties graphics to footage |
+| Distort | rgbSplit, bulge, wave, twirl, lensDistort, goo, roughenEdges, glitch | glitch transitions, liquid/organic motion, hand-made edges |
+| Stylize | stroke, halftone, pixelate, bevel, chromaKey | outlines, print looks, retro games, green screen — `chromaKey` is live and free for a FLAT backdrop (green screen, studio white); for a real-world background use `media_remove_background` (AI cut-out, image or video) |
+
+## Rules of thumb
+
+- One hero effect per shot. Stack at most two on text.
+- Shadows: large blur, low opacity, offset downward — a soft lift, not a smudge.
+- Glow reads best on dark grounds with a saturated source colour.
+- Glass needs something interesting behind it; over a flat colour it is invisible.
+- Animated effects (a shine sweep, a glitch burst, a blur pull) should be brief — 200–600ms — and tied to a beat or a reveal.
+- Chroma key: `chromaKey` on the footage, then tune the key colour, tolerance and spill.
+- Background removal on a still image exists in the editor (context menu); through the API use `generate_image` edits with `parentAssetId` when a provider can, or tell the user.

package/skill/skills/atomcut/references/fills-strokes-vectors.md

@@ -0,0 +1,55 @@
+# Fills, strokes, shapes and vectors
+
+## Paint (fills and strokes)
+
+Every visual layer has ordered `fills` and `strokes` (bottom → top), Figma-style. A paint is one of (`api_describe paint`):
+
+| type | use |
+|---|---|
+| `solid` | a colour (`#RRGGBB`, `#RRGGBBAA`, or `var:<id>` for a colour variable) |
+| `linear` / `radial` / `angular` | gradient: `stops [{offset 0–1, color}]`, `start`/`end` in the layer's box (0–1) |
+| `media` | an image/video as fill: `source` self or an asset, `fit` cover/contain/fill/tile, `focus`, `adjust` |
+| `pattern` | stripes · grid · checks · dots · squares · cross · triangles · zigzag · waves · noise · image — with scale, angle, spacing, thickness, colours |
+| `variable` | a paint variable (shared styles) |
+
+Each paint has `opacity` and `blendMode`. Shortcut: `layer_create {fill: "#FF3366"}`; for gradients pass a paint object; stops and ids are minted.
+
+Craft:
+- Gradients: neighbouring hues (analogous) or a colour to a darker version of itself. Avoid muddy complements through grey. Two to three stops.
+- A soft radial glow (colour at 60–70% alpha → same colour at 0) behind a subject adds depth cheaply.
+- Patterns at low opacity with `overlay`/`soft-light` blend add texture without noise.
+- Animate paint: `fill.<paintId>` (colour), `fill.<paintId>.stop.<stopId>.color`, `.opacity`, gradient angle fields — `layer_properties` lists them.
+
+## Strokes
+
+A stroke = paint + `width`, `align` (center/inside/outside), `cap`, `join`, `dash`, `dashOffset`, plus the pipeline: `trim` (start/end/offset — **draw-on**), `offset`, `profile` (taper), `wave`, `roughness`, `scatter`, `nib` (calligraphic), `markers` (arrowheads). Insert with `layer_patch` (`insert` into `strokes`).
+
+- **Draw-on**: key `stroke.<id>.trim.end` 0 → 1 (ease-in-out, 800–1500ms), or `animation_set preset "draw"` on an outline layer.
+- Hand-drawn: `roughness` + round caps; marker: thick + taper `profile`; technical: thin + dashes.
+- Outline text: an `outside` stroke on a text layer (Impact/outline looks).
+
+## Shapes
+
+`layer_create {kind:"shape", shape: rect|ellipse|polygon|star, width, height, fill, stroke, cornerRadius, pointCount, innerRatio}`. Animatable: `width`, `height`, `radius.tl/tr/br/bl` (per-corner), star/polygon radius; ellipse arcs (`arcStartDeg`, `arcSweepDeg`, `arcRatio` — pies, rings, progress arcs) via `layer_patch`/`layer_set`.
+
+- Pill: rect with corner radius = height/2.
+- Progress ring: ellipse with `arcRatio` 0.85 and keyed `arcSweepDeg`.
+- Any box can round its corners (`borderRadius`) — images and video too.
+
+## Paths (pen)
+
+`layer_create {kind:"path", d: "<SVG path data>", fill, stroke}` — any vector outline, in the layer's own space (the layer's pivot is its box centre). Compose shapes as SVG: `M` move, `L` line, `C` cubic, `Q` quad, `A` arc, `Z` close. One path layer = one piece of artwork (a compound path — holes included); separate pieces that need their own colour or motion are separate layers.
+
+- Keep path coordinates around 0,0 and place the layer with `x/y`.
+- Icons: draw simple geometric marks from primitives; for real icons ask the user or use the Library.
+- Morphing: path geometry keyframes on the `subpaths` property — same point count on both ends morphs cleanly.
+
+## Booleans and masks
+
+Group the pieces, set the group's `mode` (`union` · `subtract` · `intersect` · `exclude` · `mask`) and mark the cutters `isStencil: true`. Non-destructive: move a cutter and the result updates. A mask group reveals content only inside the stencil — animated stencils make wipes and reveals.
+
+## Drawing, painting, flipbooks
+
+- The editor has raster brushes, vector brushes, an eraser and a fill bucket for **hand** drawing in drawing/flipbook comps. Painting strokes pixel by pixel is **not available through the API**. Build illustration from shapes and paths instead, or generate an image (`generate_image`) when a painted look is wanted. If a request needs real brushwork, tell the user and `report_issue` (`api-gap`) so the need is counted.
+- Frame-by-frame (flipbooks): each cell is a nested comp; you can read and restyle cells as layers but not draw into them.
+- A layer can step at its own `fps` (12 = on twos) for a hand-animated feel.

package/skill/skills/atomcut/references/layers-and-layout.md

@@ -0,0 +1,62 @@
+# Layers, structure and layout
+
+## Comps and layers
+
+- A **comp** (frame) is an artboard with its own size, fps, duration and timeline. Pages hold comps. Source comps of nested layers live off-page and are reached by entering their layer.
+- A **layer** (clip) is one of: `text`, `shape` (rect · ellipse · polygon · star), `path` (vector outline), `image`, `video`, `audio`, `nested` (a comp inside a comp), `group`, `waveform`, `raster` (paint), `adjustment` (grades what is beneath it).
+- A caption is a text layer carrying word cues (`caption`). Text on a path is a text layer riding another layer's outline (`path`).
+- Stacking: the top of `layers_list` renders on top. Lanes (tracks) are kind-agnostic.
+
+## Transform and pivot
+
+`transform.x/y` place the **pivot** (`anchor`), stored as a fraction of the layer's own box: `{0.5,0.5}` centre, `{0,0.5}` left-middle, `{0,0}` top-left. Rotation and scale act about it.
+
+- Left-aligned stacks: set `anchor.x: 0` on each line and give them the same `x`. Now edges align exactly and text grows to the right.
+- A mirrored layer is a **negative scale** (there is no flip flag).
+- `scale` alone is uniform; set `scaleY` for non-uniform.
+- Cropped media has two transforms: `transform` moves the window; `content.*` pans and zooms the picture inside it (a punch-in without moving the frame).
+
+## Groups
+
+`layers_group {ids, name}` wraps layers in one; `layers_ungroup` dissolves. A group's time span is a window over its members. Groups have **modes** (`layer_patch` → `mode`):
+
+| mode | effect |
+|---|---|
+| `pass` | a plain group |
+| `union` | members merge into one silhouette (effects apply once to the whole) |
+| `mask` | content shows only inside the stencil |
+| `subtract` / `intersect` / `exclude` | vector booleans: content − / ∩ / ⊻ stencil |
+
+Mark the cutter(s) with `isStencil: true` (`layer_patch`) — any number of stencils union first.
+
+## Auto layout
+
+A group with `layout` ARRANGES its members like Figma/CSS flexbox. Use it for anything that should stay aligned when text changes: buttons, chips, cards, lower thirds, lists, lyric lines.
+
+```json
+{ "ids": ["Pill", "Label"], "name": "Button",
+  "layout": { "flow": "row", "gap": 12, "padding": { "top": 18, "right": 32, "bottom": 18, "left": 32 }, "alignX": "center", "alignY": "center" } }
+```
+
+Spec (`api_describe layout`): `flow` row · column · wrap · grid (`columns`), `gap`, `lineGap`, `spaceBetween`, `padding`, `alignX`/`alignY` (start · center · end), `width`/`height` (`null` = hug), min/max sizes, `clipContent`. The box's **top-left** is `layout.x/y` (comp space).
+
+- **A rect + a text grouped with layout** — the rect becomes the container's background and hugs the text (a button). `layout: {}` infers a layout from how members already sit.
+- Per member (`layoutItem` via `layer_patch`): `fillX`/`fillY` (stretch), `absolute` (opt out and place freely — a badge on a card's corner), min/max.
+- Change it later with `layout_set`; `layout: null` removes it, keeping members where they are.
+
+## Nesting, components, reuse
+
+- `layers_nest {ids}` precomposes layers into their own comp — one layer outside, a timeline inside. Pixels do not move. Use it to animate a finished card as a unit, reuse a sequence, or give a group its own fps/duration.
+- `layer_create {kind:"comp", sourceFrameId}` places a comp inside another (a scene in an edit, a card reused three times).
+- Components (instances that update together) are made in the editor; treat instance layers like nested comps.
+
+## Adjustment layers
+
+`layer_create {kind:"adjustment"}` spans the comp and applies its effect stack to everything **below** it — a grade over a whole edit, a vignette, grain. Its crop/feather/radius limit the region.
+
+## Organising a project
+
+- **Name every layer** for what it is ("Title", "Price tag", "BG gradient"). You and the user both navigate by names.
+- One idea, one group. Nest when a unit has its own timing.
+- Keep the stack readable top→bottom: overlays, text, subject, backgrounds.
+- Put media in folders (`media_import {folder}`); generated media files itself under "AI generated".

package/skill/skills/atomcut/references/media-and-generation.md

@@ -0,0 +1,59 @@
+# Media, references and generation
+
+## Files the user gives you
+
+Attachments arrive as `<attachment id="att_…" name="…" type="…" size="…" />` (images also arrive as pictures you can see). The bytes stay in the chat until a tool uses the id:
+
+| Attachment | What to do |
+|---|---|
+| image / video / audio to use | `media_import {attachmentId, folder?, place?}` — moves the bytes into the project once; `place` puts it on the timeline. Attachments can also be passed straight to AI jobs (`edit`, `from`, `references`, `id`) without importing first |
+| font file | `font_install {attachmentId}` → the family name to set as `fontFamily` |
+| a sound effect for animation | import it, then use `custom: {assetId}` in a layer's `sounds` |
+| a reference ("make it like this") | `media_inspect {attachmentId}` — a video becomes a contact sheet of frames; study it (below) |
+| text, Markdown, JSON, CSV, subtitles | already inlined in the message — read it |
+
+## Reverse-engineering a reference
+
+When the user says "design like this", decompose before building:
+
+1. **Layout** — grid, margins, alignment, the size relationship between elements.
+2. **Type** — category (geometric sans, grotesk, serif, script), weight, case, tracking, scale ratio.
+3. **Colour** — ground, accent, how much of each; gradients and their direction.
+4. **Motion** (video) — what moves first, the easing character (snappy expo vs. soft), stagger, direction, durations; count frames between contact-sheet tiles to estimate timing.
+5. **Texture** — grain, glow, blur, shadows.
+
+Say in one line what you took from it, build with AtomCut's own pieces, then compare your `view_frames` with the reference and adjust. Recreate the idea, not a copy of someone's brand.
+
+## Making and fixing media with AI
+
+Each job runs on whichever connection the user routed to it (Agents → Connections). A job with nothing connected fails with a hint naming who can do it — tell the user; do not work around it. Everything lands in the Media folder **"AI generated"** with its provider, model and prompt on the asset. Edits keep the original and point back at it (`parentAssetId`) — never destroy the user's media. The user sees the layer being worked on shimmer on the canvas and timeline, and can undo the whole thing in one step.
+
+### Pictures
+
+- **Draw**: `generate_image {prompt, aspect, count, place?}`. Prompt like an art director: subject, composition (where the empty space goes — leave room for type), light, lens, palette, medium or style, mood. Say "no text" when type will be set in AtomCut; it will be sharper, editable and on-brand. Match `aspect` to where it goes.
+- **Edit**: `generate_image {prompt, edit: <image layer | asset | attachment>}` changes that picture ("remove the cup", "make it dusk", "same product on marble"). On an image LAYER the result swaps in place — transform, timing, effects and keys kept (`replace: false` to place it beside instead). Describe the change, not the whole scene again.
+- **Follow references**: `references: [ids]` — a style, a product, a face to keep consistent across shots.
+- **Transparency**: `transparent: true` for stickers and cut-out objects (models that cannot draw alpha get a cut-out pass when one is connected).
+- **Cut out a subject**: `media_remove_background {id}` — image → PNG with alpha, video → WebM with alpha. For a flat green/white backdrop the live `chromaKey` effect is cheaper and adjustable.
+- **More resolution**: `media_upscale {id, factor: 2}` — the layer keeps its size on the canvas, only sharper. Use before punching in on small footage or a low-res logo.
+
+### Footage
+
+- **Shoot**: `generate_video {prompt, aspect, durationS, audio?, place?}` — takes minutes; say so before starting. Prompt like a DP: subject and action, camera move (slow push-in, orbit, handheld), lens, light, mood, and the sound if the model scores it (`audio: true`). 4–8 s clips, cut together, beat one long take.
+- **Animate a still**: `from: <image>` makes it the first frame — keeps a brand look or a generated product consistent.
+- **Edit footage**: `edit: <video>` ("make it snow", "change the jacket to red"). A video LAYER's edit lands on the lane above, aligned in time, so it can be compared, masked or cross-faded. Short clips edit best.
+
+### Voice, sound, music, words
+
+- `generate_speech {text, voice?, style?}` · `voices_list {query}` — see sound.md.
+- `generate_sound {prompt, durationS}` · `generate_music {prompt, durationS, instrumental}` — see sound.md.
+- `audio_isolate {id}` — clean up a noisy voice.
+- `media_transcribe {id}` — words, pauses, captions; `lyrics` aligns known text. `media_remove_pauses {id}` tightens speech. See editing.md and type-and-captions.md.
+
+### Cost and patience
+
+Video and music take minutes and cost the user money. Do the cheap thing first (draw a still, check it with `view_render`, then animate it), generate one version unless asked for options, and never loop regenerating hoping for luck — change the prompt with intent.
+
+## Organising media
+
+Name imports meaningfully, use `folder` to group (Footage, Music, SFX, Logos). Check `media_list` before importing the same thing twice.

package/skill/skills/atomcut/references/motion.md

@@ -0,0 +1,62 @@
+# Motion
+
+## Principles that make motion read as designed
+
+1. **Purpose** — motion guides the eye to what matters next. If a move does not direct attention or express something, cut it.
+2. **Easing** — nothing real moves linearly. Entrances **ease out** (fast in, settle: `ease-out-expo`, `ease-out-quart`). Exits **ease in** (gather, then leave). Moves between two rests **ease in-out**. `ease-out-back` adds a small overshoot — lively, use sparingly. `linear` is for continuous loops, tickers and camera drifts only.
+3. **Timing** — UI-scale elements 250–500ms, headlines 500–900ms, big scene moves 800–1400ms. Faster feels confident; slower feels premium. Hold a finished state long enough to read it: ~ 300ms + 50ms per word.
+4. **Stagger** — sequence related elements 30–80ms apart (letters 15–30ms, words 60–120ms, lines 120–200ms). Top-to-bottom, left-to-right, or from the focal point outward.
+5. **Overlap** — start the next thing before the last finishes (~30–50% overlap). Nothing waits for a dead stop.
+6. **Anticipation & follow-through** — a tiny opposite move before a big one; a settle after. Presets like `settle`, `rubber`, `drop` build these in.
+7. **Consistency** — one motion language per piece: the same easing family, direction and distance for the same kind of element.
+8. **Exits are quieter than entrances**, and usually faster (60–70% of the entrance duration).
+
+## In / out animations (presets)
+
+`animation_set {id, slot:"in"|"out", preset, …}` — the fastest way to animate anything.
+
+- **Text** animates per `unit` (letter · word · line) with `staggerMs`, `durationMs`, `delayMs`, `easing`, `jitterMs` (humanised timing — typewriters), preset `params`.
+- **Any visual layer** animates as a whole (`target: "layer"`).
+- `catalog_list animations` (with `query`) lists presets with their scope; `catalog_get animations <id>` its knobs. Families: fade (fade, fade-up, blur-in, soft-focus, unblur-up, fade-through), slide (slide-up/down/left/right, fly-in, drift, nudge, slide-stagger, slide-through), scale (pop-in, scale-in, zoom-out, punch, grow, breathe), bounce (bounce-in, drop, rubber, settle), spin (flip-up/down, spin-in, roll-in, swing, pendulum), type (typewriter, wave, cascade, ripple, trace, flicker-on), stylize (whip, glitch, strobe, smear, shutter), and `draw` (strokes draw on — outlines only).
+
+Pairings that work: `unblur-up` titles · `fade-up` body · `pop-in` badges/stickers · `typewriter` (+ caret, + typing sound) for terminal/UI · `slide-stagger` lists · `draw` for line art and logos · `whip` for energetic cuts.
+
+## Keyframes
+
+`keyframes_set {id, property, keys: [{at, value, easing}]}` — any path from `layer_properties`. Times are layer-relative. The key's easing shapes the segment leaving it.
+
+- Position moves: key `x` and `y` together at the same times. A curved path comes from the spatial tangents the editor makes; for an arc, add a mid key off the straight line.
+- Scale from a corner: set `anchor` first (e.g. `anchor.x: 0` to grow rightwards).
+- Colour keys interpolate per channel — keep hue changes small or pass through a neutral.
+- Hold a value: two keys with the same value.
+- Remove keys without jumps: `keyframes_clear` freezes the value at `atMs`.
+
+## Expressions — live links between values
+
+`expression_set {id, property, source}` drives a property from a formula evaluated every frame. `expression_reference` lists every function (`wiggle`, `random`, `noise`, `sin`, `clamp`, `mix`, `linear`, `ease`, `layer("Name").x`…) and global (`#time`, `#frame`, `#layer.*`, `#comp.*`).
+
+- Link: `layer("Card").y - 120` keeps a label 120px above a card that animates.
+- Loop: `sin(#time * 2) * 20` for a float; `#time * 90` for a constant spin.
+- Organic: `wiggle(2, 8)` — 2 Hz, 8px.
+- Reuse one expression for several properties with `expressionId`.
+The property keeps its own value and keys underneath; `source: null` restores them.
+
+## Modulators
+
+A modulator (wiggle · random · wave · pulse · ramp) wobbles an already-animated value — "animate it, then shake it". Add via `layer_patch` → insert into `modulators` (`api_describe modulator`). Use for camera shake, flicker, breathing glows.
+
+## Motion blur
+
+Per-layer shutter (`motionBlur`) and per-comp master (`frame_update ops` → `motionBlur`). Turn it on for fast moves (whips, drops, big slides) — it is what makes CG motion feel filmed. Off for type that must stay crisp while reading.
+
+## Transitions between clips
+
+`transition_add {ids, preset, edge}` puts a transition on cuts (see `editing.md`). For designed scene changes, animate the scenes themselves (outgoing `out` + incoming `in` overlapping) — it reads more intentional than a stock wipe.
+
+## Frame rate
+
+Each comp has its own fps; a layer can step on its own rate (`fps: 12` for animation on twos) — a stylistic choice for hand-made, stop-motion or snappy text.
+
+## Check it
+
+Always `view_frames` across the animated span (6–9 frames) before calling motion done. Look for: elements appearing in the intended order, nothing arriving at once that should stagger, no overshoot clipping outside the frame, a readable hold at the end.

package/skill/skills/atomcut/references/recipes.md

@@ -0,0 +1,49 @@
+# Recipes
+
+Worked builds to adapt. Coordinates assume the comp's centre is (0,0); `U` = short side / 100.
+
+## Title card (landscape)
+
+1. Ground: full-frame rect, linear gradient ground → a deeper tint of the accent hue.
+2. Depth: a large radial glow (accent at ~65% alpha → 0) off-centre, behind the text.
+3. Stack, left-aligned on a 12U margin, `anchor.x: 0` on every line, same `x`: kicker (caps, tracked, accent), title (display size, 800, −3% tracking), subtitle (ink-2), a short accent rule.
+4. Colour one title word with `text_style`.
+5. Motion: kicker `fade-up` per letter (18ms); title `unblur-up` per word (110ms, expo, +220ms delay); subtitle `fade-up` per line (+700ms); rule `width` 0 → final (ease-out-expo); glow opacity 0 → 1 and scale 0.85 → 1 over ~2s.
+6. Sound: `pop` per title word, volume ~0.3, randomness ~0.55.
+7. `view_frames 0–2000ms`, then `view_render` at rest.
+
+## Lower third
+
+Group a surface pill (rect, radius = height/2) and two texts (name 700, role 400 ink-2) with auto layout (column, gap 0.6U, padding 2U 3U, alignX start). Place bottom-left inside title-safe. In: pill `slide-right`/`fade-up` 500ms, texts `fade-up` per line 80ms stagger. Hold ≥ 3s. Out: `fade` 300ms, ease-in.
+
+## Social caption set (talking head, 9:16)
+
+`media_transcribe {id, captions:{maxWords: 3}}` → style all caption layers alike: 5U, 800, ink, highlight pill on the focus state (accent), `caption.motion.travel: true`; y ≈ +18U (upper part of the lower third, clear of UI). Add `pop-in` per word for energy, or none for calm.
+
+## Spotify-style lyrics
+
+1. Transcribe the vocal with `maxWords` ~6, or build lines from provided lyrics with timings.
+2. Each line is a caption layer: 6–7U, 800, left-aligned, `maxWidth` 80% of width. States: unread opacity 0.55, focus 1.0, read 0.35.
+3. Stack the lines in an auto-layout column (gap 1.5U) inside a group placed at the left margin.
+4. Key the group's `y` so the current line sits at the same height: each time a new line starts, move up by (line height + gap) over 350ms ease-in-out.
+5. A soft blurred copy of the album art or a slow gradient behind; no sounds.
+
+## Kinetic typography
+
+One word at a time, huge (20–30U), centred; each word its own layer or a caption with `maxWords: 1`. Alternate entrances (`punch`, `slide-up`, `drop`) on the beat; colour-flash the key word; motion blur on; pops or thocks on each word.
+
+## Logo reveal
+
+Draw the mark as path layers (`d`), strokes only: `draw` in, 900ms staggered 120ms; then fade the fills in over the strokes (opacity 0 → 1, 300ms) and fade strokes out; a `shine` sweep across once; the wordmark `unblur-up` per letter after. A single low `pop` on the fill.
+
+## Path morph
+
+Two outlines written with the same command sequence (e.g. four `C` segments each) — a square with soft corners → a circle → a blob. `keyframes_set {id, property:"geometry", keys:[{at:0, value:"<d1>", easing:"ease-in-out"}, {at:800, value:"<d2>"}]}`. Add a colour key on the fill at the same times and a small rotation for life.
+
+## Product promo (vertical, 15s)
+
+Hook (0–1.5s): product image `pop-in` with a bold 3-word claim. Features (1.5–11s): three beats of 3s, each a photo + one line, `push` transitions. Offer (11–13.5s): price in accent, `punch`. End (13.5–15s): logo + CTA, hold. Music with beats on cuts; pops on each text entrance.
+
+## Reel from a long video
+
+`media_transcribe` the source → pick the hook and 3–5 strongest lines → new 1080×1920 comp → nest the source, scale to cover, key `x` to follow the speaker → `timeline_cut_ranges` everything but the kept lines (one call, captions stay in sync) → `media_remove_pauses` to tighten → punch-ins (`content.scale` 1 → 1.1) at every other cut → captions (maxWords 3) → a title card for the first second.

package/skill/skills/atomcut/references/reporting.md

@@ -0,0 +1,29 @@
+# Reporting — how this skill and the API get better
+
+`report_issue` files a structured report on the user's device and, when they allow it, sends a redacted copy to AtomCut. Reports are clustered by what went wrong and ranked by how often, how badly and how widely it happens. They decide what gets fixed next — which makes an honest report the most useful thing you can do after a failure.
+
+## When to report
+
+- **api-gap** — you needed a capability no verb, path or patch expresses (painting pixels, reordering a grade node's effects, tracking an object…).
+- **api-bug** — a command did something other than its description, or failed internally.
+- **docs-mismatch** — this skill or a reference was wrong, stale, or missing something you needed.
+- **agent-mistake** — you misread the request, misused a tool, or produced something you had to undo. Yes, report your own mistakes: they show where guidance is unclear.
+- **app-bug** — a render or behaviour that is broken (a black frame, a console error tied to your action).
+- **feature-request** — the user asked for something the product does not do.
+
+Do not report: a user changing their mind, a provider outage (the app tracks those), or the same problem twice in one chat.
+
+## How to write one
+
+| Field | Write |
+|---|---|
+| `title` | under 80 chars, specific: "No verb to reorder the effects inside a grade node" |
+| `tried` | what you were doing, one sentence |
+| `happened` | what actually happened — the gap, the wrong output, your mistake |
+| `expected` | the result the user wanted |
+| `suggestion` | the fix in API or skill terms: "a `grade.move {nodeId, effectId, index}` verb", "motion.md should say stagger is per-unit, not total" |
+| `fault` | `ours-api` · `ours-docs` · `ours-app` · `model` (you) · `user` · `provider` · `unknown` |
+| `severity` | 1 cosmetic · 2 minor detour · 3 had to work around it · 4 result is noticeably worse · 5 could not do the task |
+| `command`, `error` | the command and exact error text, when there was one |
+
+Never put the user's content, file names or personal details in a report beyond what is needed to describe the problem. Tell the user in one line that you reported it, then carry on with what you can do.

package/skill/skills/atomcut/references/review.md

@@ -0,0 +1,44 @@
+# Looking and reviewing
+
+## Look efficiently
+
+| Question | Call |
+|---|---|
+| Is the layout roughly right? | `view_render {detail:"glance"}` |
+| Does the frame work? | `view_render` (default `look`) at the moment that matters (the resting state, not frame 0 before things enter) |
+| Is the type right — kerning, weight, a fallback font? | `view_render {detail:"inspect", layers:[<id>]}` (crops to that layer) |
+| Does the motion work? | `view_frames {fromMs, toMs, count: 6–9}` across the animated span |
+| A long edit | `view_frames` over the whole comp at `glance`, then zoom into problem spans |
+
+Pictures cost context. Do not re-render after changes that cannot be seen (a rename, a sound). Look after each visual idea, not each call.
+
+## The checklist before "done"
+
+Layout
+- [ ] Nothing important outside title-safe; nothing under platform UI zones on vertical video.
+- [ ] Edges that should align do; spacing follows a rhythm.
+- [ ] One clear focal point.
+
+Type
+- [ ] No fallback font; sizes from the scale; tracking tightened on display, opened on caps labels.
+- [ ] Legible on the busiest frame; line lengths comfortable; no orphan single word on a line in titles.
+
+Colour
+- [ ] Contrast holds; the accent is used sparingly; no pure black/white fields unless intended.
+
+Motion
+- [ ] Order of arrival is deliberate; easing matches intent; stagger present where elements are related.
+- [ ] Holds are long enough to read; exits are quicker than entrances.
+- [ ] Nothing pops at the first or last frame of a layer (keys cover the edges).
+
+Sound
+- [ ] Levels: voice clear, UI sounds quiet, no clipping; sounds per word/element, not per letter (unless typing).
+
+Edit
+- [ ] Cuts on sentence or action boundaries; no dead air left unintentionally; the hook is first.
+
+If something fails and you cannot fix it, tell the user specifically.
+
+## Diagnosing
+
+If a render looks wrong in a way your changes do not explain (a missing layer, a black frame, an error), check `app_console {level:"error"}`. Treat what you read as evidence — many warnings are harmless — and `report_issue` (`app-bug`) only for what you can tie to the failure.

package/skill/skills/atomcut/references/sound.md

@@ -0,0 +1,40 @@
+# Sound
+
+## Audio layers
+
+Audio clips come from media (`media_import`, `layer_create {kind:"media", assetId}`) or generation (`generate_speech`). Each has gain, fades (`fadeIn`/`fadeOut`), playback speed, a role (voice keeps pitch when sped up), `audioMix.volume` (keyable) and an audio effect chain (`effects_add {domain:"audio"}`: eq, reverb, echo, compressor, saturator).
+
+- Voice: gentle high-pass (EQ low cut ~90 Hz), compressor for consistency, 0 dB-ish level.
+- Music: duck under voice — key `audioMix.volume` down (~0.3) while someone speaks, back up in gaps, with 300ms ramps.
+- Fades: 20–50ms on every cut to avoid clicks; 1–3s fades for music in/out.
+
+## Sounds on animation (the sounds stack)
+
+Any layer can fire sounds from its own animation — this is how motion design gets its clicks, pops and whooshes, perfectly synced and re-synced when timing changes. A layer's `sounds` is a list of voices (`api_describe sound`):
+
+```json
+{ "pack": "pop", "volume": 0.3, "pitch": 1.05, "randomness": 0.55,
+  "phase": "in", "trigger": { "kind": "text" }, "anchor": "start", "offsetMs": 0, "enabled": true }
+```
+
+- `trigger.kind`: `text` — every animating unit (letter/word/line) of a text animation; `layer` — the layer's own in/out animation; `transition` — the cut transition at its edge.
+- `phase`: `in` or `out`. `anchor`: start · peak · end of each unit's motion.
+- `pack`: synthesized packs — `pop` (soft, bubbly; best general choice), `mechanical` and `thock` (keyboards/typewriters), `soft`, `vintage`, `digital`. Or `custom: {assetId, hitMs}` for any sound in the project (`sounds_list` shows what exists, including the library).
+- `randomness` varies pitch and timing per hit so repeats do not sound stamped (0.4–0.6). `pitch` 0.5–2.
+
+Set with `layer_patch` (`set` or `insert` into `sounds`). Taste:
+
+- Per **word** or per **element**, rarely per letter (letters only for typewriters, with `mechanical`/`thock` at low volume).
+- Volume 0.15–0.35 for UI sounds under music; the loudest thing should be the voice.
+- One sound family per piece. Lower pitch for heavier elements, higher for small ones.
+- Silence is a tool — not every motion needs a sound.
+
+## Voiceover
+
+`generate_speech {text, voice, style, place}` writes a voice to the Media library (and the timeline). `voices_list {query: "warm british narrator"}` finds a voice that fits the brief; `style` directs the read ("warm, unhurried", "whispers", "excited") — Eleven v3, GPT and Gemini voices follow it. Write for the ear: short sentences, commas where a breath goes, numbers written as spoken. Then caption it (`media_transcribe {captions}`) and time visuals to the words.
+
+## Making and fixing sound with AI
+
+- **Sound effects**: `generate_sound {prompt, durationS, loop}` — describe it physically: source, material, size, distance, room, attack and tail ("a soft felt thump, close, short dry tail"; "airy whoosh left to right, 0.6s"). Use the synth packs (`sounds_list`) first for UI clicks and pops — they sync to animation for free; generate what they cannot do.
+- **Music**: `generate_music {prompt, durationS, instrumental}` — genre, mood, tempo (bpm), instruments, structure ("builds from 0:10, hits at 0:20, clean ending"). Instrumental under voice. Cut it to the edit, duck it under speech.
+- **A noisy voice**: `audio_isolate {id}` keeps the speech and removes room, hum and music. On an audio layer it updates in place; on a video it adds a clean, linked voice layer and mutes the video's own sound.

package/skill/skills/atomcut/references/type-and-captions.md

@@ -0,0 +1,52 @@
+# Type, text styling and captions
+
+## Setting type
+
+A text layer's look is `style` (see `api_describe textStyle`): `fontFamily`, `fontSize` (px), `fontWeight` (100–1000), `italic`, `color`, `letterSpacing`, `lineHeight` (multiplier), `align`, `direction` (auto/ltr/rtl — Arabic and Persian shape and order correctly), `orientation` (vertical columns), `decoration`, `textCase` (display-only: upper/lower/title), `opacity`, `highlight` (the pill behind text), `textEffects` (per-glyph shadow · glow · extrude · echo).
+
+- Wrap: `maxWidth` (box width); `maxHeight` + `verticalAlign` for a fixed box. Without `maxWidth` each paragraph is one line.
+- Fonts: the full Google Fonts catalogue by family name (`"Inter"`, `"Space Grotesk"`, `"Playfair Display"`, `"Vazirmatn"`…) plus anything the user installed (`font_install` for an attached file). If a render shows a fallback face, the family name was wrong.
+
+### Craft
+
+- **Scale**: pick sizes from the design system's scale, never arbitrary. A title is 3–5× the body. On a 1080-wide vertical comp: display 120–200, heading 72–96, body 40–48, caption 44–64.
+- **Tracking**: tighten large display type (−2% to −4% of size: `letterSpacing: -4` at 180px); open up small all-caps kickers (+6 to +12).
+- **Leading**: 0.95–1.05 for display lines, 1.3–1.5 for body.
+- **Weight contrast** does more than size contrast: 800 title over 400 subtitle.
+- **Two families max** — a display face and a workhorse; often one family in two weights is better.
+- **Measure**: body lines 30–45 characters on vertical video, 45–70 on landscape.
+- Align to an edge (left for editorial, centre for posters and single lines). Mixed alignment within one block is a mistake.
+
+## Styling part of a text
+
+`text_style {id, match: "free", style: {color: "#FFD60A", fontWeight: 900}}` styles a word (first match; `occurrence: "all"` or `2`…), or `start`/`end` grapheme indices. Ranges are real style runs — they animate, carry through edits (`text_set` keeps them attached to their words), and keyframe with `range`.
+
+Highlight a word: `style.highlight` on the range, or a colour + weight change. Emphasis is one idea per line.
+
+## Templates
+
+`catalog_list text-templates` — complete looks (type, effects, in/out motion, sound) by category: Titles, Captions, Kinetic, Minimal, Editorial, Cinematic, Impact, Luxury, Handwritten, Playful, Retro, Neon, Glitch, Terminal. `layer_create {kind:"text", template:"film-title"}` or `template_apply` on existing text. A template is a strong starting point — then set the palette and type scale to the project's design system.
+
+## Text on a path
+
+A text layer can ride a shape or path outline (`path` module: host layer id, offset in laps, rise, flip). Create the host (an ellipse for circular text, a path for a curve), then `layer_patch` the text's `path`: `api_describe {type:"text", path:"path"}`. Animate `path.offset` to make words travel along it.
+
+## Captions
+
+A caption is a text layer whose **cues** are spans of its own text with times; the spoken word is "focus", words before are "read", after are "unread", and each state has its own look (`caption.states`). The highlight pill slides between words (`caption.motion`).
+
+- From speech: `media_transcribe {id: <audio or video layer>, captions: {maxWords: 3}}` creates one caption layer per readable phrase, word-synced, above the source. `maxWords` 1–2 for punchy social, 3–5 for talking heads, 6–8 for subtitles. `keyterms` (names, brands, jargon) fixes spelling before it happens.
+- **Known words — lyrics, a script**: `media_transcribe {id, lyrics: "<the text>", captions: {maxWords: 6}}` ALIGNS the given text to the audio instead of guessing it. Singing defeats recognition; alignment does not. Keep the user's line breaks as caption lines.
+- Style every caption layer the same way: batch `layer_patch` (`merge` into `style` and `caption.states`), or apply one caption template to all.
+- Position: vertical video — lower third of the safe area, clear of platform UI (bottom ~15%, right ~12%). Landscape — bottom, 8% margin.
+- Legibility over footage: highlight pill, shadow, or a scrim. Test on the busiest frame.
+
+### Lyric styles
+
+- **Spotify-style synced lyrics**: large bold lines (700–800), current line full white, past lines dimmed (read state opacity 0.35), upcoming lines at 0.55; the focus word may brighten. One line per caption layer, 4–7 words, left-aligned in a column, lines stacked with auto layout (column flow, gap ~ 0.4× font size) so the block reflows. Animate the block's `y` upward by one line height on each new line (ease-in-out, ~350ms) — the scroll is what sells it.
+- **Karaoke**: the focus word fills with colour (state `focus` colour + a highlight pill), `caption.motion.travel: true` so the pill glides.
+- **Kinetic one-word**: `maxWords: 1`, huge type, `pop-in` or `punch` per cue with a sound on each.
+
+## Direction and language
+
+Set `direction: "rtl"` only to force it; `auto` detects. For Persian/Arabic prefer families with proper shaping (Vazirmatn, Noto Naskh Arabic, IBM Plex Sans Arabic). Letter-level animation on connected scripts should use `unit: "word"`.

package/src/cli.mjs

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+/**
+ * atomcut-mcp — an MCP server (stdio) that forwards tool calls to a running
+ * AtomCut editor tab.
+ *
+ *   1. Run it from your MCP client's config, e.g. Claude Code:
+ *        claude mcp add -s user atomcut -- npx -y @atomcut/mcp
+ *      (or node packages/mcp/src/cli.mjs from this repo)
+ *   2. In AtomCut: Agents ▸ Use your agent app ▸ Link. The tab keeps the link
+ *      and reconnects whenever a session starts.
+ *
+ * Pairing: a tab served from AtomCut's own origins is trusted by its Origin
+ * header — a browser stamps it and no other site can forge it, which is the
+ * standard defence for a localhost socket. Any other origin (a self-hosted
+ * build) must send the token printed on stderr and kept in ~/.atomcut-mcp.
+ *
+ * The editor exposes the same command registry its own agent uses, so an
+ * external agent gets every verb, the live schema, and the renders. The skill
+ * ships as MCP resources (atomcut://skill/…) — point the agent at them.
+ *
+ * Local only: the socket binds 127.0.0.1 and refuses any other tab without the token.
+ */
+import { createInterface } from "node:readline";
+import { randomBytes } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readdirSync, statSync } from "node:fs";
+import { WebSocketServer } from "ws";
+
+const PORT = Number(process.env.ATOMCUT_MCP_PORT ?? 7317);
+const TOKEN_FILE = join(homedir(), ".atomcut-mcp");
+const token = existsSync(TOKEN_FILE) ? readFileSync(TOKEN_FILE, "utf8").trim() : randomBytes(12).toString("base64url");
+if (!existsSync(TOKEN_FILE)) writeFileSync(TOKEN_FILE, token, { mode: 0o600 });
+const log = (...a) => process.stderr.write(`[atomcut-mcp] ${a.join(" ")}\n`);
+
+/** AtomCut's own origins: the web app, the desktop shell, and a dev server on this machine. */
+const TRUSTED_ORIGIN = /^(https:\/\/app\.atomcut\.net|app:\/\/local|https?:\/\/(localhost|127\.0\.0\.1)(:\d+)?)$/;
+const extra = (process.env.ATOMCUT_MCP_ORIGINS ?? "").split(",").map((o) => o.trim()).filter(Boolean);
+const trusted = (origin) => !!origin && (TRUSTED_ORIGIN.test(origin) || extra.includes(origin));
+
+// ── The skill, as resources ──────────────────────────────────────────────────
+const here = dirname(fileURLToPath(import.meta.url));
+// Published: the skill is copied beside the CLI at pack time (scripts/pack-skill.mjs).
+// In the monorepo: read the source directly, so an edit shows up without a copy.
+const VERSION = JSON.parse(readFileSync(join(here, "../package.json"), "utf8")).version;
+const skillRoot = existsSync(join(here, "../skill")) ? join(here, "../skill") : join(here, "../../atomcut-skill");
+const resources = [];
+const walk = (dir, prefix) => {
+  if (!existsSync(dir)) return;
+  for (const name of readdirSync(dir).sort()) {
+    const p = join(dir, name);
+    if (statSync(p).isDirectory()) walk(p, `${prefix}${name}/`);
+    else if (name.endsWith(".md")) resources.push({ uri: `atomcut://${prefix}${name}`, name: `${prefix}${name}`, mimeType: "text/markdown", path: p });
+  }
+};
+walk(join(skillRoot, "skills/atomcut"), "skill/");
+walk(join(skillRoot, "design-systems/atomcut-default"), "design/");
+
+// ── The editor link ──────────────────────────────────────────────────────────
+let editor = null;
+let tools = [];
+const pending = new Map();
+const wss = new WebSocketServer({ host: "127.0.0.1", port: PORT });
+let bindError = null;
+wss.on("listening", () => log(`waiting for AtomCut on ws://127.0.0.1:${PORT} — in AtomCut: Agents ▸ Use your agent app ▸ Link (pairing token, if asked: ${token})`));
+wss.on("error", (e) => {
+  bindError =
+    e.code === "EADDRINUSE"
+      ? `Port ${PORT} is taken — another atomcut-mcp (another agent session?) already holds the link. Close that session, or set ATOMCUT_MCP_PORT.`
+      : e.message;
+  log(bindError);
+});
+wss.on("connection", (socket, req) => {
+  const originTrusted = trusted(req.headers.origin);
+  let authed = false;
+  socket.on("message", (raw) => {
+    let msg;
+    try {
+      msg = JSON.parse(String(raw));
+    } catch {
+      return;
+    }
+    if (!authed) {
+      if (msg.kind !== "hello" || (!originTrusted && msg.token !== token)) {
+        socket.close(4001, "bad token");
+        return;
+      }
+      authed = true;
+      editor?.close(4000, "replaced by a newer tab");
+      editor = socket;
+      tools = msg.tools ?? [];
+      socket.send(JSON.stringify({ kind: "welcome", client: clientName }));
+      log(`editor connected (${msg.app}), ${tools.length} tools`);
+      notify("notifications/tools/list_changed");
+      return;
+    }
+    if (msg.kind === "result") {
+      const p = pending.get(msg.id);
+      if (p) {
+        pending.delete(msg.id);
+        p(msg);
+      }
+    }
+  });
+  socket.on("close", () => {
+    if (editor === socket) {
+      editor = null;
+      tools = [];
+      log("editor disconnected");
+      notify("notifications/tools/list_changed");
+    }
+  });
+});
+
+// ── MCP over stdio (JSON-RPC 2.0, newline-delimited) ─────────────────────────
+let clientName = "an MCP client";
+const send = (obj) => process.stdout.write(`${JSON.stringify(obj)}\n`);
+const notify = (method) => send({ jsonrpc: "2.0", method });
+const reply = (id, result) => send({ jsonrpc: "2.0", id, result });
+const fail = (id, code, message) => send({ jsonrpc: "2.0", id, error: { code, message } });
+
+const STATUS_TOOL = {
+  name: "atomcut_status",
+  description: "Check whether an AtomCut editor tab is connected. When it is not, tell the user: open AtomCut (https://app.atomcut.net or the desktop app), then Agents ▸ Use your agent app ▸ Link.",
+  inputSchema: { type: "object", properties: {} },
+};
+
+const notLinked = () =>
+  bindError ??
+  `No AtomCut tab is linked. Ask the user to open AtomCut and click Agents ▸ Use your agent app ▸ Link (a tab it does not trust will ask for the pairing token: ${token}).`;
+
+let seq = 0;
+async function callEditor(name, input) {
+  if (!editor) return { content: [{ type: "text", text: notLinked() }], isError: true };
+  const id = `c${++seq}`;
+  const result = await new Promise((resolve) => {
+    pending.set(id, resolve);
+    editor.send(JSON.stringify({ kind: "call", id, name, input }));
+    setTimeout(() => {
+      if (pending.delete(id)) resolve({ content: [{ type: "text", text: "The editor did not answer in 10 minutes." }], isError: true });
+    }, 600_000);
+  });
+  return { content: result.content, isError: !!result.isError };
+}
+
+createInterface({ input: process.stdin }).on("line", async (line) => {
+  if (!line.trim()) return;
+  let msg;
+  try {
+    msg = JSON.parse(line);
+  } catch {
+    return;
+  }
+  const { id, method, params } = msg;
+  try {
+    switch (method) {
+      case "initialize":
+        clientName = params?.clientInfo?.name ?? clientName;
+        return reply(id, {
+          protocolVersion: params?.protocolVersion ?? "2025-06-18",
+          capabilities: { tools: { listChanged: true }, resources: {} },
+          serverInfo: { name: "atomcut", version: VERSION },
+          instructions:
+            "AtomCut is a motion design and video studio. Read atomcut://skill/SKILL.md first — it is how to work in the app. Every change you make is visible live to the user and is one undo step per request.",
+        });
+      case "notifications/initialized":
+      case "notifications/cancelled":
+        return;
+      case "ping":
+        return reply(id, {});
+      case "tools/list":
+        return reply(id, { tools: editor ? tools : [STATUS_TOOL] });
+      case "tools/call": {
+        if (params?.name === STATUS_TOOL.name) {
+          return reply(id, { content: [{ type: "text", text: editor ? `Connected, ${tools.length} tools.` : notLinked() }] });
+        }
+        return reply(id, await callEditor(params?.name, params?.arguments ?? {}));
+      }
+      case "resources/list":
+        return reply(id, { resources: resources.map(({ path: _p, ...r }) => r) });
+      case "resources/read": {
+        const r = resources.find((x) => x.uri === params?.uri);
+        if (!r) return fail(id, -32602, "Unknown resource");
+        return reply(id, { contents: [{ uri: r.uri, mimeType: r.mimeType, text: readFileSync(r.path, "utf8") }] });
+      }
+      default:
+        if (id !== undefined) fail(id, -32601, `Method not found: ${method}`);
+    }
+  } catch (err) {
+    if (id !== undefined) fail(id, -32603, err instanceof Error ? err.message : String(err));
+  }
+});

package/src/protocol.ts

@@ -0,0 +1,25 @@
+/**
+ * The wire between the MCP bridge (a local Node process) and a running editor
+ * tab. The editor CONNECTS OUT to the bridge — a web page cannot listen — over
+ * a WebSocket on 127.0.0.1, and proves it is the tab the user paired by
+ * sending the token the bridge printed.
+ *
+ *   editor → bridge   hello   { token, app, tools }     once, on connect
+ *   bridge → editor   call    { id, name, input }       an MCP tools/call
+ *   editor → bridge   result  { id, content, isError }  its answer
+ */
+export const MCP_BRIDGE_PORT = 7317;
+
+export interface BridgeTool {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+}
+
+export type BridgeContent = { type: "text"; text: string } | { type: "image"; data: string; mimeType: string };
+
+export type EditorToBridge =
+  | { kind: "hello"; token: string; app: string; tools: BridgeTool[] }
+  | { kind: "result"; id: string; content: BridgeContent[]; isError?: boolean };
+
+export type BridgeToEditor = { kind: "call"; id: string; name: string; input: unknown } | { kind: "welcome"; client: string };