@pinepaper.studio/mcp-server 1.6.6 → 1.6.8

package/dist/tools/definitions.js

@@ -9,7 +9,7 @@
  */
 import { COMPACT_DESCRIPTIONS } from './compact-descriptions.js';
 import { MINIMAL_DESCRIPTIONS } from './minimal-descriptions.js';
-import { EffectTypeSchema, SimpleAnimationTypeSchema, GEOMETRY_OPERATIONS, } from '../types/schemas.js';
+import { EffectTypeSchema, SimpleAnimationTypeSchema, GEOMETRY_OPERATIONS, THREAD_STITCHES, } from '../types/schemas.js';
 /**
  * Vocabulary lists derived from Zod schemas so tool descriptions stay in
  * sync automatically. The description-schema-parity test
@@ -26,6 +26,11 @@ export const AI_AGENT_GUIDE = `⚠️ You are connected to PinePaper Studio via
 NEVER create standalone HTML pages, React components, or web apps as a substitute. Do NOT use frontend design skills or CSS-only animations instead of PinePaper.
 PinePaper tools ARE the implementation — they generate Paper.js/JavaScript code that runs on the canvas and produce Canvas 2D, SVG, MP4, GIF, PNG exports.
 If a tool fails, report the error — do NOT fall back to generating HTML pages.
+
+THE DOORS THAT ARE OPEN, because four lines of prohibition above this one will otherwise read as a ban on the capability rather than on the substitution:
+- HTML IS a supported output. \`pinepaper_export_widget_html\` exports the scene as a self-contained HTML page, and \`pinepaper_export_widget\` as an embeddable widget. Asked for a web page or an embed, build the scene with tools and export it — that is the intended path, not a workaround.
+- CODE IS a supported input. \`pinepaper_execute_custom_code\` runs Paper.js against the live canvas, and \`pinepaper_execute_generator\` runs a named generator. Reach for them when no tool fits; they are part of the surface, not an escape from it.
+- The rule above is about SUBSTITUTION — writing a CSS animation instead of calling a tool. It is not a rule against the formats themselves, and a model that reads it as one will refuse work this server can do.
 The generated code is shown in tool responses and can be copied into PinePaper's Code Console.
 
 ⚠️ KNOWN CONFLICT: The "frontend-design" plugin instructs agents to generate HTML/CSS pages for visual content. This conflicts with PinePaper. If you keep generating HTML instead of calling PinePaper tools, the user should disable the frontend-design plugin.
@@ -73,6 +78,10 @@ Choose based on mood:
 ─── ITEMS ───
 
 Shapes: circle, rectangle, star, ellipse, triangle, polygon, line, arc, path, pentagon, hexagon, diamond, arrow, heart
+Surfaces (render-time, evaluated per pixel — not shapes): shader, field
+  shader: a lit surface — water, liquid_metal, heatmap, gem_smoke. Set behind:true to put it UNDER the art, which is what scenery wants.
+  field:  one expression, many marks — xExpr/yExpr/count, re-evaluated every frame against t.
+  Both draw fully in a cloud render; locally they stand in as a flat plate.
 Text: text (content, fontSize, fontFamily, color, fontWeight)
   Dynamic text: set contentType on text items → clock (live time), timer (elapsed), countdown (from N seconds), stopwatch (pauseable)
 All items: opacity, shadowColor, shadowBlur, blendMode, strokeColor, strokeWidth
@@ -98,7 +107,7 @@ Photos / raster images (on-device, no upload):
 
 ─── ANIMATION (all in batch) ───
 
-Loop presets (animate): pulse, rotate, bounce, fade, wobble, slide, typewriter
+Loop presets (animate): bounce, breathe, fade, glow, jelly, path, pulse, rotate, scrollDown, scrollLeft, scrollRight, scrollUp, shake, slideLeftRight, slideUpDown, swing, typewriter, wobble
 Keyframe (keyframe_animate): [{time, properties, easing}] → opacity, scale, scaleX, scaleY, x, y, rotation, fillColor, strokeColor, fontSize
 Relations (relation): orbits, follows, attached_to, points_at, mirrors, parallax, wave_through, morphs_to, group_morphs_to, moves_along_path, is_midpoint_of, is_circumcenter_of, construction_reveal (+ geometric constraints & more in batch_execute schema)
 Masks (apply_mask): wipeLeft, wipeRight, wipeUp, wipeDown, iris, irisOut, star, heart, curtainHorizontal, curtainVertical, cinematic, diagonalWipe, revealUp, revealDown
@@ -165,7 +174,7 @@ Measurement: pinepaper_measurement — rulers, grid, snap-to-grid, get item dime
 ─── CANVAS & EXPORT ───
 
 Presets: instagram (1080x1080), youtube (1920x1080), tiktok (1080x1920), twitter (1200x675)
-Export: pinepaper_agent_export (SVG/PNG/GIF/MP4/WebM/PDF), pinepaper_export_svg
+Export: pinepaper_agent_export (SVG/PNG/GIF/MP4/WebM/PDF, plus WAV for the soundtrack alone), pinepaper_export_svg
 Widget: pinepaper_export_widget (pp:PinePaper ontology JSON), pinepaper_export_widget_html (self-contained HTML with tree-shaken runtime)`;
 /*
  * The AI_AGENT_GUIDE constant above is included as a comment in verbose/compact modes
@@ -368,6 +377,28 @@ ITEM TYPES:
 - diamond: 4-sided diamond/rhombus (properties: radius, color)
 - arrow: Right-pointing block arrow (properties: width, height, color)
 - heart: Heart shape (properties: color)
+- disk: Filled disk — the region inside a circle (properties: radius, color)
+- circle-outline: The circle CURVE — stroked, no interior (properties: radius,
+  strokeColor, strokeWidth)
+- arrow-right: Alias for arrow — the same definition under the name the shape
+  grids use. Identical output; both are listed because both are accepted.
+
+SPEECH AND ANNOTATION SHAPES — the engine draws these; use one instead of
+hand-building an outline from a path. All take width, height and color, and the
+descriptions below are the engine's own. The six with a tail also take
+tailDirection (bottom-left | bottom-right | bottom | top-left | top-right | top
+| left | right) and tailSize (0-1, default 0.35):
+- speech-bubble: Classic round speech bubble with triangular tail.
+- speech-bubble-square: Rectangular speech bubble with sharp corners and
+  pointed tail.
+- speech-bubble-pointed: Tooltip-style bubble with arrow pointer (tail defaults
+  to "bottom").
+- thought-bubble: Cloud-like thought bubble with trailing dots.
+- comment-box: Modern chat message bubble with high corner radius.
+- callout-box: Annotation callout with narrow arrow (tail defaults to "left").
+- double-bubble: Two overlapping bubbles for conversation (properties:
+  secondaryColor).
+- quote-bubble: Stylized bubble with quotation marks.
 
 PATH FOR CUSTOM SHAPES:
 Use itemType: "path" with either:
@@ -397,6 +428,24 @@ Items on the canvas can originate from multiple sources — all become first-cla
 - pinepaper_import_asset: Pre-made asset import → becomes a full item
 All imported items participate in the relation and animation systems just like natively created items.
 
+RENDER-TIME SURFACES — 'shader' and 'field':
+These are not shapes. A shape is built as an item and drawn from its geometry; a
+surface has no geometry — it is evaluated, per pixel or per sample, as each frame
+is drawn. Use them for things a vector cannot be: an open sea, a drifting field
+of marks, a lit material.
+- shader: pick one of water | liquid_metal | heatmap | gem_smoke, give it width
+  and height, and set behind:true to place it UNDER the vector art — which is
+  what scenery wants, a sea the boats float ON rather than a sheen over them.
+- field: xExpr/yExpr/count draw many marks from one expression, re-evaluated
+  every frame against t. rExpr and aExpr vary size and alpha per mark.
+Both draw fully in a cloud render; on a local canvas they stand in as a flat
+plate of their own colour so the layout still reads.
+
+LIFETIMES — bornAt and ttl, on any item:
+The only way to build a piece that CUTS between shots. Without them every item
+is on screen for the whole render, which is what makes a long piece read as one
+crowded frame instead of a sequence.
+
 WORKFLOW TIP:
 After creating items, use pinepaper_add_relation to animate them (e.g., orbits, follows, attached_to).
 For glossy 3D spheres, use pinepaper_create_glossy_sphere instead. For diagonal stripes, use pinepaper_create_diagonal_stripes.`,
@@ -405,8 +454,8 @@ For glossy 3D spheres, use pinepaper_create_glossy_sphere instead. For diagonal
             properties: {
                 itemType: {
                     type: 'string',
-                    enum: ['text', 'circle', 'star', 'rectangle', 'triangle', 'polygon', 'ellipse', 'path', 'line', 'arc', 'pentagon', 'hexagon', 'diamond', 'arrow', 'heart'],
-                    description: 'Type of item to create',
+                    enum: ['text', 'circle', 'star', 'rectangle', 'triangle', 'polygon', 'ellipse', 'path', 'line', 'arc', 'pentagon', 'hexagon', 'diamond', 'arrow', 'heart', 'disk', 'circle-outline', 'arrow-right', 'speech-bubble', 'speech-bubble-square', 'speech-bubble-pointed', 'thought-bubble', 'double-bubble', 'quote-bubble', 'comment-box', 'callout-box', 'shader', 'field'],
+                    description: "Type of item to create. 'shader' and 'field' are RENDER-TIME SURFACES drawn per pixel by the cloud renderer — locally they stand in as a flat plate. See the shader/field properties below.",
                 },
                 position: {
                     oneOf: [
@@ -429,7 +478,33 @@ For glossy 3D spheres, use pinepaper_create_glossy_sphere instead. For diagonal
                 },
                 properties: {
                     type: 'object',
-                    description: 'Type-specific properties (content, radius, color, fontSize, etc.)',
+                    description: `Type-specific properties (content, radius, color, fontSize, etc.)
+
+LIFETIME — on ANY item, and the only way to build a piece that CUTS between shots:
+- bornAt: seconds. The item does not exist before this instant.
+- ttl: seconds it lives for. Omit for "until the end".
+Without these every item is on screen for the whole render, which is what makes
+a long piece read as one crowded frame instead of a sequence of shots.
+
+SHADER (itemType 'shader') — a lit surface, drawn per pixel:
+- shader: 'water' (open sea, lit swell) | 'liquid_metal' (chrome) | 'heatmap' (thermal halo) | 'gem_smoke' (smoke) | 'electric_arc' (branching discharge, stepped flicker) | 'vortex' (hollow bright RING, sheared by differential rotation) | 'rain_veil' | 'caustics' | 'ink_bleed'
+- width, height: the quad it fills
+- shaderIntensity: 0..2, the effect's amplitude (water: chop)
+- shaderPalette: 0 day | 1 low sun | 2 night
+- behind: true draws it UNDER the vector art, which is what scenery needs —
+  a sea the boats float ON rather than a sheen laid over them. Default false.
+
+FIELD (itemType 'field') — one expression, many marks. The generative form:
+a whole surface as a function of the sample index and the clock, rather than
+thousands of authored items.
+- xExpr, yExpr: expressions for each mark's position
+- rExpr, aExpr: optional radius and alpha per mark. A radius <= 0 is skipped,
+  so subtracting a threshold draws only the crests of a wave.
+- count: how many marks (up to 200000)
+- Variables in scope: i (0..count-1), n (count), t (seconds), u (i/n), pi, e, tau.
+  Functions: sin cos tan asin acos atan sinh cosh tanh exp ln log10 log2 sqrt
+  cbrt abs floor ceil round sign atan2 min max pow hypot, and % for modulo.
+- Example — a rolling swell: xExpr "(i % 120) * 8", yExpr "400 + sin((i % 120) * 0.4 - t * 2) * 12", count 3600`,
                     additionalProperties: true,
                 },
                 data: {
@@ -443,7 +518,7 @@ For glossy 3D spheres, use pinepaper_create_glossy_sphere instead. For diagonal
                 },
                 animationType: {
                     type: 'string',
-                    description: "Animation type to apply on creation (e.g., 'pulse', 'bounce', 'rotate', 'fade', 'wobble', 'slide', 'typewriter', 'keyframe')",
+                    description: "Animation type to apply on creation (e.g., 'pulse', 'bounce', 'rotate', 'fade', 'slideLeftRight', 'scrollUp', 'typewriter', 'keyframe'). NOT 'slide' — that has never existed; the driver silently does nothing with an unknown type.",
                 },
                 animationSpeed: {
                     type: 'number',
@@ -509,6 +584,7 @@ MODIFIABLE PROPERTIES:
 - shadowBlur: Shadow blur radius
 - shadowOffset: Shadow offset [x, y]
 - blendMode: Blend mode (normal, multiply, screen, overlay, etc.)
+- pathData: SVG path data — RESHAPE the geometry itself, not just its styling. This is how you straighten a hand-drawn box or correct a traced outline without deleting and recreating the item, which would lose its id and every relation and keyframe pointing at it. Requires an FxTool build from 2026-08 or later: before that the property was silently dropped while the same call applied the fill and stroke and reported success.
 
 GRADIENT OBJECT FORMAT:
 {type: "linear"|"radial", stops: [{color: "#fff", offset: 0}, {color: "#000", offset: 1}], origin: [x,y], destination: [x,y]}
@@ -734,6 +810,56 @@ EXAMPLES:
     // ---------------------------------------------------------------------------
     // LAYER 1 — ATOMS: IMPORT TOOLS
     // ---------------------------------------------------------------------------
+    {
+        name: 'pinepaper_import_motion_capture',
+        annotations: {
+            title: 'Import Motion Capture (BVH)',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+        description: `Import a BVH motion-capture clip (CMU, Mixamo) as an animated skeleton, or retarget one onto a rig that already exists.
+
+TWO MODES, and picking the right one is the whole decision:
+- mode:'import'   → builds a NEW skeleton shaped like the capture file. Use when there is no character yet.
+- mode:'retarget' → drives an EXISTING rig named by skeletonId. Proportions stay the character's; only the MOTION comes from the clip. Use whenever the character already exists.
+
+USE WHEN:
+- The user supplies a .bvh clip, or asks for real captured motion rather than a simple animationType
+- A rigged character should perform a walk / run / gesture
+- Simple animation (pulse, bounce, rotate) is too coarse for the request
+
+DO NOT USE FOR:
+- Simple property animation → pinepaper_animate
+- Timed keyframe tracks you author yourself → pinepaper_keyframe_animate
+
+RESULT:
+- import   → { skeletonId, bones, poses, duration }
+- retarget → { skeletonId, matched, unmatchedSource, unmatchedTarget }
+
+BONE MATCHING: a BVH edge is named for the joint it ENDS at, so "LeftLeg" is the thigh and "LeftFoot" the shin — the alias table accounts for this. Anything it cannot place is reported in unmatchedSource/unmatchedTarget rather than silently driving half the rig; pass boneMap to resolve those explicitly.
+
+SAMPLING: CMU records at 120fps. fps defaults to 15 because 120 poses per second is unusable on a canvas timeline; fps:0 keeps every frame.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                bvh: { type: 'string', description: 'BVH clip text.' },
+                mode: { type: 'string', enum: ['import', 'retarget'], description: "'import' = new skeleton from the file; 'retarget' = drive the existing rig in skeletonId, keeping its proportions. Default 'import'." },
+                skeletonId: { type: 'string', description: "Rig to drive. REQUIRED when mode='retarget'." },
+                fps: { type: 'number', description: 'Pose sampling rate; 0 keeps every frame. Default 15.' },
+                height: { type: 'number', description: 'Skeleton height on canvas in px (import mode). Default 320.' },
+                position: {
+                    type: 'object',
+                    description: 'Where the ROOT joint stands (import mode).',
+                    properties: { x: { type: 'number' }, y: { type: 'number' } },
+                },
+                name: { type: 'string', description: 'Name for the created skeleton (import mode).' },
+                boneMap: { type: 'object', description: "BVH edge name → this rig's bone name; overrides the alias table.", additionalProperties: { type: 'string' } },
+            },
+            required: ['bvh'],
+        },
+    },
     {
         name: 'pinepaper_import_svg',
         annotations: {
@@ -1349,7 +1475,11 @@ EXAMPLES:
                 y: { type: 'number', description: 'Canvas origin y (default: canvas center)' },
                 flipY: { type: 'boolean', description: 'Math y-up → screen y-down (default true)' },
                 style: { type: 'object', description: 'Path style forwarded to create (strokeColor, strokeWidth, fillColor, …)' },
-                warp: { description: 'Chained parametric warp(s): { dx, dy } expressions of x, y, t — one object or an array' },
+                solveOde: { type: 'object', description: "Integrate an ODE instead of plotting a closed form, and return the SOLUTION rather than drawing it: { equations, initialState, tEnd?, dt?, method? ('rk4' default, or 'euler' — faster and visibly wrong on anything stiff) }. The trajectory comes back as data, to inspect, feed to a path, or drive keyframes with." },
+                warp: {
+                    anyOf: [{ type: 'object' }, { type: 'array', items: { type: 'object' } }],
+                    description: 'Chained parametric warp(s): { dx, dy } expressions of x, y, t — one object or an array',
+                },
             },
         },
     },
@@ -1384,7 +1514,10 @@ RETURNS: create → { success, action, eventId }; pulse → { success, action, e
                 x: { type: 'number', description: 'Canvas x for the event marker — action create' },
                 y: { type: 'number', description: 'Canvas y for the event marker — action create' },
                 eventId: { type: 'string', description: "Event id to fire — required for action 'pulse'" },
-                payload: { description: "Optional value forwarded to listeners — action 'pulse'" },
+                payload: {
+                    anyOf: [{ type: 'string' }, { type: 'number' }, { type: 'boolean' }, { type: 'object' }, { type: 'array' }],
+                    description: "Optional value forwarded to listeners — action 'pulse'",
+                },
             },
             required: ['action'],
         },
@@ -1795,10 +1928,17 @@ EXAMPLE: { action: 'apply_style', itemId: 'title_1', styleKey: 'arcade', fontFam
         inputSchema: {
             type: 'object',
             properties: {
-                action: { type: 'string', enum: ['apply_style', 'set_font_axes', 'list_styles'], description: 'Text style operation' },
+                action: { type: 'string', enum: ['apply_style', 'set_font_axes', 'list_styles', 'cursive', 'wrap', 'unwrap', 'to_collage'], description: "Text style operation. 'cursive' draws text as STROKED handwriting — a path, not a glyph, so draw-on animation and outline_stroke both apply. 'wrap'/'unwrap' break a text item to a width, reversibly. 'to_collage' converts an EXISTING text item into a letter collage in place." },
+                text: { type: 'string', description: 'cursive: the words to write. to_collage: the text to build from, if it differs from the item.' },
+                maxWidth: { type: 'number', description: 'wrap: the width to break at, in canvas units. unwrap restores the original, so this is not destructive.' },
+                cursiveOptions: { type: 'object', description: 'cursive: { x?, y?, scale?, strokeColor?, strokeWidth? }.' },
+                collageOptions: { type: 'object', description: 'to_collage: style, palette and the rest — same vocabulary as pinepaper_create_letter_collage.' },
                 itemId: { type: 'string', description: 'Text item id — apply_style / set_font_axes.' },
                 styleKey: { type: 'string', description: 'apply_style: style name from list_styles.' },
-                palette: { description: 'apply_style: named colourway (string) or explicit color array.' },
+                palette: {
+                    anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
+                    description: 'apply_style: named colourway (string) or explicit color array.',
+                },
                 variant: { type: 'number', description: 'apply_style: variation index within the style.' },
                 content: { type: 'string', description: 'apply_style: replace the text while styling.' },
                 fontFamily: { type: 'string', description: "apply_style: font override; 'suggested' = the face the style was designed around." },
@@ -1808,6 +1948,137 @@ EXAMPLE: { action: 'apply_style', itemId: 'title_1', styleKey: 'arcade', fontFam
             required: ['action'],
         },
     },
+    {
+        name: 'pinepaper_design_medium',
+        annotations: {
+            title: 'Design Medium (What Makes The Marks)',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `The THIRD design axis: the MEDIUM — what physically makes the marks.
+
+Register is which design language a piece speaks; level is how well it is executed; a medium is a set of physical constraints that produce characteristic marks. All three are independent: an embroidered schematic is a technical register at a refined level in a thread medium, and no single better/worse ranking can say that.
+
+READ THIS BEFORE PROMISING A MEDIUM. Naming a medium does not create its marks. Every medium declares a FIDELITY:
+- native — the characteristic marks ARE vector geometry (vector, thread, ink, cutPaper)
+- stylised — a recognisable impression; the limitation is stated on the entry (charcoal, oil)
+- absent — no vertex-level expression; the tool REFUSES with the reason instead of producing flat shapes in its colours (encaustic)
+
+Call resolve before telling a user you will render in a medium. "yes, but as an impression" is the true answer for half of them, and a flat approximation misrepresents a medium rather than approximating it.
+
+ACTIONS:
+- list_media: every medium with fidelity, definition and limitation. Read it rather than assuming a fixed set — the catalogue grows (hatch and watercolor are recent additions).
+- resolve: { medium } → { ok, fidelity, reason, markMaker }. ok:false with a reason is a real answer — pass it on rather than trying anyway.
+- list_stitches: the 4 thread stitches with their params.
+- apply_thread: render an item in thread. Its own silhouette is the region and its own fill is the thread colour, so an existing drawing becomes stitched rather than needing to be redrawn. The source is HIDDEN, not destroyed.
+- apply_hatch: rule an item with hatching. Same deal — silhouette is the region, source is hidden, re-hatching replaces.
+- list_flow_fields: the 7 fields that bend a hatch line.
+- list_hatch_options: the hatch defaults.
+
+THE DIRECTION FIELD IS THE WHOLE THING. Stitches that all lie the same way are hatching; stitches that follow the form are needlepainting. Use { kind: 'radial', cx, cy } for anything that radiates (a flower, an eye), { kind: 'spine', spine: [...] } to run them along a midrib or feather shaft, { kind: 'constant', angle } when you actually want flat hatch.
+
+STITCH CHOICE: longAndShort (default) is the shading fill — the length variance IS the blend. satin spans the shape edge to edge in one sheet, which is right for a petal or a letter stroke and wrong for a round shape. seed is texture, not direction. stem is an OUTLINE mark and leaves the interior bare — that is the stitch, not a bug.
+
+An unknown stitch is refused rather than defaulted, and re-stitching an item REPLACES its previous stitching instead of stacking.
+
+HATCHING STATES VALUE THROUGH LINE DENSITY, not colour. The same shape at distance 6 and at distance 3 reads as light and dark with nothing else changed — that is the whole medium, and it is why distance is the parameter to reach for rather than a lighter ink. gradient makes the density fall off across the shape, which is a shaded ramp rather than a flat tone.
+
+The straight ruling is what a printer makes; flowField is what makes it read as DRAWN. hand is the small correlated wander of a hand-drawn line, waves for water/hair/contours, spiral for wood grain around a knot, columns for rake marks. continuous joins the whole set into one serpentine path — a pen that never leaves the paper, and one item instead of many.
+
+Hatching needs a CLOSED outline. Text has none: convert it to glyph paths (pinepaper_text_style) and hatch the result. A group is hatched child by child, up to 40 paths; past that the result says so rather than quietly stopping.
+
+Note that a thread field and a hatch flowField are different things and are named differently for it: 'field' steers stitches around a form, 'flowField' bends a ruling line the way a hand drifts.
+
+EXAMPLE — a hatched shadow side, drawn rather than printed:
+{ "action": "apply_hatch", "itemId": "item_3", "distance": 3, "angle": 30, "flowField": "hand", "rand": 0.2 }
+
+EXAMPLE — a stitched leaf:
+{ "action": "apply_thread", "itemId": "item_3", "stitch": "longAndShort",
+  "field": { "kind": "spine", "spine": [{"x":400,"y":200},{"x":400,"y":520}] },
+  "stitchLen": 26, "variance": 0.45 }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['list_media', 'resolve', 'list_stitches', 'apply_thread', 'apply_hatch', 'list_flow_fields', 'list_hatch_options'], description: 'Medium operation' },
+                medium: { type: 'string', description: 'resolve: vector | thread | ink | watercolor | hatch | cutPaper | charcoal | oil | encaustic. Six are native (vector, thread, ink, watercolor, hatch, cutPaper), two stylised, one absent — call list_media for the live table rather than trusting this line.' },
+                itemId: { type: 'string', description: 'apply_thread / apply_hatch: a closed path, compound path, or a group of them.' },
+                stitch: { type: 'string', enum: [...THREAD_STITCHES], description: "apply_thread: default longAndShort. These six are the stitches the engine publishes; call 'list_stitches' for each one's description and its own parameters. An unknown name is refused rather than quietly stitched as a default fill." },
+                field: { type: 'object', description: "apply_thread: { kind: 'radial'|'spine'|'constant', cx, cy, angle, spine[], across } — default radial from the shape centre." },
+                stitchLen: { type: 'number', description: 'apply_thread: nominal stitch length px (default 18).' },
+                rowGap: { type: 'number', description: 'apply_thread: row spacing px; defaults from thread width so rows abut.' },
+                variance: { type: 'number', description: 'apply_thread: length jitter 0..1 (default 0.35) — the long-and-short shading.' },
+                width: { type: 'number', description: 'apply_thread: thread width px (default 2).' },
+                sheen: { type: 'boolean', description: 'apply_thread: highlight along each stitch (default true).' },
+                color: { type: 'string', description: "apply_thread: thread colour (defaults to the item's fill)." },
+                seed: { type: 'number', description: 'apply_thread: PRNG seed (default 1) — same seed stitches the same way.' },
+                count: { type: 'number', description: 'apply_thread: stitch count for seed/satin.' },
+                slant: { type: 'number', description: 'apply_thread: stitch slant in DEGREES — satin (default 0) and stem (default 22).' },
+                overlap: { type: 'number', description: 'apply_thread: how far consecutive stem stitches overlap (default 0.4) — what makes a stem outline read as rope.' },
+                stagger: { type: 'number', description: 'apply_thread: offsets alternate longAndShort rows (default 0.5) — stops stitch ends lining up into seams.' },
+                gapLen: { type: 'number', description: 'apply_thread: gap between runningSeam stitches, px (default 4) — with stitchLen, the dash rhythm of a machine seam.' },
+                gridSize: { type: 'number', description: 'apply_thread: crossStitch grid pitch, px (default 12) — the size of each X, and so the resolution of the fill.' },
+                roughness: { type: 'number', description: 'apply_thread: hand wobble. Jitters every point of every stitch after the engine lays them, so the fill reads as sewn rather than plotted. 0 is machine-exact; reproducible for a given seed. Applied by the tool, not the engine.' },
+                distance: { type: 'number', description: 'apply_hatch: line spacing px (default 6). THE VALUE CONTROL — 6 vs 3 is light vs dark.' },
+                angle: { type: 'number', description: 'apply_hatch: ruling angle in DEGREES (default 45).' },
+                gradient: { type: 'number', description: 'apply_hatch: 0..1 spacing growth per line (default 0, even) — a shaded ramp rather than a flat tone.' },
+                rand: { type: 'number', description: 'apply_hatch: jitter as a fraction of distance (default 0) — takes the mechanical evenness off.' },
+                continuous: { type: 'boolean', description: 'apply_hatch: join the lines into ONE serpentine path (default false).' },
+                flowField: {
+                    type: 'string',
+                    enum: ['hand', 'curved', 'zigzag', 'waves', 'seabed', 'spiral', 'columns'],
+                    description: 'apply_hatch: bend each line along a flow field — what makes it read as drawn rather than printed.',
+                },
+                t: { type: 'number', description: 'apply_hatch: flow-field time offset — advances the field without changing the seed.' },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'pinepaper_text_effect',
+        annotations: {
+            title: 'Text Effects (37 Character-Level Animations)',
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Animate text CHARACTER BY CHARACTER — 37 effects (terminaltexteffects' vocabulary, reimplemented from source).
+
+⚠️ THIS REPLACES THE TEXT ITEM. Unlike pinepaper_text_style (which ADOPTS the text's registry id), this EXPLODES the text into one item per character and REMOVES the original. Any relation, keyframe, or handle pointing at the source id DIES with it. Pass keepSource: true to leave the original in place. The returned \`ids\` array is your entire new handle set.
+
+ACTIONS:
+- list: {} — the 37 effects as {key, label, definition}. Call this first; effect keys come from here.
+- apply: { itemId, effect, duration?, seed?, gradient?, gradientStops?, gradientDirection?, gradientSteps?, keepSource?, options? } — explode and animate.
+
+WHAT YOU GET: ordinary keyframe-animated items. It scrubs on the timeline, survives undo and session restore, and exports through the existing MP4 / SMIL / Lottie paths — this is not a frame-callback effect that renders on screen and vanishes from your export. Every effect ends AT REST, so \`duration\` is the settle time and the text is readable afterwards.
+
+COLOR: by default the resting characters are painted with a GRADIENT across the text block — that is what the upstream effects do and what their reference frames show. Pass gradient: false to keep the text's authored fill, or gradientStops to choose your own.
+
+DETERMINISM: seed defaults to 1, so the same text + effect + seed animates identically every run. Vary seed for a different scatter of the same effect.
+
+EFFECT KEYS (37): scattered, expand, spray, slice, bouncyballs, pour, slide, print, randomsequence, wipe, sweep, highlight, middleout, fireworks, blackhole, unstable, crumble, rings, swarm, orbittingvolley, overflow, decrypt, errorcorrect, matrix, binarypath, rain, burn, smoke, thunderstorm, bubbles, waves, beams, laseretch, spotlights, synthgrid, vhstape, colorshift.
+
+EXAMPLE: { action: 'apply', itemId: 'title_1', effect: 'decrypt', duration: 3, gradientStops: ['#00ff9c', '#0066ff'] }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['apply', 'list'], description: 'Text effect operation' },
+                itemId: { type: 'string', description: 'apply: the text item to animate (must have non-whitespace content).' },
+                effect: { type: 'string', description: "apply: effect key from 'list'." },
+                duration: { type: 'number', description: 'apply: seconds for the whole effect (default 2.5); ends at rest.' },
+                seed: { type: 'number', description: 'apply: PRNG seed (default 1) — same seed reproduces the animation exactly.' },
+                gradient: { type: 'boolean', description: "apply: false keeps the text's authored fill. Default true (gradient across the block)." },
+                gradientStops: { type: 'array', items: { type: 'string' }, description: 'apply: hex colors overriding the effect gradient.' },
+                gradientDirection: { type: 'string', enum: ['vertical', 'horizontal', 'radial', 'diagonal'], description: 'apply: gradient axis.' },
+                gradientSteps: { type: 'number', description: 'apply: quantization steps in the gradient ramp.' },
+                keepSource: { type: 'boolean', description: 'apply: keep the original text item — use when relations/keyframes reference its id.' },
+                options: { type: 'object', description: 'apply: per-effect knobs, passed through verbatim.' },
+            },
+            required: ['action'],
+        },
+    },
     {
         name: 'pinepaper_crop_image',
         annotations: {
@@ -1981,6 +2252,231 @@ RECIPE — a playable maze: create_tilemap with wall fills → batch_create colo
             required: ['action'],
         },
     },
+    {
+        name: 'pinepaper_design_system',
+        description: `The design vocabulary, as data you can read — and eighteen styles that can build a scene.
+
+TWO DIFFERENT THINGS, kept apart on purpose:
+
+A DESIGN SYSTEM is a real, licensed, versioned product — Material Design 3, IBM Carbon, Shopify Polaris, Fluent 2, Adobe Spectrum, GitHub Primer, USWDS, GOV.UK, Shadcn/Radix, SLDS 2, Tailwind, Chakra and more. Its tokens are facts with a licence attached, in the W3C DTCG format ($value, $type, $description). Twenty-one of them are here. Where a motion curve had to be filled in because the published system does not specify one, the token is marked "pinepaper:authored" — so you can tell a vendor's curve from ours instead of treating both as equally official.
+
+An AESTHETIC STYLE is a look: Bauhaus, Art Deco, Swiss typographic, De Stijl, vaporwave, risograph, brutalist, Memphis, claymorphism, op art, pixel art. No licence, no vendor. Thirty-one are named; eighteen can COMPOSE a scene rather than only be described, and 'list_styles' says which.
+
+- list_systems / get_system: the licensed systems and their tokens, filterable by token type.
+- list_easings: every motion curve across every system as a named easing, with its licence and whether it was authored here. Use these to make a motion match a system it has to sit beside.
+- list_styles / compose: build a titled scene in a style. Layout is decided in this server by a pure function, so 'compose' with draw:false returns the scene and the ops as DATA and draws nothing — read it before committing, the same way pinepaper_story's distill works.
+
+A partial composition reports as a failure with the elements that did not create, rather than as a success with half a poster.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['list_systems', 'get_system', 'list_easings', 'list_styles', 'compose'], description: 'Which design-system operation.' },
+                systemId: { type: 'string', description: "get_system: e.g. 'material_3', 'ibm_carbon', 'uswds'. Call list_systems for ids." },
+                tokenType: { type: 'string', enum: ['dimension', 'duration', 'cubicBezier', 'color', 'fontFamily', 'fontWeight', 'number', 'shadow', 'grid'], description: 'get_system: return only tokens of this DTCG type.' },
+                style: { type: 'string', description: "compose: the aesthetic style, e.g. 'bauhaus_geometric'. Call list_styles for the composable ones." },
+                title: { type: 'string', description: 'compose: the headline most styles build around.' },
+                subtitle: { type: 'string', description: 'compose: the supporting line.' },
+                body: { type: 'string', description: 'compose: body copy, where the style has room for it.' },
+                width: { type: 'number', description: 'compose: canvas width (the style picks its own default otherwise).' },
+                height: { type: 'number', description: 'compose: canvas height.' },
+                variant: { type: 'string', description: "compose: a style-specific variant, e.g. art deco's 'emerald'." },
+                draw: { type: 'boolean', description: 'compose: draw it (default true). false returns the scene and ops as data and draws nothing.' },
+                authoredOnly: { type: 'boolean', description: 'list_easings: true for only the curves authored here, false for only what vendors publish.' },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'pinepaper_stick',
+        description: `The vendored stick-figure kit — a rigged figure posed, walking, travelling, holding a prop, with a garment and hair, plus the set it stands on and among.
+
+A different construction from pinepaper_character, which places a figure from the DESIGN GRAPH by concept ("pp:Pigeon"). This is the stick kit specifically, and its options — pose, walk, travel, prop, garment, trouser, hair, expression and a timeline of expressions — were discoverable only by reading the engine's source.
+
+action 'figure' builds the figure. action 'set' builds the floor, the wall and the objects around it, so a figure has somewhere to be.
+
+The geometry is vendored from mcp-cloud, which makes this a three-repo artifact: a change to the kit lands there first and is re-vendored into the engine.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['figure', 'set'], description: "'figure' or 'set'." },
+                id: { type: 'string', description: 'Prefix for the created items.' },
+                kind: { type: 'string', description: 'figure: which figure. set: which piece of the kit.' },
+                at: { type: 'object', description: '{ x?, y? } — where it goes.' },
+                scale: { type: 'number', description: 'Size multiplier.' },
+                facing: { type: 'string', enum: ['left', 'right'], description: 'Which way the figure looks.' },
+                pose: { type: 'string', description: "figure: a named pose from the kit's POSES." },
+                poseAt: { type: 'number', description: 'figure: seconds at which that pose is struck.' },
+                expression: { type: 'string', description: 'figure: one facial expression.' },
+                expressions: { type: 'array', items: { type: 'object' }, description: 'figure: [{ at, name }] — expressions over time.' },
+                walk: { anyOf: [{ type: 'boolean' }, { type: 'object' }], description: 'figure: a walk cycle.' },
+                travel: { type: 'object', description: 'figure: move across the scene while walking, rather than walking in place.' },
+                prop: { type: 'string', description: 'figure: something held in hand.' },
+                propSide: { type: 'string', enum: ['left', 'right'], description: 'figure: which hand.' },
+                garment: { type: 'string', description: 'figure: clothing.' },
+                trouser: { type: 'string', description: 'figure: legwear.' },
+                hair: { type: 'string', description: 'figure: hair style.' },
+                withHair: { type: 'boolean', description: 'figure: draw hair at all.' },
+                groundY: { type: 'number', description: 'The y the figure stands on.' },
+                surfaceY: { type: 'number', description: 'The y a set object sits on.' },
+                durationSeconds: { type: 'number', description: 'figure: length of the performance.' },
+                object: { type: 'object', description: 'set: the object spec.' },
+                items: { type: 'array', items: { type: 'object' }, description: 'set: several pieces at once.' },
+                floor: { anyOf: [{ type: 'boolean' }, { type: 'object' }], description: 'set: draw a floor.' },
+                wall: { anyOf: [{ type: 'boolean' }, { type: 'object' }], description: 'set: draw a wall.' },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'pinepaper_story',
+        description: `A piece of prose becomes a scene.
+
+- distill: reduce an article to its story beats and draw NOTHING. This is the half worth having on its own — a caller can read what the distiller made of the text, edit the beats, and only then assemble. Discovering the reading by looking at a finished scene is the expensive way round.
+- from_text: distill and assemble in one call, when the reading does not need checking.
+- apply_spec: assemble a spec you already have, usually a distilled one you edited.
+- plan_book: lay images out as pages.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['distill', 'from_text', 'apply_spec', 'plan_book'], description: 'Which story operation.' },
+                text: { type: 'string', description: 'distill / from_text: the prose.' },
+                spec: { type: 'object', description: 'apply_spec: the story spec, usually a distilled one you edited.' },
+                images: { type: 'array', items: { anyOf: [{ type: 'string' }, { type: 'object' }] }, description: 'plan_book: images as ids or specs.' },
+                options: { type: 'object', description: 'Assembly or layout options.' },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'pinepaper_interchange',
+        description: `The formats other tools read and write — Lottie, dotLottie, GLB, BVH, PNG sequence.
+
+pinepaper_agent_export covers the PLATFORM formats: png, svg, mp4, webm, gif, pdf, sized for Instagram or YouTube. These are the interchange ones — a Lottie an app plays, a GLB a 3D tool opens, a BVH a rig imports, a PNG sequence an editor ingests. Import is here too, because a format you can only write is half a bridge.
+
+Three of these refuse quietly in the engine: exportGLB with no perspective objects and exportBVH with no rigging system both warn to the console and return nothing, and the production build strips the console. Over MCP there is no console to read, so the precondition is checked BEFORE the call and named — "no perspective objects to export — create one with createObject3D first" rather than an empty result and a guess.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['export_lottie', 'export_dotlottie', 'import_lottie', 'export_glb', 'export_bvh', 'export_png_sequence'], description: 'Which interchange operation.' },
+                options: { type: 'object', description: 'Format options passed through to the exporter: frame range, dimensions, fps, naming.' },
+                data: { anyOf: [{ type: 'string' }, { type: 'object' }], description: 'import_lottie: the Lottie JSON — object, JSON string, or URL.' },
+                skeletonId: { type: 'string', description: "export_bvh: which skeleton to write. A BVH is one skeleton's motion." },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'pinepaper_sound',
+        description: `Synthesis — and the drawing that is the same object.
+
+The engine carries a full audio graph, and none of it was reachable. pinepaper_audio_beats ANALYSES audio that already exists; this MAKES audio.
+
+- Catalogues: list_instruments, list_percussion, list_sfx. Call one before naming a drum or effect — the names are the engine's.
+- Play: play_tone ('A4'), play_chord (root + kind: major, minor, maj7, dim…), play_percussion, play_sfx (beep, pop, wind, whoosh, zap), play_spec, play_from_text.
+- Read without playing: chord_frequencies (the Hz a chord resolves to), from_text (a plain-language description — "a soft warm bell on A4" — resolved to a spec you can inspect or edit before committing), timbre_from_path.
+
+THE PART WORTH KNOWING: sound and drawing are the same object here, both ways.
+- create draws a sound AS a waveform path on the canvas. Edit the path and the timbre changes with it — it is not a picture of the sound, it is the sound.
+- timbre_from_path reads ANY drawn path back as harmonic content. A curve someone drew by hand becomes the partials of a note.
+
+A path with no length cannot be a timbre, and the engine answers a flat single-partial timbre for anything that is not one — a real answer and a refusal look identical — so the item is checked before the call and a non-path is refused by name.
+
+THE CATALOGUE IS A STARTING SET, NOT THE LIMIT. Six instruments, five drums and six effects are what the engine ships with; that is not a claim about how many instruments exist. define_instrument, define_percussion and define_sfx register a new one at runtime — a rhodes, a koto, a taiko, a specific synth patch — and it is first-class from then on: it appears in the list_* catalogues and plays by name like any built-in.
+- A melodic instrument needs a partial table, because one with no partials renders silence. Percussion and SFX may be pure noise instead, because a hat and a whoosh are.
+- For a drum, pass pitch: { from, tau }. The glide is what makes a kick a kick; without it you get a beep.
+- Names are normalised to [a-z][a-z0-9_-]. Register 'Rhodes' and the response returns canonicalName 'rhodes' — play THAT.
+
+render_soundtrack mixes every placed sound to a WAV and writes it to a file. It runs offline, with no Web Audio and no playback, so it works in a headless studio. An empty scene is refused by name rather than producing a silent file, and any sound that could not be mixed is reported as dropped — a soundtrack missing a track otherwise looks exactly like a complete one.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['list_instruments', 'list_percussion', 'list_sfx', 'play_tone', 'play_chord', 'chord_frequencies', 'play_percussion', 'play_sfx', 'play_spec', 'from_text', 'play_from_text', 'create', 'timbre_from_path', 'set_placement', 'remove', 'stop_all', 'define_instrument', 'define_percussion', 'define_sfx', 'render_soundtrack'], description: 'Which sound operation.' },
+                partials: { type: 'array', items: { type: 'object' }, description: 'define_*: [{ h, amp }] — the harmonic table that IS the timbre. Required for define_instrument.' },
+                envelope: { type: 'object', description: 'define_*: { attack, decay, sustain, release } — seconds, except sustain which is a level 0-1.' },
+                gain: { type: 'number', description: 'define_*: output level 0-1 (0.8 instrument, 0.85 percussion, 0.65 sfx).' },
+                aliases: { type: 'array', items: { type: 'string' }, description: "define_*: extra names for the same sound. An alias never shadows a real catalogue entry." },
+                noise: { type: 'number', description: 'define_percussion / define_sfx: noise content 0-1. A hat and a clap are pure noise, so these kinds take partials OR noise.' },
+                noiseFreq: { type: 'number', description: 'define_percussion / define_sfx: noise band centre in Hz.' },
+                hz: { type: 'number', description: 'define_percussion / define_sfx: base frequency in Hz.' },
+                pitch: { type: 'object', description: 'define_percussion / define_sfx: { from, tau } pitch glide. The glide IS the drum — omit it and a kick comes out a beep.' },
+                sampleRate: { type: 'number', description: 'render_soundtrack: samples per second (default 48000).' },
+                bitDepth: { type: 'number', enum: [16, 32], description: 'render_soundtrack: 16 (default) or 32-bit float.' },
+                note: { type: 'string', description: "play_tone: scientific pitch, e.g. 'A4'." },
+                root: { type: 'string', description: "play_chord / chord_frequencies: root note, e.g. 'C4'." },
+                chord: { type: 'string', description: "play_chord / chord_frequencies: chord kind (default 'major')." },
+                name: { type: 'string', description: 'play_percussion / play_sfx: the named drum or effect — list them first.' },
+                text: { type: 'string', description: "from_text / play_from_text: a plain-language description. 'from_text' resolves WITHOUT playing." },
+                spec: { type: 'object', description: 'play_spec / create: the sound spec, usually one from from_text or a catalogue.' },
+                options: { type: 'object', description: 'Playback options for the play_* actions.' },
+                itemId: { type: 'string', description: 'timbre_from_path: the path whose shape becomes the timbre. set_placement / remove: the sound item.' },
+                samples: { type: 'number', description: 'timbre_from_path: points sampled along the path (default 256).' },
+                placement: { type: 'object', description: 'set_placement: where and when the sound sits on the timeline.' },
+                visual: { type: 'object', description: 'create: { width?, height?, position?, color? } for the waveform path.' },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'pinepaper_motion',
+        description: `The generators' Animation knob, pointed at anything — the same motion engine every generator's own animation runs on, reachable for any group or list of items.
+
+Two kinds, and the second is the one nothing else here can do:
+- GROUP motions (drift, sway, rotate, pulse, wave, bounce) move the target as one.
+- FIELD motions (ripple, breathe, undulate) sweep a crest THROUGH the children from an origin, with a chosen waveform — each element moves at its own moment in the cycle. That is a wave passing through a crowd, not a crowd moving together.
+
+Call action 'list' first. It returns the engine's own catalogue — every motion, waveform and origin it will accept — so the names come from the engine rather than from an enum here that can drift away from it.
+
+Origins apply to field motions: center, the four corners, the four edges, 'random' (every element on its own phase — a twinkle rather than a wave), and 'roam' (hopping between the corners and the centre). Pass a seed to make 'random' reproducible.
+
+Waveform 'spike' is a narrow bump. It was called 'pulse' until the engine noticed that one word was naming both a waveform and an animation; saved scenes still carry the old spelling and it is still accepted, but 'spike' is the name.
+
+This is not pinepaper_animate: that applies a loop preset to ONE item. This moves a group, or moves a wave through one.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['list', 'apply'], description: "'list' the catalogue · 'apply' a motion." },
+                itemId: { type: 'string', description: 'apply: a group or single item.' },
+                itemIds: { type: 'array', items: { type: 'string' }, description: 'apply: several items, wrapped in a new group that hosts the motion. Members keep their own ids.' },
+                motion: { type: 'string', description: "apply: the motion name. Call 'list' for the set the engine accepts." },
+                speed: { type: 'number', description: 'apply: roughly cycles per second.' },
+                intensity: { type: 'number', description: 'apply: amplitude (0.15 is the usual default elsewhere).' },
+                waveform: { type: 'string', enum: ['sine', 'triangle', 'square', 'sawtooth', 'spike'], description: 'apply: the shape of one cycle.' },
+                origin: { type: 'string', enum: ['center', 'topLeft', 'topRight', 'bottomLeft', 'bottomRight', 'left', 'right', 'top', 'bottom', 'random', 'roam'], description: 'apply, field motions only: where the crest sweeps from.' },
+                seed: { type: 'number', description: "apply: makes a 'random' origin reproducible." },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'pinepaper_path',
+        description: `Destructive path operations — the ones that REPLACE or ADD items rather than restyling them.
+
+- boolean: unite | subtract | intersect | exclude | divide. CONSUMES its operands and leaves one result, so the input ids stop existing. The first id is the base; the rest apply to it in order.
+- simplify: fewer segments, same shape. Higher tolerance is fewer points and a looser curve.
+- outline_stroke: a stroked line becomes a FILLED SHAPE of the same width — the thing you do before exporting to a format with no stroke model, or before a boolean against a line.
+- toggle_closed: open a closed path or close an open one.
+- pattern: repeat an item — concentric rings, a radial ring, a grid, or a depth-wise extrude stack.
+- get_geometry: read the segments back (anchor and handle coordinates).
+- set_locked / unlock_all: a locked item is also unselectable and undraggable, so it cannot be grabbed by accident.
+
+These live apart from pinepaper_modify_item on purpose: modify restyles an item and keeps its id, every action here changes what items EXIST. A boolean's operands are gone afterwards, and their relations and keyframes go with them.
+
+The engine names each refusal — "a boolean needs at least two paths", "that path has no stroke to outline", "simplify needs a path" — and those come back verbatim rather than being reworded here.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['boolean', 'simplify', 'outline_stroke', 'toggle_closed', 'pattern', 'get_geometry', 'set_locked', 'unlock_all'], description: 'Which path operation.' },
+                itemId: { type: 'string', description: 'The item to operate on — every action except boolean and unlock_all.' },
+                itemIds: { type: 'array', items: { type: 'string' }, description: 'boolean: at least two path ids. The first is the base.' },
+                op: { type: 'string', enum: ['unite', 'subtract', 'intersect', 'exclude', 'divide'], description: 'boolean: which operation (default unite).' },
+                tolerance: { type: 'number', description: 'simplify: how far the new curve may stray, in canvas units (default 2.5). outline_stroke: flattening tolerance.' },
+                kind: { type: 'string', enum: ['concentric', 'radial', 'grid', 'extrude'], description: 'pattern: which repeat (default radial).' },
+                pattern: { type: 'object', description: 'pattern options: { count?, radius?, angle?, phase?, rows?, cols?, gapX?, gapY?, step?, depth?, rotateItems?, shade?, shadeStrength? }. angle and phase are DEGREES. Copies are capped — past a few hundred this is a generator, not a drawing aid.' },
+                locked: { type: 'boolean', description: 'set_locked: true locks, false unlocks (default true).' },
+            },
+            required: ['action'],
+        },
+    },
     {
         name: 'pinepaper_world3d',
         annotations: {
@@ -1999,16 +2495,22 @@ ACTIONS:
 - add_actor: { actorId?, x, z, height?, sprite? (a canvas item id), live? } → { actorId }. live: true re-rasterizes the item as it animates — a RIGGED character (walk cycle, expressions) PERFORMS in the world instead of standing there as a photograph of itself.
 - remove_actor / list_actors / set_actor_pose: { actorId, pose: { x?, z?, angle? } } — the setter a timeline, sequencer or agent drives frame by frame.
 - set_camera: { camera: { mode: 'follow' | 'fixed' | 'orbit', target? (actorId), radius?, speed?, eye?, lookAt? } }
-- add_object: { object: { x, z, height?, color? } } (y defaults to sitting ON the terrain) / remove_object: { objectId }
+- add_object: { object: { x, z, height?, color?, metalness?, roughness?, emissiveIntensity? } } (y defaults to sitting ON the terrain) / remove_object: { objectId }
 - remove_world: {} — tears the world down; the Paper canvas was always its own layer and is untouched.
 
 RECIPE — a character walking through a forest: create {spec:'forest'} → import/rig a character on the canvas → add_actor {sprite: itemId, live: true} → set_camera {mode:'follow', target} → drive set_actor_pose over time (or let the built-in character control walk).`,
         inputSchema: {
             type: 'object',
             properties: {
-                action: { type: 'string', enum: ['create', 'describe', 'configure', 'add_actor', 'remove_actor', 'list_actors', 'set_actor_pose', 'set_camera', 'add_object', 'remove_object', 'remove_world'], description: 'World operation' },
-                spec: { description: "create: preset id ('forest'|'snowMountain'|'field'|'jungle') or a full spec object." },
-                character: { description: 'create: include the walkable character (boolean or config).' },
+                action: { type: 'string', enum: ['create', 'describe', 'configure', 'add_actor', 'remove_actor', 'list_actors', 'set_actor_pose', 'set_camera', 'add_object', 'remove_object', 'remove_world', 'extrude_path', 'lathe_path', 'list_meshes', 'remove_mesh', 'add_light', 'set_light', 'remove_light', 'list_lights', 'add_material', 'set_material', 'remove_material', 'list_materials', 'import_obj', 'import_gltf', 'list_mesh_clips', 'set_mesh_clip', 'set_nav_target', 'get_nav_target', 'ground_height', 'raycast', 'dolly_camera', 'pan_camera', 'world_to_canvas', 'canvas_to_ground', 'add_body', 'remove_body', 'list_bodies', 'step_physics', 'impulse', 'set_velocity', 'fire_projectile', 'line_of_sight', 'set_mesh_instances'], description: 'World operation. extrude_path/lathe_path turn a canvas path into real geometry; lights are capped at 8; a material is shared by every object referencing it.' },
+                spec: {
+                    anyOf: [{ type: 'string' }, { type: 'object' }],
+                    description: "create: preset id ('forest'|'snowMountain'|'field'|'jungle') or a full spec object.",
+                },
+                character: {
+                    anyOf: [{ type: 'boolean' }, { type: 'object' }],
+                    description: 'create: include the walkable character (boolean or config).',
+                },
                 patch: { type: 'object', description: 'configure: partial world spec, validated against describe.' },
                 actorId: { type: 'string', description: 'Actor id.' },
                 x: { type: 'number', description: 'add_actor: world x.' },
@@ -2018,12 +2520,118 @@ RECIPE — a character walking through a forest: create {spec:'forest'} → impo
                 live: { type: 'boolean', description: 'add_actor: re-rasterize as the item animates.' },
                 pose: { type: 'object', description: 'set_actor_pose: { x?, z?, angle? }.' },
                 camera: { type: 'object', description: "set_camera: { mode: follow|fixed|orbit, target?, radius?, speed?, eye?, lookAt? }." },
-                object: { type: 'object', description: 'add_object: { x, z, height?, color?, y? }.' },
+                object: { type: 'object', description: 'add_object: { x, z, height?, color?, y? }. metalness/roughness are accepted and IGNORED here — a plain object is drawn by the prop shader, which declares no such uniform. They render on the mesh path only.' },
+                pathId: { type: 'string', description: 'extrude_path / lathe_path: the canvas path to turn into geometry. The path itself is unchanged.' },
+                mesh: { type: 'object', description: 'extrude_path / lathe_path options: { id?, depth?, unitsPerPixel?, caps?, segments?, arc?, flatness?, x?, y?, z?, rotY?, rotYDegrees?, scale?, doubleSided? }. arc is DEGREES; rotY is RADIANS (fed straight to cos/sin in the shader) — pass rotYDegrees to write degrees. These names are the ones the engine records as the mesh provenance, so a captured meshProvenance.opts spreads straight back in.' },
+                meshId: { type: 'string', description: 'remove_mesh: the mesh id.' },
+                light: { type: 'object', description: 'add_light / set_light: { id?, x?, y?, z?, color?, intensity?, range? }. At most 8 point lights; the ninth is refused by name because the shader array is fixed-size.' },
+                lightId: { type: 'string', description: 'set_light / remove_light: the light id.' },
+                material: { type: 'object', description: 'add_material / set_material: { id?, color?, emissive?, metalness?, roughness?, emissiveIntensity?, clearcoat?, clearcoatRoughness?, sheenColor?, sheenRoughness? }. A shared surface — one edit restyles every object using it. metalness/roughness render on the mesh path only.' },
+                materialId: { type: 'string', description: 'set_material / remove_material: the material id.' },
+                source: { type: 'string', description: 'import_obj: the OBJ file TEXT. import_gltf: a URL or a data: URI of the .glb bytes.' },
+                importOptions: { type: 'object', description: 'import_obj / import_gltf: placement and scale options, passed through.' },
+                clip: { type: 'string', description: 'set_mesh_clip: which imported animation clip a skinned mesh plays.' },
+                crossfade: { type: 'number', description: 'set_mesh_clip: seconds to blend out of the previous clip (blended in LOCAL pose space).' },
+                navTarget: { type: 'string', enum: ['2d', '3d'], description: "set_nav_target: which layer the pointer drives." },
+                point: { type: 'object', description: 'ground_height / canvas_to_ground / world_to_canvas: { x, y, z? }.' },
+                origin: { type: 'array', items: { type: 'number' }, description: 'raycast: ray origin [x, y, z].' },
+                direction: { type: 'array', items: { type: 'number' }, description: 'raycast: ray direction [x, y, z], need not be normalised.' },
+                multiplier: { type: 'number', description: 'dolly_camera: >1 away, <1 closer.' },
+                dx: { type: 'number', description: 'pan_camera: horizontal pan in SCREEN pixels.' },
+                dy: { type: 'number', description: 'pan_camera: vertical pan in SCREEN pixels.' },
+                body: { type: 'object', description: 'add_body / fire_projectile: the body spec. NARROW by design — a sphere or capsule under gravity colliding with the world. No stacking solver, no joints; pinepaper_physics is the 2D world and has those.' },
+                bodyId: { type: 'string', description: 'remove_body / impulse / set_velocity: the body id.' },
+                vector: { type: 'array', items: { type: 'number' }, description: 'impulse / set_velocity: [x, y, z].' },
+                dt: { type: 'number', description: 'step_physics: seconds to advance. Returns contacts made and bodies removed.' },
+                from: { type: 'array', items: { type: 'number' }, description: 'line_of_sight: eye point [x, y, z].' },
+                to: { type: 'array', items: { type: 'number' }, description: 'line_of_sight: target point [x, y, z].' },
+                instances: { type: 'array', items: { type: 'array', items: { type: 'number' } }, description: 'set_mesh_instances: one entry per copy, six numbers — x, y, z, scale, rotY (RADIANS), variant.' },
                 objectId: { type: 'string', description: 'remove_object: object id.' },
             },
             required: ['action'],
         },
     },
+    {
+        name: 'pinepaper_character',
+        annotations: {
+            title: 'Character (place and direct a figure from the graph)',
+            readOnlyHint: false,
+            idempotentHint: false,
+        },
+        description: `Place a CHARACTER from the design graph and DIRECT it — no geometry, no bones, no poses.
+
+The knowledge of how a figure is built and how it moves lives in the graph; this asks for it by name and states WHAT happens. The alternative is thirty-odd exactly-right calls — create the skeleton, add each bone with the right parent and angle, create each shape, attach each to the right bone, then author poses — where one mistake anywhere leaves a broken figure.
+
+  { concept: "pp:Character", at: { x: 470, y: 250 }, height: 300,
+    beats: [ { at: 1.0, channel: "blink" },
+             { at: 1.8, channel: "say", until: 4.2 },
+             { at: 5.0, channel: "headTurn", value: -0.8 } ] }
+
+CHANNELS ARE DECLARED BY THE CONCEPT, not by you. Ask pinepaper_ontology for a concept to see the ones it has. Four kinds exist:
+- transform: one part deformed with an attack, a hold and a release — a blink is the eyes flattening in scaleY and easing back. This is what gives a gesture a MIDDLE; a swap between two drawings has only two ends and reads as flashing.
+- cycle: a repeating throw that runs for as long as you ask — a pigeon's head bob, a tail flick. Amplitude is a fraction of the part, so it means the same at any size.
+- shift: every part moved together, for a turn a flat drawing cannot rotate into.
+- alternate / speak: swaps between drawn states, for shapes that genuinely differ rather than deform.
+
+BEATS ARE INSTANTS OR SPANS. \`at\` is when it happens; \`until\` is how long for a channel that occupies time. \`value\` is how far, for channels that take a magnitude.
+
+WHAT YOU GET BACK: the items and keyframe tracks the beats compile to. They are ordinary scene items afterwards — modify, animate and relate them like anything else.
+
+NOT LIP SYNC. \`say\` opens and closes a mouth for the length of a line. Matching phonemes needs the word timings a voice track carries; pass \`timings\` if you have them and each entry drives one mouth opening.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                concept: {
+                    type: 'string',
+                    description: 'Concept id from the design graph, e.g. "pp:Character" or "pp:Pigeon". Its parts, rig and channels come with it.',
+                },
+                at: {
+                    type: 'object',
+                    properties: {
+                        x: { type: 'number', description: 'X of the figure\'s centre' },
+                        y: { type: 'number', description: 'Y of the figure\'s centre' },
+                    },
+                    description: 'Where the figure stands.',
+                },
+                height: { type: 'number', description: 'Drawn height in pixels. Every amplitude in the graph is a fraction, so the performance scales with it.' },
+                position: { type: 'object', description: 'Where the figure stands — a synonym for `at`, because the rest of this surface says position. `at` wins if both are sent.' },
+                scale: { type: 'number', description: 'Size as a multiplier of the 300px default, for callers who think in scale rather than pixels. `height` wins if both are sent.' },
+                palette: { type: 'object', description: "Override the depiction's own colours: part id → colour. Only the parts you name change." },
+                ink: { type: 'string', description: 'Ink colour for the stroked copies that make the figure read as drawn rather than filled. Overrides the style\'s own.' },
+                id: { type: 'string', description: 'Prefix for the created items (default: the concept name).' },
+                style: { type: 'string', description: 'Style id for the depiction (default: the concept\'s own).' },
+                variant: { type: 'string', description: 'Depiction variant (default: "default").' },
+                durationSeconds: { type: 'number', description: 'Length of the piece, so every track spans it. A track that starts late leaves the figure invisible until it does.' },
+                beats: {
+                    type: 'array',
+                    description: 'What happens, in order. Channels the concept does not declare are ignored rather than approximated.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            at: { type: 'number', description: 'When, in seconds' },
+                            channel: { type: 'string', description: 'A channel the concept declares — blink, say, headTurn, bob, tailFlick…' },
+                            until: { type: 'number', description: 'For a channel that occupies a span rather than an instant' },
+                            value: { type: 'number', description: 'How far, for a channel that takes a magnitude' },
+                        },
+                        required: ['at', 'channel'],
+                    },
+                },
+                timings: {
+                    type: 'array',
+                    description: 'Optional word or syllable timings from a voice track. Each entry drives one mouth opening, which is what turns the shape of speech into lip sync.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            at: { type: 'number', description: 'Start, in seconds' },
+                            until: { type: 'number', description: 'End, in seconds' },
+                        },
+                        required: ['at'],
+                    },
+                },
+            },
+            required: ['concept'],
+        },
+    },
     {
         name: 'pinepaper_rigging',
         annotations: {
@@ -2037,6 +2645,19 @@ RECIPE — a character walking through a forest: create {spec:'forest'} → impo
 
 WORKFLOW: create_skeleton → add_bone (×N, parent them into a hierarchy) → attach_item (bind shapes to bones) → optionally create_ik_chain → animate with add_pose_keyframe (or save_pose then reference it).
 
+POSE MOTION — build a performance out of saved poses:
+- START HERE on a rig you did not build yourself: list_bones gives the ids an inline pose needs ({ boneId: angleDeg }), and list_pose_libraries + load_pose_library give a fresh rig a stock walk/run/jump set to work with. A newly rigged character has ZERO saved poses, so without one of these there is nothing to sequence.
+- save_pose / list_poses / load_pose / interpolate_poses: the pose library. A pose is a snapshot of bone angles; everything below is a graph over these.
+- play_pose_sequence: one clip. Keys name a saved pose id or an inline { boneId: angleDeg } map. ONE sequence per skeleton — starting another replaces it.
+- stitch_poses: join CLIPS into one continuous performance (walk ×3 → jump → land → idle) and install it as a single sequence. This is how you get a transition rather than a cut.
+  · A cyclic clip (loop: true) is entered at the phase CLOSEST to where the previous clip ended, so the legs do not teleport mid-stride. matchPhase: false to disable.
+  · Every seam reports 'residual' — the angular mismatch, in degrees, that the blend could not remove. Near zero is a real match; a large number means the blend is HIDING a cut. Read it.
+  · plan: true returns the seams without touching the skeleton, so you can check the joins first.
+- move_root: a deterministic locomotion track, keyed in SCENE SECONDS on the same clock as the pose sequence. Without it a walk cycle is a march on the spot; with a last keyframe shorter than the performance, the figure arrives early and stands there.
+- auto_walk / auto_breath / auto_idle / auto_jump: one-call procedural layers. breath and idle find their bones BY NAME (spine/chest/body, head/hip/spine) and refuse with that list if the rig uses other names.
+- bake_animation: freeze the whole rig into plain item keyframes for export. Needs items ATTACHED to bones — a bare skeleton has no output.
+- add_secondary_motion: spring chains for tails, hair, cloth. skin_path: per-vertex deformation of a curved path.
+
 ACTIONS:
 - create_skeleton: { name?, rootPosition? } → { skeletonId }
 - add_bone: { skeletonId, name?, parentBoneId? (omit for root), length? (80), angle? (deg), flexibility? (0 rigid…1), segments? } → { boneId }
@@ -2054,7 +2675,7 @@ BREAKDOWN POSES (S12): a breakdown keyframe shapes the ARC + SPACING between key
         inputSchema: {
             type: 'object',
             properties: {
-                action: { type: 'string', enum: ['create_skeleton', 'add_bone', 'attach_item', 'create_ik_chain', 'add_pose_keyframe', 'set_target_path', 'save_pose', 'save_shape_key', 'import_bvh', 'retarget_bvh', 'import_spine'], description: 'Rigging operation' },
+                action: { type: 'string', enum: ['create_skeleton', 'add_bone', 'attach_item', 'create_ik_chain', 'add_pose_keyframe', 'set_target_path', 'save_pose', 'save_shape_key', 'import_bvh', 'retarget_bvh', 'import_spine', 'list_skeletons', 'list_bones', 'list_pose_libraries', 'load_pose_library', 'list_poses', 'load_pose', 'interpolate_poses', 'play_pose_sequence', 'stop_pose_sequence', 'stitch_poses', 'apply_pose_transition', 'auto_walk', 'auto_breath', 'auto_idle', 'auto_jump', 'move_root', 'stop_root_track', 'add_secondary_motion', 'skin_path', 'bake_animation', 'list_shape_keys', 'load_shape_key'], description: 'Rigging operation' },
                 bvhText: { type: 'string', description: 'import_bvh / retarget_bvh: the .bvh file contents.' },
                 spineJson: { type: 'string', description: 'import_spine: the Spine JSON export, as a string.' },
                 view: { type: 'string', enum: ['side', 'front'], description: 'import_bvh: 3D→2D projection plane. CMU walks read best from the side (default).' },
@@ -2065,6 +2686,25 @@ BREAKDOWN POSES (S12): a breakdown keyframe shapes the ARC + SPACING between key
                 itemId: { type: 'string', description: 'Canvas item id — attach_item.' },
                 chainId: { type: 'string', description: 'IK chain id — set_target_path.' },
                 name: { type: 'string', description: 'Name — create_skeleton / add_bone / create_ik_chain / save_pose / save_shape_key.' },
+                poseId: { type: 'string', description: 'Saved pose id — load_pose.' },
+                libraryName: { type: 'string', description: 'Stock pose set — load_pose_library. list_pose_libraries for the names.' },
+                boneMap: { type: 'object', description: 'Bone NAME → bone id — load_pose_library. Omit to build it from list_bones.' },
+                poseIdA: { type: 'string', description: 'First pose — interpolate_poses.' },
+                poseIdB: { type: 'string', description: 'Second pose — interpolate_poses.' },
+                t: { type: 'number', description: 'Blend 0=A … 1=B — interpolate_poses.' },
+                sequence: { type: 'array', items: { type: 'object' }, description: 'Pose keys [{ t, pose | angles, ease }] — play_pose_sequence.' },
+                clips: { type: 'array', items: { type: 'object' }, description: 'Clips in order for stitch_poses: [{ keys | poses, duration, repeat, loop, blend, matchPhase }]. A clip key names a SAVED pose id or an inline { boneId: angleDeg } map.' },
+                blend: { type: 'number', description: 'Seam overlap in seconds (default 0.25) — stitch_poses.' },
+                blendSteps: { type: 'number', description: 'Keys emitted across a seam (default 6) — stitch_poses.' },
+                matchPhase: { type: 'boolean', description: 'Enter a cyclic clip at the phase closest to where the last one ended (default true) — stitch_poses.' },
+                plan: { type: 'boolean', description: 'stitch_poses: return the seams WITHOUT installing the result.' },
+                transitionName: { type: 'string', description: 'Named transition — apply_pose_transition.' },
+                poseIdMap: { type: 'object', description: 'Transition pose name → saved pose id — apply_pose_transition.' },
+                boneNames: { type: 'array', items: { type: 'string' }, description: 'Ordered bone names for a spring chain — add_secondary_motion.' },
+                keyframes: { type: 'array', items: { type: 'object' }, description: 'World root positions [{ t, x, y, ease }] — move_root. `t` is SCENE SECONDS on the same clock as the pose sequence, not a 0..1 fraction: match the last keyframe to the performance duration or the figure arrives early and stands still for the rest.' },
+                shapeKeyId: { type: 'string', description: 'Saved shape key id — load_shape_key.' },
+                weight: { type: 'number', description: 'Shape key weight (default 1) — load_shape_key.' },
+                options: { type: 'object', description: 'Pass-through options — auto_* / bake_animation / move_root / skin_path / play_pose_sequence.' },
                 rootPosition: { type: 'object', properties: { x: { type: 'number' }, y: { type: 'number' } }, description: 'Skeleton root position — create_skeleton.' },
                 parentBoneId: { type: 'string', description: 'Parent bone id (omit for root) — add_bone.' },
                 length: { type: 'number', description: 'Bone length px (default 80) — add_bone.' },
@@ -2079,7 +2719,10 @@ BREAKDOWN POSES (S12): a breakdown keyframe shapes the ARC + SPACING between key
                 strength: { type: 'number', description: 'Chain strength 0..1 (1) — create_ik_chain.' },
                 poleVector: { type: 'object', properties: { x: { type: 'number' }, y: { type: 'number' } }, description: 'Pole vector hint — create_ik_chain.' },
                 time: { type: 'number', description: 'Keyframe time s — add_pose_keyframe.' },
-                pose: { description: 'Saved pose id (string) OR { boneId: angleDeg } map — add_pose_keyframe.' },
+                pose: {
+                    anyOf: [{ type: 'string' }, { type: 'object', additionalProperties: { type: 'number' } }],
+                    description: 'Saved pose id (string) OR { boneId: angleDeg } map — add_pose_keyframe.',
+                },
                 easing: { type: 'string', description: 'Named easing (linear) — add_pose_keyframe.' },
                 favor: { type: 'number', description: 'Breakdown spacing bias −1..1 — add_pose_keyframe.' },
                 breakdown: { type: 'boolean', description: 'Mark as breakdown pose — add_pose_keyframe.' },
@@ -2198,7 +2841,7 @@ USE WHEN:
 - Building live geometric constructions (GeoGebra-style — dragging an anchor updates the dependent)
 
 RELATION TYPES:
-- orbits: Circular motion around target (params: radius, speed, direction, phase)
+- orbits: Circular motion around target (params: radius, speed, direction, phaseDegrees). Use phaseDegrees. 'phase' is the one parameter in the whole relation vocabulary measured in RADIANS — the documented exception to "angles are DEGREES", kept only for scenes that already set it. phaseDegrees wins when both are given.
 - follows: Move toward target with smoothing (params: offset, smoothing, delay)
 - attached_to: Fixed offset from target (params: offset, inherit_rotation)
 - maintains_distance: Stay fixed distance from target (params: distance, strength)
@@ -2206,6 +2849,35 @@ RELATION TYPES:
 - mirrors: Mirror position across axis (params: axis, center)
 - parallax: Move relative by depth (params: depth, origin)
 - bounds_to: Stay within bounds (params: padding, bounce)
+- anchored_in_world: Pin the item to a 3D world position so it tracks the world camera.
+- spring_follow: Follow with spring dynamics rather than smoothing — it overshoots and settles.
+- repels: Move away from the target inside a radius and ease back when it leaves (params: force, maxDistance, minDistance, returnSpeed). Crowd avoidance, and reacting to a cursor without being dragged by it.
+- wiggle: Continuous procedural noise on the item. Richer than a sine: it does not repeat visibly.
+- syncs_with: Run the source's animation on the TARGET's timeline (params: offset, speedRatio) — they share a clock and stay in step even when the target's timing changes, which merely starting together does not give you.
+- triggers_animation: Start the target's animation on a condition (params: trigger, delay, atTime). The declarative "and then": sequencing in the graph instead of in a callback nobody can query.
+- tours / synced_to_audio: Move through a sequence of targets; bind playback to an audio track.
+- connects_to: Diagram edge (params: via, sourcePort, targetPort, label).
+- attached_to_tail / head_points_to: Bind a connector's tail / head to a diagram port (params: port). Together they are why a connector stays connected when a flowchart is rearranged.
+- expresses: Play a facial expression over a root's part_of children (params: expression — blink|smile|surprise…, interval, duration, easing). No interval means sustained. It walks part_of from the ROOT, so parts with roles but no parent are INERT: the relation applies to nothing and reports success, which is what makes an unparented pair of eyes look finished while being unable to blink.
+- part_of: Semantic membership with a named role (params: role, offset, structural). structural: true records the part WITHOUT driving its position — the right choice when the parent is a group that already transforms its children, since driving it too would fight the group.
+- staggered_with: Delay an item's animation by its place in a sequence (params: index, stagger, effect). For a SHAPED stagger — outward from the centre, converging from the edges, across a grid — also pass count (required: without it there is no "end" to measure distance from), plus from (start|end|center|edges|random), amount (total seconds for the whole run, overrides stagger), grid ("rows,cols" or "auto"), axis (x|y) and distributeEase. Plain index x stagger still works and is taken first. To stagger items directly rather than through a relation, use pinepaper_stagger.
+
+INTERACTIVE RELATIONS — the state machine lives in the graph.
+An event channel (pinepaper_event) is the hub: something FIRES it, and reactions bound to it run. Nothing here is a callback; it is all queryable graph, so it scrubs, exports and survives a reload.
+
+- Input triggers (item → event): on_click_fire, on_pointer_enter_fire, on_pointer_exit_fire, on_key_fire (params: key, modifiers, global, preventDefault). { key: 'Enter' } makes Enter activate a button exactly as a click does. The chord is matched EXACTLY in both directions — { key: 'Enter' } does NOT fire on Ctrl+Enter, and { key: 's' } does not steal the browser's Ctrl+S; ask for a modifier with modifiers: { ctrl: true }. Listens only while the source item has focus unless global: true, so it will not take keys from the rest of the page.
+- Event reactions (event → item), params in common: property, value, key, by, color, template, delay, timeline.
+  · on_event_set_property / _set_color / _set_visibility / _set_data — write a value.
+  · on_event_set_property_from_template — write a value built from a '{token}' TEMPLATE read off item.data, so the text can quote live state ("Score: {score}") instead of a literal fixed when you authored it.
+  · on_event_increment (params: property, by) / on_event_toggle — counters and flip-flops.
+  · on_event_fire_after (params: delay, timeline) — chain one beat to the next.
+  · on_event_fire_if — the only reaction that TESTS graph state rather than mutating it; params.predicate is an ExpressionIR program.
+  · on_event_add_relation / on_event_remove_relation — the scene rewires itself.
+  · on_event_store_set / on_event_store_increment / restores_from — persistent state. The target is a store node whose id is the storage SCOPE, so two stores in a scene and two widgets on a page do not collide. restores_from is the read half and fires ONCE at load.
+- Proximity (pointer over an item): on_enter_* / on_exit_* mirror the on_event_* reactions above (set_color, set_property, set_property_from_template, set_visibility, set_data, increment, toggle) — hover states without a single line of script.
+- Exclusive state: exclusive_group makes at most one member active (on_event_set_active is how you activate one — tabs, steppers, quiz cards). menubar_group is the same grouping WITHOUT the mutex.
+
+There are 80 relation types and this list names the families rather than every member. For the live catalogue — what exists in THIS build, with definitions — call pinepaper_query_capabilities { kind: 'relation' }, which reads the engine's registry rather than a list written down here.
 
 RELATION COMPATIBILITY:
 - Universal relations (position-based) work with ALL item types including imported SVGs/images:
@@ -2228,7 +2900,7 @@ GEOMETRIC CONSTRUCTION CONSTRAINTS (Layer 2) — the source item is RE-DERIVED e
 
 PROCEDURAL / DETERMINISTIC BINDING (Expression IR — S10 G1) — bind a property to another property or to a math function of time. Pass params.signal:true to route through the pure, seed/frame-deterministic signal interpreter (replay-stable — same time → identical output); omit it for the per-frame compute fallback.
 - driven_by: source's sourceProperty = target's targetProperty * multiplier + offset (optionally clamped). sourceProperty ∈ x|y|rotation|opacity|scale|strokeWidth|fillColor|strokeColor; targetProperty ∈ x|y|rotation|opacity|scale. For fillColor/strokeColor the (clamped 0..1) driven value interpolates colorFrom→colorTo — so a relation drives COLOR. NEEDS a target (the property source). params: sourceProperty, targetProperty, multiplier, offset, clamp {min,max}, colorFrom, colorTo, signal. e.g. tint a dot by a planet's x: sourceProperty 'fillColor', targetProperty 'x', colorFrom '#0055ff', colorTo '#ff3300', signal true.
-- time_expression: self-relation (targetId=null); the source's params.property is driven by a math expression of t (scene time) and v (params.baseValue). params: property (default 'y'), expression (e.g. 'sin(t*2)*50 + v'), baseValue, signal. With signal:true the expression is parsed into the Expression IR and evaluated as a pure f(t); it falls back to per-frame if it uses random() or an unknown symbol (non-deterministic).
+- time_expression: self-relation (targetId=null); the source's params.property is driven by a math expression of t (scene time) and v (params.baseValue). params: property (default 'y'), expression (e.g. 'sin(t*2)*50 + v'), baseValue, signal. Both modes parse the SAME grammar — the caret is exponentiation (not XOR), and random() is rejected by name rather than falling back, because a scene that renders differently twice cannot be baked or exported. signal:true additionally evaluates it as a pure f(t) via the Expression IR. Beyond the usual trig/log/pow set: clamp, mod, fract, pingpong, inverseLerp, remap, noise, sec, csc, cot, the six ease in/out quad and cubic curves, and the constants PI, E and TAU.
 
 EVENT-DRIVEN SCENE CHAINS (S11) — build a LONG scene as a graph of timed events, not a keyframe track. First make events with pinepaper_event (action:'create' → eventId). The relations below have an EVENT as their sourceId; firing the event runs the reaction. Chain beats over animation time with on_event_fire_after (timeline:'canvas'), have beats mutate the scene with on_event_add_relation, then kick it off with pinepaper_event action:'pulse'. Because canvas-timed fires are on the animation clock, the whole chain is scrub-, loop-, and replay-stable.
 - on_event_fire_after: sourceId=event, targetId=the NEXT event. When source fires, pulse target after params.delay ms. params.timeline: 'canvas' (animation clock — use for scene chains) | 'wall' (real setTimeout). This is the chaining primitive.
@@ -2270,7 +2942,7 @@ Relations are COMPOSITIONAL - an item can have multiple relations that work toge
                 },
                 relationType: {
                     type: 'string',
-                    enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'camera_follows', 'camera_animates', 'morphs_to', 'group_morphs_to', 'moves_along_path', 'is_midpoint_of', 'lies_on_line', 'is_centroid_of', 'is_circumcenter_of', 'concentric_with', 'construction_reveal', 'driven_by', 'time_expression', 'on_event_fire_after', 'on_event_add_relation', 'on_event_remove_relation', 'on_event_set_color', 'on_event_set_property', 'on_event_set_visibility', 'on_top_of', 'below', 'beside', 'inside', 'centered_on', 'aligned_with'],
+                    enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'anchored_in_world', 'spring_follow', 'repels', 'attracts', 'wiggle', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'morphs_to', 'group_morphs_to', 'moves_along_path', 'construction_reveal', 'triggers_animation', 'syncs_with', 'tours', 'synced_to_audio', 'expresses', 'camera_follows', 'camera_animates', 'is_midpoint_of', 'lies_on_line', 'is_centroid_of', 'is_circumcenter_of', 'concentric_with', 'driven_by', 'time_expression', 'on_click_fire', 'on_pointer_enter_fire', 'on_pointer_exit_fire', 'on_key_fire', 'on_event_fire_after', 'on_event_fire_if', 'on_event_add_relation', 'on_event_remove_relation', 'on_event_set_color', 'on_event_set_property', 'on_event_set_property_from_template', 'on_event_set_visibility', 'on_event_set_active', 'on_event_set_data', 'on_event_increment', 'on_event_toggle', 'on_event_store_set', 'on_event_store_increment', 'on_enter_set_color', 'on_enter_set_property', 'on_enter_set_property_from_template', 'on_enter_set_visibility', 'on_enter_set_data', 'on_enter_increment', 'on_enter_toggle', 'on_exit_set_color', 'on_exit_set_property', 'on_exit_set_property_from_template', 'on_exit_set_visibility', 'on_exit_set_data', 'on_exit_increment', 'on_exit_toggle', 'exclusive_group', 'menubar_group', 'restores_from', 'on_top_of', 'below', 'beside', 'inside', 'centered_on', 'aligned_with', 'part_of', 'connects_to', 'attached_to_tail', 'head_points_to'],
                     description: 'Type of relationship',
                 },
                 params: {
@@ -2278,8 +2950,17 @@ Relations are COMPOSITIONAL - an item can have multiple relations that work toge
                     description: 'Relation-specific parameters',
                     additionalProperties: true,
                 },
+                presetId: {
+                    type: 'string',
+                    description: "Adopt a community relation PRESET instead of naming a type and params yourself — a tuned motion with its symbols exposed as knobs. List them with pinepaper_query_capabilities { action: 'catalogue', catalogue: 'relation_presets' }. The preset decides the relationType, so relationType is not needed alongside it.",
+                },
+                presetValues: {
+                    type: 'object',
+                    description: 'presetId: symbol → number. An omitted symbol takes the midpoint of its declared range, so a preset applies sensibly with no values at all.',
+                    additionalProperties: true,
+                },
             },
-            required: ['sourceId', 'relationType'],
+            required: ['sourceId'],
         },
     },
     {
@@ -2304,7 +2985,7 @@ USE WHEN:
                 targetId: { type: 'string', description: 'Target item ID' },
                 relationType: {
                     type: 'string',
-                    enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'camera_follows', 'camera_animates', 'morphs_to', 'group_morphs_to', 'moves_along_path', 'is_midpoint_of', 'lies_on_line', 'is_centroid_of', 'is_circumcenter_of', 'concentric_with', 'construction_reveal', 'driven_by', 'time_expression', 'on_event_fire_after', 'on_event_add_relation', 'on_event_remove_relation', 'on_event_set_color', 'on_event_set_property', 'on_event_set_visibility', 'on_top_of', 'below', 'beside', 'inside', 'centered_on', 'aligned_with'],
+                    enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'anchored_in_world', 'spring_follow', 'repels', 'attracts', 'wiggle', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'morphs_to', 'group_morphs_to', 'moves_along_path', 'construction_reveal', 'triggers_animation', 'syncs_with', 'tours', 'synced_to_audio', 'expresses', 'camera_follows', 'camera_animates', 'is_midpoint_of', 'lies_on_line', 'is_centroid_of', 'is_circumcenter_of', 'concentric_with', 'driven_by', 'time_expression', 'on_click_fire', 'on_pointer_enter_fire', 'on_pointer_exit_fire', 'on_key_fire', 'on_event_fire_after', 'on_event_fire_if', 'on_event_add_relation', 'on_event_remove_relation', 'on_event_set_color', 'on_event_set_property', 'on_event_set_property_from_template', 'on_event_set_visibility', 'on_event_set_active', 'on_event_set_data', 'on_event_increment', 'on_event_toggle', 'on_event_store_set', 'on_event_store_increment', 'on_enter_set_color', 'on_enter_set_property', 'on_enter_set_property_from_template', 'on_enter_set_visibility', 'on_enter_set_data', 'on_enter_increment', 'on_enter_toggle', 'on_exit_set_color', 'on_exit_set_property', 'on_exit_set_property_from_template', 'on_exit_set_visibility', 'on_exit_set_data', 'on_exit_increment', 'on_exit_toggle', 'exclusive_group', 'menubar_group', 'restores_from', 'on_top_of', 'below', 'beside', 'inside', 'centered_on', 'aligned_with', 'part_of', 'connects_to', 'attached_to_tail', 'head_points_to'],
                     description: 'Specific relation type to remove (optional - removes all if not specified)',
                 },
             },
@@ -2332,7 +3013,7 @@ USE WHEN:
                 itemId: { type: 'string', description: 'Item to query relations for' },
                 relationType: {
                     type: 'string',
-                    enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'camera_follows', 'camera_animates', 'morphs_to', 'group_morphs_to', 'moves_along_path', 'is_midpoint_of', 'lies_on_line', 'is_centroid_of', 'is_circumcenter_of', 'concentric_with', 'construction_reveal', 'driven_by', 'time_expression', 'on_event_fire_after', 'on_event_add_relation', 'on_event_remove_relation', 'on_event_set_color', 'on_event_set_property', 'on_event_set_visibility', 'on_top_of', 'below', 'beside', 'inside', 'centered_on', 'aligned_with'],
+                    enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'anchored_in_world', 'spring_follow', 'repels', 'attracts', 'wiggle', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'morphs_to', 'group_morphs_to', 'moves_along_path', 'construction_reveal', 'triggers_animation', 'syncs_with', 'tours', 'synced_to_audio', 'expresses', 'camera_follows', 'camera_animates', 'is_midpoint_of', 'lies_on_line', 'is_centroid_of', 'is_circumcenter_of', 'concentric_with', 'driven_by', 'time_expression', 'on_click_fire', 'on_pointer_enter_fire', 'on_pointer_exit_fire', 'on_key_fire', 'on_event_fire_after', 'on_event_fire_if', 'on_event_add_relation', 'on_event_remove_relation', 'on_event_set_color', 'on_event_set_property', 'on_event_set_property_from_template', 'on_event_set_visibility', 'on_event_set_active', 'on_event_set_data', 'on_event_increment', 'on_event_toggle', 'on_event_store_set', 'on_event_store_increment', 'on_enter_set_color', 'on_enter_set_property', 'on_enter_set_property_from_template', 'on_enter_set_visibility', 'on_enter_set_data', 'on_enter_increment', 'on_enter_toggle', 'on_exit_set_color', 'on_exit_set_property', 'on_exit_set_property_from_template', 'on_exit_set_visibility', 'on_exit_set_data', 'on_exit_increment', 'on_exit_toggle', 'exclusive_group', 'menubar_group', 'restores_from', 'on_top_of', 'below', 'beside', 'inside', 'centered_on', 'aligned_with', 'part_of', 'connects_to', 'attached_to_tail', 'head_points_to'],
                     description: 'Filter by relation type (optional)',
                 },
                 direction: {
@@ -2483,7 +3164,8 @@ USE WHEN:
 - "bouncing text" → animationType: bounce
 - "fading effect" → animationType: fade
 - "wobbling button" → animationType: wobble
-- "sliding header" → animationType: slide
+- "sliding header" → animationType: slideLeftRight (or slideUpDown)
+- "scrolling banner" → animationType: scrollLeft (also scrollRight/Up/Down)
 - "typewriter effect" → animationType: typewriter (text only)
 
 DO NOT USE WHEN:
@@ -2491,21 +3173,30 @@ DO NOT USE WHEN:
 - User wants sequential animations ("first fade, then rotate") → Use keyframe animation
 - User describes relationships ("orbit around") → Use relations
 
-ANIMATION TYPES:
+ANIMATION TYPES (18 — the list the driver actually switches on):
 - pulse: Scale up/down rhythmically
+- breathe: A slower, softer pulse
 - rotate: Continuous rotation
+- swing: Pendulum rotation about the top
 - bounce: Vertical bouncing motion
-- fade: Opacity cycling
+- jelly: Squash-and-stretch wobble
+- shake: Rapid small displacement
 - wobble: Side-to-side wobbling
-- slide: Horizontal sliding
-- typewriter: Character-by-character reveal`,
+- fade: Opacity cycling
+- glow: Cycling luminance
+- slideLeftRight / slideUpDown: Sliding on one axis
+- scrollLeft / scrollRight / scrollUp / scrollDown: Continuous scroll, wrapping
+- path: Travel along an assigned path
+- typewriter: Character-by-character reveal
+
+There is NO 'slide'. An unknown type is stored and then ignored — the item sits still while its data claims otherwise, and the call still reports success — so use the exact names above.`,
         inputSchema: {
             type: 'object',
             properties: {
                 itemId: { type: 'string', description: 'Registry ID of the item' },
                 animationType: {
                     type: 'string',
-                    enum: ['pulse', 'rotate', 'bounce', 'fade', 'wobble', 'slide', 'typewriter'],
+                    enum: ['bounce', 'breathe', 'fade', 'glow', 'jelly', 'path', 'pulse', 'rotate', 'scrollDown', 'scrollLeft', 'scrollRight', 'scrollUp', 'shake', 'slideLeftRight', 'slideUpDown', 'swing', 'typewriter', 'wobble'],
                     description: 'Type of animation',
                 },
                 speed: {
@@ -2635,15 +3326,45 @@ USE WHEN:
 - Seeking to specific time
 - Controlling animation state
 
-DETERMINISTIC SEEK: pass deterministic: true with action 'seek' to evaluate the WHOLE scene at the exact time via app.sceneAt(t) — keyframes + relations + generators all tick to t, so the same time always yields the same frame (paired with a seed in pinepaper_capture_frames for reproducible output). Plain seek only sets the keyframe playback state. Use deterministic seek before pinepaper_browser_screenshot to capture a reproducible frame.`,
+DETERMINISTIC SEEK: pass deterministic: true with action 'seek' to evaluate the WHOLE scene at the exact time via app.sceneAt(t) — keyframes + relations + generators all tick to t, so the same time always yields the same frame (paired with a seed in pinepaper_capture_frames for reproducible output). Plain seek only sets the keyframe playback state. Use deterministic seek before pinepaper_browser_screenshot to capture a reproducible frame.
+
+RATE (set_time_scale / get_time_scale): 1 is real time, 0.5 half speed, 0 freezes the clock WITHOUT stopping playback, and a negative rate runs the scene backwards. Changing it preserves the current position — the clock is rebased, so the playhead does not jump. Export is deliberately unaffected: a scene watched at 0.5x still exports its real duration rather than a file twice as long.
+
+PROGRESS (get_progress / set_progress): the timeline as 0..1, which is the unit a scrubber or a progress bar actually has. set_progress returns the seconds it landed on.
+
+SCROLL (bind_scroll / unbind_scroll / list_scrub_anchors): drive the timeline from how far the reader has scrolled instead of from a clock — what makes a scroll-told story a story rather than a video that happens to be on the page. Anchors ('top bottom' = the moment the element appears, 'bottom top' = the moment it is gone) say where the range starts and ends; scrub is a smoothing time constant so the playhead chases the scroll instead of snapping to it. Chiefly for embeds and generated code — nothing scrolls a headless page. ALWAYS unbind before rebinding or navigating away: the listener holds the scene alive. bind_scroll releases a previous binding for you, and unbind_scroll on nothing bound answers { bound: false } rather than failing.`,
         inputSchema: {
             type: 'object',
             properties: {
                 action: {
                     type: 'string',
-                    enum: ['play', 'pause', 'stop', 'seek'],
+                    enum: [
+                        'play', 'pause', 'stop', 'seek',
+                        'set_time_scale', 'get_time_scale',
+                        'get_progress', 'set_progress',
+                        'bind_scroll', 'unbind_scroll', 'list_scrub_anchors',
+                    ],
                     description: 'Playback action',
                 },
+                rate: {
+                    type: 'number',
+                    description: 'set_time_scale: 1 real time, 0.5 half speed, 0 freezes without stopping, negative runs backwards. Export is unaffected.',
+                },
+                progress: {
+                    type: 'number',
+                    description: 'set_progress: how far through the timeline, 0..1',
+                },
+                scroll: {
+                    type: 'object',
+                    properties: {
+                        elementId: { type: 'string', description: 'DOM id of the element to track (defaults to the canvas)' },
+                        start: { type: 'string', description: "Anchor where the range begins, e.g. 'top bottom' — see list_scrub_anchors" },
+                        end: { type: 'string', description: "Anchor where the range ends, e.g. 'bottom top'" },
+                        scrub: { type: 'number', description: 'Seconds of smoothing so the playhead chases the scroll (default 0.3; 0 snaps)' },
+                        range: { type: 'array', items: { type: 'number' }, description: '[from, to] seconds — drive only a sub-range of the timeline' },
+                    },
+                    description: 'bind_scroll options',
+                },
                 duration: {
                     type: 'number',
                     description: 'Duration for play action',
@@ -3131,7 +3852,7 @@ EXAMPLE - Bouncing Balls:
 
 SUPPORTED ITEM TYPES: text, circle, star, rectangle, triangle, polygon, ellipse, path, line, arc
 SUPPORTED RELATIONS: orbits, follows, attached_to, maintains_distance, points_at, mirrors, parallax, bounds_to, animates, grows_from, staggered_with, indicates, circumscribes, wave_through, camera_follows, camera_animates, morphs_to, group_morphs_to, moves_along_path, is_midpoint_of, lies_on_line, is_centroid_of, is_circumcenter_of, concentric_with, construction_reveal
-SUPPORTED ANIMATIONS: pulse, rotate, bounce, fade, wobble, slide, typewriter`,
+SUPPORTED ANIMATIONS: bounce, breathe, fade, glow, jelly, path, pulse, rotate, scrollDown, scrollLeft, scrollRight, scrollUp, shake, slideLeftRight, slideUpDown, swing, typewriter, wobble`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -3176,7 +3897,7 @@ SUPPORTED ANIMATIONS: pulse, rotate, bounce, fade, wobble, slide, typewriter`,
                             target: { type: 'string', description: 'Name of target item' },
                             type: {
                                 type: 'string',
-                                enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'camera_follows', 'camera_animates', 'morphs_to', 'group_morphs_to', 'moves_along_path', 'is_midpoint_of', 'lies_on_line', 'is_centroid_of', 'is_circumcenter_of', 'concentric_with', 'construction_reveal', 'driven_by', 'time_expression', 'on_event_fire_after', 'on_event_add_relation', 'on_event_remove_relation', 'on_event_set_color', 'on_event_set_property', 'on_event_set_visibility', 'on_top_of', 'below', 'beside', 'inside', 'centered_on', 'aligned_with'],
+                                enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'anchored_in_world', 'spring_follow', 'repels', 'attracts', 'wiggle', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'morphs_to', 'group_morphs_to', 'moves_along_path', 'construction_reveal', 'triggers_animation', 'syncs_with', 'tours', 'synced_to_audio', 'expresses', 'camera_follows', 'camera_animates', 'is_midpoint_of', 'lies_on_line', 'is_centroid_of', 'is_circumcenter_of', 'concentric_with', 'driven_by', 'time_expression', 'on_click_fire', 'on_pointer_enter_fire', 'on_pointer_exit_fire', 'on_key_fire', 'on_event_fire_after', 'on_event_fire_if', 'on_event_add_relation', 'on_event_remove_relation', 'on_event_set_color', 'on_event_set_property', 'on_event_set_property_from_template', 'on_event_set_visibility', 'on_event_set_active', 'on_event_set_data', 'on_event_increment', 'on_event_toggle', 'on_event_store_set', 'on_event_store_increment', 'on_enter_set_color', 'on_enter_set_property', 'on_enter_set_property_from_template', 'on_enter_set_visibility', 'on_enter_set_data', 'on_enter_increment', 'on_enter_toggle', 'on_exit_set_color', 'on_exit_set_property', 'on_exit_set_property_from_template', 'on_exit_set_visibility', 'on_exit_set_data', 'on_exit_increment', 'on_exit_toggle', 'exclusive_group', 'menubar_group', 'restores_from', 'on_top_of', 'below', 'beside', 'inside', 'centered_on', 'aligned_with', 'part_of', 'connects_to', 'attached_to_tail', 'head_points_to'],
                             },
                             params: {
                                 type: 'object',
@@ -3196,7 +3917,7 @@ SUPPORTED ANIMATIONS: pulse, rotate, bounce, fade, wobble, slide, typewriter`,
                             target: { type: 'string', description: 'Name of item to animate' },
                             type: {
                                 type: 'string',
-                                enum: ['pulse', 'rotate', 'bounce', 'fade', 'wobble', 'slide', 'typewriter'],
+                                enum: ['bounce', 'breathe', 'fade', 'glow', 'jelly', 'path', 'pulse', 'rotate', 'scrollDown', 'scrollLeft', 'scrollRight', 'scrollUp', 'shake', 'slideLeftRight', 'slideUpDown', 'swing', 'typewriter', 'wobble'],
                             },
                             speed: { type: 'number', description: 'Animation speed (default: 1.0)' },
                             params: {
@@ -3334,6 +4055,361 @@ EXAMPLE — Slideshow:
             required: ['action'],
         },
     },
+    {
+        name: 'pinepaper_sequence',
+        annotations: {
+            title: 'Timeline Sequencing (Relative Positions)',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: `Work out WHEN clips start, said relative to each other instead of in absolute seconds. A pure planner — it computes times and touches nothing on the canvas. (For revealing a geometric construction step by step, that is pinepaper_construction_sequence, a different tool.)
+
+Nobody thinks "the subtitle starts at 1.85s"; they think "a quarter of a second after the title finishes". This resolves the second into the first, and re-resolves it when an earlier clip changes length.
+
+ACTIONS:
+- place: thread a whole run of clips, each resolved against the ones before it. Returns { placed: [{start, end, duration}], labels, duration }.
+- resolve: answer a single position spec against a context you supply.
+- list_forms: the accepted grammar, each form with what it means.
+
+POSITION FORMS:
+- 3 — exactly 3s from the start of the timeline
+- "<" / ">" — when the previous clip STARTED / ENDED
+- "<2" / ">2" — 2s after the previous clip started / ended
+- "+=1" / "-=1" — 1s after the timeline ends (a gap) / 1s before it (an overlap)
+- "intro" / "intro+=0.5" — at a label, or half a second after it
+- omitted — append at the end, which is what appending has always meant
+
+THE ONE THING TO GET RIGHT: a percentage means different things in different forms.
+- "-=25%" and "+=25%" scale against the clip BEING INSERTED — "overlap the previous clip by a quarter of MY length".
+- "<25%" and ">25%" scale against the PREVIOUS clip — "start a quarter of the way THROUGH it".
+They agree only when the two clips are the same length, which is rarely, and getting it backwards yields timings that look almost right.
+
+A label names the moment a clip STARTS, so "label+=0" lands on the clip rather than skipping it. The timeline only ever grows — placing something early with "-=" never pulls the end back.
+
+EXAMPLE:
+{
+  "action": "place",
+  "clips": [
+    { "id": "title",    "duration": 2, "label": "intro" },
+    { "id": "subtitle", "duration": 4, "position": "-=25%" },
+    { "id": "cta",      "duration": 1, "position": "intro+=0.5" }
+  ]
+}`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['place', 'resolve', 'list_forms'],
+                    description: 'place (a run of clips), resolve (one position), or list_forms (default: place)',
+                },
+                clips: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            id: { type: 'string', description: 'Your own name for the clip — echoed back on the placement' },
+                            duration: { type: 'number', description: 'How long the clip runs, in seconds' },
+                            position: {
+                                anyOf: [{ type: 'number' }, { type: 'string' }],
+                                description: 'Where it starts. Omit to append at the end of the run so far.',
+                            },
+                            label: { type: 'string', description: 'Name this moment for later clips to position against. Marks where the clip STARTS.' },
+                        },
+                        required: ['duration'],
+                    },
+                    description: 'place: the run of clips, in order',
+                },
+                position: {
+                    anyOf: [{ type: 'number' }, { type: 'string' }],
+                    description: 'resolve: the single position spec to resolve',
+                },
+                context: {
+                    type: 'object',
+                    properties: {
+                        timelineEnd: { type: 'number', description: 'Where the timeline currently ends — what "+=1" counts from' },
+                        prevStart: { type: 'number', description: 'Start of the most recent clip — what "<" means' },
+                        prevEnd: { type: 'number', description: 'End of the most recent clip — what ">" means' },
+                        insertDuration: { type: 'number', description: 'Duration of the clip being placed — the basis for a "+=25%" percentage' },
+                    },
+                    description: 'resolve: what the spec is measured against',
+                },
+                labels: {
+                    type: 'object',
+                    additionalProperties: { type: 'number' },
+                    description: 'Named moments in seconds, addressable as "name" or "name+=0.5"',
+                },
+                startAt: { type: 'number', description: 'place: where the run begins (default 0)' },
+            },
+        },
+    },
+    {
+        name: 'pinepaper_stagger',
+        annotations: {
+            title: 'Stagger',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: `Shape a delay across many items. What makes a stagger read as designed rather than as a queue is where it STARTS and how it SPREADS — a grid lighting up outward from the centre, a row converging from both edges.
+
+Delays are written to the channel the engine and the SMIL exporter already read, so a staggered scene scrubs, exports and restores. Nothing here is playback-only.
+
+ACTIONS:
+- apply: write the delays onto real items, in the order you list them (row-major for a grid).
+- preview: the delays for a count, without touching the canvas.
+- list_origins: the origins, each with what it means.
+
+each VS amount — alternatives, not a pair:
+- each fixes the gap between NEIGHBOURS, so more items make a longer sequence.
+- amount fixes the TOTAL, so more items crowd together. It overrides each.
+
+ORIGINS (from):
+- start — the first item goes first, in order. The plain queue.
+- end — the last goes first; the sequence runs backwards.
+- center — spreads outward from the middle of the run or grid.
+- edges — starts at both ends at once and converges on the middle.
+- random — a shuffled ORDER, not random delays: every item still lands on one of the same slots, so the rhythm survives. Seeded.
+from also takes an item index, or [fx, fy] fractions for a grid ([0.5, 0.5] is the centre).
+
+ease distributes the START TIMES. It is not the items' own animation curve.
+
+EXAMPLE — a 3x3 grid lighting up from the middle:
+{ "action": "apply", "itemIds": ["a","b","c","d","e","f","g","h","i"], "opts": { "each": 0.1, "from": "center", "grid": [3, 3] } }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['apply', 'preview', 'list_origins'],
+                    description: 'apply (to items), preview (delays only), or list_origins (default: apply)',
+                },
+                itemIds: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'apply: registry IDs in the order the stagger should follow (row-major for a grid)',
+                },
+                count: { type: 'number', description: 'preview: how many items to compute delays for' },
+                opts: {
+                    type: 'object',
+                    properties: {
+                        each: { type: 'number', description: 'Seconds between neighbours (default 0.1)' },
+                        amount: { type: 'number', description: 'Total seconds for the whole run — overrides each' },
+                        from: {
+                            anyOf: [
+                                { type: 'string', enum: ['start', 'end', 'center', 'edges', 'random'] },
+                                { type: 'number' },
+                                { type: 'array', items: { type: 'number' } },
+                            ],
+                            description: 'Named origin, an item index, or [fx, fy] fractions for a grid',
+                        },
+                        grid: { type: 'array', items: { type: 'number' }, description: '[rows, columns] for a 2D stagger' },
+                        axis: { type: 'string', enum: ['x', 'y'], description: 'Restrict a grid stagger to one axis' },
+                        ease: {
+                            type: 'string',
+                            enum: ['linear', 'easeIn', 'easeOut', 'easeInOut', 'easeInCubic', 'easeOutCubic'],
+                            description: "Curve that distributes the START TIMES — not the items' own animation",
+                        },
+                        seed: { type: 'number', description: "from: 'random' — same seed, same shuffle (default 1)" },
+                    },
+                    description: 'Shape of the stagger',
+                },
+            },
+        },
+    },
+    {
+        name: 'pinepaper_flip',
+        annotations: {
+            title: 'Flip (Derived Transition)',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Animate a layout change WITHOUT describing the motion. Every other animation tool asks you to say what the movement is; this asks the opposite — record where things are, rearrange them however you like, and the transition is derived from the difference.
+
+That is what makes it usable for changes nobody could enumerate in advance: a re-sort, an auto-layout pass, a filter, a drag.
+
+THE ORDER MATTERS:
+1. action: 'record' — capture the current positions.
+2. Rearrange, with any tools you like (move, align, sort, re-layout).
+3. action: 'apply' — the motion between the two states is worked out and written.
+
+Recording after the change, or skipping step 2, produces nothing to animate.
+
+It writes ordinary keyframes, so the transition scrubs on the timeline, exports through the MP4 / SMIL / Lottie paths, and survives a reload. Only properties that ACTUALLY changed are written — a track that also pinned the unchanged ones would fight anything else animating them, and a flip of position would quietly freeze an item's own pulse.
+
+Rotation is compared on the shortest arc: 359 to 1 degrees is a two-degree move, not a near-full spin the wrong way.
+
+READ THE RESULT: 'entered' are items that appeared during the change and were given an entrance rather than popping in. 'left' are items that went away — they cannot be animated out, because they are already gone. Remove things AFTER the flip, not before.
+
+EXAMPLE:
+{ "action": "apply", "duration": 0.6, "easing": "easeInOut", "stagger": { "each": 0.05, "from": "center" } }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['record', 'apply'],
+                    description: "'record' before the change, 'apply' after it (default: record)",
+                },
+                itemIds: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'record: which items to capture (defaults to everything on the item layer)',
+                },
+                duration: { type: 'number', description: 'apply: seconds the transition runs' },
+                easing: { type: 'string', description: 'apply: named easing for the generated keyframes' },
+                enter: { type: 'string', description: 'apply: entrance preset for items that appeared during the change' },
+                stagger: {
+                    type: 'object',
+                    properties: {
+                        each: { type: 'number', description: 'Seconds between neighbours' },
+                        amount: { type: 'number', description: 'Total seconds for the whole run — overrides each' },
+                        from: {
+                            anyOf: [
+                                { type: 'string', enum: ['start', 'end', 'center', 'edges', 'random'] },
+                                { type: 'number' },
+                                { type: 'array', items: { type: 'number' } },
+                            ],
+                            description: 'Named origin, an item index, or [fx, fy] fractions for a grid',
+                        },
+                        grid: { type: 'array', items: { type: 'number' }, description: '[rows, columns]' },
+                        axis: { type: 'string', enum: ['x', 'y'], description: 'Restrict a grid stagger to one axis' },
+                        ease: {
+                            type: 'string',
+                            enum: ['linear', 'easeIn', 'easeOut', 'easeInOut', 'easeInCubic', 'easeOutCubic'],
+                            description: 'Curve that distributes the START TIMES',
+                        },
+                        seed: { type: 'number', description: 'Seed for the random origin' },
+                    },
+                    description: "apply: stagger the transition across the items, in the items' own order",
+                },
+            },
+        },
+    },
+    {
+        name: 'pinepaper_scene_graph',
+        annotations: {
+            title: 'Scene Graph (Interactive Stories / Quizzes)',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Create an interactive multi-node story or quiz card graph. Compiles cards, answer buttons, click-to-event routing, exclusive-group mutex visibility, and scoring into native items and relations.
+
+ACTIONS:
+- create (default): build the graph on the canvas.
+- validate: run the same structural check WITHOUT drawing anything. Returns errors, warnings, the nodes reachable from start, and any cycles. Cheap — use it on a graph you generated before committing a canvas full of cards to it.
+
+HOW IT WORKS:
+1. Provide a graph with nodes and choices (start node, question cards with answers pointing to other node IDs, end cards with outcome text).
+2. The engine compiles the card stack, creates panel rectangles and styled text items, wires on_click_fire -> event -> on_event_set_active relations, and binds active card mutex state.
+3. If scoreItemId is provided, correct answers automatically wire on_event_increment to track score.
+
+TWO WAYS OUT OF A CARD: 'answers' waits for a click (a quiz). 'next' advances on its own after 'duration' seconds (a linear story beat). Every non-terminal node needs one or the other, or the player is stuck; mark outcome cards kind: 'end'.
+
+READ THE RESULT: 'failed' counts relations that did not wire. A graph can render completely and still be inert, and that count is the only thing that says so. 'cycles' reports loops — legitimate for a retry, an accidental one is a game that never ends.
+
+EXAMPLE — Interactive Quiz:
+{
+  "graph": {
+    "start": "q1",
+    "nodes": [
+      {
+        "id": "q1",
+        "prompt": "Which planet is known as the Red Planet?",
+        "answers": [
+          { "text": "Mars", "correct": true, "to": "win" },
+          { "text": "Venus", "to": "lose" }
+        ]
+      },
+      { "id": "win", "kind": "end", "text": "Correct! Mars is rich in iron oxide." },
+      { "id": "lose", "kind": "end", "text": "Not quite! Mars is the Red Planet." }
+    ]
+  },
+  "opts": {
+    "style": { "panelColor": "#1E1B4B", "textColor": "#F8FAFC", "answerColor": "#93C5FD" }
+  }
+}`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['create', 'validate'],
+                    description: "'create' builds it (default) · 'validate' checks it without drawing",
+                },
+                graph: {
+                    type: 'object',
+                    properties: {
+                        start: { type: 'string', description: 'Initial active node id' },
+                        nodes: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    id: { type: 'string', description: 'Unique node id' },
+                                    prompt: { type: 'string', description: 'Prompt text for question cards' },
+                                    text: { type: 'string', description: 'Text for message/end cards' },
+                                    kind: { type: 'string', enum: ['node', 'card', 'end'], description: "Card kind: 'node'/'card' (content) or 'end' (terminal)" },
+                                    answers: {
+                                        type: 'array',
+                                        items: {
+                                            type: 'object',
+                                            properties: {
+                                                text: { type: 'string', description: 'Answer button text' },
+                                                correct: { type: 'boolean', description: 'Is correct answer' },
+                                                to: { type: 'string', description: 'Destination node id' },
+                                            },
+                                            required: ['text', 'to'],
+                                        },
+                                        description: 'Interactive answer buttons — the card waits for a click',
+                                    },
+                                    next: { type: 'string', description: 'Unconditional destination — the card auto-advances instead of waiting for a click. Use INSTEAD of answers.' },
+                                    duration: { type: 'number', description: 'Seconds the card holds before `next` fires (default 3). Ignored without `next`.' },
+                                    outcome: { type: 'string', enum: ['win', 'lose'], description: 'Force a terminal node\u2019s outcome. Without it the engine infers it from the wording, which only works in English.' },
+                                },
+                                required: ['id'],
+                            },
+                            description: 'List of graph nodes',
+                        },
+                    },
+                    required: ['nodes'],
+                    description: 'Scene graph definition',
+                },
+                opts: {
+                    type: 'object',
+                    properties: {
+                        width: { type: 'number', description: 'Layout width' },
+                        height: { type: 'number', description: 'Layout height' },
+                        centerX: { type: 'number', description: 'Center X coordinate' },
+                        centerY: { type: 'number', description: 'Center Y coordinate' },
+                        groupName: { type: 'string', description: 'Seed / prefix for IDs' },
+                        scoreItemId: { type: 'string', description: 'Scoreboard item ID to increment on correct answers' },
+                        subject: { type: 'string', description: "Theme of the piece, folded into each card's text-effect selection (e.g. 'space exploration')" },
+                        plain: { type: 'boolean', description: 'Plain mode without entrance/text effects' },
+                        style: {
+                            type: 'object',
+                            properties: {
+                                panelColor: { type: 'string', description: 'Card panel background color' },
+                                textColor: { type: 'string', description: 'Card text color' },
+                                answerColor: { type: 'string', description: 'Answer button text color' },
+                                headlineSize: { type: 'number', description: 'Prompt font size' },
+                                bodySize: { type: 'number', description: 'Answer/body font size' },
+                            },
+                        },
+                    },
+                    description: 'Layout and styling options',
+                },
+            },
+            required: ['graph'],
+        },
+    },
     // ---------------------------------------------------------------------------
     // LAYER 4 — COMPOSITIONS: SELECTION, TRANSFORM & HISTORY TOOLS
     // ---------------------------------------------------------------------------
@@ -3464,6 +4540,11 @@ flags as a badly-composed scene, and they do not survive an artboard change.`,
         inputSchema: {
             type: 'object',
             properties: {
+                register: { type: 'string', enum: ['naive', 'playful', 'poster', 'editorial', 'technical'], description: 'Which design language. Resolves gutter, margin, hue budget and type scale together; an explicit craft still overrides it.' },
+                level: { type: 'number', description: 'Craft level 1-4 within the register: sketch, competent, refined, art-directed.' },
+                medium: { type: 'string', enum: ['vector', 'thread'], description: "What makes the marks. 'thread' stitches every closed path AFTER arranging; photographs and text cannot be stitched and return in medium.skipped with the reason. Other media are refused with their own reason rather than faked." },
+                stitch: { type: 'string', enum: [...THREAD_STITCHES], description: 'Which stitch when medium is thread (default longAndShort) — the same six pinepaper_design_medium offers.' },
+                stitchBudget: { type: 'number', description: 'Total marks across the composition (default 6000); the stitch scales to fit rather than the fill being cut short.' },
                 action: { type: 'string', enum: ['list_patterns', 'list_treatments', 'apply', 'set_treatment'] },
                 pattern: { type: 'string', description: 'Pattern key from list_patterns' },
                 itemIds: { type: 'array', items: { type: 'string' }, description: 'Items in slot order' },
@@ -3566,7 +4647,10 @@ Overrides are the point: an instance can differ from its master and still receiv
                 },
                 componentKey: { type: 'string', description: 'Which part of the component to override' },
                 prop: { type: 'string', description: 'Property to override, e.g. fillColor or content' },
-                value: { description: 'Override value' },
+                value: {
+                    anyOf: [{ type: 'string' }, { type: 'number' }, { type: 'boolean' }, { type: 'object' }, { type: 'array' }],
+                    description: 'Override value',
+                },
                 overrides: { type: 'object', description: 'Overrides applied at instantiate time' },
             },
             required: ['action'],
@@ -4006,6 +5090,88 @@ ACTIONS:
             required: ['action'],
         },
     },
+    {
+        name: 'pinepaper_query_capabilities',
+        annotations: {
+            title: 'Query Capabilities',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: `Discover and match capabilities across the engine — text styles, character-level text effects, generators, vertex deforms, and behavioral relations.
+
+ACTIONS:
+- list: List all available capabilities or filter by kind (style, effect, generator, deform, relation, etc.).
+- choose: Mood- and context-weighted recommendation based on subject/prompt words and target feeling.
+- coverage: Report total indexable and describable capabilities across categories.
+- find: Direct lookup of a capability by key to inspect its description and how to apply it (applyWith).
+
+MOOD VOCABULARY FOR CHOOSE:
+- reveal: resolve, reveal, appear, emerge, decode, decrypt, unscramble, form, assemble
+- triumphant: burst, launch, firework, bloom, spark, explode, shine, glow, celebrate, rise
+- failure: crumble, fall, collapse, burn, decay, dissolve, break, shatter, sink, error
+- calm: drift, float, gentle, slow, settle, fade, wave, ripple, pour
+- technical: binary, matrix, grid, scan, code, digital, circuit, data, print, terminal
+- energetic: bounce, swarm, spray, shoot, fast, rapid, scatter, slam, volley
+
+EXAMPLE — Choose effect for a victory card:
+{
+  "action": "choose",
+  "kind": "effect",
+  "mood": "triumphant",
+  "subject": "celebrate correct answer",
+  "seed": "quiz_q1"
+}`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['list', 'choose', 'coverage', 'find', 'catalogue', 'studio'],
+                    description: "Query mode: list, choose, coverage, find, catalogue, or studio (default: list). 'catalogue' reads a registry the aggregate does not gather. 'studio' reports which engine METHODS this studio has, so you learn what will refuse BEFORE calling it — long-form export needs exportEngine.exportToStore, mesh authoring needs extrudeToMesh, and this is how you find out without trying each.",
+                },
+                catalogue: {
+                    type: 'string',
+                    enum: ['rig_presets', 'shader_effects', 'stroke_decorations', 'precomps', 'images', 'segment_edit_kinds', 'shatter_orders', 'world_meshes', 'relation_presets'],
+                    description: "action 'catalogue': which registry to read. These sit OUTSIDE the aggregate, which already covers styles, effects, deforms, entrances, animations, collages, palettes, masks, maskShapes and cutouts — 'list' reaches all of those.",
+                },
+                kind: {
+                    anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
+                    description: 'Filter by capability kind (style, effect, deform, entrance, animation, generator, collage, palette, mask, cutout, relation)',
+                },
+                mood: {
+                    anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
+                    description: "Target feeling for choose: reveal, triumphant, failure, calm, technical, energetic",
+                },
+                subject: {
+                    type: 'string',
+                    description: 'Contextual prompt/subject text to score against capability definitions',
+                },
+                avoid: {
+                    anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
+                    description: 'Mood keys to penalize — only the six vocabulary keys above are matched, arbitrary words are ignored',
+                },
+                seed: {
+                    type: 'string',
+                    description: 'Deterministic seed string for reproducible selection',
+                },
+                key: {
+                    type: 'string',
+                    description: 'Capability key to look up (for find action)',
+                },
+                exclude: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Keys to exclude from choose recommendation',
+                },
+                warm: {
+                    type: 'boolean',
+                    description: 'Load the lazy registries before answering (default true). Generators and the rigging/blending/deform relation rules only exist once touched, so a cold answer omits them — pass false only to cheaply re-read what is already resident.',
+                },
+            },
+        },
+    },
     // ---------------------------------------------------------------------------
     // DEFORMATION, SPRITE SHEETS, INTERACTION
     // ---------------------------------------------------------------------------
@@ -4428,6 +5594,10 @@ RETURNS:
         inputSchema: {
             type: 'object',
             properties: {
+                id: {
+                    type: 'string',
+                    description: 'Stable ID for the connector. Assign your own and reuse it as `connectorId` in pinepaper_update_connector / pinepaper_remove_connector — creation does not return an ID you can rely on. Without one the engine mints a timestamp-based ID that no caller can predict.',
+                },
                 sourceItemId: {
                     type: 'string',
                     description: 'Registry ID of the source item (where arrow starts)',
@@ -4521,6 +5691,10 @@ Same as pinepaper_connect: routing, lineColor, lineWidth, lineStyle, headStyle,
         inputSchema: {
             type: 'object',
             properties: {
+                id: {
+                    type: 'string',
+                    description: 'Stable ID for the connector. Assign your own and reuse it as `connectorId` in pinepaper_update_connector / pinepaper_remove_connector — creation does not return an ID you can rely on. Without one the engine mints a timestamp-based ID that no caller can predict.',
+                },
                 sourceItemId: {
                     type: 'string',
                     description: 'Registry ID of the source item',
@@ -5554,7 +6728,7 @@ USE WHEN:
 - Celebration effects (confetti)
 - Enhancing visual impact (ripple, glow, electric)
 
-EFFECTS (15 particle + 3 shader auras):
+EFFECTS (15 particle + 7 shader auras):
 - sparkle: Glitter/sparkle particles (color, speed, size)
 - blast: Explosion burst effect (color, radius, count)
 - smoke: Rising smoke plumes (color, speed, size, drift, height, growthRate)
@@ -5575,6 +6749,11 @@ SHADER AURAS (WebGL2, silhouette-clipped — same tool, routed to the aura syste
 - heatmap: Thermal shimmer aura (palette 0=Hot 1=Cool 2=Violet)
 - liquid_metal: Flowing metallic sheen (palette 0=Chrome 1=Gold 2=Copper)
 - gem_smoke: Crystalline smoke wisps
+- electric_arc: Branching discharge filaments with a hot core and inverse-square bloom. Stepped flicker, not a sine — a stroke is a train of return strokes, which reads far more electric than a smooth pulse.
+- vortex: The bright band is a RING, not a disc — condensation tracks the steepest pressure gradient, so the core is hollow, and differential rotation shears the field rather than spinning one picture round.
+- rain_veil: Drifting sheets of falling rain across the silhouette.
+- caustics: Refracted light patterns, as through moving water.
+- ink_bleed: Ink wicking outward into the surface, as on absorbent paper. Routable since the engine began publishing every aura name and warming the subsystem before routing; it was defined-but-unreachable before that, which is why it arrived last.
 Aura params: { intensity, radius, palette, mode ('inside'|'outside'|'overlay'), tint, tintStrength, offsetX, offsetY, channels: { a: {speed, curve}, b: {speed, curve} } } — curves: linear, sawtooth, sine, triangle, pulse, ease, bounce, noise.
 
 EXAMPLE — bubbles with magenta interior over a blue rim:
@@ -5587,7 +6766,7 @@ EXAMPLE — gold liquid-metal aura outside a logo:
                 itemId: { type: 'string', description: 'Registry ID of the item' },
                 effectType: {
                     type: 'string',
-                    enum: ['sparkle', 'blast', 'smoke', 'fire', 'rain', 'snow', 'confetti', 'ripple', 'glow', 'electric', 'bubbles', 'dust', 'fireflies', 'shockwave', 'trail', 'heatmap', 'liquid_metal', 'gem_smoke'],
+                    enum: ['sparkle', 'blast', 'smoke', 'fire', 'rain', 'snow', 'confetti', 'ripple', 'glow', 'electric', 'bubbles', 'dust', 'fireflies', 'shockwave', 'trail', 'heatmap', 'liquid_metal', 'gem_smoke', 'electric_arc', 'vortex', 'rain_veil', 'caustics', 'ink_bleed'],
                     description: 'Type of effect',
                 },
                 params: {
@@ -6068,7 +7247,7 @@ PRIVACY: No screenshots, no tool call arguments, no user content — only struct
             idempotentHint: false,
             openWorldHint: false,
         },
-        description: `Start a new agent job for creating animations, videos, graphics, or any visual content. Do NOT generate HTML or React — use PinePaper tools instead.
+        description: `Start a new agent job for creating animations, videos, graphics, or any visual content. Do not hand-write HTML or React INSTEAD OF calling these tools — but if the user wants an HTML page or an embeddable widget, that is pinepaper_export_widget_html and pinepaper_export_widget, and they are the right answer rather than a fallback.
 
 ⚠️ Call ONCE per pipeline. NEVER restart — creates duplicates.
 
@@ -6347,7 +7526,7 @@ EXAMPLE — Animated sky scene with timed reveals:
                             // Loop animation
                             animationType: {
                                 type: 'string',
-                                enum: ['pulse', 'rotate', 'bounce', 'fade', 'wobble', 'slide', 'typewriter'],
+                                enum: ['bounce', 'breathe', 'fade', 'glow', 'jelly', 'path', 'pulse', 'rotate', 'scrollDown', 'scrollLeft', 'scrollRight', 'scrollUp', 'shake', 'slideLeftRight', 'slideUpDown', 'swing', 'typewriter', 'wobble'],
                                 description: 'For animate: loop animation type',
                             },
                             animationOptions: { type: 'object', description: 'For animate: {speed, amplitude, direction}' },
@@ -6371,7 +7550,7 @@ EXAMPLE — Animated sky scene with timed reveals:
                             targetId: { type: 'string', description: 'For relation: target item ID or $N' },
                             relationType: {
                                 type: 'string',
-                                enum: ['orbits', 'follows', 'attached_to', 'points_at', 'mirrors', 'parallax', 'animates', 'grows_from', 'staggered_with', 'wave_through', 'circumscribes', 'morphs_to', 'group_morphs_to', 'moves_along_path', 'maintains_distance', 'bounds_to', 'indicates', 'camera_follows', 'camera_animates', 'is_midpoint_of', 'lies_on_line', 'is_centroid_of', 'is_circumcenter_of', 'concentric_with', 'construction_reveal', 'driven_by', 'time_expression', 'on_event_fire_after', 'on_event_add_relation', 'on_event_remove_relation', 'on_event_set_color', 'on_event_set_property', 'on_event_set_visibility', 'on_top_of', 'below', 'beside', 'inside', 'centered_on', 'aligned_with'],
+                                enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'anchored_in_world', 'spring_follow', 'repels', 'attracts', 'wiggle', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'morphs_to', 'group_morphs_to', 'moves_along_path', 'construction_reveal', 'triggers_animation', 'syncs_with', 'tours', 'synced_to_audio', 'expresses', 'camera_follows', 'camera_animates', 'is_midpoint_of', 'lies_on_line', 'is_centroid_of', 'is_circumcenter_of', 'concentric_with', 'driven_by', 'time_expression', 'on_click_fire', 'on_pointer_enter_fire', 'on_pointer_exit_fire', 'on_key_fire', 'on_event_fire_after', 'on_event_fire_if', 'on_event_add_relation', 'on_event_remove_relation', 'on_event_set_color', 'on_event_set_property', 'on_event_set_property_from_template', 'on_event_set_visibility', 'on_event_set_active', 'on_event_set_data', 'on_event_increment', 'on_event_toggle', 'on_event_store_set', 'on_event_store_increment', 'on_enter_set_color', 'on_enter_set_property', 'on_enter_set_property_from_template', 'on_enter_set_visibility', 'on_enter_set_data', 'on_enter_increment', 'on_enter_toggle', 'on_exit_set_color', 'on_exit_set_property', 'on_exit_set_property_from_template', 'on_exit_set_visibility', 'on_exit_set_data', 'on_exit_increment', 'on_exit_toggle', 'exclusive_group', 'menubar_group', 'restores_from', 'on_top_of', 'below', 'beside', 'inside', 'centered_on', 'aligned_with', 'part_of', 'connects_to', 'attached_to_tail', 'head_points_to'],
                                 description: 'For relation: type',
                             },
                             relationOptions: { type: 'object', description: 'For relation: options' },
@@ -6386,7 +7565,7 @@ EXAMPLE — Animated sky scene with timed reveals:
                             // Effects
                             effectType: {
                                 type: 'string',
-                                enum: ['sparkle', 'blast', 'smoke', 'fire', 'rain', 'snow', 'confetti', 'ripple', 'glow', 'electric', 'bubbles', 'dust', 'fireflies', 'shockwave', 'trail', 'heatmap', 'liquid_metal', 'gem_smoke'],
+                                enum: ['sparkle', 'blast', 'smoke', 'fire', 'rain', 'snow', 'confetti', 'ripple', 'glow', 'electric', 'bubbles', 'dust', 'fireflies', 'shockwave', 'trail', 'heatmap', 'liquid_metal', 'gem_smoke', 'electric_arc', 'vortex', 'rain_veil', 'caustics'],
                                 description: 'For apply_effect: effect type',
                             },
                             effectParams: { type: 'object', description: 'For apply_effect: parameters' },
@@ -6458,8 +7637,17 @@ EXAMPLES:
                 },
                 format: {
                     type: 'string',
-                    enum: ['svg', 'png', 'gif', 'mp4', 'webm', 'pdf'],
-                    description: 'Override format (auto-detected if not specified)',
+                    enum: ['svg', 'png', 'gif', 'mp4', 'webm', 'pdf', 'wav'],
+                    description: "Override format (auto-detected if not specified). 'wav' exports the SOUNDTRACK ON ITS OWN, with no frames rendered — no platform preset resolves to it, so it must be asked for by name, and platform dimensions, framing and quality do not apply.",
+                },
+                sampleRate: {
+                    type: 'number',
+                    description: 'wav only: samples per second (default 48000). Rejected for any other format.',
+                },
+                bitDepth: {
+                    type: 'number',
+                    enum: [16, 32],
+                    description: 'wav only: 16 (default) or 32-bit float. Rejected for any other format.',
                 },
                 quality: {
                     type: 'string',
@@ -6473,7 +7661,7 @@ EXAMPLES:
                 },
                 estimateOnly: {
                     type: 'boolean',
-                    description: 'Preflight only — return the estimated file size for these exact settings and render nothing. Modeled for mp4/webm/gif; png/pdf/svg report confidence "none" (no dimension-based model exists for them).',
+                    description: 'Preflight only — return the estimated file size for these exact settings and render nothing. Modeled for mp4/webm/gif; png/pdf/svg report confidence "none" (no dimension-based model exists for them); wav reports confidence "exact", because uncompressed PCM size is arithmetic.',
                 },
                 duration: {
                     type: 'number',
@@ -7223,6 +8411,9 @@ ACTIONS:
             required: ['action'],
         },
     },
+    // ---------------------------------------------------------------------------
+    // STITCHCRAFT PROCEDURAL EMBROIDERY & THREAD
+    // ---------------------------------------------------------------------------
 ];
 /**
  * Get a tool definition by name