@pinepaper.studio/mcp-server 1.6.18 → 1.6.20

package/dist/tools/definitions.js

@@ -10,9 +10,9 @@
 import { COMPACT_DESCRIPTIONS } from './compact-descriptions.js';
 import { MINIMAL_DESCRIPTIONS } from './minimal-descriptions.js';
 import { STICK_GAITS, STICK_POSES, STICK_SEQUENCES, STICK_EXPRESSIONS, STICK_PROPS } from './stick-vocabulary.js';
-import { GeneratorNameSchema, ItemTypeSchema } from '../types/schemas.js';
-import { DESIGN_MEDIA, DESIGN_MEDIA_APPLY } from './engine-lists.js';
-import { EffectTypeSchema, SimpleAnimationTypeSchema, EasingSchema, KEYFRAME_EASINGS, EASING_DESCRIPTIONS, KEYFRAME_EASING_JSON_SCHEMA, GEOMETRY_OPERATIONS, THREAD_STITCHES, } from '../types/schemas.js';
+import { AgentBatchOperationTypeSchema, GeneratorNameSchema, ItemTypeSchema } from '../types/schemas.js';
+import { DESIGN_MEDIA, DESIGN_MEDIA_APPLY, FILTER_TYPES, FILTER_DOCS, LINEAGE_KINDS, STYLED_SCENE_STYLES, STYLED_SCENE_STYLE_INFO } from './engine-lists.js';
+import { EffectTypeSchema, AgentExportFormatSchema, RelationTypeSchema, SimpleAnimationTypeSchema, EasingSchema, KEYFRAME_EASINGS, EASING_DESCRIPTIONS, KEYFRAME_EASING_JSON_SCHEMA, 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
@@ -27,9 +27,44 @@ const SIMPLE_ANIMATION_TYPES_LIST = SimpleAnimationTypeSchema.options.join(', ')
 // (round 8 DD, 1.68) — derived now, so it cannot say what the schema refuses.
 const KEYFRAME_EASINGS_LIST = EasingSchema.options.join(', ');
 const EASING_LINES = KEYFRAME_EASINGS.map((e) => `- ${e}: ${EASING_DESCRIPTIONS[e]}`).join('\n');
-// =============================================================================
-// AI AGENT GUIDE (exported for pinepaper_tool_guide)
-// =============================================================================
+const DOORS = [
+    { when: 'A scene or landscape drawn in an art style (cut paper, ink, watercolour, dither, flow, ASCII)', doors: [{ tool: 'pinepaper_styled_scene', text: 'pinepaper_styled_scene' }] },
+    { when: 'Make THIS — an item, a character, the whole scene — look like a style (8-bit, blueprint, ink sketch, flat modern, print halftone, paper cutout…)', doors: [{ tool: 'pinepaper_look', text: 'pinepaper_look (describe first: the engine grades each look native / faithful / impression)' }] },
+    { when: 'A story, several beats, a narrative from prose — a video or film in N parts, or a click-through widget', doors: [{ tool: 'pinepaper_story', text: "pinepaper_story (from_text; nav: 'scenes' for a VIDEO — a scene chain that cuts — 'panels' for a widget)" }, { tool: 'pinepaper_scene_playback', text: 'scene chains (pinepaper_scene_playback: cutSound, play)' }] },
+    { when: 'An ORIGINAL character from a description (a hero with a cape, a round robot, a cat in glasses), or a cast of variants', doors: [{ tool: 'pinepaper_original_character', text: 'pinepaper_original_character (describe first, then create)' }] },
+    { when: 'A character that acts (expressions, poses, walks)', doors: [{ tool: 'pinepaper_character', text: 'pinepaper_character' }, { tool: 'pinepaper_stick', text: 'pinepaper_stick' }, { tool: 'pinepaper_rigging', text: 'pinepaper_rigging' }, { tool: 'pinepaper_deform', text: 'squash and stretch via pinepaper_deform' }] },
+    { when: 'A number that counts up (a KPI roll-up, a year counter, a timer)', doors: [{ tool: 'pinepaper_create_item', text: 'create_item text with counter: exact on every frame, steady width; year counters: counter {from: -30000, to: 2026, era: true}' }] },
+    { when: 'Any item that moves with intent (pops in, hops, bounces, rolls, flies, peeks, lands)', doors: [{ tool: 'pinepaper_choreograph', text: 'pinepaper_choreograph: beats, not hand-timed keyframes' }] },
+    { when: 'One element that becomes the next thing, and the next, with no cuts (a pill → a field → a dot → a card)', doors: [{ tool: 'pinepaper_morph_sequence', text: 'pinepaper_morph_sequence' }] },
+    { when: 'A title or caption with craft', doors: [{ tool: 'pinepaper_text_style', text: 'pinepaper_text_style (display styles; cursive with animate writes itself on)' }, { tool: 'pinepaper_text_effect', text: 'pinepaper_text_effect' }] },
+    { when: 'A poster or layout in an aesthetic, or a collage', doors: [{ tool: 'pinepaper_design_system', text: 'pinepaper_design_system (compose)' }, { tool: 'pinepaper_compose', text: 'a collage: pinepaper_compose' }] },
+    { when: 'A painted, stitched, hatched, inked or cut-paper look on shapes or photos', doors: [{ tool: 'pinepaper_design_medium', text: 'pinepaper_design_medium' }, { tool: 'pinepaper_image_filter', text: 'photos also pinepaper_image_filter (watercolor, painterly)' }] },
+    { when: 'A brand', doors: [{ tool: 'pinepaper_brand_kit', text: 'pinepaper_brand_kit set (first): every item made afterwards inherits it' }] },
+    { when: 'Sound and music', doors: [{ tool: 'pinepaper_sound', text: 'pinepaper_sound' }, { tool: 'pinepaper_audio_beats', text: 'pinepaper_audio_beats' }, { tool: 'pinepaper_beat_cuts', text: 'pinepaper_beat_cuts' }] },
+    { when: 'Particles that must survive save, export and the cloud (confetti bursts, a trail), or custom per-frame drawing', doors: [{ tool: 'pinepaper_emitter', text: 'pinepaper_emitter' }, { tool: 'pinepaper_render_hook', text: 'custom drawing: pinepaper_render_hook' }] },
+    { when: 'A camera move through the piece, or 3D', doors: [{ tool: 'pinepaper_camera_director', text: 'pinepaper_camera_director' }, { tool: 'pinepaper_world3d', text: '3D: pinepaper_world3d' }, { tool: 'pinepaper_relight', text: 'pinepaper_relight' }] },
+];
+/**
+ * The door block for a host's tool list (D72; cloud request from a3). A host
+ * that offers only some tools passes their names: a row keeps only the doors
+ * that host has, and a row with none is dropped — so the model is never told
+ * to "use pinepaper_X" for a tool it cannot see. With no list, every door.
+ */
+export function buildDoorBlock(available) {
+    const has = available ? new Set(available) : null;
+    const rows = DOORS.map((d) => {
+        const doors = d.doors.filter((x) => !has || !x.tool || has.has(x.tool));
+        return doors.length ? `- ${d.when} → ${doors.map((x) => x.text).join('; ')}` : null;
+    }).filter(Boolean);
+    return [
+        'CHOOSE THE HIGHEST-LEVEL TOOL FIRST. Primitive shapes over a generator backdrop with a pulse is the stock result users reject; reach for it only when nothing below fits the brief.',
+        ...rows,
+        'pinepaper_agent_batch_execute then does the glue in ONE call: extra items, keyframes, relations, masks, effects, playback.',
+        'If no tool reaches what the brief asks (for example, redrawing a subject in another art style), tell the user what is missing instead of handing over a lesser result as done.',
+    ].join('\n');
+}
+/** The full door block (every tool), for the guide and a local server. */
+export const CHOOSE_THE_DOOR = buildDoorBlock();
 export const AI_AGENT_GUIDE = `⚠️ You are connected to PinePaper Studio via MCP tools. ALWAYS use these tools to create visual content.
 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.
@@ -43,11 +78,14 @@ The generated code is shown in tool responses and can be copied into PinePaper's
 
 ⚠️ 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.
 
+${CHOOSE_THE_DOOR}
+
 WORKFLOW — Create → Validate → Iterate:
 
 1. pinepaper_agent_start_job (clearCanvas: true, canvasPreset)
-2. pinepaper_agent_batch_execute — ONE call with ALL operations:
-     set_canvas_size → set_background / execute_generator → create items → animate / keyframe_animate → relation → apply_mask → apply_effect → play_timeline
+2. The craft tool(s) above that fit the brief, each called once.
+   Then pinepaper_agent_batch_execute — ONE call for the glue:
+     set_canvas_size → set_background → create items → keyframe_animate / animate → relation → apply_mask → apply_effect → play_timeline
 3. pinepaper_agent_end_job — returns screenshot
 4. Show screenshot to user for validation
 5. If user wants changes → modify specific items or start a new job
@@ -59,13 +97,13 @@ If you restart the pipeline or re-call batch_execute, you DOUBLE every item on t
 To fix mistakes: use modify/delete operations, or start a NEW job with clearCanvas: true.
 
 RULES:
-- NEVER restart the pipeline — one start_job, one batch_execute, one end_job
-- ALL operations go in batch_execute — canvas, background, items, animation, masks, effects, playback
+- NEVER restart the pipeline — one start_job, one batch_execute, one end_job; the craft tools go between them
+- Primitive operations go in the ONE batch_execute — canvas, background, items, animation, masks, effects, playback
 - EXCEPTION: Diagrams (flowcharts, UML) use pinepaper_create_diagram_shape + pinepaper_connect, NOT batch_execute
-- Use generators for rich backgrounds — the built-in templates are limited, generators create much better visuals
+- A generator is a BACKDROP: under a composed scene it adds texture; on its own it is the stock look. Prefer a styled scene, a drawn world or a real photo for the ground of a piece
 - Use "$0", "$1" to reference items by creation order within the batch
 
-─── BATCH OPERATIONS (12 types, in order) ───
+─── BATCH OPERATIONS (${AgentBatchOperationTypeSchema.options.length} types, in order) ───
 
 CANVAS:  set_canvas_size (width/height or preset) → set_background (color) → execute_generator (procedural art)
 ITEMS:   create (itemType, position, properties) → modify (itemId, properties) → delete (itemId) → group (itemIds → one entity)
@@ -73,9 +111,9 @@ ANIMATE: animate (loop presets) → keyframe_animate (timed reveals) → relatio
 EFFECTS: apply_mask (reveal animations) → apply_effect (sparkle/blast/bubbles/fireflies/trail...)
 PLAY:    play_timeline (start playback)
 
-─── GENERATORS (prefer these for backgrounds) ───
+─── GENERATORS (procedural backdrops — under a scene, not as one) ───
 
-Generators fill the canvas with procedural art — much richer than solid colors.
+Generators fill the canvas with procedural art: richer than a flat colour as a backdrop, but not a composition by themselves.
 Choose based on mood:
   Dreamy/soft:  drawBokeh, drawGradientMesh, drawOrganicFlow
   Techy/modern: drawCircuit, drawGrid, drawWindField
@@ -111,7 +149,7 @@ Text: text (content, fontSize, fontFamily, color, fontWeight)
 All items: opacity, shadowColor, shadowBlur, blendMode, strokeColor, strokeWidth
 
 SVG imports for recognizable objects (planes, cars, animals, buildings):
-  pinepaper_search_assets → pinepaper_import_asset (850k+ SVG icons)
+  pinepaper_search_assets → pinepaper_import_asset (open SVG icon repositories)
   An imported SVG is ONE opaque item. To move/recolor its parts (a wheel, a window), pinepaper_group action:"break_apart" splits it into individually movable, re-grouped sub-parts.
 
 Photos / raster images (on-device, no upload):
@@ -197,7 +235,7 @@ Measurement: pinepaper_measurement — rulers, grid, snap-to-grid, get item dime
 
 ─── CANVAS & EXPORT ───
 
-Presets: instagram (1080x1080), youtube (1920x1080), tiktok (1080x1920), twitter (1200x675)
+Canvas presets (pinepaper_set_canvas_size preset): instagram-post (1080x1080), instagram-story (1080x1920), tiktok (1080x1920), youtube-thumbnail (1280x720), full-hd-1080p (1920x1080), twitter-post (1200x675). Platform names (instagram, youtube) are agent_export's, not canvas presets.
 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)`;
 /*
@@ -255,13 +293,11 @@ USE WHEN:
 - Custom canvas size requirements
 - Design elements extend beyond current canvas bounds
 
-COMMON PRESETS:
-- instagram-square: 1080x1080
-- instagram-story: 1080x1920
-- youtube-thumbnail: 1280x720
-- twitter-post: 1200x675
-- hd-landscape: 1920x1080
-- hd-portrait: 1080x1920
+COMMON PRESETS (studio keys; an unknown key is refused with the full list):
+- instagram-post: 1080x1080 · instagram-portrait · instagram-story: 1080x1920
+- youtube-thumbnail: 1280x720 · youtube-short · tiktok: 1080x1920
+- twitter-post: 1200x675 · facebook-post · linkedin-post · pinterest-pin
+- full-hd-1080p: 1920x1080 · hd-720p: 1280x720 · a4-portrait / a4-landscape and other print sizes
 
 Max canvas size: 16384 per side (a 12000 px DOOH or projection canvas fits); above 8192 Safari / iOS may not render it, Chrome and Firefox do. For wedding invitations, event cards, or detailed designs, use at least 1080x1080 or larger.`,
         inputSchema: {
@@ -271,10 +307,10 @@ Max canvas size: 16384 per side (a 12000 px DOOH or projection canvas fits); abo
                 height: { type: 'number', description: 'Canvas height in pixels (100-16384)' },
                 preset: {
                     type: 'string',
-                    description: 'Optional preset name',
+                    description: "A studio preset key instead of width/height, e.g. 'instagram-post', 'instagram-story', 'youtube-thumbnail', 'tiktok', 'full-hd-1080p'. An unknown key is refused with the known ones.",
                 },
             },
-            required: ['width', 'height'],
+            // width + height, or preset alone (enforced by the Zod schema).
         },
     },
     {
@@ -558,6 +594,9 @@ For glossy 3D spheres, use pinepaper_create_glossy_sphere instead. For diagonal
         inputSchema: {
             type: 'object',
             properties: {
+                screenSpace: { type: 'boolean', description: 'HUD: true keeps the item fixed in the FRAME under camera moves; its x/y, keyframes and relations are then frame coordinates. Exports (mp4, webm, gif, png, pdf) honour it; the live preview still tilts it; SVG and Lottie ignore it (agent_export warns). A studio without it refuses.' },
+                counter: { description: "TEXT only: a number that counts on the scene clock, exact on every exported frame. {from, to, start? (s), duration? (s, 1), easing? (engine name or [x1,y1,x2,y2]), decimals?, prefix?, suffix?, locale?, grouping?, padStart?, steps?, tabular? (true: steady width)}; null removes it. A year counter: {from: -30000, to: 2026, era: true} reads '30,000 BCE' … '2026 CE' (eraNegative / eraPositive relabel; no year 0); a KPI: {from: 1.67, to: 5.58, suffix: '%'}. A studio without counters refuses.", oneOf: [{ type: 'object', additionalProperties: true }, { type: 'null' }] },
+                stepTiming: { description: "Animate 'on twos': N or {every: N, baseFps?} (every N frames of a 30 fps base unless baseFps), {fps}, or null to turn off. A stepped group steps its children; follows, spring_follow, auras, rigging and GPU generators are not stepped. A studio without it refuses.", oneOf: [{ type: 'integer', minimum: 1 }, { type: 'object', properties: { every: { type: 'integer', minimum: 1 }, baseFps: { type: 'number' }, fps: { type: 'number' } } }, { type: 'null' }] },
                 itemType: {
                     type: 'string',
                     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'],
@@ -716,6 +755,9 @@ Use the collage group's id for palette/collageStyle; use a child letter's id for
         inputSchema: {
             type: 'object',
             properties: {
+                screenSpace: { type: 'boolean', description: 'HUD: true keeps the item fixed in the FRAME under camera moves; its x/y, keyframes and relations are then frame coordinates. Exports (mp4, webm, gif, png, pdf) honour it; the live preview still tilts it; SVG and Lottie ignore it (agent_export warns). A studio without it refuses.' },
+                counter: { description: "TEXT only: a number that counts on the scene clock, exact on every exported frame. {from, to, start? (s), duration? (s, 1), easing? (engine name or [x1,y1,x2,y2]), decimals?, prefix?, suffix?, locale?, grouping?, padStart?, steps?, tabular? (true: steady width)}; null removes it. A year counter: {from: -30000, to: 2026, era: true} reads '30,000 BCE' … '2026 CE' (eraNegative / eraPositive relabel; no year 0); a KPI: {from: 1.67, to: 5.58, suffix: '%'}. A studio without counters refuses.", oneOf: [{ type: 'object', additionalProperties: true }, { type: 'null' }] },
+                stepTiming: { description: "Animate 'on twos': N or {every: N, baseFps?} (every N frames of a 30 fps base unless baseFps), {fps}, or null to turn off. A stepped group steps its children; follows, spring_follow, auras, rigging and GPU generators are not stepped. A studio without it refuses.", oneOf: [{ type: 'integer', minimum: 1 }, { type: 'object', properties: { every: { type: 'integer', minimum: 1 }, baseFps: { type: 'number' }, fps: { type: 'number' } } }, { type: 'null' }] },
                 itemId: {
                     type: 'string',
                     description: 'Registry ID of the item (e.g., "item_1")',
@@ -1075,7 +1117,7 @@ EXAMPLE (sequenceDiagram):
   "mermaidText": "sequenceDiagram\\n  Alice->>Bob: Hello\\n  Bob-->>Alice: Hi back\\n  Note right of Bob: Thinking..."
 }
 
-Returns { success, nodeCount, edgeCount, nodes, edges, errors }. The created shapes participate in the relation/animation systems just like natively created items — you can grab their ids from \`nodes\` and feed them into pinepaper_add_relation, pinepaper_animate, etc.
+Returns { success, nodeCount, edgeCount, nodeItemIds, nodeIdMap?, edgeIds?, nodes, edges, errors }. nodeItemIds are the CANVAS ids of the shapes (item_N): pass THOSE to pinepaper_auto_layout, pinepaper_animate, pinepaper_add_relation. The mermaid ids (A, B…) in edges[].from/to name nodes in the source text and resolve to nothing on the canvas; nodeIdMap (where the studio returns it) maps one to the other, and edgeIds are the connectors' canvas ids.
 
 NOTE: Import-only — there is no MCP equivalent of FxTool's exportMermaid. Mermaid lacks animation primitives, so a round-trip would silently drop animations.`,
         inputSchema: {
@@ -1106,7 +1148,7 @@ NOTE: Import-only — there is no MCP equivalent of FxTool's exportMermaid. Merm
             idempotentHint: false,
             openWorldHint: true,
         },
-        description: `Import a raster image from a URL onto the canvas. Returns an itemId for the imported image.
+        description: `Import a raster image onto the canvas from an http(s) URL, a data: URL, or a LOCAL FILE PATH (the server reads the file). Returns an itemId for the imported image.
 
 USE WHEN:
 - User wants to add a photo, PNG, JPG, or other raster image
@@ -1128,6 +1170,9 @@ Apply a mask shape during import to clip the image:
 
 SIZE CONSTRAINTS:
 Use maxWidth/maxHeight to constrain the image dimensions while preserving aspect ratio.
+- maxEdge: the longest edge the studio STORES the image at (px), or 'native' to keep every pixel. The result says when it was stored smaller.
+- nativeSize: true places the image at its source footprint even if it was stored smaller.
+- smoothing: 'off' (nearest-neighbour, for pixel art) | 'low' (default) | 'medium' | 'high'.
 
 EXAMPLES:
 - Import photo: url: "https://example.com/photo.jpg"
@@ -1184,7 +1229,7 @@ EXAMPLES:
             idempotentHint: true,
             openWorldHint: true,
         },
-        description: `Search for free SVG assets from open repositories (SVGRepo, OpenClipart, Iconify, FontAwesome).
+        description: `Search for free SVG assets from open repositories (Iconify, Font Awesome). The result's sources says how each repository answered (ok | timeout | error); one that is down does not hold up the others, and a search that names one repository fails if it is down.
 
 USE WHEN:
 - User wants icons, illustrations, or clipart
@@ -1194,15 +1239,13 @@ USE WHEN:
 - Need graphics that are too complex to draw with paths
 
 REPOSITORIES:
-- SVGRepo: 500,000+ icons, various categories and licenses
-- OpenClipart: 150,000+ public domain clipart
 - Iconify: 200,000+ icon sets (various licenses)
 - Font Awesome: 2,000+ free icons (CC BY 4.0)
 
 WORKFLOW:
 1. Search for assets: pinepaper_search_assets(query: "rocket")
 2. Review results (you'll see assetIds, previews, licenses)
-3. Import chosen asset: pinepaper_import_asset(assetId: "svgrepo_rocket_12345")
+3. Import chosen asset: pinepaper_import_asset(assetId: "iconify_mdi_rocket")
 
 IMPORTANT NOTES:
 - Always respect license terms (check license field in results)
@@ -1239,7 +1282,7 @@ SVG CONTENT RETRIEVAL:
                 },
                 repository: {
                     type: 'string',
-                    enum: ['all', 'svgrepo', 'openclipart', 'iconify', 'fontawesome'],
+                    enum: ['all', 'iconify', 'fontawesome'],
                     description: 'Which repository to search (default: all)',
                 },
                 limit: {
@@ -1273,12 +1316,12 @@ USE WHEN:
 WORKFLOW:
 1. Search: pinepaper_search_assets(query: "rocket")
 2. Choose: Review results, pick one with desired license
-3. Import: pinepaper_import_asset(assetId: "svgrepo_rocket_12345", position: {x: 400, y: 300})
+3. Import: pinepaper_import_asset(assetId: "iconify_mdi_rocket", position: {x: 400, y: 300})
 4. Modify: Use pinepaper_modify_item to adjust size, color, etc.
 5. Animate: Use pinepaper_animate or pinepaper_add_relation for motion
 
 PARAMETERS:
-- assetId: From search results (e.g., "svgrepo_12345")
+- assetId: From search results (e.g., "iconify_mdi_rocket")
 - url: Alternative to assetId - direct URL to SVG
 - position: Where to place on canvas (default: center)
 - scale: Size multiplier (default: 1.0)
@@ -1297,9 +1340,9 @@ CACHING:
 - No disk storage (memory only)
 
 EXAMPLES:
-- Import from search: {assetId: "svgrepo_rocket_001", position: {x: 400, y: 300}, scale: 2.0}
+- Import from search: {assetId: "iconify_mdi_rocket", position: {x: 400, y: 300}, scale: 2.0}
 - Import from URL: {url: "https://example.com/icon.svg", position: {x: 500, y: 400}}
-- Import with color override: {assetId: "svgrepo_heart_123", position: {x: 400, y: 300}, color: "#ef4444"}
+- Import with color override: {assetId: "iconify_mdi_heart", position: {x: 400, y: 300}, color: "#ef4444"}
 
 RETURNS:
 - itemId: ID of the imported SVG group (use for further modifications)
@@ -1309,7 +1352,7 @@ RETURNS:
             properties: {
                 assetId: {
                     type: 'string',
-                    description: 'Asset ID from search results (e.g., "svgrepo_12345")',
+                    description: 'Asset ID from search results (e.g., "iconify_mdi_rocket")',
                 },
                 url: {
                     type: 'string',
@@ -1636,6 +1679,7 @@ RETURNS: create → { success, action, eventId }; pulse → { success, action, e
         inputSchema: {
             type: 'object',
             properties: {
+                at: { description: 'create: fire this event at these scene times (seconds) — a timed trigger that runs on the timeline and in video exports. The widget player does not run timed triggers.', oneOf: [{ type: 'number' }, { type: 'array', items: { type: 'number' } }] },
                 action: { type: 'string', enum: ['create', 'pulse'], description: "'create' a pp:event · 'pulse' it to fire" },
                 name: { type: 'string', description: "Event name — required for action 'create'" },
                 payloadType: { type: 'string', description: "Payload type label (default 'Pulse') — action 'create'" },
@@ -2117,7 +2161,7 @@ MODES:
 
 This complements pinepaper_validate_design (which validates a definition object, not the live scene).
 
-EXAMPLE (pre-flight): { ops: [ { kind: "create", id: "c1", itemType: "circle" }, { kind: "addRelation", source: "c1", target: "missing", relationType: "orbits" } ] }`,
+EXAMPLE (pre-flight): { ops: [ { kind: "create", id: "c1", itemType: "circle" }, { kind: "addRelation", from: "c1", to: "missing", relation: "orbits" } ] } (source / target / relationType are accepted as the same fields)`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -2216,7 +2260,7 @@ ACTIONS:
 - set_clip: { id, inPoint, outPoint (media-time s, outPoint > inPoint), timeOffset? (canvas s: also MOVE the clip to start there) } → re-trim an ALREADY-uploaded clip (video or audio). A studio that cannot move clips refuses timeOffset rather than ignoring it.
 - split: { id, at (canvas s) } → cut a clip in two: { leftId, rightId, leftMediaId, rightMediaId, at }. The first half keeps its id. Refused (not claimed) where the studio cannot split or the time is outside the clip.
 - add_transition: { fromItemId (ends at the cut), toItemId (starts at it), transition?: { type: 'crossfade'|'dip', seconds, color } } → the same in preview and export. Split a clip, then transition between its halves, or join two clips that meet.
-- For an IMAGE on the timeline, use pinepaper_import_image with bornAt / ttl (seconds on screen).
+- For an IMAGE on the timeline, import it with pinepaper_import_image, then give it bornAt / ttl (seconds on screen) with pinepaper_modify_item.
 
 NOTES:
 - The server fetches the URL (or reads a local path / data: URL) and hands the page the bytes, so it does not need to be CORS-permitted.
@@ -2293,6 +2337,10 @@ ACTIONS:
 - apply_style: { itemId, styleKey, palette?, variant?, content?, fontFamily?, fontSize? } — render a text item as a layered display title (offset copies, outlines, fills). The result GROUP ADOPTS the text's registry id, so existing relations/keyframes/handles keep pointing at it. fontFamily: 'suggested' opts into the face the style was designed around (arcade wants a pixel face — a layer stack can outline any typeface but cannot pixellate one); never automatic.
 - set_font_axes: { itemId, axes: { weight?, width?, slant? } } — STANDARD variable-font axes only (Canvas 2D has no font-variation-settings, so custom foundry axes are unreachable — platform limit, stated, not silent). Returns {applied, rejected}: CHECK rejected — an axis silently ignored is the failure this surface exists to prevent. All three are ordinary animatable properties: keyframe fontWeight and type breathes between weights.
 - list_styles: {} — styles + palettes + axes, for pickers. Call this first; styleKey strings come from here.
+- list: {} — the same as list_styles.
+- cursive: { text, cursiveOptions?: { x?, y?, scale? (1), strokeColor? ('#ffffff'), strokeWidth? (2), nib? ('monoline' | 'broad' | {angle?, width?, contrast?, taper?}), animate? (false), duration? (2), easing? ('easeOut'), timeOffset? (0), singleStroke?, showGhost?, tension? } } → { itemId, strokes, width } — writes the words as STROKED handwriting, a path rather than a glyph. animate: true writes it on by itself over duration seconds (from timeOffset), no keyframes needed; otherwise pinepaper_animate's draw-on applies to it. Unknown cursiveOptions keys are refused.
+- wrap: { itemId, maxWidth } — breaks a text item into lines no wider than maxWidth (canvas units). unwrap: { itemId } — restores the single line; wrap is not destructive.
+- to_collage: { itemId, text?, collageOptions? } — rebuilds a text item as a letter collage (same vocabulary as pinepaper_create_letter_collage); text defaults to the item's content.
 
 OVER PHOTOGRAPHS, PASS A PALETTE — NEVER THE DEFAULT. Measured on a real
 render of captions over photographs: highlighter, sticker, caption and badge
@@ -2314,7 +2362,7 @@ EXAMPLE: { action: 'apply_style', itemId: 'title_1', styleKey: 'arcade', fontFam
                 action: { type: 'string', enum: ['apply_style', 'set_font_axes', 'list_styles', 'list', 'cursive', 'wrap', 'unwrap', 'to_collage'], description: "Text style operation. 'list' is accepted as an alias for 'list_styles', because pinepaper_text_effect spells the same action 'list' and an agent moving between them guesses wrong. '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? }.' },
+                cursiveOptions: { type: 'object', description: "cursive: { x?, y?, scale?, strokeColor?, strokeWidth?, nib?, animate?, duration?, easing?, timeOffset?, singleStroke?, showGhost?, tension? }. animate: true writes the line on over duration seconds. nib: 'monoline' for one even line, 'broad' (or {angle, width, contrast, taper}) for thick/thin; omitted, the studio's default pen." },
                 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.' },
@@ -2352,7 +2400,7 @@ READ THIS BEFORE PROMISING A MEDIUM. Naming a medium does not create its marks.
 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:
-- apply: { itemId, medium, options? } — render an item in ANY medium the engine can make: ${Object.keys(DESIGN_MEDIA_APPLY).join(', ')}. One engine entry point; a medium it cannot make (encaustic, absent here) or that is a brush rather than a fill (charcoal, ink) is refused with the reason: pass it on. watercolor options: color, brush, water 0..1, opacity, edge 0..1 (the dark rim), angle, bleed, seed. oil (stylised): color, brush, length, density, toneRange, relief, angle, seed. cutPaper (vector: survives SVG/PDF/video): color, facet, jitter, shadow, shadowColor, shadowOpacity, shadowOffset [dx, dy], seed. The result replaces the source in the stacking order and hides it; applying again replaces; one undo step.
+- apply: { itemId, medium, options? } — on a PHOTO (an image item), watercolor and oil run as the watercolor / painterly image filters and report fidelity 'stylised' (an image filter, not paint simulated over geometry); other media are refused for photos, with the reason. On shapes — render an item in ANY medium the engine can make: ${Object.keys(DESIGN_MEDIA_APPLY).join(', ')}. One engine entry point; a medium this studio cannot apply is refused with the reason: pass it on. ink / charcoal (where the studio applies them) restyle a path, text, or group of them IN PLACE — same itemId, keyframes and relations kept — with a boiling hand-drawn line; raster and video exports boil, SVG/Lottie get the colour and width only. Their options: color, amplitude (px), wavelength (px), fps (boil rate, 12), seed, boil (default true), width (px, paths), keepColor. watercolor options: color, brush, water 0..1, opacity, edge 0..1 (the dark rim), angle, bleed, seed. oil (stylised): color, brush, length, density, toneRange, relief, angle, seed. cutPaper (vector: survives SVG/PDF/video): color, facet, jitter, shadow, shadowColor, shadowOpacity, shadowOffset [dx, dy], seed. The result replaces the source in the stacking order and hides it; applying again replaces; one undo step.
 - 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 thread stitches with their params.
@@ -2360,6 +2408,7 @@ ACTIONS:
 - 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.
+- sdf_stroke: { points, width? (8), softness? (0.2), color?, opacity?, resolution? (2), name? } → itemId — a smooth, anti-aliased brush stroke along points ({x, y, pressure?} or [x, y, pressure?], canvas px; pressure 0..1 thins the line there), made as an image item (registered, one undo step). Runs on the CPU; a stroke too large for its bitmap budget is refused with the fix. A studio without the SDF brush refuses with the reason.
 
 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.
 
@@ -2385,9 +2434,14 @@ EXAMPLE — a stitched leaf:
         inputSchema: {
             type: 'object',
             properties: {
-                action: { type: 'string', enum: ['list_media', 'resolve', 'list_stitches', 'apply_thread', 'apply_hatch', 'list_flow_fields', 'list_hatch_options', 'apply'], description: 'Medium operation' },
+                action: { type: 'string', enum: ['list_media', 'resolve', 'list_stitches', 'apply_thread', 'apply_hatch', 'list_flow_fields', 'list_hatch_options', 'apply', 'sdf_stroke'], description: 'Medium operation' },
                 medium: { type: 'string', enum: [...DESIGN_MEDIA], description: `resolve / apply: the medium. apply works for ${Object.keys(DESIGN_MEDIA_APPLY).join(', ')}; the rest are refused by the engine with the reason. Call list_media for each one's fidelity and limitation.` },
                 options: { type: 'object', description: 'apply: the medium\'s own options (see the description; color takes hex).' },
+                points: { type: 'array', items: {}, description: 'sdf_stroke: [{x, y, pressure?}] or [[x, y, pressure?]] in canvas px' },
+                softness: { type: 'number', description: 'sdf_stroke: edge softness 0..1 (default 0.2)' },
+                opacity: { type: 'number', description: 'sdf_stroke: 0..1 (default 1)' },
+                resolution: { type: 'number', description: 'sdf_stroke: bitmap px per canvas px (default 2)' },
+                name: { type: 'string', description: 'sdf_stroke: item name' },
                 itemId: { type: 'string', description: 'apply / apply_thread / apply_hatch: a closed path, compound path (holes kept), or a group of them (applied per path).' },
                 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. spine is a list of points, each {x, y} or [x, y], e.g. [{x:400,y:200},{x:400,y:520}]; this tool normalises [x, y] to {x, y} before the engine sees it." },
@@ -2429,12 +2483,12 @@ EXAMPLE — a stitched leaf:
             idempotentHint: false,
             openWorldHint: false,
         },
-        description: `Animate text CHARACTER BY CHARACTER — 37 effects (terminaltexteffects' vocabulary, reimplemented from source).
+        description: `Animate text CHARACTER BY CHARACTER — the 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.
+- list: {} — every effect 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.
@@ -2583,9 +2637,10 @@ RECIPE — assemble-from-pieces: shatter with keepSource, keyframe each tile fro
 
 Input is the output of a single-image layer decomposer (See-through — one flat anime drawing in, ~20 occlusion-inpainted layers out — or any PSD-style layer dump with the same manifest shape). The decomposition model does NOT run here: it needs a GPU and minutes per image; run it where it fits and import the folder.
 
-Layer tags map onto the exact role tokens the expresses presets read (eye_left, pupil_right, mouth…), so blink / smile / talk work on the imported character immediately — through an 'expresses' RELATION (pinepaper_add_relation relationType expresses), which is the only thing that drives them. pinepaper_animate applies ambient motion (bounce, pulse, wobble) and cannot blink: asking it to is a silent no-op.
+Layer tags resolve to the role tokens the expresses presets read: decomposer tags (eyel / eyer, iridesl / iridesr, eyebrowl / eyebrowr, hairf, mouth, face…) and the role tokens themselves (eye_left, pupil_right…) both work, in any case and with _ or - separators, so blink / smile / talk work on the imported character immediately — through an 'expresses' RELATION (pinepaper_add_relation relationType expresses), which is the only thing that drives them. pinepaper_animate applies ambient motion (bounce, pulse, wobble) and cannot blink: asking it to is a silent no-op.
 
-Params: { info — the decomposer manifest, whose parts live under info.parts (or info.tag2pinfo) as an OBJECT KEYED BY TAG, not a layers[] array: { eye_left: { xyxy: [x0,y0,x1,y1], depth_median: <draw order> }, … } plus frame_size [h,w]. An array here imports nothing and reports no parts. images ({tag: PNG data URL or CORS-reachable https URL} — data URLs are the reliable path; ~20 layers of base64 is a big call, use URLs when you can), position?, scale?, name? }
+Params: { info — the decomposer manifest, whose parts live under info.parts (or info.tag2pinfo) as an OBJECT KEYED BY TAG, not a layers[] array: { eyel: { xyxy: [x0,y0,x1,y1], depth_median: <draw order> }, … } plus frame_size [h,w]. An array here imports nothing and reports no parts. images ({tag: PNG data URL or CORS-reachable https URL} — data URLs are the reliable path; ~20 layers of base64 is a big call, use URLs when you can), position?, scale?, name? }
+A supplied image that does not land (no manifest entry, no usable xyxy) FAILS the call by name, with skipped: [...] and the groupId of what did land; layers that imported without a role are listed in unroled.
 Returns: { groupId, parts, roles, rolesWired, warnings }
 
 CHECK rolesWired: a character importing with 0 roles renders perfectly and silently refuses to animate — that number is the difference between a picture and a puppet.`,
@@ -2671,7 +2726,7 @@ A partial composition reports as a failure with the elements that did not create
                 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).' },
+                width: { type: 'number', description: 'compose: canvas width. compose SETS the canvas to the size it laid out for. Most styles honour width/height; a few lay out at their own fixed size, and the result warns when the requested size was not used. canvasResized says when the canvas changed.' },
                 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.' },
@@ -2695,7 +2750,7 @@ A different construction from pinepaper_character, which places a figure from th
 
 TO MAKE IT ACT, not just stand: gait is how it walks and is never just walking; poses is the body over time, [{at, pose}]; sequence is a named track of those. Pass gait and travel in the SAME call to cross the frame — they share one track and two calls fight over it. A mistyped gait, pose or sequence comes back NAMED in warnings with the valid list, and the figure is still built.
 
-action 'figure' builds the figure. action 'set' builds the floor, the wall and the objects around it, so a figure has somewhere to be.
+action 'figure' builds the figure. action 'set' builds the floor, the wall and the objects around it, so a figure has somewhere to be. set takes kind: 'room' (floor and wall: groundY?, wall?, floor?), 'tabletop' (object, surfaceY), 'chair' (facing), 'table', 'counter', 'door', 'shelf' (items), 'window'; all take at and scale.
 
 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: {
@@ -2703,7 +2758,7 @@ The geometry is vendored from mcp-cloud, which makes this a three-repo artifact:
             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.' },
+                kind: { type: 'string', description: 'figure: which figure. set: room | tabletop | chair | table | counter | door | shelf | window (an unknown one is refused with the current list).' },
                 at: { type: 'object', description: '{ x?, y? } — where it goes.' },
                 scale: { type: 'number', description: 'Size multiplier.' },
                 facing: { type: 'string', enum: ['left', 'right'], description: "set: which way a CHAIR faces. A figure has none and passing it here is refused — a figure faces the way it travels." },
@@ -2761,7 +2816,9 @@ The geometry is vendored from mcp-cloud, which makes this a three-repo artifact:
             idempotentHint: false,
             openWorldHint: false,
         },
-        description: `A piece of prose becomes a scene.
+        description: `FORM — nav: 'scenes' is the VIDEO story: one scene per part on a scene chain that cuts in time (export as MP4); each part's length follows its role (hook 2.5 s, stat 3 s, section 3.5 s, quote 3 s, exit 3 s; 0.4 s transitions), and the reply carries the cut times. nav: 'panels' (the default) is the WIDGET story: tabs a viewer clicks through (export_widget_html). A video brief needs 'scenes'.
+
+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.
@@ -2770,6 +2827,7 @@ The geometry is vendored from mcp-cloud, which makes this a three-repo artifact:
         inputSchema: {
             type: 'object',
             properties: {
+                nav: { type: 'string', enum: ['panels', 'scenes'], description: "'scenes' = the video form (a scene chain that cuts); 'panels' = the widget form (default)" },
                 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.' },
@@ -2792,13 +2850,25 @@ The geometry is vendored from mcp-cloud, which makes this a three-repo artifact:
 
 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.`,
+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.
+
+EXPORTS ARE FILES. Each export is written to a file in the export directory and the result returns { format, filePath, bytes } instead of the data — the bytes are not inlined. An export that produced nothing is refused by name.
+
+EXPORT:
+- export_lottie: { options?: { fps?, duration? (s), includeRelations? } } → a .json Lottie file
+- export_dotlottie: { options?: { fps?, duration? (s), id?, loop?, autoplay? } } → a .lottie file (the zipped Lottie plus manifest)
+- export_glb: { } → a .glb file of the PERSPECTIVE 3D objects (createObject3D). Refused when there are none. It does not export world3d meshes, which are a separate renderer.
+- export_bvh: { skeletonId (required), options?: { fps? } } → a .bvh file of that skeleton's motion. Refused when nothing is rigged.
+- export_png_sequence: { options?: { duration (s), fps, width?, height?, transparent? } } → a .zip of one PNG per frame. PASS duration and fps: the studio does not size the sequence to the scene, and the result's defaultsUsed says when its own default length was used.
+
+IMPORT:
+- import_lottie: { data (the Lottie JSON — an object or a JSON string), options?: { fitToCanvas?, autoPlay?, centerOnCanvas?, scale? } } → { itemId, itemIds, items, duration, bounds }; a failed import fails with the importer's errors. data is parsed as JSON, so a URL or a file path does not work; read the file and pass its contents. There is no .lottie, GLB or BVH import here: a glTF goes into a 3D world with the world3d tool's import_gltf, a BVH onto a rig with the rigging tool's import_bvh / retarget_bvh.`,
         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. export_png_sequence: { duration (seconds), fps, width, height, transparent (keep alpha; default false fills the background) } — PASS duration and fps: the studio does not size the sequence to the scene, and without them it writes its own default length, which does not follow the scene (runs have measured 45 and 90 frames). The result's defaultsUsed says when that happened." },
-                data: { anyOf: [{ type: 'string' }, { type: 'object' }], description: 'import_lottie: the Lottie JSON — object, JSON string, or URL.' },
+                data: { anyOf: [{ type: 'string' }, { type: 'object' }], description: 'import_lottie: the Lottie JSON — object or JSON string (a URL or path is not fetched).' },
                 skeletonId: { type: 'string', description: "export_bvh: which skeleton to write. A BVH is one skeleton's motion." },
             },
             required: ['action'],
@@ -2832,6 +2902,36 @@ THE CATALOGUE IS A STARTING SET, NOT THE LIMIT. Six instruments, five drums and
 - 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.
 
+ARGUMENTS BY ACTION. A sound spec is { note? ('A4') | hz? | chord? + root?, instrument? (a catalogue name), waveform? ('sine' | 'square' | 'sawtooth' | 'triangle'), partials? ([{ h, amp }]), envelope? ({ attack, decay, sustain, release }), gain? (0..1), pan? (-1..1), duration? (seconds) }.
+
+CATALOGUES:
+- list_instruments / list_percussion / list_sfx: {} → the engine's names, built-in and defined.
+
+PLAY — each returns { played }. When the studio returns no voice (it may have no audio output) the call fails and says so; placed sounds and render_soundtrack need no audio output:
+- play_tone: { note ('A4', required), options? } — options is merged into the spec, so { duration, gain, pan, instrument, envelope, waveform } all work, and options.hz overrides the note. A top-level hz is NOT play_tone's: it belongs to define_percussion / define_sfx, and play_tone without note is refused.
+- play_chord: { root ('C4'), chord? ('major' default; 'minor', 'maj7', 'dim' …), options? }
+- play_percussion / play_sfx: { name (from the catalogue), options? }
+- play_spec: { spec, options? } — options is merged into the spec.
+- play_from_text: { text, options? } — options is merged into the resolved spec.
+
+READ WITHOUT PLAYING:
+- chord_frequencies: { root, chord?, options? } → { frequencies } (Hz)
+- from_text: { text ('a soft warm bell on A4') } → { spec } to inspect or edit, then play_spec or create
+- timbre_from_path: { itemId (a path with length), samples? (256) } → { timbre: { partials } }
+
+ON THE CANVAS — a placed sound is a timeline item:
+- create: { spec?, visual?: { width? (220), height? (64), position? ({ x, y }), color?, startTime? (s), duration? (s) } } → { itemId, placement? } — startTime / duration place it in the same call.
+- sequence: { cues: [{ t (s, required), spec? | preset? (an instrument name) + note?, duration?, visual? }] } → { placed, itemIds, cues, failed? } — a whole bed in ONE call; failures come back by index. preset is shorthand for spec: { instrument: preset, note }.
+- set_placement: { itemId, placement: { startTime?, duration? } } (seconds; no other keys are read) → { placed }
+- remove: { itemId } → { removed } · stop_all: {} → { stopped } — stops everything sounding now; placed sounds stay placed.
+
+DEFINE (name is normalised to [a-z][a-z0-9_-]; play the returned canonicalName):
+- define_instrument: { name, partials (required, ≥1), envelope?, gain? (0.8), aliases? } → { canonicalName, requestedName, normalised, listed }
+- define_percussion / define_sfx: { name, partials? or noise? (0..1; one of the two is required), noiseFreq? (Hz), hz? (base Hz), pitch? ({ from (Hz), tau (s, ≤5) }), envelope?, gain?, aliases? }
+
+RENDER:
+- render_soundtrack: { duration? (s, ≤600), sampleRate? (48000), bitDepth? (16 | 32) } → a WAV FILE; the result names filePath, fileSize, placed and any dropped. Refused by name when no sound is placed.
+
 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',
@@ -2876,7 +2976,7 @@ render_soundtrack mixes every placed sound to a WAV and writes it to a file. It
         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.
+- GROUP motions (driftX, driftY, swayX, swayY, 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.
@@ -2957,9 +3057,49 @@ 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?, metalness?, roughness?, emissiveIntensity? } } (y defaults to sitting ON the terrain) / remove_object: { objectId }
+- add_object: { object: { x, z, height?, color? } } (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.
 
+UNITS: positions, sizes, ranges and radii are WORLD units (metres). rotY is RADIANS everywhere on the mesh path (pass mesh.rotYDegrees to write degrees); lathe arc is DEGREES. Colours take hex or [r, g, b] in 0..1. These act on an existing world: call create first.
+
+MESHES — a canvas path becomes real geometry:
+- extrude_path: { pathId, mesh?: { id?, depth? (1), unitsPerPixel? (0.01: canvas px → world units), upright? (stand the drawing up; default flat, a floor plan), placement? ('centered' default: centred on x/z, base at y | 'canvas'), caps?, segments?, flatness?, x?, y?, z?, rotY?, rotYDegrees?, scale?, doubleSided?, color?, metalness?, roughness?, uniforms? } } → { meshId }. The path is unchanged.
+- lathe_path: { pathId, mesh?: same fields, plus arc? (DEGREES, 360 = full solid); segments? = steps round the revolution } → { meshId }
+- list_meshes: {} → { count, meshes } (long vertex arrays summarised to their length)
+- remove_mesh: { meshId }
+- set_mesh_instances: { meshId, instances: [[x, y, z, scale, rotY (RADIANS), variant], …] } — replaces the copies a mesh draws, six numbers each.
+
+LIGHTS — point lights, at most 8 (the ninth is refused by name):
+- add_light: { light: { id?, x? (0), y? (3), z? (0), color? (hex or linear [r, g, b], may exceed 1), intensity? (6), range? (20) } } → { lightId, light }
+- set_light: { lightId, light: any of the add_light fields } — moves or retunes in place.
+- remove_light: { lightId } · list_lights: {} → { lights }
+
+MATERIALS — a NAMED, SHARED surface: one edit restyles every object using it.
+- add_material: { material: { id?, color?, emissive?, emissiveIntensity?, metalness? (0..1), roughness? (0..1), clearcoat?, clearcoatRoughness?, sheenColor?, sheenRoughness? } } → { materialId, material }. metalness / roughness reach pixels on the MESH path only.
+- set_material: { materialId, material: any of the add_material fields } · remove_material: { materialId } · list_materials: {} → { materials }
+
+IMPORT:
+- import_obj: { source (the .obj file TEXT), importOptions?: { id?, x?, y?, z?, rotY? (RADIANS), scale?, doubleSided?, uniforms?, color? ([r, g, b] 0..1; .mtl is never read) } } → { meshIds, warnings }
+- import_gltf: { source (the .gltf JSON TEXT, buffers embedded), importOptions?: { id?, x?, y?, z?, rotY?, scale?, doubleSided?, uniforms?, merge? (default true) } } → { meshIds, warnings }. A URL, a data: URI or a file path is NOT fetched — the string is parsed as glTF JSON. Unsupported features come back named in warnings.
+- list_mesh_clips: { meshId } → { clips } (the animation clips a skinned import carries)
+- set_mesh_clip: { meshId, clip, crossfade? (seconds) }
+
+NAVIGATION, PICKING, CAMERA:
+- set_nav_target: { navTarget: '2d' | '3d' } — which layer the pointer drives · get_nav_target: {} → { navTarget }
+- ground_height: { point: { x, z } (WORLD) } → { height } of the terrain there
+- raycast: { origin: [x, y, z], direction: [x, y, z] (need not be normalised) } → { hit (registry id, point …) | null, missed }
+- line_of_sight: { from: [x, y, z], to: [x, y, z] } → { clear }
+- world_to_canvas: { point: { x, y, z? } (WORLD) } → { point: { x, y } } in canvas px; refused when the point is behind the camera
+- canvas_to_ground: { point: { x, y } (CANVAS px) } → { ground } where that pixel lands on the terrain
+- dolly_camera: { multiplier } (>1 away, <1 closer) → { camera }
+- pan_camera: { dx, dy } (SCREEN px) → { camera }
+
+PHYSICS — narrow by design: spheres and capsules under gravity colliding with terrain, objects, actors and meshes. No stacking, no joints (pinepaper_physics is the 2D world and has those).
+- add_body: { body: { id?, kind? ('sphere' default | 'capsule'), position? ([x, y, z]), velocity? ([x, y, z]), radius? (0.5), height? (1.8, capsule), mass? (1), restitution? (0.3), friction? (0.6), gravityScale? (1), kinematic?, ignoreIds?, ttl? (seconds), data? } } → { bodyId, body }
+- fire_projectile: { body: { id?, position?, direction? ([0, 0, -1]), speed? (40), radius? (0.15), restitution? (0), gravityScale? (0.35), ttl? (6 s), ignoreIds? (e.g. the shooter), data? } } → { id, body } — a SWEPT sphere, so it cannot tunnel through a thin wall.
+- impulse: { bodyId, vector: [x, y, z] } · set_velocity: { bodyId, vector: [x, y, z] }
+- step_physics: { dt (seconds) } → { contacts, removed } · remove_body: { bodyId } · list_bodies: {} → { bodies }
+
 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',
@@ -2990,7 +3130,7 @@ RECIPE — a character walking through a forest: create {spec:'forest'} → impo
                 lightId: { type: 'string', description: 'set_light / remove_light: the light id.' },
                 material: { type: 'object', description: 'add_material / set_material: colours (color, emissive, sheenColor) take hex or [r, g, b] in 0..1. { 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.' },
+                source: { type: 'string', description: 'import_obj: the OBJ file TEXT. import_gltf: the .gltf JSON TEXT, buffers embedded (a URL, data: URI or path is not fetched; .glb is not supported here).' },
                 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).' },
@@ -3031,7 +3171,7 @@ The knowledge of how a figure is built and how it moves lives in the graph; this
              { 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:
+CHANNELS ARE DECLARED BY THE CONCEPT, not by you. Ask pinepaper_query_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.
@@ -3119,7 +3259,7 @@ POSE MOTION — build a performance out of saved poses:
   · 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.
+- bake_animation: { skeletonId, options?: { duration? (2), fps? (30), detach? (true), write? (true) } } → { written, keyframes, detached, wrote } — freeze the whole rig into plain item keyframes for export. Needs items ATTACHED to bones. It DETACHES the items (the bones stop driving them, so the keyframes are what plays); pass options.detach:false to keep the rig driving.
 - add_secondary_motion: spring chains for tails, hair, cloth. skin_path: per-vertex deformation of a curved path.
 
 ACTIONS:
@@ -3134,6 +3274,12 @@ ACTIONS:
 - import_bvh: { bvhText, view? (side|front), fps? (15; 0 = every frame), height? (320px), rootPosition?, name? } → { skeletonId, poses, duration, warnings } — build a NEW rig from a BVH mocap clip (CMU / Mixamo), stick figure included. Root translation returns as a separate track rather than baked into poses.
 - retarget_bvh: { bvhText, skeletonId, fps?, name? } → { skeletonId, matched, unmatchedSource, unmatchedTarget, poses, duration } — drive an EXISTING rig with a BVH clip, bones matched by name. CHECK matched/unmatched in the result: a retarget that matched 2 of 15 bones "succeeds" and looks broken.
 - import_spine: { spineJson, rootPosition?, name? } → { skeletonId, bones, placeholders, animations, warnings } — import a Spine editor JSON export (bones, poses, attachment placeholders).
+- list_skeletons: {} → { skeletons: [{ id, name, boneCount, rootBoneId, hasIK, hasPhysics }], count } — needs no skeletonId; the place to find one on a rig you did not build.
+- stop_pose_sequence: { skeletonId } — stops the playing pose sequence; joints go back to their poses / rest. Refused (a no-op, not a fault) when nothing was playing.
+- apply_pose_transition: { skeletonId, transitionName, poseIdMap? ({ transitionPoseName: savedPoseId }) } — plays a named stock transition (walk, run, flap …; list_pose_libraries returns the names). It plays poses BY NAME, so load_pose_library first; poseIdMap is built from list_poses by name when omitted.
+- stop_root_track: { skeletonId } — stops a move_root locomotion track; the figure stays where it is. Refused (a no-op) when no track was running.
+- list_shape_keys: { skeletonId } → { shapeKeys: [{ id, name }], count }
+- load_shape_key: { skeletonId, shapeKeyId, weight? (0..1, default 1) } — blends the attached items toward a shape key saved with save_shape_key.
 
 BREAKDOWN POSES (S12): a breakdown keyframe shapes the ARC + SPACING between key poses (favor biases spacing; boneOffsets lag bones so a tip drags its root — follow-through; movingHold keeps a hold alive). This is the difference between mechanical and lifelike motion.`,
         inputSchema: {
@@ -3234,7 +3380,7 @@ EXAMPLE doc: { "nodes": [ {"id":"bar","type":"pp:Rectangle","width":300,"height"
                         width: { type: 'number' },
                         height: { type: 'number' },
                     },
-                    description: 'Canvas size used to tile component roots (default 1080×1080).',
+                    description: 'Canvas size to lay out for (default: the live canvas). The result returns registry itemIds, the document ids as docIds, and idMap pairing them.',
                 },
                 defaultGeometry: {
                     type: 'object',
@@ -3342,6 +3488,7 @@ An event channel (pinepaper_event) is the hub: something FIRES it, and reactions
   · 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_play_sound (source = the EVENT, target null; params: sound, gain?, note?) — play a sound when the event fires: a catalogue name (effect, drum or instrument; aliases accepted) or a define_sfx spec; gain is a multiplier capped at full scale; note is for instruments (default C5). An unknown sound is refused with the catalogue. Wire a click sound as on_click_fire (button → event) + on_event_play_sound (event → null). For a sound at a TIME, pinepaper_event create { at: seconds | [seconds] } fires the event on the timeline (and in video exports); a scene chain's cutSound puts one on every cut. LIMITS: the exported widget player does not run timed triggers, and a browser may block sound until the viewer's first click or key.
   · 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.
@@ -3411,8 +3558,8 @@ 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', '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',
+                    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_event_play_sound', 'looks_at', 'reacts_to', 'drag_to_turn', '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. A name registered with pinepaper_register_custom_relation in this session is accepted too.',
                 },
                 params: {
                     type: 'object',
@@ -3454,7 +3601,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', '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'],
+                    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_event_play_sound', 'looks_at', 'reacts_to', 'drag_to_turn', '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)',
                 },
             },
@@ -3482,7 +3629,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', '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'],
+                    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_event_play_sound', 'looks_at', 'reacts_to', 'drag_to_turn', '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: {
@@ -3503,7 +3650,9 @@ USE WHEN:
             idempotentHint: false,
             openWorldHint: false,
         },
-        description: `Register a custom relation type with compute and apply functions.
+        description: `PARAMS ARE DEFINITIONS, not values: { gap: { type: 'number', default: 60, min: 0 } } (type is number | string | boolean | array | object). Once registered, the name is a valid relationType for pinepaper_add_relation in this session.
+
+Register a custom relation type with compute and apply functions.
 
 USE WHEN:
 - Creating physics-based behaviors (attraction, repulsion, collision)
@@ -3744,6 +3893,10 @@ EASING — IT SHAPES THE SEGMENT ARRIVING AT THE KEYFRAME IT IS ON.
 The move from keyframe A to keyframe B is eased by B's easing, not A's. Easing on the FIRST keyframe does nothing (no segment arrives at it) — a Ken Burns with easing only on its first key plays linear. Put the easing on the key you are moving TO.
 ${EASING_LINES}
 - or a custom cubic-bezier [x1, y1, x2, y2] — x in 0..1, y may exceed 0..1 for overshoot. keyframe_animate and camera_animate only.
+COUNTERS: a text item with a counter (create_item / modify_item counter) also animates the numeric property counterValue, drawn through the counter's format — keyframe it to shape a count by hand (hold on a number, then race). Its keys override the counter's own from / to.
+
+HOLD KEYS (where the studio has them): interpolation: 'hold' on a key holds ITS value until the next key, then cuts — no in-between. Easing 'hold' / 'step' on the ARRIVING key does the same. A studio without hold keys refuses rather than interpolate; there, two keys a frame apart make the cut. For a whole layer 'on twos', set stepTiming on the item (create_item / modify_item).
+
 Every easing renders exactly in video, GIF and APNG. Lottie and CSS get the closest single Bézier: springPlayful loses its wobble, and the in-out quart/quint/expo/circ curves are within 2–4 %. SMIL is exact for springs and those four.
 
 CLIP WINDOW (optional — Premiere/Canva-style clip behavior):
@@ -3824,6 +3977,8 @@ USE WHEN:
 - Seeking to specific time
 - Controlling animation state
 
+PLAYBACK: play { duration?, loop? } · pause {} (holds the playhead) · stop {} (stops and rewinds) · seek { time (s), deterministic? }
+
 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.
@@ -4402,7 +4557,7 @@ SUPPORTED ANIMATIONS: bounce, breathe, fade, glow, jelly, path, pulse, rotate, s
                             target: { type: 'string', description: 'Name of target item' },
                             type: {
                                 type: 'string',
-                                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'],
+                                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_event_play_sound', 'looks_at', 'reacts_to', 'drag_to_turn', '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',
@@ -4535,6 +4690,7 @@ EXAMPLE — Slideshow:
         inputSchema: {
             type: 'object',
             properties: {
+                cutSound: { description: "create_chain: a sound at every cut — a catalogue name, or {sound, gain?, offset? (s)}. The scene_cut event also fires at each cut.", oneOf: [{ type: 'string' }, { type: 'object', additionalProperties: true }] },
                 action: {
                     type: 'string',
                     enum: ['create_chain', 'play', 'pause', 'resume', 'stop', 'toggle_loop', 'jump'],
@@ -5050,7 +5206,7 @@ flags as a badly-composed scene, and they do not survive an artboard change.`,
                 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'] },
+                action: { type: 'string', enum: ['list_patterns', 'list_treatments', 'list_reveals', 'list_styles', 'apply', 'set_treatment'] },
                 pattern: { type: 'string', description: 'Pattern key from list_patterns' },
                 itemIds: { type: 'array', items: { type: 'string' }, description: 'Items in slot order' },
                 treatment: { type: 'string', description: 'Camera treatment key' },
@@ -5058,6 +5214,15 @@ flags as a badly-composed scene, and they do not survive an artboard change.`,
                 applyCamera: { type: 'boolean', description: 'false to arrange without compiling a camera track' },
                 loop: { type: 'boolean' },
                 craft: { type: 'object', description: 'Override craft ratios (gutter, margin…), as fractions of the short canvas edge' },
+                // These were in the Zod schema and the description but not here, so a
+                // client never saw them (1.6.19 gate C3).
+                reveal: { type: ['string', 'null'], description: 'apply: temporal reveal key from list_reveals — items arriving over time' },
+                revealOptions: { type: 'object', description: 'apply: reveal tuning { duration, beat, fade, beats: number[] }; explicit beats sync cuts to audio' },
+                style: { type: 'string', description: 'apply: visual style bundle from list_styles (treatments + spacing + motion defaults)' },
+                text: { type: 'array', items: { type: 'string' }, description: "apply: content for the pattern's TEXT slots (headline, caption…), in slot order" },
+                assets: { type: 'array', items: { type: 'string' }, description: "apply: SVG markup for the pattern's VECTOR slots (badge, logo mark), in slot order" },
+                audio: { type: 'string', description: 'apply: audio source to beat-sync the reveal to' },
+                grid: { type: 'boolean', description: 'apply with audio: snap to an even tempo grid instead of raw onsets' },
             },
             required: ['action'],
         },
@@ -5074,6 +5239,8 @@ ACTIONS:
 - plan: Report what WOULD change (count, per-role breakdown, WCAG contrast audit) WITHOUT touching
   the canvas. Call this first on an unfamiliar scene; a whole-scene recolour is hard to eyeball afterwards.
 - apply: Commit it. A history snapshot is taken FIRST, so one undo puts everything back.
+- set: { kit } — apply it AND make it the ACTIVE brand for the rest of the piece: every shape created afterwards (create_item, batch create, agent_batch_execute) takes colors.primary, and every text colors.text with the heading font from 32 px up (body below), wherever the call names none. Pass noBrand: true in an item's properties to opt it out. Use set at the start of a multi-beat piece so beat 5 matches beat 1. It lives with the studio session: set it again after a reload.
+- get: the active brand (or null).   clear: stop inheriting (what is on the canvas keeps its colours).
 - from_url: { url, screenshots? } — read the product's REAL brand from its own site before animating anything: screenshots down the page, the logo (header image or SVG, else the site icon), and a proposed kit from the colours and fonts the site's CSS computes (buttons and links weigh most). Saved to files; the result lists them. Read in an isolated browser context: the studio is not touched. Review the kit against the screenshots, then plan / apply it. Use the brand you are given, never an invented one.
 
 KIT SHAPE — only name and colors.primary are required:
@@ -5089,7 +5256,7 @@ Both actions return a WCAG contrast audit, so you can see failing pairs before s
         inputSchema: {
             type: 'object',
             properties: {
-                action: { type: 'string', enum: ['plan', 'apply', 'from_url'], description: 'plan (dry run), apply, or from_url (read a site into a proposed kit)' },
+                action: { type: 'string', enum: ['plan', 'apply', 'from_url', 'set', 'get', 'clear'], description: 'plan (dry run), apply (once), set (apply + every new item inherits it), get, clear, or from_url (read a site into a proposed kit)' },
                 url: { type: 'string', description: "from_url: the product's site, http(s)." },
                 screenshots: { type: 'integer', minimum: 1, maximum: 6, description: 'from_url: screenshots down the page (default 3).' },
                 kit: {
@@ -5244,13 +5411,13 @@ ACTIONS:
 - lineage: Walk back to the roots — the chain of imports/derivations that produced it. Params: itemId
 - dependents: What breaks if you delete it. Params: itemId — check this BEFORE removing something
   other items were built from.
-- record: Note that this item derives from a source. Params: itemId, kind, sourceRef, meta`,
+- record: Note where this item came from. Params: itemId, kind (${LINEAGE_KINDS.join(' | ')}; default derivedFrom), sourceRef (an item id, or asset:… / component:…), meta`,
         inputSchema: {
             type: 'object',
             properties: {
                 action: { type: 'string', enum: ['get', 'lineage', 'dependents', 'record'] },
                 itemId: { type: 'string' },
-                kind: { type: 'string', description: 'Lineage kind, e.g. traced | imported | derived' },
+                kind: { type: 'string', enum: [...LINEAGE_KINDS], description: 'record: lineage kind (default derivedFrom)' },
                 sourceRef: { type: 'string', description: 'What it came from (item id, asset id, URL)' },
                 meta: { type: 'object' },
             },
@@ -5386,7 +5553,7 @@ ACTIONS:
             idempotentHint: false,
             openWorldHint: false,
         },
-        description: `Apply GPU-accelerated image filters to raster items.
+        description: `Apply image filters to raster items: a GPU set, plus painted watercolor / painterly looks for photos.
 
 ACTIONS:
 - apply: Apply a single filter. Params: itemId, filterName, params
@@ -5399,6 +5566,8 @@ Available filters (GPU raster set):
 - Stylize: vignette (intensity, radius), edgeDetect, halftoneDots (size, angle), halftoneCMYK (size), dither (levels), grain (amount, seed), scanlines (intensity, period), chromaticAberration (amount), blur (radius)
 - Light (additive): bloom (amount, threshold, radius), glow, halation (warm-fringed bloom; color), lightShafts (amount, threshold, decay, density, x, y, color — volumetric rays from a point)
 - Keying: lumaKey (threshold, softness, invert)
+- Pixel art: pixelate (size or cells across, levels, dither, palette [colours] — e.g. a PICO-8 set), where the studio has it
+- Painted (CPU, STILL images only, where the studio has them): watercolor (strength, seed, radius, edges, bleed, granulation, paper, washes — layered washes, pigment rims, paper grain), painterly (strength, seed, radius, stroke, texture, edges, vivid — brush strokes along the form). About 1 s per 1080p image; the same seed paints the same picture; values are clamped and unknown params are warned about. A video is refused (they cannot run per frame): apply to a still or a captured frame. A studio without them refuses with its list of filters.
 - SECOND-INPUT (params.map = another item's id, resolved to its pixels): displace (amount, dispersion, map, mapChannel — the map's brightness pushes pixels), refract (displace with per-channel dispersion — glass), trackMatte (channel, invert, strength — prefer pinepaper_media apply_track_matte for the live version), datamosh (amount, block, map? — self-moshes without a map)
 
 RECIPE — grunge poster: chain [grain, scanlines, vignette]. Glass header: refract with map = a gradient item.
@@ -5636,6 +5805,8 @@ ACTIONS:
 - 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).
+- catalogue: { catalogue: 'rig_presets' | 'shader_effects' | 'stroke_decorations' | 'precomps' | 'images' | 'segment_edit_kinds' | 'shatter_orders' | 'world_meshes' | 'relation_presets' } — the registries 'list' does not gather.
+- studio: {} — which engine methods THIS studio has, so you learn what will refuse before calling it.
 
 MOOD VOCABULARY FOR CHOOSE:
 - reveal: resolve, reveal, appear, emerge, decode, decrypt, unscramble, form, assemble
@@ -5833,7 +6004,8 @@ ACTIONS:
 BEHAVIOR TYPES: repel, attract, follow, orbit, slingshot, physics_body, draggable_constrained
 - repel params: strength, maxDistance, minDistance, returnSpeed (0–1, default 0.08 — how fast the item eases back to its home position once the target/cursor leaves; returnSpeed: 0 freezes it scattered instead of reforming).
 
-ACTION TYPES: navigate, show, hide, animate, stopAnimation, setState, incrementScore, playTimeline, pauseTimeline, seekTimeline, showFeedback, complete`,
+ACTION TYPES: navigate, show, hide, animate, stopAnimation, setState, incrementScore, playTimeline, pauseTimeline, seekTimeline, showFeedback, complete
+ACTION PARAMS: show / hide / stopAnimation: { items: [ids] } (itemId is accepted); animate: { items, animation?, speed? }; incrementScore: { points } (default 1; amount is accepted); setState: { key, value }.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -5948,7 +6120,7 @@ TEMPLATE CATEGORIES (13):
 EXAMPLES:
 - List all templates: { "listOnly": true }
 - List by category: { "category": "social-media", "listOnly": true }
-- Load template: { "templateId": "solar-system" }`,
+- Load template: { "templateId": "solar-system-education" }`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -6129,7 +6301,7 @@ RETURNS:
             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.',
+                    description: 'Requested connector id. The studio may not honour it (the result says idHonoured): always use the connectorId the result returns in pinepaper_update_connector / pinepaper_remove_connector.',
                 },
                 sourceItemId: {
                     type: 'string',
@@ -6226,7 +6398,7 @@ Same as pinepaper_connect: routing, lineColor, lineWidth, lineStyle, headStyle,
             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.',
+                    description: 'Requested connector id. The studio may not honour it (the result says idHonoured): always use the connectorId the result returns in pinepaper_update_connector / pinepaper_remove_connector.',
                 },
                 sourceItemId: {
                     type: 'string',
@@ -6392,7 +6564,7 @@ EXAMPLES:
 - Grid of icons: {layoutType: "grid", options: {columns: 4, cellWidth: 120}}
 
 PARTIAL LAYOUT:
-Pass itemIds array to only layout specific items, leaving others in place.`,
+Pass itemIds array to only layout specific items, leaving others in place. They are CANVAS ids (item_N) — after pinepaper_import_mermaid, use its nodeItemIds, not the mermaid ids (A, B…), which lay out nothing.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -6404,7 +6576,7 @@ Pass itemIds array to only layout specific items, leaving others in place.`,
                 itemIds: {
                     type: 'array',
                     items: { type: 'string' },
-                    description: 'Specific items to layout (default: all diagram items)',
+                    description: 'Canvas item ids (item_N) to layout (default: all diagram items). After import_mermaid, its nodeItemIds.',
                 },
                 options: {
                     type: 'object',
@@ -6667,14 +6839,13 @@ EXAMPLES:
             idempotentHint: false,
             openWorldHint: false,
         },
-        description: `Load a map and control its viewport. Call action: "load" first to set up; subsequent calls control pan / zoom / config import-export.
+        description: `Load a map and import/export its config. Call action: "load" first.
 
 ACTIONS:
-- load           — { mapId: "usa"|"world"|"worldHighRes"|<custom>, projection?, options? }
-- pan            — { lat, lon, duration? }
-- zoom           — { level, duration? }
+- load           — { mapId: "usa"|"world"|"worldHighRes"|<custom>, projection?, center?: [lon, lat], options? } — center is the projection's centre; options.scale is the d3 projection scale, UNIT-LESS (hundreds: about 600 fills India on a 1080-tall canvas). center alone does not zoom
+- pan, zoom      — REFUSED: the map has no view transform, and a camera move would change only the studio view, which a canvas export ignores. For a moving frame, keyframe a camera animation and export with framing:"camera"
 - export_config  — {}
-- import_custom  — { url? | geojson?, projection? }
+- import_custom  — { url? | geoJson? (geojson accepted), options?: { projection?, fillColor? } }
 
 For region styling/selection use pinepaper_map_regions; for animations use pinepaper_map_animation; for CSV/GeoJSON/source-info use pinepaper_map_data.`,
         inputSchema: {
@@ -6683,6 +6854,7 @@ For region styling/selection use pinepaper_map_regions; for animations use pinep
                 action: { type: 'string', enum: ['load', 'pan', 'zoom', 'export_config', 'import_custom'], description: 'Map action' },
                 mapId: { type: 'string', description: 'Map identifier (load)' },
                 projection: { type: 'string', description: 'Projection (load / import_custom)' },
+                center: { type: 'array', items: { type: 'number' }, minItems: 2, maxItems: 2, description: 'load: [lon, lat] the projection centres on' },
                 options: { type: 'object', description: 'Map options (load)', additionalProperties: true },
                 lat: { type: 'number', description: 'Latitude (pan)' },
                 lon: { type: 'number', description: 'Longitude (pan)' },
@@ -6706,15 +6878,17 @@ For region styling/selection use pinepaper_map_regions; for animations use pinep
         description: `Highlight, color, label, and select map regions. Requires a map loaded via pinepaper_map { action: "load" } first.
 
 ACTIONS:
-- highlight        — { regionIds: string[], color?, opacity? }
+- highlight        — { regionIds: string[], color?, opacity? }   opacity 0..1 tints over the land: pre-blended over the region's land fill, drawn opaque
 - unhighlight      — { regionIds?: string[] }              omit to clear all
 - apply_colors     — { data: Record<regionId, value>, options? }   choropleth coloring
 - add_marker       — { lat, lon, label?, color?, size? }
 - add_labels       — { regions?: string[], style?, formatter? }
-- get_at_point     — { x, y }                              region at canvas coords
+- get_at_point     — { x, y }                              region id + name at canvas coords, and its (lon, lat)
 - select           — { regionIds: string[] }
 - deselect         — { regionIds?: string[] }              omit to deselect all
-- get_highlighted  — {}`,
+- get_highlighted  — {}                                    every region highlight OR apply_colors coloured (one colour channel)
+
+highlight and apply_colors return the regions they coloured, by id, and name any id not on the map (notFound / unmatched).`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -6749,19 +6923,19 @@ ACTIONS:
         description: `Animate map regions with keyframes or wave effects.
 
 ACTIONS:
-- animate_regions  — { regions: Record<regionId, keyframes[]>, duration?, loop? }
-- animate_wave     — { regions?: string[], waveDirection?, speed?, color?, duration?, loop? }
+- animate_regions  — { regions: { [regionId]: [{ time, fillColor (or color), opacity?, easing? }, …at least 2] }, duration?, loop? }
+- animate_wave     — { colors: [at least 2], waveDirection? (horizontal | vertical | radial), waveSpeed?, duration?, loop? } — the wave runs across ALL regions
 - stop             — { regionIds?: string[] }
 - get_animated     — {}`,
         inputSchema: {
             type: 'object',
             properties: {
                 action: { type: 'string', enum: ['animate_regions', 'animate_wave', 'stop', 'get_animated'], description: 'Animation action' },
-                regions: { type: 'object', description: 'Keyframes per region (animate_regions) or list (animate_wave)', additionalProperties: true },
-                regionIds: { type: 'array', items: { type: 'string' } },
+                regions: { description: 'animate_regions: an object of keyframes per region id. stop: an array of region ids to stop (omit for all).' },
+                resetColors: { type: 'boolean', description: 'stop: reset regions to their default colours (default true).' },
+                colors: { type: 'array', items: { type: 'string' }, description: 'animate_wave: colours the wave cycles through (at least 2).' },
                 waveDirection: { type: 'string', enum: ['horizontal', 'vertical', 'radial'] },
-                speed: { type: 'number' },
-                color: { type: 'string' },
+                waveSpeed: { type: 'number' },
                 duration: { type: 'number' },
                 loop: { type: 'boolean' },
             },
@@ -6780,8 +6954,8 @@ ACTIONS:
         description: `CSV / GeoJSON import-export and source-info introspection.
 
 ACTIONS:
-- export_csv               — { regionIds?, columns?, download?, filename? }
-- import_csv               — { csv: string, mapping?: { region?, value?, color? } }
+- export_csv               — { includeColors?, includeHighlighted?, includeSelected?, download?, filename? } — one row per region of the loaded map
+- import_csv               — { csv (or csvText): string, applyColors?, applyHighlight?, applySelection? } — the CSV export_csv writes (one row per region id)
 - export_geojson           — { includeStyles?, includeMetadata?, selectedOnly?, download?, filename? }
 - export_original_geojson  — { download?, filename? }   source GeoJSON before styling
 - source_info              — {}                          { source, projection, quality, regionCount, hasOriginalGeoJSON, isCustomImport }`,
@@ -6789,10 +6963,14 @@ ACTIONS:
             type: 'object',
             properties: {
                 action: { type: 'string', enum: ['export_csv', 'import_csv', 'export_geojson', 'export_original_geojson', 'source_info'], description: 'Data action' },
-                regionIds: { type: 'array', items: { type: 'string' } },
-                columns: { type: 'array', items: { type: 'string' } },
-                csv: { type: 'string' },
-                mapping: { type: 'object', additionalProperties: true },
+                csv: { type: 'string', description: 'import_csv: the CSV text (csvText is accepted too).' },
+                csvText: { type: 'string' },
+                applyColors: { type: 'boolean' },
+                applyHighlight: { type: 'boolean' },
+                applySelection: { type: 'boolean' },
+                includeColors: { type: 'boolean' },
+                includeHighlighted: { type: 'boolean' },
+                includeSelected: { type: 'boolean' },
                 includeStyles: { type: 'boolean' },
                 includeMetadata: { type: 'boolean' },
                 selectedOnly: { type: 'boolean' },
@@ -7148,7 +7326,7 @@ USE WHEN:
 - "grid background", "geometric abstract", "noise texture"
 - Creating dynamic procedural backgrounds
 
-GENERATORS (15 total):
+GENERATORS (highlights; all ${GeneratorNameSchema.options.length} are in the generatorName enum):
 
 Classic:
 - drawSunburst: Radial rays from center (rayCount, colors, bgColor, opacity, rayGap, gradientRays)
@@ -7276,6 +7454,8 @@ USE WHEN:
         },
         description: `Apply a visual effect to an item.
 
+EFFECT OR EMITTER: apply_effect is a live look on an item. For particles a saved scene, a template, the cloud render and every export must reproduce frame for frame — confetti at 2 s, a trail behind a moving item — use pinepaper_emitter: its particles are a pure function of its spec and the scene time.
+
 USE WHEN:
 - Adding sparkle/glitter effects
 - Creating burst/explosion, fire, smoke effects
@@ -7292,7 +7472,7 @@ glow's own default is 1.5. Pass a pixel count here and you will be wrong by
 about two orders of magnitude. A recent studio warns about it
 (kind: 'glow-size-unit'); an older one does not.
 
-EFFECTS (15 particle + 7 shader auras):
+EFFECTS (${EffectTypeSchema.options.length}: particles, then the shader auras from heatmap on):
 - sparkle: Glitter/sparkle particles (color, speed, size)
 - blast: Explosion burst effect (color, radius, count)
 - smoke: Rising smoke plumes (color, speed, size, drift, height, growthRate)
@@ -7362,27 +7542,17 @@ USE WHEN:
 - Post-processing the entire scene
 - User says "make it look vintage", "add blur", "black and white"
 
-AVAILABLE FILTERS:
-- grayscale: Convert to black and white (params: intensity 0-1)
-- sepia: Warm vintage brownish tone (params: intensity 0-1)
-- blur: Gaussian blur effect (params: radius 0-20)
-- brightness: Adjust brightness (params: value -100 to 100)
-- contrast: Adjust contrast (params: value -100 to 100)
-- saturation: Adjust color saturation (params: value -100 to 100). 'saturate' is accepted as the same filter.
-- invert: Invert colors (params: intensity 0-1)
-- noise: Add film grain (params: intensity 0-100, monochrome: true/false)
-- vignette: Darken edges (params: intensity 0-1, radius 0-1)
-- vintage: Preset combining sepia, vignette, noise
-- colorOverlay: Add color tint (params: color, intensity, blendMode)
-- sharpen: Increase sharpness (params: intensity 0-100)
-- emboss: 3D emboss (params: intensity 0-1)
-- posterize: Reduce color levels (params: levels 2-32)
+AVAILABLE FILTERS (the engine's own list, with each one's parameters):
+${FILTER_TYPES.map((f) => `- ${f}: ${FILTER_DOCS[f]}`).join('\n')}
+'saturate' is accepted as saturation.
 
 EXAMPLES:
 - "Make it black and white" → filterType: "grayscale"
 - "Add vintage look" → filterType: "vintage", params: {intensity: 0.8}
 - "Blur the background" → filterType: "blur", params: {radius: 5}
 - "Increase contrast" → filterType: "contrast", params: {value: 30}
+- "Print it like a comic" → filterType: "halftoneCMYK", params: {size: 6}
+- "8-bit / retro screen" → filterType: "dither", params: {levels: 4}
 
 Filters can be stacked - call multiple times to combine effects.`,
         inputSchema: {
@@ -7390,7 +7560,7 @@ Filters can be stacked - call multiple times to combine effects.`,
             properties: {
                 filterType: {
                     type: 'string',
-                    enum: ['grayscale', 'sepia', 'blur', 'brightness', 'contrast', 'saturation', 'invert', 'noise', 'vignette', 'vintage', 'colorOverlay', 'sharpen', 'emboss', 'posterize', 'saturate'],
+                    enum: [...FILTER_TYPES],
                     description: 'Type of filter to apply',
                 },
                 params: {
@@ -7543,28 +7713,403 @@ OUTPUT FORMAT:
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: `Export the complete scene state including all items, relations, and settings.
+        description: `Export the scene: a SUMMARY for inspection by default, or with full: true a RESTORABLE project document saved to a file.
+
+SUMMARY (default) — for reading the scene, not for saving it:
+- items (id, type, position, bounds, active window), relations, decorative items, backgroundColor, canvasSize
+- It does NOT carry keyframe tracks, rigging or scene chains, so a scene rebuilt from it has no motion. The result says so (note).
+
+FULL (full: true) — to save work and restore it later:
+- The engine's own project document (relations, keyframes, rigging, connectors, scene chains, animation config), written to a file because it can be megabytes.
+- Returns filePath, bytes and counts (items, animated items, keyframes, relations). Restore with pinepaper_import_scene { path } and compare the counts.
 
 USE WHEN:
-- Saving a complete scene for later restoration
-- Creating scene backups
-- Debugging scene composition
-- Generating scene snapshots for version control
+- full: true — saving a scene to come back to, a backup, a hand-off to another session
+- summary — debugging composition, checking what is on the canvas`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                full: { type: 'boolean', description: 'Save a restorable project document to a file instead of returning the summary.' },
+                name: { type: 'string', description: 'full: a name recorded in the document.' },
+            },
+        },
+    },
+    {
+        name: 'pinepaper_styled_scene',
+        annotations: {
+            title: 'Styled Scene',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: `One composition, drawn in a built-in STYLE, as one canvas item that redraws itself every exported frame. No drawing code: pick a style, optionally shape the composition, then export.
 
-RETURNS:
-- items: Array of all canvas items with properties
-- relations: Array of active relations
-- decorative: Array of decorative (non-interactive) items
-- backgroundColor: Current background color
-- canvasSize: Canvas dimensions`,
+STYLES: ${STYLED_SCENE_STYLES.map((k) => `${k} (${STYLED_SCENE_STYLE_INFO[k]})`).join('; ')}. Default watercolor; the studio also takes its aliases (watercolour, papercut, 1bit…), and an unknown style is refused with the list.
+
+THE COMPOSITION is data (spec). Every key is optional; omitted keys take the 'valley' preset, a valley going from dream to cost over 8 s: size [W, H], duration, transition {name, start, length}, camera {zoom: [from, to], pan}, palette, sun, clouds, ridges, foreground, river, settlements, structure, pylons, vegetation, effects {steam, ripples, scars}, hud {label}.
+
+THEN EXPORT FOR ITS DURATION: the result carries duration, and the scene runs that long. Pass it as agent_export's duration; a different length cuts the scene short or holds its last frame.
+
+KNOW:
+- Calling again with the same id REPLACES the scene, which is how to change style.
+- dither and ascii need a Chrome renderer (WebKit ignores the canvas filter they use).
+- The scene redraws every frame through a render hook. After a page reload it is a still image until this is called again.
+- It sits below every other item, sized to cover the canvas, so titles and overlays go on top as usual.
+
+EXAMPLE: { style: 'ink', duration: 6 }`,
         inputSchema: {
             type: 'object',
-            properties: {},
+            properties: {
+                style: { type: 'string', description: `${STYLED_SCENE_STYLES.join(' | ')} (default watercolor)` },
+                duration: { type: 'number', description: 'Seconds the scene runs (default 8). Export for this long.' },
+                id: { type: 'string', description: 'Scene id (default "styled-scene"); the same id replaces the scene.' },
+                spec: { type: 'object', description: "The composition; omitted keys take the 'valley' preset.", additionalProperties: true },
+            },
+        },
+    },
+    {
+        name: 'pinepaper_look',
+        annotations: { title: 'Look', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        description: `Restyle what is already drawn — one item, a group and everything in it, or the WHOLE SCENE — as a named look: palette remapped in place (colour keyframes too), strokes, type, image treatment, texture, background and a framing device. Ids, keyframes and relations are kept; it survives a project round trip; remove restores it pixel for pixel. This is "the same subject, in style X".
+
+ACTIONS:
+- list: every look with its FIDELITY — the engine's own grade: native (the medium itself), faithful (close, its approximations named), impression (an evocation, not the real style).
+- describe: { look } — the recipe, its fidelity, what it approximates, and the engine call per part. Read it before promising a look.
+- apply: { look, target? ('scene' default | an itemId), scope? ('item' | 'subtree' | 'scene') } → what it restyled, and the fidelity. An impression comes with a warning — present it as an approximation, not the finished style; a faithful look lists what it approximates.
+- remove: { target } — restore what was there.   get: { target } — the look on it now.
+- grid: { looks?, cols?, cellWidth?, t? } — a contact sheet of the scene in several looks, to choose from: the PNG is the reply's \`data\` (a data URL, as agent_export returns it), with cells [{ id, name, fidelity }].
+
+look is an id from list, or a look spec. An unknown look is refused with the known ones.
+Looks act on what is THERE: they restyle a drawing, they do not redraw a subject from scratch in another medium.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['list', 'describe', 'apply', 'remove', 'get', 'grid'] },
+                look: { description: 'a look id, or a look spec', oneOf: [{ type: 'string' }, { type: 'object', additionalProperties: true }] },
+                target: { type: 'string', description: "an itemId, or 'scene' (default)" },
+                scope: { type: 'string', enum: ['item', 'subtree', 'scene'] },
+                looks: { type: 'array', items: { type: 'string' } },
+                cols: { type: 'integer' }, cellWidth: { type: 'number' }, t: { type: 'number' },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'pinepaper_original_character',
+        annotations: { title: 'Original Character', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        description: `Make an ORIGINAL character from a base rig and a declarative variant — no drawing code, and nothing anyone else owns. Every variant keeps its base's parts and rig, so expressions, walks, poses and pinepaper_choreograph (which drives its root) all work on it.
+
+ACTIONS:
+- bases: the bases (person, robot, cat, bird, blob) with their roles.
+- describe: { base? } — every legal palette key, feature value, accessory (and its slot), proportion range and look. READ IT FIRST: a value it does not list is refused by name and nothing is drawn.
+- random: { base, seed, fixed? } — a distinct, valid variant; the same seed gives the same one. fixed is shared by every member (a look, proportions) while each draws its own signature — a cast of 12 is twelve seeds with one fixed.
+- create: { base, variant?: { palette, features, look, seed, name }, at: { x, y }, height? (320) | scale?, rig? (true) } → itemId (the root), rigId, parts { role: id }. y is the FEET.
+
+FEATURES: hair, eyes, eyeColor, nose, mouth, ears, brows, accessories (12 slots, one per slot), proportions { headScale, bodyScale, limbLength }.
+LOOKS on a rig: flat, ink, charcoal, paper-cutout, pixel. watercolor / oil / hatch are refused with the reason.
+
+INTERACTION (pinepaper_add_relation, source = the character's itemId):
+- looks_at → an item id, or target 'cursor': the face follows it.
+- reacts_to → an event or another character; params reaction (hop | jolt | shake | nod | an expression), after, duration, amount.
+- drag_to_turn (no target): dragging turns the head; params max, sensitivity, turn (keyframeable), spring.
+- a sound on the reaction: on_event_play_sound on the same event.
+
+EXAMPLE: { action: 'create', base: 'person', at: { x: 480, y: 900 }, variant: { palette: { skin: '#e8b48a', hair: '#2b1d16', outfit: '#3a7bd5', accent: '#f2c14e' }, features: { hair: 'bun', eyes: 'almond', mouth: 'smile', accessories: ['cape'] }, look: 'ink', name: 'Mira' } }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['bases', 'describe', 'random', 'create'] },
+                base: { type: 'string' }, variant: { type: 'object', additionalProperties: true },
+                seed: { type: 'integer' }, fixed: { type: 'object', additionalProperties: true },
+                at: { type: 'object', properties: { x: { type: 'number' }, y: { type: 'number' } } },
+                height: { type: 'number' }, scale: { type: 'number' }, rig: { type: 'boolean' },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'pinepaper_morph_sequence',
+        annotations: { title: 'Morph Sequence', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        description: `ONE element through many states, with no cuts: each state grows out of the last (a pill becomes an input field becomes a dot becomes a card). The one-take UI-launch idiom, from one call.
+
+{ itemId, states: [{ at, duration? (0.8), to: itemId | shape: { itemType, position, properties? } }], easing?, camera?, sound? }
+- Each state is the shape the element morphs INTO, starting at \`at\` seconds. Name an existing item (to) or describe one (shape); either way the reference is hidden and the element keeps its own id throughout. States run one after another; an overlap is refused.
+- easing: linear | easeIn | easeOut | easeInOut (default easeInOut) — the four the morph supports.
+- camera: true (or { fill, easing }) keys the camera on the SAME timing: it holds while a state rests and moves with each morph, framing the new state to \`fill\` of the frame (default 0.45).
+- sound: true puts a whoosh at each morph start (or name any catalogue sound).
+
+Shapes morph by kind: path → path point by point, circle → circle by radius, text → text by font, across kinds by a particle transition. Colours and size morph too.
+
+RETURNS: states [{ at, duration, targetId }], end (seconds), camera { keyframes }, sounds.
+
+EXAMPLE — pill → field → dot:
+{ itemId: "item_1", camera: true, sound: true, states: [
+  { at: 1, shape: { itemType: "rectangle", position: { x: 960, y: 540 }, properties: { width: 640, height: 88, cornerRadius: 44, color: "#ffffff" } } },
+  { at: 3, shape: { itemType: "circle", position: { x: 960, y: 540 }, properties: { radius: 18, color: "#111111" } } } ] }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                itemId: { type: 'string' },
+                states: { type: 'array', items: { type: 'object', properties: { at: { type: 'number' }, duration: { type: 'number' }, to: { type: 'string' }, shape: { type: 'object', additionalProperties: true } }, required: ['at'] } },
+                easing: { type: 'string', enum: ['linear', 'easeIn', 'easeOut', 'easeInOut'] },
+                camera: { description: 'true, or {fill, easing}', oneOf: [{ type: 'boolean' }, { type: 'object', additionalProperties: true }] },
+                sound: { description: 'true, or a catalogue sound name', oneOf: [{ type: 'boolean' }, { type: 'string' }] },
+            },
+            required: ['itemId', 'states'],
+        },
+    },
+    {
+        name: 'pinepaper_emitter',
+        annotations: { title: 'Particle Emitter', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        description: `Particles as an ITEM whose every frame is a pure function of its spec and the scene time — so the preview, capture_frames, every export, a saved project, a template and the cloud render all draw the same particles, scrubbing backwards included. The serialisable, cloud-safe choice; pinepaper_apply_effect is a live look on an item.
+
+ACTIONS:
+- create: { spec } → itemId
+- set: { itemId, spec } — merge a partial spec onto the emitter's.
+
+SPEC:
+- mode: 'burst' (default) — bursts: [{ t, x, y, count, …per-burst overrides }]: a pop of particles at scene time t.
+- mode: 'trail' (or give target) — target (an item id), rate (per second), emitWindows [[t0, t1], …], window, offset: particles shed from a moving item.
+- look and physics (per emitter or per burst): shape ('circle' | 'rect' | 'dash' | 'star' | 'confetti', or an array), palette [colours], size / sizes / sizeEnd, speed + angle ranges or velocities, gravity (px/s², +down), drag, friction, lifetime, fadeIn / fadeOut, spin, opacity, jitter, seed.
+An unknown shape, mode or bad range is refused with the engine's reason — never defaulted.
+
+EXAMPLE — confetti at 2 s:
+{ action: 'create', spec: { bursts: [{ t: 2, x: 960, y: 400, count: 80 }], shape: 'confetti', palette: ['#f43f5e', '#facc15', '#22d3ee'], speed: [300, 700], angle: [-150, -30], gravity: 900, lifetime: 2.5, seed: 7 } }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['create', 'set'] },
+                itemId: { type: 'string', description: 'set: the emitter' },
+                spec: { type: 'object', additionalProperties: true, description: 'create: the whole spec; set: the keys to change' },
+            },
+            required: ['action', 'spec'],
+        },
+    },
+    {
+        name: 'pinepaper_render_hook',
+        annotations: { title: 'Render Hook', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        description: `Custom per-frame drawing that a saved scene CARRIES: SOURCE TEXT, compiled and run under the governor's loop guards with seeded Math, saved in the project document, the template and undo, and re-installed on load. (A raw function added with code is not saved — pinepaper_export_scene { full: true } names any such as unserialized.)
+
+ACTIONS:
+- register: { id, source, layer? ('above' | 'below'), deterministic? (true), seed? } — source evaluates to (ctx, t, info) => {}: ctx in canvas coordinates, t the scene time in seconds, info { width, height, frame, seed }. 'above' draws over every item, 'below' under them. deterministic reseeds Math.random from (seed, frame) each call, so a frame always draws the same.
+- unregister: { id }   list: the saved hooks.
+
+Reach for it when no tool draws the look (a scanline overlay, a custom texture pass). For particles, pinepaper_emitter is data rather than code.
+
+EXAMPLE: { action: 'register', id: 'scanlines', layer: 'above', source: "(ctx, t, info) => { ctx.globalAlpha = 0.08; for (let y = (t * 40) % 4; y < info.height; y += 4) ctx.fillRect(0, y, info.width, 1); }" }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['register', 'unregister', 'list'] },
+                id: { type: 'string' }, source: { type: 'string' },
+                layer: { type: 'string', enum: ['above', 'below'] },
+                deterministic: { type: 'boolean' }, seed: { type: 'integer' },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'pinepaper_choreograph',
+        annotations: {
+            title: 'Choreograph an Actor',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Make any item ACT: a list of beats compiled to one keyframe track with anticipation, squash and stretch, contact and settle — the timing a hand animator would key, from one call.
+
+BEATS run one after another: [{ at, verb, ...params }]. Positions are the actor's CENTRE in canvas px; a squash keeps its BOTTOM on the ground.
+- pop: scales up from nothing with an overshoot (an entrance in place).
+- drop { to? }: falls and lands with a squash. Already in the air (after a fly), it falls from where it is; on the ground or below the landing point, it comes in from above the frame.
+- hop { to?, height? }: crouch, launch stretched, arc, land squashed, settle. Without to it hops in place.
+- bounce { times? (3), height?, decay? (0.6), to? }: bounces that lose height; with to it travels while bouncing.
+- roll { to }: rolls without slipping — it turns by the distance over its radius (right = clockwise).
+- fly { to, arc? }: an arc through the air, nose up on the rise and down on the fall.
+- peek { edge (left|right|top|bottom), amount? (0.5), hold? (1) }: slides partly in from a frame edge, waits, ducks back out.
+- shake { intensity? }: a startled shiver.   squash { amount? }: an in-place squash and recover (a reaction, a landing hit).
+- enter { from (edge), to? }: slides in from an edge with an overshoot.   exit { edge }: a small anticipation, then away off that edge.
+Each verb has a default duration; pass duration to change it.
+
+WHAT IT RETURNS: keyframes written, the duration, and where the actor ends (and whether that is on screen). Beats that overlap, an unknown verb, or roll / fly without a destination are refused by name.
+
+ACTORS: a shape, a group, an imported SVG character, a photo cut-out — anything with one transform. Its own scale and rotation are kept (a beat squashes relative to them). A figure placed by pinepaper_character is several parts with their own tracks and no single transform, so choreograph its parts' group only if you grouped a STATIC figure; otherwise direct it with character beats.
+
+SOUND: sound: true puts a sound on every moment the motion makes — the pop, each launch, every landing (a bounce's landings get quieter as the bounces shrink), a shake — placed on the timeline and baked into the video. sound: { contact: 'kick', whoosh: false, gain: 0.6 } picks or silences them by catalogue name (SFX beep, pop, wind, whoosh, zap; drums kick, snare, tom, hat, clap; or your own from define_sfx). The reply lists the sounds placed. A sound due before 0.06 s is placed at 0.06 s (movedFrom says so): an MP4 encoder swallows the first ~50 ms of audio.
+
+MIX WITH: pinepaper_character / text expressions on top; pinepaper_apply_effect (confetti, shockwave) at a landing; pinepaper_sound at the same times. Call choreograph BEFORE keyframing the actor's other properties (colour, fill): the beat keys carry position, scale, rotation and opacity only, and the result warns if the actor already animates something else.
+
+EXAMPLE — a ball comes to life and crosses the frame:
+{ itemId: "item_1", beats: [ { at: 0, verb: "pop" }, { at: 0.6, verb: "bounce", times: 3, to: [700, 820] }, { at: 2.4, verb: "roll", to: [1200, 820] }, { at: 3.5, verb: "fly", to: [1600, 300] } ] }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                itemId: { type: 'string', description: 'The actor (any item with one transform).' },
+                sound: { description: "true, or {pop?, whoosh?, contact?, shake? (catalogue name or false), gain? 0..1}: a sound on every pop, launch, landing and shake.", oneOf: [{ type: 'boolean' }, { type: 'object', additionalProperties: true }] },
+                beats: {
+                    type: 'array',
+                    description: 'Beats in time order: [{at, verb, to?, duration?, height?, times?, decay?, arc?, edge?, from?, amount?, hold?, intensity?}].',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            at: { type: 'number' },
+                            verb: { type: 'string', enum: ['pop', 'drop', 'hop', 'bounce', 'roll', 'fly', 'peek', 'shake', 'squash', 'enter', 'exit'] },
+                            to: { description: '[x, y] or {x, y}: the actor centre at the end of the beat' },
+                            duration: { type: 'number' }, height: { type: 'number' }, times: { type: 'integer' }, decay: { type: 'number' },
+                            arc: { type: 'number' }, edge: { type: 'string', enum: ['left', 'right', 'top', 'bottom'] }, from: { type: 'string', enum: ['left', 'right', 'top', 'bottom'] },
+                            amount: { type: 'number' }, hold: { type: 'number' }, intensity: { type: 'number' },
+                        },
+                        required: ['at', 'verb'],
+                    },
+                },
+            },
+            required: ['itemId', 'beats'],
+        },
+    },
+    {
+        name: 'pinepaper_relight',
+        annotations: {
+            title: 'Relight the 3D World',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: `Light the 3D world layer (pinepaper_world3d) with point and directional lights — a post pass, so the lit side of every surface reads brighter in the preview and the export.
+
+ACTIONS:
+- set: { lights, ambient?, strength?, enabled?, preview? } — install or replace the rig. Up to 8 lights:
+    point:       { type: 'point', x, y, z? (120), radius? (400), color?, intensity? (1), specular? (32) }
+    directional: { type: 'directional', dir: [dx, dy, dz], color?, intensity? }   [0, 0, -1] faces the viewer
+  Coordinates are export-frame px; colours are '#rrggbb' or [r, g, b]. ambient default 0.2, strength (normal-map) default 2.
+  The result reports cost: the pass runs on the CPU, about 0.42 s per 1080p frame, so a 10 s MP4 at 30 fps takes about 2 minutes longer.
+- get: the current rig.
+- clear: remove it.
+- list_lights: the light types.
+
+LIMITS — say them before you promise a look:
+- Applied in the preview and in PNG, PDF, MP4 and WebM exports. GIF and APNG are NOT relit (agent_export says so when it happens).
+- Normals come from the world's brightness, not real depth, so it reads as raking light over the picture rather than true 3D shading.
+- It lights the 3D world layer only, not 2D items drawn over it.
+- The rig is NOT saved with the project: set it again after reloading.
+- A studio without the relight pass refuses with the reason.
+
+EXAMPLE: { action: 'set', lights: [{ type: 'point', x: 1500, y: 200, z: 300, radius: 1200, color: '#ffd9a0', intensity: 1.4 }], ambient: 0.15 }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['set', 'get', 'clear', 'list_lights'], description: 'Relight operation' },
+                lights: { type: 'array', items: { type: 'object', additionalProperties: true }, description: "set: up to 8 lights, {type:'point', x, y, z?, radius?, color?, intensity?, specular?} or {type:'directional', dir:[dx,dy,dz], color?, intensity?}" },
+                ambient: { type: 'number', description: 'set: ambient light (default 0.2)' },
+                strength: { type: 'number', description: 'set: normal-map strength (default 2)' },
+                enabled: { type: 'boolean', description: 'set: false keeps the rig but turns it off' },
+                preview: { description: 'set: true / false, or {maxSide} for the live preview overlay', oneOf: [{ type: 'boolean' }, { type: 'object', properties: { maxSide: { type: 'number' } } }] },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'pinepaper_shader_graph',
+        annotations: {
+            title: 'Shader Graph',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Build a pixel-processing graph from nodes (normal map, relighting, depth of field, bloom) and run it over an item or the whole scene.
+
+ACTIONS:
+- node_types: the node vocabulary with each node's params. Call this first.
+- validate: { graph } — check it, store nothing. Errors are named (unknown type, duplicate id, dangling edge, cycle, branching).
+- create: { graph } → graphId — validate and store.
+- get / remove: { graphId }.  list: the stored graphs.
+- apply: { target, graph | graphId, keepSource?, asItem? }
+    target = an itemId → the item's pixels become a NEW image item in its place (returned itemId); the source is hidden unless keepSource:true. One undo step.
+    target = 'scene' → the rendered frame is processed and returned as a PNG (data); the scene does not change. asItem:true adds it as an image item instead.
+
+GRAPH: { nodes: [{ id, type, params? }], edges: [{ from, to }] } — a LINEAR chain from SourceInput to OutputCompositor. A NormalGen feeds a Relighting node; a DepthMap feeds DepthOfField.
+
+PARAMS come from node_types, which is the studio's own list. SelectiveBloom: threshold 0..1, intensity 0..10, and radius 0..64 px (the glow's reach past the bright pixels; 0 keeps the glow inside them) where the studio has it. A glow can make the new item LARGER than its source, centred on it: read its bounds from the reply rather than reusing the source's.
+
+The graph runs on the CPU. Stored graphs live for the session, not in the project. A studio without the shader graph refuses with the reason.
+
+EXAMPLE: { action: 'apply', target: 'item_4', graph: { nodes: [{ id: 'in', type: 'SourceInput' }, { id: 'bloom', type: 'SelectiveBloom', params: { threshold: 0.6, intensity: 2 } }, { id: 'out', type: 'OutputCompositor' }], edges: [{ from: 'in', to: 'bloom' }, { from: 'bloom', to: 'out' }] } }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['node_types', 'validate', 'create', 'get', 'list', 'remove', 'apply'], description: 'Shader graph operation' },
+                graph: { type: 'object', description: 'validate / create / apply: {id?, nodes: [{id, type, params?}], edges: [{from, to}]}', additionalProperties: true },
+                graphId: { type: 'string', description: 'get / remove / apply: a stored graph id' },
+                target: { type: 'string', description: "apply: an itemId, or 'scene'" },
+                keepSource: { type: 'boolean', description: 'apply to an item: keep the source visible' },
+                asItem: { type: 'boolean', description: "apply to 'scene': add the result as an image item" },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'pinepaper_place_on_surface',
+        annotations: {
+            title: 'Place on Surface',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: `Put a UI ONTO A SCREEN inside a photo: a phone, a monitor, a billboard. It is corner-pinned into the screen's perspective, matted by the photo's own brightness so a thumb or hand stays IN FRONT, softened to the photo, and keeps a little glass glare and light spill. A card laid over a phone photo reads as a sticker; this reads as the screen.
+
+- photoId: the photo (an image item). sourceId: the UI, any canvas item or group (rendered at about twice the screen's size), or an image.
+- quad: the screen's corners TL, TR, BR, BL in the photo's pixels (quadSpace 'canvas' for canvas coordinates). Omit it to DETECT the screen (the largest bright, neutral region); the result's quad and detected say what was found. If nothing is found it refuses: pass quad.
+- The result is BAKED INTO THE PHOTO'S PIXELS, so a zoom or camera move on the photo carries it. Placing again in the same slot replaces it; use different slots for several screens. Undo restores the photo.
+- Tuning: occlusion ('luma' | 'none'), key, erode, matteBlur, soften, glare, spill, spillRadius, tint [r, g, b]. hideSource (default true) hides the UI item once placed.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                photoId: { type: 'string', description: 'The photo (an image item).' },
+                sourceId: { type: 'string', description: 'The UI to place (any item or group, or an image).' },
+                quad: { type: 'array', items: { type: 'array', items: { type: 'number' }, minItems: 2, maxItems: 2 }, minItems: 4, maxItems: 4, description: 'Corners TL, TR, BR, BL as [x, y]; omit to detect.' },
+                quadSpace: { type: 'string', enum: ['image', 'canvas'], description: "quad's coordinates (default 'image', the photo's pixels)." },
+                occlusion: { type: 'string', enum: ['luma', 'none'], description: "'luma' (default) keeps a hand in front of the screen." },
+                key: { type: 'number', description: 'Brightness that counts as screen (default: found from the photo).' },
+                erode: { type: 'number', description: 'Pull the matte in from the bezel, px (default 2).' },
+                matteBlur: { type: 'number', description: 'Matte edge softness (default 0.8).' },
+                soften: { type: 'number', description: 'Soften the UI to the photo (default 0.5).' },
+                glare: { type: 'number', description: 'Glass glare 0..1 (default 0.10).' },
+                spill: { type: 'number', description: 'Light spill 0..1 (default 0.35).' },
+                spillRadius: { type: 'number', description: 'Spill reach, px (default 40).' },
+                tint: { type: 'array', items: { type: 'number' }, minItems: 3, maxItems: 3, description: 'Multiply the UI by [r, g, b] 0..1 to match white balance.' },
+                slot: { type: 'string', description: "Screen name (default 'screen'); the same slot replaces." },
+                hideSource: { type: 'boolean', description: 'Hide the UI item after placing (default true).' },
+            },
+            required: ['photoId', 'sourceId'],
+        },
+    },
+    {
+        name: 'pinepaper_import_scene',
+        annotations: {
+            title: 'Import Scene',
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: `Restore a scene from a project document saved by pinepaper_export_scene { full: true }. REPLACES the current scene.
+
+The engine validates the document before applying it: a truncated file, a foreign JSON blob or a document from a newer major version is refused, not half-applied. Returns counts (items, animated items, keyframes, relations): compare them with the export's to confirm nothing was lost.
+
+- path: the file the export wrote (absolute, or relative to the server's working directory).
+- strict: false loads a document with validation problems anyway and returns them as warnings (default true: refuse).`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'The project document file.' },
+                strict: { type: 'boolean', description: 'Refuse a document with validation problems (default true).' },
+            },
+            required: ['path'],
         },
     },
-    // ---------------------------------------------------------------------------
-    // INFRASTRUCTURE: BROWSER CONTROL TOOLS
-    // ---------------------------------------------------------------------------
     {
         name: 'pinepaper_browser_connect',
         annotations: {
@@ -7818,9 +8363,9 @@ PRIVACY: No screenshots, no tool call arguments, no user content — only struct
 
 ⚠️ Call ONCE per pipeline. NEVER restart — creates duplicates.
 
-WORKFLOW: start_job → batch_execute (everything in ONE call) → end_job (screenshot) → show user → iterate if needed.
+WORKFLOW: start_job → the craft tool(s) that fit the brief (styled_scene, story, character, text_style, compose, design_medium…) → batch_execute for the primitive glue, in ONE call → end_job (screenshot) → show user → iterate if needed. Primitive shapes over a generator backdrop is the stock look; use it only when no higher-level tool fits.
 
-RETURNS: canvasSize {width, height} — use this to position items within bounds. Also returns ontology: a pp: triples + item summary snapshot of the (typically empty) canvas. Reuse this baseline across the same agent turn instead of calling pinepaper_get_canvas_ontology unless you've mutated the canvas. When clearCanvas is false, the ontology captures whatever's already on the canvas.
+RETURNS: canvasSize {width, height} — use this to position items within bounds. Without a canvasPreset, an unbounded canvas is fixed at that size, so stills and video both export it (the result says so in note). Also returns ontology: a pp: triples + item summary snapshot of the (typically empty) canvas. Reuse this baseline across the same agent turn instead of calling pinepaper_get_canvas_ontology unless you've mutated the canvas. When clearCanvas is false, the ontology captures whatever's already on the canvas.
 
 CANVAS PRESETS: instagram (1080x1080), instagram-story (1080x1920), tiktok (1080x1920), youtube (1920x1080), youtube-thumbnail (1280x720), twitter (1200x675), linkedin (1200x627), web, print-a4, print-letter, print-a4-landscape, print-letter-landscape (print presets carry 300 dpi, so a PDF comes out at paper size)`,
         inputSchema: {
@@ -7971,7 +8516,7 @@ EXAMPLES:
             idempotentHint: false,
             openWorldHint: false,
         },
-        description: `Execute ALL operations in a single call for building animated scenes — canvas setup, backgrounds, items, animations, masks, effects, and playback.
+        description: `Execute the primitive operations of a scene in a single call — canvas setup, backgrounds, items, animations, masks, effects, and playback. It is the GLUE: a styled scene, a character, a story or a crafted title has its own tool (styled_scene, character, story, text_style), called first.
 
 NOTE: For diagrams (flowcharts, UML), use pinepaper_create_diagram_shape + pinepaper_connect instead.
 
@@ -7982,20 +8527,20 @@ NOTE: For diagrams (flowcharts, UML), use pinepaper_create_diagram_shape + pinep
 ONTOLOGY PREFLIGHT: Before code generation, this tool validates itemType, relationType, effectType, and generatorName against the canonical PinePaper vocabulary. A typo (e.g. "circel") returns a structured VALIDATION_ERROR with the operation index, the offending field, the canonical valid list, and a suggested fix — fix and retry rather than guessing. Pass skipValidation: true to bypass when intentionally using experimental vocabulary.
 
 WORKFLOW:
-1. pinepaper_agent_start_job → 2. pinepaper_agent_batch_execute (everything) → 3. pinepaper_agent_end_job (screenshot for validation)
+1. pinepaper_agent_start_job → 2. the craft tools that fit the brief (styled_scene, story, character, text_style, compose…) → 3. pinepaper_agent_batch_execute (the primitive glue, in one call) → 4. pinepaper_agent_end_job (screenshot for validation)
 After validation: user reviews screenshot → feedback → modify/recreate as needed.
 
-OPERATION TYPES (13) — use in this order:
+OPERATION TYPES (${AgentBatchOperationTypeSchema.options.length}) — use in this order:
 
 CANVAS SETUP:
-  set_canvas_size — {width, height} or {preset: "instagram"|"youtube"|"tiktok"|...}
+  set_canvas_size — {width, height} or {preset: "instagram-post"|"instagram-story"|"youtube-thumbnail"|"tiktok"|"full-hd-1080p"|...} (studio preset keys, not platform names; an unknown one is refused with the list)
   set_background — {backgroundColor: "#hex"}
   execute_generator — {generatorName, generatorParams} → fills canvas with procedural art (paints WITHOUT fully registering items — see get_items; custom generator names need skipValidation:true)
     Generators: drawBokeh, drawGradientMesh, drawWaves, drawSunburst, drawSunsetScene, drawGrid, drawCircuit, drawPattern, drawStackedCircles, drawGeometricAbstract, drawWindField, drawFluidFlow, drawOrganicFlow, drawNoiseTexture, drawGlobeWireframe
     PineMath: drawFunctionPlot (y=f(x) plots), drawParametricCurve (x(t),y(t)), drawSimulation (pendulum, Lorenz, spring-mass), drawSpectrumAnalyzer (FFT), draw3DSurface (torus, sphere, Klein bottle)
 
 ITEMS:
-  create — {itemType, position: {x,y}, properties}
+  create — {itemType, position: {x,y} or [x,y], properties}
     itemType: text, circle, rectangle, star, triangle, polygon, ellipse, path, line, arc, pentagon, hexagon, diamond, arrow, heart
     Properties per type:
       text: {content, fontSize, fontFamily, color, fontWeight}
@@ -8037,14 +8582,14 @@ ANIMATION NOTES:
 
 EXAMPLE — Animated sky scene with timed reveals:
 {operations: [
-  {type: "set_canvas_size", preset: "youtube"},
+  {type: "set_canvas_size", preset: "full-hd-1080p"},
   {type: "execute_generator", generatorName: "drawGradientMesh", generatorParams: {colors: ["#1e3a5f", "#87CEEB", "#fbbf24"], bgColor: "#0c1445", blobCount: 4}},
   {type: "create", itemType: "circle", position: {x: 1600, y: 150}, properties: {radius: 80, color: "#fbbf24", shadowColor: "#fbbf24", shadowBlur: 40}},
   {type: "create", itemType: "ellipse", position: {x: 400, y: 180}, properties: {radiusX: 100, radiusY: 35, color: "#ffffff", opacity: 0.8}},
   {type: "create", itemType: "ellipse", position: {x: 900, y: 120}, properties: {radiusX: 120, radiusY: 40, color: "#ffffff", opacity: 0.7}},
   {type: "create", itemType: "text", position: {x: 960, y: 500}, properties: {content: "Dream Big", fontSize: 96, color: "#ffffff", fontWeight: "bold"}},
   {type: "animate", itemId: "$0", animationType: "pulse", animationOptions: {speed: 0.3}},
-  {type: "animate", itemId: "$1", animationType: "slide", animationOptions: {speed: 0.2, direction: "left"}},
+  {type: "animate", itemId: "$1", animationType: "slideLeftRight", animationOptions: {speed: 0.2}},
   {type: "animate", itemId: "$2", animationType: "slide", animationOptions: {speed: 0.15, direction: "left"}},
   {type: "keyframe_animate", itemId: "$3", keyframes: [{time: 0, properties: {opacity: 0, scale: 0.8}}, {time: 2, properties: {opacity: 1, scale: 1}, easing: "easeOutBack"}], duration: 3},
   {type: "apply_mask", itemId: "$3", maskPreset: "wipeLeft"},
@@ -8081,9 +8626,11 @@ EXAMPLE — Animated sky scene with timed reveals:
                                 description: 'For create: item type',
                             },
                             position: {
-                                type: 'object',
-                                properties: { x: { type: 'number' }, y: { type: 'number' } },
-                                description: 'For create: position {x, y}',
+                                oneOf: [
+                                    { type: 'object', properties: { x: { type: 'number' }, y: { type: 'number' } } },
+                                    { type: 'array', items: { type: 'number' }, minItems: 2, maxItems: 2 },
+                                ],
+                                description: 'For create: position {x, y} or [x, y]',
                             },
                             properties: { type: 'object', description: 'For create/modify: item properties' },
                             itemId: { type: 'string', description: 'Target item ID or $N reference' },
@@ -8093,7 +8640,7 @@ EXAMPLE — Animated sky scene with timed reveals:
                             // Loop animation
                             animationType: {
                                 type: 'string',
-                                enum: ['bounce', 'breathe', 'fade', 'glow', 'jelly', 'path', 'pulse', 'rotate', 'scrollDown', 'scrollLeft', 'scrollRight', 'scrollUp', 'shake', 'slideLeftRight', 'slideUpDown', 'swing', 'typewriter', 'wobble'],
+                                enum: [...SimpleAnimationTypeSchema.options],
                                 description: 'For animate: loop animation type',
                             },
                             animationOptions: { type: 'object', description: 'For animate: {speed, amplitude, direction}' },
@@ -8117,7 +8664,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', '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'],
+                                enum: [...RelationTypeSchema.options],
                                 description: 'For relation: type',
                             },
                             relationOptions: { type: 'object', description: 'For relation: options' },
@@ -8132,7 +8679,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', 'electric_arc', 'vortex', 'rain_veil', 'caustics'],
+                                enum: [...EffectTypeSchema.options],
                                 description: 'For apply_effect: effect type',
                             },
                             effectParams: { type: 'object', description: 'For apply_effect: parameters' },
@@ -8207,7 +8754,7 @@ Held exports last until released, or until a LATER export needs the space — an
     {
         name: 'pinepaper_agent_export',
         annotations: {
-            title: 'Export as MP4 Video, GIF, PNG, SVG, or PDF',
+            title: 'Export Video, Stills, Animation, Ads, Captions or Audio',
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
@@ -8236,7 +8783,7 @@ PLATFORMS & OPTIMAL FORMATS:
 
 A preset's dimensions assume the canvas has the same aspect. When it does not, the canvas aspect is KEPT (never stretched) and its short edge takes the preset's short edge — a 4:5 canvas on instagram exports 1080x1350 — and the result carries platformFit saying so.
 
-FORMATS: svg, png, gif, mp4, webm, pdf.
+FORMATS: ${AgentExportFormatSchema.options.join(', ')}.
 QUALITY: draft, standard, high.
 FRAMING: canvas (default, full canvas) | camera (camera_animates first-keyframe viewport — video formats only, requires a keyframe-mode walkthrough on the canvas; camera animation still drives motion within the fixed output frame).
 
@@ -8259,7 +8806,7 @@ VERIFY MOTION BEFORE YOU RENDER. An export takes seconds to minutes and shows yo
                 platform: {
                     type: 'string',
                     enum: ['auto', 'instagram', 'instagram-story', 'tiktok', 'youtube', 'youtube-thumbnail', 'twitter', 'linkedin', 'web', 'print-a4', 'print-letter', 'print-a4-landscape', 'print-letter-landscape'],
-                    description: "Target platform, which sets the output DIMENSIONS. 'auto' (the default) renders the canvas at its own size — use it when the canvas is already the size you want, otherwise a preset REPLACES your dimensions. Every other value forces that platform's frame regardless of the canvas.",
+                    description: "Target platform, which sets the output DIMENSIONS. 'auto' (the default) renders the canvas at its own size — use it when the canvas is already the size you want, otherwise a preset sets the output SIZE from the platform's short edge. The canvas aspect is kept, never stretched: on a canvas of a different aspect the output is not the platform's frame (an 800x600 canvas on instagram exports 1440x1080), and the result's platformFit says so. To get the exact frame, set the canvas to the platform's aspect first.",
                 },
                 format: {
                     type: 'string',
@@ -8675,6 +9222,14 @@ Three-phase analysis:
 
 Quality tiers: basic (<0.4), fair (0.4-0.6), good (0.6-0.8), excellent (>=0.8)
 
+DEFINITION SHAPE (a template document; id, name, category and data are REQUIRED, the rest optional; items and relations sit under data):
+{ id, name, category, dimensions?: { width, height }, duration? (s), description?, tags?: [..], semantics?: {..},
+  data: {
+    items: [{ id, type ('circle', 'text' …), x?, y? | position?: [x, y], content?, animationType?, keyframes?: [{ time, properties: {..}, easing? }], mask?: { type } }],
+    relations: [{ type ('orbits' …), source | from, target | to, params? }],
+    backgroundGenerator?, backgroundGeneratorParams?
+  } }
+
 USE WHEN:
 - Checking a template for structural issues before publishing
 - Comparing quality scores between template variants
@@ -8860,12 +9415,12 @@ USE WHEN:
 - You want more/less detail in tool descriptions → switch verbosity
 
 PROFILES:
-- full: All 120+ tools
-- agent: Core creative tools (~50 tools) — default
+- full: Every tool, no filtering
+- agent: Every tool except the diagnostics (get_performance_metrics, diagnostic_report) and register_item — default
 - diagram: Diagram/flowchart tools
 - map: Map/choropleth tools
 - font: Font creation tools
-- minimal: Bare essentials (~15 tools)
+- minimal: Bare essentials
 
 VERBOSITY:
 - verbose: Full descriptions
@@ -9091,7 +9646,7 @@ ACTIONS:
 - set_rulers: Show/hide rulers. Params: enabled (bool)
 - set_grid: Show/hide unit grid. Params: enabled (bool)
 - get_dimensions: Get item bounds. Params: itemId → returns {x, y, width, height, rotation}
-- set_snap: Enable/disable snap-to-grid. Params: enabled (bool)`,
+- set_snap: Enable/disable snapping a DRAG or RESIZE in the studio to the unit grid (only while the grid is on). Params: enabled (bool). Items placed by tools are not snapped.`,
         inputSchema: {
             type: 'object',
             properties: {