@pinepaper.studio/mcp-server 1.5.0 → 1.5.1

package/dist/prompts/index.js

@@ -1,38 +1,12 @@
 /**
  * MCP Prompts — Template Recipes
  *
- * Each prompt replicates a specific PinePaper template pattern.
- * The assistant message is kept ultra-concise to prevent:
- * - Token waste from verbose planning
- * - Pipeline restarts from step-by-step tool lists
- * - Duplicate items from re-execution
- *
- * Rules:
- * - User message: frames the request with the user's description
- * - Assistant message: short commitment to single-pass execution
- * - Visual templates: use SINGLE_PASS_RULES (batch_execute) with layer labels (CANVAS/ITEMS/ANIMATE/EFFECTS/PLAY)
- * - Diagram templates: use DIAGRAM_RULES (create_diagram_shape + connect + auto_layout)
- * - NEVER restart the pipeline
+ * Each prompt frames a user request as a single user message.
+ * No assistant pre-fill — let the model respond naturally.
+ * Workflow rules are handled by start_job guidance and tool descriptions.
  */
 // -----------------------------------------------------------------------------
-// Shared rules injected into every assistant message
-// -----------------------------------------------------------------------------
-const SINGLE_PASS_RULES = `RULES — follow exactly:
-- start_job → batch_execute (ALL operations in ONE call) → end_job (screenshot) → show user → iterate
-- batch_execute supports: set_canvas_size, set_background, execute_generator, create, modify, delete, animate, keyframe_animate, relation, apply_mask, apply_effect, play_timeline
-- Use execute_generator for rich backgrounds (drawBokeh, drawGradientMesh, drawWaves, etc.) — much better than solid colors
-- NEVER restart the pipeline — if user wants changes, modify items or start a new job
-- After end_job, SHOW the screenshot and ask user if the design looks good`;
-const DIAGRAM_RULES = `RULES — follow exactly:
-- start_job → create shapes (pinepaper_create_diagram_shape) → connect (pinepaper_connect) → optionally auto_layout → end_job
-- Analyze the description to infer ALL shapes, decisions, and connections
-- Shape types: terminal (start/end), process (steps), decision (branches), data (I/O), document, database
-- Position shapes explicitly when layout matters; use auto_layout only for tree/hierarchical flows
-- Curved connectors follow source→target regardless of positioning, so manual placement works fine
-- NEVER restart the pipeline
-- After end_job, SHOW the screenshot and ask user if the design looks good`;
-// -----------------------------------------------------------------------------
-// Prompt definitions — each has a single declarative description argument
+// Prompt definitions
 // -----------------------------------------------------------------------------
 const MOTIVATIONAL_QUOTE_PROMPT = {
     name: 'motivational-quote',
@@ -100,7 +74,7 @@ export const PROMPTS = [
     CINEMA_TITLES_PROMPT,
 ];
 // -----------------------------------------------------------------------------
-// Message builders — ultra-concise, batch-first, no tool lists
+// Message builders — user message only, no assistant pre-fill
 // -----------------------------------------------------------------------------
 function buildMotivationalQuote(args = {}) {
     const description = args.description || 'Dream big — bold and energetic';
@@ -112,19 +86,6 @@ function buildMotivationalQuote(args = {}) {
                 text: `Create an animated motivational quote poster: ${description}`,
             },
         },
-        {
-            role: 'assistant',
-            content: {
-                type: 'text',
-                text: `I'll create this. All operations in one batch_execute call, then show you the result for feedback.
-
-${SINGLE_PASS_RULES}
-
-CANVAS: execute_generator (match mood) / ITEMS: create text (quote + attribution) / ANIMATE: keyframe_animate (staggered reveals) / EFFECTS: apply_mask (wipeUp or iris) / PLAY: play_timeline.
-
-Starting now.`,
-            },
-        },
     ];
 }
 function buildTextRevealUp(args = {}) {
@@ -137,19 +98,6 @@ function buildTextRevealUp(args = {}) {
                 text: `Create a text reveal animation: ${description}`,
             },
         },
-        {
-            role: 'assistant',
-            content: {
-                type: 'text',
-                text: `I'll create this. All operations in one batch_execute call, then show you the result.
-
-${SINGLE_PASS_RULES}
-
-CANVAS: execute_generator (match style) / ITEMS: create text (one per word, each on its own line — stack vertically with Y spacing ≥ fontSize × 1.4, NEVER same position) / ANIMATE: keyframe_animate (staggered fade-in, each word 0.3s after previous) / EFFECTS: apply_mask (wipeUp per item) / PLAY: play_timeline.
-
-Starting now.`,
-            },
-        },
     ];
 }
 function buildSimpleDecisionFlow(args = {}) {
@@ -162,19 +110,6 @@ function buildSimpleDecisionFlow(args = {}) {
                 text: `Create a decision flowchart: ${description}`,
             },
         },
-        {
-            role: 'assistant',
-            content: {
-                type: 'text',
-                text: `I'll create this flowchart using diagram tools, then show you the result.
-
-${DIAGRAM_RULES}
-
-DESIGN: Analyze description → identify shapes (terminal, process, decision) → create_diagram_shape each (position explicitly or let auto_layout arrange) → connect with arrows.
-
-Starting now.`,
-            },
-        },
     ];
 }
 function buildSolarSystem(args = {}) {
@@ -187,19 +122,6 @@ function buildSolarSystem(args = {}) {
                 text: `Create an animated solar system: ${description}`,
             },
         },
-        {
-            role: 'assistant',
-            content: {
-                type: 'text',
-                text: `I'll create this. All operations in one batch_execute call, then show you the result.
-
-${SINGLE_PASS_RULES}
-
-CANVAS: set_background (#0a0a2e) + execute_generator (drawBokeh starfield) / ITEMS: create (sun, orbits, planets) / ANIMATE: animate (sun pulse) + relation (orbits) + keyframe_animate (comet) / PLAY: play_timeline.
-
-Starting now.`,
-            },
-        },
     ];
 }
 function buildCinemaTitles(args = {}) {
@@ -212,19 +134,6 @@ function buildCinemaTitles(args = {}) {
                 text: `Create a cinematic title sequence: ${description}`,
             },
         },
-        {
-            role: 'assistant',
-            content: {
-                type: 'text',
-                text: `I'll create this. All operations in one batch_execute call, then show you the result.
-
-${SINGLE_PASS_RULES}
-
-CANVAS: set_background (#000000) / ITEMS: create text (title + subtitle, opacity:0) / ANIMATE: keyframe_animate (fade in + scale, staggered) / EFFECTS: apply_mask (cinematic letterbox) / PLAY: play_timeline.
-
-Starting now.`,
-            },
-        },
     ];
 }
 // -----------------------------------------------------------------------------

package/dist/prompts/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/prompts/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/prompts/index.ts"],"names":[],"mappings":"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"}

package/dist/tools/compact-descriptions.d.ts

@@ -1,7 +1,7 @@
 /**
  * Compact tool descriptions for reduced context usage.
  *
- * Activated via PINEPAPER_TOOL_VERBOSITY=compact env var.
+ * Activated via PINEPAPER_VERBOSITY=compact env var.
  * Cuts ~58% from the 13 largest tool descriptions while preserving
  * USE WHEN guidance, critical warnings, and resource doc references.
  */

package/dist/tools/compact-descriptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compact-descriptions.d.ts","sourceRoot":"","sources":["../../src/tools/compact-descriptions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAyQvD,CAAC"}
+{"version":3,"file":"compact-descriptions.d.ts","sourceRoot":"","sources":["../../src/tools/compact-descriptions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAwTvD,CAAC"}

package/dist/tools/compact-descriptions.js

@@ -1,15 +1,43 @@
 /**
  * Compact tool descriptions for reduced context usage.
  *
- * Activated via PINEPAPER_TOOL_VERBOSITY=compact env var.
+ * Activated via PINEPAPER_VERBOSITY=compact env var.
  * Cuts ~58% from the 13 largest tool descriptions while preserving
  * USE WHEN guidance, critical warnings, and resource doc references.
  */
 export const COMPACT_DESCRIPTIONS = {
+    // -------------------------------------------------------------------------
+    // Minimal toolkit tools — outcome-focused descriptions
+    // -------------------------------------------------------------------------
+    pinepaper_set_background_color: `Set the canvas background color. Pass a hex color string (e.g. "#0f172a").`,
+    pinepaper_set_canvas_size: `Set canvas dimensions. Use width+height or a preset: instagram (1080x1080), youtube (1920x1080), tiktok (1080x1920), twitter (1200x675). Call BEFORE creating items.`,
+    pinepaper_get_canvas_size: `Get current canvas width and height.`,
+    pinepaper_clear_canvas: `Remove all items from the canvas.`,
+    pinepaper_refresh_page: `Reload the PinePaper browser page for a clean start.`,
+    pinepaper_browser_connect: `Connect to PinePaper Studio. Usually NOT needed — auto-connects on first tool call.`,
+    pinepaper_browser_disconnect: `Disconnect from the browser.`,
+    pinepaper_browser_screenshot: `Take a screenshot of the current canvas to show the user.`,
+    pinepaper_browser_status: `Check browser connection status.`,
+    pinepaper_agent_start_job: `Begin creating an animation or graphic. Call this FIRST, then use batch_execute to build the scene, then end_job to finish.
+
+Pass the user's request as "description" for creative direction tips. Use canvasPreset for platform sizing (instagram, youtube, tiktok, twitter).
+
+WORKFLOW: start_job → batch_execute (ONE call with ALL operations) → end_job → show screenshot → export if requested.`,
+    pinepaper_agent_end_job: `Finish the current animation job. Returns a screenshot — SHOW it to the user and ask if the design looks good.`,
+    pinepaper_agent_reset: `Quick canvas reset. Faster than refresh_page.`,
+    pinepaper_agent_analyze: `Analyze what's on the canvas and get export recommendations.`,
+    pinepaper_get_canvas_presets: `List available canvas size presets (YouTube, Instagram, TikTok, etc.).`,
+    pinepaper_tool_guide: `Get detailed docs for any tool or category. Call with no args for the full workflow guide. Call with tool name for that tool's full description.`,
+    pinepaper_set_toolkit: `Switch available tools at runtime. Use when the user needs tools not currently visible.
+
+Toolkits: agent (animations/graphics), diagram (flowcharts/UML), map (geographic maps), font (font creation), full (all 120+ tools), minimal (core only).
+Verbosity: verbose (full docs), compact (shorter), minimal (1-line summaries).
+
+Example: User asks for a map → call set_toolkit({toolkit: "map"}).`,
     // -------------------------------------------------------------------------
     // batch_execute — 4382 → ~1200 chars
     // -------------------------------------------------------------------------
-    pinepaper_agent_batch_execute: `Execute ALL operations in a single call for building animated scenes — canvas setup, backgrounds, items, animations, masks, effects, and playback.
+    pinepaper_agent_batch_execute: `Create animated scenes in a single call — canvas setup, backgrounds, text, shapes, animations, masks, effects, and playback. This is how you build animations on PinePaper.
 
 NOTE: For diagrams (flowcharts, UML), use pinepaper_create_diagram_shape + pinepaper_connect instead.
 
@@ -17,7 +45,14 @@ NOTE: For diagrams (flowcharts, UML), use pinepaper_create_diagram_shape + pinep
 
 WORKFLOW: pinepaper_agent_start_job → pinepaper_agent_batch_execute → pinepaper_agent_end_job
 
-OPERATION TYPES (12, use in order): set_canvas_size, set_background, execute_generator, create, modify, delete, animate, keyframe_animate, relation, apply_mask, apply_effect, play_timeline.
+PATTERN — Always follow this order:
+  1. set_canvas_size / set_background / execute_generator (canvas setup)
+  2. create (items — text, shapes, etc.)
+  3. animate or keyframe_animate for EACH created item ("$0", "$1", ...) — REQUIRED for animated content
+  4. relation / apply_mask / apply_effect (optional enhancements)
+  5. play_timeline (REQUIRED — starts playback, without this nothing moves)
+
+OPERATION TYPES (12): set_canvas_size, set_background, execute_generator, create, modify, delete, animate, keyframe_animate, relation, apply_mask, apply_effect, play_timeline.
 
 VARIABLE REFERENCES: "$0", "$1" etc. reference items by creation order within the batch.
 
@@ -238,23 +273,19 @@ RETURNS: itemId (for further modifications), metadata (including license).`,
     // -------------------------------------------------------------------------
     // agent_export — 1615 → ~900 chars
     // -------------------------------------------------------------------------
-    pinepaper_agent_export: `Smart export with automatic format detection and platform optimization.
-
-USE WHEN: Exporting for social media, print, or web with optimal format auto-selected.
+    pinepaper_agent_export: `Export your animation as MP4 video, GIF, PNG, SVG, or PDF. When user asks for "video" or "export", default to MP4.
 
-PLATFORMS:
+PLATFORMS & FORMATS:
 | Platform         | Size       | Static | Animated |
 |------------------|------------|--------|----------|
 | instagram        | 1080x1080  | PNG    | MP4      |
-| instagram-story  | 1080x1920  | PNG    | MP4      |
-| tiktok           | 1080x1920  | PNG    | MP4@60fps|
+| tiktok           | 1080x1920  | PNG    | MP4      |
 | youtube          | 1920x1080  | PNG    | MP4      |
-| youtube-thumbnail| 1280x720   | PNG    | PNG      |
 | twitter          | 1200x675   | PNG    | GIF      |
-| linkedin         | 1200x627   | PNG    | GIF      |
 | web              | flexible   | SVG    | SVG      |
-| print-a4/letter  | A4/Letter  | PDF    | PDF      |
 
-Format override: svg, png, gif, mp4, webm, pdf. Quality: draft, standard, high. See inputSchema for details.`,
+DEFAULT: When user asks for "video" or "export", use format: "mp4". Only use svg/gif if user specifically requests them.
+Formats: svg, png, gif, mp4, webm, pdf. Quality: draft, standard, high.
+⚠️ If export fails, do NOT retry with different formats — report the error to the user.`,
 };
 //# sourceMappingURL=compact-descriptions.js.map

package/dist/tools/compact-descriptions.js.map

@@ -1 +1 @@
-{"version":3,"file":"compact-descriptions.js","sourceRoot":"","sources":["../../src/tools/compact-descriptions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAA2B;IAE1D,4EAA4E;IAC5E,qCAAqC;IACrC,4EAA4E;IAC5E,6BAA6B,EAAE;;;;;;;;;;;;;;kHAciF;IAEhH,4EAA4E;IAC5E,mCAAmC;IACnC,4EAA4E;IAC5E,qBAAqB,EAAE;;;;;;;;;;;;;;;;;;;;kEAoByC;IAEhE,4EAA4E;IAC5E,+BAA+B;IAC/B,4EAA4E;IAC5E,iBAAiB,EAAE;;;;;;;;;;;;;;;;EAgBnB;IAEA,4EAA4E;IAC5E,oCAAoC;IACpC,4EAA4E;IAC5E,sBAAsB,EAAE;;;;;;;;;;;;;;;;;;;;;;oEAsB0C;IAElE,4EAA4E;IAC5E,wCAAwC;IACxC,4EAA4E;IAC5E,2BAA2B,EAAE;;;;;;;;;;;;yJAY0H;IAEvJ,4EAA4E;IAC5E,+CAA+C;IAC/C,4EAA4E;IAC5E,iCAAiC,EAAE;;;;;;;;;;;;;8BAaP;IAE5B,4EAA4E;IAC5E,oCAAoC;IACpC,4EAA4E;IAC5E,sBAAsB,EAAE;;;;;;;;;;;;;;sFAc4D;IAEpF,4EAA4E;IAC5E,4CAA4C;IAC5C,4EAA4E;IAC5E,8BAA8B,EAAE;;;;;;;;;;;;;;qJAcmH;IAEnJ,4EAA4E;IAC5E,qCAAqC;IACrC,4EAA4E;IAC5E,uBAAuB,EAAE;;;;;;;;;;;;;qCAaU;IAEnC,4EAA4E;IAC5E,+BAA+B;IAC/B,4EAA4E;IAC5E,iBAAiB,EAAE;;;;;;;;;;;;;;;yFAeoE;IAEvF,4EAA4E;IAC5E,mCAAmC;IACnC,4EAA4E;IAC5E,qBAAqB,EAAE;;;;;;;;;;;;;;;;oDAgB2B;IAElD,4EAA4E;IAC5E,mCAAmC;IACnC,4EAA4E;IAC5E,sBAAsB,EAAE;;;;;;;;;;;;2EAYiD;IAEzE,4EAA4E;IAC5E,mCAAmC;IACnC,4EAA4E;IAC5E,sBAAsB,EAAE;;;;;;;;;;;;;;;;;6GAiBmF;CAE5G,CAAC"}
+{"version":3,"file":"compact-descriptions.js","sourceRoot":"","sources":["../../src/tools/compact-descriptions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAA2B;IAE1D,4EAA4E;IAC5E,uDAAuD;IACvD,4EAA4E;IAC5E,8BAA8B,EAAE,4EAA4E;IAE5G,yBAAyB,EAAE,sKAAsK;IAEjM,yBAAyB,EAAE,sCAAsC;IAEjE,sBAAsB,EAAE,mCAAmC;IAE3D,sBAAsB,EAAE,sDAAsD;IAE9E,yBAAyB,EAAE,qFAAqF;IAEhH,4BAA4B,EAAE,8BAA8B;IAE5D,4BAA4B,EAAE,2DAA2D;IAEzF,wBAAwB,EAAE,kCAAkC;IAE5D,yBAAyB,EAAE;;;;sHAIyF;IAEpH,uBAAuB,EAAE,gHAAgH;IAEzI,qBAAqB,EAAE,+CAA+C;IAEtE,uBAAuB,EAAE,8DAA8D;IAEvF,4BAA4B,EAAE,wEAAwE;IAEtG,oBAAoB,EAAE,kJAAkJ;IAExK,qBAAqB,EAAE;;;;;mEAK0C;IAEjE,4EAA4E;IAC5E,qCAAqC;IACrC,4EAA4E;IAC5E,6BAA6B,EAAE;;;;;;;;;;;;;;;;;;;;;kHAqBiF;IAEhH,4EAA4E;IAC5E,mCAAmC;IACnC,4EAA4E;IAC5E,qBAAqB,EAAE;;;;;;;;;;;;;;;;;;;;kEAoByC;IAEhE,4EAA4E;IAC5E,+BAA+B;IAC/B,4EAA4E;IAC5E,iBAAiB,EAAE;;;;;;;;;;;;;;;;EAgBnB;IAEA,4EAA4E;IAC5E,oCAAoC;IACpC,4EAA4E;IAC5E,sBAAsB,EAAE;;;;;;;;;;;;;;;;;;;;;;oEAsB0C;IAElE,4EAA4E;IAC5E,wCAAwC;IACxC,4EAA4E;IAC5E,2BAA2B,EAAE;;;;;;;;;;;;yJAY0H;IAEvJ,4EAA4E;IAC5E,+CAA+C;IAC/C,4EAA4E;IAC5E,iCAAiC,EAAE;;;;;;;;;;;;;8BAaP;IAE5B,4EAA4E;IAC5E,oCAAoC;IACpC,4EAA4E;IAC5E,sBAAsB,EAAE;;;;;;;;;;;;;;sFAc4D;IAEpF,4EAA4E;IAC5E,4CAA4C;IAC5C,4EAA4E;IAC5E,8BAA8B,EAAE;;;;;;;;;;;;;;qJAcmH;IAEnJ,4EAA4E;IAC5E,qCAAqC;IACrC,4EAA4E;IAC5E,uBAAuB,EAAE;;;;;;;;;;;;;qCAaU;IAEnC,4EAA4E;IAC5E,+BAA+B;IAC/B,4EAA4E;IAC5E,iBAAiB,EAAE;;;;;;;;;;;;;;;yFAeoE;IAEvF,4EAA4E;IAC5E,mCAAmC;IACnC,4EAA4E;IAC5E,qBAAqB,EAAE;;;;;;;;;;;;;;;;oDAgB2B;IAElD,4EAA4E;IAC5E,mCAAmC;IACnC,4EAA4E;IAC5E,sBAAsB,EAAE;;;;;;;;;;;;2EAYiD;IAEzE,4EAA4E;IAC5E,mCAAmC;IACnC,4EAA4E;IAC5E,sBAAsB,EAAE;;;;;;;;;;;;;wFAa8D;CAEvF,CAAC"}

package/dist/tools/definitions.d.ts

@@ -9,6 +9,7 @@
  */
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import { I18nManager } from '../i18n/index.js';
+export declare const AI_AGENT_GUIDE = "WORKFLOW \u2014 Create \u2192 Validate \u2192 Iterate:\n\n1. pinepaper_agent_start_job (clearCanvas: true, canvasPreset)\n2. pinepaper_agent_batch_execute \u2014 ONE call with ALL operations:\n     set_canvas_size \u2192 set_background / execute_generator \u2192 create items \u2192 animate / keyframe_animate \u2192 relation \u2192 apply_mask \u2192 apply_effect \u2192 play_timeline\n3. pinepaper_agent_end_job \u2014 returns screenshot\n4. Show screenshot to user for validation\n5. If user wants changes \u2192 modify specific items or start a new job\n\n\u26A0\uFE0F CRITICAL \u2014 Every operation is LIVE on the canvas:\nEvery create, animate, relation, or generator call IMMEDIATELY executes on the connected browser canvas.\nCalling the same operation twice creates DUPLICATE elements. There is no \"preview\" \u2014 it's all live.\nIf you restart the pipeline or re-call batch_execute, you DOUBLE every item on the canvas.\nTo fix mistakes: use modify/delete operations, or start a NEW job with clearCanvas: true.\n\nRULES:\n- NEVER restart the pipeline \u2014 one start_job, one batch_execute, one end_job\n- ALL operations go in batch_execute \u2014 canvas, background, items, animation, masks, effects, playback\n- EXCEPTION: Diagrams (flowcharts, UML) use pinepaper_create_diagram_shape + pinepaper_connect, NOT batch_execute\n- Use generators for rich backgrounds \u2014 the built-in templates are limited, generators create much better visuals\n- Use \"$0\", \"$1\" to reference items by creation order within the batch\n\n\u2500\u2500\u2500 BATCH OPERATIONS (12 types, in order) \u2500\u2500\u2500\n\nCANVAS:  set_canvas_size (width/height or preset) \u2192 set_background (color) \u2192 execute_generator (procedural art)\nITEMS:   create (itemType, position, properties) \u2192 modify (itemId, properties) \u2192 delete (itemId)\nANIMATE: animate (loop presets) \u2192 keyframe_animate (timed reveals) \u2192 relation (behavioral links)\nEFFECTS: apply_mask (reveal animations) \u2192 apply_effect (sparkle/blast)\nPLAY:    play_timeline (start playback)\n\n\u2500\u2500\u2500 GENERATORS (prefer these for backgrounds) \u2500\u2500\u2500\n\nGenerators fill the canvas with procedural art \u2014 much richer than solid colors.\nChoose based on mood:\n  Dreamy/soft:  drawBokeh, drawGradientMesh, drawOrganicFlow\n  Techy/modern: drawCircuit, drawGrid, drawWindField\n  Nature/warm:  drawSunsetScene, drawSunburst, drawWaves\n  Abstract:     drawGeometricAbstract, drawFluidFlow, drawNoiseTexture\n  Decorative:   drawPattern, drawStackedCircles\n\n\u2500\u2500\u2500 ITEMS \u2500\u2500\u2500\n\nShapes: circle, rectangle, star, ellipse, triangle, polygon, line, arc, path\nText: text (content, fontSize, fontFamily, color, fontWeight)\nAll items: opacity, shadowColor, shadowBlur, blendMode, strokeColor, strokeWidth\n\nSVG imports for recognizable objects (planes, cars, animals, buildings):\n  pinepaper_search_assets \u2192 pinepaper_import_asset (850k+ SVG icons)\n\n\u2500\u2500\u2500 ANIMATION (all in batch) \u2500\u2500\u2500\n\nLoop presets (animate): pulse, rotate, bounce, fade, wobble, slide, typewriter\nKeyframe (keyframe_animate): [{time, properties, easing}] \u2192 opacity, scale, scaleX, scaleY, x, y, rotation, fillColor, strokeColor, fontSize\nRelations (relation): orbits, follows, attached_to, points_at, mirrors, parallax, wave_through, morphs_to (+ 9 more in batch_execute schema)\nMasks (apply_mask): wipeLeft, wipeRight, wipeUp, wipeDown, iris, irisOut, star, heart, curtainHorizontal, curtainVertical, cinematic, diagonalWipe, revealUp, revealDown\nEffects (apply_effect): sparkle, blast\n\nComposability: one item can have loop + keyframe + relation + mask simultaneously.\n\nTiming templates (stagger reveals across duration):\n  5s:  bg 0s \u2192 elements 1-2s \u2192 text 2.5-3.5s \u2192 final 4-5s\n  10s: bg 0-1s \u2192 elements 1-4s \u2192 main 4-7s \u2192 details 7-9s \u2192 finale 9-10s\n\n\u2500\u2500\u2500 VISUAL COMPOSITION \u2500\u2500\u2500\n\nLayer order: background \u2192 large shapes (low opacity) \u2192 main subjects \u2192 text on top\nColor: dark bg (#0f172a) + bright accents (#f472b6, #818cf8, #fbbf24)\nScale: main subject 40-60% of canvas, supporting elements smaller\nSpacing: distribute across canvas with breathing room, don't cluster\n\n\u26A0\uFE0F SIZING \u2014 All positions and sizes MUST fit within the canvas:\n  Default canvas is 800x600. For infographics/social media, SET A PRESET FIRST.\n  start_job returns canvasSize \u2014 use it to calculate positions.\n  Keep all items within 5%-95% of canvas width/height (leave margins).\n  Font sizes relative to canvas: titles \u2264 5% of canvas width, body \u2264 3%.\n  Example for 1080x1080: title fontSize \u2264 54, body \u2264 32, positions 54-1026.\n  Example for 800x600: title fontSize \u2264 40, body \u2264 24, positions 40-760.\n\n\u26A0\uFE0F TEXT OVERLAP \u2014 NEVER place multiple text items at the same position:\n  Each text item MUST have a unique Y position. Stack vertically with spacing \u2265 fontSize \u00D7 1.4.\n  For N words stacked vertically: startY = centerY - (N-1) \u00D7 spacing / 2, then increment Y by spacing.\n  Example for 5 words at fontSize 48 on 800x600: spacing=67, startY=166, positions: 166, 233, 300, 367, 434.\n\n\u2500\u2500\u2500 DIAGRAMS (flowcharts, UML \u2014 do NOT use batch_execute) \u2500\u2500\u2500\n\nDiagrams use their own tools, not batch_execute:\n  pinepaper_create_diagram_shape \u2192 pinepaper_connect \u2192 pinepaper_auto_layout\nShapes: process (rect), decision (diamond), terminal (rounded), data, document, database, cloud, server\nWorkflow: create shapes with positions \u2192 connect with arrows \u2192 optional auto_layout\nSee pinepaper://docs/diagrams for full examples.\n\n\u2500\u2500\u2500 CANVAS & EXPORT \u2500\u2500\u2500\n\nPresets: instagram (1080x1080), youtube (1920x1080), tiktok (1080x1920), twitter (1200x675)\nExport: pinepaper_agent_export (SVG/PNG/GIF/MP4/WebM/PDF), pinepaper_export_svg";
 export declare const PINEPAPER_TOOLS: Tool[];
 /**
  * Get a tool definition by name
@@ -25,14 +26,15 @@ export declare function getToolNames(): string[];
 export declare function getLocalizedTools(i18n: I18nManager): Tool[];
 /**
  * Tool description verbosity level.
- * - 'verbose': Full descriptions (default, ~42K tokens)
+ * - 'verbose': Full descriptions (~42K tokens for full toolkit)
  * - 'compact': Trimmed descriptions for the 13 largest tools (~37K tokens)
+ * - 'minimal': 1-line summaries for all tools (~22K tokens). Use pinepaper_tool_guide for details.
  */
-export type ToolVerbosity = 'verbose' | 'compact';
+export type ToolVerbosity = 'verbose' | 'compact' | 'minimal';
 /**
  * Get tools with the specified verbosity level.
- * Compact mode swaps in shorter descriptions for the 13 largest tools,
- * reducing context usage by ~5K tokens while preserving critical guidance.
+ * Compact mode swaps in shorter descriptions for the 13 largest tools.
+ * Minimal mode swaps in 1-line summaries for ALL tools (on-demand guide available).
  */
 export declare function getToolsForVerbosity(verbosity: ToolVerbosity): Tool[];
 //# sourceMappingURL=definitions.d.ts.map

package/dist/tools/definitions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/tools/definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AA4G/C,eAAO,MAAM,eAAe,EAAE,IAAI,EAq5LjC,CAAC;AAEF;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAE5D;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,EAAE,CAEvC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,EAAE,CAO3D;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,SAAS,CAAC;AAElD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,aAAa,GAAG,IAAI,EAAE,CAMrE"}
+{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/tools/definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAQ/C,eAAO,MAAM,cAAc,83LA8FqD,CAAC;AAWjF,eAAO,MAAM,eAAe,EAAE,IAAI,EAygMjC,CAAC;AAEF;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAE5D;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,EAAE,CAEvC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,EAAE,CAO3D;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAE9D;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,aAAa,GAAG,IAAI,EAAE,CAQrE"}

package/dist/tools/definitions.js

@@ -8,11 +8,11 @@
  * User-facing messages (errors, success) are translated via i18n.
  */
 import { COMPACT_DESCRIPTIONS } from './compact-descriptions.js';
+import { MINIMAL_DESCRIPTIONS } from './minimal-descriptions.js';
 // =============================================================================
-// AI AGENT GUIDE
+// AI AGENT GUIDE (exported for pinepaper_tool_guide)
 // =============================================================================
-/*
-WORKFLOW — Create → Validate → Iterate:
+export const AI_AGENT_GUIDE = `WORKFLOW — Create → Validate → Iterate:
 
 1. pinepaper_agent_start_job (clearCanvas: true, canvasPreset)
 2. pinepaper_agent_batch_execute — ONE call with ALL operations:
@@ -106,8 +106,11 @@ See pinepaper://docs/diagrams for full examples.
 ─── CANVAS & EXPORT ───
 
 Presets: instagram (1080x1080), youtube (1920x1080), tiktok (1080x1920), twitter (1200x675)
-Export: pinepaper_agent_export (SVG/PNG/GIF/MP4/WebM/PDF), pinepaper_export_svg
-*/
+Export: pinepaper_agent_export (SVG/PNG/GIF/MP4/WebM/PDF), pinepaper_export_svg`;
+/*
+ * The AI_AGENT_GUIDE constant above is included as a comment in verbose/compact modes
+ * and served on-demand via pinepaper_tool_guide in minimal mode.
+ */
 // =============================================================================
 // TOOL DEFINITIONS
 // =============================================================================
@@ -5396,7 +5399,7 @@ If you see significantly higher numbers, investigate:
                 },
                 phase: {
                     type: 'string',
-                    enum: ['validation', 'code_generation', 'browser_execution', 'screenshot', 'total'],
+                    enum: ['validation', 'code_generation', 'browser_execution', 'screenshot', 'total', 'response_size'],
                     description: 'Filter by execution phase (optional)',
                 },
                 since: {
@@ -5416,6 +5419,50 @@ If you see significantly higher numbers, investigate:
         },
     },
     // ---------------------------------------------------------------------------
+    // INFRASTRUCTURE: DIAGNOSTIC REPORT
+    // ---------------------------------------------------------------------------
+    {
+        name: 'pinepaper_diagnostic_report',
+        annotations: {
+            title: 'Generate Diagnostic Report',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: `[Utility] Generate a diagnostic report for bug reporting. Collects server config, browser state, session history, canvas snapshot, performance metrics, and token usage estimates into a JSON file.
+
+USE WHEN:
+- User encounters an error or unexpected behavior
+- Filing a bug report and need debugging context
+- Troubleshooting performance or connection issues
+- Checking token consumption per tool call to optimize costs
+
+RETURNS:
+- JSON file saved to disk with full diagnostic data
+- Summary text with key state information
+- Token usage breakdown: estimated response tokens per tool, top consumers, total payload size
+
+PRIVACY: No screenshots, no tool call arguments, no user content — only structural/timing data.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                includeMetrics: {
+                    type: 'boolean',
+                    description: 'Include performance metrics (default: true)',
+                },
+                includeCanvas: {
+                    type: 'boolean',
+                    description: 'Include canvas state snapshot (default: true)',
+                },
+                metricsLimit: {
+                    type: 'number',
+                    description: 'Max metrics entries to include (default: 100)',
+                },
+            },
+        },
+    },
+    // ---------------------------------------------------------------------------
     // INFRASTRUCTURE: AGENT FLOW MODE TOOLS
     // ---------------------------------------------------------------------------
     {
@@ -5443,6 +5490,10 @@ CANVAS PRESETS: instagram (1080x1080), instagram-story (1080x1920), tiktok (1080
                     type: 'string',
                     description: 'Optional job name for tracking',
                 },
+                description: {
+                    type: 'string',
+                    description: 'Pass the user\'s request/prompt here — the server returns contextual design guidance when the prompt is vague',
+                },
                 screenshotPolicy: {
                     type: 'string',
                     enum: ['on_complete', 'on_error', 'never', 'on_request'],
@@ -5759,12 +5810,6 @@ EXAMPLE — Animated sky scene with timed reveals:
         },
         description: `Smart export with automatic format detection and platform optimization.
 
-USE WHEN:
-- Exporting content for a specific social media platform
-- Need optimal format automatically selected
-- Want platform-specific dimensions and quality
-- Exporting for print or web
-
 PLATFORMS & OPTIMAL FORMATS:
 | Platform        | Dimensions | Static | Animated |
 |-----------------|------------|--------|----------|
@@ -5772,31 +5817,19 @@ PLATFORMS & OPTIMAL FORMATS:
 | instagram-story | 1080x1920  | PNG    | MP4      |
 | tiktok          | 1080x1920  | PNG    | MP4@60fps|
 | youtube         | 1920x1080  | PNG    | MP4      |
-| youtube-thumbnail| 1280x720  | PNG    | PNG      |
 | twitter         | 1200x675   | PNG    | GIF      |
-| linkedin        | 1200x627   | PNG    | GIF      |
 | web             | flexible   | SVG    | SVG      |
-| print-a4        | 2480x3508  | PDF    | PDF      |
-| print-letter    | 2550x3300  | PDF    | PDF      |
-
-FORMAT OVERRIDE:
-You can specify a format to override auto-detection:
-- svg: Scalable vector (best for web, smallest file)
-- png: High quality raster (best for static social media)
-- gif: Animated (limited to 256 colors)
-- mp4: Video (best quality animations)
-- webm: Video (smaller file, modern browsers)
-- pdf: Print-ready document
-
-QUALITY LEVELS:
-- draft: Fast export, lower quality (good for previews)
-- standard: Balanced quality and file size (default)
-- high: Maximum quality (best for final export)
+
+FORMATS: svg, png, gif, mp4, webm, pdf.
+QUALITY: draft, standard, high.
+
+⚠️ If export fails, do NOT retry with different formats — report the error to the user.
+⚠️ When user asks for "video", always use format: "mp4".
 
 EXAMPLES:
-- Auto-export for Instagram: {platform: "instagram"}
-- Force SVG export: {platform: "web", format: "svg"}
-- High-quality print: {platform: "print-a4", quality: "high"}`,
+- {platform: "instagram"} — auto-selects best format
+- {platform: "instagram", format: "mp4"} — force MP4
+- {platform: "web", format: "svg"} — animated SVG`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -6071,6 +6104,89 @@ EXAMPLES:
             required: ['itemJson', 'itemType'],
         },
     },
+    // ---------------------------------------------------------------------------
+    // ON-DEMAND TOOL GUIDE (RLM-inspired — query detailed docs in minimal mode)
+    // ---------------------------------------------------------------------------
+    {
+        name: 'pinepaper_tool_guide',
+        annotations: {
+            title: 'Tool Guide',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: `Get detailed guidance for PinePaper tools on demand.
+
+USE WHEN: You need full parameter docs, examples, or workflow guidance — especially in minimal verbosity mode where tool descriptions are short summaries.
+
+MODES:
+- No args → returns the full AI Agent Guide (workflow, rules, batch operations, visual composition tips)
+- tool: "pinepaper_agent_batch_execute" → returns that tool's full verbose description
+- category: "animation" → returns all tools in that category with full descriptions
+
+CATEGORIES: agent, browser, canvas, core, import, assets, batch, relations, animation, masks, camera, generators, effects, filters, scene, template, query, export, diagram, map, font, letter_collage, triggers, quiz, performance, custom_code, p5, register, guide`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                tool: {
+                    type: 'string',
+                    description: 'Tool name to get detailed description for (e.g., "pinepaper_agent_batch_execute")',
+                },
+                category: {
+                    type: 'string',
+                    description: 'Category/tag name to list all tools with descriptions (e.g., "animation", "map")',
+                },
+            },
+        },
+    },
+    // ---------------------------------------------------------------------------
+    // RUNTIME TOOLKIT SWITCHING
+    // ---------------------------------------------------------------------------
+    {
+        name: 'pinepaper_set_toolkit',
+        annotations: {
+            title: 'Set Toolkit',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: `Switch the active toolkit profile and/or verbosity level at runtime. The tools/list updates immediately.
+
+USE WHEN:
+- You need diagram tools but are on the 'agent' profile → switch to 'diagram' or 'full'
+- You need map tools → switch to 'map' or 'full'
+- You want more/less detail in tool descriptions → switch verbosity
+
+PROFILES:
+- full: All 120+ tools
+- agent: Core creative tools (~50 tools) — default
+- diagram: Diagram/flowchart tools
+- map: Map/choropleth tools
+- font: Font creation tools
+- minimal: Bare essentials (~15 tools)
+
+VERBOSITY:
+- verbose: Full descriptions
+- compact: Shorter descriptions for 13 largest tools — default
+- minimal: 1-line summaries (use pinepaper_tool_guide for details)`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                toolkit: {
+                    type: 'string',
+                    description: 'Toolkit profile: full, agent, diagram, map, font, minimal',
+                    enum: ['full', 'agent', 'diagram', 'map', 'font', 'minimal'],
+                },
+                verbosity: {
+                    type: 'string',
+                    description: 'Description verbosity: verbose, compact, minimal',
+                    enum: ['verbose', 'compact', 'minimal'],
+                },
+            },
+        },
+    },
 ];
 /**
  * Get a tool definition by name
@@ -6098,15 +6214,16 @@ export function getLocalizedTools(i18n) {
 }
 /**
  * Get tools with the specified verbosity level.
- * Compact mode swaps in shorter descriptions for the 13 largest tools,
- * reducing context usage by ~5K tokens while preserving critical guidance.
+ * Compact mode swaps in shorter descriptions for the 13 largest tools.
+ * Minimal mode swaps in 1-line summaries for ALL tools (on-demand guide available).
  */
 export function getToolsForVerbosity(verbosity) {
     if (verbosity === 'verbose')
         return PINEPAPER_TOOLS;
+    const descMap = verbosity === 'minimal' ? MINIMAL_DESCRIPTIONS : COMPACT_DESCRIPTIONS;
     return PINEPAPER_TOOLS.map(tool => {
-        const compact = COMPACT_DESCRIPTIONS[tool.name];
-        return compact ? { ...tool, description: compact } : tool;
+        const replacement = descMap[tool.name];
+        return replacement ? { ...tool, description: replacement } : tool;
     });
 }
 //# sourceMappingURL=definitions.js.map