@pinepaper.studio/mcp-server 1.6.6 → 1.6.8

package/dist/types/schemas.js

@@ -98,6 +98,44 @@ export const ItemTypeSchema = z.enum([
     'diamond',
     'arrow',
     'heart',
+    // THE REST OF THE ENGINE'S SHAPE REGISTRY — same argument as the two below,
+    // applied to shapes that were already being drawn.
+    //
+    // js/shapes/index.js registers 34 shapes across five modules. Flowchart, UML
+    // and network route through pinepaper_create_diagram_shape, so 23 were
+    // reachable. These eleven were reachable from NOTHING: three basic shapes,
+    // and the whole `comment` module — every speech bubble, thought bubble and
+    // callout the engine can draw.
+    //
+    // The engine was never the limit. PinePaper.create() delegates any registry
+    // type — "basic shapes, comment/bubble shapes, etc." in its own comment —
+    // and already forwards `tailDirection` and `tailSize`, which exist only for
+    // bubbles. It has been able to draw a speech bubble the whole time; no tool
+    // could name one, so an agent asked for a comic panel or an annotated
+    // diagram had to hand-build the outline or decline.
+    'disk',
+    'circle-outline',
+    'arrow-right',
+    'speech-bubble',
+    'speech-bubble-square',
+    'speech-bubble-pointed',
+    'thought-bubble',
+    'double-bubble',
+    'quote-bubble',
+    'comment-box',
+    'callout-box',
+    // RENDER-TIME SURFACES. These two are not Paper items and never enter the
+    // scene tree: they are drawn per pixel by the cloud rasterizer, straight from
+    // the scene document. They are here because a capability nobody can name is a
+    // capability nobody has — the cloud has drawn shaders and fields for months
+    // and no tool has ever offered them, so the only way to reach one was to
+    // hand-write a scene file.
+    //
+    // In the browser they degrade to a flat plate of their own colour (see
+    // generateCreateItemCode) so a composition built with one still reads
+    // locally; the shaded surface appears in a cloud render.
+    'shader',
+    'field',
 ]);
 // Text item properties
 export const TextPropertiesSchema = z.object({
@@ -182,14 +220,32 @@ export const ArcPropertiesSchema = z.object({
 // =============================================================================
 // ANIMATION TYPES
 // =============================================================================
+// The loop animations the engine's driver can actually run.
+//
+// Pinned to the engine by animation-type-parity.test.ts. It offered 'slide',
+// which has NEVER existed — the real ones are slideLeftRight and slideUpDown.
+// The engine stored the unknown value and the driver's switch fell through, so
+// the item sat still while its data claimed a slide, and nothing anywhere said
+// so. It also hid twelve types that do work.
 export const SimpleAnimationTypeSchema = z.enum([
-    'pulse',
-    'rotate',
     'bounce',
+    'breathe',
     'fade',
-    'wobble',
-    'slide',
+    'glow',
+    'jelly',
+    'path',
+    'pulse',
+    'rotate',
+    'scrollDown',
+    'scrollLeft',
+    'scrollRight',
+    'scrollUp',
+    'shake',
+    'slideLeftRight',
+    'slideUpDown',
+    'swing',
     'typewriter',
+    'wobble',
 ]).describe('Simple loop animation type');
 // Keyframe schema
 export const KeyframeSchema = z.object({
@@ -200,7 +256,21 @@ export const KeyframeSchema = z.object({
 // =============================================================================
 // RELATION TYPES
 // =============================================================================
+// The relation vocabulary the engine can actually run.
+//
+// Held in step with the engine by relation-parity.test.ts, against a fixture of
+// the registry's own map. This list is a hard gate: a name missing from it is
+// REJECTED at validation, so for 95 live relations the engine could do it and
+// no agent could name it — and for a model those are the same condition. The
+// whole interactive vocabulary sat on the wrong side of that line.
+//
+// Relations a dedicated tool emits (deform_*, effect_*, geo_*, bone_*, …) are
+// deliberately absent: the agent authors those THROUGH that tool, and a second
+// name here would be a worse way to do the same thing. The test file holds that
+// exclusion list, with the reason.
+/** Engine parity ENFORCED BY src/__tests__/unit/relation-parity.test.ts (fixture: engine-relations.txt). */
 export const RelationTypeSchema = z.enum([
+    // --- Motion, spatial and transform ---
     'orbits',
     'follows',
     'attached_to',
@@ -209,61 +279,100 @@ export const RelationTypeSchema = z.enum([
     'mirrors',
     'parallax',
     'bounds_to',
+    'anchored_in_world',
+    'spring_follow',
+    'repels',
+    'attracts',
+    'wiggle',
+    // --- Animation and sequencing ---
     'animates',
-    // Manim-inspired animation relations
     'grows_from',
     'staggered_with',
     'indicates',
     'circumscribes',
     'wave_through',
-    'camera_follows',
-    'camera_animates',
     'morphs_to',
-    // Pair-by-index group morph; same call shape works for any two paper.Groups
     'group_morphs_to',
-    // Self-relation; item moves along a custom-drawn path stored in params
     'moves_along_path',
-    // Geometric construction constraints (Layer 2) — the source is RE-DERIVED each
-    // frame from its anchor item(s), so dragging an anchor updates it live
-    // (GeoGebra-style). Anchor A is the relation target; extra anchors ride in params.
-    'is_midpoint_of', // source = midpoint(target, params.other)
-    'lies_on_line', // source on line target→params.other at fraction params.t
-    'is_centroid_of', // source = centroid(target, ...params.others)
-    'is_circumcenter_of', // source = circumcenter(target, params.other1, params.other2)
-    'concentric_with', // source shares the target's center
-    'construction_reveal', // self-relation: opacity 0→1 at params.revealAt over params.fadeIn (timeline-driven)
-    // Procedural / deterministic property binding (Expression IR — FxTool S10 G1).
-    // params.signal:true routes through the pure, seed/frame-deterministic signal
-    // interpreter (replay-stable), else the per-frame compute fallback runs.
-    'driven_by', // source property = target property * multiplier + offset (+clamp); drives color/stroke/opacity/scale/pos. Needs a target.
-    'time_expression', // self-relation: source property driven by a math expression f(t, v) — t=time, v=params.baseValue
-    // Event-driven scene chains (FxTool S11). The source is a pp:event (make one
-    // with pinepaper_event); firing it runs these reactions. on_event_fire_after
-    // chains events over canvas/wall time; on_event_add_relation mutates the graph
-    // (the scene evolves itself). Kick a chain off with pinepaper_event pulse.
-    'on_event_fire_after', // event→event: when source fires, pulse target after params.delay (timeline: wall|canvas)
-    'on_event_add_relation', // event→item: add params.type relation from item to params.target when the event fires
-    'on_event_remove_relation', // event→item: remove params.type relation from item to params.target
-    'on_event_set_color', // event→item: set fill/stroke to params.color
-    'on_event_set_property', // event→item: set item[params.property] = params.value
-    'on_event_set_visibility', // event→item: show/hide (params.visible, default true)
-    // Structural layout relations (FxTool S12-E1) — STATIC composition as graph edges.
-    // Placement is derived from the TARGET'S BOUNDS and re-derived each frame, so
-    // dragging or resizing the target moves the dependent live. Use these instead of
-    // hardcoding x/y when the intent is "on", "under", "next to", "inside".
-    'on_top_of', // source bottom edge rests on target top edge (params: gap, align, overhang)
-    'below', // source top edge rests on target bottom edge (params: gap, align, overhang)
-    'beside', // source flanks the target left/right (params: side, gap, align)
-    'inside', // source anchored inside the target's bounds (params: anchor, padding)
-    'centered_on', // source center = target center + (offsetX, offsetY)
-    'aligned_with', // source matches target on ONE axis only — the other stays free (params: axis, offset)
+    'construction_reveal',
+    'triggers_animation',
+    'syncs_with',
+    'tours',
+    'synced_to_audio',
+    'expresses',
+    // --- Camera ---
+    'camera_follows',
+    'camera_animates',
+    // --- Geometry ---
+    'is_midpoint_of',
+    'lies_on_line',
+    'is_centroid_of',
+    'is_circumcenter_of',
+    'concentric_with',
+    // --- Procedural / expression ---
+    'driven_by',
+    'time_expression',
+    // --- Input triggers — a user action FIRES an event channel ---
+    'on_click_fire',
+    'on_pointer_enter_fire',
+    'on_pointer_exit_fire',
+    'on_key_fire',
+    // --- Event reactions — an event fires and something happens ---
+    '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',
+    // --- Proximity — the pointer entering or leaving an item ---
+    '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 state — at most one member active ---
+    'exclusive_group',
+    'menubar_group',
+    'restores_from',
+    // --- Structural and diagram ---
+    'on_top_of',
+    'below',
+    'beside',
+    'inside',
+    'centered_on',
+    'aligned_with',
+    'part_of',
+    'connects_to',
+    'attached_to_tail',
+    'head_points_to',
 ]).describe('Type of relationship between items');
 // Relation parameter schemas
 export const OrbitsParamsSchema = z.object({
     radius: z.number().optional().default(100).describe('Orbit radius'),
     speed: z.number().optional().default(1).describe('Rotation speed'),
     direction: z.enum(['clockwise', 'counterclockwise']).optional().default('counterclockwise'),
-    phase: z.number().optional().default(0).describe('Starting angle offset'),
+    // The one angle in the relation vocabulary that is NOT degrees. Kept because
+    // changing it outright would silently re-time every scene that sets it — a 57x
+    // error of exactly the kind the "angles are DEGREES" convention exists to stop.
+    phase: z.number().optional().default(0).describe('Starting angle in RADIANS — the documented exception to the degrees convention, kept for existing scenes. Prefer phaseDegrees.'),
+    phaseDegrees: z.number().optional().describe('Starting angle in DEGREES, matching the convention every other angle uses. Takes precedence over phase when set.'),
 });
 export const FollowsParamsSchema = z.object({
     offset: PointArraySchema.optional().default([0, 0]).describe('Position offset from target'),
@@ -308,8 +417,19 @@ export const GrowsFromParamsSchema = z.object({
 });
 export const StaggeredWithParamsSchema = z.object({
     index: z.number().describe('0-based position in the stagger sequence'),
-    stagger: z.number().optional().default(0.1).describe('Delay between items in seconds'),
-    effect: z.enum(['fadeIn', 'fadeOut', 'growIn', 'slideIn', 'popIn']).optional().default('fadeIn').describe('Stagger effect type'),
+    stagger: z.number().optional().default(0.1).describe('Seconds between neighbours. Ignored when amount is set.'),
+    // Shape params (pp:Stagger). The plain index x stagger path is taken first and
+    // unchanged; these only engage when a shape is actually asked for AND count is
+    // known — there is no "end" to measure from without it, so an origin like
+    // 'center' would have nothing to mean.
+    count: z.number().optional().describe('How many items are in the stagger. Required by any origin other than "start".'),
+    from: z.enum(['start', 'end', 'center', 'edges', 'random']).optional().default('start').describe('Where the stagger begins — what turns a delay into a direction. Requires count.'),
+    amount: z.number().optional().describe('Total seconds for the WHOLE sequence, split among the items. Overrides stagger.'),
+    grid: z.string().optional().describe('Rows and columns as "rows,cols" (or "auto") for a 2D stagger. Requires count.'),
+    axis: z.enum(['x', 'y']).optional().describe('Restrict a grid stagger to one axis.'),
+    distributeEase: z.enum(['linear', 'easeIn', 'easeOut', 'easeInOut', 'easeInCubic', 'easeOutCubic']).optional().default('linear')
+        .describe("Curve that distributes the START TIMES — not the items' own animation curve."),
+    effect: z.enum(['fadeIn', 'fadeOut', 'growIn', 'slideIn', 'popIn', 'typewriter']).optional().default('fadeIn').describe('Stagger effect type'),
 });
 export const IndicatesParamsSchema = z.object({
     scale: z.number().optional().default(1.3).describe('Max scale during indication'),
@@ -448,6 +568,13 @@ export const MovesAlongPathParamsSchema = z.object({
 // || opts) — so they must survive validation.
 export const EquationPathInputSchema = z.object({
     ...equationSpecShape,
+    solveOde: z.object({
+        equations: z.union([z.string(), z.array(z.string())]).describe("The derivative(s), as expressions — e.g. 'y' for dy/dt = y, or ['v', '-9.8'] for a falling body."),
+        initialState: z.array(z.number()).describe('The state at t = 0, one number per equation.'),
+        tEnd: z.number().optional().describe('How far to integrate (default 10).'),
+        dt: z.number().optional().describe('Step size (default 0.01). Smaller is more accurate and slower.'),
+        method: z.enum(['rk4', 'euler']).optional().describe("Integrator (default 'rk4' — fourth-order Runge-Kutta). 'euler' is faster and visibly wrong on anything stiff."),
+    }).optional().describe('Numerically integrate an ODE instead of plotting a closed-form expression, and return the SOLUTION rather than drawing it. The trajectory comes back as data, so a caller can inspect it, feed it to a path, or drive keyframes with it.'),
     x: z.number().optional().describe('Canvas origin x (default: canvas center)'),
     y: z.number().optional().describe('Canvas origin y (default: canvas center)'),
     style: z.record(z.unknown()).optional().describe('Path style forwarded to create (strokeColor, strokeWidth, fillColor, …)'),
@@ -471,12 +598,22 @@ export const DrivenByParamsSchema = z.object({
 // time_expression: self-relation (targetId=null). The source's `property` is
 // driven by a math expression of t (scene time) and v (baseValue). signal:true
 // parses the expression into the Expression IR and evaluates a pure f(t)
-// (replay-stable), falling back to per-frame if it uses random()/unknown symbols.
+// (replay-stable).
+//
+// THERE IS NO LONGER A PER-FRAME FALLBACK FOR random(). The engine used to
+// build a `new Function` from the scene's own text on the per-frame path, which
+// made the authoring language JavaScript rather than the grammar the other
+// renderers speak — `^` was bitwise XOR there and exponentiation everywhere
+// else, so one scene string drew two different pictures, and `random()` could
+// not be refused, so a scene could never be baked or exported deterministically.
+// Both paths now go through the same parser, `random` is rejected by name, and
+// `^` is exponentiation. This comment said "falls back to per-frame" until
+// 2026-09-15; it described behaviour the engine had removed.
 export const TimeExpressionParamsSchema = z.object({
     property: z.string().optional().default('y').describe('Property to drive: x, y, rotation, opacity, scale'),
-    expression: z.string().optional().default('sin(t * 2) * 50 + 300').describe('Math expression of t (time) and v (baseValue), e.g. "sin(t*2)*50 + v"'),
+    expression: z.string().optional().default('sin(t * 2) * 50 + 300').describe('Math expression of t (time) and v (baseValue), e.g. "sin(t*2)*50 + v". `^` is exponentiation, not XOR. Available: sin cos tan asin acos atan sinh cosh tanh abs floor ceil round trunc sign sqrt cbrt exp log log2 log10 · pow min max atan2 hypot clamp mod · fract pingpong inverseLerp remap noise sec csc cot · easeInQuad easeOutQuad easeInOutQuad easeInCubic easeOutCubic easeInOutCubic · constants PI, E, TAU. `random()` is REJECTED by name on both the signal and per-frame paths — a scene that cannot render the same way twice can never be baked or exported deterministically.'),
     baseValue: z.number().optional().default(0).describe('Base value accessible as v in the expression'),
-    signal: z.boolean().optional().default(false).describe('Deterministic IR mode — parse expression to IR, evaluate as pure f(t)'),
+    signal: z.boolean().optional().default(false).describe('Deterministic IR mode — parse expression to IR, evaluate as pure f(t). Both modes now use the same parser and the same grammar; signal additionally makes the result bakeable as a pure function of time.'),
 });
 // =============================================================================
 // EVENT-DRIVEN SCENE CHAINS (FxTool S11). Source of each is a pp:event.
@@ -609,6 +746,7 @@ export const ExecuteCustomCodeInputSchema = z.object({
 // =============================================================================
 // GENERATOR TYPES
 // =============================================================================
+/** Engine parity ENFORCED BY src/__tests__/unit/preflight-gate-parity.test.ts (fixture: engine-generators.txt). */
 export const GeneratorNameSchema = z.enum([
     // Classic generators
     'drawSunburst',
@@ -683,6 +821,24 @@ export const GeneratorNameSchema = z.enum([
     'drawScatter',
     'drawStackedWaves',
     'draw3DParametricCurve',
+    // THE GATE WAS NARROWER THAN THE ENGINE, and generatorName is a hard
+    // preflight gate — an unlisted name is rejected before the browser sees
+    // it. The engine registers 74 generators and this offered 64, so these
+    // ten were live and uncallable. Seven are the GPU field generators, which
+    // is the expensive half: create_item's `field` type, design_medium's flow
+    // fields and the design graph's own recipe example all name drawGPUTunnel,
+    // so a captured scene recording `generator: 'drawGPUTunnel'` could not be
+    // replayed through the tool that exists to replay it.
+    'draw3DWorld',
+    'drawCharacterEyes',
+    'drawGPUCaustics',
+    'drawGPUClouds',
+    'drawGPUOcean',
+    'drawGPUPlasma',
+    'drawGPUStarfield',
+    'drawGPUTunnel',
+    'drawGPUVoronoi',
+    'drawRiggedCharacter',
 ]).describe('Background generator name');
 // ---------------------------------------------------------------------------
 // Generator parameter schemas — Phase 1 (enhanced existing)
@@ -835,6 +991,7 @@ export const NoiseTextureParamsSchema = z.object({
 // =============================================================================
 // EFFECT TYPES
 // =============================================================================
+/** Engine parity ENFORCED BY src/__tests__/unit/preflight-gate-parity.test.ts (fixture: engine-effects.txt). */
 export const EffectTypeSchema = z.enum([
     'sparkle',
     'blast',
@@ -856,6 +1013,17 @@ export const EffectTypeSchema = z.enum([
     'heatmap',
     'liquid_metal',
     'gem_smoke',
+    'electric_arc',
+    'vortex',
+    'rain_veil',
+    'caustics',
+    // ink_bleed was the LAST aura and the gate rejected it. The engine's own
+    // comment says it 'has shipped unroutable through applyEffect since it was
+    // added' — past tense, describing a bug it then fixed: _publishNames()
+    // publishes every aura definition, and PinePaper.applyEffect warms the
+    // subsystem before routing, so all eight route now. Reading the comment
+    // would have kept it out; reading the mechanism put it in.
+    'ink_bleed',
 ]).describe('Visual effect type (particle effects + shader auras)');
 export const SparkleParamsSchema = z.object({
     color: ColorSchema.optional().default('#fbbf24').describe('Sparkle color'),
@@ -923,7 +1091,7 @@ export const CreateItemInputSchema = z.object({
     itemType: ItemTypeSchema,
     position: PositionSchema.optional().default({ x: 400, y: 300 }),
     properties: z.record(z.unknown()).optional().default({}),
-    animationType: z.string().optional().describe('Inline animation to apply on creation. Loop presets (pulse, rotate, bounce, fade, wobble, slide, typewriter) or "keyframe" with keyframes array. Equivalent to a follow-up pinepaper_animate / pinepaper_keyframe_animate call.'),
+    animationType: z.string().optional().describe('Inline animation to apply on creation. Loop presets (bounce, breathe, fade, glow, jelly, path, pulse, rotate, scrollDown, scrollLeft, scrollRight, scrollUp, shake, slideLeftRight, slideUpDown, swing, typewriter, wobble) or "keyframe" with keyframes array. Equivalent to a follow-up pinepaper_animate / pinepaper_keyframe_animate call.'),
     animationSpeed: z.number().optional().describe('Speed multiplier for loop animations (default: 1.0). Ignored when animationType is "keyframe".'),
     animationIntensity: z.number().optional().describe('Loop animation amplitude (0.1 = ±10%, default 0.15). Drives pulse/wobble/bounce/breathe amplitude; honored by SVG/SMIL/widget export.'),
     animationDelay: z.number().optional().describe('Loop animation start delay in seconds.'),
@@ -973,8 +1141,26 @@ export const DeleteItemInputSchema = z.object({
 export const AddRelationInputSchema = z.object({
     sourceId: z.string().describe('Registry ID of the source item'),
     targetId: z.string().nullish().describe('Registry ID of the target item; null/omitted for self-relations (animates, moves_along_path, construction_reveal, time_expression)'),
-    relationType: RelationTypeSchema,
+    relationType: RelationTypeSchema.optional().describe('The relation to create. Required unless presetId is given.'),
     params: z.record(z.unknown()).optional().default({}),
+    presetId: z.string().optional()
+        .describe("Apply a community relation PRESET instead of naming a type and params yourself — a tuned motion someone already got right, with its symbols exposed as knobs. List them with pinepaper_query_capabilities { action: 'catalogue', catalogue: 'relation_presets' }. The preset decides the relationType, so relationType is not needed and is ignored if sent."),
+    presetValues: z.record(z.number()).optional()
+        .describe('presetId: symbol → number. Any symbol you omit takes the midpoint of its declared range, so a preset applies sensibly with no values at all.'),
+})
+    .refine((v) => !!v.relationType || !!v.presetId, { message: 'relationType is required unless presetId is given', path: ['relationType'] })
+    // A PRESET IS A SELF-RELATION and has no target slot. applyRelationPreset
+    // takes (item, presetId, values) — pass a targetId alongside one and the
+    // emitted call has nowhere to put it, so a caller adopting a preset for a
+    // two-item relation silently got a self-relation with no diagnostic.
+    // Refused here rather than dropped there.
+    .refine((v) => !v.presetId || v.targetId == null, {
+    message: 'presetId cannot be combined with targetId — a relation preset applies to one item. Name the relationType directly for a two-item relation.',
+    path: ['targetId'],
+})
+    .refine((v) => !v.presetId || !v.relationType, {
+    message: 'presetId cannot be combined with relationType — the preset decides its own type. Send one or the other.',
+    path: ['relationType'],
 });
 // Remove Relation
 export const RemoveRelationInputSchema = z.object({
@@ -1007,6 +1193,63 @@ export const KeyframeAnimateInputSchema = z.object({
     clipInPoint: z.number().optional().describe('Skip the first N seconds of keyframe data — clip head trim.'),
     clipOutPoint: z.number().optional().describe('Stop at N seconds into the keyframe data — clip tail trim. Default: lastKeyframeTime.'),
 });
+// Character — a symbol and some beats, expanded against the design graph.
+//
+// Mirrors `pinepaper_character`'s inputSchema field for field. Only `concept`
+// is required: everything else has a defensible default, and the point of the
+// tool is that a caller who knows nothing but the name of a figure gets one.
+export const CharacterBeatSchema = z.object({
+    at: z.number().describe('When, in seconds'),
+    channel: z.string().describe('A channel the concept declares — blink, say, headTurn, bob, tailFlick…'),
+    until: z.number().optional().describe('For a channel that occupies a span rather than an instant'),
+    value: z.number().optional().describe('How far, for a channel that takes a magnitude'),
+});
+export const CharacterInputSchema = z.object({
+    concept: z.string().describe('Concept id from the design graph, e.g. "pp:Character" or "pp:Pigeon".'),
+    at: z.object({ x: z.number().optional(), y: z.number().optional() }).optional().describe('Where the figure stands.'),
+    height: z.number().optional().describe('Drawn height in pixels.'),
+    id: z.string().optional().describe('Prefix for the created items (default: the concept name).'),
+    style: z.string().optional().describe('Style id for the depiction (default: the concept\'s own).'),
+    variant: z.string().optional().describe('Depiction variant (default: "default").'),
+    durationSeconds: z.number().optional().describe('Length of the piece, so every track spans it.'),
+    beats: z.array(CharacterBeatSchema).optional().describe('What happens, in order.'),
+    timings: z.array(z.object({ at: z.number(), until: z.number().optional() })).optional()
+        .describe('Word or syllable timings from a voice track; each entry drives one mouth opening.'),
+    // THESE WERE HANDLED AND UNDECLARED. resolveCharacter reads all four and its
+    // own comment says a call written the way the rest of the vocabulary reads
+    // must not land dead-centre at the default size — but zod strips unknown
+    // keys, so `{concept, position, scale}` did exactly that, silently.
+    position: z.object({ x: z.number().optional(), y: z.number().optional() }).optional()
+        .describe('Where the figure stands. A synonym for `at`, because the rest of this surface says position; `at` wins if both are sent.'),
+    scale: z.number().optional()
+        .describe('Size as a multiplier of the 300px default, for callers who think in scale rather than pixels. `height` wins if both are sent.'),
+    palette: z.record(z.string(), z.string()).optional()
+        .describe("Override the depiction's own colours: part id → colour. Only the parts you name change."),
+    ink: z.string().optional()
+        .describe("Ink colour for the stroked copies that make the figure read as drawn rather than filled. The style supplies its own; this overrides it."),
+});
+// Motion Capture (BVH)
+//
+// FxTool exposes two distinct operations and the difference is the whole point:
+//   importBVH   builds a NEW skeleton shaped like the capture file
+//   retargetBVH drives an EXISTING rig — proportions stay yours, only MOTION comes from the clip
+// Angles transfer as bind-pose deltas (target.rest + (source(t) - source(rest))), so a T-posed CMU
+// rest is not slammed onto a rig with a relaxed stance. Bone matching carries the BVH child-joint
+// shift ("LeftLeg" is the thigh); anything unmatched is REPORTED, never silently half-driven.
+export const ImportMotionCaptureInputSchema = z.object({
+    bvh: z.string().describe('BVH clip text (CMU / Mixamo export). Required.'),
+    mode: z.enum(['import', 'retarget']).optional().default('import')
+        .describe("'import' builds a new skeleton from the file; 'retarget' drives an existing rig named by skeletonId — use retarget when the character already exists, so its proportions are preserved and only the motion is taken from the capture."),
+    skeletonId: z.string().optional()
+        .describe("Rig to drive. REQUIRED when mode='retarget'; ignored for 'import'."),
+    fps: z.number().optional().describe('Pose sampling rate. CMU records at 120fps and nobody wants 120 poses a second; 0 keeps every frame. Default 15.'),
+    height: z.number().optional().describe('Skeleton height on the canvas in px (import mode). Default 320.'),
+    position: z.object({ x: z.number(), y: z.number() }).optional()
+        .describe('Where the ROOT joint stands (import mode). Defaults to canvas centre, 70% down.'),
+    name: z.string().optional().describe('Name for the created skeleton (import mode).'),
+    boneMap: z.record(z.string(), z.string()).optional()
+        .describe('BVH edge name → this rig\'s bone name. Overrides the alias table when a clip uses non-standard joint names; check unmatchedSource/unmatchedTarget in the result to see what needs mapping.'),
+});
 // Execute Generator
 //
 // Region (added FxTool c81781c): when set, the generator draws into a clipped
@@ -1042,7 +1285,13 @@ export const GetItemsInputSchema = z.object({
 });
 // Play Timeline
 export const PlayTimelineInputSchema = z.object({
-    action: z.enum(['play', 'pause', 'stop', 'seek']),
+    action: z.enum([
+        'play', 'pause', 'stop', 'seek',
+        // pp:TimeScale — the rate the scene clock runs at.
+        'set_time_scale', 'get_time_scale',
+        // pp:InputDrivenPlayback — progress driven by an input instead of a clock.
+        'get_progress', 'set_progress', 'bind_scroll', 'unbind_scroll', 'list_scrub_anchors',
+    ]),
     duration: z.number().optional().describe('Duration for play action'),
     loop: z.boolean().optional(),
     time: z.number().optional().describe('Time to seek to'),
@@ -1050,6 +1299,22 @@ export const PlayTimelineInputSchema = z.object({
         .boolean()
         .optional()
         .describe('For seek: evaluate the scene at the exact time via app.sceneAt(t) — ticks keyframes + relations + generators deterministically (same t → same frame), not just the keyframe state. Use before a screenshot for a reproducible frame.'),
+    // Deliberately unclamped: 0 freezes the clock without stopping playback, and a
+    // negative rate runs the scene backwards. Both are things the engine supports
+    // and a min(0) would quietly forbid.
+    rate: z.number().optional()
+        .describe('set_time_scale: 1 is real time, 0.5 half speed, 0 freezes without stopping, negative runs backwards. Export is unaffected — a scene watched at 0.5x still exports its real duration.'),
+    progress: z.number().min(0).max(1).optional()
+        .describe('set_progress: how far through the timeline, 0..1 — the unit a scrubber or a progress bar actually has.'),
+    scroll: z.object({
+        elementId: z.string().optional().describe('DOM id of the element to track (defaults to the canvas)'),
+        start: z.string().optional().describe("Anchor where the range begins, e.g. 'top bottom' (the moment the element appears). See list_scrub_anchors."),
+        end: z.string().optional().describe("Anchor where the range ends, e.g. 'bottom top' (the moment it is gone)."),
+        scrub: z.number().min(0).optional()
+            .describe('Seconds of smoothing — the played position chases the scroll instead of snapping to it (default 0.3). 0 snaps.'),
+        range: z.array(z.number()).length(2).optional()
+            .describe('[from, to] in seconds — drive only a sub-range of the timeline instead of the whole thing.'),
+    }).optional().describe('bind_scroll options'),
 });
 // Canvas Control
 export const SetBackgroundColorInputSchema = z.object({
@@ -1187,7 +1452,7 @@ export const SceneAnimationSchema = z.object({
     /** Reference name of the item to animate */
     target: z.string().describe('Name of the item to animate'),
     /** Type of animation */
-    type: z.enum(['pulse', 'rotate', 'bounce', 'fade', 'wobble', 'slide', 'typewriter']),
+    type: z.enum(['bounce', 'breathe', 'fade', 'glow', 'jelly', 'path', 'pulse', 'rotate', 'scrollDown', 'scrollLeft', 'scrollRight', 'scrollUp', 'shake', 'slideLeftRight', 'slideUpDown', 'swing', 'typewriter', 'wobble']),
     /** Animation speed (default: 1.0) */
     speed: z.number().optional(),
     /** Animation parameters */
@@ -1346,6 +1611,7 @@ export const CreateDiagramShapeInputSchema = z.object({
  * Connect items input
  */
 export const ConnectInputSchema = z.object({
+    id: z.string().optional().describe('Stable connector ID. Assign your own and reuse it as `connectorId` in update/remove — the engine otherwise mints a Date.now()-based ID no caller can predict'),
     sourceItemId: z.string().describe('Registry ID of source item'),
     targetItemId: z.string().describe('Registry ID of target item'),
     routing: ConnectorRoutingSchema.optional().default('orthogonal'),
@@ -1363,6 +1629,7 @@ export const ConnectInputSchema = z.object({
  * Connect specific ports input
  */
 export const ConnectPortsInputSchema = z.object({
+    id: z.string().optional().describe('Stable connector ID. Assign your own and reuse it as `connectorId` in update/remove — the engine otherwise mints a Date.now()-based ID no caller can predict'),
     sourceItemId: z.string().describe('Registry ID of source item'),
     sourcePort: PortPositionSchema.describe('Port position on source'),
     targetItemId: z.string().describe('Registry ID of target item'),
@@ -1561,6 +1828,10 @@ export const AgentPlatformSchema = z.enum([
  */
 export const AgentExportFormatSchema = z.enum([
     'svg', 'png', 'gif', 'mp4', 'webm', 'pdf',
+    // AUDIO-ONLY. The soundtrack on its own, with no frames rendered — so
+    // platform dimensions, framing and quality do not apply to it, and no
+    // platform preset resolves to it. It has to be asked for by name.
+    'wav',
 ]).describe('Export file format');
 /**
  * Screenshot policy for agent jobs
@@ -1739,6 +2010,17 @@ export const AgentBatchExecuteInputSchema = z.object({
  * could not. This brings the two in line.
  */
 export const GIF_MAX_DURATION_S = 15;
+/**
+ * Longest mp4/webm export the tool will accept, in seconds.
+ *
+ * Was 60. A ten-minute export is only reachable because the bytes no longer
+ * cross the browser→server bridge as one base64 string: above an inline
+ * ceiling the studio keeps the file in its export store and the handler pages
+ * it out in chunks. On a studio with no export store the emitted code refuses
+ * by name with the numbers instead, so raising this cap cannot turn into an
+ * out-of-memory — it turns into a message naming the ceiling and what to do.
+ */
+export const VIDEO_MAX_DURATION_S = 600;
 /**
  * Smart export input schema
  */
@@ -1748,10 +2030,29 @@ export const AgentExportInputSchema = z.object({
     quality: z.enum(['draft', 'standard', 'high']).optional().default('standard').describe('Export quality level'),
     includeRecommendations: z.boolean().optional().default(true).describe('Include alternative format recommendations'),
     framing: z.enum(['canvas', 'camera']).optional().default('canvas').describe('Output framing: "canvas" (full canvas, default) or "camera" (camera_animates first-keyframe viewport — fails if no walkthrough exists). Camera animation still drives motion within the fixed output frame.'),
-    duration: z.number().min(0.5).max(60).optional().default(5).describe(`Video duration in seconds for animated formats (mp4/webm/gif). Default 5. Max 60 for mp4/webm, max ${GIF_MAX_DURATION_S} for gif (GIF is not codec-bounded, so file size scales with frames × dimensions). Static formats (png/svg/pdf) ignore this.`),
-    estimateOnly: z.boolean().optional().default(false).describe('Preflight only: return the estimated file size for these EXACT settings and render nothing. Use before a long or high-quality export to check the size first. Modeled for mp4/webm/gif; png/pdf/svg return confidence "none" because no dimension-based model exists for them.'),
+    duration: z.number().min(0.5).max(VIDEO_MAX_DURATION_S).optional().default(5).describe(`Video duration in seconds for animated formats (mp4/webm/gif). Default 5. Max ${VIDEO_MAX_DURATION_S} for mp4/webm, max ${GIF_MAX_DURATION_S} for gif (GIF is not codec-bounded, so file size scales with frames × dimensions, and it cannot stream to the export store). Static formats (png/svg/pdf) ignore this. Past roughly a minute the export is held in the studio's export store and paged back to a file rather than returned inline; a studio without that store refuses by name and says so.`),
+    estimateOnly: z.boolean().optional().default(false).describe('Preflight only: return the estimated file size for these EXACT settings and render nothing. Use before a long or high-quality export to check the size first. Modeled for mp4/webm/gif; png/pdf/svg return confidence "none" because no dimension-based model exists for them; wav is reported as "exact", because uncompressed PCM size is arithmetic rather than a guess.'),
+    sampleRate: z.number().int().positive().optional().describe('wav only: samples per second (default 48000). Ignored by every other format.'),
+    bitDepth: z.union([z.literal(16), z.literal(32)]).optional().describe('wav only: 16 (default) or 32-bit float. Ignored by every other format.'),
 }).describe('Smart export options')
     .superRefine((val, ctx) => {
+    // wav carries no picture, so the visual knobs are not merely ignored — a
+    // caller who set them believes something about the output that is not
+    // true. Said once, rather than silently dropped.
+    if (val.format === 'wav' && val.framing === 'camera') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['framing'],
+            message: 'framing does not apply to a wav export — it renders no frames. Drop framing, or export mp4/webm if you want the picture with the sound.',
+        });
+    }
+    if (val.format !== 'wav' && (val.sampleRate !== undefined || val.bitDepth !== undefined)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['sampleRate'],
+            message: `sampleRate and bitDepth apply only to format "wav" (got "${val.format}").`,
+        });
+    }
     if (val.format === 'gif' && val.duration > GIF_MAX_DURATION_S) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
@@ -2208,6 +2509,33 @@ export const QueryOntologyInputSchema = z.object({
     category: z.string().optional(),
     includeAbstract: z.boolean().optional().default(false),
 });
+// Capabilities query schema: discover and match capabilities across text styles, text effects, generators, deforms, relations, etc.
+export const QueryCapabilitiesInputSchema = z.object({
+    action: z.enum(['list', 'choose', 'coverage', 'find', 'catalogue', 'studio']).default('list')
+        .describe("'list' (all capabilities or filtered by kind) · 'choose' (context/mood-weighted recommendation) · 'coverage' (breakdown of indexable capabilities) · 'find' (lookup by key) · 'catalogue' (the registries the aggregate does NOT gather — see `catalogue`) · 'studio' (which engine METHODS this studio has, so you learn what will refuse BEFORE calling it)"),
+    catalogue: z.enum([
+        'rig_presets', 'shader_effects', 'stroke_decorations', 'precomps', 'images',
+        'segment_edit_kinds', 'shatter_orders', 'world_meshes', 'relation_presets',
+    ]).optional().describe("action 'catalogue': which registry to read. These sit OUTSIDE app.getCapabilities' aggregate — that one already covers styles, effects, deforms, entrances, animations, collages, palettes, masks, maskShapes and cutouts, and 'list' reaches all of those. Use this for the ones it does not gather: rig presets, shader effects, stroke decorations, the precomp list, the image library, segment-edit kinds, shatter orders and world meshes."),
+    kind: z.union([
+        z.string(),
+        z.array(z.string()),
+    ]).optional().describe("Filter by capability kind: 'style'|'effect'|'deform'|'entrance'|'animation'|'generator'|'collage'|'palette'|'mask'|'cutout'|'relation'"),
+    mood: z.union([
+        z.string(),
+        z.array(z.string()),
+    ]).optional().describe("For choose: target feeling ('reveal'|'triumphant'|'failure'|'calm'|'technical'|'energetic')"),
+    subject: z.string().optional().describe('For choose: contextual subject keywords / prompt text to score against capability definitions'),
+    avoid: z.union([
+        z.string(),
+        z.array(z.string()),
+    ]).optional().describe('For choose: mood terms or feelings to penalize'),
+    seed: z.string().optional().describe('For choose: deterministic seed string for reproducible selection'),
+    key: z.string().optional().describe('For find: exact capability key to look up'),
+    exclude: z.array(z.string()).optional().describe('For choose: list of capability keys to exclude from recommendation'),
+    warm: z.boolean().optional()
+        .describe('Load the lazy registries before answering (default true). The generator registry and the rigging/blending/deform relation rules only exist once touched, so a cold answer omits them — pass false only to re-read what is already resident, cheaply.'),
+});
 // =============================================================================
 // SCENE MANAGEMENT SCHEMAS
 // =============================================================================
@@ -2232,6 +2560,175 @@ export const ScenePlaybackInputSchema = z.object({
     index: z.number().optional(),
 });
 // =============================================================================
+// RELATIVE TIMING, STAGGERS, FLIP  (GSAP's vocabulary, PinePaper's engine)
+// =============================================================================
+// pp:TimelinePosition — saying WHEN relative to something else.
+//
+// The position spec is a number or one of the string forms; it stays loose on
+// purpose, because the grammar is open ("intro+=0.5" names a caller's label) and
+// an enum here could only ever be a stale subset of it. list_forms is the
+// discoverable list.
+export const SequenceInputSchema = z.object({
+    action: z.enum(['place', 'resolve', 'list_forms']).default('place')
+        .describe("'place' threads a run of clips, each resolved against the ones before it · 'resolve' answers a single position · 'list_forms' returns the accepted grammar with what each form means"),
+    clips: z.array(z.object({
+        id: z.string().optional().describe('Your own name for the clip — echoed back on the placement'),
+        duration: z.number().min(0).describe('How long the clip runs, in seconds'),
+        position: z.union([z.number(), z.string()]).optional()
+            .describe('Where it starts. Omit to append at the end of the timeline so far.'),
+        label: z.string().optional().describe('Name this moment so later clips can position against it. A label marks where the clip STARTS.'),
+    })).optional().describe('place: the run of clips, in order'),
+    position: z.union([z.number(), z.string()]).optional().describe('resolve: the single position spec to resolve'),
+    context: z.object({
+        timelineEnd: z.number().optional().describe('Where the timeline currently ends — what a bare "+=1" counts from'),
+        prevStart: z.number().optional().describe('Start of the most recently added clip — what "<" means'),
+        prevEnd: z.number().optional().describe('End of the most recently added clip — what ">" means'),
+        insertDuration: z.number().optional().describe('Duration of the clip being placed — the basis for a "+=25%" / "-=25%" percentage'),
+    }).optional().describe('resolve: what the spec is measured against'),
+    labels: z.record(z.string(), z.number()).optional().describe('Named moments in seconds, addressable as "name" or "name+=0.5"'),
+    startAt: z.number().optional().describe('place: where the run begins (default 0)'),
+});
+// pp:Stagger — the shape of a delay across many items.
+const StaggerOptsSchema = z.object({
+    // `each` and `amount` are ALTERNATIVES, not a pair: each fixes the gap between
+    // neighbours so more items make a longer sequence; amount fixes the total so
+    // more items crowd together.
+    each: z.number().min(0).optional().describe('Seconds between neighbours (default 0.1). More items ⇒ a longer sequence.'),
+    amount: z.number().min(0).optional().describe('Total seconds for the WHOLE run, split among the items. Overrides each — more items ⇒ they crowd together.'),
+    from: z.union([
+        z.enum(['start', 'end', 'center', 'edges', 'random']),
+        z.number(),
+        z.array(z.number()).length(2),
+    ]).optional().describe("Where the stagger begins: a named origin, an item index, or [fx, fy] fractions for a grid ([0.5, 0.5] is the centre)."),
+    grid: z.array(z.number()).length(2).optional().describe('[rows, columns] for a 2D stagger. Items are read row-major.'),
+    axis: z.enum(['x', 'y']).optional().describe('Restrict a grid stagger to one axis.'),
+    ease: z.enum(['linear', 'easeIn', 'easeOut', 'easeInOut', 'easeInCubic', 'easeOutCubic']).optional()
+        .describe("Curve that distributes the START TIMES — not the items' own animation curve."),
+    seed: z.number().optional().describe("from: 'random' — same seed, same shuffle (default 1)."),
+});
+export const StaggerInputSchema = z.object({
+    action: z.enum(['apply', 'preview', 'list_origins']).default('apply')
+        .describe("'apply' writes the delays onto real items · 'preview' returns the delays for a count without touching the canvas · 'list_origins' names the origins"),
+    itemIds: z.array(z.string()).optional().describe('apply: registry ids IN THE ORDER the stagger should follow (row-major for a grid)'),
+    count: z.number().int().min(0).optional().describe('preview: how many items to compute delays for'),
+    opts: StaggerOptsSchema.optional().describe('Shape of the stagger'),
+});
+// pp:Flip — a transition DERIVED from a change rather than described.
+export const FlipInputSchema = z.object({
+    action: z.enum(['record', 'apply']).default('record')
+        .describe("'record' captures where things are NOW · 'apply' animates from that record to wherever they have since been moved"),
+    itemIds: z.array(z.string()).optional()
+        .describe('record: which items to capture (defaults to everything on the item layer, which is the usual case for a re-layout)'),
+    duration: z.number().min(0).optional().describe('apply: seconds the transition runs (engine default)'),
+    easing: z.string().optional().describe('apply: named easing for the generated keyframes'),
+    enter: z.string().optional().describe('apply: entrance preset for items that appeared during the change, so they animate in rather than popping'),
+    stagger: StaggerOptsSchema.optional().describe("apply: stagger the transition across the items, in the items' own order"),
+});
+// Scene graph: interactive multi-node story/quiz state graphs (cards, answers, mutex, event wiring)
+//
+// The node and opts fields below mirror what the engine's compiler actually
+// reads (js/core/SceneGraph.js). zod strips unknown keys, so a field missing
+// here is not "passed through" — it is silently dropped on the way to an engine
+// that would have honoured it. `next`, `duration`, `outcome` and `subject` were
+// each unreachable for that reason.
+const SceneGraphNodeSchema = z.object({
+    id: z.string().describe('Unique node id (e.g., "q1", "win", "lose")'),
+    prompt: z.string().optional().describe('Prompt or headline text for question cards'),
+    text: z.string().optional().describe('Text for message/end cards'),
+    kind: z.enum(['node', 'card', 'end']).optional()
+        .describe("'node'/'card' (question or content) or 'end' (terminal/outcome). Anything that is not 'end' is a card."),
+    answers: z.array(z.object({
+        text: z.string().describe('Answer button text'),
+        correct: z.boolean().optional().describe('Whether this is the correct answer (increments score when scoreItemId given)'),
+        to: z.string().min(1).describe('Destination node id when clicked'),
+    })).optional().describe('Interactive answer choices (for question cards)'),
+    next: z.string().min(1).optional()
+        .describe('Unconditional destination — a linear story beat that auto-advances instead of waiting for a click. Use INSTEAD of answers, not alongside a lone fake button.'),
+    duration: z.number().positive().optional()
+        .describe('Seconds this card holds before `next` fires (default 3). Ignored without `next`.'),
+    outcome: z.enum(['win', 'lose']).optional()
+        .describe('Force the outcome of a terminal node. Without it the engine infers win/lose from the wording, which only works in English.'),
+});
+export const SceneGraphInputSchema = z.object({
+    action: z.enum(['create', 'validate']).default('create')
+        .describe("'create' builds the graph on the canvas · 'validate' runs the same check WITHOUT drawing anything, returning errors, warnings, unreachable nodes and cycles"),
+    graph: z.object({
+        start: z.string().optional().describe('Node id of the initial active card (defaults to the first node)'),
+        nodes: z.array(SceneGraphNodeSchema).min(1).describe('Array of scene graph nodes'),
+    })
+        // Structural integrity, checked HERE because in code mode there is no engine
+        // to catch it: the snippet is handed to the caller and fails silently later.
+        // Duplicate ids in particular are invisible engine-side — `indexNodes` keys a
+        // Map by id, so the second node quietly replaces the first.
+        .superRefine((graph, ctx) => {
+        const seen = new Set();
+        graph.nodes.forEach((node, i) => {
+            if (seen.has(node.id)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ['nodes', i, 'id'],
+                    message: `duplicate node id "${node.id}" — the later node silently replaces the earlier one`,
+                });
+            }
+            seen.add(node.id);
+        });
+        const has = (id) => seen.has(id);
+        if (graph.start !== undefined && !has(graph.start)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['start'],
+                message: `start node "${graph.start}" does not exist`,
+            });
+        }
+        graph.nodes.forEach((node, i) => {
+            (node.answers || []).forEach((answer, a) => {
+                if (!has(answer.to)) {
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        path: ['nodes', i, 'answers', a, 'to'],
+                        message: `node "${node.id}" points at "${answer.to}", which does not exist — clicking it would do nothing`,
+                    });
+                }
+            });
+            if (node.next !== undefined && !has(node.next)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ['nodes', i, 'next'],
+                    message: `node "${node.id}" advances to "${node.next}", which does not exist`,
+                });
+            }
+            // Mirrors the engine's own refusal: a non-terminal card with no edge is
+            // a dead end the player can never leave.
+            if (node.kind !== 'end' && !node.answers?.length && node.next === undefined) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ['nodes', i],
+                    message: `node "${node.id}" is not terminal but has no way out — give it answers, a next, or kind: 'end'`,
+                });
+            }
+        });
+    })
+        .describe('The declarative scene graph definition'),
+    opts: z.object({
+        width: z.number().optional().describe('Layout width (defaults to view width or canvas width)'),
+        height: z.number().optional().describe('Layout height (defaults to view height or canvas height)'),
+        centerX: z.number().optional().describe('Center X position for card stack'),
+        centerY: z.number().optional().describe('Center Y position for card stack'),
+        groupName: z.string().optional().describe('Prefix / seed namespace for generated IDs and effect selection'),
+        scoreItemId: z.string().optional().describe('Optional scoreboard text item id to increment on correct answers'),
+        subject: z.string().optional()
+            .describe("Extra context folded into each card's text-effect selection — the theme of the piece, e.g. 'space exploration'."),
+        plain: z.boolean().optional().describe('Opt out of rich effects/entrances for a bare structural graph'),
+        style: z.object({
+            panelColor: z.string().optional().describe('Background panel fill color (default #1E1B4B)'),
+            textColor: z.string().optional().describe('Headline/prompt text color (default #F8FAFC)'),
+            answerColor: z.string().optional().describe('Answer text color (default #93C5FD)'),
+            headlineSize: z.number().optional().describe('Font size for headline/prompt (default 34)'),
+            bodySize: z.number().optional().describe('Font size for body/answers (default 24)'),
+        }).optional().describe('Visual styling options for generated cards and text'),
+    }).optional().describe('Layout, style, and scoring options'),
+});
+// =============================================================================
 // SELECTION, TRANSFORM & HISTORY TOOLS
 // =============================================================================
 export const SelectionInputSchema = z.object({
@@ -2329,6 +2826,28 @@ export const ProvenanceInputSchema = z.object({
     sourceRef: z.string().optional(),
     meta: z.record(z.string(), z.unknown()).optional(),
 });
+/**
+ * The stitches the thread medium publishes — ONE list, because it had four copies.
+ *
+ * Mirrors FxTool's `STITCH_OPS` in js/core/ThreadPainting.js — ENFORCED BY
+ * src/__tests__/unit/preflight-gate-parity.test.ts against the fixture
+ * src/__tests__/fixtures/engine-stitches.txt, both directions, with a
+ * guard-the-guard that plants a seventh stitch and asserts the comparison
+ * fails. A parity claim that cites the test enforcing it is checkable in one
+ * command; one that does not is a memory of someone having checked once, and
+ * this sentence was that memory for six commits. The table is
+ * vocabulary `applyThreadPainting` dispatches on; it refuses an unknown name
+ * rather than falling through to a default fill.
+ *
+ * There were four copies of this list here — two Zod enums and their two JSON
+ * mirrors — and fixing one left `pinepaper_compose` unable to ask for two
+ * stitches `apply_thread` could. The engine had the identical split for the
+ * identical reason: `MEDIA.thread.stitches` was hardcoded to the same stale
+ * four while STITCH_OPS published six (FxTool 6aaa9069). Two repos, four
+ * copies, one list, drifted the same direction on the same day — so it is
+ * declared once here and spread everywhere it is needed.
+ */
+export const THREAD_STITCHES = ['longAndShort', 'satin', 'seed', 'stem', 'runningSeam', 'crossStitch'];
 export const SceneDiffInputSchema = z.object({
     /** 'history' compares two undo states; 'version' compares live vs a saved version. */
     action: z.enum(['history', 'version']),
@@ -2364,6 +2883,24 @@ export const ComposeInputSchema = z.object({
     audio: z.string().optional(),
     /** With audio: snap to an even tempo grid instead of raw onsets. */
     grid: z.boolean().optional(),
+    /**
+     * WHICH DESIGN LANGUAGE. Resolves the craft — gutter, margin, hue budget,
+     * type scale, alignment discipline — so those move together instead of being
+     * chosen one at a time. A default, not a handcuff: an explicit `craft` still
+     * wins. naive | playful | poster | editorial | technical.
+     */
+    register: z.string().optional().describe('Design register — naive, playful, poster, editorial, technical. Sets the craft; an explicit `craft` still overrides it.'),
+    level: z.number().int().min(1).max(4).optional().describe('Craft level 1-4 WITHIN the register (sketch, competent, refined, art-directed). Climbing never widens a budget — restraint is the direction of craft.'),
+    /**
+     * WHAT MAKES THE MARKS. Only media a whole composition can be rendered in
+     * are accepted: `vector` (what composing already produces) and `thread`
+     * (needlepainting, stitched after the arrangement). The rest are refused
+     * with the medium's own reason rather than composed as flat shapes in its
+     * colours.
+     */
+    medium: z.enum(['vector', 'thread']).optional().describe("Render the composition in a medium. 'thread' stitches every closed path; photographs and text CANNOT be stitched and come back in `medium.skipped` with the reason, so read that count — a composition can render completely and be entirely unstitched."),
+    stitch: z.enum(THREAD_STITCHES).optional().describe('Which stitch, when medium is thread. Default longAndShort. The same six pinepaper_design_medium offers — call its list_stitches for each one.'),
+    stitchBudget: z.number().int().min(200).max(20000).optional().describe('Total marks across the composition (default 6000). The stitch is scaled to fit rather than the fill being truncated — a half-stitched shape looks broken, coarser thread does not.'),
 });
 export const AudioBeatsInputSchema = z.object({
     action: z.enum(['analyze', 'animate_to_beat']),
@@ -2743,8 +3280,17 @@ export const MediaInputSchema = z.object({
  * platform impossibility, not an omission.
  */
 export const TextStyleInputSchema = z.object({
-    action: z.enum(['apply_style', 'set_font_axes', 'list_styles'])
-        .describe("'apply_style' (stacked-layer display style) · 'set_font_axes' (variable-font weight/width/slant) · 'list_styles' (styles + palettes + axes, for pickers)"),
+    action: z.enum(['apply_style', 'set_font_axes', 'list_styles', 'cursive', 'wrap', 'unwrap', 'to_collage'])
+        .describe("'apply_style' (stacked-layer display style) · 'set_font_axes' (variable-font weight/width/slant) · 'list_styles' (styles + palettes + axes, for pickers) · 'cursive' (draw text as STROKED handwriting — a path, not a glyph, so it can be drawn on over time) · 'wrap' / 'unwrap' (break a text item to a width, reversibly) · 'to_collage' (turn an EXISTING text item into a letter collage, keeping its place)"),
+    text: z.string().optional().describe('cursive: the words to write. to_collage: the text to build the collage from, if it differs from the item.'),
+    maxWidth: z.number().optional().describe('wrap: the width to break at, in canvas units. unwrap restores the original single line, so this is not destructive.'),
+    cursiveOptions: z.object({
+        x: z.number().optional(), y: z.number().optional(),
+        scale: z.number().optional().describe('Size multiplier (default 1).'),
+        strokeColor: z.string().optional().describe("Ink colour (default '#ffffff')."),
+        strokeWidth: z.number().optional().describe('Pen width (default 2).'),
+    }).optional().describe('cursive: where and how it is written. The result is a STROKED PATH, so pinepaper_animate\'s draw-on and pinepaper_path\'s outline_stroke both apply to it — which is the reason to prefer it over a script font.'),
+    collageOptions: z.record(z.string(), z.unknown()).optional().describe('to_collage: style, palette and the rest, same vocabulary as pinepaper_create_letter_collage.'),
     itemId: z.string().optional().describe('Text item id — apply_style / set_font_axes.'),
     styleKey: z.string().optional().describe("apply_style: style name from list_styles (e.g. 'stacked', 'arcade' — the pixel/arcade styles suggest their own face)."),
     palette: z.union([z.string(), z.array(z.string())]).optional().describe('apply_style: a named colourway or an explicit color array.'),
@@ -2760,6 +3306,104 @@ export const TextStyleInputSchema = z.object({
 })
     .refine((v) => v.action !== 'apply_style' || (!!v.itemId && !!v.styleKey), { message: 'apply_style requires itemId and styleKey', path: ['styleKey'] })
     .refine((v) => v.action !== 'set_font_axes' || (!!v.itemId && !!v.axes && Object.keys(v.axes).length > 0), { message: 'set_font_axes requires itemId and at least one axis', path: ['axes'] });
+/**
+ * pinepaper_text_effect — the 37 character-level text effects
+ * (terminaltexteffects' vocabulary, reimplemented in FxTool from source).
+ *
+ * The contract that separates this from `pinepaper_text_style`, and the one
+ * thing a caller must know: this tool EXPLODES the text item into one item per
+ * character and REMOVES the original. `text_style` ADOPTS the text's registry
+ * id; this DESTROYS it. Relations, keyframes and agent handles pointing at the
+ * source id die with it — `keepSource: true` leaves the original in place if
+ * they matter.
+ *
+ * `effect` is a free string, not an enum: the engine owns the vocabulary, its
+ * own error names every valid key, and `action: 'list'` is authoritative. An
+ * enum here would pin the server to today's 37 and go stale on the 38th.
+ *
+ * The planner is pure and emits KEYFRAMES, so the result is ordinary animated
+ * items — it scrubs, survives undo/session restore, and exports through the
+ * existing MP4/SMIL/Lottie paths rather than needing a per-exporter animator.
+ */
+/**
+ * The MEDIUM axis — what makes the marks, as distinct from which design
+ * language (register) and how well executed (level).
+ *
+ * Every medium declares a fidelity, and the tool refuses an `absent` one with
+ * the reason rather than producing flat shapes in its colours. Ask
+ * `list_media` before promising a medium in prose.
+ */
+export const DesignMediumInputSchema = z.object({
+    action: z.enum(['list_media', 'resolve', 'list_stitches', 'apply_thread', 'apply_hatch', 'list_flow_fields', 'list_hatch_options'])
+        .describe("'list_media' (7 media with fidelity + limitation) · 'resolve' (can this medium be made here, and how honestly) · 'list_stitches' · 'apply_thread' (render an item in thread) · 'apply_hatch' (rule an item with hatching — value through line density) · 'list_flow_fields' · 'list_hatch_options'"),
+    medium: z.string().optional().describe("resolve: medium key — vector, thread, hatch, watercolor, ink, cutPaper, charcoal, oil, encaustic. Call list_media for the live set with each one's fidelity; the catalogue grows."),
+    itemId: z.string().optional().describe('apply_thread / apply_hatch: a closed path, compound path, or a group of them. Its own silhouette is the region and its fill is the ink colour.'),
+    stitch: z.enum(THREAD_STITCHES).optional()
+        .describe("Which stitch, when the medium is thread. Default longAndShort. These six are THE_STITCH_OPS the engine publishes — call 'list_stitches' for each one's description and its own parameters. An unknown name is refused by the engine rather than quietly stitched as a default fill."),
+    field: z.object({
+        kind: z.enum(['radial', 'spine', 'constant']),
+        cx: z.number().optional(), cy: z.number().optional(),
+        angle: z.number().optional(),
+        spine: z.array(PositionSchema).optional(),
+        across: z.boolean().optional(),
+    }).optional().describe("apply_thread: the direction field — the thing that makes it needlepainting rather than hatching. Default radial from the shape centre. 'spine' runs stitches along a midrib or feather shaft; 'constant' is flat hatch."),
+    stitchLen: z.number().positive().optional().describe('apply_thread: nominal stitch length px (default 18).'),
+    rowGap: z.number().positive().optional().describe('apply_thread: row spacing px. Defaults from the thread width so the rows abut; setting it wider is what makes a fill read as hatching.'),
+    variance: z.number().min(0).max(1).optional().describe('apply_thread: length jitter 0..1 (default 0.35) — the variance IS the long-and-short shading.'),
+    width: z.number().positive().optional().describe('apply_thread: thread width px (default 2).'),
+    sheen: z.boolean().optional().describe('apply_thread: draw the highlight along each stitch (default true) — thread is not matte.'),
+    color: z.string().optional().describe("apply_thread: thread colour, defaulting to the item's own fill."),
+    seed: z.number().int().optional().describe('apply_thread: PRNG seed (default 1). Same seed stitches the same way.'),
+    count: z.number().int().positive().optional().describe('apply_thread: stitch count for seed/satin.'),
+    // THE OPTIONS THE ENGINE READS AND NOTHING NAMED. ThreadPainting.paint reads
+    // every one of these; apply_thread passed ten of its eighteen, so eight
+    // controls existed and were unreachable — the same gap that made the stick
+    // kit's options source-only.
+    slant: z.number().optional().describe('apply_thread: stitch slant in DEGREES — satin (default 0) and stem (default 22). A satin fill laid at a slant is what separates embroidery from ruling.'),
+    overlap: z.number().min(0).optional().describe('apply_thread: how far consecutive stem stitches overlap (default 0.4) — what makes a stem outline read as rope rather than a dashed line.'),
+    stagger: z.number().min(0).max(1).optional().describe('apply_thread: offsets alternate longAndShort rows (default 0.5) — stops stitch ends lining up into seams down the fill.'),
+    gapLen: z.number().positive().optional().describe('apply_thread: gap between runningSeam stitches, px (default 4). With stitchLen, this is the dash rhythm of a machine seam.'),
+    gridSize: z.number().positive().optional().describe('apply_thread: crossStitch grid pitch, px (default 12) — the size of each X, and so the resolution of the whole fill.'),
+    roughness: z.number().min(0).optional()
+        .describe('apply_thread: hand wobble. Jitters every point of every stitch after the engine lays them, so the fill reads as sewn rather than plotted. 0 is machine-exact. Reproducible for a given seed. This one is applied by the tool, not the engine.'),
+    // --- Hatching (pp: the p5.brush marks, as vector) ---
+    //
+    // `field` above is the THREAD direction field (radial/spine/constant) and is
+    // a different thing from `flowField` here (hand/curved/waves/…). Separate
+    // names because one steers stitches around a form and the other bends a
+    // ruling line the way a hand would drift; sharing a key would silently apply
+    // one where the other was meant.
+    distance: z.number().positive().optional()
+        .describe('apply_hatch: spacing between lines in px (default 6). THIS IS THE VALUE CONTROL — the same shape at 6px and 3px reads as light and dark with no change of colour.'),
+    angle: z.number().optional().describe('apply_hatch: ruling angle in DEGREES (default 45).'),
+    gradient: z.number().min(0).max(1).optional()
+        .describe('apply_hatch: 0..1 spacing growth per line (default 0, even). Non-zero makes the density fall off across the shape — a shaded ramp rather than a flat tone.'),
+    rand: z.number().min(0).max(1).optional()
+        .describe('apply_hatch: jitter as a fraction of distance (default 0) — takes the mechanical evenness off.'),
+    continuous: z.boolean().optional()
+        .describe('apply_hatch: join the lines into ONE serpentine path (default false) — a pen that never leaves the paper, and a single item instead of many.'),
+    flowField: z.enum(['hand', 'curved', 'zigzag', 'waves', 'seabed', 'spiral', 'columns']).optional()
+        .describe('apply_hatch: bend each line along a flow field. The straight scanline is the ruling; the field is what makes it read as drawn rather than printed. See list_flow_fields.'),
+    t: z.number().optional().describe('apply_hatch: flow-field time offset — advances the field without changing the seed.'),
+})
+    .refine((v) => v.action !== 'apply_thread' || !!v.itemId, { message: 'apply_thread requires itemId', path: ['itemId'] })
+    .refine((v) => v.action !== 'resolve' || !!v.medium, { message: 'resolve requires medium', path: ['medium'] })
+    .refine((v) => v.action !== 'apply_hatch' || !!v.itemId, { message: 'apply_hatch requires itemId', path: ['itemId'] });
+export const TextEffectInputSchema = z.object({
+    action: z.enum(['apply', 'list'])
+        .describe("'apply' (explode a text item into animated characters) · 'list' (the 37 effects with key/label/definition, for a picker)"),
+    itemId: z.string().optional().describe('apply: the text item to animate. Must be a text item with non-whitespace content.'),
+    effect: z.string().optional().describe("apply: effect key from 'list' (e.g. scattered, decrypt, matrix, burn, fireworks, rain, blackhole)."),
+    duration: z.number().positive().optional().describe('apply: seconds for the whole effect (default 2.5). Every effect ends AT REST, so this is the settle time.'),
+    seed: z.number().int().optional().describe('apply: PRNG seed (default 1). Same seed + same text = identical animation, so exports are reproducible.'),
+    gradient: z.boolean().optional().describe("apply: false keeps each character's authored fill. Default TRUE — the upstream effects all end by painting the block with a gradient, which is what their reference frames show."),
+    gradientStops: z.array(z.string()).optional().describe('apply: hex colors overriding the effect\'s own gradient.'),
+    gradientDirection: z.enum(['vertical', 'horizontal', 'radial', 'diagonal']).optional().describe('apply: gradient axis across the text block.'),
+    gradientSteps: z.number().int().positive().optional().describe('apply: quantization steps in the gradient ramp.'),
+    keepSource: z.boolean().optional().describe('apply: leave the original text item in place instead of removing it — the escape hatch when relations/keyframes reference its id.'),
+    options: z.record(z.string(), z.unknown()).optional().describe('apply: per-effect knobs, passed through verbatim (each of the 37 has its own). Spread FIRST, so named fields above win on collision.'),
+})
+    .refine((v) => v.action !== 'apply' || (!!v.itemId && !!v.effect), { message: 'apply requires itemId and effect', path: ['effect'] });
 /**
  * pinepaper_shatter_image — split a raster into a grid of per-tile rasters.
  * Deliberately INERT on its own: the pieces sit exactly where the picture was
@@ -2839,8 +3483,19 @@ export const GameInputSchema = z.object({
  * itself — the tool does not restate it, so it cannot drift.
  */
 export const World3DInputSchema = z.object({
-    action: z.enum(['create', 'describe', 'configure', 'add_actor', 'remove_actor', 'list_actors', 'set_actor_pose', 'set_camera', 'add_object', 'remove_object', 'remove_world'])
-        .describe("'create' (a preset world) · 'describe' (every parameter with type/range — CALL THIS before configure) · 'configure' (live deep-merge patch, schema-validated) · actor ops · 'set_camera' (follow|fixed|orbit) · object ops · 'remove_world'"),
+    action: z.enum([
+        'create', 'describe', 'configure', 'add_actor', 'remove_actor', 'list_actors', 'set_actor_pose',
+        'set_camera', 'add_object', 'remove_object', 'remove_world',
+        'extrude_path', 'lathe_path', 'list_meshes', 'remove_mesh',
+        'add_light', 'set_light', 'remove_light', 'list_lights',
+        'add_material', 'set_material', 'remove_material', 'list_materials',
+        'import_obj', 'import_gltf', 'list_mesh_clips', 'set_mesh_clip',
+        'set_nav_target', 'get_nav_target', 'ground_height', 'raycast',
+        'dolly_camera', 'pan_camera', 'world_to_canvas', 'canvas_to_ground',
+        'add_body', 'remove_body', 'list_bodies', 'step_physics', 'impulse', 'set_velocity', 'fire_projectile',
+        'line_of_sight', 'set_mesh_instances',
+    ])
+        .describe("'create' (a preset world) · 'describe' (every parameter with type/range — CALL THIS before configure) · 'configure' (live deep-merge patch, schema-validated) · actor ops · 'set_camera' (follow|fixed|orbit) · object ops · 'remove_world' · MESH AUTHORING: 'extrude_path' / 'lathe_path' turn a canvas path into real geometry, 'list_meshes', 'remove_mesh' · 'add_light' / 'set_light' / 'remove_light' / 'list_lights' (at most 8 point lights) · 'add_material' / 'set_material' / 'remove_material' / 'list_materials'"),
     spec: z.union([z.string(), z.record(z.string(), z.unknown())]).optional().describe("create: a preset id ('forest', 'snowMountain', …) or a full world spec object."),
     character: z.union([z.boolean(), z.record(z.string(), z.unknown())]).optional().describe('create: include the walkable character (true/config).'),
     patch: z.record(z.string(), z.unknown()).optional().describe('configure: partial world spec, deep-merged and validated — a wrong key errors naming the right one.'),
@@ -2852,18 +3507,372 @@ export const World3DInputSchema = z.object({
     live: z.boolean().optional().describe('add_actor: re-rasterize the item as it animates — a rigged character PERFORMS in the world instead of standing there as a photograph of itself.'),
     pose: z.record(z.string(), z.unknown()).optional().describe('set_actor_pose: { x?, z?, angle?, … } — the setter a timeline or agent drives.'),
     camera: z.record(z.string(), z.unknown()).optional().describe("set_camera: { mode: 'follow'|'fixed'|'orbit', target?, radius?, speed?, eye?, lookAt? }."),
-    object: z.record(z.string(), z.unknown()).optional().describe('add_object: { x, z, height?, color?, y? (defaults to sitting on the terrain) }.'),
+    object: z.record(z.string(), z.unknown()).optional().describe("add_object: { x, z, height?, color?, y? } (defaults to sitting on the terrain). metalness and roughness are ACCEPTED AND IGNORED here: a plain object is drawn by the prop shader, which has no such uniform, so they are stored and listed and never reach a pixel. They render on the MESH path only — 'extrude_path' / 'lathe_path' and imported geometry. Use a material there instead of setting them here and seeing nothing."),
     objectId: z.string().optional().describe('remove_object: the object id.'),
+    // --- Mesh authoring: a canvas path becomes real geometry -----------------
+    pathId: z.string().optional().describe("extrude_path / lathe_path: the canvas path to turn into geometry. Extrude sweeps it along depth; lathe revolves its profile around the Y axis. The path is unchanged — the mesh is new."),
+    mesh: z.object({
+        id: z.string().optional().describe('Mesh id (generated if omitted).'),
+        depth: z.number().optional().describe('extrude_path: how far to sweep, in world units.'),
+        unitsPerPixel: z.number().optional().describe('Canvas pixels → world units. The whole scale relationship between the drawing and the world.'),
+        caps: z.boolean().optional().describe('extrude_path: close the two ends. A capped extrude is a solid; an uncapped one is a ribbon.'),
+        segments: z.number().optional().describe('extrude_path: segments along the sweep · lathe_path: segments around the revolution.'),
+        arc: z.number().optional().describe('lathe_path: how far round to revolve, in degrees. 360 is a full solid of revolution; less leaves it open.'),
+        flatness: z.number().optional().describe('Curve flattening tolerance when the path is sampled into rings — smaller is finer and heavier.'),
+        x: z.number().optional().describe('Placement in world space.'),
+        y: z.number().optional().describe('Placement in world space (omit to let it sit where the terrain puts it).'),
+        z: z.number().optional().describe('Placement in world space.'),
+        rotY: z.number().optional().describe('Rotation about the Y axis, in RADIANS — the value is stored raw and fed straight to cos()/sin() in the shader, with no conversion anywhere on the path. This is an exception to the degrees convention every other angle in this surface follows; pass rotYDegrees instead if you would rather write degrees. (`arc` on lathe_path IS degrees — the engine converts that one.)'),
+        rotYDegrees: z.number().optional().describe('Rotation about the Y axis in degrees, converted to radians for you. Convenience only — the engine and the mesh provenance record both speak rotY in radians, so a round-tripped capture uses rotY.'),
+        scale: z.number().optional().describe('Uniform scale applied after the geometry is built.'),
+        doubleSided: z.boolean().optional().describe('Draw back faces too. An uncapped extrude usually wants this.'),
+    }).optional().describe("extrude_path / lathe_path options. These field names ARE the ones the engine records as the mesh's provenance, so a mesh captured in a design graph can be rebuilt by spreading its meshProvenance.opts straight back in here."),
+    meshId: z.string().optional().describe('remove_mesh: the mesh id.'),
+    // --- Lights ---------------------------------------------------------------
+    light: z.object({
+        id: z.string().optional().describe('Light id (generated if omitted).'),
+        x: z.number().optional().describe('World-space x (default 0).'),
+        y: z.number().optional().describe('World-space y (default 3 — above the ground, not on it).'),
+        z: z.number().optional().describe('World-space z (default 0).'),
+        color: z.array(z.number()).length(3).optional().describe('Linear RGB, each component ≥ 0 (default [1, 0.86, 0.62], a warm lamp).'),
+        intensity: z.number().optional().describe('Brightness (default 6).'),
+        range: z.number().optional().describe('How far the light reaches, in world units (default 20).'),
+    }).optional().describe('add_light / set_light: the light spec. At most 8 point lights exist at once — the shader array is fixed-size, so a ninth is refused by name rather than ignored.'),
+    lightId: z.string().optional().describe('set_light / remove_light: the light id.'),
+    // --- Materials ------------------------------------------------------------
+    material: z.object({
+        id: z.string().optional().describe('Material id (generated if omitted).'),
+        color: z.array(z.number()).length(3).optional().describe('Base colour, linear RGB (default [0.8, 0.8, 0.82]).'),
+        emissive: z.array(z.number()).length(3).optional().describe('Light the surface emits regardless of the scene (default [0, 0, 0]).'),
+        metalness: z.number().min(0).max(1).optional().describe('0 dielectric → 1 metal.'),
+        roughness: z.number().min(0).max(1).optional().describe('0 mirror → 1 fully diffuse. Floored at 0.045: a true zero is a numerically unstable mirror.'),
+        emissiveIntensity: z.number().min(0).optional().describe('Scales `emissive` before the frame is built, so it reaches every path that draws emissive.'),
+        clearcoat: z.number().min(0).max(1).optional().describe('A lacquer layer over the base — car paint, varnished wood.'),
+        clearcoatRoughness: z.number().min(0).max(1).optional().describe("The coat's own roughness. NOT floored like the base, so a mirror-smooth lacquer stays expressible."),
+        sheenColor: z.array(z.number()).length(3).optional().describe('Retroreflective sheen colour — cloth, velvet.'),
+        sheenRoughness: z.number().min(0).max(1).optional().describe('How broad the sheen lobe is.'),
+    }).optional().describe("add_material / set_material: a NAMED, SHARED surface referenced by many objects, so one edit restyles all of them. metalness and roughness reach the shader on the MESH path only. There are no aoMapIntensity / normalScale / envMapIntensity knobs: each scales a map that does not exist, and a knob that scales nothing is worse than a missing one."),
+    materialId: z.string().optional().describe('set_material / remove_material: the material id.'),
+    // --- Import ---------------------------------------------------------------
+    source: z.string().optional().describe('import_obj: the OBJ file TEXT. import_gltf: a URL, or a data: URI of the .glb bytes.'),
+    importOptions: z.record(z.string(), z.unknown()).optional().describe('import_obj / import_gltf: placement and scale options, passed through to the engine.'),
+    clip: z.string().optional().describe('set_mesh_clip: which imported animation clip a skinned mesh plays.'),
+    crossfade: z.number().optional().describe('set_mesh_clip: seconds to blend out of the clip that was playing. The blend happens in LOCAL pose space — a palette cannot be blended after the fact.'),
+    // --- Navigation, picking and the camera ----------------------------------
+    navTarget: z.enum(['2d', '3d']).optional().describe("set_nav_target: which layer the pointer drives — '2d' the Paper canvas, '3d' the world."),
+    point: z.object({ x: z.number(), y: z.number(), z: z.number().optional() }).optional()
+        .describe('ground_height / canvas_to_ground / world_to_canvas: the point to convert. ground_height and canvas_to_ground read x and y (canvas) or x and z (world); world_to_canvas takes a world point.'),
+    origin: z.array(z.number()).length(3).optional().describe('raycast: ray origin in world space, [x, y, z].'),
+    direction: z.array(z.number()).length(3).optional().describe('raycast: ray direction in world space, [x, y, z]. Need not be normalised.'),
+    multiplier: z.number().optional().describe('dolly_camera: greater than 1 moves away, less than 1 moves closer.'),
+    dx: z.number().optional().describe('pan_camera: horizontal pan in SCREEN pixels.'),
+    dy: z.number().optional().describe('pan_camera: vertical pan in SCREEN pixels.'),
+    // --- Physics in the world -------------------------------------------------
+    body: z.record(z.string(), z.unknown()).optional()
+        .describe('add_body / fire_projectile: the body spec. Deliberately NARROW — a sphere or a capsule under gravity, colliding with the world (terrain, objects, actors, imported meshes). There is no stacking solver and no joints; for those use pinepaper_physics, which is the 2D world.'),
+    bodyId: z.string().optional().describe('remove_body / impulse / set_velocity: the body id.'),
+    vector: z.array(z.number()).length(3).optional().describe('impulse: the impulse to apply, [x, y, z]. set_velocity: the velocity to set, [x, y, z].'),
+    dt: z.number().optional().describe('step_physics: seconds to advance. Returns the contacts made and the bodies removed in that step.'),
+    from: z.array(z.number()).length(3).optional().describe('line_of_sight: the eye point, [x, y, z].'),
+    to: z.array(z.number()).length(3).optional().describe('line_of_sight: the target point, [x, y, z].'),
+    instances: z.array(z.array(z.number())).optional()
+        .describe('set_mesh_instances: one entry per copy, six numbers each — x, y, z, scale, rotY (RADIANS), and a free variant a shader may read for per-instance colour or phase.'),
 })
     .refine((v) => v.action !== 'configure' || !!v.patch, { message: 'configure requires patch', path: ['patch'] })
     .refine((v) => !['remove_actor', 'set_actor_pose'].includes(v.action) || !!v.actorId, { message: 'this action requires actorId', path: ['actorId'] })
     .refine((v) => v.action !== 'set_actor_pose' || !!v.pose, { message: 'set_actor_pose requires pose', path: ['pose'] })
     .refine((v) => v.action !== 'set_camera' || !!v.camera, { message: 'set_camera requires camera', path: ['camera'] })
     .refine((v) => v.action !== 'add_object' || !!v.object, { message: 'add_object requires object', path: ['object'] })
-    .refine((v) => v.action !== 'remove_object' || !!v.objectId, { message: 'remove_object requires objectId', path: ['objectId'] });
+    .refine((v) => v.action !== 'remove_object' || !!v.objectId, { message: 'remove_object requires objectId', path: ['objectId'] })
+    .refine((v) => !['extrude_path', 'lathe_path'].includes(v.action) || !!v.pathId, { message: 'this action requires pathId — the canvas path to turn into geometry', path: ['pathId'] })
+    .refine((v) => v.action !== 'remove_mesh' || !!v.meshId, { message: 'remove_mesh requires meshId', path: ['meshId'] })
+    .refine((v) => v.action !== 'add_light' || !!v.light, { message: 'add_light requires light', path: ['light'] })
+    .refine((v) => v.action !== 'set_light' || (!!v.lightId && !!v.light), { message: 'set_light requires lightId and light', path: ['lightId'] })
+    .refine((v) => v.action !== 'remove_light' || !!v.lightId, { message: 'remove_light requires lightId', path: ['lightId'] })
+    .refine((v) => v.action !== 'add_material' || !!v.material, { message: 'add_material requires material', path: ['material'] })
+    .refine((v) => v.action !== 'set_material' || (!!v.materialId && !!v.material), { message: 'set_material requires materialId and material', path: ['materialId'] })
+    .refine((v) => v.action !== 'remove_material' || !!v.materialId, { message: 'remove_material requires materialId', path: ['materialId'] })
+    .refine((v) => !['import_obj', 'import_gltf'].includes(v.action) || !!v.source, { message: 'this action requires source', path: ['source'] })
+    .refine((v) => !['list_mesh_clips', 'set_mesh_clip'].includes(v.action) || !!v.meshId, { message: 'this action requires meshId', path: ['meshId'] })
+    .refine((v) => v.action !== 'set_mesh_clip' || !!v.clip, { message: 'set_mesh_clip requires clip', path: ['clip'] })
+    .refine((v) => v.action !== 'set_nav_target' || !!v.navTarget, { message: 'set_nav_target requires navTarget', path: ['navTarget'] })
+    .refine((v) => !['ground_height', 'canvas_to_ground', 'world_to_canvas'].includes(v.action) || !!v.point, { message: 'this action requires point', path: ['point'] })
+    .refine((v) => v.action !== 'raycast' || (!!v.origin && !!v.direction), { message: 'raycast requires origin and direction', path: ['origin'] })
+    .refine((v) => v.action !== 'dolly_camera' || v.multiplier !== undefined, { message: 'dolly_camera requires multiplier', path: ['multiplier'] })
+    .refine((v) => v.action !== 'pan_camera' || (v.dx !== undefined && v.dy !== undefined), { message: 'pan_camera requires dx and dy', path: ['dx'] })
+    .refine((v) => !['add_body', 'fire_projectile'].includes(v.action) || !!v.body, { message: 'this action requires body', path: ['body'] })
+    .refine((v) => !['remove_body', 'impulse', 'set_velocity'].includes(v.action) || !!v.bodyId, { message: 'this action requires bodyId', path: ['bodyId'] })
+    .refine((v) => !['impulse', 'set_velocity'].includes(v.action) || !!v.vector, { message: 'this action requires vector', path: ['vector'] })
+    .refine((v) => v.action !== 'step_physics' || v.dt !== undefined, { message: 'step_physics requires dt', path: ['dt'] })
+    .refine((v) => v.action !== 'line_of_sight' || (!!v.from && !!v.to), { message: 'line_of_sight requires from and to', path: ['from'] })
+    .refine((v) => v.action !== 'set_mesh_instances' || (!!v.meshId && !!v.instances), { message: 'set_mesh_instances requires meshId and instances', path: ['meshId'] });
 // =============================================================================
 // ONE-SHOT IMAGE OPS (crop / chroma key — Track A agent parity, 2026-07-31)
 // =============================================================================
+/**
+ * pinepaper_design_system — the design vocabulary, as data an agent can read.
+ *
+ * TWO DIFFERENT THINGS, deliberately not merged, because the upstream is
+ * explicit that they are not the same:
+ *
+ *  - A DESIGN SYSTEM is a real, licensed, versioned product — Material 3,
+ *    IBM Carbon, Polaris, Fluent 2, USWDS, GOV.UK. Its tokens are facts with a
+ *    licence attached, expressed in the W3C DTCG format ($value, $type,
+ *    $description). Where a motion token had to be filled in because the
+ *    published system does not specify one, it is marked
+ *    `pinepaper:authored` — so a caller can tell a vendor's curve from ours.
+ *  - An AESTHETIC STYLE is a look: Bauhaus, Art Deco, Swiss, vaporwave,
+ *    risograph. It carries no licence and no vendor. Eighteen of them can
+ *    COMPOSE a scene rather than only describe one.
+ *
+ * These run in this server, not in the browser. The generators are pure
+ * functions over numbers, so the scene is computed here and arrives as items;
+ * nothing about a design vocabulary needs the canvas to be open to decide it.
+ */
+export const DesignSystemInputSchema = z.object({
+    action: z.enum(['list_systems', 'get_system', 'list_easings', 'list_styles', 'compose'])
+        .describe("'list_systems' every licensed design system with its vendor, licence and version · 'get_system' one system's full DTCG tokens · 'list_easings' every motion curve across all of them as named easings, with provenance · 'list_styles' the aesthetic styles and which can compose · 'compose' build a scene in a style."),
+    systemId: z.string().optional().describe("get_system: which system, e.g. 'material_3', 'ibm_carbon', 'uswds'. Call list_systems for the ids."),
+    tokenType: z.enum(['dimension', 'duration', 'cubicBezier', 'color', 'fontFamily', 'fontWeight', 'number', 'shadow', 'grid']).optional()
+        .describe('get_system: return only tokens of this DTCG type.'),
+    style: z.string().optional().describe("compose: the aesthetic style, e.g. 'bauhaus_geometric', 'art_deco_geometric', 'vaporwave_retro'. Call list_styles for the ones that can compose."),
+    title: z.string().optional().describe('compose: the headline. Most styles are poster-shaped and build around it.'),
+    subtitle: z.string().optional().describe('compose: the supporting line.'),
+    body: z.string().optional().describe('compose: optional body copy, where the style has somewhere to put it.'),
+    width: z.number().optional().describe('compose: canvas width (the style picks its own default otherwise).'),
+    height: z.number().optional().describe('compose: canvas height.'),
+    variant: z.string().optional().describe("compose: a style-specific variant where one exists, e.g. art deco's emerald colourway."),
+    draw: z.boolean().optional().default(true)
+        .describe('compose: draw the scene on the canvas (default). false returns the computed scene as DATA and draws nothing — the same distinction story\'s `distill` makes, and for the same reason: a caller should be able to read a composition before committing to it.'),
+    authoredOnly: z.boolean().optional().describe('list_easings: return only the curves PinePaper authored to fill a gap, or only the ones a vendor actually publishes, rather than both mixed together.'),
+})
+    .refine((v) => v.action !== 'get_system' || !!v.systemId, { message: 'get_system requires systemId — call list_systems for the ids', path: ['systemId'] })
+    .refine((v) => v.action !== 'compose' || !!v.style, { message: 'compose requires style — call list_styles for the ones that can compose', path: ['style'] })
+    .refine((v) => v.action !== 'compose' || !!v.title, { message: 'compose requires title', path: ['title'] });
+/**
+ * pinepaper_stick — the vendored stick-figure kit.
+ *
+ * A different construction from pinepaper_character, which places a figure
+ * from the design graph by concept. This is the stick kit: a rigged figure
+ * posed, walking, travelling, holding a prop, with a garment and hair — plus
+ * `set`, which builds the furniture it stands on and among.
+ *
+ * The geometry is vendored from mcp-cloud, so this is a three-repo artifact:
+ * a change to the kit lands there first and is re-vendored into FxTool.
+ */
+export const StickInputSchema = z.object({
+    action: z.enum(['figure', 'set']).describe("'figure' a posed, walking or travelling stick figure · 'set' the floor, wall and objects it stands on and among."),
+    id: z.string().optional().describe('Prefix for the created items.'),
+    kind: z.string().optional().describe("figure: which figure. set: which piece of the scene kit ('floor', 'wall', a named object) — list-free, because the kit is vendored and grows there."),
+    at: z.object({ x: z.number().optional(), y: z.number().optional() }).optional().describe('Where it goes.'),
+    scale: z.number().optional().describe('Size multiplier.'),
+    facing: z.enum(['left', 'right']).optional().describe('Which way the figure looks.'),
+    pose: z.string().optional().describe("figure: a named pose from the kit's POSES."),
+    poseAt: z.number().optional().describe('figure: the time, in seconds, at which that pose is struck.'),
+    expression: z.string().optional().describe("figure: a single facial expression from the kit's EXPRESSIONS."),
+    expressions: z.array(z.object({ at: z.number(), name: z.string() })).optional().describe('figure: expressions over time, each at a moment.'),
+    walk: z.union([z.boolean(), z.record(z.string(), z.unknown())]).optional().describe('figure: a walk cycle — true for the default, or a config.'),
+    travel: z.record(z.string(), z.unknown()).optional().describe('figure: move the figure across the scene while it walks, rather than walking in place.'),
+    prop: z.string().optional().describe('figure: something held in hand.'),
+    propSide: z.enum(['left', 'right']).optional().describe('figure: which hand holds it.'),
+    garment: z.string().optional().describe('figure: clothing.'),
+    trouser: z.string().optional().describe('figure: legwear.'),
+    hair: z.string().optional().describe('figure: hair style.'),
+    withHair: z.boolean().optional().describe('figure: draw hair at all.'),
+    groundY: z.number().optional().describe('The y the figure stands on.'),
+    surfaceY: z.number().optional().describe('The y of the surface an object sits on.'),
+    durationSeconds: z.number().optional().describe('figure: length of the performance, so every track spans it.'),
+    object: z.record(z.string(), z.unknown()).optional().describe('set: the object spec.'),
+    items: z.array(z.record(z.string(), z.unknown())).optional().describe('set: several pieces at once.'),
+    floor: z.union([z.boolean(), z.record(z.string(), z.unknown())]).optional().describe('set: draw a floor.'),
+    wall: z.union([z.boolean(), z.record(z.string(), z.unknown())]).optional().describe('set: draw a wall.'),
+});
+/**
+ * pinepaper_story — a piece of prose becomes a scene.
+ *
+ * `distill` reduces an article to its beats WITHOUT drawing anything, which is
+ * the half worth having on its own: a caller can read what the distiller made
+ * of the text, edit it, and only then assemble. `from_text` does both in one
+ * call, `apply_spec` assembles a spec you already have, and `plan_book` lays
+ * images out as pages.
+ */
+export const StoryInputSchema = z.object({
+    action: z.enum(['distill', 'from_text', 'apply_spec', 'plan_book'])
+        .describe("'distill' text → story beats, drawing NOTHING · 'from_text' distill and assemble in one call · 'apply_spec' assemble a spec you already have · 'plan_book' lay images out as pages."),
+    text: z.string().optional().describe('distill / from_text: the prose.'),
+    spec: z.record(z.string(), z.unknown()).optional().describe('apply_spec: the story spec — usually one from `distill`, edited.'),
+    images: z.array(z.union([z.string(), z.record(z.string(), z.unknown())])).optional().describe('plan_book: the images to lay out, as ids or specs.'),
+    options: z.record(z.string(), z.unknown()).optional().describe('Assembly or layout options, passed through.'),
+})
+    .refine((v) => !['distill', 'from_text'].includes(v.action) || !!v.text, { message: 'this action requires text', path: ['text'] })
+    .refine((v) => v.action !== 'apply_spec' || !!v.spec, { message: 'apply_spec requires spec', path: ['spec'] })
+    .refine((v) => v.action !== 'plan_book' || (Array.isArray(v.images) && v.images.length > 0), { message: 'plan_book requires images', path: ['images'] });
+/**
+ * pinepaper_interchange — the formats other tools read and write.
+ *
+ * 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 — and they had no tool at all.
+ *
+ * Import is here too, because a format you can only write is half a bridge.
+ */
+export const InterchangeInputSchema = z.object({
+    action: z.enum(['export_lottie', 'export_dotlottie', 'import_lottie', 'export_glb', 'export_bvh', 'export_png_sequence'])
+        .describe("'export_lottie' (JSON) · 'export_dotlottie' (the zipped .lottie) · 'import_lottie' (a Lottie or .lottie back onto the canvas) · 'export_glb' (the perspective 3D objects — needs some to exist) · 'export_bvh' (a skeleton's motion — needs a rig) · 'export_png_sequence' (one file per frame)."),
+    options: z.record(z.string(), z.unknown()).optional().describe('Format options, passed through to the exporter: frame range, dimensions, fps, naming.'),
+    data: z.union([z.string(), z.record(z.string(), z.unknown())]).optional()
+        .describe('import_lottie: the Lottie JSON — an object, a JSON string, or a URL.'),
+    skeletonId: z.string().optional().describe('export_bvh: which skeleton to write. A BVH is one skeleton\'s motion, so this is not optional in practice.'),
+})
+    .refine((v) => v.action !== 'import_lottie' || v.data !== undefined, { message: 'import_lottie requires data', path: ['data'] })
+    .refine((v) => v.action !== 'export_bvh' || !!v.skeletonId, { message: 'export_bvh requires skeletonId — a BVH is one skeleton\'s motion', path: ['skeletonId'] });
+/**
+ * pinepaper_sound — synthesis, and the drawing that is the same object.
+ *
+ * The engine carries a whole audio graph: tones, chords, named percussion and
+ * SFX, plain-language sound descriptions, and — the part worth the tool — a
+ * two-way bridge between a sound and a Paper path. `create` draws a sound as a
+ * waveform path you can then edit; `timbre_from_path` reads any drawn path
+ * back as a timbre. A curve someone drew becomes the harmonic content of a
+ * note.
+ *
+ * None of it was reachable. `pinepaper_audio_beats` analyses audio that
+ * already exists; this makes audio.
+ */
+export const SoundInputSchema = z.object({
+    action: z.enum([
+        'list_instruments', 'list_percussion', 'list_sfx',
+        'play_tone', 'play_chord', 'chord_frequencies', 'play_percussion', 'play_sfx',
+        'play_spec', 'from_text', 'play_from_text',
+        'create', 'timbre_from_path', 'set_placement', 'remove', 'stop_all',
+        'define_instrument', 'define_percussion', 'define_sfx', 'render_soundtrack',
+    ]).describe("Catalogues: 'list_instruments' · 'list_percussion' · 'list_sfx'. Play: 'play_tone' · 'play_chord' · 'play_percussion' · 'play_sfx' · 'play_spec' · 'play_from_text'. Read without playing: 'chord_frequencies' · 'from_text' (a plain-language description resolved to a spec) · 'timbre_from_path'. Canvas: 'create' (a sound drawn AS a waveform path) · 'set_placement' · 'remove' · 'stop_all'. Define: 'define_instrument' · 'define_percussion' · 'define_sfx' — the six built-in instruments are a starting set, not a claim that music contains six; anything missing can be defined here and is then first-class, listed by the list_* actions and playable by name. Render: 'render_soundtrack' — mix every placed sound to a WAV file offline, with no Web Audio and no playback."),
+    note: z.string().optional().describe("play_tone: scientific pitch, e.g. 'A4' or 'C#3'."),
+    root: z.string().optional().describe("play_chord / chord_frequencies: the root note, e.g. 'C4'."),
+    chord: z.string().optional().default('major').describe("play_chord / chord_frequencies: the chord kind, e.g. 'major', 'minor', 'maj7', 'dim'. Call the engine rather than guessing at exotic names."),
+    name: z.string().optional().describe("play_percussion / play_sfx: the named drum or effect — list them first (SFX include beep, pop, wind, whoosh, zap). define_*: the name to register under. It is NORMALISED to [a-z][a-z0-9_-]{0,31}, so 'Rhodes' registers as 'rhodes' — the response returns the canonical name the engine chose, and that is the name to play."),
+    partials: z.array(z.object({
+        h: z.number().positive().describe('Harmonic number — 1 is the fundamental, 2 the octave above.'),
+        amp: z.number().min(0).describe('Relative amplitude of this partial.'),
+    })).optional().describe("define_*: the harmonic table that IS the timbre. Required for define_instrument — a melodic instrument with no partials renders pure silence, and the engine refuses rather than handing back a note nobody can hear. Percussion and SFX may use noise instead."),
+    envelope: z.object({
+        attack: z.number().min(0).optional(),
+        decay: z.number().min(0).optional(),
+        sustain: z.number().min(0).max(1).optional(),
+        release: z.number().min(0).optional(),
+    }).optional().describe('define_*: ADSR shape, in seconds except sustain which is a level (0-1).'),
+    gain: z.number().min(0).max(1).optional().describe('define_*: output level. Defaults differ by kind — 0.8 instrument, 0.85 percussion, 0.65 sfx.'),
+    aliases: z.array(z.string()).optional().describe("define_*: extra names reaching the same sound, so 'rhodes' can also answer to 'electric piano'. An alias NEVER shadows a real catalogue entry — the table is consulted first — so aliasing an existing name is silently ignored rather than overriding it."),
+    noise: z.number().min(0).max(1).optional().describe('define_percussion / define_sfx: noise content. A hat, a clap, wind and whoosh are pure noise, so these two kinds accept a partial table OR noise > 0; with neither the engine refuses, because the result is silent.'),
+    noiseFreq: z.number().positive().optional().describe('define_percussion / define_sfx: centre frequency of the noise band, in Hz.'),
+    hz: z.number().positive().optional().describe('define_percussion / define_sfx: base frequency in Hz.'),
+    pitch: z.object({
+        from: z.number().positive().describe('Starting frequency in Hz.'),
+        tau: z.number().positive().max(5).describe('Glide time constant in seconds (max 5).'),
+    }).optional().describe("define_percussion / define_sfx: the pitch glide, which is what makes a kick a kick — the engine's own note is that the glide IS the drum. Omit it and a defined kick comes out a beep."),
+    sampleRate: z.number().int().positive().optional().describe('render_soundtrack: samples per second (default 48000).'),
+    bitDepth: z.union([z.literal(16), z.literal(32)]).optional().describe('render_soundtrack: 16 (default) or 32-bit float.'),
+    text: z.string().optional().describe("from_text / play_from_text: a plain-language description, e.g. 'a soft warm bell on A4'. 'from_text' resolves it to a spec WITHOUT playing, so a caller can inspect or edit before committing."),
+    spec: z.record(z.string(), z.unknown()).optional().describe('play_spec / create: the sound spec — partials, envelope, duration. Usually one you got from from_text or a catalogue entry rather than wrote by hand.'),
+    options: z.record(z.string(), z.unknown()).optional().describe('Playback options for the play_* actions: duration, gain, pan, and the rest the audio graph accepts.'),
+    itemId: z.string().optional().describe('timbre_from_path: the path whose SHAPE becomes the harmonic content. set_placement / remove: the sound item.'),
+    samples: z.number().int().positive().optional().describe('timbre_from_path: how many points to sample along the path (default 256). More is a finer timbre and a slower read.'),
+    placement: z.record(z.string(), z.unknown()).optional().describe('set_placement: where and when the sound sits on the timeline.'),
+    visual: z.object({
+        width: z.number().optional().describe('Waveform path width in canvas units (default 220).'),
+        height: z.number().optional().describe('Waveform path height in canvas units (default 64).'),
+        position: z.object({ x: z.number(), y: z.number() }).optional(),
+        color: z.string().optional(),
+    }).optional().describe('create: how the waveform path is drawn. The sound IS this item — edit the path and the timbre changes with it.'),
+})
+    .refine((v) => v.action !== 'play_tone' || !!v.note, { message: 'play_tone requires note', path: ['note'] })
+    .refine((v) => !['play_chord', 'chord_frequencies'].includes(v.action) || !!v.root, { message: 'this action requires root', path: ['root'] })
+    .refine((v) => !['play_percussion', 'play_sfx'].includes(v.action) || !!v.name, { message: 'this action requires name — list the catalogue first', path: ['name'] })
+    .refine((v) => !['from_text', 'play_from_text'].includes(v.action) || !!v.text, { message: 'this action requires text', path: ['text'] })
+    .refine((v) => v.action !== 'play_spec' || !!v.spec, { message: 'play_spec requires spec', path: ['spec'] })
+    .refine((v) => !['timbre_from_path', 'set_placement', 'remove'].includes(v.action) || !!v.itemId, { message: 'this action requires itemId', path: ['itemId'] })
+    .refine((v) => v.action !== 'set_placement' || !!v.placement, { message: 'set_placement requires placement', path: ['placement'] })
+    .refine((v) => !['define_instrument', 'define_percussion', 'define_sfx'].includes(v.action) || !!v.name, { message: 'defining a sound requires name', path: ['name'] })
+    // The engine's own rule, stated here so the refusal arrives before the round
+    // trip: a melodic instrument needs partials, while percussion and SFX may be
+    // pure noise. Mirrored rather than tightened — tightening it would refuse a
+    // hat, which is exactly the sound that has no partials.
+    .refine((v) => v.action !== 'define_instrument' || (v.partials?.length ?? 0) > 0, { message: 'define_instrument requires at least one partial — an instrument with none renders silence', path: ['partials'] })
+    .refine((v) => !['define_percussion', 'define_sfx'].includes(v.action)
+    || (v.partials?.length ?? 0) > 0 || (v.noise ?? 0) > 0, { message: 'this action needs a partial table or noise > 0 — with neither the sound is silent', path: ['noise'] })
+    // Bound by the scene, like every other timed export.
+    .refine((v) => v.action !== 'render_soundtrack' || (v.options?.duration ?? 1) <= VIDEO_MAX_DURATION_S, { message: `render_soundtrack duration is capped at ${VIDEO_MAX_DURATION_S}s, the same ceiling as video`, path: ['options'] });
+/**
+ * pinepaper_motion — the generators' Animation knob, pointed at anything.
+ *
+ * The same engine every generator's own animation runs on, reachable for any
+ * group or list of items. Two kinds: a GROUP motion (drift, sway, rotate,
+ * pulse, wave, bounce) moves the target as one; a FIELD motion (ripple,
+ * breathe, undulate) sweeps a crest through the children from an origin, with
+ * a chosen waveform. The field kind is the one nothing else here can do.
+ *
+ * `list` first. The catalogue is the engine's own and names every motion,
+ * waveform and origin it will accept — the alternative is guessing at an enum
+ * that moves.
+ */
+export const MotionInputSchema = z.object({
+    action: z.enum(['list', 'apply']).describe("'list' every motion, waveform and origin the engine offers · 'apply' one to a target."),
+    itemId: z.string().optional().describe('apply: a group or single item to move.'),
+    itemIds: z.array(z.string()).optional().describe('apply: several items, wrapped in a new group that becomes the motion host. The members keep their own identity and ids.'),
+    motion: z.string().optional().describe("apply: the motion name — a GROUP motion (drift, sway, rotate, pulse, wave, bounce) moves the target as one; a FIELD motion (ripple, breathe, undulate) sweeps a crest through its children. Call 'list' for the engine's own set rather than guessing."),
+    speed: z.number().optional().describe('apply: cycles per second, roughly. Higher is faster.'),
+    intensity: z.number().optional().describe('apply: amplitude. 0.15 is the usual default elsewhere in this surface.'),
+    waveform: z.enum(['sine', 'triangle', 'square', 'sawtooth', 'spike']).optional()
+        .describe("apply: the shape of one cycle. 'spike' is a narrow bump — it was called 'pulse' until the engine noticed one word was naming both a waveform and an animation; the old spelling is still accepted on the way in, but 'spike' is the name."),
+    origin: z.enum(['center', 'topLeft', 'topRight', 'bottomLeft', 'bottomRight', 'left', 'right', 'top', 'bottom', 'random', 'roam']).optional()
+        .describe("apply, FIELD motions only: where the crest starts and sweeps from. 'random' gives every element its own phase (a twinkle rather than a wave); 'roam' hops between the corners and the centre."),
+    seed: z.number().optional().describe('apply: makes a random origin reproducible — the same seed lays out the same phases every run.'),
+})
+    .refine((v) => v.action !== 'apply' || !!v.itemId || (Array.isArray(v.itemIds) && v.itemIds.length > 0), { message: 'apply requires itemId or itemIds', path: ['itemId'] })
+    .refine((v) => v.action !== 'apply' || !!v.motion, { message: "apply requires motion — call action 'list' for the names the engine accepts", path: ['motion'] });
+/**
+ * pinepaper_path — the destructive path operations Paper.js has always had and
+ * nothing here could reach: booleans, simplify, outline-stroke, open/close,
+ * repeat patterns, plus read-back geometry and a lock.
+ *
+ * Every one of these REPLACES or ADDS items rather than restyling them, which
+ * is why they live together and away from `pinepaper_modify_item`: a boolean
+ * consumes its operands, and an outlined stroke is a new filled shape where a
+ * stroked line used to be. The engine refuses each by name — "a boolean needs
+ * at least two paths", "that path has no stroke to outline" — and those
+ * refusals are passed through rather than reworded.
+ */
+export const PathOpInputSchema = z.object({
+    action: z.enum(['boolean', 'simplify', 'outline_stroke', 'toggle_closed', 'pattern', 'get_geometry', 'set_locked', 'unlock_all'])
+        .describe("'boolean' (unite|subtract|intersect|exclude|divide, consumes its operands) · 'simplify' (fewer segments, same shape) · 'outline_stroke' (a stroked line becomes a filled shape) · 'toggle_closed' · 'pattern' (repeat an item: concentric|radial|grid|extrude) · 'get_geometry' (read segments back) · 'set_locked' / 'unlock_all'"),
+    itemId: z.string().optional().describe('The item to operate on — every action except boolean and unlock_all.'),
+    itemIds: z.array(z.string()).optional().describe('boolean: at least two paths. The FIRST is the base; the rest are applied to it in order.'),
+    op: z.enum(['unite', 'subtract', 'intersect', 'exclude', 'divide']).optional().default('unite')
+        .describe("boolean: 'unite' merges · 'subtract' removes the later shapes from the first · 'intersect' keeps the overlap · 'exclude' keeps everything but the overlap · 'divide' splits into every region."),
+    tolerance: z.number().positive().optional()
+        .describe('simplify: how far the new curve may stray, in canvas units (default 2.5 — higher is fewer points and a looser shape). outline_stroke: flattening tolerance (defaults to an eighth of the stroke radius).'),
+    kind: z.enum(['concentric', 'radial', 'grid', 'extrude']).optional().default('radial')
+        .describe("pattern: 'concentric' rings outward · 'radial' around a circle · 'grid' rows and columns · 'extrude' a depth-wise stack."),
+    pattern: z.object({
+        count: z.number().optional().describe('concentric / radial / extrude: how many copies.'),
+        radius: z.number().optional().describe('radial / concentric: distance from the original.'),
+        angle: z.number().optional().describe('radial: total sweep in DEGREES (360 is a full ring).'),
+        phase: z.number().optional().describe('radial: where the first copy starts, in DEGREES.'),
+        rows: z.number().optional().describe('grid: row count.'),
+        cols: z.number().optional().describe('grid: column count.'),
+        gapX: z.number().optional().describe('grid: horizontal spacing in canvas units.'),
+        gapY: z.number().optional().describe('grid: vertical spacing in canvas units.'),
+        step: z.number().optional().describe('extrude / concentric: spacing between successive copies.'),
+        depth: z.number().optional().describe('extrude: total depth the stack spans.'),
+        rotateItems: z.boolean().optional().describe('radial: turn each copy to face along the ring instead of keeping its original angle.'),
+        shade: z.boolean().optional().describe('extrude: darken copies with depth, so the stack reads as receding.'),
+        shadeStrength: z.number().optional().describe('extrude: how strong that darkening is.'),
+    }).optional().describe('pattern options. Copies are capped — past a few hundred this stops being a drawing aid and becomes a generator, which is a different tool.'),
+    locked: z.boolean().optional().default(true).describe('set_locked: true locks (also clearing selectable and draggable, so it cannot be grabbed), false unlocks.'),
+})
+    .refine((v) => v.action !== 'boolean' || (Array.isArray(v.itemIds) && v.itemIds.length >= 2), { message: 'boolean requires itemIds with at least two paths', path: ['itemIds'] })
+    .refine((v) => ['boolean', 'unlock_all'].includes(v.action) || !!v.itemId, { message: 'this action requires itemId', path: ['itemId'] });
 export const CropImageInputSchema = z.object({
     itemId: z.string().describe('Registry id of the raster item (or a group containing one).'),
     rect: z.object({
@@ -2892,7 +3901,71 @@ export const RiggingInputSchema = z.object({
         'create_skeleton', 'add_bone', 'attach_item', 'create_ik_chain',
         'add_pose_keyframe', 'set_target_path', 'save_pose', 'save_shape_key',
         'import_bvh', 'retarget_bvh', 'import_spine',
+        // ── Pose motion. The engine has had these for releases; nothing could
+        // reach them, which is not the same as their not existing.
+        'list_skeletons', 'list_bones', 'list_poses', 'load_pose', 'interpolate_poses',
+        'list_pose_libraries', 'load_pose_library',
+        'play_pose_sequence', 'stop_pose_sequence', 'stitch_poses',
+        'apply_pose_transition',
+        'auto_walk', 'auto_breath', 'auto_idle', 'auto_jump',
+        'move_root', 'stop_root_track',
+        'add_secondary_motion', 'skin_path', 'bake_animation',
+        'list_shape_keys', 'load_shape_key',
     ]).describe('Rigging operation'),
+    // ── Pose motion ────────────────────────────────────────────────────────
+    poseId: z.string().optional().describe('Saved pose id — load_pose.'),
+    poseIdA: z.string().optional().describe('First pose — interpolate_poses.'),
+    poseIdB: z.string().optional().describe('Second pose — interpolate_poses.'),
+    t: z.number().min(0).max(1).optional().describe('Blend 0=A … 1=B — interpolate_poses.'),
+    /**
+     * A pose sequence: keys over normalized time, each naming a SAVED pose or an
+     * inline { boneId: angleDeg } map. The saved-pose form is the point — an
+     * animation that is literally a graph over the poses in the Poses panel.
+     */
+    sequence: z.array(z.object({
+        t: z.number().describe('Time (normalized within the clip unless duration is given).'),
+        pose: z.string().optional().describe('Saved pose id.'),
+        angles: z.record(z.string(), z.number()).optional().describe('Inline { boneId: angleDeg }.'),
+        ease: z.string().optional(),
+    })).optional().describe('Pose keys — play_pose_sequence.'),
+    /**
+     * Clips to STITCH into one continuous performance. Each clip is a sequence
+     * plus how it joins: `repeat` plays it N times, `loop` marks it cyclic (only
+     * a cyclic clip can be phase-matched), `blend` is the seam overlap.
+     */
+    clips: z.array(z.object({
+        keys: z.array(z.object({
+            t: z.number().optional(),
+            pose: z.string().optional(),
+            angles: z.record(z.string(), z.number()).optional(),
+            ease: z.string().optional(),
+        })).optional(),
+        poses: z.array(z.object({
+            pose: z.string().optional(),
+            angles: z.record(z.string(), z.number()).optional(),
+        })).optional().describe('Bare list — spread evenly across the clip.'),
+        duration: z.number().positive().optional(),
+        repeat: z.number().int().min(1).max(200).optional(),
+        loop: z.boolean().optional().describe('Cyclic: can be entered at any phase.'),
+        blend: z.number().min(0).optional().describe('Override the seam overlap into this clip.'),
+        matchPhase: z.boolean().optional(),
+    })).optional().describe('Clips in order — stitch_poses.'),
+    blend: z.number().min(0).optional().describe('Seam overlap in seconds (default 0.25) — stitch_poses.'),
+    blendSteps: z.number().int().min(2).max(64).optional().describe('Keys emitted across a seam (default 6) — stitch_poses.'),
+    matchPhase: z.boolean().optional().describe('Enter a cyclic clip at the phase closest to where the last one ended (default true) — stitch_poses.'),
+    plan: z.boolean().optional().describe('Return the seams WITHOUT installing the result — stitch_poses. Read `residual` per seam: it is the mismatch the blend is hiding, in degrees.'),
+    libraryName: z.string().optional().describe("Stock pose set — load_pose_library. The LIBRARIES are rig shapes: humanoid, quadruped, bird, fish. Loading one saves its poses (idle, walk_00…walk_07, walk_contact_L, run_*, …) against your bones. The walk/run/flap SEQUENCES are transitions, not libraries — play those with apply_pose_transition once the library is loaded. list_pose_libraries returns both lists."),
+    boneMap: z.record(z.string(), z.string()).optional().describe('Bone NAME → bone id — load_pose_library. Omit and it is built from list_bones, which is what you want unless the rig uses non-standard names.'),
+    transitionName: z.string().optional().describe('Named pose transition — apply_pose_transition.'),
+    poseIdMap: z.record(z.string(), z.string()).optional().describe('Transition pose name → saved pose id — apply_pose_transition.'),
+    boneNames: z.array(z.string()).optional().describe('Ordered bone names for a spring chain — add_secondary_motion.'),
+    keyframes: z.array(z.object({
+        t: z.number().describe('SCENE SECONDS, not a 0..1 fraction.'),
+        x: z.number(), y: z.number(), ease: z.string().optional(),
+    })).optional().describe('World root positions over SCENE TIME — move_root. This is what makes a figure travel instead of walking on the spot. `t` is in seconds on the same clock as the pose sequence, so match the last keyframe to the performance duration or the figure arrives early and stands there. Pass options.loop with options.period to cycle it.'),
+    shapeKeyId: z.string().optional().describe('Saved shape key id — load_shape_key.'),
+    weight: z.number().optional().describe('Shape key weight 0..1 (default 1) — load_shape_key.'),
+    options: z.record(z.string(), z.unknown()).optional().describe('Pass-through options for auto_* / bake_animation / move_root / skin_path / play_pose_sequence.'),
     // ── Mocap / rig import (import_bvh, retarget_bvh, import_spine) ──
     // The file CONTENTS travel in the call (MCP has no filesystem): .bvh text for
     // BVH, the exported .json for Spine. import_bvh builds a NEW stick-figure rig