@pinepaper.studio/mcp-server 1.6.17 → 1.6.19

package/dist/tools/definitions.js

@@ -10,8 +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 { EffectTypeSchema, SimpleAnimationTypeSchema, EasingSchema, 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
@@ -25,6 +26,7 @@ const SIMPLE_ANIMATION_TYPES_LIST = SimpleAnimationTypeSchema.options.join(', ')
 // easeInCubic / easeOutCubic / easeOutBounce, which keyframe_animate rejects
 // (round 8 DD, 1.68) — derived now, so it cannot say what the schema refuses.
 const KEYFRAME_EASINGS_LIST = EasingSchema.options.join(', ');
+const EASING_LINES = KEYFRAME_EASINGS.map((e) => `- ${e}: ${EASING_DESCRIPTIONS[e]}`).join('\n');
 // =============================================================================
 // AI AGENT GUIDE (exported for pinepaper_tool_guide)
 // =============================================================================
@@ -109,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):
@@ -195,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)`;
 /*
@@ -253,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: {
@@ -269,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).
         },
     },
     {
@@ -1104,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
@@ -1126,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"
@@ -1182,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
@@ -1192,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)
@@ -1237,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: {
@@ -1271,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)
@@ -1295,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)
@@ -1307,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',
@@ -1738,6 +1739,8 @@ EXAMPLES:
         annotations: { title: 'Beat-Snapped Cuts', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
         description: `Cut on the music: analyse a track's beats (or take beat times you already have), fit a beat grid, and return cut points on every beat, every bar, or every N beats — optionally splitting a video or audio clip at each one.
 
+The song is the backbone of the edit: when the music is generated, cut the picture to its beats and bars and use the whole song. Do not trim the song to fit shots that were planned first.
+
 - source: the music — an upload id, URL, data: URL or local file path. Or beats: [seconds] to skip the analysis.
 - every: 'beat' (default) | 'bar' | N beats. beatsPerBar (default 4). range: [from, to] seconds.
 - bpm: the tempo, if you know it (the grid's phase is still fitted to the music). Otherwise the studio's detection and its usual confusions (double, half, 3:4, 4:3 …) are scored against the music and the best is used; bpmHint: [min, max] keeps the choice in a range. The result lists the candidates, and says lowConfidence with a warning when the tempo is uncertain — pass bpm then.
@@ -1805,6 +1808,12 @@ EXAMPLE: { checks: ["contrast", "flash"], duration: 6, fps: 20 }`,
         annotations: { title: 'Generate Image (cloud)', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
         description: `Generate images with an AI model in the PinePaper cloud, and optionally place the first one on the canvas. CHARGED per output — price it first with pinepaper_generate_estimate (free).
 
+PLAN FIRST; GENERATE ONLY WHAT THE EDIT USES. Every output is paid in full whether or not it is used, so generate-then-trim is waste:
+- Plan the whole timeline (shots, lengths, roles) before the first paid call, and price the whole plan with pinepaper_generate_estimate.
+- Reuse before generating: an image you already generated is referenced by its ref "/scene-assets/<id>".
+- Video: choose each shot's length from the lengths the model allows (listModels; Veo takes 4, 6 or 8 s) and re-time the edit to them. Do not generate long and crop.
+- Music: the song is the backbone. Its length only loosely follows the request, so cut the picture to its beats and bars with pinepaper_beat_cuts and use the whole song, rather than trimming it to fit the picture.
+
 Needs a service-account key in PINEPAPER_API_KEY (pp_sa_…, render:create scope). It is an internal beta enabled per organisation: without it the result says "not enabled for your organisation", and nothing is charged. Every refusal says whether anything was charged.
 
 - model or useCase: a model id from pinepaper_generate_estimate {listModels: true}, or a use case and the cloud picks its default (hero stills, plates, text in the image, character-consistent edits).
@@ -1847,7 +1856,7 @@ The result: assets [{assetId, ref, width, height}] — the sizes the files HAVE
     {
         name: 'pinepaper_generate_estimate',
         annotations: { title: 'Estimate Generation (free)', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-        description: `Free: price a pinepaper_generate call before making it, or list the models. { listModels: true } returns every model you may use with its price per output, use cases, licence notes and the defaults per use case; { model | useCase, input } returns the estimate for that request. Needs PINEPAPER_API_KEY, like pinepaper_generate.`,
+        description: `Free: price a pinepaper_generate call before making it, or list the models. Estimate the WHOLE plan (every asset the edit needs, at the lengths it will use) before generating any of it, not call by call. { listModels: true } returns every model you may use with its price per output, use cases, licence notes and the defaults per use case; { model | useCase, input } returns the estimate for that request. Needs PINEPAPER_API_KEY, like pinepaper_generate.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -2107,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: {
@@ -2135,6 +2144,13 @@ By default returns a cheap per-frame hash + byte size (token-light), plus unique
 
 Set includeDataUrls: true to also get each frame as a PNG data URL (large — only for a few frames).
 
+LOOK AT YOUR OWN FILM — sheet: one tiled image of many frames, saved to a file (filePath), plus a review rubric to score it against. Structure checks cannot see what a frame looks like; this can. Pick the frames with times (e.g. the music's beat times), or:
+- sheet.every + sheet.duration: one frame every N seconds.
+- sheet.strip {at, count?, step?}: consecutive frames around a moment (a transition, a stutter).
+- sheet.loopSeam + sheet.duration: the last frame beside the first.
+tileWidth defaults to 360 px, phone width: if a word cannot be read in its tile, it cannot be read on a phone. Then open the file, score review.criteria 1-10, and go through review.checklist.
+EXAMPLE: { sheet: { every: 1, duration: 15 } } → one ~15-tile JPEG.
+
 USE WHEN:
 - Verifying an animation is deterministic / reproducible
 - Checking whether a scene actually animates across a time range
@@ -2157,8 +2173,26 @@ EXAMPLE: { times: [0, 0.5, 1, 1.5, 2], seed: 42 }`,
                     type: 'boolean',
                     description: 'Include each frame as a PNG data URL (large). Default false → hashes only.',
                 },
+                sheet: {
+                    type: 'object',
+                    description: 'Return ONE tiled image saved to a file, plus a critique rubric, instead of per-frame hashes. times is then optional.',
+                    properties: {
+                        every: { type: 'number', description: 'One frame every N seconds from 0 to duration.' },
+                        duration: { type: 'number', description: 'Scene length in seconds (for every and loopSeam).' },
+                        strip: {
+                            type: 'object',
+                            properties: { at: { type: 'number' }, count: { type: 'integer', minimum: 2, maximum: 24 }, step: { type: 'number' } },
+                            required: ['at'],
+                            description: 'Consecutive frames around a moment: count (default 8), step seconds apart (default 1/30).',
+                        },
+                        loopSeam: { type: 'boolean', description: 'The last frame beside the first.' },
+                        tileWidth: { type: 'integer', minimum: 120, maximum: 1080, description: 'Tile width in px (default 360, phone width).' },
+                        columns: { type: 'integer', minimum: 1, maximum: 12 },
+                        format: { type: 'string', enum: ['jpeg', 'png'], description: 'Default jpeg (small).' },
+                        labels: { type: 'boolean', description: 'Stamp each tile with its time (default true).' },
+                    },
+                },
             },
-            required: ['times'],
         },
     },
     {
@@ -2181,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.
@@ -2194,11 +2228,15 @@ VIDEO EDITING:
 - apply_track_matte: { id, matteItemId, channel? (luma|alpha|red), invert?, strength?, hideMatte?, live? } — the matte item's pixels drive the target's alpha. The classic: a headline filled with footage. live: true keeps the cut tracking an ANIMATING matte (kinetic mask reveal); otherwise it bakes once, destructively (recorded in data.filterChain for round-trip).
 - stop_live_matte: { id } — stop a live matte, keep the last cut.
 
+MAKE ONE LIKE THIS — a reference video's FORMAT, never its content:
+- analyze_reference: { id, thumbnails? } — the uploaded reference clip (upload_video it first) → cuts (to the frame), shots (length, colours), pacing, beat, and card: the same facts as plain text. Read the card before planning.
+- remake_from_reference: { texts, duration?, clear? } — builds a new piece on the last analysed reference: one card per shot, cut at its cut times, in each shot's colours, the headline popping on its beats. texts are YOUR words, one per shot. Nothing of the footage, its words or its sound is copied; the reference clip stays in the project muted. One undo step.
+
 EXAMPLE: { action: 'upload_video', url: 'https://…/clip.mp4', scale: 0.5, timeOffset: 1 }`,
         inputSchema: {
             type: 'object',
             properties: {
-                action: { type: 'string', enum: ['upload_video', 'upload_audio', 'list', 'remove', 'set_playback_rate', 'set_clip', 'split', 'add_transition', 'set_time_remap', 'speed_ramp', 'match_cut', 'apply_track_matte', 'stop_live_matte'], description: "Media action" },
+                action: { type: 'string', enum: ['upload_video', 'upload_audio', 'list', 'remove', 'set_playback_rate', 'set_clip', 'split', 'add_transition', 'set_time_remap', 'speed_ramp', 'match_cut', 'apply_track_matte', 'stop_live_matte', 'analyze_reference', 'remake_from_reference'], description: "Media action" },
                 transition: { type: 'object', properties: { type: { type: 'string', enum: ['crossfade', 'dip'] }, seconds: { type: 'number', exclusiveMinimum: 0, maximum: 10 }, color: { type: 'string' } }, description: "add_transition: { type ('crossfade' default | 'dip'), seconds, color (dip) }." },
                 atPlayhead: { type: 'boolean', description: 'upload_video / upload_audio: start at the current playback time (instead of timeOffset).' },
                 remapTrack: { type: 'array', items: { type: 'object', properties: { time: { type: 'number' }, value: { type: 'number' }, easing: { type: 'string' } }, required: ['time', 'value'] }, description: 'set_time_remap: canvas-seconds → source-seconds curve (≥2 points). null clears the remap.' },
@@ -2218,7 +2256,11 @@ EXAMPLE: { action: 'upload_video', url: 'https://…/clip.mp4', scale: 0.5, time
                 hideMatte: { type: 'boolean', description: 'apply_track_matte: hide the matte item after applying.' },
                 live: { type: 'boolean', description: 'apply_track_matte: keep re-cutting as the matte moves/animates — the kinetic mask reveal. Omitted = bake once, destructively.' },
                 url: { type: 'string', description: "Required for upload_video / upload_audio: an http(s) URL, a data: URL, or a PATH TO A LOCAL FILE. Remote URLs and local files are fetched/read by the server (the page may not fetch third-party hosts), so stock music and SFX links work; the HTTP status or content-type is named if one does not. Up to 48 MB." },
-                id: { type: 'string', description: 'Media id — required for remove / set_playback_rate / set_clip.' },
+                id: { type: 'string', description: 'Media id — required for remove / set_playback_rate / set_clip / analyze_reference.' },
+                texts: { type: 'array', items: { type: 'string' }, description: 'remake_from_reference: your words, one per shot of the reference.' },
+                duration: { type: 'number', description: 'remake_from_reference: total seconds (default the reference\'s own).' },
+                clear: { type: 'boolean', description: 'remake_from_reference: empty the canvas first (media survives).' },
+                thumbnails: { type: 'boolean', description: 'analyze_reference: include a small image per shot (default false; token-heavy).' },
                 rate: { type: 'number', description: 'Playback rate 0.25–4 — set_playback_rate.' },
                 inPoint: { type: 'number', description: 'Clip in-point (media-time s) — set_clip.' },
                 outPoint: { type: 'number', description: 'Clip out-point (media-time s, > inPoint) — set_clip.' },
@@ -2250,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
@@ -2271,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.' },
@@ -2309,13 +2355,15 @@ 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 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 4 thread stitches with their params.
+- list_stitches: the thread stitches with their params.
 - apply_thread: render an item in thread. Its own silhouette is the region and its own fill is the thread colour, so an existing drawing becomes stitched rather than needing to be redrawn. The source is HIDDEN, not destroyed.
 - apply_hatch: rule an item with hatching. Same deal — silhouette is the region, source is hidden, re-hatching replaces.
 - list_flow_fields: the 7 fields that bend a hatch line.
 - list_hatch_options: the hatch defaults.
+- 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.
 
@@ -2341,11 +2389,17 @@ 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'], description: 'Medium operation' },
-                medium: { type: 'string', description: 'resolve: vector | thread | ink | watercolor | hatch | cutPaper | charcoal | oil | encaustic. Six are native (vector, thread, ink, watercolor, hatch, cutPaper), two stylised, one absent — call list_media for the live table rather than trusting this line.' },
-                itemId: { type: 'string', description: 'apply_thread / apply_hatch: a closed path, compound path, or a group of them.' },
+                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." },
+                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." },
                 stitchLen: { type: 'number', description: 'apply_thread: nominal stitch length px (default 18).' },
                 rowGap: { type: 'number', description: 'apply_thread: row spacing px; defaults from thread width so rows abut.' },
                 variance: { type: 'number', description: 'apply_thread: length jitter 0..1 (default 0.35) — the long-and-short shading.' },
@@ -2384,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.
@@ -2538,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.`,
@@ -2594,6 +2649,13 @@ RECIPE — a playable maze: create_tilemap with wall fills → batch_create colo
     },
     {
         name: 'pinepaper_design_system',
+        annotations: {
+            title: 'Design System',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: `The design vocabulary, as data you can read — and eighteen styles that can build a scene.
 
 TWO DIFFERENT THINGS, kept apart on purpose:
@@ -2619,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.' },
@@ -2630,13 +2692,20 @@ A partial composition reports as a failure with the elements that did not create
     },
     {
         name: 'pinepaper_stick',
+        annotations: {
+            title: 'Stick Figure Kit',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: `The vendored stick-figure kit — a rigged figure posed, walking, travelling, holding a prop, with a garment and hair, plus the set it stands on and among.
 
 A different construction from pinepaper_character, which places a figure from the DESIGN GRAPH by concept ("pp:Pigeon"). This is the stick kit specifically.
 
 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: {
@@ -2644,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." },
@@ -2695,6 +2764,13 @@ The geometry is vendored from mcp-cloud, which makes this a three-repo artifact:
     },
     {
         name: 'pinepaper_story',
+        annotations: {
+            title: 'Story to Scene',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: `A piece of prose becomes a scene.
 
 - distill: reduce an article to its story beats and draw NOTHING. This is the half worth having on its own — a caller can read what the distiller made of the text, edit the beats, and only then assemble. Discovering the reading by looking at a finished scene is the expensive way round.
@@ -2715,17 +2791,36 @@ The geometry is vendored from mcp-cloud, which makes this a three-repo artifact:
     },
     {
         name: 'pinepaper_interchange',
+        annotations: {
+            title: 'Interchange Formats',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: `The formats other tools read and write — Lottie, dotLottie, GLB, BVH, PNG sequence.
 
 pinepaper_agent_export covers the PLATFORM formats: png, svg, mp4, webm, gif, pdf, sized for Instagram or YouTube. These are the interchange ones — a Lottie an app plays, a GLB a 3D tool opens, a BVH a rig imports, a PNG sequence an editor ingests. Import is here too, because a format you can only write is half a bridge.
 
-Three of these refuse quietly in the engine: exportGLB with no perspective objects and exportBVH with no rigging system both warn to the console and return nothing, and the production build strips the console. Over MCP there is no console to read, so the precondition is checked BEFORE the call and named — "no perspective objects to export — create one with createObject3D first" rather than an empty result and a guess.`,
+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'],
@@ -2733,6 +2828,13 @@ Three of these refuse quietly in the engine: exportGLB with no perspective objec
     },
     {
         name: 'pinepaper_sound',
+        annotations: {
+            title: 'Sound Synthesis & Soundtrack',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: `Synthesis — and the drawing that is the same object.
 
 The engine carries a full audio graph, and none of it was reachable. pinepaper_audio_beats ANALYSES audio that already exists; this MAKES audio.
@@ -2752,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',
@@ -2786,10 +2918,17 @@ render_soundtrack mixes every placed sound to a WAV and writes it to a file. It
     },
     {
         name: 'pinepaper_motion',
+        annotations: {
+            title: 'Group & Field Motion',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         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.
@@ -2817,6 +2956,13 @@ This is not pinepaper_animate: that applies a loop preset to ONE item. This move
     },
     {
         name: 'pinepaper_path',
+        annotations: {
+            title: 'Path Operations',
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: `Destructive path operations — the ones that REPLACE or ADD items rather than restyling them.
 
 - boolean: unite | subtract | intersect | exclude | divide. CONSUMES its operands and leaves one result, so the input ids stop existing. The first id is the base; the rest apply to it in order.
@@ -2863,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',
@@ -2879,7 +3065,7 @@ RECIPE — a character walking through a forest: create {spec:'forest'} → impo
                     anyOf: [{ type: 'boolean' }, { type: 'object' }],
                     description: 'create: include the walkable character (boolean or config).',
                 },
-                patch: { type: 'object', description: 'configure: partial world spec, validated against describe.' },
+                patch: { type: 'object', description: 'configure: partial world spec, validated against describe. Colours (env.zenith, env.horizon, env.fogColor, env.sunColor, env.ambient, env.lowColor … env.propColorB) take hex ("#03050c") or [r, g, b] in 0..1.' },
                 actorId: { type: 'string', description: 'Actor id.' },
                 x: { type: 'number', description: 'add_actor: world x.' },
                 z: { type: 'number', description: 'add_actor: world z.' },
@@ -2890,18 +3076,18 @@ RECIPE — a character walking through a forest: create {spec:'forest'} → impo
                 camera: { type: 'object', description: "set_camera: { mode: follow|fixed|orbit, target?, radius?, speed?, eye?, lookAt? }." },
                 object: { type: 'object', description: 'add_object: { x, z, height?, color?, y? }. metalness/roughness are accepted and IGNORED here — a plain object is drawn by the prop shader, which declares no such uniform. They render on the mesh path only.' },
                 pathId: { type: 'string', description: 'extrude_path / lathe_path: the canvas path to turn into geometry. The path itself is unchanged.' },
-                mesh: { type: 'object', description: 'extrude_path / lathe_path options: { id?, depth?, unitsPerPixel?, caps?, segments?, arc?, flatness?, x?, y?, z?, rotY?, rotYDegrees?, scale?, doubleSided?, color?, metalness?, roughness? }. color is hex or [r,g,b] (default light grey — without it the mesh rendered black); it becomes the shader\'s diffuse uniform. arc is DEGREES; rotY is RADIANS (fed straight to cos/sin in the shader) — pass rotYDegrees to write degrees. These names are the ones the engine records as the mesh provenance, so a captured meshProvenance.opts spreads straight back in.' },
+                mesh: { type: 'object', description: 'extrude_path / lathe_path options: { id?, depth? (WORLD units, default 1), unitsPerPixel? (canvas px → world units, default 0.01), upright? (extrude: stand the drawing up, extruded along Z; default flat, a floor plan extruded along Y), placement? (extrude: \'centered\' default: centred on x/z, base at y; \'canvas\': the outline\'s canvas position), caps?, segments?, arc?, flatness?, x?, y?, z?, rotY?, rotYDegrees?, scale?, doubleSided?, color?, metalness?, roughness? }. color is hex or [r,g,b] (default light grey — without it the mesh rendered black); it becomes the shader\'s diffuse uniform. arc is DEGREES; rotY is RADIANS (fed straight to cos/sin in the shader) — pass rotYDegrees to write degrees. These names are the ones the engine records as the mesh provenance, so a captured meshProvenance.opts spreads straight back in.' },
                 meshId: { type: 'string', description: 'remove_mesh: the mesh id.' },
-                light: { type: 'object', description: 'add_light / set_light: { id?, x?, y?, z?, color?, intensity?, range? }. At most 8 point lights; the ninth is refused by name because the shader array is fixed-size.' },
+                light: { type: 'object', description: 'add_light / set_light: { id?, x?, y?, z?, color? (hex or linear [r, g, b], may exceed 1), intensity?, range? }. At most 8 point lights; the ninth is refused by name because the shader array is fixed-size.' },
                 lightId: { type: 'string', description: 'set_light / remove_light: the light id.' },
-                material: { type: 'object', description: 'add_material / set_material: { id?, color?, emissive?, metalness?, roughness?, emissiveIntensity?, clearcoat?, clearcoatRoughness?, sheenColor?, sheenRoughness? }. A shared surface — one edit restyles every object using it. metalness/roughness render on the mesh path only.' },
+                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).' },
                 navTarget: { type: 'string', enum: ['2d', '3d'], description: "set_nav_target: which layer the pointer drives." },
-                point: { type: 'object', description: 'ground_height / canvas_to_ground / world_to_canvas: { x, y, z? }.' },
+                point: { type: 'object', description: 'ground_height: { x, z } in WORLD coordinates (y is read as z if z is absent). canvas_to_ground: { x, y } in canvas pixels. world_to_canvas: { x, y, z? } in world coordinates.' },
                 origin: { type: 'array', items: { type: 'number' }, description: 'raycast: ray origin [x, y, z].' },
                 direction: { type: 'array', items: { type: 'number' }, description: 'raycast: ray direction [x, y, z], need not be normalised.' },
                 multiplier: { type: 'number', description: 'dolly_camera: >1 away, <1 closer.' },
@@ -2924,7 +3110,9 @@ RECIPE — a character walking through a forest: create {spec:'forest'} → impo
         annotations: {
             title: 'Character (place and direct a figure from the graph)',
             readOnlyHint: false,
+            destructiveHint: false,
             idempotentHint: false,
+            openWorldHint: false,
         },
         description: `Place a CHARACTER from the design graph and DIRECT it — no geometry, no bones, no poses.
 
@@ -2935,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.
@@ -3023,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:
@@ -3038,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: {
@@ -3138,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',
@@ -3316,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',
@@ -3407,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)
@@ -3472,7 +3668,7 @@ applyFunction: \`
         annotations: {
             title: 'Execute Custom Code',
             readOnlyHint: false,
-            destructiveHint: false,
+            destructiveHint: true,
             idempotentHint: false,
             openWorldHint: true,
         },
@@ -3646,12 +3842,9 @@ The authoritative list for a given item is pinepaper_get_animatable_properties
 
 EASING — IT SHAPES THE SEGMENT ARRIVING AT THE KEYFRAME IT IS ON.
 The move from keyframe A to keyframe B is eased by B's easing, not A's. Easing on the FIRST keyframe does nothing (no segment arrives at it) — a Ken Burns with easing only on its first key plays linear. Put the easing on the key you are moving TO.
-- linear: Constant speed
-- easeIn: Slow start
-- easeOut: Slow end
-- easeInOut: Slow start and end
-- bounce: Bounce effect
-- elastic: Elastic overshoot
+${EASING_LINES}
+- or a custom cubic-bezier [x1, y1, x2, y2] — x in 0..1, y may exceed 0..1 for overshoot. keyframe_animate and camera_animate only.
+Every easing renders exactly in video, GIF and APNG. Lottie and CSS get the closest single Bézier: springPlayful loses its wobble, and the in-out quart/quint/expo/circ curves are within 2–4 %. SMIL is exact for springs and those four.
 
 CLIP WINDOW (optional — Premiere/Canva-style clip behavior):
 - timeOffset: Shift the whole clip in canvas time (seconds). The animation only runs while canvas time is in [timeOffset, timeOffset + (clipOutPoint - clipInPoint)].
@@ -3679,9 +3872,8 @@ EXAMPLE — Reveal at 2s, skip first second of keyframe data, end at 4s of keyfr
                                 additionalProperties: true,
                             },
                             easing: {
-                                type: 'string',
-                                enum: ['linear', 'easeIn', 'easeOut', 'easeInOut', 'bounce', 'elastic'],
-                                description: 'Shapes the segment ARRIVING at this keyframe (from the previous one). Ignored on the first keyframe.',
+                                ...KEYFRAME_EASING_JSON_SCHEMA,
+                                description: 'Shapes the segment ARRIVING at this keyframe (from the previous one). Ignored on the first keyframe. A name, or a custom cubic-bezier [x1, y1, x2, y2] — x in 0..1, y may exceed 0..1 for overshoot.',
                             },
                         },
                         required: ['time', 'properties'],
@@ -3732,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.
@@ -3849,7 +4043,7 @@ MASK TYPES: rectangle, circle, ellipse, star, triangle, hexagon, heart, rounded`
                         properties: {
                             time: { type: 'number', description: 'Normalized time (0-1)' },
                             properties: { type: 'object', description: 'Mask properties (x, y, width, height, radius, scale, rotation, opacity)' },
-                            easing: { type: 'string', enum: ['linear', 'easeIn', 'easeOut', 'easeInOut', 'bounce', 'elastic'] },
+                            easing: { type: 'string', enum: [...KEYFRAME_EASINGS] },
                         },
                         required: ['time', 'properties'],
                     },
@@ -3860,7 +4054,7 @@ MASK TYPES: rectangle, circle, ellipse, star, triangle, hexagon, heart, rounded`
                     properties: {
                         startTime: { type: 'number', description: 'Start time in seconds', default: 0 },
                         duration: { type: 'number', description: 'Duration in seconds', default: 0.8 },
-                        easing: { type: 'string', enum: ['linear', 'easeIn', 'easeOut', 'easeInOut', 'bounce'], default: 'easeOut' },
+                        easing: { type: 'string', enum: [...KEYFRAME_EASINGS], default: 'easeOut' },
                         reversed: { type: 'boolean', description: 'Reverse animation (hide instead of reveal)', default: false },
                         loop: { type: 'boolean', description: 'Loop the animation', default: false },
                     },
@@ -3977,7 +4171,7 @@ Needs a studio that publishes the item-side table; without one, the tool says so
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: `[Utility] Get list of available easing functions for mask animations.`,
+        description: `[Utility] List the easing names the studio accepts: one table serves keyframes, masks, relations and the camera. Reads the live engine's list when it reports one.`,
         inputSchema: {
             type: 'object',
             properties: {},
@@ -4101,8 +4295,8 @@ EXAMPLE (curved arc between waypoints):
                             pitch: { type: 'number', description: '3D tilt in degrees — rendered where the studio supports camera tilt (result.tiltRenders).' },
                             yaw: { type: 'number', description: '3D rotation in degrees — rendered where the studio supports camera tilt (result.tiltRenders).' },
                             easing: {
-                                type: 'string',
-                                enum: ['linear', 'easeIn', 'easeOut', 'easeInOut', 'bounce', 'elastic'],
+                                ...KEYFRAME_EASING_JSON_SCHEMA,
+                                description: 'A name, or a custom cubic-bezier [x1, y1, x2, y2] — x in 0..1, y may exceed 0..1 for overshoot.',
                             },
                             pathOut: {
                                 type: 'array',
@@ -4958,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' },
@@ -4966,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'],
         },
@@ -4974,7 +5177,7 @@ flags as a badly-composed scene, and they do not survive an artboard change.`,
         name: 'pinepaper_brand_kit',
         annotations: {
             title: 'Brand Kit', readOnlyHint: false, destructiveHint: false,
-            idempotentHint: true, openWorldHint: false,
+            idempotentHint: true, openWorldHint: true,
         },
         description: `Apply a brand kit — colours, fonts and roles — across the scene.
 
@@ -4982,6 +5185,7 @@ ACTIONS:
 - plan: Report what WOULD change (count, per-role breakdown, WCAG contrast audit) WITHOUT touching
   the canvas. Call this first on an unfamiliar scene; a whole-scene recolour is hard to eyeball afterwards.
 - apply: Commit it. A history snapshot is taken FIRST, so one undo puts everything back.
+- from_url: { url, screenshots? } — read the product's REAL brand from its own site before animating anything: screenshots down the page, the logo (header image or SVG, else the site icon), and a proposed kit from the colours and fonts the site's CSS computes (buttons and links weigh most). Saved to files; the result lists them. Read in an isolated browser context: the studio is not touched. Review the kit against the screenshots, then plan / apply it. Use the brand you are given, never an invented one.
 
 KIT SHAPE — only name and colors.primary are required:
   { "name": "Acme", "colors": { "primary": "#e11d48", "secondary": "#0ea5e9",
@@ -4996,7 +5200,9 @@ Both actions return a WCAG contrast audit, so you can see failing pairs before s
         inputSchema: {
             type: 'object',
             properties: {
-                action: { type: 'string', enum: ['plan', 'apply'], description: 'plan (dry run) or apply' },
+                action: { type: 'string', enum: ['plan', 'apply', 'from_url'], description: 'plan (dry run), apply, or from_url (read a site into a proposed kit)' },
+                url: { type: 'string', description: "from_url: the product's site, http(s)." },
+                screenshots: { type: 'integer', minimum: 1, maximum: 6, description: 'from_url: screenshots down the page (default 3).' },
                 kit: {
                     type: 'object',
                     description: 'Brand kit. Requires name and colors.primary; other roles are inferred.',
@@ -5022,7 +5228,7 @@ Both actions return a WCAG contrast audit, so you can see failing pairs before s
                 },
                 selectionOnly: { type: 'boolean', description: 'Restrict to current selection' },
             },
-            required: ['action', 'kit'],
+            required: ['action'],
         },
     },
     {
@@ -5149,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' },
             },
@@ -5541,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
@@ -5738,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: {
@@ -5853,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: {
@@ -6034,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',
@@ -6131,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',
@@ -6572,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: {
@@ -6588,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)' },
@@ -6611,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: {
@@ -6654,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' },
             },
@@ -6685,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 }`,
@@ -6694,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' },
@@ -7031,7 +7246,7 @@ EXAMPLES:
         annotations: {
             title: 'Execute Generator',
             readOnlyHint: false,
-            destructiveHint: false,
+            destructiveHint: true,
             idempotentHint: false,
             openWorldHint: false,
         },
@@ -7053,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)
@@ -7197,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)
@@ -7267,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: {
@@ -7295,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: {
@@ -7448,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: {
@@ -7725,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: {
@@ -7872,7 +8253,7 @@ EXAMPLES:
         annotations: {
             title: 'Build Scene — Items, Animations, Effects in One Call',
             readOnlyHint: false,
-            destructiveHint: false,
+            destructiveHint: true,
             idempotentHint: false,
             openWorldHint: false,
         },
@@ -7890,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}
@@ -7942,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"},
@@ -7986,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' },
@@ -7998,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}' },
@@ -8022,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' },
@@ -8037,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' },
@@ -8112,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,
@@ -8141,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).
 
@@ -8164,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',
@@ -8195,6 +8578,14 @@ VERIFY MOTION BEFORE YOU RENDER. An export takes seconds to minutes and shows yo
                 broadcast: { type: 'boolean', description: 'mp4 only: broadcast-safe — BT.709, limited range (16-235), tagged bt709, constant bitrate with an 8 Mbps floor at 720p+ (4 below). result.video reports what the encoder did.' },
                 frames: { type: 'integer', minimum: 1, maximum: 36000, description: 'Animated formats: exactly this many frames instead of duration. A duration makes ceil(duration x fps) frames (7.91667 s at 24 fps is 191, not 190), so use frames for frame-exact segments.' },
                 deterministic: { type: 'boolean', description: 'mp4 / webm: byte-identical files for the same scene (pins the container timestamps), so exports can be checksummed or cached by hash.' },
+                motionBlur: {
+                    type: 'object',
+                    description: 'mp4 / webm: real motion blur. Each frame is rendered `subframes` times across the shutter and averaged, so fast movement smears instead of strobing. Costs subframes× the render time: run estimateOnly first (it reports renders and renderCost). The result carries motionBlur (what the exporter applied).',
+                    properties: {
+                        subframes: { type: 'integer', minimum: 1, maximum: 32, description: 'Renders per frame (default 8; 1 = no blur).' },
+                        shutter: { type: 'number', minimum: 0, maximum: 1, description: 'Fraction of the frame interval the shutter is open (default 0.5).' },
+                    },
+                },
                 broadcastHeadroom: { type: 'integer', minimum: 0, maximum: 40, description: 'mp4 with broadcast only, default 12: luma codes kept clear at both ends, so encoder ringing stays legal (12 measured clean on hard edges; 4 = ~100x fewer out-of-range samples, 12 = ~1000x; never zero). Fidelity raises luma_out_of_range with the legaliser command when any remain.' },
                 bitrate: { type: 'integer', minimum: 100000, maximum: 200000000, description: 'mp4 / webm: target bits/s, replacing the quality-derived one. The browser encoder treats it as a CEILING; result.video.achievedBitrate is what it produced.' },
                 minBitrate: { type: 'integer', minimum: 100000, maximum: 200000000, description: 'mp4 / webm: a floor; a miss is a fidelity warning naming the re-encode a delivery spec needs.' },
@@ -8572,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
@@ -8757,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
@@ -8988,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: {