@pinepaper.studio/mcp-server 1.6.18 → 1.6.19

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
@@ -111,7 +111,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 +197,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 +255,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 +269,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).
         },
     },
     {
@@ -1106,7 +1104,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 +1126,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 +1185,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 +1195,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 +1238,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 +1272,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 +1296,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 +1308,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',
@@ -2117,7 +2116,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 +2215,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 +2292,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 +2317,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 +2355,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? } — 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 +2363,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 +2389,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 +2438,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 +2592,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 +2681,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 +2705,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 +2713,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." },
@@ -2792,13 +2802,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 +2854,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 +2928,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 +3009,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 +3082,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 +3123,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 +3211,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 +3226,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 +3332,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',
@@ -3412,7 +3510,7 @@ Relations are COMPOSITIONAL - an item can have multiple relations that work toge
                 relationType: {
                     type: 'string',
                     enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', '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',
+                    description: 'Type of relationship. A name registered with pinepaper_register_custom_relation in this session is accepted too.',
                 },
                 params: {
                     type: 'object',
@@ -3503,7 +3601,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)
@@ -3824,6 +3924,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.
@@ -5050,7 +5152,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 +5160,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'],
         },
@@ -5244,13 +5355,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' },
             },
@@ -5636,6 +5747,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 +5946,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 +6062,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 +6243,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 +6340,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',
@@ -6667,14 +6781,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 +6796,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 +6820,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 +6865,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 +6896,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 +6905,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 +7268,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)
@@ -7292,7 +7412,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 +7482,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 +7500,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 +7653,204 @@ 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_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: {
@@ -7820,7 +8106,7 @@ PRIVACY: No screenshots, no tool call arguments, no user content — only struct
 
 WORKFLOW: start_job → batch_execute (everything in ONE call) → end_job (screenshot) → show user → iterate if needed.
 
-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: {
@@ -7985,17 +8271,17 @@ WORKFLOW:
 1. pinepaper_agent_start_job → 2. pinepaper_agent_batch_execute (everything) → 3. 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 +8323,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 +8367,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 +8381,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 +8405,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 +8420,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 +8495,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 +8524,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 +8547,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 +8963,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 +9156,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 +9387,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: {