@ufira/vibma 1.1.3 → 1.1.4

package/dist/mcp.js

@@ -80,15 +80,15 @@ Use help(topic: "<endpoint>") for endpoint details.
 Use help(topic: "<endpoint>.<method>") for method details.`;
 var helpEndpoints = {
   "annotations": {
-    "summary": '# annotations\nRead and manage design annotations and annotation categories.\n\nMethods:\n  get                  Read all annotations on a node (full detail with resolved category names) [read]\n  list                 Search annotations across a subtree, optionally filtered by category [read]\n  set                  Replace all annotations on a node [edit]\n  add                  Add an annotation to a node [edit]\n  remove               Remove an annotation from a node by index [edit]\n  categories           List all annotation categories in the file [read]\n  create_category      Create a new annotation category [create]\n  update_category      Update an annotation category\'s label or color [edit]\n  delete_category      Delete an annotation category [edit]\n\n// Annotations are designer-authored notes attached to nodes \u2014 specs, intent, constraints.\n// Every node-returning endpoint includes an annotation brief: { label, properties?, categoryId? }.\n// Use this endpoint for full CRUD and to manage annotation categories.\n// Workflow: read annotations on a node with get, add new ones with add, manage categories with categories/create_category.\n// Batch: get/set/add/remove accept items:[{id, ...}] for multi-node operations, or single-item params (id, label, etc).\n// properties: measurement indicators Figma displays on the canvas \u2014 validated per node type and state.\n// labelMarkdown: rich text label supporting **bold**, *italic*, `code`, [links](url).\n// categoryId: group annotations by category (e.g. "Spacing", "Typography"). Create categories first.\n// ---\n// AnnotationPropertyType values (node-type-dependent \u2014 invalid ones are rejected with the available list):\n//   Dimension: width, height, maxWidth, minWidth, maxHeight, minHeight\n//   Paint: fills, strokes, effects, strokeWeight, cornerRadius, opacity\n//   Text (TEXT nodes only): textStyleId, textAlignHorizontal, fontFamily, fontStyle, fontSize, fontWeight, lineHeight, letterSpacing\n//   Layout (auto-layout only): itemSpacing, padding, layoutMode, alignItems\n//   Instance (INSTANCE only): mainComponent\n//   Grid (grid layout only): gridRowGap, gridColumnGap, gridRowCount, gridColumnCount, gridRowAnchorIndex, gridColumnAnchorIndex, gridRowSpan, gridColumnSpan\n// AnnotationCategoryColor values: yellow, orange, red, pink, violet, blue, teal, green.\n\nUse annotations(method: "help", topic: "<method>") for method details.',
+    "summary": '# annotations\nRead and manage design annotations and annotation categories.\n\nMethods:\n  get                  Read all annotations on a node (full detail with resolved category names) [read]\n  list                 Search annotations across a subtree, optionally filtered by category [read]\n  set                  Replace all annotations on a node [edit]\n  add                  Add an annotation to a node [edit]\n  remove               Remove an annotation from a node by index [edit]\n  categories           List all annotation categories in the file [read]\n  create_category      Create a new annotation category [create]\n  update_category      Update an annotation category\'s label or color [edit]\n  delete_category      Delete an annotation category [edit]\n\n// Annotations are designer-authored notes attached to nodes \u2014 specs, intent, constraints.\n// Every node-returning endpoint includes an annotation brief: { label, properties?, categoryId? }.\n// Use this endpoint for full CRUD and to manage annotation categories.\n// Workflow: read annotations on a node with get, add new ones with add, manage categories with categories/create_category.\n// Batch: get/set/add/remove accept items:[{id, ...}] for multi-node operations, or single-item params (id, label, etc).\n// properties: measurement indicators Figma displays on the canvas \u2014 validated per node type and state.\n// labelMarkdown: rich text label supporting **bold**, *italic*, `code`, [links](url).\n// categoryId: group annotations by category (e.g. "Spacing", "Typography"). Create categories first.\n// ---\n// AnnotationPropertyType values (node-type-dependent \u2014 invalid ones are rejected with the available list):\n//   Dimension: width, height, maxWidth, minWidth, maxHeight, minHeight\n//   Paint: fills, strokes, effects, strokeWeight, cornerRadius, opacity\n//   Text (TEXT nodes only): textStyleId, textAlignHorizontal, fontFamily, fontStyle, fontSize, fontWeight, lineHeight, letterSpacing\n//   Layout (auto-layout only): itemSpacing, padding, layoutMode, alignItems\n//   Instance (INSTANCE only): mainComponent\n//   Grid (grid layout only): gridRowGap, gridColumnGap, gridRowCount, gridColumnCount, gridRowAnchorIndex, gridColumnAnchorIndex, gridRowSpan, gridColumnSpan\n// AnnotationCategoryColor values: yellow, orange, red, pink, violet, blue, teal, green.\n\nUse annotations(method: "help", topic: "<method>") for method details.\n// Shared types:\n// Color: hex "#RGB"|"#RGBA"|"#RRGGBB"|"#RRGGBBAA" or {r: 0-1, g: 0-1, b: 0-1, a?: 0-1}\n// VariableAlias: {type: "VARIABLE_ALIAS", id: string}. The id must be a Figma VariableID; discover it via variables.get/list or variable_collections.get. Prefer colorVariableName/fillVariableName/strokeVariableName when available; Paint[] VariableAlias is mainly for precise Paint[] round-trips and gradient stop bindings.\n// Transform: [[number, number, number], [number, number, number]] (Figma Plugin API 2\xD73 matrix)\n// BlendMode: "PASS_THROUGH"|"NORMAL"|"DARKEN"|"MULTIPLY"|"LINEAR_BURN"|"COLOR_BURN"|"LIGHTEN"|"SCREEN"|"LINEAR_DODGE"|"COLOR_DODGE"|"OVERLAY"|"SOFT_LIGHT"|"HARD_LIGHT"|"DIFFERENCE"|"EXCLUSION"|"HUE"|"SATURATION"|"COLOR"|"LUMINOSITY"\n// ColorStop: {position: 0-1, color: Color, boundVariables?: {color?: VariableAlias}}\n// GradientPaint: {type: "GRADIENT_LINEAR"|"GRADIENT_RADIAL"|"GRADIENT_ANGULAR"|"GRADIENT_DIAMOND", gradientTransform: Transform, gradientStops: ColorStop[], visible?: boolean, opacity?: number, blendMode?: BlendMode}. Use gradientTransform + gradientStops (basic left-to-right: [[1,0,0],[0,1,0]]); do not use CSS gradients or REST gradientHandlePositions.\n// Paint: Paint[] authoring accepts only SOLID and GRADIENT_LINEAR/GRADIENT_RADIAL/GRADIENT_ANGULAR/GRADIENT_DIAMOND. SolidPaint: {type: "SOLID", color: Color, visible?: boolean, opacity?: number, blendMode?: BlendMode, boundVariables?: {color?: VariableAlias}}. GradientPaint authoring: {type: GRADIENT_*, gradientTransform: Transform, gradientStops: ColorStop[], visible?, opacity?, blendMode?}; bind variables on gradientStops[].boundVariables.color, not top-level gradient boundVariables. Do not pass IMAGE/VIDEO/PATTERN to create/update Paint[]; those may appear only in readback metadata from existing Figma content. Use imageUrl/images for image authoring. VIDEO/PATTERN authoring is not supported here. Do not use CSS gradients or REST gradientHandlePositions.',
     "methods": {
-      "get": '# annotations.get\nRead all annotations on a node (full detail with resolved category names)\n\nExample: annotations(method:"get", id:"1:23")\n\nParams:\n    id (string, optional) \u2014 Node ID\n    categoryId (string, optional) \u2014 Filter \u2014 only return annotations in this category\n    items (array, optional) \u2014 Batch: [{id, categoryId?}, ...]\n      id (string, required)\n      categoryId (string, optional)',
-      "list": '# annotations.list\nSearch annotations across a subtree, optionally filtered by category\n\nExample: annotations(method:"list", parentId:"1:2", categoryId:"113:0")\n\nParams:\n    parentId (string, optional) \u2014 Root node to search within (default: current page)\n    categoryId (string, optional) \u2014 Filter by category ID\n    limit (number, optional) \u2014 Max items per page (default 100)',
-      "set": '# annotations.set\nReplace all annotations on a node\n\nExample: annotations(method:"set", id:"1:23", annotations:[{label:"Spacing: 16px", properties:["padding"]}])\n\nParams:\n    id (string, optional) \u2014 Node ID\n    annotations (array, optional) \u2014 Array of annotation objects to set (replaces all existing)\n      label (string, optional) \u2014 Plain text label\n      labelMarkdown (string, optional) \u2014 Rich text label (Markdown)\n      properties (string[], optional) \u2014 Measurement property types to display\n      categoryId (string, optional) \u2014 Category ID\n    items (array, optional) \u2014 Batch: [{id, annotations: [...]}, ...]\n      id (string, required)\n      annotations (array, required) \u2014 Annotations to set on this node',
-      "add": '# annotations.add\nAdd an annotation to a node\n\nExample: annotations(method:"add", id:"1:23", labelMarkdown:"**Width**: 320px fixed", properties:["width"])\n\nParams:\n    id (string, optional) \u2014 Node ID\n    label (string, optional) \u2014 Plain text label (use label or labelMarkdown, not both)\n    labelMarkdown (string, optional) \u2014 Rich text label with Markdown formatting\n    properties (string[], optional) \u2014 Measurement property types to display on canvas\n    categoryId (string, optional) \u2014 Category ID to group this annotation\n    items (array, optional) \u2014 Batch: [{id, label?, labelMarkdown?, properties?, categoryId?}, ...]\n      id (string, required)\n      label (string, optional)\n      labelMarkdown (string, optional)\n      properties (string[], optional)\n      categoryId (string, optional)',
-      "remove": '# annotations.remove\nRemove an annotation from a node by index\n\nExample: annotations(method:"remove", id:"1:23", index:0)\n\nParams:\n    id (string, optional) \u2014 Node ID\n    index (number, optional) \u2014 Annotation index to remove (from get response)\n    items (array, optional) \u2014 Batch: [{id, index}, ...]\n      id (string, required)\n      index (number, required)',
-      "categories": '# annotations.categories\nList all annotation categories in the file\n\nExample: annotations(method:"categories")\n\nNo params.',
-      "create_category": '# annotations.create_category\nCreate a new annotation category\n\nExample: annotations(method:"create_category", label:"Spacing", color:"blue")\n\nParams:\n    label (string, required) \u2014 Category label\n    color (yellow | orange | red | pink | violet | blue | teal | green, required) \u2014 Category color',
+      "get": '# annotations.get\nRead all annotations on a node (full detail with resolved category names)\n\nExample: annotations(method:"get", id:"1:23")\n\nParams:\n    id (string, optional) \u2014 Node ID\n    categoryId (string, optional) \u2014 Filter \u2014 only return annotations in this category\n    items (array, optional) \u2014 Batch: [{id, categoryId?}, ...]\n      id (string, required)\n      categoryId (string, optional)\n\nResponse:\n    { results: ({id} | {error})[] }',
+      "list": '# annotations.list\nSearch annotations across a subtree, optionally filtered by category\n\nExample: annotations(method:"list", parentId:"1:2", categoryId:"113:0")\n\nParams:\n    parentId (string, optional) \u2014 Root node to search within (default: current page)\n    categoryId (string, optional) \u2014 Filter by category ID\n    limit (number, optional) \u2014 Max items per page (default 100)\n\nResponse:\n    results (array, optional) \u2014 Annotations found across the subtree\n      nodeId (string, optional)\n      nodeName (string, optional)\n      nodeType (string, optional)\n      index (number, optional)\n      label (string, optional)\n      labelMarkdown (string, optional)\n      properties (array, optional)\n      category (object, optional)\n    count (number, optional)\n    _truncated (boolean, optional)',
+      "set": '# annotations.set\nReplace all annotations on a node\n\nExample: annotations(method:"set", id:"1:23", annotations:[{label:"Spacing: 16px", properties:["padding"]}])\n\nParams:\n    id (string, optional) \u2014 Node ID\n    annotations (array, optional) \u2014 Array of annotation objects to set (replaces all existing)\n      label (string, optional) \u2014 Plain text label\n      labelMarkdown (string, optional) \u2014 Rich text label (Markdown)\n      properties (string[], optional) \u2014 Measurement property types to display\n      categoryId (string, optional) \u2014 Category ID\n    items (array, optional) \u2014 Batch: [{id, annotations: [...]}, ...]\n      id (string, required)\n      annotations (array, required) \u2014 Annotations to set on this node\n\nResponse:\n    { results: ({id} | {error})[] }',
+      "add": '# annotations.add\nAdd an annotation to a node\n\nExample: annotations(method:"add", id:"1:23", labelMarkdown:"**Width**: 320px fixed", properties:["width"])\n\nParams:\n    id (string, optional) \u2014 Node ID\n    label (string, optional) \u2014 Plain text label (use label or labelMarkdown, not both)\n    labelMarkdown (string, optional) \u2014 Rich text label with Markdown formatting\n    properties (string[], optional) \u2014 Measurement property types to display on canvas\n    categoryId (string, optional) \u2014 Category ID to group this annotation\n    items (array, optional) \u2014 Batch: [{id, label?, labelMarkdown?, properties?, categoryId?}, ...]\n      id (string, required)\n      label (string, optional)\n      labelMarkdown (string, optional)\n      properties (string[], optional)\n      categoryId (string, optional)\n\nResponse:\n    { results: ({id} | {error})[] }',
+      "remove": '# annotations.remove\nRemove an annotation from a node by index\n\nExample: annotations(method:"remove", id:"1:23", index:0)\n\nParams:\n    id (string, optional) \u2014 Node ID\n    index (number, optional) \u2014 Annotation index to remove (from get response)\n    items (array, optional) \u2014 Batch: [{id, index}, ...]\n      id (string, required)\n      index (number, required)\n\nResponse:\n    { results: ({id} | {error})[] }',
+      "categories": '# annotations.categories\nList all annotation categories in the file\n\nExample: annotations(method:"categories")\n\nNo params.\n\nResponse:\n    categories (array, optional)\n      id (string, optional)\n      label (string, optional)\n      color (string, optional)\n      isPreset (boolean, optional)',
+      "create_category": '# annotations.create_category\nCreate a new annotation category\n\nExample: annotations(method:"create_category", label:"Spacing", color:"blue")\n\nParams:\n    label (string, required) \u2014 Category label\n    color (yellow | orange | red | pink | violet | blue | teal | green, required) \u2014 Category color\n\nResponse:\n    id (string, optional)\n    label (string, optional)\n    color (string, optional)',
       "update_category": `# annotations.update_category
 Update an annotation category's label or color
 
@@ -97,14 +97,33 @@ Example: annotations(method:"update_category", id:"cat:123", label:"Layout", col
 Params:
     id (string, required) \u2014 Category ID
     label (string, optional) \u2014 New label
-    color (yellow | orange | red | pink | violet | blue | teal | green, optional) \u2014 New color`,
-      "delete_category": '# annotations.delete_category\nDelete an annotation category\n\nExample: annotations(method:"delete_category", id:"cat:123")\n\nParams:\n    id (string, required) \u2014 Category ID to delete'
+    color (yellow | orange | red | pink | violet | blue | teal | green, optional) \u2014 New color
+
+Response:
+    id (string, optional)
+    label (string, optional)
+    color (string, optional)`,
+      "delete_category": '# annotations.delete_category\nDelete an annotation category\n\nExample: annotations(method:"delete_category", id:"cat:123")\n\nParams:\n    id (string, required) \u2014 Category ID to delete\n\nResponse:\n    deleted (boolean, optional)'
     }
   },
   "components": {
-    "summary": '# components\nCreate and manage reusable components and variant sets.\n\nMethods:\n  clone                Duplicate nodes \u2014 produces a same-type copy (frame\u2192frame, instance\u2192instance, component\u2192component). Instance clones reference the same source component; they do not duplicate the component definition. [create]\n  audit                Run lint on a node \u2014 returns severity-ranked findings [read]\n  reparent             Move nodes into a new parent [edit]\n  list                 List local component names (variant sets as single entries) [read]\n  get                  Get component detail \u2014 property definitions + optional node tree for structural inspection [read]\n  create               Create components [create]\n  commit               Commit a staged component \u2014 unwraps from [STAGED] container into the original target location. [edit]\n  update               Add, edit, or delete component properties [edit]\n  delete               Delete components or component sets [edit]\n\n// depth: omit \u2192 id+name stubs | 0 \u2192 props + child stubs | N \u2192 recurse N | -1 \u2192 full tree\n// fields: whitelist e.g. ["fills","opacity"] \u2014 id, name, type always included. Pass ["*"] for all.\n// layoutSizingHorizontal/Vertical: FIXED | HUG | FILL \u2014 how the node sizes within auto-layout.\n// Colors: fillVariableName/strokeVariableName bind by name \u2014 preferred over raw color values.\n// Note: node-based endpoints (frames, text, instances, components) use `results` as the list key.\n//   Standalone endpoints (styles, variables, variable_collections) use `items`. Components.list uses `items` (catalog view).\n// ---\n// visible: false hides the node. Omitted from response when true (the default).\n// locked: true prevents editing in Figma UI. Omitted when false (the default).\n// rotation: degrees (0-360). Omitted when 0.\n// blendMode: layer blend mode. Omitted when PASS_THROUGH (the default).\n// layoutPositioning: ABSOLUTE = floating inside auto-layout parent. Omitted when AUTO (the default).\n// minWidth/maxWidth/minHeight/maxHeight: responsive constraints for auto-layout children.\n// constraints: position behavior in non-auto-layout parents. Ignored inside auto-layout frames.\n// bindings: bind design variables to node properties. field uses slash path: "fills/0/color" (first fill), "strokes/0/color", "opacity", "width", "height", "cornerRadius", "paddingLeft", "itemSpacing".\n// explicitMode: pin a variable mode on this node. Use { collectionName, modeName } (preferred) or { collectionId, modeId }.\n// properties: escape hatch \u2014 set any Figma node property directly. Use only when no dedicated field exists.\ninterface Node {\n  id: string; name: string; type: string;\n  visible?: boolean;       // omitted when true\n  locked?: boolean;        // omitted when false\n  opacity?: number;        // omitted when 1\n  rotation?: number;       // omitted when 0\n  blendMode?: string;      // omitted when PASS_THROUGH\n  layoutPositioning?: "AUTO" | "ABSOLUTE";\n  layoutSizingHorizontal?: "FIXED" | "HUG" | "FILL";\n  layoutSizingVertical?: "FIXED" | "HUG" | "FILL";\n  minWidth?: number; maxWidth?: number; minHeight?: number; maxHeight?: number;\n  absoluteBoundingBox: { x: number; y: number; width: number; height: number };\n  fills?: Paint[];         // solid: {type: "SOLID", color: {r, g, b, a}}\n  strokes?: Paint[];\n  effects?: Effect[];      // DROP_SHADOW | INNER_SHADOW | LAYER_BLUR | BACKGROUND_BLUR\n  children?: NodeStub[];   // stubs: {id, name, type} \u2014 use depth to expand\n}\n// PatchItem uses flat params matching create shape \u2014 no nested sub-objects.\n// Fill/stroke/corner/layout/text params are identical to frames.create and text.create.\n// Unknown keys produce a warning, preventing silent failures.\n// Components are reusable design elements. Instances stay linked to the component and inherit changes.\n// Workflow: create component (with properties) \u2192 add children \u2192 create instances via instances.create.\n// ---\n// A component set (variant set) groups related components as variants (e.g. Button/Primary, Button/Secondary).\n// Property types: BOOLEAN (toggle visibility), TEXT (editable text), INSTANCE_SWAP (swap child instance), VARIANT (variant picker).\n// exposeText: when creating from_node, text children become editable TEXT properties on the component.\n// Auto-bind: TEXT properties auto-bind to text children with matching names (case-insensitive).\n// Example: properties:[{propertyName:"Label", type:"TEXT", defaultValue:"Click"}] binds to a child text node named "Label".\n// text.create accepts componentPropertyName to bind on creation \u2014 walks up ancestors to find the nearest component.\n//   For nested text (text inside frames inside a component), componentPropertyName resolves via ancestor walk. Alternatively, pass componentId explicitly.\n//   For existing nodes with many text children, prefer components(method:"create", type:"from_node", exposeText:true) \u2014 it auto-discovers, creates TEXT properties, and binds all text nodes in one operation.\n// Property keys: read returns clean names ("Label"), write requires the #suffix ("Label#1:0"). Call components.get(id) to discover exact keys before edit/delete.\n// ComponentItem accepts the same params as FrameItem (layout, fill, stroke, sizing, min/max).\n// A component IS a frame \u2014 create it directly with all layout properties, then add children.\n// SIZING: Components with text need a width constraint \u2014 set width + layoutSizingHorizontal:"FIXED".\n//   Without it, text won\'t wrap and the component grows unboundedly.\n//   HUG on both axes is only correct for intrinsically-sized elements (buttons, badges, icons).\n// action: "add" (default) \u2014 requires type + defaultValue. "edit" \u2014 pass defaultValue to change value, name to rename property. "delete" \u2014 just propertyName#suffix.\n// action: "rename_variant" \u2014 renames a variant option VALUE (not the property). Pass defaultValue=current option name, name=new option name.\n// For VARIANT properties: "edit" with defaultValue reorders children to set the default variant.\n// Adding variants: clone an existing variant into the set with a new name. See guidelines(topic:"component-structure") for workflow.\n\nUse components(method: "help", topic: "<method>") for method details.',
+    "summary": '# components\nCreate and manage reusable components and variant sets.\n\nMethods:\n  clone                Duplicate nodes \u2014 produces a same-type copy (frame\u2192frame, instance\u2192instance, component\u2192component). Instance clones reference the same source component; they do not duplicate the component definition. [create]\n  scale                Proportionally rescale a node subtree using Figma\'s visual Scale tool behavior. This is for visual/artifact scaling, not responsive layout resizing. [edit]\n  audit                Run lint on a node \u2014 returns severity-ranked findings [read]\n  reparent             Move nodes into a new parent [edit]\n  list                 List local component names (variant sets as single entries) [read]\n  get                  Get component detail \u2014 property definitions + optional node tree for structural inspection [read]\n  create               Create components [create]\n  commit               Commit a staged component \u2014 unwraps from [STAGED] container into the original target location. [edit]\n  update               Add, edit, or delete component properties [edit]\n  delete               Delete components or component sets [edit]\n\n// depth: omit \u2192 id+name stubs | 0 \u2192 props + child stubs | N \u2192 recurse N | -1 \u2192 full tree\n// fields: whitelist e.g. ["fills","opacity"] \u2014 id, name, type always included. Pass ["*"] for all.\n// layoutSizingHorizontal/Vertical: FIXED | HUG | FILL \u2014 how the node sizes within auto-layout.\n// Colors: fillVariableName/strokeVariableName bind by name \u2014 preferred over raw color values.\n// Note: node-based endpoints (frames, text, instances, components) use `results` as the list key.\n//   Standalone endpoints (styles, variables, variable_collections) use `items`. Components.list uses `items` (catalog view).\n// ---\n// visible: false hides the node. Omitted from response when true (the default).\n// locked: true prevents editing in Figma UI. Omitted when false (the default).\n// rotation: degrees (0-360). Omitted when 0.\n// blendMode: layer blend mode. Omitted when PASS_THROUGH (the default).\n// layoutPositioning: ABSOLUTE = floating inside auto-layout parent. Omitted when AUTO (the default).\n// minWidth/maxWidth/minHeight/maxHeight: responsive constraints for auto-layout children.\n// constraints: position behavior in non-auto-layout parents. Ignored inside auto-layout frames.\n// bindings: bind design variables to node properties. field uses slash path: "fills/0/color" (first fill), "strokes/0/color", "opacity", "width", "height", "cornerRadius", "paddingLeft", "itemSpacing".\n// explicitMode: pin a variable mode on this node. Use { collectionName, modeName } (preferred) or { collectionId, modeId }.\n// clipsContent: clip children to the node bounds where supported (frames/components/instances). Set false for overflow-visible layouts.\ninterface Node {\n  id: string; name: string; type: string;\n  visible?: boolean;       // omitted when true\n  locked?: boolean;        // omitted when false\n  opacity?: number;        // omitted when 1\n  rotation?: number;       // omitted when 0\n  blendMode?: string;      // omitted when PASS_THROUGH\n  layoutPositioning?: "AUTO" | "ABSOLUTE";\n  layoutSizingHorizontal?: "FIXED" | "HUG" | "FILL";\n  layoutSizingVertical?: "FIXED" | "HUG" | "FILL";\n  minWidth?: number; maxWidth?: number; minHeight?: number; maxHeight?: number;\n  absoluteBoundingBox: { x: number; y: number; width: number; height: number };\n  fills?: Paint[];         // readback Paint[]; authoring supports SOLID + gradients via gradientTransform + gradientStops\n  strokes?: Paint[];\n  effects?: Effect[];      // DROP_SHADOW | INNER_SHADOW | LAYER_BLUR | BACKGROUND_BLUR\n  children?: NodeStub[];   // stubs: {id, name, type} \u2014 use depth to expand\n}\n// PatchItem uses flat params matching create shape \u2014 no nested sub-objects.\n// Fill/stroke/corner/layout/text params are identical to frames.create and text.create. Paint[] authoring supports SOLID + gradients only; IMAGE/VIDEO/PATTERN are readback-only metadata.\n// Unknown keys produce a warning, preventing silent failures.\n// Components are reusable design elements. Instances stay linked to the component and inherit changes.\n// Workflow: create component (with properties) \u2192 add children \u2192 create instances via instances.create.\n// ---\n// A component set (variant set) groups related components as variants (e.g. Button/Primary, Button/Secondary).\n// Property types: BOOLEAN (toggle visibility), TEXT (editable text), INSTANCE_SWAP (swap child instance), VARIANT (variant picker).\n// exposeText: when creating from_node, text children become editable TEXT properties on the component.\n// Auto-bind: TEXT properties auto-bind to text children with matching names (case-insensitive).\n// Example: properties:[{propertyName:"Label", type:"TEXT", defaultValue:"Click"}] binds to a child text node named "Label".\n// text.create accepts componentPropertyName to bind on creation \u2014 walks up ancestors to find the nearest component.\n//   For nested text (text inside frames inside a component), componentPropertyName resolves via ancestor walk. Alternatively, pass componentId explicitly.\n//   For existing nodes with many text children, prefer components(method:"create", type:"from_node", exposeText:true) \u2014 it auto-discovers, creates TEXT properties, and binds all text nodes in one operation.\n// Property keys: read returns clean names ("Label"), write requires the #suffix ("Label#1:0"). Call components.get(id) to discover exact keys before edit/delete.\n// ComponentItem accepts the same params as FrameItem (layout, fill, stroke, sizing, min/max).\n// A component IS a frame \u2014 create it directly with all layout properties, then add children.\n// Examples assume design tokens/styles already exist. Build components from tokens/styles, not raw color/spacing/type values.\n// SIZING: Components with text need a width constraint \u2014 set width + layoutSizingHorizontal:"FIXED".\n//   Without it, text won\'t wrap and the component grows unboundedly.\n//   HUG on both axes is only correct for intrinsically-sized elements (buttons, badges, icons).\n// action: "add" (default) \u2014 requires type + defaultValue. "edit" \u2014 pass defaultValue to change value, name to rename property. "delete" \u2014 just propertyName#suffix.\n// action: "rename_variant" \u2014 renames a variant option VALUE (not the property). Pass defaultValue=current option name, name=new option name.\n// For VARIANT properties: "edit" with defaultValue reorders children to set the default variant.\n// Adding variants: clone an existing variant into the set with a new name. See guidelines(topic:"component-structure") for workflow.\n\nUse components(method: "help", topic: "<method>") for method details.\n// Shared types:\n// Color: hex "#RGB"|"#RGBA"|"#RRGGBB"|"#RRGGBBAA" or {r: 0-1, g: 0-1, b: 0-1, a?: 0-1}\n// VariableAlias: {type: "VARIABLE_ALIAS", id: string}. The id must be a Figma VariableID; discover it via variables.get/list or variable_collections.get. Prefer colorVariableName/fillVariableName/strokeVariableName when available; Paint[] VariableAlias is mainly for precise Paint[] round-trips and gradient stop bindings.\n// Transform: [[number, number, number], [number, number, number]] (Figma Plugin API 2\xD73 matrix)\n// BlendMode: "PASS_THROUGH"|"NORMAL"|"DARKEN"|"MULTIPLY"|"LINEAR_BURN"|"COLOR_BURN"|"LIGHTEN"|"SCREEN"|"LINEAR_DODGE"|"COLOR_DODGE"|"OVERLAY"|"SOFT_LIGHT"|"HARD_LIGHT"|"DIFFERENCE"|"EXCLUSION"|"HUE"|"SATURATION"|"COLOR"|"LUMINOSITY"\n// ColorStop: {position: 0-1, color: Color, boundVariables?: {color?: VariableAlias}}\n// GradientPaint: {type: "GRADIENT_LINEAR"|"GRADIENT_RADIAL"|"GRADIENT_ANGULAR"|"GRADIENT_DIAMOND", gradientTransform: Transform, gradientStops: ColorStop[], visible?: boolean, opacity?: number, blendMode?: BlendMode}. Use gradientTransform + gradientStops (basic left-to-right: [[1,0,0],[0,1,0]]); do not use CSS gradients or REST gradientHandlePositions.\n// Effect: {type: "DROP_SHADOW"|"INNER_SHADOW"|"LAYER_BLUR"|"BACKGROUND_BLUR", radius: number, color?: {r,g,b,a} (0-1), offset?: {x, y}, spread?: number, visible?: boolean}\n// Paint: Paint[] authoring accepts only SOLID and GRADIENT_LINEAR/GRADIENT_RADIAL/GRADIENT_ANGULAR/GRADIENT_DIAMOND. SolidPaint: {type: "SOLID", color: Color, visible?: boolean, opacity?: number, blendMode?: BlendMode, boundVariables?: {color?: VariableAlias}}. GradientPaint authoring: {type: GRADIENT_*, gradientTransform: Transform, gradientStops: ColorStop[], visible?, opacity?, blendMode?}; bind variables on gradientStops[].boundVariables.color, not top-level gradient boundVariables. Do not pass IMAGE/VIDEO/PATTERN to create/update Paint[]; those may appear only in readback metadata from existing Figma content. Use imageUrl/images for image authoring. VIDEO/PATTERN authoring is not supported here. Do not use CSS gradients or REST gradientHandlePositions.\n// NodeStub: {id: string, name: string, type: string}',
     "methods": {
-      "clone": "# components.clone\nDuplicate nodes \u2014 produces a same-type copy (frame\u2192frame, instance\u2192instance, component\u2192component). Instance clones reference the same source component; they do not duplicate the component definition.\n\nParams:\n    id (string, optional) \u2014 Node ID\n    name (string, optional) \u2014 Rename the clone (set before appending to parent \u2014 required when cloning a variant into its component set to avoid duplicate names)\n    parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.\n    x (number, optional) \u2014 X position (default: 0)\n    y (number, optional) \u2014 Y position (default: 0)\n    items (array, optional) \u2014 Batch: [{id, name?, parentId?, x?, y?}, ...]. Alternative to single-item params.\n      id (string, required) \u2014 Node ID to clone\n      name (string, optional) \u2014 Rename the clone\n      parentId (string, optional) \u2014 Target parent\n      x (number, optional)\n      y (number, optional)\n    depth (number, optional) \u2014 Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.",
+      "clone": "# components.clone\nDuplicate nodes \u2014 produces a same-type copy (frame\u2192frame, instance\u2192instance, component\u2192component). Instance clones reference the same source component; they do not duplicate the component definition.\n\nParams:\n    id (string, optional) \u2014 Node ID\n    name (string, optional) \u2014 Rename the clone (set before appending to parent \u2014 required when cloning a variant into its component set to avoid duplicate names)\n    parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.\n    x (number, optional) \u2014 X position (default: 0)\n    y (number, optional) \u2014 Y position (default: 0)\n    items (array, optional) \u2014 Batch: [{id, name?, parentId?, x?, y?}, ...]. Alternative to single-item params.\n      id (string, required) \u2014 Node ID to clone\n      name (string, optional) \u2014 Rename the clone\n      parentId (string, optional) \u2014 Target parent\n      x (number, optional)\n      y (number, optional)\n    depth (number, optional) \u2014 Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.\n\nResponse:\n    { results: ({id} | {error})[] }",
+      "scale": `# components.scale
+Proportionally rescale a node subtree using Figma's visual Scale tool behavior. This is for visual/artifact scaling, not responsive layout resizing.
+
+Example: components(method:"scale", id:"1:23", factor:0.5)
+
+Params:
+    id (string, optional) \u2014 Node ID to scale
+    factor (number, optional) \u2014 Scale factor, >= 0.01. 0.5 = 50%, 2 = 200%. Scales children, text, strokes, effects, and layout geometry from the node's top-left. On auto-layout or HUG/FILL nodes, Figma may resolve responsive sizing to fixed width/height.
+    items (array, optional) \u2014 Batch: [{id, factor}, ...]. Alternative to single-item params.
+      id (string, required) \u2014 Node ID to scale
+      factor (number, required) \u2014 Scale factor, >= 0.01. 0.5 = 50%, 2 = 200%.
+
+Response:
+    { results: ("ok" | {error})[] }`,
       "audit": `# components.audit
 Run lint on a node \u2014 returns severity-ranked findings
 
@@ -114,189 +133,216 @@ Params:
     maxDepth (number, optional) \u2014 Max tree depth (default: 10)
     maxFindings (number, optional) \u2014 Max findings (default: 50)
     minSeverity (error | unsafe | heuristic | style | verbose, optional) \u2014 Minimum severity to report (default: style). Set to 'verbose' to include AAA contrast and line-height checks.
-    skipInstances (boolean, optional) \u2014 Skip instance internals \u2014 findings inside instances are owned by the component (default: true)`,
-      "reparent": "# components.reparent\nMove nodes into a new parent\n\nParams:\n    items (array, required) \u2014 Array of {id, parentId, index?}\n      id (string, required)\n      parentId (string, required)\n      index (number, optional)",
-      "list": "# components.list\nList local component names (variant sets as single entries)\n\nParams:\n    query (string, optional) \u2014 Name search query (case-insensitive substring match)\n    offset (number, optional) \u2014 Skip N items for pagination (default 0)\n    limit (number, optional) \u2014 Max items per page (default 100)",
-      "get": "# components.get\nGet component detail \u2014 property definitions + optional node tree for structural inspection\n\nParams:\n    id (string, optional) \u2014 Component or component set ID\n    names (string[], optional) \u2014 Batch lookup by name (case-insensitive). Either id or names is required.\n    depth (number, optional) \u2014 Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.\n    verbose (boolean, optional) \u2014 Include all properties (bounding box, constraints, text style details). Default false \u2014 returns slim, actionable output.",
+    skipInstances (boolean, optional) \u2014 Skip instance internals \u2014 findings inside instances are owned by the component (default: true)
+
+Response:
+    nodeId (string, optional)
+    nodeName (string, optional)
+    categories (array, optional) \u2014 Sorted by severity (error > unsafe > heuristic > style)`,
+      "reparent": '# components.reparent\nMove nodes into a new parent\n\nParams:\n    items (array, required) \u2014 Array of {id, parentId, index?}\n      id (string, required)\n      parentId (string, required)\n      index (number, optional)\n\nResponse:\n    { results: ("ok" | {error})[] }',
+      "list": "# components.list\nList local component names (variant sets as single entries)\n\nParams:\n    query (string, optional) \u2014 Name search query (case-insensitive substring match)\n    offset (number, optional) \u2014 Skip N items for pagination (default 0)\n    limit (number, optional) \u2014 Max items per page (default 100)\n\nResponse:\n    totalCount (number, required)\n    returned (number, optional)\n    offset (number, optional)\n    limit (number, optional)\n    items (array, required)",
+      "get": "# components.get\nGet component detail \u2014 property definitions + optional node tree for structural inspection\n\nParams:\n    id (string, optional) \u2014 Component or component set ID\n    names (string[], optional) \u2014 Batch lookup by name (case-insensitive). Either id or names is required.\n    depth (number, optional) \u2014 Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.\n    verbose (boolean, optional) \u2014 Include all properties (bounding box, constraints, text style details). Default false \u2014 returns slim, actionable output.\n\nResponse:\n    results (array, required) \u2014 Component summaries (without depth) or full node trees with properties merged (with depth)\n      id (string, optional)\n      name (string, optional)\n      description (string, optional)\n      properties (object, optional) \u2014 Property definitions \u2014 {name: {type, defaultValue, options?}}\n    _truncated (boolean, optional)",
       "create": `# components.create
 Create components
 
-Example: components(method:"create", type:"component", items:[{name:"Card", layoutMode:"VERTICAL", padding:"16", itemSpacing:"8", fillVariableName:"bg/surface", children:[{type:"text", text:"Title", componentPropertyName:"Title"}, {type:"text", text:"Description", fontSize:14, componentPropertyName:"Description"}], properties:[{propertyName:"Show Icon", type:"BOOLEAN", defaultValue:true}]}])
+Call shape: components(method:"create", type:"<type>", items:[{...type-specific fields...}])
+Do not pass type-specific item fields at the top level; put them inside items[].
 
 Discriminant: type (component | from_node | variant_set)
+Top-level params:
+    type (component | from_node | variant_set, required) \u2014 Selects which item shape to use
+    items (array, required) \u2014 One or more type-specific item objects
 
   ## component \u2014 Create component with full frame properties (layout, fill, stroke, sizing). A component IS a frame \u2014 build directly, no need to create a frame first.
-    name (string, required) \u2014 Component name
-    parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.
-    x (number, optional) \u2014 X position (default: 0)
-    y (number, optional) \u2014 Y position (default: 0)
-    width (number, optional) \u2014 Width in px (omit to shrink-to-content via HUG)
-    height (number, optional) \u2014 Height in px (omit to shrink-to-content via HUG)
-    rotation (number, optional) \u2014 Rotation in degrees (0-360)
-    visible (boolean, optional) \u2014 Show/hide (default true)
-    locked (boolean, optional) \u2014 Lock/unlock (default false)
-    opacity (string, optional) \u2014 Opacity (0-1) or variable name
-    blendMode (PASS_THROUGH | NORMAL | DARKEN | MULTIPLY | LINEAR_BURN | COLOR_BURN | LIGHTEN | SCREEN | LINEAR_DODGE | COLOR_DODGE | OVERLAY | SOFT_LIGHT | HARD_LIGHT | DIFFERENCE | EXCLUSION | HUE | SATURATION | COLOR | LUMINOSITY, optional)
-    effectStyleName (string, optional) \u2014 Effect style name (e.g. 'Shadow/Card') for shadows, blurs
-    fills (array, optional) \u2014 Fill paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] for transparent. Primary way to set fills.
-    fillColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid fill (auto-binds to matching variable/style)
-    fillStyleName (string, optional) \u2014 Paint style name for fill
-    fillVariableName (string, optional) \u2014 Color variable by name e.g. 'bg/primary'
-    imageUrl (string, optional) \u2014 Image source \u2014 'pexel:<id>' for Pexels photos, a public URL, or a local file path. SVGs are inserted as vectors; raster images become IMAGE fills.
-    imageScaleMode (FILL | FIT | CROP | TILE, optional) \u2014 How the image is scaled within the frame (default: FILL)
-    strokes (array, optional) \u2014 Stroke paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] to clear. Primary way to set strokes.
-    strokeColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid stroke (auto-binds to matching variable/style)
-    strokeStyleName (string, optional) \u2014 Paint style name for stroke
-    strokeVariableName (string, optional) \u2014 Color variable by name for stroke
-    strokeWeight (string, optional) \u2014 All sides (number) or variable name (string). Per-side: strokeTopWeight, strokeBottomWeight, strokeLeftWeight, strokeRightWeight.
-    strokeTopWeight (string, optional)
-    strokeBottomWeight (string, optional)
-    strokeLeftWeight (string, optional)
-    strokeRightWeight (string, optional)
-    strokeAlign (INSIDE | OUTSIDE | CENTER, optional) \u2014 Stroke position (default: INSIDE)
-    cornerRadius (string, optional) \u2014 All corners (number) or variable name (string). Per-corner: topLeftRadius, topRightRadius, bottomRightRadius, bottomLeftRadius.
-    topLeftRadius (string, optional)
-    topRightRadius (string, optional)
-    bottomRightRadius (string, optional)
-    bottomLeftRadius (string, optional)
-    layoutMode (NONE | HORIZONTAL | VERTICAL, optional) \u2014 Layout direction (default: auto \u2014 NONE when width+height set, otherwise inferred from layout props)
-    layoutWrap (NO_WRAP | WRAP, optional) \u2014 Wrap children to new rows (HORIZONTAL layout only \u2014 Figma does not support WRAP on VERTICAL layouts). Use column frames inside a HORIZONTAL parent for vertical grid patterns.
-    padding (string, optional) \u2014 All edges (number) or variable name (string). Per-edge: paddingTop, paddingRight, paddingBottom, paddingLeft.
-    paddingTop (string, optional)
-    paddingRight (string, optional)
-    paddingBottom (string, optional)
-    paddingLeft (string, optional)
-    primaryAxisAlignItems (MIN | MAX | CENTER | SPACE_BETWEEN, optional)
-    counterAxisAlignItems (MIN | MAX | CENTER | BASELINE, optional)
-    itemSpacing (string, optional) \u2014 Spacing between children (number or variable name string, default: 0)
-    counterAxisSpacing (string, optional) \u2014 Gap between wrapped rows (requires layoutWrap: WRAP)
-    strokesIncludedInLayout (boolean, optional) \u2014 Include stroke width in layout measurements (default: false)
-    overflowDirection (NONE | HORIZONTAL | VERTICAL | BOTH, optional) \u2014 Scroll overflow in prototype (default: NONE)
-    layoutPositioning (AUTO | ABSOLUTE, optional) \u2014 ABSOLUTE = floating inside auto-layout parent
-    layoutSizingHorizontal (FIXED | HUG | FILL, optional)
-    layoutSizingVertical (FIXED | HUG | FILL, optional)
-    minWidth (number, optional) \u2014 Min width for responsive auto-layout
-    maxWidth (number, optional) \u2014 Max width for responsive auto-layout
-    minHeight (number, optional) \u2014 Min height for responsive auto-layout
-    maxHeight (number, optional) \u2014 Max height for responsive auto-layout
-    annotations (array, optional) \u2014 Set annotations \u2014 [{label?, labelMarkdown?, properties?, categoryId?}]. Properties validated per node type.
-    description (string, optional) \u2014 Component description (shown in Figma's component panel)
-    children (array, optional) \u2014 Inline child nodes \u2014 build nested trees in one call. Types: text: {type:"text", text, componentPropertyName?, fontFamily?, fontSize?, fontWeight?, fontStyle?, fontColor?, layoutSizingHorizontal?}. frame: {type:"frame", name?, layoutMode?, fillColor?, width?, layoutSizingHorizontal?, children?}. instance: {type:"instance", componentId, componentPropertyName?, variantProperties?, properties?}. component: {type:"component", name, children?}. All params from text/frame endpoints are supported on their respective types. componentPropertyName auto-creates and binds a TEXT (text) or INSTANCE_SWAP (instance) property. Always set layoutSizingHorizontal + layoutSizingVertical on children inside auto-layout parents (FILL, HUG, or FIXED). Example: children:[{type:"text", text:"Label", componentPropertyName:"Label", fontSize:14, fontColorVariableName:"text/primary", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}, {type:"frame", name:"Actions", layoutMode:"HORIZONTAL", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG", itemSpacing:8, children:[{type:"instance", componentId:"1:2", componentPropertyName:"Action", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}]}]
+    Example: components(method:"create", type:"component", items:[{name:"Card", width:320, height:200, layoutMode:"VERTICAL", padding:"space/16", itemSpacing:"space/8", fillVariableName:"bg/surface", strokeVariableName:"border/subtle", strokeWeight:"stroke/1", cornerRadius:"radius/12", children:[{type:"text", name:"Title", text:"Title", componentPropertyName:"Title", textStyleName:"Heading/Medium", fontColorVariableName:"text/primary", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}]}])
+    Item fields for items[] when type:"component":
+      name (string, required) \u2014 Component name
+      parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.
+      x (number, optional) \u2014 X position (default: 0)
+      y (number, optional) \u2014 Y position (default: 0)
+      width (number, optional) \u2014 Width in px (omit to shrink-to-content via HUG)
+      height (number, optional) \u2014 Height in px (omit to shrink-to-content via HUG)
+      rotation (number, optional) \u2014 Rotation in degrees (0-360)
+      visible (boolean, optional) \u2014 Show/hide (default true)
+      locked (boolean, optional) \u2014 Lock/unlock (default false)
+      opacity (string, optional) \u2014 Opacity (0-1) or variable name
+      blendMode (PASS_THROUGH | NORMAL | DARKEN | MULTIPLY | LINEAR_BURN | COLOR_BURN | LIGHTEN | SCREEN | LINEAR_DODGE | COLOR_DODGE | OVERLAY | SOFT_LIGHT | HARD_LIGHT | DIFFERENCE | EXCLUSION | HUE | SATURATION | COLOR | LUMINOSITY, optional)
+      effectStyleName (string, optional) \u2014 Effect style name (e.g. 'Shadow/Card') for shadows, blurs
+      fills (Paint[], optional) \u2014 Fill Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] for transparent. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables; use imageUrl/images for image authoring. IMAGE/VIDEO/PATTERN may appear in readback metadata only. Primary way to set non-image fills.
+      fillColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid fill (auto-binds to matching variable/style)
+      fillStyleName (string, optional) \u2014 Paint style name for fill
+      fillVariableName (string, optional) \u2014 Color variable by name e.g. 'bg/surface'
+      imageUrl (string, optional) \u2014 Image source \u2014 'pexel:<id>' for Pexels photos, a public URL, or a local file path. SVGs are inserted as vectors; raster images become IMAGE fills.
+      imageScaleMode (FILL | FIT | CROP | TILE, optional) \u2014 How the image is scaled within the frame (default: FILL)
+      strokes (Paint[], optional) \u2014 Stroke Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] to clear. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables. IMAGE/VIDEO/PATTERN may appear in readback metadata only. Primary way to set strokes.
+      strokeColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid stroke (auto-binds to matching variable/style)
+      strokeStyleName (string, optional) \u2014 Paint style name for stroke
+      strokeVariableName (string, optional) \u2014 Color variable by name for stroke
+      strokeWeight (string, optional) \u2014 All sides (number) or variable name (string). Per-side: strokeTopWeight, strokeBottomWeight, strokeLeftWeight, strokeRightWeight.
+      strokeTopWeight (string, optional)
+      strokeBottomWeight (string, optional)
+      strokeLeftWeight (string, optional)
+      strokeRightWeight (string, optional)
+      strokeAlign (INSIDE | OUTSIDE | CENTER, optional) \u2014 Stroke position (default: INSIDE)
+      cornerRadius (string, optional) \u2014 All corners (number) or variable name (string). Per-corner: topLeftRadius, topRightRadius, bottomRightRadius, bottomLeftRadius.
+      topLeftRadius (string, optional)
+      topRightRadius (string, optional)
+      bottomRightRadius (string, optional)
+      bottomLeftRadius (string, optional)
+      layoutMode (NONE | HORIZONTAL | VERTICAL, optional) \u2014 Layout direction (default: auto \u2014 NONE when width+height set, otherwise inferred from layout props)
+      layoutWrap (NO_WRAP | WRAP, optional) \u2014 Wrap children to new rows (HORIZONTAL layout only \u2014 Figma does not support WRAP on VERTICAL layouts). Use column frames inside a HORIZONTAL parent for vertical grid patterns.
+      padding (string, optional) \u2014 All edges (number) or variable name (string). Per-edge: paddingTop, paddingRight, paddingBottom, paddingLeft.
+      paddingTop (string, optional)
+      paddingRight (string, optional)
+      paddingBottom (string, optional)
+      paddingLeft (string, optional)
+      primaryAxisAlignItems (MIN | MAX | CENTER | SPACE_BETWEEN, optional)
+      counterAxisAlignItems (MIN | MAX | CENTER | BASELINE, optional)
+      itemSpacing (string, optional) \u2014 Spacing between children (number or variable name string, default: 0)
+      counterAxisSpacing (string, optional) \u2014 Gap between wrapped rows (requires layoutWrap: WRAP)
+      strokesIncludedInLayout (boolean, optional) \u2014 Include stroke width in layout measurements (default: false)
+      overflowDirection (NONE | HORIZONTAL | VERTICAL | BOTH, optional) \u2014 Scroll overflow in prototype (default: NONE)
+      layoutPositioning (AUTO | ABSOLUTE, optional) \u2014 ABSOLUTE = floating inside auto-layout parent
+      layoutSizingHorizontal (FIXED | HUG | FILL, optional)
+      layoutSizingVertical (FIXED | HUG | FILL, optional)
+      minWidth (number, optional) \u2014 Min width for responsive auto-layout
+      maxWidth (number, optional) \u2014 Max width for responsive auto-layout
+      minHeight (number, optional) \u2014 Min height for responsive auto-layout
+      maxHeight (number, optional) \u2014 Max height for responsive auto-layout
+      annotations (array, optional) \u2014 Set annotations \u2014 [{label?, labelMarkdown?, properties?, categoryId?}]. Properties validated per node type.
+      description (string, optional) \u2014 Component description (shown in Figma's component panel)
+      children (array, optional) \u2014 Inline child nodes \u2014 build nested trees in one call. Types: text: {type:"text", text, componentPropertyName?, textStyleName?, fontColorVariableName?, layoutSizingHorizontal?}. frame: {type:"frame", name?, layoutMode?, fillVariableName?, itemSpacing?, layoutSizingHorizontal?, children?}. instance: {type:"instance", componentId, componentPropertyName?, variantProperties?, properties?}. component: {type:"component", name, children?}. rectangle / ellipse / line: same params as the corresponding frames(method:"create", type:"rectangle"|"ellipse"|"line") branch. All params from text/frame endpoints are supported on their respective types. Inline fills/strokes accept Paint[] authoring input: SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. Do not use CSS gradients, REST gradientHandlePositions, or IMAGE/VIDEO/PATTERN in Paint[] authoring. componentPropertyName auto-creates and binds a TEXT (text) or INSTANCE_SWAP (instance) property. Always set layoutSizingHorizontal + layoutSizingVertical on children inside auto-layout parents (FILL, HUG, or FIXED). Example: children:[{type:"ellipse", name:"Dot", width:6, height:6, fillVariableName:"status/active"}, {type:"text", name:"Label", text:"Button", componentPropertyName:"Label", textStyleName:"Body/Medium", fontColorVariableName:"text/primary", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}, {type:"frame", name:"Actions", layoutMode:"HORIZONTAL", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG", itemSpacing:"space/8", children:[{type:"instance", componentId:"1:2", componentPropertyName:"Action", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}]}]
 
-    properties (array, optional) \u2014 Component properties to define at creation: [{propertyName, type, defaultValue}]. TEXT properties for inline children with componentPropertyName are created automatically.
-      propertyName (string, required) \u2014 Property name
-      type (BOOLEAN | TEXT | INSTANCE_SWAP, required) \u2014 Property type
-      defaultValue (string_or_boolean, required) \u2014 Default value
-      preferredValues (array, optional) \u2014 Preferred values for INSTANCE_SWAP
+      properties (array, optional) \u2014 Component properties to define at creation: [{propertyName, type, defaultValue}]. TEXT properties for inline children with componentPropertyName are created automatically.
+        propertyName (string, required) \u2014 Property name
+        type (BOOLEAN | TEXT | INSTANCE_SWAP, required) \u2014 Property type
+        defaultValue (string_or_boolean, required) \u2014 Default value
+        preferredValues (array, optional) \u2014 Preferred values for INSTANCE_SWAP
 
   ## from_node \u2014 Convert existing nodes to components. Text children auto-exposed as editable properties (exposeText: true).
-    nodeId (string, required) \u2014 Node ID to convert
-    name (string, optional) \u2014 Rename the component (default: keeps the node's current name)
-    exposeText (boolean, optional) \u2014 Auto-expose text as editable properties (default: true)
+    Example: components(method:"create", type:"from_node", items:[{nodeId:"1:23", name:"Button", exposeText:true}])
+    Item fields for items[] when type:"from_node":
+      nodeId (string, required) \u2014 Node ID to convert
+      name (string, optional) \u2014 Rename the component (default: keeps the node's current name)
+      exposeText (boolean, optional) \u2014 Auto-expose text as editable properties (default: true)
 
   ## variant_set \u2014 Combine components into a variant set. The resulting set is a frame \u2014 accepts all frame properties for layout/styling.
-    name (string, optional) \u2014 Node name
-    parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.
-    x (number, optional) \u2014 X position (default: 0)
-    y (number, optional) \u2014 Y position (default: 0)
-    width (number, optional) \u2014 Width in px (omit to shrink-to-content via HUG)
-    height (number, optional) \u2014 Height in px (omit to shrink-to-content via HUG)
-    rotation (number, optional) \u2014 Rotation in degrees (0-360)
-    visible (boolean, optional) \u2014 Show/hide (default true)
-    locked (boolean, optional) \u2014 Lock/unlock (default false)
-    opacity (string, optional) \u2014 Opacity (0-1) or variable name
-    blendMode (PASS_THROUGH | NORMAL | DARKEN | MULTIPLY | LINEAR_BURN | COLOR_BURN | LIGHTEN | SCREEN | LINEAR_DODGE | COLOR_DODGE | OVERLAY | SOFT_LIGHT | HARD_LIGHT | DIFFERENCE | EXCLUSION | HUE | SATURATION | COLOR | LUMINOSITY, optional)
-    effectStyleName (string, optional) \u2014 Effect style name (e.g. 'Shadow/Card') for shadows, blurs
-    fills (array, optional) \u2014 Fill paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] for transparent. Primary way to set fills.
-    fillColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid fill (auto-binds to matching variable/style)
-    fillStyleName (string, optional) \u2014 Paint style name for fill
-    fillVariableName (string, optional) \u2014 Color variable by name e.g. 'bg/primary'
-    imageUrl (string, optional) \u2014 Image source \u2014 'pexel:<id>' for Pexels photos, a public URL, or a local file path. SVGs are inserted as vectors; raster images become IMAGE fills.
-    imageScaleMode (FILL | FIT | CROP | TILE, optional) \u2014 How the image is scaled within the frame (default: FILL)
-    strokes (array, optional) \u2014 Stroke paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] to clear. Primary way to set strokes.
-    strokeColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid stroke (auto-binds to matching variable/style)
-    strokeStyleName (string, optional) \u2014 Paint style name for stroke
-    strokeVariableName (string, optional) \u2014 Color variable by name for stroke
-    strokeWeight (string, optional) \u2014 All sides (number) or variable name (string). Per-side: strokeTopWeight, strokeBottomWeight, strokeLeftWeight, strokeRightWeight.
-    strokeTopWeight (string, optional)
-    strokeBottomWeight (string, optional)
-    strokeLeftWeight (string, optional)
-    strokeRightWeight (string, optional)
-    strokeAlign (INSIDE | OUTSIDE | CENTER, optional) \u2014 Stroke position (default: INSIDE)
-    cornerRadius (string, optional) \u2014 All corners (number) or variable name (string). Per-corner: topLeftRadius, topRightRadius, bottomRightRadius, bottomLeftRadius.
-    topLeftRadius (string, optional)
-    topRightRadius (string, optional)
-    bottomRightRadius (string, optional)
-    bottomLeftRadius (string, optional)
-    layoutMode (NONE | HORIZONTAL | VERTICAL, optional) \u2014 Layout direction (default: auto \u2014 NONE when width+height set, otherwise inferred from layout props)
-    layoutWrap (NO_WRAP | WRAP, optional) \u2014 Wrap children to new rows (HORIZONTAL layout only \u2014 Figma does not support WRAP on VERTICAL layouts). Use column frames inside a HORIZONTAL parent for vertical grid patterns.
-    padding (string, optional) \u2014 All edges (number) or variable name (string). Per-edge: paddingTop, paddingRight, paddingBottom, paddingLeft.
-    paddingTop (string, optional)
-    paddingRight (string, optional)
-    paddingBottom (string, optional)
-    paddingLeft (string, optional)
-    primaryAxisAlignItems (MIN | MAX | CENTER | SPACE_BETWEEN, optional)
-    counterAxisAlignItems (MIN | MAX | CENTER | BASELINE, optional)
-    itemSpacing (string, optional) \u2014 Spacing between children (number or variable name string, default: 0)
-    counterAxisSpacing (string, optional) \u2014 Gap between wrapped rows (requires layoutWrap: WRAP)
-    strokesIncludedInLayout (boolean, optional) \u2014 Include stroke width in layout measurements (default: false)
-    overflowDirection (NONE | HORIZONTAL | VERTICAL | BOTH, optional) \u2014 Scroll overflow in prototype (default: NONE)
-    layoutPositioning (AUTO | ABSOLUTE, optional) \u2014 ABSOLUTE = floating inside auto-layout parent
-    layoutSizingHorizontal (FIXED | HUG | FILL, optional)
-    layoutSizingVertical (FIXED | HUG | FILL, optional)
-    minWidth (number, optional) \u2014 Min width for responsive auto-layout
-    maxWidth (number, optional) \u2014 Max width for responsive auto-layout
-    minHeight (number, optional) \u2014 Min height for responsive auto-layout
-    maxHeight (number, optional) \u2014 Max height for responsive auto-layout
-    annotations (array, optional) \u2014 Set annotations \u2014 [{label?, labelMarkdown?, properties?, categoryId?}]. Properties validated per node type.
-    componentIds (string[], optional) \u2014 Existing component IDs to combine (min 2). Alternative to children.
-    variantPropertyName (string, optional) \u2014 Rename the auto-generated variant property (default: 'Property 1')
-    children (array, optional) \u2014 Inline variant components. Each must be {type:"component", name, children?, ...frame_params}. All variants must share the same child structure. Alternative to componentIds \u2014 do not combine both.`,
-      "commit": '# components.commit\nCommit a staged component \u2014 unwraps from [STAGED] container into the original target location.\n\nExample: components(method:"commit", id:"1:234")\n\nParams:\n    id (string, required) \u2014 Staged node ID to commit',
-      "update": '# components.update\nAdd, edit, or delete component properties\n\nExample: components(method:"update", items:[{id:"1:23", propertyName:"Label", action:"edit", defaultValue:"Click Me"}])\n\nParams:\n    items (UpdatePropertyItem[], required) \u2014 Array of {id, propertyName, action?, type?, defaultValue?, name?, preferredValues?}\n      id (string, required) \u2014 Component or component set ID\n      propertyName (string, required) \u2014 Property name with #suffix for edit/delete (e.g. "Label#1:0"). Call components.get to find exact keys. For add, plain name works.\n      action (add | edit | delete | rename_variant, optional) \u2014 "add" (default): requires type + defaultValue. "edit": pass defaultValue to change default, name to rename property. "delete": just propertyName. "rename_variant": pass defaultValue=current option name, name=new option name.\n      type (BOOLEAN | TEXT | INSTANCE_SWAP | VARIANT, optional) \u2014 Property type (required for add)\n      defaultValue (string_or_boolean, optional) \u2014 Default value (add/edit). For rename_variant: the CURRENT option name to rename\n      name (string, optional) \u2014 New name \u2014 for edit: renames the property itself, for rename_variant: the new option value name\n      preferredValues (array, optional) \u2014 Preferred values for INSTANCE_SWAP\n    depth (number, optional) \u2014 Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.',
-      "delete": "# components.delete\nDelete components or component sets\n\nParams:\n    id (string, required) \u2014 Component or component set ID"
+    Example: components(method:"create", type:"variant_set", items:[{name:"Button", layoutMode:"HORIZONTAL", layoutSizingHorizontal:"HUG", layoutSizingVertical:"HUG", padding:"space/8", itemSpacing:"space/8", children:[{type:"component", name:"Style=Primary", minWidth:120, height:48, layoutMode:"HORIZONTAL", layoutSizingHorizontal:"HUG", layoutSizingVertical:"FIXED", padding:"space/12", cornerRadius:"radius/8", fillVariableName:"bg/accent", primaryAxisAlignItems:"CENTER", counterAxisAlignItems:"MIN", children:[{type:"text", name:"Button", text:"Button", width:72, componentPropertyName:"Button", textStyleName:"Body/Medium", fontColorVariableName:"text/inverse", textAlignHorizontal:"CENTER", textAlignVertical:"CENTER", layoutSizingHorizontal:"FIXED", layoutSizingVertical:"FILL"}]}, {type:"component", name:"Style=Secondary", minWidth:120, height:48, layoutMode:"HORIZONTAL", layoutSizingHorizontal:"HUG", layoutSizingVertical:"FIXED", padding:"space/12", cornerRadius:"radius/8", fillVariableName:"bg/surface", strokeVariableName:"border/subtle", strokeWeight:"stroke/1", primaryAxisAlignItems:"CENTER", counterAxisAlignItems:"MIN", children:[{type:"text", name:"Button", text:"Button", width:72, componentPropertyName:"Button", textStyleName:"Body/Medium", fontColorVariableName:"text/primary", textAlignHorizontal:"CENTER", textAlignVertical:"CENTER", layoutSizingHorizontal:"FIXED", layoutSizingVertical:"FILL"}]}]}])
+    Item fields for items[] when type:"variant_set":
+      name (string, optional) \u2014 Node name
+      parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.
+      x (number, optional) \u2014 X position (default: 0)
+      y (number, optional) \u2014 Y position (default: 0)
+      width (number, optional) \u2014 Width in px (omit to shrink-to-content via HUG)
+      height (number, optional) \u2014 Height in px (omit to shrink-to-content via HUG)
+      rotation (number, optional) \u2014 Rotation in degrees (0-360)
+      visible (boolean, optional) \u2014 Show/hide (default true)
+      locked (boolean, optional) \u2014 Lock/unlock (default false)
+      opacity (string, optional) \u2014 Opacity (0-1) or variable name
+      blendMode (PASS_THROUGH | NORMAL | DARKEN | MULTIPLY | LINEAR_BURN | COLOR_BURN | LIGHTEN | SCREEN | LINEAR_DODGE | COLOR_DODGE | OVERLAY | SOFT_LIGHT | HARD_LIGHT | DIFFERENCE | EXCLUSION | HUE | SATURATION | COLOR | LUMINOSITY, optional)
+      effectStyleName (string, optional) \u2014 Effect style name (e.g. 'Shadow/Card') for shadows, blurs
+      fills (Paint[], optional) \u2014 Fill Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] for transparent. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables; use imageUrl/images for image authoring. IMAGE/VIDEO/PATTERN may appear in readback metadata only. Primary way to set non-image fills.
+      fillColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid fill (auto-binds to matching variable/style)
+      fillStyleName (string, optional) \u2014 Paint style name for fill
+      fillVariableName (string, optional) \u2014 Color variable by name e.g. 'bg/surface'
+      imageUrl (string, optional) \u2014 Image source \u2014 'pexel:<id>' for Pexels photos, a public URL, or a local file path. SVGs are inserted as vectors; raster images become IMAGE fills.
+      imageScaleMode (FILL | FIT | CROP | TILE, optional) \u2014 How the image is scaled within the frame (default: FILL)
+      strokes (Paint[], optional) \u2014 Stroke Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] to clear. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables. IMAGE/VIDEO/PATTERN may appear in readback metadata only. Primary way to set strokes.
+      strokeColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid stroke (auto-binds to matching variable/style)
+      strokeStyleName (string, optional) \u2014 Paint style name for stroke
+      strokeVariableName (string, optional) \u2014 Color variable by name for stroke
+      strokeWeight (string, optional) \u2014 All sides (number) or variable name (string). Per-side: strokeTopWeight, strokeBottomWeight, strokeLeftWeight, strokeRightWeight.
+      strokeTopWeight (string, optional)
+      strokeBottomWeight (string, optional)
+      strokeLeftWeight (string, optional)
+      strokeRightWeight (string, optional)
+      strokeAlign (INSIDE | OUTSIDE | CENTER, optional) \u2014 Stroke position (default: INSIDE)
+      cornerRadius (string, optional) \u2014 All corners (number) or variable name (string). Per-corner: topLeftRadius, topRightRadius, bottomRightRadius, bottomLeftRadius.
+      topLeftRadius (string, optional)
+      topRightRadius (string, optional)
+      bottomRightRadius (string, optional)
+      bottomLeftRadius (string, optional)
+      layoutMode (NONE | HORIZONTAL | VERTICAL, optional) \u2014 Layout direction (default: auto \u2014 NONE when width+height set, otherwise inferred from layout props)
+      layoutWrap (NO_WRAP | WRAP, optional) \u2014 Wrap children to new rows (HORIZONTAL layout only \u2014 Figma does not support WRAP on VERTICAL layouts). Use column frames inside a HORIZONTAL parent for vertical grid patterns.
+      padding (string, optional) \u2014 All edges (number) or variable name (string). Per-edge: paddingTop, paddingRight, paddingBottom, paddingLeft.
+      paddingTop (string, optional)
+      paddingRight (string, optional)
+      paddingBottom (string, optional)
+      paddingLeft (string, optional)
+      primaryAxisAlignItems (MIN | MAX | CENTER | SPACE_BETWEEN, optional)
+      counterAxisAlignItems (MIN | MAX | CENTER | BASELINE, optional)
+      itemSpacing (string, optional) \u2014 Spacing between children (number or variable name string, default: 0)
+      counterAxisSpacing (string, optional) \u2014 Gap between wrapped rows (requires layoutWrap: WRAP)
+      strokesIncludedInLayout (boolean, optional) \u2014 Include stroke width in layout measurements (default: false)
+      overflowDirection (NONE | HORIZONTAL | VERTICAL | BOTH, optional) \u2014 Scroll overflow in prototype (default: NONE)
+      layoutPositioning (AUTO | ABSOLUTE, optional) \u2014 ABSOLUTE = floating inside auto-layout parent
+      layoutSizingHorizontal (FIXED | HUG | FILL, optional)
+      layoutSizingVertical (FIXED | HUG | FILL, optional)
+      minWidth (number, optional) \u2014 Min width for responsive auto-layout
+      maxWidth (number, optional) \u2014 Max width for responsive auto-layout
+      minHeight (number, optional) \u2014 Min height for responsive auto-layout
+      maxHeight (number, optional) \u2014 Max height for responsive auto-layout
+      annotations (array, optional) \u2014 Set annotations \u2014 [{label?, labelMarkdown?, properties?, categoryId?}]. Properties validated per node type.
+      componentIds (string[], optional) \u2014 Existing component IDs to combine (min 2). Alternative to children.
+      variantPropertyName (string, optional) \u2014 Rename the auto-generated variant property (default: 'Property 1')
+      children (array, optional) \u2014 Inline variant components. Each must be {type:"component", name, children?, ...frame_params}. Variant children use the same inline child types as components.create, including rectangle / ellipse / line. All variants must share the same child structure. Alternative to componentIds \u2014 do not combine both.
+
+Response:
+    { results: ({id} | {error})[] }
+// Shared types:
+// Color: hex "#RGB"|"#RGBA"|"#RRGGBB"|"#RRGGBBAA" or {r: 0-1, g: 0-1, b: 0-1, a?: 0-1}
+// VariableAlias: {type: "VARIABLE_ALIAS", id: string}. The id must be a Figma VariableID; discover it via variables.get/list or variable_collections.get. Prefer colorVariableName/fillVariableName/strokeVariableName when available; Paint[] VariableAlias is mainly for precise Paint[] round-trips and gradient stop bindings.
+// Transform: [[number, number, number], [number, number, number]] (Figma Plugin API 2\xD73 matrix)
+// BlendMode: "PASS_THROUGH"|"NORMAL"|"DARKEN"|"MULTIPLY"|"LINEAR_BURN"|"COLOR_BURN"|"LIGHTEN"|"SCREEN"|"LINEAR_DODGE"|"COLOR_DODGE"|"OVERLAY"|"SOFT_LIGHT"|"HARD_LIGHT"|"DIFFERENCE"|"EXCLUSION"|"HUE"|"SATURATION"|"COLOR"|"LUMINOSITY"
+// ColorStop: {position: 0-1, color: Color, boundVariables?: {color?: VariableAlias}}
+// GradientPaint: {type: "GRADIENT_LINEAR"|"GRADIENT_RADIAL"|"GRADIENT_ANGULAR"|"GRADIENT_DIAMOND", gradientTransform: Transform, gradientStops: ColorStop[], visible?: boolean, opacity?: number, blendMode?: BlendMode}. Use gradientTransform + gradientStops (basic left-to-right: [[1,0,0],[0,1,0]]); do not use CSS gradients or REST gradientHandlePositions.
+// Effect: {type: "DROP_SHADOW"|"INNER_SHADOW"|"LAYER_BLUR"|"BACKGROUND_BLUR", radius: number, color?: {r,g,b,a} (0-1), offset?: {x, y}, spread?: number, visible?: boolean}
+// Paint: Paint[] authoring accepts only SOLID and GRADIENT_LINEAR/GRADIENT_RADIAL/GRADIENT_ANGULAR/GRADIENT_DIAMOND. SolidPaint: {type: "SOLID", color: Color, visible?: boolean, opacity?: number, blendMode?: BlendMode, boundVariables?: {color?: VariableAlias}}. GradientPaint authoring: {type: GRADIENT_*, gradientTransform: Transform, gradientStops: ColorStop[], visible?, opacity?, blendMode?}; bind variables on gradientStops[].boundVariables.color, not top-level gradient boundVariables. Do not pass IMAGE/VIDEO/PATTERN to create/update Paint[]; those may appear only in readback metadata from existing Figma content. Use imageUrl/images for image authoring. VIDEO/PATTERN authoring is not supported here. Do not use CSS gradients or REST gradientHandlePositions.`,
+      "commit": '# components.commit\nCommit a staged component \u2014 unwraps from [STAGED] container into the original target location.\n\nExample: components(method:"commit", id:"1:234")\n\nParams:\n    id (string, required) \u2014 Staged node ID to commit\n\nResponse:\n    { results: ({id} | {error})[] }',
+      "update": '# components.update\nAdd, edit, or delete component properties\n\nExample: components(method:"update", items:[{id:"1:23", propertyName:"Show Icon", action:"add", type:"BOOLEAN", defaultValue:true}])\n\nParams:\n    items (UpdatePropertyItem[], required) \u2014 Array of {id, propertyName, action?, type?, defaultValue?, name?, preferredValues?}\n      id (string, required) \u2014 Component or component set ID\n      propertyName (string, required) \u2014 Property name with #suffix for edit/delete (e.g. "Label#1:0"). Call components.get to find exact keys. For add, plain name works.\n      action (add | edit | delete | rename_variant, optional) \u2014 "add" (default): requires type + defaultValue. "edit": pass defaultValue to change default, name to rename property. "delete": just propertyName. "rename_variant": pass defaultValue=current option name, name=new option name.\n      type (BOOLEAN | TEXT | INSTANCE_SWAP | VARIANT, optional) \u2014 Property type (required for add)\n      defaultValue (string_or_boolean, optional) \u2014 Default value (add/edit). For rename_variant: the CURRENT option name to rename\n      name (string, optional) \u2014 New name \u2014 for edit: renames the property itself, for rename_variant: the new option value name\n      preferredValues (array, optional) \u2014 Preferred values for INSTANCE_SWAP\n    depth (number, optional) \u2014 Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.\n\nResponse:\n    { results: ("ok" | {error} | object)[] }',
+      "delete": '# components.delete\nDelete components or component sets\n\nParams:\n    id (string, required) \u2014 Component or component set ID\n\nResponse:\n    { results: ("ok" | {error})[] }'
     }
   },
   "connection": {
     "summary": '# connection\nManage the Figma plugin connection.\n\nMethods:\n  create               Join a relay channel (required first step before any other tool) [read]\n  get                  Verify end-to-end connection to Figma [read]\n  list                 Inspect which clients (MCP, plugin) are connected to each channel [read]\n  delete               Disconnect all clients (MCP server and Figma plugin) from a channel and reset its state [edit]\n\n// Connection manages the WebSocket link between the MCP server and the Figma plugin.\n// Channels are named rooms \u2014 both the MCP server and Figma plugin must join the same channel to communicate.\n// Workflow: connection(method:"create") to join a channel \u2192 connection(method:"get") to verify Figma plugin is connected.\n// If get times out (5s), the Figma plugin is not running or not on the same channel.\n// list shows all active channels and their connected clients. delete factory-resets a channel.\n\nUse connection(method: "help", topic: "<method>") for method details.',
     "methods": {
-      "create": "# connection.create\nJoin a relay channel (required first step before any other tool)\n\nParams:\n    channel (string, optional) \u2014 The channel name displayed in the Figma plugin panel. Defaults to 'vibma' if omitted.",
-      "get": "# connection.get\nVerify end-to-end connection to Figma\n\nNo params.",
-      "list": "# connection.list\nInspect which clients (MCP, plugin) are connected to each channel\n\nNo params.",
-      "delete": "# connection.delete\nDisconnect all clients (MCP server and Figma plugin) from a channel and reset its state\n\nParams:\n    channel (string, optional) \u2014 Channel to reset. Defaults to 'vibma'."
+      "create": "# connection.create\nJoin a relay channel (required first step before any other tool)\n\nParams:\n    channel (string, optional) \u2014 The channel name displayed in the Figma plugin panel. Defaults to 'vibma' if omitted.\n\nResponse:\n    Confirmation message with channel and port\n    string",
+      "get": "# connection.get\nVerify end-to-end connection to Figma\n\nNo params.\n\nResponse:\n    status (string, required)\n    documentName (string, required) \u2014 Active Figma document name\n    currentPage (string, required) \u2014 Current page name\n    timestamp (number, required) \u2014 Unix timestamp",
+      "list": "# connection.list\nInspect which clients (MCP, plugin) are connected to each channel\n\nNo params.\n\nResponse:\n    Map of channel names to their connected clients\n    object",
+      "delete": "# connection.delete\nDisconnect all clients (MCP server and Figma plugin) from a channel and reset its state\n\nParams:\n    channel (string, optional) \u2014 Channel to reset. Defaults to 'vibma'.\n\nResponse:\n    Confirmation of tunnel reset\n    string"
     }
   },
   "document": {
     "summary": '# document\nNavigate and manage Figma pages (canvases) in the document.\n\nMethods:\n  get                  Get current page with top-level children [read]\n  list                 Get document name and list all pages [read]\n  set                  Switch to a page by ID or name. At least one of pageId or pageName must be provided. [read]\n  create               Create a new page [create]\n  update               Rename a page [edit]\n\n// A Figma document contains pages \u2014 each page is an independent canvas with its own node tree.\n// The "current page" is where all node operations happen. Use document.set to switch pages before working with nodes.\n// Page IDs look like "0:1", "1:1", etc. The first page is always "0:1".\n// get returns the current page with its top-level children as stubs. list returns all pages in the document.\n\nUse document(method: "help", topic: "<method>") for method details.',
     "methods": {
-      "get": "# document.get\nGet current page with top-level children\n\nNo params.",
-      "list": "# document.list\nGet document name and list all pages\n\nNo params.",
-      "set": "# document.set\nSwitch to a page by ID or name. At least one of pageId or pageName must be provided.\n\nParams:\n    pageId (string, optional) \u2014 Page ID\n    pageName (string, optional) \u2014 Page name (case-insensitive, substring match)",
-      "create": "# document.create\nCreate a new page\n\nParams:\n    name (string, optional) \u2014 Page name (default: 'New Page')",
-      "update": "# document.update\nRename a page\n\nParams:\n    newName (string, required) \u2014 New page name\n    pageId (string, optional) \u2014 Page ID (default: current page)"
+      "get": '# document.get\nGet current page with top-level children\n\nNo params.\n\nResponse:\n    id (string, required)\n    name (string, required)\n    backgroundColor (string, optional) \u2014 Canvas background hex color (e.g. "#F5F5F5")\n    children (NodeStub[], required)\n// Shared types:\n// NodeStub: {id: string, name: string, type: string}',
+      "list": "# document.list\nGet document name and list all pages\n\nNo params.\n\nResponse:\n    name (string, required) \u2014 Document name\n    currentPageId (string, required)\n    pages (array, required)\n      id (string, required)\n      name (string, required)",
+      "set": "# document.set\nSwitch to a page by ID or name. At least one of pageId or pageName must be provided.\n\nParams:\n    pageId (string, optional) \u2014 Page ID\n    pageName (string, optional) \u2014 Page name (case-insensitive, substring match)\n\nResponse:\n    id (string, required)\n    name (string, required)",
+      "create": "# document.create\nCreate a new page\n\nParams:\n    name (string, optional) \u2014 Page name (default: 'New Page')\n\nResponse:\n    id (string, required) \u2014 New page ID",
+      "update": "# document.update\nRename a page\n\nParams:\n    newName (string, required) \u2014 New page name\n    pageId (string, optional) \u2014 Page ID (default: current page)\n\nResponse:\n    string"
     }
   },
   "fonts": {
     "summary": '# fonts\nSearch available fonts in Figma.\n\nMethods:\n  list                 List available font families, optionally filtered by name [read]\n\n// Returns font family names installed in the Figma environment. Use to verify a fontFamily before text.create or styles.create.\n// query filters by family name substring (case-insensitive), e.g. query:"inter" matches "Inter", "Inter Tight".\n// ---\n// Default response: just family names. Set includeStyles:true to also get available styles per family (e.g. "Regular", "Bold", "Italic").\n// Use fonts.list with query to narrow results before creating text with specific fontFamily + fontStyle.\n\nUse fonts(method: "help", topic: "<method>") for method details.',
     "methods": {
-      "list": '# fonts.list\nList available font families, optionally filtered by name\n\nExample: fonts(method:"list", query:"inter")\n\nParams:\n    query (string, optional) \u2014 Filter by family name (case-insensitive substring)\n    includeStyles (boolean, optional) \u2014 Include available styles per family (default: false)\n    offset (number, optional) \u2014 Skip N items for pagination (default 0)\n    limit (number, optional) \u2014 Max items per page (default 100)'
+      "list": '# fonts.list\nList available font families, optionally filtered by name\n\nExample: fonts(method:"list", query:"inter")\n\nParams:\n    query (string, optional) \u2014 Filter by family name (case-insensitive substring)\n    includeStyles (boolean, optional) \u2014 Include available styles per family (default: false)\n    offset (number, optional) \u2014 Skip N items for pagination (default 0)\n    limit (number, optional) \u2014 Max items per page (default 100)\n\nResponse:\n    count (number, required) \u2014 Number of matching families\n    fonts (array, required) \u2014 Array of {family} stubs, or {family, styles[]} when includeStyles:true\n      family (string, required)\n      styles (array, optional)'
     }
   },
   "frames": {
-    "summary": '# frames\nCreate and manage frames, shapes, auto-layout containers, sections, and SVG nodes.\n\nMethods:\n  get                  Get serialized node data [read]\n  list                 Search for nodes (returns stubs only \u2014 use get with depth for full properties) [read]\n  update               Patch node properties [edit]\n  delete               Delete nodes [edit]\n  clone                Duplicate nodes \u2014 produces a same-type copy (frame\u2192frame, instance\u2192instance, component\u2192component). Instance clones reference the same source component; they do not duplicate the component definition. [create]\n  audit                Run lint on a node \u2014 returns severity-ranked findings [read]\n  reparent             Move nodes into a new parent [edit]\n  create               Create frame-like containers [create]\n  commit               Commit a staged node \u2014 unwraps from [STAGED] container into the original target location. [edit]\n  export               Export a node as PNG, JPG, SVG, SVG_STRING, or PDF [read]\n\n// depth: omit \u2192 id+name stubs | 0 \u2192 props + child stubs | N \u2192 recurse N | -1 \u2192 full tree\n// fields: whitelist e.g. ["fills","opacity"] \u2014 id, name, type always included. Pass ["*"] for all.\n// layoutSizingHorizontal/Vertical: FIXED | HUG | FILL \u2014 how the node sizes within auto-layout.\n// Colors: fillVariableName/strokeVariableName bind by name \u2014 preferred over raw color values.\n// Note: node-based endpoints (frames, text, instances, components) use `results` as the list key.\n//   Standalone endpoints (styles, variables, variable_collections) use `items`. Components.list uses `items` (catalog view).\n// ---\n// visible: false hides the node. Omitted from response when true (the default).\n// locked: true prevents editing in Figma UI. Omitted when false (the default).\n// rotation: degrees (0-360). Omitted when 0.\n// blendMode: layer blend mode. Omitted when PASS_THROUGH (the default).\n// layoutPositioning: ABSOLUTE = floating inside auto-layout parent. Omitted when AUTO (the default).\n// minWidth/maxWidth/minHeight/maxHeight: responsive constraints for auto-layout children.\n// constraints: position behavior in non-auto-layout parents. Ignored inside auto-layout frames.\n// bindings: bind design variables to node properties. field uses slash path: "fills/0/color" (first fill), "strokes/0/color", "opacity", "width", "height", "cornerRadius", "paddingLeft", "itemSpacing".\n// explicitMode: pin a variable mode on this node. Use { collectionName, modeName } (preferred) or { collectionId, modeId }.\n// properties: escape hatch \u2014 set any Figma node property directly. Use only when no dedicated field exists.\ninterface Node {\n  id: string; name: string; type: string;\n  visible?: boolean;       // omitted when true\n  locked?: boolean;        // omitted when false\n  opacity?: number;        // omitted when 1\n  rotation?: number;       // omitted when 0\n  blendMode?: string;      // omitted when PASS_THROUGH\n  layoutPositioning?: "AUTO" | "ABSOLUTE";\n  layoutSizingHorizontal?: "FIXED" | "HUG" | "FILL";\n  layoutSizingVertical?: "FIXED" | "HUG" | "FILL";\n  minWidth?: number; maxWidth?: number; minHeight?: number; maxHeight?: number;\n  absoluteBoundingBox: { x: number; y: number; width: number; height: number };\n  fills?: Paint[];         // solid: {type: "SOLID", color: {r, g, b, a}}\n  strokes?: Paint[];\n  effects?: Effect[];      // DROP_SHADOW | INNER_SHADOW | LAYER_BLUR | BACKGROUND_BLUR\n  children?: NodeStub[];   // stubs: {id, name, type} \u2014 use depth to expand\n}\n// PatchItem uses flat params matching create shape \u2014 no nested sub-objects.\n// Fill/stroke/corner/layout/text params are identical to frames.create and text.create.\n// Unknown keys produce a warning, preventing silent failures.\n// Frames are the primary container in Figma. Use auto_layout for responsive containers.\n// Sizing: FIXED = explicit size, HUG = shrink to children, FILL = expand to fill parent.\n// Fill: pass fills:[{type:"SOLID", color:"#hex"}] or [] for transparent. Shorthand: fillColor:"#3B82F6" (auto-binds to matching variable/style).\n// Also: fillVariableName:"bg/primary", fillStyleName:"Surface/Primary".\n// Image fill: imageUrl accepts "pexel:<id>", a public URL, or a local file path. SVGs become vector nodes; raster images become IMAGE fills. imageScaleMode: FILL (default), FIT, CROP, TILE.\n// Stroke: pass strokes:[{type:"SOLID", color:"#hex"}] or [] to clear. Shorthand: strokeColor:"#000", strokeVariableName:"border/default".\n// Token fields (cornerRadius, opacity, itemSpacing, padding, strokeWeight): pass number for value, string for variable name/ID.\n// ---\n// SIZING: Always think about both axes. Containers with text need a width constraint \u2014 set width + layoutSizingHorizontal:"FIXED".\n//   HUG/HUG is only correct for intrinsically-sized elements (buttons, badges, icons).\n//   Smart defaults inside auto-layout parent: cross-axis defaults to FILL, primary axis stays HUG.\n//   FILL only works inside an auto-layout parent. Use FIXED for top-level frames.\n// minWidth/maxWidth/minHeight/maxHeight: responsive constraints for auto-layout children.\n// clipsContent: true (default) clips children to the frame bounds. Set false for overflow-visible.\n// Sections are top-level organizers (like artboards) \u2014 they cannot be nested inside frames.\n// Shape primitives: rectangle, ellipse, line \u2014 for decorative/visual elements (not containers).\n// group: wraps existing nodes into a Group. boolean_operation: UNION/SUBTRACT/INTERSECT/EXCLUDE combines shapes.\n// SVG create: pass raw SVG markup string (e.g. "<svg>...</svg>") \u2014 Figma converts it to vector nodes.\n\nUse frames(method: "help", topic: "<method>") for method details.',
+    "summary": '# frames\nCreate and manage frames, shapes, auto-layout containers, sections, and SVG nodes.\n\nMethods:\n  get                  Get serialized node data [read]\n  list                 Search for nodes (returns stubs only \u2014 use get with depth for full properties) [read]\n  update               Patch node properties [edit]\n  delete               Delete nodes [edit]\n  clone                Duplicate nodes \u2014 produces a same-type copy (frame\u2192frame, instance\u2192instance, component\u2192component). Instance clones reference the same source component; they do not duplicate the component definition. [create]\n  scale                Proportionally rescale a node subtree using Figma\'s visual Scale tool behavior. This is for visual/artifact scaling, not responsive layout resizing. [edit]\n  audit                Run lint on a node \u2014 returns severity-ranked findings [read]\n  reparent             Move nodes into a new parent [edit]\n  create               Create frame-like containers [create]\n  commit               Commit a staged node \u2014 unwraps from [STAGED] container into the original target location. [edit]\n  export               Export a node as PNG, JPG, SVG, SVG_STRING, or PDF [read]\n\n// depth: omit \u2192 id+name stubs | 0 \u2192 props + child stubs | N \u2192 recurse N | -1 \u2192 full tree\n// fields: whitelist e.g. ["fills","opacity"] \u2014 id, name, type always included. Pass ["*"] for all.\n// layoutSizingHorizontal/Vertical: FIXED | HUG | FILL \u2014 how the node sizes within auto-layout.\n// Colors: fillVariableName/strokeVariableName bind by name \u2014 preferred over raw color values.\n// Note: node-based endpoints (frames, text, instances, components) use `results` as the list key.\n//   Standalone endpoints (styles, variables, variable_collections) use `items`. Components.list uses `items` (catalog view).\n// ---\n// visible: false hides the node. Omitted from response when true (the default).\n// locked: true prevents editing in Figma UI. Omitted when false (the default).\n// rotation: degrees (0-360). Omitted when 0.\n// blendMode: layer blend mode. Omitted when PASS_THROUGH (the default).\n// layoutPositioning: ABSOLUTE = floating inside auto-layout parent. Omitted when AUTO (the default).\n// minWidth/maxWidth/minHeight/maxHeight: responsive constraints for auto-layout children.\n// constraints: position behavior in non-auto-layout parents. Ignored inside auto-layout frames.\n// bindings: bind design variables to node properties. field uses slash path: "fills/0/color" (first fill), "strokes/0/color", "opacity", "width", "height", "cornerRadius", "paddingLeft", "itemSpacing".\n// explicitMode: pin a variable mode on this node. Use { collectionName, modeName } (preferred) or { collectionId, modeId }.\n// clipsContent: clip children to the node bounds where supported (frames/components/instances). Set false for overflow-visible layouts.\ninterface Node {\n  id: string; name: string; type: string;\n  visible?: boolean;       // omitted when true\n  locked?: boolean;        // omitted when false\n  opacity?: number;        // omitted when 1\n  rotation?: number;       // omitted when 0\n  blendMode?: string;      // omitted when PASS_THROUGH\n  layoutPositioning?: "AUTO" | "ABSOLUTE";\n  layoutSizingHorizontal?: "FIXED" | "HUG" | "FILL";\n  layoutSizingVertical?: "FIXED" | "HUG" | "FILL";\n  minWidth?: number; maxWidth?: number; minHeight?: number; maxHeight?: number;\n  absoluteBoundingBox: { x: number; y: number; width: number; height: number };\n  fills?: Paint[];         // readback Paint[]; authoring supports SOLID + gradients via gradientTransform + gradientStops\n  strokes?: Paint[];\n  effects?: Effect[];      // DROP_SHADOW | INNER_SHADOW | LAYER_BLUR | BACKGROUND_BLUR\n  children?: NodeStub[];   // stubs: {id, name, type} \u2014 use depth to expand\n}\n// PatchItem uses flat params matching create shape \u2014 no nested sub-objects.\n// Fill/stroke/corner/layout/text params are identical to frames.create and text.create. Paint[] authoring supports SOLID + gradients only; IMAGE/VIDEO/PATTERN are readback-only metadata.\n// Unknown keys produce a warning, preventing silent failures.\n// Frames are the primary container in Figma. Use auto_layout for responsive containers.\n// Sizing: FIXED = explicit size, HUG = shrink to children, FILL = expand to fill parent.\n// Fill: prefer fillVariableName/fillStyleName. Use fills:[{type:"SOLID", color:"#hex"}] or gradient Paint[] (GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND) with gradientTransform + gradientStops only for one-off values; [] for transparent. Shorthand: fillColor:"#3B82F6" (auto-binds single solids).\n// Also: fillVariableName:"bg/surface", fillStyleName:"Surface/Primary". Do not use CSS gradients, REST gradientHandlePositions, or top-level gradient boundVariables.\n// Image fill: use imageUrl/images for image authoring. imageUrl accepts "pexel:<id>", a public URL, or a local file path. SVGs become vector nodes; raster images become IMAGE fills. IMAGE/VIDEO/PATTERN may appear in readback metadata only; do not pass those objects in Paint[]. imageScaleMode: FILL (default), FIT, CROP, TILE.\n// Stroke: prefer strokeVariableName/strokeStyleName. Use strokes:[{type:"SOLID", color:"#hex"}] or gradient Paint[] (GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND) with gradientTransform + gradientStops only for one-off values; [] to clear. Shorthand: strokeColor:"#000", strokeVariableName:"border/default".\n// Token fields (cornerRadius, opacity, itemSpacing, padding, strokeWeight): pass number for value, string for variable name/ID.\n// Examples assume design tokens/styles already exist. Prefer token names (fillVariableName, strokeVariableName, padding:"space/16", cornerRadius:"radius/8") over raw values in production designs.\n// ---\n// SIZING: Always think about both axes. Containers with text need a width constraint \u2014 set width + layoutSizingHorizontal:"FIXED".\n//   HUG/HUG is only correct for intrinsically-sized elements (buttons, badges, icons).\n//   Smart defaults inside auto-layout parent: cross-axis defaults to FILL, primary axis stays HUG.\n//   FILL only works inside an auto-layout parent. Use FIXED for top-level frames.\n// minWidth/maxWidth/minHeight/maxHeight: responsive constraints for auto-layout children.\n// clipsContent: true (default) clips children to the frame bounds. Set false for overflow-visible.\n// Sections are top-level organizers (like artboards) \u2014 they cannot be nested inside frames.\n// Shape primitives: rectangle, ellipse, line \u2014 for decorative/visual elements (not containers).\n// group: wraps existing nodes into a Group. boolean_operation: UNION/SUBTRACT/INTERSECT/EXCLUDE combines shapes.\n// SVG create: pass raw SVG markup string (e.g. "<svg>...</svg>") \u2014 Figma converts it to vector nodes.\n\nUse frames(method: "help", topic: "<method>") for method details.\n// Shared types:\n// Color: hex "#RGB"|"#RGBA"|"#RRGGBB"|"#RRGGBBAA" or {r: 0-1, g: 0-1, b: 0-1, a?: 0-1}\n// VariableAlias: {type: "VARIABLE_ALIAS", id: string}. The id must be a Figma VariableID; discover it via variables.get/list or variable_collections.get. Prefer colorVariableName/fillVariableName/strokeVariableName when available; Paint[] VariableAlias is mainly for precise Paint[] round-trips and gradient stop bindings.\n// Transform: [[number, number, number], [number, number, number]] (Figma Plugin API 2\xD73 matrix)\n// BlendMode: "PASS_THROUGH"|"NORMAL"|"DARKEN"|"MULTIPLY"|"LINEAR_BURN"|"COLOR_BURN"|"LIGHTEN"|"SCREEN"|"LINEAR_DODGE"|"COLOR_DODGE"|"OVERLAY"|"SOFT_LIGHT"|"HARD_LIGHT"|"DIFFERENCE"|"EXCLUSION"|"HUE"|"SATURATION"|"COLOR"|"LUMINOSITY"\n// ColorStop: {position: 0-1, color: Color, boundVariables?: {color?: VariableAlias}}\n// GradientPaint: {type: "GRADIENT_LINEAR"|"GRADIENT_RADIAL"|"GRADIENT_ANGULAR"|"GRADIENT_DIAMOND", gradientTransform: Transform, gradientStops: ColorStop[], visible?: boolean, opacity?: number, blendMode?: BlendMode}. Use gradientTransform + gradientStops (basic left-to-right: [[1,0,0],[0,1,0]]); do not use CSS gradients or REST gradientHandlePositions.\n// Effect: {type: "DROP_SHADOW"|"INNER_SHADOW"|"LAYER_BLUR"|"BACKGROUND_BLUR", radius: number, color?: {r,g,b,a} (0-1), offset?: {x, y}, spread?: number, visible?: boolean}\n// Paint: Paint[] authoring accepts only SOLID and GRADIENT_LINEAR/GRADIENT_RADIAL/GRADIENT_ANGULAR/GRADIENT_DIAMOND. SolidPaint: {type: "SOLID", color: Color, visible?: boolean, opacity?: number, blendMode?: BlendMode, boundVariables?: {color?: VariableAlias}}. GradientPaint authoring: {type: GRADIENT_*, gradientTransform: Transform, gradientStops: ColorStop[], visible?, opacity?, blendMode?}; bind variables on gradientStops[].boundVariables.color, not top-level gradient boundVariables. Do not pass IMAGE/VIDEO/PATTERN to create/update Paint[]; those may appear only in readback metadata from existing Figma content. Use imageUrl/images for image authoring. VIDEO/PATTERN authoring is not supported here. Do not use CSS gradients or REST gradientHandlePositions.\n// NodeStub: {id: string, name: string, type: string}',
     "methods": {
-      "get": '# frames.get\nGet serialized node data\n\nParams:\n    id (string, required) \u2014 Node ID\n    fields (string[], optional) \u2014 Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.\n    depth (number, optional) \u2014 Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.\n    verbose (boolean, optional) \u2014 Include all properties (bounding box, constraints, text style details). Default false \u2014 returns slim, actionable output.',
-      "list": '# frames.list\nSearch for nodes (returns stubs only \u2014 use get with depth for full properties)\n\nParams:\n    query (string, optional) \u2014 Name search query (case-insensitive substring match)\n    types (string[], optional) \u2014 Filter by node types (e.g. ["FRAME", "TEXT"])\n    parentId (string, optional) \u2014 Search only within this subtree\n    fields (string[], optional) \u2014 Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.\n    offset (number, optional) \u2014 Skip N items for pagination (default 0)\n    limit (number, optional) \u2014 Max items per page (default 100)',
+      "get": '# frames.get\nGet serialized node data\n\nParams:\n    id (string, required) \u2014 Node ID\n    fields (string[], optional) \u2014 Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.\n    depth (number, optional) \u2014 Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.\n    verbose (boolean, optional) \u2014 Include all properties (bounding box, constraints, text style details). Default false \u2014 returns slim, actionable output.\n\nResponse:\n    Serialized node tree. Shape depends on depth parameter.\n    results (Node[], required) \u2014 Serialized node trees\n    _truncated (boolean, optional) \u2014 True when node budget exceeded\n    _notice (string, optional) \u2014 Human-readable truncation notice',
+      "list": '# frames.list\nSearch for nodes (returns stubs only \u2014 use get with depth for full properties)\n\nParams:\n    query (string, optional) \u2014 Name search query (case-insensitive substring match)\n    types (string[], optional) \u2014 Filter by node types (e.g. ["FRAME", "TEXT"])\n    parentId (string, optional) \u2014 Search only within this subtree\n    fields (string[], optional) \u2014 Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.\n    offset (number, optional) \u2014 Skip N items for pagination (default 0)\n    limit (number, optional) \u2014 Max items per page (default 100)\n\nResponse:\n    Paginated node search results (uses `results` not `items`)\n    totalCount (number, required) \u2014 Total matching nodes\n    returned (number, required) \u2014 Nodes in this page\n    offset (number, optional)\n    limit (number, optional)\n    results (array, required) \u2014 Matching node stubs\n      id (string, required)\n      name (string, required)\n      type (string, required)\n      parentId (string, required)\n      parentName (string, optional)\n      bounds (object, optional)',
       "update": `# frames.update
 Patch node properties
 
 Params:
-    items (PatchItem[], required) \u2014 Array of {id, ...properties} to patch
-      fills (array, optional) \u2014 Fill paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] for transparent. Primary way to set fills.
+    items (PatchItem[], required) \u2014 Array of {id, ...fields} to patch
+      fills (Paint[], optional) \u2014 Fill Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] for transparent. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables; use imageUrl/images for image authoring. IMAGE/VIDEO/PATTERN may appear in readback metadata only. Primary way to set non-image fills.
       fillColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid fill (auto-binds to matching variable/style)
       fillStyleName (string, optional) \u2014 Paint style name for fill
-      fillVariableName (string, optional) \u2014 Color variable by name e.g. 'bg/primary'
-      strokes (array, optional) \u2014 Stroke paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] to clear. Primary way to set strokes.
+      fillVariableName (string, optional) \u2014 Color variable by name e.g. 'bg/surface'
+      strokes (Paint[], optional) \u2014 Stroke Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] to clear. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables. IMAGE/VIDEO/PATTERN may appear in readback metadata only. Primary way to set strokes.
       strokeColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid stroke (auto-binds to matching variable/style)
       strokeStyleName (string, optional) \u2014 Paint style name for stroke
       strokeVariableName (string, optional) \u2014 Color variable by name for stroke
@@ -371,9 +417,35 @@ Params:
       explicitMode (object, optional) \u2014 Pin variable mode \u2014 use { collectionName, modeName } (preferred) or { collectionId, modeId }
       exportSettings (array, optional) \u2014 Export settings
       annotations (array, optional) \u2014 Set annotations \u2014 [{label?, labelMarkdown?, properties?, categoryId?}]. Properties are validated per node type.
-      properties (object, optional) \u2014 Direct Figma API props (escape hatch)`,
-      "delete": "# frames.delete\nDelete nodes\n\nParams:\n    id (string, optional) \u2014 Single node ID\n    items (array, optional) \u2014 Batch: [{id}, ...]\n      id (string, optional)",
-      "clone": "# frames.clone\nDuplicate nodes \u2014 produces a same-type copy (frame\u2192frame, instance\u2192instance, component\u2192component). Instance clones reference the same source component; they do not duplicate the component definition.\n\nParams:\n    id (string, optional) \u2014 Node ID\n    name (string, optional) \u2014 Rename the clone (set before appending to parent \u2014 required when cloning a variant into its component set to avoid duplicate names)\n    parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.\n    x (number, optional) \u2014 X position (default: 0)\n    y (number, optional) \u2014 Y position (default: 0)\n    items (array, optional) \u2014 Batch: [{id, name?, parentId?, x?, y?}, ...]. Alternative to single-item params.\n      id (string, required) \u2014 Node ID to clone\n      name (string, optional) \u2014 Rename the clone\n      parentId (string, optional) \u2014 Target parent\n      x (number, optional)\n      y (number, optional)\n    depth (number, optional) \u2014 Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.",
+      clipsContent (boolean, optional) \u2014 Clip children to bounds where supported (frames/components/instances).
+
+Response:
+    { results: ("ok" | {error} | object)[] }
+// Shared types:
+// Color: hex "#RGB"|"#RGBA"|"#RRGGBB"|"#RRGGBBAA" or {r: 0-1, g: 0-1, b: 0-1, a?: 0-1}
+// VariableAlias: {type: "VARIABLE_ALIAS", id: string}. The id must be a Figma VariableID; discover it via variables.get/list or variable_collections.get. Prefer colorVariableName/fillVariableName/strokeVariableName when available; Paint[] VariableAlias is mainly for precise Paint[] round-trips and gradient stop bindings.
+// Transform: [[number, number, number], [number, number, number]] (Figma Plugin API 2\xD73 matrix)
+// BlendMode: "PASS_THROUGH"|"NORMAL"|"DARKEN"|"MULTIPLY"|"LINEAR_BURN"|"COLOR_BURN"|"LIGHTEN"|"SCREEN"|"LINEAR_DODGE"|"COLOR_DODGE"|"OVERLAY"|"SOFT_LIGHT"|"HARD_LIGHT"|"DIFFERENCE"|"EXCLUSION"|"HUE"|"SATURATION"|"COLOR"|"LUMINOSITY"
+// ColorStop: {position: 0-1, color: Color, boundVariables?: {color?: VariableAlias}}
+// GradientPaint: {type: "GRADIENT_LINEAR"|"GRADIENT_RADIAL"|"GRADIENT_ANGULAR"|"GRADIENT_DIAMOND", gradientTransform: Transform, gradientStops: ColorStop[], visible?: boolean, opacity?: number, blendMode?: BlendMode}. Use gradientTransform + gradientStops (basic left-to-right: [[1,0,0],[0,1,0]]); do not use CSS gradients or REST gradientHandlePositions.
+// Effect: {type: "DROP_SHADOW"|"INNER_SHADOW"|"LAYER_BLUR"|"BACKGROUND_BLUR", radius: number, color?: {r,g,b,a} (0-1), offset?: {x, y}, spread?: number, visible?: boolean}
+// Paint: Paint[] authoring accepts only SOLID and GRADIENT_LINEAR/GRADIENT_RADIAL/GRADIENT_ANGULAR/GRADIENT_DIAMOND. SolidPaint: {type: "SOLID", color: Color, visible?: boolean, opacity?: number, blendMode?: BlendMode, boundVariables?: {color?: VariableAlias}}. GradientPaint authoring: {type: GRADIENT_*, gradientTransform: Transform, gradientStops: ColorStop[], visible?, opacity?, blendMode?}; bind variables on gradientStops[].boundVariables.color, not top-level gradient boundVariables. Do not pass IMAGE/VIDEO/PATTERN to create/update Paint[]; those may appear only in readback metadata from existing Figma content. Use imageUrl/images for image authoring. VIDEO/PATTERN authoring is not supported here. Do not use CSS gradients or REST gradientHandlePositions.`,
+      "delete": '# frames.delete\nDelete nodes\n\nParams:\n    id (string, optional) \u2014 Single node ID\n    items (array, optional) \u2014 Batch: [{id}, ...]\n      id (string, optional)\n\nResponse:\n    { results: ("ok" | {error})[] }',
+      "clone": "# frames.clone\nDuplicate nodes \u2014 produces a same-type copy (frame\u2192frame, instance\u2192instance, component\u2192component). Instance clones reference the same source component; they do not duplicate the component definition.\n\nParams:\n    id (string, optional) \u2014 Node ID\n    name (string, optional) \u2014 Rename the clone (set before appending to parent \u2014 required when cloning a variant into its component set to avoid duplicate names)\n    parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.\n    x (number, optional) \u2014 X position (default: 0)\n    y (number, optional) \u2014 Y position (default: 0)\n    items (array, optional) \u2014 Batch: [{id, name?, parentId?, x?, y?}, ...]. Alternative to single-item params.\n      id (string, required) \u2014 Node ID to clone\n      name (string, optional) \u2014 Rename the clone\n      parentId (string, optional) \u2014 Target parent\n      x (number, optional)\n      y (number, optional)\n    depth (number, optional) \u2014 Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.\n\nResponse:\n    { results: ({id} | {error})[] }",
+      "scale": `# frames.scale
+Proportionally rescale a node subtree using Figma's visual Scale tool behavior. This is for visual/artifact scaling, not responsive layout resizing.
+
+Example: frames(method:"scale", id:"1:23", factor:0.5)
+
+Params:
+    id (string, optional) \u2014 Node ID to scale
+    factor (number, optional) \u2014 Scale factor, >= 0.01. 0.5 = 50%, 2 = 200%. Scales children, text, strokes, effects, and layout geometry from the node's top-left. On auto-layout or HUG/FILL nodes, Figma may resolve responsive sizing to fixed width/height.
+    items (array, optional) \u2014 Batch: [{id, factor}, ...]. Alternative to single-item params.
+      id (string, required) \u2014 Node ID to scale
+      factor (number, required) \u2014 Scale factor, >= 0.01. 0.5 = 50%, 2 = 200%.
+
+Response:
+    { results: ("ok" | {error})[] }`,
       "audit": `# frames.audit
 Run lint on a node \u2014 returns severity-ranked findings
 
@@ -383,299 +455,346 @@ Params:
     maxDepth (number, optional) \u2014 Max tree depth (default: 10)
     maxFindings (number, optional) \u2014 Max findings (default: 50)
     minSeverity (error | unsafe | heuristic | style | verbose, optional) \u2014 Minimum severity to report (default: style). Set to 'verbose' to include AAA contrast and line-height checks.
-    skipInstances (boolean, optional) \u2014 Skip instance internals \u2014 findings inside instances are owned by the component (default: true)`,
-      "reparent": "# frames.reparent\nMove nodes into a new parent\n\nParams:\n    items (array, required) \u2014 Array of {id, parentId, index?}\n      id (string, required)\n      parentId (string, required)\n      index (number, optional)",
+    skipInstances (boolean, optional) \u2014 Skip instance internals \u2014 findings inside instances are owned by the component (default: true)
+
+Response:
+    nodeId (string, optional)
+    nodeName (string, optional)
+    categories (array, optional) \u2014 Sorted by severity (error > unsafe > heuristic > style)`,
+      "reparent": '# frames.reparent\nMove nodes into a new parent\n\nParams:\n    items (array, required) \u2014 Array of {id, parentId, index?}\n      id (string, required)\n      parentId (string, required)\n      index (number, optional)\n\nResponse:\n    { results: ("ok" | {error})[] }',
       "create": `# frames.create
 Create frame-like containers
 
-Example: frames(method:"create", type:"auto_layout", layoutMode:"VERTICAL", itemSpacing:16, padding:24)
+Example: frames(method:"create", type:"rectangle", items:[{name:"Gradient Box", fills:[{type:"GRADIENT_LINEAR", gradientTransform:[[1,0,0],[0,1,0]], gradientStops:[{position:0,color:"#FF6B6B"},{position:1,color:"#FFD93D"}]}]}])
+
+Call shape: frames(method:"create", type:"<type>", items:[{...type-specific fields...}])
+Do not pass type-specific item fields at the top level; put them inside items[].
 
 Discriminant: type (frame | auto_layout | section | rectangle | ellipse | line | group | boolean_operation | svg | slot)
+Top-level params:
+    type (frame | auto_layout | section | rectangle | ellipse | line | group | boolean_operation | svg | slot, required) \u2014 Selects which item shape to use
+    items (array, required) \u2014 One or more type-specific item objects
 
   ## frame \u2014 General-purpose frame \u2014 shrinks to content by default, static when width+height given
-    name (string, optional) \u2014 Node name
-    parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.
-    x (number, optional) \u2014 X position (default: 0)
-    y (number, optional) \u2014 Y position (default: 0)
-    width (number, optional) \u2014 Width in px (omit to shrink-to-content via HUG)
-    height (number, optional) \u2014 Height in px (omit to shrink-to-content via HUG)
-    rotation (number, optional) \u2014 Rotation in degrees (0-360)
-    visible (boolean, optional) \u2014 Show/hide (default true)
-    locked (boolean, optional) \u2014 Lock/unlock (default false)
-    opacity (string, optional) \u2014 Opacity (0-1) or variable name
-    blendMode (PASS_THROUGH | NORMAL | DARKEN | MULTIPLY | LINEAR_BURN | COLOR_BURN | LIGHTEN | SCREEN | LINEAR_DODGE | COLOR_DODGE | OVERLAY | SOFT_LIGHT | HARD_LIGHT | DIFFERENCE | EXCLUSION | HUE | SATURATION | COLOR | LUMINOSITY, optional)
-    effectStyleName (string, optional) \u2014 Effect style name (e.g. 'Shadow/Card') for shadows, blurs
-    fills (array, optional) \u2014 Fill paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] for transparent. Primary way to set fills.
-    fillColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid fill (auto-binds to matching variable/style)
-    fillStyleName (string, optional) \u2014 Paint style name for fill
-    fillVariableName (string, optional) \u2014 Color variable by name e.g. 'bg/primary'
-    imageUrl (string, optional) \u2014 Image source \u2014 'pexel:<id>' for Pexels photos, a public URL, or a local file path. SVGs are inserted as vectors; raster images become IMAGE fills.
-    imageScaleMode (FILL | FIT | CROP | TILE, optional) \u2014 How the image is scaled within the frame (default: FILL)
-    strokes (array, optional) \u2014 Stroke paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] to clear. Primary way to set strokes.
-    strokeColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid stroke (auto-binds to matching variable/style)
-    strokeStyleName (string, optional) \u2014 Paint style name for stroke
-    strokeVariableName (string, optional) \u2014 Color variable by name for stroke
-    strokeWeight (string, optional) \u2014 All sides (number) or variable name (string). Per-side: strokeTopWeight, strokeBottomWeight, strokeLeftWeight, strokeRightWeight.
-    strokeTopWeight (string, optional)
-    strokeBottomWeight (string, optional)
-    strokeLeftWeight (string, optional)
-    strokeRightWeight (string, optional)
-    strokeAlign (INSIDE | OUTSIDE | CENTER, optional) \u2014 Stroke position (default: INSIDE)
-    cornerRadius (string, optional) \u2014 All corners (number) or variable name (string). Per-corner: topLeftRadius, topRightRadius, bottomRightRadius, bottomLeftRadius.
-    topLeftRadius (string, optional)
-    topRightRadius (string, optional)
-    bottomRightRadius (string, optional)
-    bottomLeftRadius (string, optional)
-    layoutMode (NONE | HORIZONTAL | VERTICAL, optional) \u2014 Layout direction (default: auto \u2014 NONE when width+height set, otherwise inferred from layout props)
-    layoutWrap (NO_WRAP | WRAP, optional) \u2014 Wrap children to new rows (HORIZONTAL layout only \u2014 Figma does not support WRAP on VERTICAL layouts). Use column frames inside a HORIZONTAL parent for vertical grid patterns.
-    padding (string, optional) \u2014 All edges (number) or variable name (string). Per-edge: paddingTop, paddingRight, paddingBottom, paddingLeft.
-    paddingTop (string, optional)
-    paddingRight (string, optional)
-    paddingBottom (string, optional)
-    paddingLeft (string, optional)
-    primaryAxisAlignItems (MIN | MAX | CENTER | SPACE_BETWEEN, optional)
-    counterAxisAlignItems (MIN | MAX | CENTER | BASELINE, optional)
-    itemSpacing (string, optional) \u2014 Spacing between children (number or variable name string, default: 0)
-    counterAxisSpacing (string, optional) \u2014 Gap between wrapped rows (requires layoutWrap: WRAP)
-    strokesIncludedInLayout (boolean, optional) \u2014 Include stroke width in layout measurements (default: false)
-    overflowDirection (NONE | HORIZONTAL | VERTICAL | BOTH, optional) \u2014 Scroll overflow in prototype (default: NONE)
-    layoutPositioning (AUTO | ABSOLUTE, optional) \u2014 ABSOLUTE = floating inside auto-layout parent
-    layoutSizingHorizontal (FIXED | HUG | FILL, optional)
-    layoutSizingVertical (FIXED | HUG | FILL, optional)
-    minWidth (number, optional) \u2014 Min width for responsive auto-layout
-    maxWidth (number, optional) \u2014 Max width for responsive auto-layout
-    minHeight (number, optional) \u2014 Min height for responsive auto-layout
-    maxHeight (number, optional) \u2014 Max height for responsive auto-layout
-    annotations (array, optional) \u2014 Set annotations \u2014 [{label?, labelMarkdown?, properties?, categoryId?}]. Properties validated per node type.
-    clipsContent (boolean, optional)
-    children (array, optional) \u2014 Inline child nodes \u2014 build nested trees in one call. Types: text: {type:"text", text, fontFamily?, fontSize?, fontWeight?, fontStyle?, fontColor?, layoutSizingHorizontal?}. frame: {type:"frame", name?, layoutMode?, fillColor?, width?, layoutSizingHorizontal?, children?}. instance: {type:"instance", componentId, variantProperties?, properties?}. component: {type:"component", name, children?}. All params from text/frame endpoints are supported on their respective types. Always set layoutSizingHorizontal + layoutSizingVertical on children inside auto-layout parents (FILL, HUG, or FIXED). Example: children:[{type:"text", text:"Title", fontSize:20, layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}, {type:"frame", name:"Row", layoutMode:"HORIZONTAL", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG", itemSpacing:8, children:[{type:"instance", componentId:"1:2", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}]}] Inside components: add componentPropertyName to auto-bind TEXT or INSTANCE_SWAP properties.
+    Example: frames(method:"create", type:"frame", items:[{name:"Dashboard Shell", x:0, y:0, width:1440, height:900, fillVariableName:"bg/canvas", children:[{type:"frame", name:"Content Area", x:80, y:80, width:640, height:360, layoutMode:"VERTICAL", padding:"space/24", itemSpacing:"space/12", fillVariableName:"bg/surface", cornerRadius:"radius/12", children:[{type:"text", name:"Dashboard overview", text:"Dashboard overview", textStyleName:"Heading/Medium", fontColorVariableName:"text/primary", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}]}]}])
+    Item fields for items[] when type:"frame":
+      name (string, optional) \u2014 Node name
+      parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.
+      x (number, optional) \u2014 X position (default: 0)
+      y (number, optional) \u2014 Y position (default: 0)
+      width (number, optional) \u2014 Width in px (omit to shrink-to-content via HUG)
+      height (number, optional) \u2014 Height in px (omit to shrink-to-content via HUG)
+      rotation (number, optional) \u2014 Rotation in degrees (0-360)
+      visible (boolean, optional) \u2014 Show/hide (default true)
+      locked (boolean, optional) \u2014 Lock/unlock (default false)
+      opacity (string, optional) \u2014 Opacity (0-1) or variable name
+      blendMode (PASS_THROUGH | NORMAL | DARKEN | MULTIPLY | LINEAR_BURN | COLOR_BURN | LIGHTEN | SCREEN | LINEAR_DODGE | COLOR_DODGE | OVERLAY | SOFT_LIGHT | HARD_LIGHT | DIFFERENCE | EXCLUSION | HUE | SATURATION | COLOR | LUMINOSITY, optional)
+      effectStyleName (string, optional) \u2014 Effect style name (e.g. 'Shadow/Card') for shadows, blurs
+      fills (Paint[], optional) \u2014 Fill Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] for transparent. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables; use imageUrl/images for image authoring. IMAGE/VIDEO/PATTERN may appear in readback metadata only. Primary way to set non-image fills.
+      fillColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid fill (auto-binds to matching variable/style)
+      fillStyleName (string, optional) \u2014 Paint style name for fill
+      fillVariableName (string, optional) \u2014 Color variable by name e.g. 'bg/surface'
+      imageUrl (string, optional) \u2014 Image source \u2014 'pexel:<id>' for Pexels photos, a public URL, or a local file path. SVGs are inserted as vectors; raster images become IMAGE fills.
+      imageScaleMode (FILL | FIT | CROP | TILE, optional) \u2014 How the image is scaled within the frame (default: FILL)
+      strokes (Paint[], optional) \u2014 Stroke Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] to clear. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables. IMAGE/VIDEO/PATTERN may appear in readback metadata only. Primary way to set strokes.
+      strokeColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid stroke (auto-binds to matching variable/style)
+      strokeStyleName (string, optional) \u2014 Paint style name for stroke
+      strokeVariableName (string, optional) \u2014 Color variable by name for stroke
+      strokeWeight (string, optional) \u2014 All sides (number) or variable name (string). Per-side: strokeTopWeight, strokeBottomWeight, strokeLeftWeight, strokeRightWeight.
+      strokeTopWeight (string, optional)
+      strokeBottomWeight (string, optional)
+      strokeLeftWeight (string, optional)
+      strokeRightWeight (string, optional)
+      strokeAlign (INSIDE | OUTSIDE | CENTER, optional) \u2014 Stroke position (default: INSIDE)
+      cornerRadius (string, optional) \u2014 All corners (number) or variable name (string). Per-corner: topLeftRadius, topRightRadius, bottomRightRadius, bottomLeftRadius.
+      topLeftRadius (string, optional)
+      topRightRadius (string, optional)
+      bottomRightRadius (string, optional)
+      bottomLeftRadius (string, optional)
+      layoutMode (NONE | HORIZONTAL | VERTICAL, optional) \u2014 Layout direction (default: auto \u2014 NONE when width+height set, otherwise inferred from layout props)
+      layoutWrap (NO_WRAP | WRAP, optional) \u2014 Wrap children to new rows (HORIZONTAL layout only \u2014 Figma does not support WRAP on VERTICAL layouts). Use column frames inside a HORIZONTAL parent for vertical grid patterns.
+      padding (string, optional) \u2014 All edges (number) or variable name (string). Per-edge: paddingTop, paddingRight, paddingBottom, paddingLeft.
+      paddingTop (string, optional)
+      paddingRight (string, optional)
+      paddingBottom (string, optional)
+      paddingLeft (string, optional)
+      primaryAxisAlignItems (MIN | MAX | CENTER | SPACE_BETWEEN, optional)
+      counterAxisAlignItems (MIN | MAX | CENTER | BASELINE, optional)
+      itemSpacing (string, optional) \u2014 Spacing between children (number or variable name string, default: 0)
+      counterAxisSpacing (string, optional) \u2014 Gap between wrapped rows (requires layoutWrap: WRAP)
+      strokesIncludedInLayout (boolean, optional) \u2014 Include stroke width in layout measurements (default: false)
+      overflowDirection (NONE | HORIZONTAL | VERTICAL | BOTH, optional) \u2014 Scroll overflow in prototype (default: NONE)
+      layoutPositioning (AUTO | ABSOLUTE, optional) \u2014 ABSOLUTE = floating inside auto-layout parent
+      layoutSizingHorizontal (FIXED | HUG | FILL, optional)
+      layoutSizingVertical (FIXED | HUG | FILL, optional)
+      minWidth (number, optional) \u2014 Min width for responsive auto-layout
+      maxWidth (number, optional) \u2014 Max width for responsive auto-layout
+      minHeight (number, optional) \u2014 Min height for responsive auto-layout
+      maxHeight (number, optional) \u2014 Max height for responsive auto-layout
+      annotations (array, optional) \u2014 Set annotations \u2014 [{label?, labelMarkdown?, properties?, categoryId?}]. Properties validated per node type.
+      clipsContent (boolean, optional)
+      children (array, optional) \u2014 Inline child nodes \u2014 build nested trees in one call. Types: text: {type:"text", text, textStyleName?, fontColorVariableName?, layoutSizingHorizontal?}. frame: {type:"frame", name?, layoutMode?, fillVariableName?, itemSpacing?, layoutSizingHorizontal?, children?}. instance: {type:"instance", componentId, variantProperties?, properties?}. component: {type:"component", name, children?}. rectangle / ellipse / line: same params as the corresponding frames(method:"create", type:"rectangle"|"ellipse"|"line") branch. All params from text/frame endpoints are supported on their respective types. Inline fills/strokes accept Paint[] authoring input: SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. Do not use CSS gradients, REST gradientHandlePositions, or IMAGE/VIDEO/PATTERN in Paint[] authoring. Always set layoutSizingHorizontal + layoutSizingVertical on children inside auto-layout parents (FILL, HUG, or FIXED). Example: children:[{type:"ellipse", name:"Dot", width:6, height:6, fillVariableName:"status/active"}, {type:"text", name:"Title", text:"Title", textStyleName:"Heading/Medium", fontColorVariableName:"text/primary", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}, {type:"frame", name:"Row", layoutMode:"HORIZONTAL", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG", itemSpacing:"space/8", children:[{type:"instance", componentId:"1:2", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}]}] Inside components: add componentPropertyName to auto-bind TEXT or INSTANCE_SWAP properties.
 
 
   ## auto_layout \u2014 Auto-layout frame that arranges children automatically
-    name (string, optional) \u2014 Node name
-    parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.
-    x (number, optional) \u2014 X position (default: 0)
-    y (number, optional) \u2014 Y position (default: 0)
-    width (number, optional) \u2014 Width in px (omit to shrink-to-content via HUG)
-    height (number, optional) \u2014 Height in px (omit to shrink-to-content via HUG)
-    rotation (number, optional) \u2014 Rotation in degrees (0-360)
-    visible (boolean, optional) \u2014 Show/hide (default true)
-    locked (boolean, optional) \u2014 Lock/unlock (default false)
-    opacity (string, optional) \u2014 Opacity (0-1) or variable name
-    blendMode (PASS_THROUGH | NORMAL | DARKEN | MULTIPLY | LINEAR_BURN | COLOR_BURN | LIGHTEN | SCREEN | LINEAR_DODGE | COLOR_DODGE | OVERLAY | SOFT_LIGHT | HARD_LIGHT | DIFFERENCE | EXCLUSION | HUE | SATURATION | COLOR | LUMINOSITY, optional)
-    effectStyleName (string, optional) \u2014 Effect style name (e.g. 'Shadow/Card') for shadows, blurs
-    fills (array, optional) \u2014 Fill paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] for transparent. Primary way to set fills.
-    fillColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid fill (auto-binds to matching variable/style)
-    fillStyleName (string, optional) \u2014 Paint style name for fill
-    fillVariableName (string, optional) \u2014 Color variable by name e.g. 'bg/primary'
-    imageUrl (string, optional) \u2014 Image source \u2014 'pexel:<id>' for Pexels photos, a public URL, or a local file path. SVGs are inserted as vectors; raster images become IMAGE fills.
-    imageScaleMode (FILL | FIT | CROP | TILE, optional) \u2014 How the image is scaled within the frame (default: FILL)
-    strokes (array, optional) \u2014 Stroke paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] to clear. Primary way to set strokes.
-    strokeColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid stroke (auto-binds to matching variable/style)
-    strokeStyleName (string, optional) \u2014 Paint style name for stroke
-    strokeVariableName (string, optional) \u2014 Color variable by name for stroke
-    strokeWeight (string, optional) \u2014 All sides (number) or variable name (string). Per-side: strokeTopWeight, strokeBottomWeight, strokeLeftWeight, strokeRightWeight.
-    strokeTopWeight (string, optional)
-    strokeBottomWeight (string, optional)
-    strokeLeftWeight (string, optional)
-    strokeRightWeight (string, optional)
-    strokeAlign (INSIDE | OUTSIDE | CENTER, optional) \u2014 Stroke position (default: INSIDE)
-    cornerRadius (string, optional) \u2014 All corners (number) or variable name (string). Per-corner: topLeftRadius, topRightRadius, bottomRightRadius, bottomLeftRadius.
-    topLeftRadius (string, optional)
-    topRightRadius (string, optional)
-    bottomRightRadius (string, optional)
-    bottomLeftRadius (string, optional)
-    layoutMode (HORIZONTAL | VERTICAL, required) \u2014 Primary axis direction
-    layoutWrap (NO_WRAP | WRAP, optional) \u2014 Wrap children to new rows (HORIZONTAL layout only \u2014 Figma does not support WRAP on VERTICAL layouts). Use column frames inside a HORIZONTAL parent for vertical grid patterns.
-    padding (string, optional) \u2014 All edges (number) or variable name (string). Per-edge: paddingTop, paddingRight, paddingBottom, paddingLeft.
-    paddingTop (string, optional)
-    paddingRight (string, optional)
-    paddingBottom (string, optional)
-    paddingLeft (string, optional)
-    primaryAxisAlignItems (MIN | MAX | CENTER | SPACE_BETWEEN, optional)
-    counterAxisAlignItems (MIN | MAX | CENTER | BASELINE, optional)
-    itemSpacing (string, optional) \u2014 Spacing between children (number or variable name string, default: 0)
-    counterAxisSpacing (string, optional) \u2014 Gap between wrapped rows (requires layoutWrap: WRAP)
-    strokesIncludedInLayout (boolean, optional) \u2014 Include stroke width in layout measurements (default: false)
-    overflowDirection (NONE | HORIZONTAL | VERTICAL | BOTH, optional) \u2014 Scroll overflow in prototype (default: NONE)
-    layoutPositioning (AUTO | ABSOLUTE, optional) \u2014 ABSOLUTE = floating inside auto-layout parent
-    layoutSizingHorizontal (FIXED | HUG | FILL, optional)
-    layoutSizingVertical (FIXED | HUG | FILL, optional)
-    minWidth (number, optional) \u2014 Min width for responsive auto-layout
-    maxWidth (number, optional) \u2014 Max width for responsive auto-layout
-    minHeight (number, optional) \u2014 Min height for responsive auto-layout
-    maxHeight (number, optional) \u2014 Max height for responsive auto-layout
-    annotations (array, optional) \u2014 Set annotations \u2014 [{label?, labelMarkdown?, properties?, categoryId?}]. Properties validated per node type.
-    clipsContent (boolean, optional)
-    nodeIds (string[], optional) \u2014 Existing node IDs to wrap into auto-layout
-    children (array, optional) \u2014 Inline child nodes \u2014 build nested trees in one call. Types: text: {type:"text", text, fontFamily?, fontSize?, fontWeight?, fontStyle?, fontColor?, layoutSizingHorizontal?}. frame: {type:"frame", name?, layoutMode?, fillColor?, width?, layoutSizingHorizontal?, children?}. instance: {type:"instance", componentId, variantProperties?, properties?}. component: {type:"component", name, children?}. All params from text/frame endpoints are supported on their respective types. Always set layoutSizingHorizontal + layoutSizingVertical on children inside auto-layout parents (FILL, HUG, or FIXED). Example: children:[{type:"text", text:"Title", fontSize:20, layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}, {type:"frame", name:"Row", layoutMode:"HORIZONTAL", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG", itemSpacing:8, children:[{type:"instance", componentId:"1:2", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}]}] Inside components: add componentPropertyName to auto-bind TEXT or INSTANCE_SWAP properties.
+    Example: frames(method:"create", type:"auto_layout", items:[{name:"Settings Card", width:360, height:180, layoutMode:"VERTICAL", padding:"space/24", itemSpacing:"space/12", fillVariableName:"bg/surface", strokeVariableName:"border/subtle", strokeWeight:"stroke/1", cornerRadius:"radius/12", children:[{type:"text", name:"Team settings", text:"Team settings", textStyleName:"Heading/Medium", fontColorVariableName:"text/primary", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}, {type:"text", name:"Manage workspace preferences.", text:"Manage workspace preferences.", textStyleName:"Body/Regular", fontColorVariableName:"text/secondary", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}]}])
+    Item fields for items[] when type:"auto_layout":
+      name (string, optional) \u2014 Node name
+      parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.
+      x (number, optional) \u2014 X position (default: 0)
+      y (number, optional) \u2014 Y position (default: 0)
+      width (number, optional) \u2014 Width in px (omit to shrink-to-content via HUG)
+      height (number, optional) \u2014 Height in px (omit to shrink-to-content via HUG)
+      rotation (number, optional) \u2014 Rotation in degrees (0-360)
+      visible (boolean, optional) \u2014 Show/hide (default true)
+      locked (boolean, optional) \u2014 Lock/unlock (default false)
+      opacity (string, optional) \u2014 Opacity (0-1) or variable name
+      blendMode (PASS_THROUGH | NORMAL | DARKEN | MULTIPLY | LINEAR_BURN | COLOR_BURN | LIGHTEN | SCREEN | LINEAR_DODGE | COLOR_DODGE | OVERLAY | SOFT_LIGHT | HARD_LIGHT | DIFFERENCE | EXCLUSION | HUE | SATURATION | COLOR | LUMINOSITY, optional)
+      effectStyleName (string, optional) \u2014 Effect style name (e.g. 'Shadow/Card') for shadows, blurs
+      fills (Paint[], optional) \u2014 Fill Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] for transparent. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables; use imageUrl/images for image authoring. IMAGE/VIDEO/PATTERN may appear in readback metadata only. Primary way to set non-image fills.
+      fillColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid fill (auto-binds to matching variable/style)
+      fillStyleName (string, optional) \u2014 Paint style name for fill
+      fillVariableName (string, optional) \u2014 Color variable by name e.g. 'bg/surface'
+      imageUrl (string, optional) \u2014 Image source \u2014 'pexel:<id>' for Pexels photos, a public URL, or a local file path. SVGs are inserted as vectors; raster images become IMAGE fills.
+      imageScaleMode (FILL | FIT | CROP | TILE, optional) \u2014 How the image is scaled within the frame (default: FILL)
+      strokes (Paint[], optional) \u2014 Stroke Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] to clear. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables. IMAGE/VIDEO/PATTERN may appear in readback metadata only. Primary way to set strokes.
+      strokeColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid stroke (auto-binds to matching variable/style)
+      strokeStyleName (string, optional) \u2014 Paint style name for stroke
+      strokeVariableName (string, optional) \u2014 Color variable by name for stroke
+      strokeWeight (string, optional) \u2014 All sides (number) or variable name (string). Per-side: strokeTopWeight, strokeBottomWeight, strokeLeftWeight, strokeRightWeight.
+      strokeTopWeight (string, optional)
+      strokeBottomWeight (string, optional)
+      strokeLeftWeight (string, optional)
+      strokeRightWeight (string, optional)
+      strokeAlign (INSIDE | OUTSIDE | CENTER, optional) \u2014 Stroke position (default: INSIDE)
+      cornerRadius (string, optional) \u2014 All corners (number) or variable name (string). Per-corner: topLeftRadius, topRightRadius, bottomRightRadius, bottomLeftRadius.
+      topLeftRadius (string, optional)
+      topRightRadius (string, optional)
+      bottomRightRadius (string, optional)
+      bottomLeftRadius (string, optional)
+      layoutMode (HORIZONTAL | VERTICAL, required) \u2014 Primary axis direction
+      layoutWrap (NO_WRAP | WRAP, optional) \u2014 Wrap children to new rows (HORIZONTAL layout only \u2014 Figma does not support WRAP on VERTICAL layouts). Use column frames inside a HORIZONTAL parent for vertical grid patterns.
+      padding (string, optional) \u2014 All edges (number) or variable name (string). Per-edge: paddingTop, paddingRight, paddingBottom, paddingLeft.
+      paddingTop (string, optional)
+      paddingRight (string, optional)
+      paddingBottom (string, optional)
+      paddingLeft (string, optional)
+      primaryAxisAlignItems (MIN | MAX | CENTER | SPACE_BETWEEN, optional)
+      counterAxisAlignItems (MIN | MAX | CENTER | BASELINE, optional)
+      itemSpacing (string, optional) \u2014 Spacing between children (number or variable name string, default: 0)
+      counterAxisSpacing (string, optional) \u2014 Gap between wrapped rows (requires layoutWrap: WRAP)
+      strokesIncludedInLayout (boolean, optional) \u2014 Include stroke width in layout measurements (default: false)
+      overflowDirection (NONE | HORIZONTAL | VERTICAL | BOTH, optional) \u2014 Scroll overflow in prototype (default: NONE)
+      layoutPositioning (AUTO | ABSOLUTE, optional) \u2014 ABSOLUTE = floating inside auto-layout parent
+      layoutSizingHorizontal (FIXED | HUG | FILL, optional)
+      layoutSizingVertical (FIXED | HUG | FILL, optional)
+      minWidth (number, optional) \u2014 Min width for responsive auto-layout
+      maxWidth (number, optional) \u2014 Max width for responsive auto-layout
+      minHeight (number, optional) \u2014 Min height for responsive auto-layout
+      maxHeight (number, optional) \u2014 Max height for responsive auto-layout
+      annotations (array, optional) \u2014 Set annotations \u2014 [{label?, labelMarkdown?, properties?, categoryId?}]. Properties validated per node type.
+      clipsContent (boolean, optional)
+      nodeIds (string[], optional) \u2014 Existing node IDs to wrap into auto-layout
+      children (array, optional) \u2014 Inline child nodes \u2014 build nested trees in one call. Types: text: {type:"text", text, textStyleName?, fontColorVariableName?, layoutSizingHorizontal?}. frame: {type:"frame", name?, layoutMode?, fillVariableName?, itemSpacing?, layoutSizingHorizontal?, children?}. instance: {type:"instance", componentId, variantProperties?, properties?}. component: {type:"component", name, children?}. rectangle / ellipse / line: same params as the corresponding frames(method:"create", type:"rectangle"|"ellipse"|"line") branch. All params from text/frame endpoints are supported on their respective types. Inline fills/strokes accept Paint[] authoring input: SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. Do not use CSS gradients, REST gradientHandlePositions, or IMAGE/VIDEO/PATTERN in Paint[] authoring. Always set layoutSizingHorizontal + layoutSizingVertical on children inside auto-layout parents (FILL, HUG, or FIXED). Example: children:[{type:"ellipse", name:"Dot", width:6, height:6, fillVariableName:"status/active"}, {type:"text", name:"Title", text:"Title", textStyleName:"Heading/Medium", fontColorVariableName:"text/primary", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}, {type:"frame", name:"Row", layoutMode:"HORIZONTAL", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG", itemSpacing:"space/8", children:[{type:"instance", componentId:"1:2", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}]}] Inside components: add componentPropertyName to auto-bind TEXT or INSTANCE_SWAP properties.
 
 
   ## section \u2014 Figma section (top-level organizer)
-    name (string, required) \u2014 Section name
-    parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.
-    x (number, optional) \u2014 X position (default: 0)
-    y (number, optional) \u2014 Y position (default: 0)
-    width (number, optional) \u2014 Width (default: 500)
-    height (number, optional) \u2014 Height (default: 500)
-    fills (array, optional) \u2014 Fill paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] for transparent
-    fillColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid fill (auto-binds to matching variable/style)
-    fillStyleName (string, optional) \u2014 Paint style name for fill
-    fillVariableName (string, optional) \u2014 Color variable by name e.g. 'bg/primary'
-    imageUrl (string, optional) \u2014 Image source \u2014 'pexel:<id>', public URL, or local file path
-    imageScaleMode (FILL | FIT | CROP | TILE, optional) \u2014 How the image is scaled (default: FILL)
+    Example: frames(method:"create", type:"section", items:[{name:"Components", x:0, y:0, width:1200, height:800, fillVariableName:"bg/canvas"}])
+    Item fields for items[] when type:"section":
+      name (string, required) \u2014 Section name
+      parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.
+      x (number, optional) \u2014 X position (default: 0)
+      y (number, optional) \u2014 Y position (default: 0)
+      width (number, optional) \u2014 Width (default: 500)
+      height (number, optional) \u2014 Height (default: 500)
+      fills (Paint[], optional) \u2014 Fill Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] for transparent. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables; use imageUrl/images for image authoring. IMAGE/VIDEO/PATTERN may appear in readback metadata only
+      fillColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid fill (auto-binds to matching variable/style)
+      fillStyleName (string, optional) \u2014 Paint style name for fill
+      fillVariableName (string, optional) \u2014 Color variable by name e.g. 'bg/surface'
+      imageUrl (string, optional) \u2014 Image source \u2014 'pexel:<id>', public URL, or local file path
+      imageScaleMode (FILL | FIT | CROP | TILE, optional) \u2014 How the image is scaled (default: FILL)
 
   ## rectangle \u2014 Rectangle shape node
-    name (string, optional) \u2014 Layer name (default: 'Rectangle')
-    parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.
-    x (number, optional) \u2014 X position (default: 0)
-    y (number, optional) \u2014 Y position (default: 0)
-    width (number, optional) \u2014 Width in px (default: 100)
-    height (number, optional) \u2014 Height in px (default: 100)
-    fills (array, optional) \u2014 Fill paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] for transparent
-    fillColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid fill (auto-binds to matching variable/style)
-    fillStyleName (string, optional) \u2014 Paint style name for fill
-    fillVariableName (string, optional) \u2014 Color variable by name e.g. 'bg/primary'
-    imageUrl (string, optional) \u2014 Image source \u2014 'pexel:<id>', public URL, or local file path
-    imageScaleMode (FILL | FIT | CROP | TILE, optional) \u2014 How the image is scaled (default: FILL)
-    strokes (array, optional) \u2014 Stroke paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] to clear
-    strokeColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid stroke (auto-binds to matching variable/style)
-    strokeVariableName (string, optional) \u2014 Color variable by name for stroke
-    strokeWeight (string, optional)
-    cornerRadius (string, optional) \u2014 All corners (number) or variable name (string). Per-corner: topLeftRadius, topRightRadius, bottomRightRadius, bottomLeftRadius.
-    topLeftRadius (string, optional)
-    topRightRadius (string, optional)
-    bottomRightRadius (string, optional)
-    bottomLeftRadius (string, optional)
-    opacity (string, optional)
-    layoutSizingHorizontal (FIXED | FILL, optional) \u2014 Horizontal sizing in auto-layout parent
-    layoutSizingVertical (FIXED | FILL, optional) \u2014 Vertical sizing in auto-layout parent
-    annotations (array, optional) \u2014 Annotations \u2014 [{label?, labelMarkdown?, properties?, categoryId?}]
+    Example: frames(method:"create", type:"rectangle", items:[{name:"Avatar Placeholder", width:64, height:64, cornerRadius:"radius/16", fillVariableName:"bg/muted"}])
+    Item fields for items[] when type:"rectangle":
+      name (string, optional) \u2014 Layer name (default: 'Rectangle')
+      parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.
+      x (number, optional) \u2014 X position (default: 0)
+      y (number, optional) \u2014 Y position (default: 0)
+      width (number, optional) \u2014 Width in px (default: 100)
+      height (number, optional) \u2014 Height in px (default: 100)
+      fills (Paint[], optional) \u2014 Fill Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] for transparent. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables; use imageUrl/images for image authoring. IMAGE/VIDEO/PATTERN may appear in readback metadata only
+      fillColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid fill (auto-binds to matching variable/style)
+      fillStyleName (string, optional) \u2014 Paint style name for fill
+      fillVariableName (string, optional) \u2014 Color variable by name e.g. 'bg/surface'
+      imageUrl (string, optional) \u2014 Image source \u2014 'pexel:<id>', public URL, or local file path
+      imageScaleMode (FILL | FIT | CROP | TILE, optional) \u2014 How the image is scaled (default: FILL)
+      strokes (Paint[], optional) \u2014 Stroke Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] to clear. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables. IMAGE/VIDEO/PATTERN may appear in readback metadata only
+      strokeColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid stroke (auto-binds to matching variable/style)
+      strokeVariableName (string, optional) \u2014 Color variable by name for stroke
+      strokeWeight (string, optional)
+      cornerRadius (string, optional) \u2014 All corners (number) or variable name (string). Per-corner: topLeftRadius, topRightRadius, bottomRightRadius, bottomLeftRadius.
+      topLeftRadius (string, optional)
+      topRightRadius (string, optional)
+      bottomRightRadius (string, optional)
+      bottomLeftRadius (string, optional)
+      opacity (string, optional)
+      layoutSizingHorizontal (FIXED | FILL, optional) \u2014 Horizontal sizing in auto-layout parent
+      layoutSizingVertical (FIXED | FILL, optional) \u2014 Vertical sizing in auto-layout parent
+      annotations (array, optional) \u2014 Annotations \u2014 [{label?, labelMarkdown?, properties?, categoryId?}]
 
   ## ellipse \u2014 Ellipse/circle shape node
-    name (string, optional) \u2014 Layer name (default: 'Ellipse')
-    parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.
-    x (number, optional) \u2014 X position (default: 0)
-    y (number, optional) \u2014 Y position (default: 0)
-    width (number, optional) \u2014 Width in px (default: 100)
-    height (number, optional) \u2014 Height in px (default: 100, same as width for circle)
-    fills (array, optional) \u2014 Fill paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] for transparent
-    fillColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid fill (auto-binds to matching variable/style)
-    fillStyleName (string, optional) \u2014 Paint style name for fill
-    fillVariableName (string, optional) \u2014 Color variable by name e.g. 'bg/primary'
-    imageUrl (string, optional) \u2014 Image source \u2014 'pexel:<id>', public URL, or local file path
-    imageScaleMode (FILL | FIT | CROP | TILE, optional) \u2014 How the image is scaled (default: FILL)
-    strokes (array, optional) \u2014 Stroke paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] to clear
-    strokeColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid stroke (auto-binds to matching variable/style)
-    strokeVariableName (string, optional) \u2014 Color variable by name for stroke
-    strokeWeight (string, optional)
-    opacity (string, optional)
-    layoutSizingHorizontal (FIXED | FILL, optional) \u2014 Horizontal sizing in auto-layout parent
-    layoutSizingVertical (FIXED | FILL, optional) \u2014 Vertical sizing in auto-layout parent
-    annotations (array, optional) \u2014 Annotations \u2014 [{label?, labelMarkdown?, properties?, categoryId?}]
+    Example: frames(method:"create", type:"ellipse", items:[{name:"Status Dot", width:12, height:12, fillVariableName:"status/success"}])
+    Item fields for items[] when type:"ellipse":
+      name (string, optional) \u2014 Layer name (default: 'Ellipse')
+      parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.
+      x (number, optional) \u2014 X position (default: 0)
+      y (number, optional) \u2014 Y position (default: 0)
+      width (number, optional) \u2014 Width in px (default: 100)
+      height (number, optional) \u2014 Height in px (default: 100, same as width for circle)
+      fills (Paint[], optional) \u2014 Fill Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] for transparent. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables; use imageUrl/images for image authoring. IMAGE/VIDEO/PATTERN may appear in readback metadata only
+      fillColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid fill (auto-binds to matching variable/style)
+      fillStyleName (string, optional) \u2014 Paint style name for fill
+      fillVariableName (string, optional) \u2014 Color variable by name e.g. 'bg/surface'
+      imageUrl (string, optional) \u2014 Image source \u2014 'pexel:<id>', public URL, or local file path
+      imageScaleMode (FILL | FIT | CROP | TILE, optional) \u2014 How the image is scaled (default: FILL)
+      strokes (Paint[], optional) \u2014 Stroke Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] to clear. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables. IMAGE/VIDEO/PATTERN may appear in readback metadata only
+      strokeColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid stroke (auto-binds to matching variable/style)
+      strokeVariableName (string, optional) \u2014 Color variable by name for stroke
+      strokeWeight (string, optional)
+      opacity (string, optional)
+      layoutSizingHorizontal (FIXED | FILL, optional) \u2014 Horizontal sizing in auto-layout parent
+      layoutSizingVertical (FIXED | FILL, optional) \u2014 Vertical sizing in auto-layout parent
+      annotations (array, optional) \u2014 Annotations \u2014 [{label?, labelMarkdown?, properties?, categoryId?}]
 
   ## line \u2014 Line shape node
-    name (string, optional) \u2014 Layer name (default: 'Line')
-    parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.
-    x (number, optional) \u2014 X position (default: 0)
-    y (number, optional) \u2014 Y position (default: 0)
-    length (number, optional) \u2014 Line length in px (default: 100)
-    rotation (number, optional) \u2014 Rotation in degrees (default: 0 = horizontal)
-    strokes (array, optional) \u2014 Stroke paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] to clear
-    strokeColor (Color, optional) \u2014 Line color (default: black, auto-binds to matching variable/style)
-    strokeVariableName (string, optional) \u2014 Color variable by name for stroke
-    strokeWeight (string, optional) \u2014 Line thickness (default: 1)
-    opacity (string, optional)
-    layoutSizingHorizontal (FIXED | FILL, optional) \u2014 Horizontal sizing in auto-layout parent (defaults to FILL in vertical auto-layout)
-    annotations (array, optional) \u2014 Annotations \u2014 [{label?, labelMarkdown?, properties?, categoryId?}]
+    Example: frames(method:"create", type:"line", items:[{name:"Divider", length:320, strokeVariableName:"border/subtle", strokeWeight:"stroke/1"}])
+    Item fields for items[] when type:"line":
+      name (string, optional) \u2014 Layer name (default: 'Line')
+      parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.
+      x (number, optional) \u2014 X position (default: 0)
+      y (number, optional) \u2014 Y position (default: 0)
+      length (number, optional) \u2014 Line length in px (default: 100)
+      rotation (number, optional) \u2014 Rotation in degrees (default: 0 = horizontal)
+      strokes (Paint[], optional) \u2014 Stroke Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] to clear. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables. IMAGE/VIDEO/PATTERN may appear in readback metadata only
+      strokeColor (Color, optional) \u2014 Line color (default: black, auto-binds to matching variable/style)
+      strokeVariableName (string, optional) \u2014 Color variable by name for stroke
+      strokeWeight (string, optional) \u2014 Line thickness (default: 1)
+      opacity (string, optional)
+      layoutSizingHorizontal (FIXED | FILL, optional) \u2014 Horizontal sizing in auto-layout parent (defaults to FILL in vertical auto-layout)
+      annotations (array, optional) \u2014 Annotations \u2014 [{label?, labelMarkdown?, properties?, categoryId?}]
 
   ## group \u2014 Group existing nodes together
-    nodeIds (string[], required) \u2014 Node IDs to group (min 1)
-    name (string, optional) \u2014 Group name
-    parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.
+    Example: frames(method:"create", type:"group", items:[{nodeIds:["1:2","1:3"], name:"Icon Group"}])
+    Item fields for items[] when type:"group":
+      nodeIds (string[], required) \u2014 Node IDs to group (min 1)
+      name (string, optional) \u2014 Group name
+      parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.
 
   ## boolean_operation \u2014 Combine shapes with boolean operations (union, subtract, intersect, exclude)
-    operation (UNION | SUBTRACT | INTERSECT | EXCLUDE, required) \u2014 Boolean operation type
-    nodeIds (string[], required) \u2014 Node IDs to combine (min 2, first node is the base for SUBTRACT)
-    name (string, optional) \u2014 Result node name
-    parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.
+    Example: frames(method:"create", type:"boolean_operation", items:[{operation:"UNION", nodeIds:["1:2","1:3"], name:"Combined Shape", fillVariableName:"bg/accent"}])
+    Item fields for items[] when type:"boolean_operation":
+      fillStyleName (string, optional) \u2014 Paint style to apply to vector fills
+      fillVariableName (string, optional) \u2014 Color variable by name for vector fills
+      strokeStyleName (string, optional) \u2014 Paint style to apply to vector strokes
+      strokeVariableName (string, optional) \u2014 Color variable by name for vector strokes
+      operation (UNION | SUBTRACT | INTERSECT | EXCLUDE, required) \u2014 Boolean operation type
+      nodeIds (string[], required) \u2014 Node IDs to combine (min 2, first node is the base for SUBTRACT)
+      name (string, optional) \u2014 Result node name
+      parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.
 
   ## svg \u2014 Create node from SVG markup
-    fillStyleName (string, optional) \u2014 Paint style to apply to vector fills
-    fillVariableName (string, optional) \u2014 Color variable by name for vector fills
-    strokeStyleName (string, optional) \u2014 Paint style to apply to vector strokes
-    strokeVariableName (string, optional) \u2014 Color variable by name for vector strokes
-    svg (string, required) \u2014 SVG markup string
-    name (string, optional) \u2014 Layer name (default: 'SVG')
-    parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.
-    x (number, optional) \u2014 X position (default: 0)
-    y (number, optional) \u2014 Y position (default: 0)
+    Example: frames(method:"create", type:"svg", items:[{name:"Logo Mark", svg:"<svg width=\\"24\\" height=\\"24\\"><path d=\\"M4 4h16v16H4z\\" fill=\\"currentColor\\"/></svg>", fillVariableName:"icon/primary"}])
+    Item fields for items[] when type:"svg":
+      fillStyleName (string, optional) \u2014 Paint style to apply to vector fills
+      fillVariableName (string, optional) \u2014 Color variable by name for vector fills
+      strokeStyleName (string, optional) \u2014 Paint style to apply to vector strokes
+      strokeVariableName (string, optional) \u2014 Color variable by name for vector strokes
+      svg (string, required) \u2014 SVG markup string
+      name (string, optional) \u2014 Layer name (default: 'SVG')
+      parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.
+      x (number, optional) \u2014 X position (default: 0)
+      y (number, optional) \u2014 Y position (default: 0)
 
   ## slot \u2014 Create a slot inside a component. Slots are placeholder containers that instance users fill with content. Defaults to VERTICAL auto-layout with FILL/HUG sizing \u2014 ready to receive children. Accepts all frame layout properties.
-    name (string, optional) \u2014 Node name
-    parentId (string, optional) \u2014 Parent node ID inside the owning component. Required unless componentId is provided.
-    x (number, optional) \u2014 X position (default: 0)
-    y (number, optional) \u2014 Y position (default: 0)
-    width (number, optional) \u2014 Width in px (omit to shrink-to-content via HUG)
-    height (number, optional) \u2014 Height in px (omit to shrink-to-content via HUG)
-    rotation (number, optional) \u2014 Rotation in degrees (0-360)
-    visible (boolean, optional) \u2014 Show/hide (default true)
-    locked (boolean, optional) \u2014 Lock/unlock (default false)
-    opacity (string, optional) \u2014 Opacity (0-1) or variable name
-    blendMode (PASS_THROUGH | NORMAL | DARKEN | MULTIPLY | LINEAR_BURN | COLOR_BURN | LIGHTEN | SCREEN | LINEAR_DODGE | COLOR_DODGE | OVERLAY | SOFT_LIGHT | HARD_LIGHT | DIFFERENCE | EXCLUSION | HUE | SATURATION | COLOR | LUMINOSITY, optional)
-    effectStyleName (string, optional) \u2014 Effect style name (e.g. 'Shadow/Card') for shadows, blurs
-    fills (array, optional) \u2014 Fill paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] for transparent. Primary way to set fills.
-    fillColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid fill (auto-binds to matching variable/style)
-    fillStyleName (string, optional) \u2014 Paint style name for fill
-    fillVariableName (string, optional) \u2014 Color variable by name e.g. 'bg/primary'
-    imageUrl (string, optional) \u2014 Image source \u2014 'pexel:<id>' for Pexels photos, a public URL, or a local file path. SVGs are inserted as vectors; raster images become IMAGE fills.
-    imageScaleMode (FILL | FIT | CROP | TILE, optional) \u2014 How the image is scaled within the frame (default: FILL)
-    strokes (array, optional) \u2014 Stroke paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] to clear. Primary way to set strokes.
-    strokeColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid stroke (auto-binds to matching variable/style)
-    strokeStyleName (string, optional) \u2014 Paint style name for stroke
-    strokeVariableName (string, optional) \u2014 Color variable by name for stroke
-    strokeWeight (string, optional) \u2014 All sides (number) or variable name (string). Per-side: strokeTopWeight, strokeBottomWeight, strokeLeftWeight, strokeRightWeight.
-    strokeTopWeight (string, optional)
-    strokeBottomWeight (string, optional)
-    strokeLeftWeight (string, optional)
-    strokeRightWeight (string, optional)
-    strokeAlign (INSIDE | OUTSIDE | CENTER, optional) \u2014 Stroke position (default: INSIDE)
-    cornerRadius (string, optional) \u2014 All corners (number) or variable name (string). Per-corner: topLeftRadius, topRightRadius, bottomRightRadius, bottomLeftRadius.
-    topLeftRadius (string, optional)
-    topRightRadius (string, optional)
-    bottomRightRadius (string, optional)
-    bottomLeftRadius (string, optional)
-    layoutMode (NONE | HORIZONTAL | VERTICAL, optional) \u2014 Layout direction (default: auto \u2014 NONE when width+height set, otherwise inferred from layout props)
-    layoutWrap (NO_WRAP | WRAP, optional) \u2014 Wrap children to new rows (HORIZONTAL layout only \u2014 Figma does not support WRAP on VERTICAL layouts). Use column frames inside a HORIZONTAL parent for vertical grid patterns.
-    padding (string, optional) \u2014 All edges (number) or variable name (string). Per-edge: paddingTop, paddingRight, paddingBottom, paddingLeft.
-    paddingTop (string, optional)
-    paddingRight (string, optional)
-    paddingBottom (string, optional)
-    paddingLeft (string, optional)
-    primaryAxisAlignItems (MIN | MAX | CENTER | SPACE_BETWEEN, optional)
-    counterAxisAlignItems (MIN | MAX | CENTER | BASELINE, optional)
-    itemSpacing (string, optional) \u2014 Spacing between children (number or variable name string, default: 0)
-    counterAxisSpacing (string, optional) \u2014 Gap between wrapped rows (requires layoutWrap: WRAP)
-    strokesIncludedInLayout (boolean, optional) \u2014 Include stroke width in layout measurements (default: false)
-    overflowDirection (NONE | HORIZONTAL | VERTICAL | BOTH, optional) \u2014 Scroll overflow in prototype (default: NONE)
-    layoutPositioning (AUTO | ABSOLUTE, optional) \u2014 ABSOLUTE = floating inside auto-layout parent
-    layoutSizingHorizontal (FIXED | HUG | FILL, optional)
-    layoutSizingVertical (FIXED | HUG | FILL, optional)
-    minWidth (number, optional) \u2014 Min width for responsive auto-layout
-    maxWidth (number, optional) \u2014 Max width for responsive auto-layout
-    minHeight (number, optional) \u2014 Min height for responsive auto-layout
-    maxHeight (number, optional) \u2014 Max height for responsive auto-layout
-    annotations (array, optional) \u2014 Set annotations \u2014 [{label?, labelMarkdown?, properties?, categoryId?}]. Properties validated per node type.
-    componentId (string, optional) \u2014 Owning component ID. Optional \u2014 auto-resolved from parentId by walking up ancestors.`,
-      "commit": '# frames.commit\nCommit a staged node \u2014 unwraps from [STAGED] container into the original target location.\n\nExample: frames(method:"commit", id:"1:234")\n\nParams:\n    id (string, required) \u2014 Staged node ID to commit',
-      "export": "# frames.export\nExport a node as PNG, JPG, SVG, SVG_STRING, or PDF\n\nParams:\n    id (string, required) \u2014 Node ID to export\n    format (PNG | JPG | SVG | SVG_STRING | PDF, optional) \u2014 Export format (default: PNG). SVG_STRING returns raw SVG text.\n    scale (number, optional) \u2014 Export scale (default: 1, only for PNG/JPG)"
+    Example: frames(method:"create", type:"slot", items:[{componentId:"1:23", name:"Content Slot", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}])
+    Item fields for items[] when type:"slot":
+      name (string, optional) \u2014 Node name
+      parentId (string, optional) \u2014 Parent node ID inside the owning component. Required unless componentId is provided.
+      x (number, optional) \u2014 X position (default: 0)
+      y (number, optional) \u2014 Y position (default: 0)
+      width (number, optional) \u2014 Width in px (omit to shrink-to-content via HUG)
+      height (number, optional) \u2014 Height in px (omit to shrink-to-content via HUG)
+      rotation (number, optional) \u2014 Rotation in degrees (0-360)
+      visible (boolean, optional) \u2014 Show/hide (default true)
+      locked (boolean, optional) \u2014 Lock/unlock (default false)
+      opacity (string, optional) \u2014 Opacity (0-1) or variable name
+      blendMode (PASS_THROUGH | NORMAL | DARKEN | MULTIPLY | LINEAR_BURN | COLOR_BURN | LIGHTEN | SCREEN | LINEAR_DODGE | COLOR_DODGE | OVERLAY | SOFT_LIGHT | HARD_LIGHT | DIFFERENCE | EXCLUSION | HUE | SATURATION | COLOR | LUMINOSITY, optional)
+      effectStyleName (string, optional) \u2014 Effect style name (e.g. 'Shadow/Card') for shadows, blurs
+      fills (Paint[], optional) \u2014 Fill Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] for transparent. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables; use imageUrl/images for image authoring. IMAGE/VIDEO/PATTERN may appear in readback metadata only. Primary way to set non-image fills.
+      fillColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid fill (auto-binds to matching variable/style)
+      fillStyleName (string, optional) \u2014 Paint style name for fill
+      fillVariableName (string, optional) \u2014 Color variable by name e.g. 'bg/surface'
+      imageUrl (string, optional) \u2014 Image source \u2014 'pexel:<id>' for Pexels photos, a public URL, or a local file path. SVGs are inserted as vectors; raster images become IMAGE fills.
+      imageScaleMode (FILL | FIT | CROP | TILE, optional) \u2014 How the image is scaled within the frame (default: FILL)
+      strokes (Paint[], optional) \u2014 Stroke Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] to clear. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables. IMAGE/VIDEO/PATTERN may appear in readback metadata only. Primary way to set strokes.
+      strokeColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid stroke (auto-binds to matching variable/style)
+      strokeStyleName (string, optional) \u2014 Paint style name for stroke
+      strokeVariableName (string, optional) \u2014 Color variable by name for stroke
+      strokeWeight (string, optional) \u2014 All sides (number) or variable name (string). Per-side: strokeTopWeight, strokeBottomWeight, strokeLeftWeight, strokeRightWeight.
+      strokeTopWeight (string, optional)
+      strokeBottomWeight (string, optional)
+      strokeLeftWeight (string, optional)
+      strokeRightWeight (string, optional)
+      strokeAlign (INSIDE | OUTSIDE | CENTER, optional) \u2014 Stroke position (default: INSIDE)
+      cornerRadius (string, optional) \u2014 All corners (number) or variable name (string). Per-corner: topLeftRadius, topRightRadius, bottomRightRadius, bottomLeftRadius.
+      topLeftRadius (string, optional)
+      topRightRadius (string, optional)
+      bottomRightRadius (string, optional)
+      bottomLeftRadius (string, optional)
+      layoutMode (NONE | HORIZONTAL | VERTICAL, optional) \u2014 Layout direction (default: auto \u2014 NONE when width+height set, otherwise inferred from layout props)
+      layoutWrap (NO_WRAP | WRAP, optional) \u2014 Wrap children to new rows (HORIZONTAL layout only \u2014 Figma does not support WRAP on VERTICAL layouts). Use column frames inside a HORIZONTAL parent for vertical grid patterns.
+      padding (string, optional) \u2014 All edges (number) or variable name (string). Per-edge: paddingTop, paddingRight, paddingBottom, paddingLeft.
+      paddingTop (string, optional)
+      paddingRight (string, optional)
+      paddingBottom (string, optional)
+      paddingLeft (string, optional)
+      primaryAxisAlignItems (MIN | MAX | CENTER | SPACE_BETWEEN, optional)
+      counterAxisAlignItems (MIN | MAX | CENTER | BASELINE, optional)
+      itemSpacing (string, optional) \u2014 Spacing between children (number or variable name string, default: 0)
+      counterAxisSpacing (string, optional) \u2014 Gap between wrapped rows (requires layoutWrap: WRAP)
+      strokesIncludedInLayout (boolean, optional) \u2014 Include stroke width in layout measurements (default: false)
+      overflowDirection (NONE | HORIZONTAL | VERTICAL | BOTH, optional) \u2014 Scroll overflow in prototype (default: NONE)
+      layoutPositioning (AUTO | ABSOLUTE, optional) \u2014 ABSOLUTE = floating inside auto-layout parent
+      layoutSizingHorizontal (FIXED | HUG | FILL, optional)
+      layoutSizingVertical (FIXED | HUG | FILL, optional)
+      minWidth (number, optional) \u2014 Min width for responsive auto-layout
+      maxWidth (number, optional) \u2014 Max width for responsive auto-layout
+      minHeight (number, optional) \u2014 Min height for responsive auto-layout
+      maxHeight (number, optional) \u2014 Max height for responsive auto-layout
+      annotations (array, optional) \u2014 Set annotations \u2014 [{label?, labelMarkdown?, properties?, categoryId?}]. Properties validated per node type.
+      componentId (string, optional) \u2014 Owning component ID. Optional \u2014 auto-resolved from parentId by walking up ancestors.
+
+Response:
+    { results: ({id} | {error})[] }
+// Shared types:
+// Color: hex "#RGB"|"#RGBA"|"#RRGGBB"|"#RRGGBBAA" or {r: 0-1, g: 0-1, b: 0-1, a?: 0-1}
+// VariableAlias: {type: "VARIABLE_ALIAS", id: string}. The id must be a Figma VariableID; discover it via variables.get/list or variable_collections.get. Prefer colorVariableName/fillVariableName/strokeVariableName when available; Paint[] VariableAlias is mainly for precise Paint[] round-trips and gradient stop bindings.
+// Transform: [[number, number, number], [number, number, number]] (Figma Plugin API 2\xD73 matrix)
+// BlendMode: "PASS_THROUGH"|"NORMAL"|"DARKEN"|"MULTIPLY"|"LINEAR_BURN"|"COLOR_BURN"|"LIGHTEN"|"SCREEN"|"LINEAR_DODGE"|"COLOR_DODGE"|"OVERLAY"|"SOFT_LIGHT"|"HARD_LIGHT"|"DIFFERENCE"|"EXCLUSION"|"HUE"|"SATURATION"|"COLOR"|"LUMINOSITY"
+// ColorStop: {position: 0-1, color: Color, boundVariables?: {color?: VariableAlias}}
+// GradientPaint: {type: "GRADIENT_LINEAR"|"GRADIENT_RADIAL"|"GRADIENT_ANGULAR"|"GRADIENT_DIAMOND", gradientTransform: Transform, gradientStops: ColorStop[], visible?: boolean, opacity?: number, blendMode?: BlendMode}. Use gradientTransform + gradientStops (basic left-to-right: [[1,0,0],[0,1,0]]); do not use CSS gradients or REST gradientHandlePositions.
+// Effect: {type: "DROP_SHADOW"|"INNER_SHADOW"|"LAYER_BLUR"|"BACKGROUND_BLUR", radius: number, color?: {r,g,b,a} (0-1), offset?: {x, y}, spread?: number, visible?: boolean}
+// Paint: Paint[] authoring accepts only SOLID and GRADIENT_LINEAR/GRADIENT_RADIAL/GRADIENT_ANGULAR/GRADIENT_DIAMOND. SolidPaint: {type: "SOLID", color: Color, visible?: boolean, opacity?: number, blendMode?: BlendMode, boundVariables?: {color?: VariableAlias}}. GradientPaint authoring: {type: GRADIENT_*, gradientTransform: Transform, gradientStops: ColorStop[], visible?, opacity?, blendMode?}; bind variables on gradientStops[].boundVariables.color, not top-level gradient boundVariables. Do not pass IMAGE/VIDEO/PATTERN to create/update Paint[]; those may appear only in readback metadata from existing Figma content. Use imageUrl/images for image authoring. VIDEO/PATTERN authoring is not supported here. Do not use CSS gradients or REST gradientHandlePositions.`,
+      "commit": '# frames.commit\nCommit a staged node \u2014 unwraps from [STAGED] container into the original target location.\n\nExample: frames(method:"commit", id:"1:234")\n\nParams:\n    id (string, required) \u2014 Staged node ID to commit\n\nResponse:\n    { results: ({id} | {error})[] }',
+      "export": "# frames.export\nExport a node as PNG, JPG, SVG, SVG_STRING, or PDF\n\nParams:\n    id (string, required) \u2014 Node ID to export\n    format (PNG | JPG | SVG | SVG_STRING | PDF, optional) \u2014 Export format (default: PNG). SVG_STRING returns raw SVG text.\n    scale (number, optional) \u2014 Export scale (default: 1, only for PNG/JPG)\n\nResponse:\n    Binary image data returned as MCP image content (SVG_STRING returns text)\n    imageData (string, optional)\n    mimeType (string, optional)"
     }
   },
   "icons": {
     "summary": '# icons\nSearch and create icons from 200k+ open-source icons via Iconify.\n\nMethods:\n  search               Search icons by keyword across all Iconify sets [read]\n  collections          List available Iconify icon sets [read]\n  create               Create an icon node in Figma from an Iconify icon name [create]\n\n// Icons are fetched from the Iconify API (iconify.design) and inserted as SVG vector nodes.\n// Icon names use "prefix:name" format. Common sets: lucide, mdi, tabler, heroicons, ph.\n// Examples: "lucide:home", "mdi:account-circle", "tabler:arrow-right", "ph:gear-bold"\n// Use search to discover icons by keyword. Use collections to list available icon sets.\n// create fetches the SVG and inserts it via frames.create \u2014 auto-detects fill vs stroke icons.\n// Use colorVariableName (not fillVariableName/strokeVariableName) \u2014 the handler applies to whichever channel has paint.\n// Fetched icons are cached in memory for the session (same icon+size is fetched once).\n// Powered by Iconify (iconify.design) \u2014 open-source icon framework.\n\nUse icons(method: "help", topic: "<method>") for method details.',
     "methods": {
-      "search": '# icons.search\nSearch icons by keyword across all Iconify sets\n\nExample: icons(method:"search", query:"arrow right", prefix:"lucide")\n\nParams:\n    query (string, required) \u2014 Search keyword (e.g. "home", "arrow", "user")\n    prefix (string, optional) \u2014 Restrict to one icon set (e.g. "lucide", "mdi")\n    limit (number, optional) \u2014 Max results (default 64)',
-      "collections": '# icons.collections\nList available Iconify icon sets\n\nExample: icons(method:"collections", category:"UI 24px", limit:10)\n\nParams:\n    query (string, optional) \u2014 Filter by name or prefix (e.g. "lucide", "material")\n    category (string, optional) \u2014 Filter by category (e.g. "UI 24px", "Logos", "Emoji")\n    limit (number, optional) \u2014 Max results (default: all)',
+      "search": '# icons.search\nSearch icons by keyword across all Iconify sets\n\nExample: icons(method:"search", query:"arrow right", prefix:"lucide")\n\nParams:\n    query (string, required) \u2014 Search keyword (e.g. "home", "arrow", "user")\n    prefix (string, optional) \u2014 Restrict to one icon set (e.g. "lucide", "mdi")\n    limit (number, optional) \u2014 Max results (default 64)\n\nResponse:\n    icons (string[], optional) \u2014 Icon names (e.g. ["lucide:home", "mdi:home"])\n    total (number, optional) \u2014 Total matching icons',
+      "collections": '# icons.collections\nList available Iconify icon sets\n\nExample: icons(method:"collections", category:"UI 24px", limit:10)\n\nParams:\n    query (string, optional) \u2014 Filter by name or prefix (e.g. "lucide", "material")\n    category (string, optional) \u2014 Filter by category (e.g. "UI 24px", "Logos", "Emoji")\n    limit (number, optional) \u2014 Max results (default: all)\n\nResponse:\n    Array of icon set metadata\n    collections (array, optional) \u2014 [{ prefix, name, total, category, license }]\n    total (number, optional) \u2014 Total matching collections (before limit)',
       "create": `# icons.create
 Create an icon node in Figma from an Iconify icon name
 
@@ -689,7 +808,18 @@ Params:
     x (number, optional) \u2014 X position (default: 0)
     y (number, optional) \u2014 Y position (default: 0)
     colorVariableName (string, optional) \u2014 Color variable for the icon \u2014 auto-detects fill vs stroke (e.g. 'text/primary')
-    colorStyleName (string, optional) \u2014 Paint style for the icon \u2014 auto-detects fill vs stroke (e.g. 'Icon/Primary')`
+    colorStyleName (string, optional) \u2014 Paint style for the icon \u2014 auto-detects fill vs stroke (e.g. 'Icon/Primary')
+
+Response:
+    { results: ({id} | {error})[] }
+// Shared types:
+// Color: hex "#RGB"|"#RGBA"|"#RRGGBB"|"#RRGGBBAA" or {r: 0-1, g: 0-1, b: 0-1, a?: 0-1}
+// VariableAlias: {type: "VARIABLE_ALIAS", id: string}. The id must be a Figma VariableID; discover it via variables.get/list or variable_collections.get. Prefer colorVariableName/fillVariableName/strokeVariableName when available; Paint[] VariableAlias is mainly for precise Paint[] round-trips and gradient stop bindings.
+// Transform: [[number, number, number], [number, number, number]] (Figma Plugin API 2\xD73 matrix)
+// BlendMode: "PASS_THROUGH"|"NORMAL"|"DARKEN"|"MULTIPLY"|"LINEAR_BURN"|"COLOR_BURN"|"LIGHTEN"|"SCREEN"|"LINEAR_DODGE"|"COLOR_DODGE"|"OVERLAY"|"SOFT_LIGHT"|"HARD_LIGHT"|"DIFFERENCE"|"EXCLUSION"|"HUE"|"SATURATION"|"COLOR"|"LUMINOSITY"
+// ColorStop: {position: 0-1, color: Color, boundVariables?: {color?: VariableAlias}}
+// GradientPaint: {type: "GRADIENT_LINEAR"|"GRADIENT_RADIAL"|"GRADIENT_ANGULAR"|"GRADIENT_DIAMOND", gradientTransform: Transform, gradientStops: ColorStop[], visible?: boolean, opacity?: number, blendMode?: BlendMode}. Use gradientTransform + gradientStops (basic left-to-right: [[1,0,0],[0,1,0]]); do not use CSS gradients or REST gradientHandlePositions.
+// Paint: Paint[] authoring accepts only SOLID and GRADIENT_LINEAR/GRADIENT_RADIAL/GRADIENT_ANGULAR/GRADIENT_DIAMOND. SolidPaint: {type: "SOLID", color: Color, visible?: boolean, opacity?: number, blendMode?: BlendMode, boundVariables?: {color?: VariableAlias}}. GradientPaint authoring: {type: GRADIENT_*, gradientTransform: Transform, gradientStops: ColorStop[], visible?, opacity?, blendMode?}; bind variables on gradientStops[].boundVariables.color, not top-level gradient boundVariables. Do not pass IMAGE/VIDEO/PATTERN to create/update Paint[]; those may appear only in readback metadata from existing Figma content. Use imageUrl/images for image authoring. VIDEO/PATTERN authoring is not supported here. Do not use CSS gradients or REST gradientHandlePositions.`
     }
   },
   "images": {
@@ -707,16 +837,36 @@ Params:
     color (string, optional) \u2014 Filter by color \u2014 hex (e.g. '#FF0000') or named: red, orange, yellow, green, turquoise, blue, violet, pink, brown, black, gray, white
     locale (string, optional) \u2014 Locale for search (e.g. 'en-US', 'ja-JP'). Default: en-US
     page (number, optional) \u2014 Page number for pagination (default: 1)
-    per_page (number, optional) \u2014 Results per page (default: 15, max: 80)`,
-      "preview": '# images.preview\nPreview a photo by ID \u2014 returns the image so you can see it before placing\n\nExample: images(method:"preview", id:12345)\n\nParams:\n    id (number, required) \u2014 Photo ID from search results\n    size (small | medium | large, optional) \u2014 Preview size (default: medium). small\u2248130px, medium\u2248350px, large\u2248940px height'
+    per_page (number, optional) \u2014 Results per page (default: 15, max: 80)
+
+Response:
+    photos (array, optional) \u2014 [{ id, alt, avg_color, width, height }]
+    total_results (number, optional) \u2014 Total matching photos
+    page (number, optional)
+    per_page (number, optional)`,
+      "preview": '# images.preview\nPreview a photo by ID \u2014 returns the image so you can see it before placing\n\nExample: images(method:"preview", id:12345)\n\nParams:\n    id (number, required) \u2014 Photo ID from search results\n    size (small | medium | large, optional) \u2014 Preview size (default: medium). small\u2248130px, medium\u2248350px, large\u2248940px height\n\nResponse:\n    The photo as a visual image preview\n    image'
     }
   },
   "instances": {
-    "summary": '# instances\nCreate and manage component instances.\n\nMethods:\n  list                 Search for nodes (returns stubs only \u2014 use get with depth for full properties) [read]\n  delete               Delete nodes [edit]\n  clone                Duplicate nodes \u2014 produces a same-type copy (frame\u2192frame, instance\u2192instance, component\u2192component). Instance clones reference the same source component; they do not duplicate the component definition. [create]\n  audit                Run lint on a node \u2014 returns severity-ranked findings [read]\n  reparent             Move nodes into a new parent [edit]\n  get                  Get instance detail with component properties and overrides [read]\n  create               Create component instances [create]\n  update               Set instance properties [edit]\n  swap                 Swap instance component (preserves overrides) [edit]\n  detach               Detach instances from their component (converts to frame) [edit]\n  reset_overrides      Reset all overrides on instances to match their main component [edit]\n\n// depth: omit \u2192 id+name stubs | 0 \u2192 props + child stubs | N \u2192 recurse N | -1 \u2192 full tree\n// fields: whitelist e.g. ["fills","opacity"] \u2014 id, name, type always included. Pass ["*"] for all.\n// layoutSizingHorizontal/Vertical: FIXED | HUG | FILL \u2014 how the node sizes within auto-layout.\n// Colors: fillVariableName/strokeVariableName bind by name \u2014 preferred over raw color values.\n// Note: node-based endpoints (frames, text, instances, components) use `results` as the list key.\n//   Standalone endpoints (styles, variables, variable_collections) use `items`. Components.list uses `items` (catalog view).\n// ---\n// visible: false hides the node. Omitted from response when true (the default).\n// locked: true prevents editing in Figma UI. Omitted when false (the default).\n// rotation: degrees (0-360). Omitted when 0.\n// blendMode: layer blend mode. Omitted when PASS_THROUGH (the default).\n// layoutPositioning: ABSOLUTE = floating inside auto-layout parent. Omitted when AUTO (the default).\n// minWidth/maxWidth/minHeight/maxHeight: responsive constraints for auto-layout children.\n// constraints: position behavior in non-auto-layout parents. Ignored inside auto-layout frames.\n// bindings: bind design variables to node properties. field uses slash path: "fills/0/color" (first fill), "strokes/0/color", "opacity", "width", "height", "cornerRadius", "paddingLeft", "itemSpacing".\n// explicitMode: pin a variable mode on this node. Use { collectionName, modeName } (preferred) or { collectionId, modeId }.\n// properties: escape hatch \u2014 set any Figma node property directly. Use only when no dedicated field exists.\ninterface Node {\n  id: string; name: string; type: string;\n  visible?: boolean;       // omitted when true\n  locked?: boolean;        // omitted when false\n  opacity?: number;        // omitted when 1\n  rotation?: number;       // omitted when 0\n  blendMode?: string;      // omitted when PASS_THROUGH\n  layoutPositioning?: "AUTO" | "ABSOLUTE";\n  layoutSizingHorizontal?: "FIXED" | "HUG" | "FILL";\n  layoutSizingVertical?: "FIXED" | "HUG" | "FILL";\n  minWidth?: number; maxWidth?: number; minHeight?: number; maxHeight?: number;\n  absoluteBoundingBox: { x: number; y: number; width: number; height: number };\n  fills?: Paint[];         // solid: {type: "SOLID", color: {r, g, b, a}}\n  strokes?: Paint[];\n  effects?: Effect[];      // DROP_SHADOW | INNER_SHADOW | LAYER_BLUR | BACKGROUND_BLUR\n  children?: NodeStub[];   // stubs: {id, name, type} \u2014 use depth to expand\n}\n// PatchItem uses flat params matching create shape \u2014 no nested sub-objects.\n// Fill/stroke/corner/layout/text params are identical to frames.create and text.create.\n// Unknown keys produce a warning, preventing silent failures.\n// Instances are linked copies of components. Changes to the component propagate to all instances.\n// Overrides: instance-level changes (text, fills, visibility) that differ from the component. Shown in overrides array.\n// variantProperties: when creating from a component set, pick which variant e.g. {"Style":"Secondary","Size":"Large"}.\n// ---\n// Property keys: read returns clean names ("Label"), write requires the #suffix ("Label#1:0"). Call instances.get(id) to discover exact keys before update.\n// swap: change which component an instance points to while preserving compatible overrides.\n// detach: permanently converts an instance to a regular frame, breaking the component link.\n// reset_overrides: reverts all instance overrides to match the main component.\n// Workflow (local components): components.list \u2192 instances.create with componentId + properties (one call).\n// Workflow (external/published libraries): library(method:"components", query:"...") \u2192 instances.create with componentName + properties. The MCP resolves componentName \u2192 key and imports via figma.importComponentByKeyAsync \u2014 the raw key never enters agent context.\n// Instances support frame-level overrides: layoutSizingHorizontal/Vertical (FIXED, FILL, HUG), opacity, width/height, min/max.\n// Use layoutSizingHorizontal: "FILL" to make instances stretch in auto-layout parents.\n\nUse instances(method: "help", topic: "<method>") for method details.',
+    "summary": '# instances\nCreate and manage component instances.\n\nMethods:\n  list                 Search for nodes (returns stubs only \u2014 use get with depth for full properties) [read]\n  delete               Delete nodes [edit]\n  clone                Duplicate nodes \u2014 produces a same-type copy (frame\u2192frame, instance\u2192instance, component\u2192component). Instance clones reference the same source component; they do not duplicate the component definition. [create]\n  scale                Proportionally rescale a node subtree using Figma\'s visual Scale tool behavior. This is for visual/artifact scaling, not responsive layout resizing. [edit]\n  audit                Run lint on a node \u2014 returns severity-ranked findings [read]\n  reparent             Move nodes into a new parent [edit]\n  get                  Get instance detail with component properties and overrides [read]\n  create               Create component instances [create]\n  update               Set instance properties [edit]\n  swap                 Swap instance component (preserves overrides) [edit]\n  detach               Detach instances from their component (converts to frame) [edit]\n  reset_overrides      Reset all overrides on instances to match their main component [edit]\n\n// depth: omit \u2192 id+name stubs | 0 \u2192 props + child stubs | N \u2192 recurse N | -1 \u2192 full tree\n// fields: whitelist e.g. ["fills","opacity"] \u2014 id, name, type always included. Pass ["*"] for all.\n// layoutSizingHorizontal/Vertical: FIXED | HUG | FILL \u2014 how the node sizes within auto-layout.\n// Colors: fillVariableName/strokeVariableName bind by name \u2014 preferred over raw color values.\n// Note: node-based endpoints (frames, text, instances, components) use `results` as the list key.\n//   Standalone endpoints (styles, variables, variable_collections) use `items`. Components.list uses `items` (catalog view).\n// ---\n// visible: false hides the node. Omitted from response when true (the default).\n// locked: true prevents editing in Figma UI. Omitted when false (the default).\n// rotation: degrees (0-360). Omitted when 0.\n// blendMode: layer blend mode. Omitted when PASS_THROUGH (the default).\n// layoutPositioning: ABSOLUTE = floating inside auto-layout parent. Omitted when AUTO (the default).\n// minWidth/maxWidth/minHeight/maxHeight: responsive constraints for auto-layout children.\n// constraints: position behavior in non-auto-layout parents. Ignored inside auto-layout frames.\n// bindings: bind design variables to node properties. field uses slash path: "fills/0/color" (first fill), "strokes/0/color", "opacity", "width", "height", "cornerRadius", "paddingLeft", "itemSpacing".\n// explicitMode: pin a variable mode on this node. Use { collectionName, modeName } (preferred) or { collectionId, modeId }.\n// clipsContent: clip children to the node bounds where supported (frames/components/instances). Set false for overflow-visible layouts.\ninterface Node {\n  id: string; name: string; type: string;\n  visible?: boolean;       // omitted when true\n  locked?: boolean;        // omitted when false\n  opacity?: number;        // omitted when 1\n  rotation?: number;       // omitted when 0\n  blendMode?: string;      // omitted when PASS_THROUGH\n  layoutPositioning?: "AUTO" | "ABSOLUTE";\n  layoutSizingHorizontal?: "FIXED" | "HUG" | "FILL";\n  layoutSizingVertical?: "FIXED" | "HUG" | "FILL";\n  minWidth?: number; maxWidth?: number; minHeight?: number; maxHeight?: number;\n  absoluteBoundingBox: { x: number; y: number; width: number; height: number };\n  fills?: Paint[];         // readback Paint[]; authoring supports SOLID + gradients via gradientTransform + gradientStops\n  strokes?: Paint[];\n  effects?: Effect[];      // DROP_SHADOW | INNER_SHADOW | LAYER_BLUR | BACKGROUND_BLUR\n  children?: NodeStub[];   // stubs: {id, name, type} \u2014 use depth to expand\n}\n// PatchItem uses flat params matching create shape \u2014 no nested sub-objects.\n// Fill/stroke/corner/layout/text params are identical to frames.create and text.create. Paint[] authoring supports SOLID + gradients only; IMAGE/VIDEO/PATTERN are readback-only metadata.\n// Unknown keys produce a warning, preventing silent failures.\n// Instances are linked copies of components. Changes to the component propagate to all instances.\n// Overrides: instance-level changes (text, fills, visibility) that differ from the component. Shown in overrides array.\n// variantProperties: when creating from a component set, pick which variant e.g. {"Style":"Secondary","Size":"Large"}.\n// ---\n// Property keys: read returns clean names ("Label"), write requires the #suffix ("Label#1:0"). Call instances.get(id) to discover exact keys before update.\n// swap: change which component an instance points to while preserving compatible overrides.\n// detach: permanently converts an instance to a regular frame, breaking the component link.\n// reset_overrides: reverts all instance overrides to match the main component.\n// Workflow (local components): components.list \u2192 instances.create with componentId + properties (one call).\n// Workflow (external/published libraries): library(method:"components", query:"...") \u2192 instances.create with componentName + properties. The MCP resolves componentName \u2192 key and imports via figma.importComponentByKeyAsync \u2014 the raw key never enters agent context.\n// Instances support frame-level overrides: layoutSizingHorizontal/Vertical (FIXED, FILL, HUG), opacity, width/height, min/max.\n// Use layoutSizingHorizontal: "FILL" to make instances stretch in auto-layout parents.\n\nUse instances(method: "help", topic: "<method>") for method details.\n// Shared types:\n// Color: hex "#RGB"|"#RGBA"|"#RRGGBB"|"#RRGGBBAA" or {r: 0-1, g: 0-1, b: 0-1, a?: 0-1}\n// VariableAlias: {type: "VARIABLE_ALIAS", id: string}. The id must be a Figma VariableID; discover it via variables.get/list or variable_collections.get. Prefer colorVariableName/fillVariableName/strokeVariableName when available; Paint[] VariableAlias is mainly for precise Paint[] round-trips and gradient stop bindings.\n// Transform: [[number, number, number], [number, number, number]] (Figma Plugin API 2\xD73 matrix)\n// BlendMode: "PASS_THROUGH"|"NORMAL"|"DARKEN"|"MULTIPLY"|"LINEAR_BURN"|"COLOR_BURN"|"LIGHTEN"|"SCREEN"|"LINEAR_DODGE"|"COLOR_DODGE"|"OVERLAY"|"SOFT_LIGHT"|"HARD_LIGHT"|"DIFFERENCE"|"EXCLUSION"|"HUE"|"SATURATION"|"COLOR"|"LUMINOSITY"\n// ColorStop: {position: 0-1, color: Color, boundVariables?: {color?: VariableAlias}}\n// GradientPaint: {type: "GRADIENT_LINEAR"|"GRADIENT_RADIAL"|"GRADIENT_ANGULAR"|"GRADIENT_DIAMOND", gradientTransform: Transform, gradientStops: ColorStop[], visible?: boolean, opacity?: number, blendMode?: BlendMode}. Use gradientTransform + gradientStops (basic left-to-right: [[1,0,0],[0,1,0]]); do not use CSS gradients or REST gradientHandlePositions.\n// Effect: {type: "DROP_SHADOW"|"INNER_SHADOW"|"LAYER_BLUR"|"BACKGROUND_BLUR", radius: number, color?: {r,g,b,a} (0-1), offset?: {x, y}, spread?: number, visible?: boolean}\n// Paint: Paint[] authoring accepts only SOLID and GRADIENT_LINEAR/GRADIENT_RADIAL/GRADIENT_ANGULAR/GRADIENT_DIAMOND. SolidPaint: {type: "SOLID", color: Color, visible?: boolean, opacity?: number, blendMode?: BlendMode, boundVariables?: {color?: VariableAlias}}. GradientPaint authoring: {type: GRADIENT_*, gradientTransform: Transform, gradientStops: ColorStop[], visible?, opacity?, blendMode?}; bind variables on gradientStops[].boundVariables.color, not top-level gradient boundVariables. Do not pass IMAGE/VIDEO/PATTERN to create/update Paint[]; those may appear only in readback metadata from existing Figma content. Use imageUrl/images for image authoring. VIDEO/PATTERN authoring is not supported here. Do not use CSS gradients or REST gradientHandlePositions.\n// NodeStub: {id: string, name: string, type: string}',
     "methods": {
-      "list": '# instances.list\nSearch for nodes (returns stubs only \u2014 use get with depth for full properties)\n\nParams:\n    query (string, optional) \u2014 Name search query (case-insensitive substring match)\n    types (string[], optional) \u2014 Filter by node types (e.g. ["FRAME", "TEXT"])\n    parentId (string, optional) \u2014 Search only within this subtree\n    fields (string[], optional) \u2014 Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.\n    offset (number, optional) \u2014 Skip N items for pagination (default 0)\n    limit (number, optional) \u2014 Max items per page (default 100)',
-      "delete": "# instances.delete\nDelete nodes\n\nParams:\n    id (string, optional) \u2014 Single node ID\n    items (array, optional) \u2014 Batch: [{id}, ...]\n      id (string, optional)",
-      "clone": "# instances.clone\nDuplicate nodes \u2014 produces a same-type copy (frame\u2192frame, instance\u2192instance, component\u2192component). Instance clones reference the same source component; they do not duplicate the component definition.\n\nParams:\n    id (string, optional) \u2014 Node ID\n    name (string, optional) \u2014 Rename the clone (set before appending to parent \u2014 required when cloning a variant into its component set to avoid duplicate names)\n    parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.\n    x (number, optional) \u2014 X position (default: 0)\n    y (number, optional) \u2014 Y position (default: 0)\n    items (array, optional) \u2014 Batch: [{id, name?, parentId?, x?, y?}, ...]. Alternative to single-item params.\n      id (string, required) \u2014 Node ID to clone\n      name (string, optional) \u2014 Rename the clone\n      parentId (string, optional) \u2014 Target parent\n      x (number, optional)\n      y (number, optional)\n    depth (number, optional) \u2014 Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.",
+      "list": '# instances.list\nSearch for nodes (returns stubs only \u2014 use get with depth for full properties)\n\nParams:\n    query (string, optional) \u2014 Name search query (case-insensitive substring match)\n    types (string[], optional) \u2014 Filter by node types (e.g. ["FRAME", "TEXT"])\n    parentId (string, optional) \u2014 Search only within this subtree\n    fields (string[], optional) \u2014 Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.\n    offset (number, optional) \u2014 Skip N items for pagination (default 0)\n    limit (number, optional) \u2014 Max items per page (default 100)\n\nResponse:\n    Paginated node search results (uses `results` not `items`)\n    totalCount (number, required) \u2014 Total matching nodes\n    returned (number, required) \u2014 Nodes in this page\n    offset (number, optional)\n    limit (number, optional)\n    results (array, required) \u2014 Matching node stubs\n      id (string, required)\n      name (string, required)\n      type (string, required)\n      parentId (string, required)\n      parentName (string, optional)\n      bounds (object, optional)',
+      "delete": '# instances.delete\nDelete nodes\n\nParams:\n    id (string, optional) \u2014 Single node ID\n    items (array, optional) \u2014 Batch: [{id}, ...]\n      id (string, optional)\n\nResponse:\n    { results: ("ok" | {error})[] }',
+      "clone": "# instances.clone\nDuplicate nodes \u2014 produces a same-type copy (frame\u2192frame, instance\u2192instance, component\u2192component). Instance clones reference the same source component; they do not duplicate the component definition.\n\nParams:\n    id (string, optional) \u2014 Node ID\n    name (string, optional) \u2014 Rename the clone (set before appending to parent \u2014 required when cloning a variant into its component set to avoid duplicate names)\n    parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.\n    x (number, optional) \u2014 X position (default: 0)\n    y (number, optional) \u2014 Y position (default: 0)\n    items (array, optional) \u2014 Batch: [{id, name?, parentId?, x?, y?}, ...]. Alternative to single-item params.\n      id (string, required) \u2014 Node ID to clone\n      name (string, optional) \u2014 Rename the clone\n      parentId (string, optional) \u2014 Target parent\n      x (number, optional)\n      y (number, optional)\n    depth (number, optional) \u2014 Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.\n\nResponse:\n    { results: ({id} | {error})[] }",
+      "scale": `# instances.scale
+Proportionally rescale a node subtree using Figma's visual Scale tool behavior. This is for visual/artifact scaling, not responsive layout resizing.
+
+Example: instances(method:"scale", id:"1:23", factor:0.5)
+
+Params:
+    id (string, optional) \u2014 Node ID to scale
+    factor (number, optional) \u2014 Scale factor, >= 0.01. 0.5 = 50%, 2 = 200%. Scales children, text, strokes, effects, and layout geometry from the node's top-left. On auto-layout or HUG/FILL nodes, Figma may resolve responsive sizing to fixed width/height.
+    items (array, optional) \u2014 Batch: [{id, factor}, ...]. Alternative to single-item params.
+      id (string, required) \u2014 Node ID to scale
+      factor (number, required) \u2014 Scale factor, >= 0.01. 0.5 = 50%, 2 = 200%.
+
+Response:
+    { results: ("ok" | {error})[] }`,
       "audit": `# instances.audit
 Run lint on a node \u2014 returns severity-ranked findings
 
@@ -726,13 +876,18 @@ Params:
     maxDepth (number, optional) \u2014 Max tree depth (default: 10)
     maxFindings (number, optional) \u2014 Max findings (default: 50)
     minSeverity (error | unsafe | heuristic | style | verbose, optional) \u2014 Minimum severity to report (default: style). Set to 'verbose' to include AAA contrast and line-height checks.
-    skipInstances (boolean, optional) \u2014 Skip instance internals \u2014 findings inside instances are owned by the component (default: true)`,
-      "reparent": "# instances.reparent\nMove nodes into a new parent\n\nParams:\n    items (array, required) \u2014 Array of {id, parentId, index?}\n      id (string, required)\n      parentId (string, required)\n      index (number, optional)",
-      "get": '# instances.get\nGet instance detail with component properties and overrides\n\nParams:\n    id (string, required) \u2014 Instance node ID\n    fields (string[], optional) \u2014 Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.\n    depth (number, optional) \u2014 Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.\n    verbose (boolean, optional) \u2014 Include all properties (bounding box, constraints, text style details). Default false \u2014 returns slim, actionable output.',
+    skipInstances (boolean, optional) \u2014 Skip instance internals \u2014 findings inside instances are owned by the component (default: true)
+
+Response:
+    nodeId (string, optional)
+    nodeName (string, optional)
+    categories (array, optional) \u2014 Sorted by severity (error > unsafe > heuristic > style)`,
+      "reparent": '# instances.reparent\nMove nodes into a new parent\n\nParams:\n    items (array, required) \u2014 Array of {id, parentId, index?}\n      id (string, required)\n      parentId (string, required)\n      index (number, optional)\n\nResponse:\n    { results: ("ok" | {error})[] }',
+      "get": '# instances.get\nGet instance detail with component properties and overrides\n\nParams:\n    id (string, required) \u2014 Instance node ID\n    fields (string[], optional) \u2014 Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.\n    depth (number, optional) \u2014 Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.\n    verbose (boolean, optional) \u2014 Include all properties (bounding box, constraints, text style details). Default false \u2014 returns slim, actionable output.\n\nResponse:\n    results (array, required) \u2014 Serialized node(s) with componentProperties, overrides\n    _truncated (boolean, optional)',
       "create": `# instances.create
 Create component instances
 
-Example: instances(method:"create", items:[{componentName:"Button", variantProperties:{"Size":"Large"}, properties:{"Label":"Click me"}, parentId:"2:45", layoutSizingHorizontal:"FILL"}])  // or componentId:"1:23" for a local component
+Example: instances(method:"create", items:[{componentId:"1:23", variantProperties:{"Style":"Primary"}, properties:{"Button":"Click me"}, x:320, y:0}])
 
 Params:
     items (InstanceCreateItem[], required) \u2014 Array of {componentId, variantProperties?, x?, y?, parentId?, layoutSizingHorizontal?, ...}
@@ -761,19 +916,25 @@ Params:
       height (number, optional) \u2014 Override height (resize)
       explicitMode (object, optional) \u2014 Pin variable mode at creation \u2014 use { collectionName, modeName } (preferred) or { collectionId, modeId }. Useful for library components with Light/Dark modes.
       parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.
-    depth (number, optional) \u2014 Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.`,
+    depth (number, optional) \u2014 Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.
+
+Response:
+    { results: ({id} | {error})[] }
+// Shared types:
+// Color: hex "#RGB"|"#RGBA"|"#RRGGBB"|"#RRGGBBAA" or {r: 0-1, g: 0-1, b: 0-1, a?: 0-1}
+// Effect: {type: "DROP_SHADOW"|"INNER_SHADOW"|"LAYER_BLUR"|"BACKGROUND_BLUR", radius: number, color?: {r,g,b,a} (0-1), offset?: {x, y}, spread?: number, visible?: boolean}`,
       "update": `# instances.update
 Set instance properties
 
-Example: instances(method:"update", items:[{id:"1:23", properties:{"Label#4:0":"Submit"}, fillColor:"#3B82F6", layoutSizingHorizontal:"FILL"}])
+Example: instances(method:"update", items:[{id:"1:23", properties:{"Button#4:0":"Submit"}, fillVariableName:"bg/accent"}])
 
 Params:
-    items (InstanceUpdateItem[], required) \u2014 Array of {id, properties: {"Label#1:0":"text"}, fillColor?: ...}
-      fills (array, optional) \u2014 Fill paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] for transparent. Primary way to set fills.
+    items (InstanceUpdateItem[], required) \u2014 Array of {id, properties: {"Property#1:0":"text"}, fillVariableName?: ...}. Use components.get on the source component to discover exact property keys.
+      fills (Paint[], optional) \u2014 Fill Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] for transparent. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables; use imageUrl/images for image authoring. IMAGE/VIDEO/PATTERN may appear in readback metadata only. Primary way to set non-image fills.
       fillColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid fill (auto-binds to matching variable/style)
       fillStyleName (string, optional) \u2014 Paint style name for fill
-      fillVariableName (string, optional) \u2014 Color variable by name e.g. 'bg/primary'
-      strokes (array, optional) \u2014 Stroke paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] to clear. Primary way to set strokes.
+      fillVariableName (string, optional) \u2014 Color variable by name e.g. 'bg/surface'
+      strokes (Paint[], optional) \u2014 Stroke Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] to clear. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables. IMAGE/VIDEO/PATTERN may appear in readback metadata only. Primary way to set strokes.
       strokeColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid stroke (auto-binds to matching variable/style)
       strokeStyleName (string, optional) \u2014 Paint style name for stroke
       strokeVariableName (string, optional) \u2014 Color variable by name for stroke
@@ -845,10 +1006,22 @@ Params:
         variableName (string, optional)
         variableId (string, optional)
       explicitMode (object, optional) \u2014 Pin variable mode \u2014 use { collectionName, modeName } (preferred) or { collectionId, modeId }
-      exportSettings (array, optional) \u2014 Export settings`,
-      "swap": "# instances.swap\nSwap instance component (preserves overrides)\n\nParams:\n    items (array, required) \u2014 Array of {id, componentId}\n      id (string, required) \u2014 Instance node ID\n      componentId (string, required) \u2014 New component or component set ID",
-      "detach": "# instances.detach\nDetach instances from their component (converts to frame)\n\nParams:\n    items (array, required) \u2014 Array of {id}\n      id (string, required) \u2014 Instance node ID",
-      "reset_overrides": "# instances.reset_overrides\nReset all overrides on instances to match their main component\n\nParams:\n    items (array, required) \u2014 Array of {id}\n      id (string, required) \u2014 Instance node ID"
+      exportSettings (array, optional) \u2014 Export settings
+
+Response:
+    { results: ("ok" | {error} | object)[] }
+// Shared types:
+// Color: hex "#RGB"|"#RGBA"|"#RRGGBB"|"#RRGGBBAA" or {r: 0-1, g: 0-1, b: 0-1, a?: 0-1}
+// VariableAlias: {type: "VARIABLE_ALIAS", id: string}. The id must be a Figma VariableID; discover it via variables.get/list or variable_collections.get. Prefer colorVariableName/fillVariableName/strokeVariableName when available; Paint[] VariableAlias is mainly for precise Paint[] round-trips and gradient stop bindings.
+// Transform: [[number, number, number], [number, number, number]] (Figma Plugin API 2\xD73 matrix)
+// BlendMode: "PASS_THROUGH"|"NORMAL"|"DARKEN"|"MULTIPLY"|"LINEAR_BURN"|"COLOR_BURN"|"LIGHTEN"|"SCREEN"|"LINEAR_DODGE"|"COLOR_DODGE"|"OVERLAY"|"SOFT_LIGHT"|"HARD_LIGHT"|"DIFFERENCE"|"EXCLUSION"|"HUE"|"SATURATION"|"COLOR"|"LUMINOSITY"
+// ColorStop: {position: 0-1, color: Color, boundVariables?: {color?: VariableAlias}}
+// GradientPaint: {type: "GRADIENT_LINEAR"|"GRADIENT_RADIAL"|"GRADIENT_ANGULAR"|"GRADIENT_DIAMOND", gradientTransform: Transform, gradientStops: ColorStop[], visible?: boolean, opacity?: number, blendMode?: BlendMode}. Use gradientTransform + gradientStops (basic left-to-right: [[1,0,0],[0,1,0]]); do not use CSS gradients or REST gradientHandlePositions.
+// Effect: {type: "DROP_SHADOW"|"INNER_SHADOW"|"LAYER_BLUR"|"BACKGROUND_BLUR", radius: number, color?: {r,g,b,a} (0-1), offset?: {x, y}, spread?: number, visible?: boolean}
+// Paint: Paint[] authoring accepts only SOLID and GRADIENT_LINEAR/GRADIENT_RADIAL/GRADIENT_ANGULAR/GRADIENT_DIAMOND. SolidPaint: {type: "SOLID", color: Color, visible?: boolean, opacity?: number, blendMode?: BlendMode, boundVariables?: {color?: VariableAlias}}. GradientPaint authoring: {type: GRADIENT_*, gradientTransform: Transform, gradientStops: ColorStop[], visible?, opacity?, blendMode?}; bind variables on gradientStops[].boundVariables.color, not top-level gradient boundVariables. Do not pass IMAGE/VIDEO/PATTERN to create/update Paint[]; those may appear only in readback metadata from existing Figma content. Use imageUrl/images for image authoring. VIDEO/PATTERN authoring is not supported here. Do not use CSS gradients or REST gradientHandlePositions.`,
+      "swap": '# instances.swap\nSwap instance component (preserves overrides)\n\nParams:\n    items (array, required) \u2014 Array of {id, componentId}\n      id (string, required) \u2014 Instance node ID\n      componentId (string, required) \u2014 New component or component set ID\n\nResponse:\n    { results: ("ok" | {error} | object)[] }',
+      "detach": "# instances.detach\nDetach instances from their component (converts to frame)\n\nParams:\n    items (array, required) \u2014 Array of {id}\n      id (string, required) \u2014 Instance node ID\n\nResponse:\n    { results: ({id} | {error})[] }",
+      "reset_overrides": '# instances.reset_overrides\nReset all overrides on instances to match their main component\n\nParams:\n    items (array, required) \u2014 Array of {id}\n      id (string, required) \u2014 Instance node ID\n\nResponse:\n    { results: ("ok" | {error} | object)[] }'
     }
   },
   "library": {
@@ -898,7 +1071,16 @@ Example: library(method:"list")  // uses FIGMA_TEAM_ID env var; or pass file/tea
 
 Params:
     file (string, optional) \u2014 File URL or file key \u2014 e.g. 'https://www.figma.com/design/abc123/MyDS' or 'abc123'
-    team (string, optional) \u2014 Team URL or team ID. Falls back to FIGMA_TEAM_ID env var if omitted.`,
+    team (string, optional) \u2014 Team URL or team ID. Falls back to FIGMA_TEAM_ID env var if omitted.
+
+Response:
+    libraries (array, optional) \u2014 Components, sets, and styles grouped by source Figma file (library) and then by section \u2014 the same hierarchy designers see in Figma's Libraries browser. Use the library name to pick the intended kit when multiple libraries expose overlapping names (e.g. two files both defining 'Item' or 'Header'), and use section names to locate components semantically (e.g. the 'Sidebars' section contains the proper sidebar Item and Section Header, distinct from a List 'Item' row).
+      name (string, optional) \u2014 Display name of the source Figma file.
+      sections (array, optional) \u2014 Sections within the library, mirroring the headings designers see in Figma's Libraries panel. Usually correspond to containing frames or pages in the source file.
+        name (string, optional) \u2014 Section heading \u2014 e.g. 'Sidebars', 'Windows', 'Buttons'. '(unsectioned)' when the source component is not inside a named frame.
+        components (array, optional) \u2014 Non-variant component names in this section. Reference by name in instances.create via componentName.
+        componentSets (array, optional) \u2014 Variant set names in this section. Use with variantProperties in instances.create.
+        styles (object, optional) \u2014 Published styles in this section, grouped by type.`,
       "get": `# library.get
 Get rich details for components matching one or more queries. Returns nested libraries \u2192 sections \u2192 entries (same hierarchy as list) with properties, variant options, defaults, and a copy-pasteable usage hint at each leaf.
 
@@ -909,7 +1091,16 @@ Params:
     library (string, optional) \u2014 Optional source library (Figma file) name filter \u2014 case-insensitive substring. Use when multiple imported libraries expose overlapping component names (e.g. two files both defining 'Item'). Match the name returned under list \u2192 libraries[].name.
     section (string, optional) \u2014 Optional section name filter \u2014 case-insensitive substring. Matches the containing frame / section headers returned under list \u2192 libraries[].sections[].name (e.g. 'Sidebars', 'Windows', 'List'). Combine with library for maximum precision.
     file (string, optional) \u2014 Only used if the registry is empty \u2014 convenience to run list+get in one step.
-    team (string, optional) \u2014 Only used if the registry is empty \u2014 convenience to run list+get in one step.`
+    team (string, optional) \u2014 Only used if the registry is empty \u2014 convenience to run list+get in one step.
+
+Response:
+    libraries (array, optional) \u2014 Matching entries nested by source library and section \u2014 same hierarchy as list, but each leaf is a full detail object (properties, variant options, defaults, usage hint) instead of a bare name.
+      name (string, optional) \u2014 Source Figma file name.
+      sections (array, optional)
+        name (string, optional) \u2014 Section heading (containing frame). '(unsectioned)' when absent.
+        components (array, optional) \u2014 Non-variant components in this section with full detail. Each entry: { name, kind, description?, properties?, usage? } \u2014 properties is { [propName]: { type: VARIANT|TEXT|BOOLEAN|INSTANCE_SWAP, defaultValue?, options? } } matching components.get. usage is a copy-pasteable instances.create snippet.
+        componentSets (array, optional) \u2014 Variant component sets in this section with full detail, same shape as components above. VARIANT properties carry options; pair with TEXT/BOOLEAN properties via instances.create.
+        styles (object, optional) \u2014 Published styles in this section, grouped by type. Each entry: { name, kind: 'style', styleType, description? } (no properties/usage \u2014 styles have no variants).`
     }
   },
   "lint": {
@@ -948,6 +1139,7 @@ Methods:
 //   "shape-instead-of-frame" \u2014 shapes used as containers [style]
 //   "fixed-in-autolayout" \u2014 FIXED-size children in auto-layout parents [heuristic]
 //   "unbounded-hug" \u2014 HUG on both axes [unsafe; short leaf text\u2192style]
+//   "fill-in-hug" \u2014 collapsed FILL on the same axis inside a HUG parent (existing anchored states may be valid) [unsafe]
 //   "hug-cross-axis" \u2014 HUG on cross-axis of constrained parent [heuristic; leaf nodes\u2192style]
 //   "empty-container" \u2014 empty frames, excludes SLOT nodes [style]
 // Token rules [token]:
@@ -981,51 +1173,90 @@ Params:
     maxDepth (number, optional) \u2014 Max tree depth (default: 10)
     maxFindings (number, optional) \u2014 Max findings (default: 50)
     minSeverity (error | unsafe | heuristic | style | verbose, optional) \u2014 Minimum severity to report (default: style). Set to 'verbose' to include AAA contrast and line-height checks.
-    skipInstances (boolean, optional) \u2014 Skip instance internals \u2014 findings inside instances are owned by the component (default: true)`,
-      "fix": "# lint.fix\nAuto-fix frames to auto-layout\n\nParams:\n    items (array, required) \u2014 Array of {nodeId, layoutMode?, itemSpacing?}\n      nodeId (string, required) \u2014 Frame node ID\n      layoutMode (VERTICAL | HORIZONTAL, optional) \u2014 Direction (default: auto-detected)\n      itemSpacing (number, optional) \u2014 Spacing between children\n    depth (number, optional) \u2014 Response detail for fixed nodes: omit for stubs, 0=properties, -1=full tree"
+    skipInstances (boolean, optional) \u2014 Skip instance internals \u2014 findings inside instances are owned by the component (default: true)
+
+Response:
+    nodeId (string, required)
+    nodeName (string, required)
+    categories (array, required) \u2014 Sorted by severity (error > unsafe > heuristic > style)
+      rule (string, required)
+      severity (string, required) \u2014 error | unsafe | heuristic | style
+      category (string, required) \u2014 component | composition | token | accessibility | naming
+      count (number, required)
+      fix (string, required)
+      nodes (array, required)
+        id (string, required)
+        name (string, required)
+        severity (string, optional) \u2014 Per-finding override when context changes the default
+    warning (string, optional)`,
+      "fix": '# lint.fix\nAuto-fix frames to auto-layout\n\nParams:\n    items (array, required) \u2014 Array of {nodeId, layoutMode?, itemSpacing?}\n      nodeId (string, required) \u2014 Frame node ID\n      layoutMode (VERTICAL | HORIZONTAL, optional) \u2014 Direction (default: auto-detected)\n      itemSpacing (number, optional) \u2014 Spacing between children\n    depth (number, optional) \u2014 Response detail for fixed nodes: omit for stubs, 0=properties, -1=full tree\n\nResponse:\n    { results: ("ok" | {error} | object)[] }'
     }
   },
   "prototyping": {
     "summary": '# prototyping\nManage prototype interactions, reactions, and navigation flows.\n\nMethods:\n  get                  Get reactions and overflow direction on a node [read]\n  add                  Add a prototype reaction to a node [edit]\n  set                  Replace all reactions on a node (raw reactions array) [edit]\n  remove               Remove a reaction from a node by index [edit]\n\n// Reactions wire up interactions: trigger (ON_CLICK, ON_HOVER, ...) \u2192 action (navigate, swap, overlay).\n// Common patterns: button ON_CLICK \u2192 NAVIGATE to detail frame; card ON_HOVER \u2192 CHANGE_TO hover variant.\n// Multi-action: pass actions[] array to run multiple actions on one trigger (e.g. navigate + set variable mode).\n// ---\n// IMPORTANT: destination rules depend on navigation type:\n//   NAVIGATE/SWAP/OVERLAY/SCROLL_TO \u2192 destination must be a top-level frame (direct child of a page). Nested frames are rejected.\n//   CHANGE_TO \u2192 destination must be a variant (COMPONENT inside a COMPONENT_SET). Used for hover/state swaps within the same component.\n// ---\n// TRIGGERS: ON_CLICK | ON_HOVER | ON_PRESS | ON_DRAG | AFTER_TIMEOUT(timeout) | MOUSE_ENTER(delay) | MOUSE_LEAVE(delay) | ON_KEY_DOWN(keyCodes)\n// NAVIGATION: NAVIGATE (go to frame) | SWAP (swap overlay) | OVERLAY (show overlay) | SCROLL_TO | CHANGE_TO (swap component variant)\n// TRANSITIONS: DISSOLVE | SMART_ANIMATE | MOVE_IN | MOVE_OUT | PUSH | SLIDE_IN | SLIDE_OUT (+ direction for directional)\n// EASING: EASE_IN | EASE_OUT | EASE_IN_AND_OUT | LINEAR | GENTLE | QUICK | BOUNCY | SLOW\n// ACTIONS: NODE (navigate/swap) | BACK (go back) | CLOSE (close overlay) | URL (open link) | SET_VARIABLE_MODE (switch theme/mode)\n\nUse prototyping(method: "help", topic: "<method>") for method details.',
     "methods": {
-      "get": "# prototyping.get\nGet reactions and overflow direction on a node\n\nParams:\n    id (string, required) \u2014 Node ID",
-      "add": '# prototyping.add\nAdd a prototype reaction to a node\n\nExample: prototyping(method:"add", items:[{id:"btn-1", trigger:"ON_CLICK", destination:"frame-2", navigation:"NAVIGATE", transition:"SMART_ANIMATE"}, {id:"btn-2", trigger:"ON_CLICK", destination:"frame-3"}])\n\nParams:\n    id (string, optional) \u2014 Node ID\n    trigger (ON_CLICK | ON_HOVER | ON_PRESS | ON_DRAG | AFTER_TIMEOUT | MOUSE_ENTER | MOUSE_LEAVE | ON_KEY_DOWN, optional) \u2014 Trigger type\n    triggerDelay (number, optional) \u2014 Delay in ms for AFTER_TIMEOUT / MOUSE_ENTER / MOUSE_LEAVE triggers\n    triggerKeyCodes (number[], optional) \u2014 Key codes for ON_KEY_DOWN trigger\n    triggerDevice (KEYBOARD | XBOX_ONE | PS4 | SWITCH_PRO, optional) \u2014 Device for ON_KEY_DOWN (default: KEYBOARD)\n    destination (string, optional) \u2014 Target node ID (required for NODE actions). NAVIGATE/SWAP/OVERLAY: must be a top-level frame. CHANGE_TO: must be a variant (component inside a component set).\n    navigation (NAVIGATE | SWAP | OVERLAY | SCROLL_TO | CHANGE_TO, optional) \u2014 Navigation type (default: NAVIGATE)\n    transition (DISSOLVE | SMART_ANIMATE | MOVE_IN | MOVE_OUT | PUSH | SLIDE_IN | SLIDE_OUT | INSTANT, optional) \u2014 Transition animation (default: DISSOLVE). INSTANT = no animation.\n    transitionDirection (LEFT | RIGHT | TOP | BOTTOM, optional) \u2014 Direction for MOVE_IN, MOVE_OUT, PUSH, SLIDE_IN, SLIDE_OUT\n    duration (number, optional) \u2014 Transition duration in seconds (default: 0.3)\n    easing (EASE_IN | EASE_OUT | EASE_IN_AND_OUT | LINEAR | GENTLE | QUICK | BOUNCY | SLOW, optional) \u2014 Easing function (default: EASE_OUT)\n    actionType (NODE | BACK | CLOSE | URL | SET_VARIABLE_MODE, optional) \u2014 Action type (default: NODE). SET_VARIABLE_MODE switches a variable collection mode.\n    url (string, optional) \u2014 URL for URL action type\n    collectionName (string, optional) \u2014 Variable collection name (for SET_VARIABLE_MODE)\n    modeName (string, optional) \u2014 Mode name to switch to (for SET_VARIABLE_MODE)\n    resetScrollPosition (boolean, optional) \u2014 Reset scroll position on navigate (default: true)\n    actions (array, optional) \u2014 Multi-action: [{actionType, destination?, navigation?, collectionName?, modeName?, ...}]. Overrides single-action params.\n    items (array, optional) \u2014 Batch: array of {id, trigger, destination?, ...} reaction items\n      id (string, required) \u2014 Node ID\n      trigger (ON_CLICK | ON_HOVER | ON_PRESS | ON_DRAG | AFTER_TIMEOUT | MOUSE_ENTER | MOUSE_LEAVE | ON_KEY_DOWN, required) \u2014 Trigger type\n      destination (string, optional) \u2014 Target node ID\n      navigation (NAVIGATE | SWAP | OVERLAY | SCROLL_TO | CHANGE_TO, optional)\n      transition (DISSOLVE | SMART_ANIMATE | MOVE_IN | MOVE_OUT | PUSH | SLIDE_IN | SLIDE_OUT | INSTANT, optional)\n      transitionDirection (LEFT | RIGHT | TOP | BOTTOM, optional)\n      duration (number, optional)\n      easing (EASE_IN | EASE_OUT | EASE_IN_AND_OUT | LINEAR | GENTLE | QUICK | BOUNCY | SLOW, optional)\n      actionType (NODE | BACK | CLOSE | URL | SET_VARIABLE_MODE, optional)\n      triggerDelay (number, optional)\n      url (string, optional)\n      collectionName (string, optional)\n      modeName (string, optional)\n      resetScrollPosition (boolean, optional)\n      actions (array, optional)',
-      "set": "# prototyping.set\nReplace all reactions on a node (raw reactions array)\n\nParams:\n    id (string, required) \u2014 Node ID\n    reactions (array, required) \u2014 Full reactions array \u2014 [{trigger:{type}, actions:[{type, destinationId, navigation, transition}]}]",
-      "remove": "# prototyping.remove\nRemove a reaction from a node by index\n\nParams:\n    id (string, required) \u2014 Node ID\n    index (number, required) \u2014 Reaction index (0-based)"
+      "get": "# prototyping.get\nGet reactions and overflow direction on a node\n\nParams:\n    id (string, required) \u2014 Node ID\n\nResponse:\n    reactions (array, optional) \u2014 Reactions on this node\n    overflowDirection (string, optional) \u2014 Overflow scroll direction (NONE, HORIZONTAL, VERTICAL, BOTH)",
+      "add": '# prototyping.add\nAdd a prototype reaction to a node\n\nExample: prototyping(method:"add", items:[{id:"btn-1", trigger:"ON_CLICK", destination:"frame-2", navigation:"NAVIGATE", transition:"SMART_ANIMATE"}, {id:"btn-2", trigger:"ON_CLICK", destination:"frame-3"}])\n\nParams:\n    id (string, optional) \u2014 Node ID\n    trigger (ON_CLICK | ON_HOVER | ON_PRESS | ON_DRAG | AFTER_TIMEOUT | MOUSE_ENTER | MOUSE_LEAVE | ON_KEY_DOWN, optional) \u2014 Trigger type\n    triggerDelay (number, optional) \u2014 Delay in ms for AFTER_TIMEOUT / MOUSE_ENTER / MOUSE_LEAVE triggers\n    triggerKeyCodes (number[], optional) \u2014 Key codes for ON_KEY_DOWN trigger\n    triggerDevice (KEYBOARD | XBOX_ONE | PS4 | SWITCH_PRO, optional) \u2014 Device for ON_KEY_DOWN (default: KEYBOARD)\n    destination (string, optional) \u2014 Target node ID (required for NODE actions). NAVIGATE/SWAP/OVERLAY: must be a top-level frame. CHANGE_TO: must be a variant (component inside a component set).\n    navigation (NAVIGATE | SWAP | OVERLAY | SCROLL_TO | CHANGE_TO, optional) \u2014 Navigation type (default: NAVIGATE)\n    transition (DISSOLVE | SMART_ANIMATE | MOVE_IN | MOVE_OUT | PUSH | SLIDE_IN | SLIDE_OUT | INSTANT, optional) \u2014 Transition animation (default: DISSOLVE). INSTANT = no animation.\n    transitionDirection (LEFT | RIGHT | TOP | BOTTOM, optional) \u2014 Direction for MOVE_IN, MOVE_OUT, PUSH, SLIDE_IN, SLIDE_OUT\n    duration (number, optional) \u2014 Transition duration in seconds (default: 0.3)\n    easing (EASE_IN | EASE_OUT | EASE_IN_AND_OUT | LINEAR | GENTLE | QUICK | BOUNCY | SLOW, optional) \u2014 Easing function (default: EASE_OUT)\n    actionType (NODE | BACK | CLOSE | URL | SET_VARIABLE_MODE, optional) \u2014 Action type (default: NODE). SET_VARIABLE_MODE switches a variable collection mode.\n    url (string, optional) \u2014 URL for URL action type\n    collectionName (string, optional) \u2014 Variable collection name (for SET_VARIABLE_MODE)\n    modeName (string, optional) \u2014 Mode name to switch to (for SET_VARIABLE_MODE)\n    resetScrollPosition (boolean, optional) \u2014 Reset scroll position on navigate (default: true)\n    actions (array, optional) \u2014 Multi-action: [{actionType, destination?, navigation?, collectionName?, modeName?, ...}]. Overrides single-action params.\n    items (array, optional) \u2014 Batch: array of {id, trigger, destination?, ...} reaction items\n      id (string, required) \u2014 Node ID\n      trigger (ON_CLICK | ON_HOVER | ON_PRESS | ON_DRAG | AFTER_TIMEOUT | MOUSE_ENTER | MOUSE_LEAVE | ON_KEY_DOWN, required) \u2014 Trigger type\n      destination (string, optional) \u2014 Target node ID\n      navigation (NAVIGATE | SWAP | OVERLAY | SCROLL_TO | CHANGE_TO, optional)\n      transition (DISSOLVE | SMART_ANIMATE | MOVE_IN | MOVE_OUT | PUSH | SLIDE_IN | SLIDE_OUT | INSTANT, optional)\n      transitionDirection (LEFT | RIGHT | TOP | BOTTOM, optional)\n      duration (number, optional)\n      easing (EASE_IN | EASE_OUT | EASE_IN_AND_OUT | LINEAR | GENTLE | QUICK | BOUNCY | SLOW, optional)\n      actionType (NODE | BACK | CLOSE | URL | SET_VARIABLE_MODE, optional)\n      triggerDelay (number, optional)\n      url (string, optional)\n      collectionName (string, optional)\n      modeName (string, optional)\n      resetScrollPosition (boolean, optional)\n      actions (array, optional)\n\nResponse:\n    { results: ("ok" | {error})[] }',
+      "set": '# prototyping.set\nReplace all reactions on a node (raw reactions array)\n\nParams:\n    id (string, required) \u2014 Node ID\n    reactions (array, required) \u2014 Full reactions array \u2014 [{trigger:{type}, actions:[{type, destinationId, navigation, transition}]}]\n\nResponse:\n    { results: ("ok" | {error})[] }',
+      "remove": '# prototyping.remove\nRemove a reaction from a node by index\n\nParams:\n    id (string, required) \u2014 Node ID\n    index (number, required) \u2014 Reaction index (0-based)\n\nResponse:\n    { results: ("ok" | {error})[] }'
     }
   },
   "selection": {
     "summary": '# selection\nRead and set the current Figma selection.\n\nMethods:\n  get                  Get the current selection [read]\n  set                  Set selection to nodes and scroll viewport to show them [read]\n\n// Selection is the set of nodes currently highlighted in the Figma canvas.\n// get returns the current selection. Without depth, returns stubs ({id, name, type}). With depth=0, returns full properties.\n// _truncated: true when the response was cut short due to node budget limits. Use depth=0 or specific fields to reduce payload.\n// set replaces the entire selection AND scrolls the viewport to show the selected nodes.\n\nUse selection(method: "help", topic: "<method>") for method details.',
     "methods": {
-      "get": "# selection.get\nGet the current selection\n\nParams:\n    depth (number, optional) \u2014 Child recursion depth. Omit for stubs only, 0=selected nodes' properties, -1=unlimited.\n    verbose (boolean, optional) \u2014 Include all properties (bounding box, constraints, text style details). Default false \u2014 returns slim, actionable output.",
-      "set": '# selection.set\nSet selection to nodes and scroll viewport to show them\n\nParams:\n    nodeIds (string[], required) \u2014 Array of node IDs to select. Example: ["1:2","1:3"]'
+      "get": "# selection.get\nGet the current selection\n\nParams:\n    depth (number, optional) \u2014 Child recursion depth. Omit for stubs only, 0=selected nodes' properties, -1=unlimited.\n    verbose (boolean, optional) \u2014 Include all properties (bounding box, constraints, text style details). Default false \u2014 returns slim, actionable output.\n\nResponse:\n    results (array, required)\n      id (string, required)\n      name (string, required)\n      type (string, required)\n    _truncated (boolean, optional)\n    _notice (string, optional)",
+      "set": '# selection.set\nSet selection to nodes and scroll viewport to show them\n\nParams:\n    nodeIds (string[], required) \u2014 Array of node IDs to select. Example: ["1:2","1:3"]\n\nResponse:\n    count (number, required) \u2014 Number of nodes selected\n    selectedNodes (array, required)\n      name (string, required)\n      id (string, required)\n    notFoundIds (array, optional) \u2014 IDs that could not be found'
     }
   },
   "styles": {
-    "summary": '# styles\nCRUD for local paint, text, effect, and grid styles.\n\nMethods:\n  list                 List local styles with optional type filter [read]\n  get                  Get full style detail by ID [read]\n  create               Create local styles [create]\n  update               Update styles by ID or name [edit]\n  delete               Delete styles [edit]\n\n// Styles are named, reusable design properties that can be applied to nodes. Four types:\n//   paint: a named color (applied to fills/strokes), text: typography settings, effect: shadows/blurs, grid: layout grids.\n// All ID params accept both IDs and display names (case-insensitive). Use whichever you have.\n// ---\n// leadingTrim: "CAP_HEIGHT" trims line-height to cap height (tighter text boxes), "NONE" is default.\n// fontStyle: font variant name like "Bold", "Italic", "Bold Italic". Use fonts.list to find available styles.\n//\n// Effect object shape (for effect styles):\n//   { type: "DROP_SHADOW"|"INNER_SHADOW"|"LAYER_BLUR"|"BACKGROUND_BLUR",\n//     color?: Color, offset?: {x, y}, radius: number, spread?: number,\n//     visible?: boolean, blendMode?: string }\n//   DROP_SHADOW/INNER_SHADOW require color, offset, radius. LAYER_BLUR/BACKGROUND_BLUR require radius only.\n//   Example: { type: "DROP_SHADOW", color: "#00000040", offset: {x:0,y:4}, radius: 8 }\n//\n// LayoutGrid object shape (for grid styles):\n//   Rows/Columns: { pattern: "ROWS"|"COLUMNS", alignment: "MIN"|"MAX"|"STRETCH"|"CENTER",\n//     gutterSize: number, count: number, sectionSize?: number, offset?: number, visible?: boolean, color?: Color }\n//   Grid: { pattern: "GRID", sectionSize: number, visible?: boolean, color?: Color }\n//   Example: { pattern: "COLUMNS", alignment: "STRETCH", gutterSize: 20, count: 12, offset: 40 }\n\nUse styles(method: "help", topic: "<method>") for method details.',
+    "summary": '# styles\nCRUD for local paint, text, effect, and grid styles.\n\nMethods:\n  list                 List local styles with optional type filter [read]\n  get                  Get full style detail by ID [read]\n  create               Create local styles [create]\n  update               Update styles by ID or name [edit]\n  delete               Delete styles [edit]\n\n// Styles are named, reusable design properties that can be applied to nodes. Four types:\n//   paint: named PaintStyle.paints (applied to fills/strokes), text: typography settings, effect: shadows/blurs, grid: layout grids.\n// All ID params accept both IDs and display names (case-insensitive). Use whichever you have.\n// ---\n// leadingTrim: "CAP_HEIGHT" trims line-height to cap height (tighter text boxes), "NONE" is default.\n// fontStyle: font variant name like "Bold", "Italic", "Bold Italic". Use fonts.list to find available styles.\n// Paint styles: create/update paints: Paint[] authoring accepts only SOLID and gradients (GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND).\n// Use gradientTransform + gradientStops; for a basic left-to-right gradient use gradientTransform:[[1,0,0],[0,1,0]]. Do not use CSS gradients, REST gradientHandlePositions, or top-level gradient boundVariables.\n// styles.get/list readback may include IMAGE/VIDEO/PATTERN metadata from existing Figma content, but those are readback-only and cannot be passed back to create/update Paint[] authoring. Use imageUrl/images for image authoring on nodes; VIDEO/PATTERN authoring is not supported here.\n// For VariableAlias ids in Paint[] (SOLID boundVariables.color or gradientStops[].boundVariables.color), inspect variables.get/list or variable_collections.get. Prefer colorVariableName/fillVariableName where available.\n// Backward-compatible color/colorVariableName create/update shorthands still create a single SOLID paint.\n//\n// Effect object shape (for effect styles):\n//   { type: "DROP_SHADOW"|"INNER_SHADOW"|"LAYER_BLUR"|"BACKGROUND_BLUR",\n//     color?: Color, offset?: {x, y}, radius: number, spread?: number,\n//     visible?: boolean, blendMode?: string }\n//   DROP_SHADOW/INNER_SHADOW require color, offset, radius. LAYER_BLUR/BACKGROUND_BLUR require radius only.\n//   Example: { type: "DROP_SHADOW", color: "#00000040", offset: {x:0,y:4}, radius: 8 }\n//\n// LayoutGrid object shape (for grid styles) follows Figma Plugin API conditional shapes:\n//   Grid: { pattern:"GRID", sectionSize:number, visible?:boolean, color?:Color }\n//   Rows/Columns: { pattern:"ROWS"|"COLUMNS", alignment?:"MIN"|"MAX"|"STRETCH"|"CENTER", gutterSize?:number, count?:number, offset?:number, sectionSize?:number, visible?:boolean, color?:Color }\n//   Important: alignment:"STRETCH" must omit sectionSize because Figma computes stretched row/column sizes. Use sectionSize only with fixed rows/columns (MIN/MAX/CENTER) or GRID.\n//   Examples: stretch columns {pattern:"COLUMNS", alignment:"STRETCH", count:12, gutterSize:24, offset:80}; fixed columns {pattern:"COLUMNS", alignment:"MIN", count:12, gutterSize:24, offset:80, sectionSize:72}; square grid {pattern:"GRID", sectionSize:8}.\n\nUse styles(method: "help", topic: "<method>") for method details.\n// Shared types:\n// Color: hex "#RGB"|"#RGBA"|"#RRGGBB"|"#RRGGBBAA" or {r: 0-1, g: 0-1, b: 0-1, a?: 0-1}\n// VariableAlias: {type: "VARIABLE_ALIAS", id: string}. The id must be a Figma VariableID; discover it via variables.get/list or variable_collections.get. Prefer colorVariableName/fillVariableName/strokeVariableName when available; Paint[] VariableAlias is mainly for precise Paint[] round-trips and gradient stop bindings.\n// Transform: [[number, number, number], [number, number, number]] (Figma Plugin API 2\xD73 matrix)\n// BlendMode: "PASS_THROUGH"|"NORMAL"|"DARKEN"|"MULTIPLY"|"LINEAR_BURN"|"COLOR_BURN"|"LIGHTEN"|"SCREEN"|"LINEAR_DODGE"|"COLOR_DODGE"|"OVERLAY"|"SOFT_LIGHT"|"HARD_LIGHT"|"DIFFERENCE"|"EXCLUSION"|"HUE"|"SATURATION"|"COLOR"|"LUMINOSITY"\n// ColorStop: {position: 0-1, color: Color, boundVariables?: {color?: VariableAlias}}\n// GradientPaint: {type: "GRADIENT_LINEAR"|"GRADIENT_RADIAL"|"GRADIENT_ANGULAR"|"GRADIENT_DIAMOND", gradientTransform: Transform, gradientStops: ColorStop[], visible?: boolean, opacity?: number, blendMode?: BlendMode}. Use gradientTransform + gradientStops (basic left-to-right: [[1,0,0],[0,1,0]]); do not use CSS gradients or REST gradientHandlePositions.\n// Effect: {type: "DROP_SHADOW"|"INNER_SHADOW"|"LAYER_BLUR"|"BACKGROUND_BLUR", radius: number, color?: {r,g,b,a} (0-1), offset?: {x, y}, spread?: number, visible?: boolean}\n// Paint: Paint[] authoring accepts only SOLID and GRADIENT_LINEAR/GRADIENT_RADIAL/GRADIENT_ANGULAR/GRADIENT_DIAMOND. SolidPaint: {type: "SOLID", color: Color, visible?: boolean, opacity?: number, blendMode?: BlendMode, boundVariables?: {color?: VariableAlias}}. GradientPaint authoring: {type: GRADIENT_*, gradientTransform: Transform, gradientStops: ColorStop[], visible?, opacity?, blendMode?}; bind variables on gradientStops[].boundVariables.color, not top-level gradient boundVariables. Do not pass IMAGE/VIDEO/PATTERN to create/update Paint[]; those may appear only in readback metadata from existing Figma content. Use imageUrl/images for image authoring. VIDEO/PATTERN authoring is not supported here. Do not use CSS gradients or REST gradientHandlePositions.\n// LayoutGrid is conditional: GridLayoutGrid {pattern:"GRID", sectionSize:number, visible?:boolean, color?:Color}; RowsColsLayoutGrid {pattern:"ROWS"|"COLUMNS", alignment?:"MIN"|"MAX"|"CENTER"|"STRETCH", gutterSize?:number, count?:number, offset?:number, sectionSize?:number, visible?:boolean, color?:Color}. For alignment:"STRETCH", omit sectionSize; Figma computes stretched row/column sizes. Use sectionSize only with fixed rows/columns (MIN/MAX/CENTER) or GRID.',
     "methods": {
-      "list": '# styles.list\nList local styles with optional type filter\n\nParams:\n    type (paint | text | effect | grid, optional) \u2014 Filter by style type\n    fields (string[], optional) \u2014 Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.\n    offset (number, optional) \u2014 Skip N items for pagination (default 0)\n    limit (number, optional) \u2014 Max items per page (default 100)',
-      "get": '# styles.get\nGet full style detail by ID\n\nParams:\n    id (string, required) \u2014 Style ID or name\n    fields (string[], optional) \u2014 Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.',
-      "create": '# styles.create\nCreate local styles\n\nExample: styles(method:"create", type:"effect", name:"Shadow/Medium", effects:[{type:"DROP_SHADOW", color:"#00000040", offset:{x:0,y:4}, radius:8}])\n\nDiscriminant: type (paint | text | effect | grid)\n\n  ## paint \u2014 Paint/color style\n    name (string, required) \u2014 Style name\n    color (Color, optional) \u2014 Color value. Optional when colorVariableName is provided.\n    colorVariableName (string, optional) \u2014 Bind to a COLOR variable by name (style tracks the variable). Can be used alone \u2014 color is resolved from the variable.\n    description (string, optional) \u2014 Style description\n\n  ## text \u2014 Text style\n    name (string, required) \u2014 Style name\n    fontFamily (string, required) \u2014 Font family\n    fontStyle (string, optional) \u2014 Font style (default: Regular)\n    fontSize (number, required) \u2014 Font size\n    lineHeight (number | {value, unit: "PIXELS"|"PERCENT"|"AUTO"}, optional)\n    letterSpacing (number | {value, unit: "PIXELS"|"PERCENT"}, optional)\n    textCase (ORIGINAL | UPPER | LOWER | TITLE | SMALL_CAPS | SMALL_CAPS_FORCED, optional)\n    textDecoration (NONE | UNDERLINE | STRIKETHROUGH, optional)\n    paragraphIndent (number, optional) \u2014 Paragraph indent (px)\n    paragraphSpacing (number, optional) \u2014 Paragraph spacing (px)\n    leadingTrim (CAP_HEIGHT | NONE, optional) \u2014 Leading trim mode\n    description (string, optional) \u2014 Style description\n\n  ## effect \u2014 Effect style\n    name (string, required) \u2014 Style name\n    effects (array, required) \u2014 Array of Effect objects\n    description (string, optional) \u2014 Style description\n\n  ## grid \u2014 Grid/layout grid style\n    name (string, required) \u2014 Style name\n    layoutGrids (array, required) \u2014 Array of LayoutGrid objects\n    description (string, optional) \u2014 Style description',
-      "update": '# styles.update\nUpdate styles by ID or name\n\nExample: styles(method:"update", items:[{id:"Surface/Primary", color:"#F5F5F5"}])\n\nParams:\n    type (paint | text | effect | grid, optional) \u2014 Style type hint for strict validation (optional, auto-detected)\n    items (PatchStyleItem[], required) \u2014 Array of {id, ...fields} to update\n      id (string, required) \u2014 Style ID or name\n      name (string, optional) \u2014 Rename the style\n      description (string, optional) \u2014 Style description\n      color (Color, optional) \u2014 New color (paint styles)\n      colorVariableName (string, optional) \u2014 Bind to a COLOR variable by name (paint styles)\n      fontFamily (string, optional)\n      fontStyle (string, optional)\n      fontSize (number, optional)\n      lineHeight (number | {value, unit: "PIXELS"|"PERCENT"|"AUTO"}, optional)\n      letterSpacing (number | {value, unit: "PIXELS"|"PERCENT"}, optional)\n      textCase (ORIGINAL | UPPER | LOWER | TITLE | SMALL_CAPS | SMALL_CAPS_FORCED, optional)\n      textDecoration (NONE | UNDERLINE | STRIKETHROUGH, optional)\n      paragraphIndent (number, optional) \u2014 Paragraph indent (px)\n      paragraphSpacing (number, optional) \u2014 Paragraph spacing (px)\n      leadingTrim (CAP_HEIGHT | NONE, optional)\n      effects (array, optional) \u2014 Array of Effect objects\n      layoutGrids (array, optional) \u2014 Array of LayoutGrid objects (grid styles)',
-      "delete": "# styles.delete\nDelete styles\n\nParams:\n    id (string, optional) \u2014 Style ID or name\n    items (array, optional) \u2014 Batch: [{id}, ...]\n      id (string, required) \u2014 Style ID or name"
+      "list": '# styles.list\nList local styles with optional type filter\n\nParams:\n    type (paint | text | effect | grid, optional) \u2014 Filter by style type\n    fields (string[], optional) \u2014 Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.\n    offset (number, optional) \u2014 Skip N items for pagination (default 0)\n    limit (number, optional) \u2014 Max items per page (default 100)\n\nResponse:\n    totalCount (number, required)\n    returned (number, optional)\n    offset (number, optional)\n    limit (number, optional)\n    items (array, required)\n      id (string, required)\n      name (string, required)\n      type (string, required)',
+      "get": `# styles.get
+Get full style detail by ID
+
+Params:
+    id (string, required) \u2014 Style ID or name
+    fields (string[], optional) \u2014 Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.
+
+Response:
+    id (string, required)
+    name (string, required)
+    type (string, required) \u2014 PAINT | TEXT | EFFECT | GRID
+    paints (Paint[], optional) \u2014 PaintStyle.paints for PAINT styles. Readback returns Figma Plugin API Paint[]; gradients include gradientTransform, gradientStops, opacity/blendMode, and stop boundVariables. Existing Figma content may return IMAGE/VIDEO/PATTERN metadata, but those are readback-only and cannot be passed to create/update Paint[] authoring, which accepts only SOLID and gradients.
+    boundVariables (object, optional) \u2014 PaintStyle.boundVariables, e.g. {paints:[{type:'VARIABLE_ALIAS', id:'...'}]}
+    fontFamily (string, optional) \u2014 Font family (TEXT styles)
+    fontSize (number, optional) \u2014 Font size (TEXT styles)
+    effects (array, optional) \u2014 Effects array (EFFECT styles)
+    layoutGrids (array, optional) \u2014 Layout grids (GRID styles)
+// Shared types:
+// Color: hex "#RGB"|"#RGBA"|"#RRGGBB"|"#RRGGBBAA" or {r: 0-1, g: 0-1, b: 0-1, a?: 0-1}
+// VariableAlias: {type: "VARIABLE_ALIAS", id: string}. The id must be a Figma VariableID; discover it via variables.get/list or variable_collections.get. Prefer colorVariableName/fillVariableName/strokeVariableName when available; Paint[] VariableAlias is mainly for precise Paint[] round-trips and gradient stop bindings.
+// Transform: [[number, number, number], [number, number, number]] (Figma Plugin API 2\xD73 matrix)
+// BlendMode: "PASS_THROUGH"|"NORMAL"|"DARKEN"|"MULTIPLY"|"LINEAR_BURN"|"COLOR_BURN"|"LIGHTEN"|"SCREEN"|"LINEAR_DODGE"|"COLOR_DODGE"|"OVERLAY"|"SOFT_LIGHT"|"HARD_LIGHT"|"DIFFERENCE"|"EXCLUSION"|"HUE"|"SATURATION"|"COLOR"|"LUMINOSITY"
+// ColorStop: {position: 0-1, color: Color, boundVariables?: {color?: VariableAlias}}
+// GradientPaint: {type: "GRADIENT_LINEAR"|"GRADIENT_RADIAL"|"GRADIENT_ANGULAR"|"GRADIENT_DIAMOND", gradientTransform: Transform, gradientStops: ColorStop[], visible?: boolean, opacity?: number, blendMode?: BlendMode}. Use gradientTransform + gradientStops (basic left-to-right: [[1,0,0],[0,1,0]]); do not use CSS gradients or REST gradientHandlePositions.
+// Paint: Paint[] authoring accepts only SOLID and GRADIENT_LINEAR/GRADIENT_RADIAL/GRADIENT_ANGULAR/GRADIENT_DIAMOND. SolidPaint: {type: "SOLID", color: Color, visible?: boolean, opacity?: number, blendMode?: BlendMode, boundVariables?: {color?: VariableAlias}}. GradientPaint authoring: {type: GRADIENT_*, gradientTransform: Transform, gradientStops: ColorStop[], visible?, opacity?, blendMode?}; bind variables on gradientStops[].boundVariables.color, not top-level gradient boundVariables. Do not pass IMAGE/VIDEO/PATTERN to create/update Paint[]; those may appear only in readback metadata from existing Figma content. Use imageUrl/images for image authoring. VIDEO/PATTERN authoring is not supported here. Do not use CSS gradients or REST gradientHandlePositions.`,
+      "create": '# styles.create\nCreate local styles\n\nExample: styles(method:"create", type:"paint", items:[{name:"Gradient/Primary", paints:[{type:"GRADIENT_LINEAR", gradientTransform:[[1,0,0],[0,1,0]], gradientStops:[{position:0,color:"#7D58ED"},{position:1,color:"#207CE5"}]}]}])\n\nCall shape: styles(method:"create", type:"<type>", items:[{...type-specific fields...}])\nDo not pass type-specific item fields at the top level; put them inside items[].\n\nDiscriminant: type (paint | text | effect | grid)\nTop-level params:\n    type (paint | text | effect | grid, required) \u2014 Selects which item shape to use\n    items (array, required) \u2014 One or more type-specific item objects\n\n  ## paint \u2014 Paint/color style\n    Example: styles(method:"create", type:"paint", items:[{name:"Surface/Primary", colorVariableName:"bg/surface"}])\n    Item fields for items[] when type:"paint":\n      name (string, required) \u2014 Style name\n      paints (Paint[], optional) \u2014 PaintStyle.paints authoring array. Accepts only SOLID and GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND, using gradientTransform + gradientStops, opacity/blendMode, and gradientStops[].boundVariables.color. Mutually exclusive with color/colorVariableName shorthands. Do not pass IMAGE/VIDEO/PATTERN, CSS gradients, REST gradientHandlePositions, or top-level gradient boundVariables. Use imageUrl/images for image authoring on nodes; VIDEO/PATTERN authoring is not supported here. For examples call styles(method:"help", topic:"create").\n      color (Color, optional) \u2014 Single-solid shorthand color. Optional when colorVariableName or paints is provided.\n      colorVariableName (string, optional) \u2014 Single-solid shorthand: bind to a COLOR variable by name (style tracks the variable). Can be used alone \u2014 color is resolved from the variable.\n      description (string, optional) \u2014 Style description\n\n  ## text \u2014 Text style\n    Example: styles(method:"create", type:"text", items:[{name:"Heading/Medium", fontFamily:"Inter", fontStyle:"Medium", fontSize:20, lineHeight:{value:28, unit:"PIXELS"}}, {name:"Body/Regular", fontFamily:"Inter", fontSize:14, lineHeight:{value:20, unit:"PIXELS"}}, {name:"Body/Medium", fontFamily:"Inter", fontStyle:"Medium", fontSize:14, lineHeight:{value:20, unit:"PIXELS"}}])\n    Item fields for items[] when type:"text":\n      name (string, required) \u2014 Style name\n      fontFamily (string, required) \u2014 Font family\n      fontStyle (string, optional) \u2014 Font style (default: Regular)\n      fontSize (number, required) \u2014 Font size\n      lineHeight (number | {value, unit: "PIXELS"|"PERCENT"|"AUTO"}, optional)\n      letterSpacing (number | {value, unit: "PIXELS"|"PERCENT"}, optional)\n      textCase (ORIGINAL | UPPER | LOWER | TITLE | SMALL_CAPS | SMALL_CAPS_FORCED, optional)\n      textDecoration (NONE | UNDERLINE | STRIKETHROUGH, optional)\n      paragraphIndent (number, optional) \u2014 Paragraph indent (px)\n      paragraphSpacing (number, optional) \u2014 Paragraph spacing (px)\n      leadingTrim (CAP_HEIGHT | NONE, optional) \u2014 Leading trim mode\n      description (string, optional) \u2014 Style description\n\n  ## effect \u2014 Effect style\n    Example: styles(method:"create", type:"effect", items:[{name:"Shadow/Medium", effects:[{type:"DROP_SHADOW", color:"#00000040", offset:{x:0,y:4}, radius:8}]}])\n    Item fields for items[] when type:"effect":\n      name (string, required) \u2014 Style name\n      effects (array, required) \u2014 Array of Effect objects\n      description (string, optional) \u2014 Style description\n\n  ## grid \u2014 Grid/layout grid style\n    Example: styles(method:"create", type:"grid", items:[{name:"Grid/Desktop 12", layoutGrids:[{pattern:"COLUMNS", alignment:"STRETCH", count:12, gutterSize:24, offset:80}]}])\n    Item fields for items[] when type:"grid":\n      name (string, required) \u2014 Style name\n      layoutGrids (array, required) \u2014 Array of LayoutGrid objects. Conditional shapes: GRID requires sectionSize and does not use alignment/count/gutterSize/offset; ROWS/COLUMNS use alignment/count/gutterSize/offset, and sectionSize only for fixed alignments MIN/MAX/CENTER. For alignment:STRETCH, omit sectionSize.\n      description (string, optional) \u2014 Style description\n\nResponse:\n    { results: ({id} | {error})[] }\n// Shared types:\n// Color: hex "#RGB"|"#RGBA"|"#RRGGBB"|"#RRGGBBAA" or {r: 0-1, g: 0-1, b: 0-1, a?: 0-1}\n// VariableAlias: {type: "VARIABLE_ALIAS", id: string}. The id must be a Figma VariableID; discover it via variables.get/list or variable_collections.get. Prefer colorVariableName/fillVariableName/strokeVariableName when available; Paint[] VariableAlias is mainly for precise Paint[] round-trips and gradient stop bindings.\n// Transform: [[number, number, number], [number, number, number]] (Figma Plugin API 2\xD73 matrix)\n// BlendMode: "PASS_THROUGH"|"NORMAL"|"DARKEN"|"MULTIPLY"|"LINEAR_BURN"|"COLOR_BURN"|"LIGHTEN"|"SCREEN"|"LINEAR_DODGE"|"COLOR_DODGE"|"OVERLAY"|"SOFT_LIGHT"|"HARD_LIGHT"|"DIFFERENCE"|"EXCLUSION"|"HUE"|"SATURATION"|"COLOR"|"LUMINOSITY"\n// ColorStop: {position: 0-1, color: Color, boundVariables?: {color?: VariableAlias}}\n// GradientPaint: {type: "GRADIENT_LINEAR"|"GRADIENT_RADIAL"|"GRADIENT_ANGULAR"|"GRADIENT_DIAMOND", gradientTransform: Transform, gradientStops: ColorStop[], visible?: boolean, opacity?: number, blendMode?: BlendMode}. Use gradientTransform + gradientStops (basic left-to-right: [[1,0,0],[0,1,0]]); do not use CSS gradients or REST gradientHandlePositions.\n// Effect: {type: "DROP_SHADOW"|"INNER_SHADOW"|"LAYER_BLUR"|"BACKGROUND_BLUR", radius: number, color?: {r,g,b,a} (0-1), offset?: {x, y}, spread?: number, visible?: boolean}\n// Paint: Paint[] authoring accepts only SOLID and GRADIENT_LINEAR/GRADIENT_RADIAL/GRADIENT_ANGULAR/GRADIENT_DIAMOND. SolidPaint: {type: "SOLID", color: Color, visible?: boolean, opacity?: number, blendMode?: BlendMode, boundVariables?: {color?: VariableAlias}}. GradientPaint authoring: {type: GRADIENT_*, gradientTransform: Transform, gradientStops: ColorStop[], visible?, opacity?, blendMode?}; bind variables on gradientStops[].boundVariables.color, not top-level gradient boundVariables. Do not pass IMAGE/VIDEO/PATTERN to create/update Paint[]; those may appear only in readback metadata from existing Figma content. Use imageUrl/images for image authoring. VIDEO/PATTERN authoring is not supported here. Do not use CSS gradients or REST gradientHandlePositions.\n// LayoutGrid is conditional: GridLayoutGrid {pattern:"GRID", sectionSize:number, visible?:boolean, color?:Color}; RowsColsLayoutGrid {pattern:"ROWS"|"COLUMNS", alignment?:"MIN"|"MAX"|"CENTER"|"STRETCH", gutterSize?:number, count?:number, offset?:number, sectionSize?:number, visible?:boolean, color?:Color}. For alignment:"STRETCH", omit sectionSize; Figma computes stretched row/column sizes. Use sectionSize only with fixed rows/columns (MIN/MAX/CENTER) or GRID.',
+      "update": '# styles.update\nUpdate styles by ID or name\n\nExample: styles(method:"update", items:[{id:"Gradient/Primary", paints:[{type:"GRADIENT_LINEAR", gradientTransform:[[1,0,0],[0,1,0]], gradientStops:[{position:0,color:"#7D58ED"},{position:1,color:"#207CE5"}]}]}])\n\nParams:\n    type (paint | text | effect | grid, optional) \u2014 Style type hint for strict validation (optional, auto-detected)\n    items (PatchStyleItem[], required) \u2014 Array of {id, ...fields} to update\n      id (string, required) \u2014 Style ID or name\n      name (string, optional) \u2014 Rename the style\n      description (string, optional) \u2014 Style description\n      paints (Paint[], optional) \u2014 Replace PaintStyle.paints. Accepts only SOLID and GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND, using gradientTransform + gradientStops, opacity/blendMode, and gradientStops[].boundVariables.color. Mutually exclusive with color/colorVariableName. Do not pass IMAGE/VIDEO/PATTERN, CSS gradients, REST gradientHandlePositions, or top-level gradient boundVariables. Use imageUrl/images for image authoring on nodes; VIDEO/PATTERN authoring is not supported here. For examples call styles(method:"help", topic:"update").\n      color (Color, optional) \u2014 New single-solid color shorthand (paint styles)\n      colorVariableName (string, optional) \u2014 Bind to a COLOR variable by name using single-solid shorthand (paint styles)\n      fontFamily (string, optional)\n      fontStyle (string, optional)\n      fontSize (number, optional)\n      lineHeight (number | {value, unit: "PIXELS"|"PERCENT"|"AUTO"}, optional)\n      letterSpacing (number | {value, unit: "PIXELS"|"PERCENT"}, optional)\n      textCase (ORIGINAL | UPPER | LOWER | TITLE | SMALL_CAPS | SMALL_CAPS_FORCED, optional)\n      textDecoration (NONE | UNDERLINE | STRIKETHROUGH, optional)\n      paragraphIndent (number, optional) \u2014 Paragraph indent (px)\n      paragraphSpacing (number, optional) \u2014 Paragraph spacing (px)\n      leadingTrim (CAP_HEIGHT | NONE, optional)\n      effects (array, optional) \u2014 Array of Effect objects\n      layoutGrids (array, optional) \u2014 Array of LayoutGrid objects (grid styles). Conditional shapes: GRID requires sectionSize and does not use alignment/count/gutterSize/offset; ROWS/COLUMNS use alignment/count/gutterSize/offset, and sectionSize only for fixed alignments MIN/MAX/CENTER. For alignment:STRETCH, omit sectionSize.\n\nResponse:\n    { results: ("ok" | {error} | object)[] }\n// Shared types:\n// Color: hex "#RGB"|"#RGBA"|"#RRGGBB"|"#RRGGBBAA" or {r: 0-1, g: 0-1, b: 0-1, a?: 0-1}\n// VariableAlias: {type: "VARIABLE_ALIAS", id: string}. The id must be a Figma VariableID; discover it via variables.get/list or variable_collections.get. Prefer colorVariableName/fillVariableName/strokeVariableName when available; Paint[] VariableAlias is mainly for precise Paint[] round-trips and gradient stop bindings.\n// Transform: [[number, number, number], [number, number, number]] (Figma Plugin API 2\xD73 matrix)\n// BlendMode: "PASS_THROUGH"|"NORMAL"|"DARKEN"|"MULTIPLY"|"LINEAR_BURN"|"COLOR_BURN"|"LIGHTEN"|"SCREEN"|"LINEAR_DODGE"|"COLOR_DODGE"|"OVERLAY"|"SOFT_LIGHT"|"HARD_LIGHT"|"DIFFERENCE"|"EXCLUSION"|"HUE"|"SATURATION"|"COLOR"|"LUMINOSITY"\n// ColorStop: {position: 0-1, color: Color, boundVariables?: {color?: VariableAlias}}\n// GradientPaint: {type: "GRADIENT_LINEAR"|"GRADIENT_RADIAL"|"GRADIENT_ANGULAR"|"GRADIENT_DIAMOND", gradientTransform: Transform, gradientStops: ColorStop[], visible?: boolean, opacity?: number, blendMode?: BlendMode}. Use gradientTransform + gradientStops (basic left-to-right: [[1,0,0],[0,1,0]]); do not use CSS gradients or REST gradientHandlePositions.\n// Effect: {type: "DROP_SHADOW"|"INNER_SHADOW"|"LAYER_BLUR"|"BACKGROUND_BLUR", radius: number, color?: {r,g,b,a} (0-1), offset?: {x, y}, spread?: number, visible?: boolean}\n// Paint: Paint[] authoring accepts only SOLID and GRADIENT_LINEAR/GRADIENT_RADIAL/GRADIENT_ANGULAR/GRADIENT_DIAMOND. SolidPaint: {type: "SOLID", color: Color, visible?: boolean, opacity?: number, blendMode?: BlendMode, boundVariables?: {color?: VariableAlias}}. GradientPaint authoring: {type: GRADIENT_*, gradientTransform: Transform, gradientStops: ColorStop[], visible?, opacity?, blendMode?}; bind variables on gradientStops[].boundVariables.color, not top-level gradient boundVariables. Do not pass IMAGE/VIDEO/PATTERN to create/update Paint[]; those may appear only in readback metadata from existing Figma content. Use imageUrl/images for image authoring. VIDEO/PATTERN authoring is not supported here. Do not use CSS gradients or REST gradientHandlePositions.\n// LayoutGrid is conditional: GridLayoutGrid {pattern:"GRID", sectionSize:number, visible?:boolean, color?:Color}; RowsColsLayoutGrid {pattern:"ROWS"|"COLUMNS", alignment?:"MIN"|"MAX"|"CENTER"|"STRETCH", gutterSize?:number, count?:number, offset?:number, sectionSize?:number, visible?:boolean, color?:Color}. For alignment:"STRETCH", omit sectionSize; Figma computes stretched row/column sizes. Use sectionSize only with fixed rows/columns (MIN/MAX/CENTER) or GRID.',
+      "delete": '# styles.delete\nDelete styles\n\nParams:\n    id (string, optional) \u2014 Style ID or name\n    items (array, optional) \u2014 Batch: [{id}, ...]\n      id (string, required) \u2014 Style ID or name\n\nResponse:\n    { results: ("ok" | {error})[] }'
     }
   },
   "text": {
-    "summary": '# text\nCreate and manage text nodes.\n\nMethods:\n  get                  Get serialized node data [read]\n  list                 Search for nodes (returns stubs only \u2014 use get with depth for full properties) [read]\n  update               Patch node properties [edit]\n  delete               Delete nodes [edit]\n  clone                Duplicate nodes \u2014 produces a same-type copy (frame\u2192frame, instance\u2192instance, component\u2192component). Instance clones reference the same source component; they do not duplicate the component definition. [create]\n  audit                Run lint on a node \u2014 returns severity-ranked findings [read]\n  reparent             Move nodes into a new parent [edit]\n  create               Create text nodes [create]\n  set_content          Replace text content on existing text nodes [edit]\n  scan                 Scan all text nodes within a subtree [read]\n\n// depth: omit \u2192 id+name stubs | 0 \u2192 props + child stubs | N \u2192 recurse N | -1 \u2192 full tree\n// fields: whitelist e.g. ["fills","opacity"] \u2014 id, name, type always included. Pass ["*"] for all.\n// layoutSizingHorizontal/Vertical: FIXED | HUG | FILL \u2014 how the node sizes within auto-layout.\n// Colors: fillVariableName/strokeVariableName bind by name \u2014 preferred over raw color values.\n// Note: node-based endpoints (frames, text, instances, components) use `results` as the list key.\n//   Standalone endpoints (styles, variables, variable_collections) use `items`. Components.list uses `items` (catalog view).\n// ---\n// visible: false hides the node. Omitted from response when true (the default).\n// locked: true prevents editing in Figma UI. Omitted when false (the default).\n// rotation: degrees (0-360). Omitted when 0.\n// blendMode: layer blend mode. Omitted when PASS_THROUGH (the default).\n// layoutPositioning: ABSOLUTE = floating inside auto-layout parent. Omitted when AUTO (the default).\n// minWidth/maxWidth/minHeight/maxHeight: responsive constraints for auto-layout children.\n// constraints: position behavior in non-auto-layout parents. Ignored inside auto-layout frames.\n// bindings: bind design variables to node properties. field uses slash path: "fills/0/color" (first fill), "strokes/0/color", "opacity", "width", "height", "cornerRadius", "paddingLeft", "itemSpacing".\n// explicitMode: pin a variable mode on this node. Use { collectionName, modeName } (preferred) or { collectionId, modeId }.\n// properties: escape hatch \u2014 set any Figma node property directly. Use only when no dedicated field exists.\ninterface Node {\n  id: string; name: string; type: string;\n  visible?: boolean;       // omitted when true\n  locked?: boolean;        // omitted when false\n  opacity?: number;        // omitted when 1\n  rotation?: number;       // omitted when 0\n  blendMode?: string;      // omitted when PASS_THROUGH\n  layoutPositioning?: "AUTO" | "ABSOLUTE";\n  layoutSizingHorizontal?: "FIXED" | "HUG" | "FILL";\n  layoutSizingVertical?: "FIXED" | "HUG" | "FILL";\n  minWidth?: number; maxWidth?: number; minHeight?: number; maxHeight?: number;\n  absoluteBoundingBox: { x: number; y: number; width: number; height: number };\n  fills?: Paint[];         // solid: {type: "SOLID", color: {r, g, b, a}}\n  strokes?: Paint[];\n  effects?: Effect[];      // DROP_SHADOW | INNER_SHADOW | LAYER_BLUR | BACKGROUND_BLUR\n  children?: NodeStub[];   // stubs: {id, name, type} \u2014 use depth to expand\n}\n// PatchItem uses flat params matching create shape \u2014 no nested sub-objects.\n// Fill/stroke/corner/layout/text params are identical to frames.create and text.create.\n// Unknown keys produce a warning, preventing silent failures.\n// Text nodes display text content with typography styling. They inherit node methods (get, list, update, delete, clone, reparent).\n// textAutoResize: NONE (fixed box), WIDTH_AND_HEIGHT (grow both), HEIGHT (fixed width, auto height), TRUNCATE (fixed + ellipsis).\n// Prefer textStyleName for typography, fontColorVariableName/fontColorStyleName for color.\n// Aliases: fillColor \u2192 fontColor, fillVariableName \u2192 fontColorVariableName, fillStyleName \u2192 fontColorStyleName (consistent with frames API).\n// ---\n// Smart defaults inside auto-layout parent: layoutSizingHorizontal defaults to FILL, layoutSizingVertical to HUG, textAutoResize to HEIGHT.\n//   Text fills parent width and wraps automatically. Override with explicit values if needed.\n// fontStyle vs fontWeight: fontStyle is a named variant like "Bold", "Italic", "SemiBold". When set, fontWeight is ignored.\n//   Use fonts.list to find available fontFamily + fontStyle combinations.\n// scan: finds all text nodes in a subtree. path (when includePath:true) shows the layer hierarchy e.g. "Frame > Card > Label".\n// ScanResult (per-item): { nodeId, count, truncated, textNodes: [{ id, name, characters, fontSize, fontFamily, fontStyle, path?, depth?, absoluteX?, absoluteY?, width?, height? }] }\n\nUse text(method: "help", topic: "<method>") for method details.',
+    "summary": '# text\nCreate and manage text nodes.\n\nMethods:\n  get                  Get serialized node data [read]\n  list                 Search for nodes (returns stubs only \u2014 use get with depth for full properties) [read]\n  update               Patch node properties [edit]\n  delete               Delete nodes [edit]\n  clone                Duplicate nodes \u2014 produces a same-type copy (frame\u2192frame, instance\u2192instance, component\u2192component). Instance clones reference the same source component; they do not duplicate the component definition. [create]\n  scale                Proportionally rescale a node subtree using Figma\'s visual Scale tool behavior. This is for visual/artifact scaling, not responsive layout resizing. [edit]\n  audit                Run lint on a node \u2014 returns severity-ranked findings [read]\n  reparent             Move nodes into a new parent [edit]\n  create               Create text nodes [create]\n  set_content          Replace text content on existing text nodes [edit]\n  scan                 Scan all text nodes within a subtree [read]\n\n// depth: omit \u2192 id+name stubs | 0 \u2192 props + child stubs | N \u2192 recurse N | -1 \u2192 full tree\n// fields: whitelist e.g. ["fills","opacity"] \u2014 id, name, type always included. Pass ["*"] for all.\n// layoutSizingHorizontal/Vertical: FIXED | HUG | FILL \u2014 how the node sizes within auto-layout.\n// Colors: fillVariableName/strokeVariableName bind by name \u2014 preferred over raw color values.\n// Note: node-based endpoints (frames, text, instances, components) use `results` as the list key.\n//   Standalone endpoints (styles, variables, variable_collections) use `items`. Components.list uses `items` (catalog view).\n// ---\n// visible: false hides the node. Omitted from response when true (the default).\n// locked: true prevents editing in Figma UI. Omitted when false (the default).\n// rotation: degrees (0-360). Omitted when 0.\n// blendMode: layer blend mode. Omitted when PASS_THROUGH (the default).\n// layoutPositioning: ABSOLUTE = floating inside auto-layout parent. Omitted when AUTO (the default).\n// minWidth/maxWidth/minHeight/maxHeight: responsive constraints for auto-layout children.\n// constraints: position behavior in non-auto-layout parents. Ignored inside auto-layout frames.\n// bindings: bind design variables to node properties. field uses slash path: "fills/0/color" (first fill), "strokes/0/color", "opacity", "width", "height", "cornerRadius", "paddingLeft", "itemSpacing".\n// explicitMode: pin a variable mode on this node. Use { collectionName, modeName } (preferred) or { collectionId, modeId }.\n// clipsContent: clip children to the node bounds where supported (frames/components/instances). Set false for overflow-visible layouts.\ninterface Node {\n  id: string; name: string; type: string;\n  visible?: boolean;       // omitted when true\n  locked?: boolean;        // omitted when false\n  opacity?: number;        // omitted when 1\n  rotation?: number;       // omitted when 0\n  blendMode?: string;      // omitted when PASS_THROUGH\n  layoutPositioning?: "AUTO" | "ABSOLUTE";\n  layoutSizingHorizontal?: "FIXED" | "HUG" | "FILL";\n  layoutSizingVertical?: "FIXED" | "HUG" | "FILL";\n  minWidth?: number; maxWidth?: number; minHeight?: number; maxHeight?: number;\n  absoluteBoundingBox: { x: number; y: number; width: number; height: number };\n  fills?: Paint[];         // readback Paint[]; authoring supports SOLID + gradients via gradientTransform + gradientStops\n  strokes?: Paint[];\n  effects?: Effect[];      // DROP_SHADOW | INNER_SHADOW | LAYER_BLUR | BACKGROUND_BLUR\n  children?: NodeStub[];   // stubs: {id, name, type} \u2014 use depth to expand\n}\n// PatchItem uses flat params matching create shape \u2014 no nested sub-objects.\n// Fill/stroke/corner/layout/text params are identical to frames.create and text.create. Paint[] authoring supports SOLID + gradients only; IMAGE/VIDEO/PATTERN are readback-only metadata.\n// Unknown keys produce a warning, preventing silent failures.\n// Text nodes display text content with typography styling. They inherit node methods (get, list, update, delete, clone, reparent).\n// textAutoResize: NONE (fixed box), WIDTH_AND_HEIGHT (grow both), HEIGHT (fixed width, auto height), TRUNCATE (fixed + ellipsis).\n// Prefer textStyleName for typography, fontColorVariableName/fontColorStyleName for color.\n// Aliases: fillColor \u2192 fontColor, fillVariableName \u2192 fontColorVariableName, fillStyleName \u2192 fontColorStyleName (consistent with frames API).\n// ---\n// Smart defaults inside auto-layout parent: layoutSizingHorizontal defaults to FILL, layoutSizingVertical to HUG, textAutoResize to HEIGHT.\n//   Text fills parent width and wraps automatically. Override with explicit values if needed.\n// fontStyle vs fontWeight: fontStyle is a named variant like "Bold", "Italic", "SemiBold". When set, fontWeight is ignored.\n//   Use fonts.list to find available fontFamily + fontStyle combinations.\n// scan: finds all text nodes in a subtree. path (when includePath:true) shows the layer hierarchy e.g. "Frame > Card > Label".\n// ScanResult (per-item): { nodeId, count, truncated, textNodes: [{ id, name, characters, fontSize, fontFamily, fontStyle, path?, depth?, absoluteX?, absoluteY?, width?, height? }] }\n\nUse text(method: "help", topic: "<method>") for method details.\n// Shared types:\n// Color: hex "#RGB"|"#RGBA"|"#RRGGBB"|"#RRGGBBAA" or {r: 0-1, g: 0-1, b: 0-1, a?: 0-1}\n// VariableAlias: {type: "VARIABLE_ALIAS", id: string}. The id must be a Figma VariableID; discover it via variables.get/list or variable_collections.get. Prefer colorVariableName/fillVariableName/strokeVariableName when available; Paint[] VariableAlias is mainly for precise Paint[] round-trips and gradient stop bindings.\n// Transform: [[number, number, number], [number, number, number]] (Figma Plugin API 2\xD73 matrix)\n// BlendMode: "PASS_THROUGH"|"NORMAL"|"DARKEN"|"MULTIPLY"|"LINEAR_BURN"|"COLOR_BURN"|"LIGHTEN"|"SCREEN"|"LINEAR_DODGE"|"COLOR_DODGE"|"OVERLAY"|"SOFT_LIGHT"|"HARD_LIGHT"|"DIFFERENCE"|"EXCLUSION"|"HUE"|"SATURATION"|"COLOR"|"LUMINOSITY"\n// ColorStop: {position: 0-1, color: Color, boundVariables?: {color?: VariableAlias}}\n// GradientPaint: {type: "GRADIENT_LINEAR"|"GRADIENT_RADIAL"|"GRADIENT_ANGULAR"|"GRADIENT_DIAMOND", gradientTransform: Transform, gradientStops: ColorStop[], visible?: boolean, opacity?: number, blendMode?: BlendMode}. Use gradientTransform + gradientStops (basic left-to-right: [[1,0,0],[0,1,0]]); do not use CSS gradients or REST gradientHandlePositions.\n// Effect: {type: "DROP_SHADOW"|"INNER_SHADOW"|"LAYER_BLUR"|"BACKGROUND_BLUR", radius: number, color?: {r,g,b,a} (0-1), offset?: {x, y}, spread?: number, visible?: boolean}\n// Paint: Paint[] authoring accepts only SOLID and GRADIENT_LINEAR/GRADIENT_RADIAL/GRADIENT_ANGULAR/GRADIENT_DIAMOND. SolidPaint: {type: "SOLID", color: Color, visible?: boolean, opacity?: number, blendMode?: BlendMode, boundVariables?: {color?: VariableAlias}}. GradientPaint authoring: {type: GRADIENT_*, gradientTransform: Transform, gradientStops: ColorStop[], visible?, opacity?, blendMode?}; bind variables on gradientStops[].boundVariables.color, not top-level gradient boundVariables. Do not pass IMAGE/VIDEO/PATTERN to create/update Paint[]; those may appear only in readback metadata from existing Figma content. Use imageUrl/images for image authoring. VIDEO/PATTERN authoring is not supported here. Do not use CSS gradients or REST gradientHandlePositions.\n// NodeStub: {id: string, name: string, type: string}',
     "methods": {
-      "get": '# text.get\nGet serialized node data\n\nParams:\n    id (string, required) \u2014 Node ID\n    fields (string[], optional) \u2014 Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.\n    depth (number, optional) \u2014 Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.\n    verbose (boolean, optional) \u2014 Include all properties (bounding box, constraints, text style details). Default false \u2014 returns slim, actionable output.',
-      "list": '# text.list\nSearch for nodes (returns stubs only \u2014 use get with depth for full properties)\n\nParams:\n    query (string, optional) \u2014 Name search query (case-insensitive substring match)\n    types (string[], optional) \u2014 Filter by node types (e.g. ["FRAME", "TEXT"])\n    parentId (string, optional) \u2014 Search only within this subtree\n    fields (string[], optional) \u2014 Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.\n    offset (number, optional) \u2014 Skip N items for pagination (default 0)\n    limit (number, optional) \u2014 Max items per page (default 100)',
+      "get": '# text.get\nGet serialized node data\n\nParams:\n    id (string, required) \u2014 Node ID\n    fields (string[], optional) \u2014 Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.\n    depth (number, optional) \u2014 Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.\n    verbose (boolean, optional) \u2014 Include all properties (bounding box, constraints, text style details). Default false \u2014 returns slim, actionable output.\n\nResponse:\n    Serialized node tree. Shape depends on depth parameter.\n    results (Node[], required) \u2014 Serialized node trees\n    _truncated (boolean, optional) \u2014 True when node budget exceeded\n    _notice (string, optional) \u2014 Human-readable truncation notice',
+      "list": '# text.list\nSearch for nodes (returns stubs only \u2014 use get with depth for full properties)\n\nParams:\n    query (string, optional) \u2014 Name search query (case-insensitive substring match)\n    types (string[], optional) \u2014 Filter by node types (e.g. ["FRAME", "TEXT"])\n    parentId (string, optional) \u2014 Search only within this subtree\n    fields (string[], optional) \u2014 Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.\n    offset (number, optional) \u2014 Skip N items for pagination (default 0)\n    limit (number, optional) \u2014 Max items per page (default 100)\n\nResponse:\n    Paginated node search results (uses `results` not `items`)\n    totalCount (number, required) \u2014 Total matching nodes\n    returned (number, required) \u2014 Nodes in this page\n    offset (number, optional)\n    limit (number, optional)\n    results (array, required) \u2014 Matching node stubs\n      id (string, required)\n      name (string, required)\n      type (string, required)\n      parentId (string, required)\n      parentName (string, optional)\n      bounds (object, optional)',
       "update": `# text.update
 Patch node properties
 
 Params:
-    items (PatchItem[], required) \u2014 Array of {id, ...properties} to patch
-      fills (array, optional) \u2014 Fill paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] for transparent. Primary way to set fills.
+    items (PatchItem[], required) \u2014 Array of {id, ...fields} to patch
+      fills (Paint[], optional) \u2014 Fill Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] for transparent. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables; use imageUrl/images for image authoring. IMAGE/VIDEO/PATTERN may appear in readback metadata only. Primary way to set non-image fills.
       fillColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid fill (auto-binds to matching variable/style)
       fillStyleName (string, optional) \u2014 Paint style name for fill
-      fillVariableName (string, optional) \u2014 Color variable by name e.g. 'bg/primary'
-      strokes (array, optional) \u2014 Stroke paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] to clear. Primary way to set strokes.
+      fillVariableName (string, optional) \u2014 Color variable by name e.g. 'bg/surface'
+      strokes (Paint[], optional) \u2014 Stroke Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] to clear. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables. IMAGE/VIDEO/PATTERN may appear in readback metadata only. Primary way to set strokes.
       strokeColor (Color, optional) \u2014 Shorthand \u2014 sets a single solid stroke (auto-binds to matching variable/style)
       strokeStyleName (string, optional) \u2014 Paint style name for stroke
       strokeVariableName (string, optional) \u2014 Color variable by name for stroke
@@ -1100,9 +1331,35 @@ Params:
       explicitMode (object, optional) \u2014 Pin variable mode \u2014 use { collectionName, modeName } (preferred) or { collectionId, modeId }
       exportSettings (array, optional) \u2014 Export settings
       annotations (array, optional) \u2014 Set annotations \u2014 [{label?, labelMarkdown?, properties?, categoryId?}]. Properties are validated per node type.
-      properties (object, optional) \u2014 Direct Figma API props (escape hatch)`,
-      "delete": "# text.delete\nDelete nodes\n\nParams:\n    id (string, optional) \u2014 Single node ID\n    items (array, optional) \u2014 Batch: [{id}, ...]\n      id (string, optional)",
-      "clone": "# text.clone\nDuplicate nodes \u2014 produces a same-type copy (frame\u2192frame, instance\u2192instance, component\u2192component). Instance clones reference the same source component; they do not duplicate the component definition.\n\nParams:\n    id (string, optional) \u2014 Node ID\n    name (string, optional) \u2014 Rename the clone (set before appending to parent \u2014 required when cloning a variant into its component set to avoid duplicate names)\n    parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.\n    x (number, optional) \u2014 X position (default: 0)\n    y (number, optional) \u2014 Y position (default: 0)\n    items (array, optional) \u2014 Batch: [{id, name?, parentId?, x?, y?}, ...]. Alternative to single-item params.\n      id (string, required) \u2014 Node ID to clone\n      name (string, optional) \u2014 Rename the clone\n      parentId (string, optional) \u2014 Target parent\n      x (number, optional)\n      y (number, optional)\n    depth (number, optional) \u2014 Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.",
+      clipsContent (boolean, optional) \u2014 Clip children to bounds where supported (frames/components/instances).
+
+Response:
+    { results: ("ok" | {error} | object)[] }
+// Shared types:
+// Color: hex "#RGB"|"#RGBA"|"#RRGGBB"|"#RRGGBBAA" or {r: 0-1, g: 0-1, b: 0-1, a?: 0-1}
+// VariableAlias: {type: "VARIABLE_ALIAS", id: string}. The id must be a Figma VariableID; discover it via variables.get/list or variable_collections.get. Prefer colorVariableName/fillVariableName/strokeVariableName when available; Paint[] VariableAlias is mainly for precise Paint[] round-trips and gradient stop bindings.
+// Transform: [[number, number, number], [number, number, number]] (Figma Plugin API 2\xD73 matrix)
+// BlendMode: "PASS_THROUGH"|"NORMAL"|"DARKEN"|"MULTIPLY"|"LINEAR_BURN"|"COLOR_BURN"|"LIGHTEN"|"SCREEN"|"LINEAR_DODGE"|"COLOR_DODGE"|"OVERLAY"|"SOFT_LIGHT"|"HARD_LIGHT"|"DIFFERENCE"|"EXCLUSION"|"HUE"|"SATURATION"|"COLOR"|"LUMINOSITY"
+// ColorStop: {position: 0-1, color: Color, boundVariables?: {color?: VariableAlias}}
+// GradientPaint: {type: "GRADIENT_LINEAR"|"GRADIENT_RADIAL"|"GRADIENT_ANGULAR"|"GRADIENT_DIAMOND", gradientTransform: Transform, gradientStops: ColorStop[], visible?: boolean, opacity?: number, blendMode?: BlendMode}. Use gradientTransform + gradientStops (basic left-to-right: [[1,0,0],[0,1,0]]); do not use CSS gradients or REST gradientHandlePositions.
+// Effect: {type: "DROP_SHADOW"|"INNER_SHADOW"|"LAYER_BLUR"|"BACKGROUND_BLUR", radius: number, color?: {r,g,b,a} (0-1), offset?: {x, y}, spread?: number, visible?: boolean}
+// Paint: Paint[] authoring accepts only SOLID and GRADIENT_LINEAR/GRADIENT_RADIAL/GRADIENT_ANGULAR/GRADIENT_DIAMOND. SolidPaint: {type: "SOLID", color: Color, visible?: boolean, opacity?: number, blendMode?: BlendMode, boundVariables?: {color?: VariableAlias}}. GradientPaint authoring: {type: GRADIENT_*, gradientTransform: Transform, gradientStops: ColorStop[], visible?, opacity?, blendMode?}; bind variables on gradientStops[].boundVariables.color, not top-level gradient boundVariables. Do not pass IMAGE/VIDEO/PATTERN to create/update Paint[]; those may appear only in readback metadata from existing Figma content. Use imageUrl/images for image authoring. VIDEO/PATTERN authoring is not supported here. Do not use CSS gradients or REST gradientHandlePositions.`,
+      "delete": '# text.delete\nDelete nodes\n\nParams:\n    id (string, optional) \u2014 Single node ID\n    items (array, optional) \u2014 Batch: [{id}, ...]\n      id (string, optional)\n\nResponse:\n    { results: ("ok" | {error})[] }',
+      "clone": "# text.clone\nDuplicate nodes \u2014 produces a same-type copy (frame\u2192frame, instance\u2192instance, component\u2192component). Instance clones reference the same source component; they do not duplicate the component definition.\n\nParams:\n    id (string, optional) \u2014 Node ID\n    name (string, optional) \u2014 Rename the clone (set before appending to parent \u2014 required when cloning a variant into its component set to avoid duplicate names)\n    parentId (string, optional) \u2014 Parent node ID. Omit to place at current page root.\n    x (number, optional) \u2014 X position (default: 0)\n    y (number, optional) \u2014 Y position (default: 0)\n    items (array, optional) \u2014 Batch: [{id, name?, parentId?, x?, y?}, ...]. Alternative to single-item params.\n      id (string, required) \u2014 Node ID to clone\n      name (string, optional) \u2014 Rename the clone\n      parentId (string, optional) \u2014 Target parent\n      x (number, optional)\n      y (number, optional)\n    depth (number, optional) \u2014 Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.\n\nResponse:\n    { results: ({id} | {error})[] }",
+      "scale": `# text.scale
+Proportionally rescale a node subtree using Figma's visual Scale tool behavior. This is for visual/artifact scaling, not responsive layout resizing.
+
+Example: text(method:"scale", id:"1:23", factor:0.5)
+
+Params:
+    id (string, optional) \u2014 Node ID to scale
+    factor (number, optional) \u2014 Scale factor, >= 0.01. 0.5 = 50%, 2 = 200%. Scales children, text, strokes, effects, and layout geometry from the node's top-left. On auto-layout or HUG/FILL nodes, Figma may resolve responsive sizing to fixed width/height.
+    items (array, optional) \u2014 Batch: [{id, factor}, ...]. Alternative to single-item params.
+      id (string, required) \u2014 Node ID to scale
+      factor (number, required) \u2014 Scale factor, >= 0.01. 0.5 = 50%, 2 = 200%.
+
+Response:
+    { results: ("ok" | {error})[] }`,
       "audit": `# text.audit
 Run lint on a node \u2014 returns severity-ranked findings
 
@@ -1112,12 +1369,17 @@ Params:
     maxDepth (number, optional) \u2014 Max tree depth (default: 10)
     maxFindings (number, optional) \u2014 Max findings (default: 50)
     minSeverity (error | unsafe | heuristic | style | verbose, optional) \u2014 Minimum severity to report (default: style). Set to 'verbose' to include AAA contrast and line-height checks.
-    skipInstances (boolean, optional) \u2014 Skip instance internals \u2014 findings inside instances are owned by the component (default: true)`,
-      "reparent": "# text.reparent\nMove nodes into a new parent\n\nParams:\n    items (array, required) \u2014 Array of {id, parentId, index?}\n      id (string, required)\n      parentId (string, required)\n      index (number, optional)",
+    skipInstances (boolean, optional) \u2014 Skip instance internals \u2014 findings inside instances are owned by the component (default: true)
+
+Response:
+    nodeId (string, optional)
+    nodeName (string, optional)
+    categories (array, optional) \u2014 Sorted by severity (error > unsafe > heuristic > style)`,
+      "reparent": '# text.reparent\nMove nodes into a new parent\n\nParams:\n    items (array, required) \u2014 Array of {id, parentId, index?}\n      id (string, required)\n      parentId (string, required)\n      index (number, optional)\n\nResponse:\n    { results: ("ok" | {error})[] }',
       "create": `# text.create
 Create text nodes
 
-Example: text(method:"create", items:[{text:"Hello", fontFamily:"Inter", fontSize:16, textStyleName:"body/medium"}])
+Example: text(method:"create", items:[{text:"Hello", textStyleName:"Body/Regular", fontColorVariableName:"text/primary"}])
 
 Params:
     items (TextItem[], required) \u2014 Array of text items to create
@@ -1135,7 +1397,7 @@ Params:
       letterSpacing (number | {value, unit: "PIXELS"|"PERCENT"}, optional)
       textCase (ORIGINAL | UPPER | LOWER | TITLE | SMALL_CAPS | SMALL_CAPS_FORCED, optional)
       textDecoration (NONE | UNDERLINE | STRIKETHROUGH, optional)
-      fills (array, optional) \u2014 Text color paints \u2014 e.g. [{type: 'SOLID', color: '#hex'}]. Same as node fills.
+      fills (Paint[], optional) \u2014 Text Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. Same as node fills. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables. IMAGE/VIDEO/PATTERN may appear in readback metadata only.
       fontColor (Color, optional) \u2014 Shorthand \u2014 sets text color (auto-binds to matching variable/style)
       fontColorVariableName (string, optional) \u2014 Bind color variable by name e.g. 'text/primary'
       fontColorStyleName (string, optional) \u2014 Apply paint style \u2014 overrides fontColor
@@ -1149,20 +1411,56 @@ Params:
       componentPropertyName (string, optional) \u2014 Bind to a component TEXT property by name. Walks up ancestors to find the nearest component, or targets the component specified by componentId. For deeply nested text, consider using components(method:'create', type:'from_node') with exposeText:true instead \u2014 it auto-discovers and binds all text nodes.
       componentId (string, optional) \u2014 Target component ID for componentPropertyName binding. When omitted, walks up ancestors to find the nearest COMPONENT or COMPONENT_SET.
       annotations (array, optional) \u2014 Annotations \u2014 [{label?, labelMarkdown?, properties?, categoryId?}]
-    depth (number, optional) \u2014 Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.`,
-      "set_content": "# text.set_content\nReplace text content on existing text nodes\n\nParams:\n    items (array, required) \u2014 Array of {nodeId, text}\n      nodeId (string, required) \u2014 Text node ID\n      text (string, required) \u2014 New text content\n    depth (number, optional) \u2014 Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.",
-      "scan": "# text.scan\nScan all text nodes within a subtree\n\nParams:\n    items ({ nodeId: string; limit?: number; includePath?: boolean; includeGeometry?: boolean }[], required) \u2014 Array of subtrees to scan"
+    depth (number, optional) \u2014 Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.
+
+Response:
+    { results: ({id} | {error})[] }
+// Shared types:
+// Color: hex "#RGB"|"#RGBA"|"#RRGGBB"|"#RRGGBBAA" or {r: 0-1, g: 0-1, b: 0-1, a?: 0-1}
+// VariableAlias: {type: "VARIABLE_ALIAS", id: string}. The id must be a Figma VariableID; discover it via variables.get/list or variable_collections.get. Prefer colorVariableName/fillVariableName/strokeVariableName when available; Paint[] VariableAlias is mainly for precise Paint[] round-trips and gradient stop bindings.
+// Transform: [[number, number, number], [number, number, number]] (Figma Plugin API 2\xD73 matrix)
+// BlendMode: "PASS_THROUGH"|"NORMAL"|"DARKEN"|"MULTIPLY"|"LINEAR_BURN"|"COLOR_BURN"|"LIGHTEN"|"SCREEN"|"LINEAR_DODGE"|"COLOR_DODGE"|"OVERLAY"|"SOFT_LIGHT"|"HARD_LIGHT"|"DIFFERENCE"|"EXCLUSION"|"HUE"|"SATURATION"|"COLOR"|"LUMINOSITY"
+// ColorStop: {position: 0-1, color: Color, boundVariables?: {color?: VariableAlias}}
+// GradientPaint: {type: "GRADIENT_LINEAR"|"GRADIENT_RADIAL"|"GRADIENT_ANGULAR"|"GRADIENT_DIAMOND", gradientTransform: Transform, gradientStops: ColorStop[], visible?: boolean, opacity?: number, blendMode?: BlendMode}. Use gradientTransform + gradientStops (basic left-to-right: [[1,0,0],[0,1,0]]); do not use CSS gradients or REST gradientHandlePositions.
+// Paint: Paint[] authoring accepts only SOLID and GRADIENT_LINEAR/GRADIENT_RADIAL/GRADIENT_ANGULAR/GRADIENT_DIAMOND. SolidPaint: {type: "SOLID", color: Color, visible?: boolean, opacity?: number, blendMode?: BlendMode, boundVariables?: {color?: VariableAlias}}. GradientPaint authoring: {type: GRADIENT_*, gradientTransform: Transform, gradientStops: ColorStop[], visible?, opacity?, blendMode?}; bind variables on gradientStops[].boundVariables.color, not top-level gradient boundVariables. Do not pass IMAGE/VIDEO/PATTERN to create/update Paint[]; those may appear only in readback metadata from existing Figma content. Use imageUrl/images for image authoring. VIDEO/PATTERN authoring is not supported here. Do not use CSS gradients or REST gradientHandlePositions.`,
+      "set_content": '# text.set_content\nReplace text content on existing text nodes\n\nParams:\n    items (array, required) \u2014 Array of {nodeId, text}\n      nodeId (string, required) \u2014 Text node ID\n      text (string, required) \u2014 New text content\n    depth (number, optional) \u2014 Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.\n\nResponse:\n    { results: ("ok" | {error})[] }',
+      "scan": '# text.scan\nScan all text nodes within a subtree\n\nParams:\n    items ({ nodeId: string; limit?: number; includePath?: boolean; includeGeometry?: boolean }[], required) \u2014 Array of subtrees to scan\n\nResponse:\n    { results: ("ok" | {error} | object)[] }'
     }
   },
   "variable_collections": {
-    "summary": '# variable_collections\nCRUD for variable collections \u2014 the document-level API for design tokens.\n\nMethods:\n  list                 List variable collections [read]\n  get                  Get collection with all variables and values (full document) [read]\n  create               Create a collection with modes and variables in one call [create]\n  update               Rename collections [edit]\n  delete               Delete collections [edit]\n  add_mode             Add a mode to a collection [create]\n  rename_mode          Rename a mode [edit]\n  remove_mode          Remove a mode from a collection [edit]\n\n// Variable collections group design tokens and define their modes (e.g. Light/Dark, Desktop/Mobile).\n// All ID params accept both IDs and display names.\n// ---\n// valuesByMode: values keyed by mode name, e.g. {"Light": "#FFF", "Dark": "#111"}.\n// Aliases: {type: "VARIABLE_ALIAS", name: "other/variable"}.\n// scopes: see variables endpoint for full list.\n// Deleting a collection deletes all variables inside it.\n// The default mode cannot be removed. Use add_mode/remove_mode for additional modes.\n\nUse variable_collections(method: "help", topic: "<method>") for method details.',
+    "summary": '# variable_collections\nCRUD for variable collections \u2014 the document-level API for design tokens.\n\nMethods:\n  list                 List variable collections [read]\n  get                  Get collection with all variables and values (full document) [read]\n  create               Create a collection with modes and variables in one call [create]\n  update               Rename collections [edit]\n  delete               Delete collections [edit]\n  add_mode             Add a mode to a collection [create]\n  rename_mode          Rename a mode [edit]\n  remove_mode          Remove a mode from a collection [edit]\n\n// Variable collections group design tokens and define their modes (e.g. Light/Dark, Desktop/Mobile).\n// All ID params accept both IDs and display names.\n// ---\n// valuesByMode: values keyed by mode name, e.g. {"Light": "#FFF", "Dark": "#111"}.\n// Aliases in variable values use {type: "VARIABLE_ALIAS", name: "other/variable"}.\n// Paint[] VariableAlias uses {type:"VARIABLE_ALIAS", id:"<VariableID>"}; variable_collections.get includes each variable id. Prefer *VariableName helpers when available.\n// scopes: see variables endpoint for full list.\n// Deleting a collection deletes all variables inside it.\n// The default mode cannot be removed. Use add_mode/remove_mode for additional modes.\n\nUse variable_collections(method: "help", topic: "<method>") for method details.\n// Shared types:\n// Color: hex "#RGB"|"#RGBA"|"#RRGGBB"|"#RRGGBBAA" or {r: 0-1, g: 0-1, b: 0-1, a?: 0-1}\n// VariableAlias: {type: "VARIABLE_ALIAS", id: string}. The id must be a Figma VariableID; discover it via variables.get/list or variable_collections.get. Prefer colorVariableName/fillVariableName/strokeVariableName when available; Paint[] VariableAlias is mainly for precise Paint[] round-trips and gradient stop bindings.\n// Transform: [[number, number, number], [number, number, number]] (Figma Plugin API 2\xD73 matrix)\n// BlendMode: "PASS_THROUGH"|"NORMAL"|"DARKEN"|"MULTIPLY"|"LINEAR_BURN"|"COLOR_BURN"|"LIGHTEN"|"SCREEN"|"LINEAR_DODGE"|"COLOR_DODGE"|"OVERLAY"|"SOFT_LIGHT"|"HARD_LIGHT"|"DIFFERENCE"|"EXCLUSION"|"HUE"|"SATURATION"|"COLOR"|"LUMINOSITY"\n// ColorStop: {position: 0-1, color: Color, boundVariables?: {color?: VariableAlias}}\n// GradientPaint: {type: "GRADIENT_LINEAR"|"GRADIENT_RADIAL"|"GRADIENT_ANGULAR"|"GRADIENT_DIAMOND", gradientTransform: Transform, gradientStops: ColorStop[], visible?: boolean, opacity?: number, blendMode?: BlendMode}. Use gradientTransform + gradientStops (basic left-to-right: [[1,0,0],[0,1,0]]); do not use CSS gradients or REST gradientHandlePositions.\n// Paint: Paint[] authoring accepts only SOLID and GRADIENT_LINEAR/GRADIENT_RADIAL/GRADIENT_ANGULAR/GRADIENT_DIAMOND. SolidPaint: {type: "SOLID", color: Color, visible?: boolean, opacity?: number, blendMode?: BlendMode, boundVariables?: {color?: VariableAlias}}. GradientPaint authoring: {type: GRADIENT_*, gradientTransform: Transform, gradientStops: ColorStop[], visible?, opacity?, blendMode?}; bind variables on gradientStops[].boundVariables.color, not top-level gradient boundVariables. Do not pass IMAGE/VIDEO/PATTERN to create/update Paint[]; those may appear only in readback metadata from existing Figma content. Use imageUrl/images for image authoring. VIDEO/PATTERN authoring is not supported here. Do not use CSS gradients or REST gradientHandlePositions.',
     "methods": {
-      "list": '# variable_collections.list\nList variable collections\n\nParams:\n    fields (string[], optional) \u2014 Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.\n    offset (number, optional) \u2014 Skip N items for pagination (default 0)\n    limit (number, optional) \u2014 Max items per page (default 100)',
-      "get": '# variable_collections.get\nGet collection with all variables and values (full document)\n\nParams:\n    id (string, required) \u2014 Collection ID or name\n    fields (string[], optional) \u2014 Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.',
+      "list": '# variable_collections.list\nList variable collections\n\nParams:\n    fields (string[], optional) \u2014 Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.\n    offset (number, optional) \u2014 Skip N items for pagination (default 0)\n    limit (number, optional) \u2014 Max items per page (default 100)\n\nResponse:\n    totalCount (number, required)\n    returned (number, optional)\n    offset (number, optional)\n    limit (number, optional)\n    items (array, required)\n      id (string, required)\n      name (string, required)\n      modes (string[], optional) \u2014 Mode names\n      variableCount (number, optional) \u2014 Number of variables',
+      "get": `# variable_collections.get
+Get collection with all variables and values (full document)
+
+Params:
+    id (string, required) \u2014 Collection ID or name
+    fields (string[], optional) \u2014 Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.
+
+Response:
+    id (string, required)
+    name (string, required)
+    modes (string[], required) \u2014 Mode names (e.g. ['Light', 'Dark'])
+    variables (array, required) \u2014 All variables in this collection
+      id (string, required) \u2014 Figma VariableID. Use as VariableAlias.id in Paint[] when needed.
+      name (string, required)
+      type (string, required) \u2014 COLOR | FLOAT | STRING | BOOLEAN
+      valuesByMode (object, required) \u2014 Values keyed by mode name
+      scopes (string[], optional)
+      description (string, optional)
+// Shared types:
+// Color: hex "#RGB"|"#RGBA"|"#RRGGBB"|"#RRGGBBAA" or {r: 0-1, g: 0-1, b: 0-1, a?: 0-1}
+// VariableAlias: {type: "VARIABLE_ALIAS", id: string}. The id must be a Figma VariableID; discover it via variables.get/list or variable_collections.get. Prefer colorVariableName/fillVariableName/strokeVariableName when available; Paint[] VariableAlias is mainly for precise Paint[] round-trips and gradient stop bindings.
+// Transform: [[number, number, number], [number, number, number]] (Figma Plugin API 2\xD73 matrix)
+// BlendMode: "PASS_THROUGH"|"NORMAL"|"DARKEN"|"MULTIPLY"|"LINEAR_BURN"|"COLOR_BURN"|"LIGHTEN"|"SCREEN"|"LINEAR_DODGE"|"COLOR_DODGE"|"OVERLAY"|"SOFT_LIGHT"|"HARD_LIGHT"|"DIFFERENCE"|"EXCLUSION"|"HUE"|"SATURATION"|"COLOR"|"LUMINOSITY"
+// ColorStop: {position: 0-1, color: Color, boundVariables?: {color?: VariableAlias}}
+// GradientPaint: {type: "GRADIENT_LINEAR"|"GRADIENT_RADIAL"|"GRADIENT_ANGULAR"|"GRADIENT_DIAMOND", gradientTransform: Transform, gradientStops: ColorStop[], visible?: boolean, opacity?: number, blendMode?: BlendMode}. Use gradientTransform + gradientStops (basic left-to-right: [[1,0,0],[0,1,0]]); do not use CSS gradients or REST gradientHandlePositions.
+// Paint: Paint[] authoring accepts only SOLID and GRADIENT_LINEAR/GRADIENT_RADIAL/GRADIENT_ANGULAR/GRADIENT_DIAMOND. SolidPaint: {type: "SOLID", color: Color, visible?: boolean, opacity?: number, blendMode?: BlendMode, boundVariables?: {color?: VariableAlias}}. GradientPaint authoring: {type: GRADIENT_*, gradientTransform: Transform, gradientStops: ColorStop[], visible?, opacity?, blendMode?}; bind variables on gradientStops[].boundVariables.color, not top-level gradient boundVariables. Do not pass IMAGE/VIDEO/PATTERN to create/update Paint[]; those may appear only in readback metadata from existing Figma content. Use imageUrl/images for image authoring. VIDEO/PATTERN authoring is not supported here. Do not use CSS gradients or REST gradientHandlePositions.`,
       "create": `# variable_collections.create
 Create a collection with modes and variables in one call
 
-Example: variable_collections(method:"create", items:[{name:"Tokens", modes:["Light","Dark"], variables:[{name:"bg/primary", type:"COLOR", valuesByMode:{"Light":"#FFF","Dark":"#111"}, scopes:["ALL_FILLS"]}, {name:"text/primary", type:"COLOR", valuesByMode:{"Light":"#111","Dark":"#F0F0F0"}, scopes:["TEXT_FILL"]}, {name:"space/16", type:"FLOAT", value:16, scopes:["GAP","WIDTH_HEIGHT"]}, {name:"radius/8", type:"FLOAT", value:8, scopes:["CORNER_RADIUS"]}]}])
+Example: variable_collections(method:"create", items:[{name:"Tokens", variables:[{name:"bg/canvas", type:"COLOR", value:"#F7F8FA", scopes:["ALL_FILLS"]}, {name:"bg/surface", type:"COLOR", value:"#FFFFFF", scopes:["ALL_FILLS"]}, {name:"bg/accent", type:"COLOR", value:"#2563EB", scopes:["ALL_FILLS"]}, {name:"bg/muted", type:"COLOR", value:"#E5E7EB", scopes:["ALL_FILLS"]}, {name:"text/primary", type:"COLOR", value:"#111827", scopes:["TEXT_FILL"]}, {name:"text/secondary", type:"COLOR", value:"#4B5563", scopes:["TEXT_FILL"]}, {name:"text/inverse", type:"COLOR", value:"#FFFFFF", scopes:["TEXT_FILL"]}, {name:"border/subtle", type:"COLOR", value:"#D1D5DB", scopes:["STROKE_COLOR"]}, {name:"icon/primary", type:"COLOR", value:{type:"VARIABLE_ALIAS", name:"text/primary"}, scopes:["ALL_FILLS","STROKE_COLOR"]}, {name:"status/success", type:"COLOR", value:"#16A34A", scopes:["ALL_FILLS"]}, {name:"space/8", type:"FLOAT", value:8, scopes:["GAP"]}, {name:"space/12", type:"FLOAT", value:12, scopes:["GAP"]}, {name:"space/16", type:"FLOAT", value:16, scopes:["GAP"]}, {name:"space/24", type:"FLOAT", value:24, scopes:["GAP"]}, {name:"radius/8", type:"FLOAT", value:8, scopes:["CORNER_RADIUS"]}, {name:"radius/12", type:"FLOAT", value:12, scopes:["CORNER_RADIUS"]}, {name:"radius/16", type:"FLOAT", value:16, scopes:["CORNER_RADIUS"]}, {name:"stroke/1", type:"FLOAT", value:1, scopes:["STROKE_FLOAT"]}]}])
 
 Params:
     items (array, required) \u2014 Array of collection documents
@@ -1174,22 +1472,25 @@ Params:
         value (variable_value, optional) \u2014 Sets all modes to this value. Use valuesByMode for per-mode control.
         valuesByMode (object, optional) \u2014 Values keyed by mode name (e.g. {"Light": "#FFF", "Dark": "#111"})
         description (string, optional)
-        scopes (string[], optional) \u2014 Restrict where variable can be applied (default: ALL_SCOPES)`,
-      "update": "# variable_collections.update\nRename collections\n\nParams:\n    items (array, required) \u2014 Array of {id, name}\n      id (string, required) \u2014 Collection ID or name\n      name (string, required) \u2014 New name",
-      "delete": "# variable_collections.delete\nDelete collections\n\nParams:\n    id (string, optional) \u2014 Collection ID or name\n    items (array, optional) \u2014 Batch: [{id}, ...]\n      id (string, required)",
-      "add_mode": "# variable_collections.add_mode\nAdd a mode to a collection\n\nParams:\n    items (array, required) \u2014 Array of {collectionId, name}\n      collectionId (string, required) \u2014 Collection ID or name\n      name (string, required) \u2014 Mode name",
-      "rename_mode": '# variable_collections.rename_mode\nRename a mode\n\nParams:\n    items (array, required) \u2014 Array of {collectionId, modeId, name}\n      collectionId (string, required) \u2014 Collection ID or name\n      modeId (string, required) \u2014 Mode ID or name (e.g. "Dark")\n      name (string, required) \u2014 New name',
-      "remove_mode": '# variable_collections.remove_mode\nRemove a mode from a collection\n\nParams:\n    items (array, required) \u2014 Array of {collectionId, modeId}\n      collectionId (string, required) \u2014 Collection ID or name\n      modeId (string, required) \u2014 Mode ID or name (e.g. "Dark")'
+        scopes (string[], optional) \u2014 Restrict where variable can be applied (default: ALL_SCOPES)
+
+Response:
+    { results: ({id} | {error})[] }`,
+      "update": '# variable_collections.update\nRename collections\n\nParams:\n    items (array, required) \u2014 Array of {id, name}\n      id (string, required) \u2014 Collection ID or name\n      name (string, required) \u2014 New name\n\nResponse:\n    { results: ("ok" | {error} | object)[] }',
+      "delete": '# variable_collections.delete\nDelete collections\n\nParams:\n    id (string, optional) \u2014 Collection ID or name\n    items (array, optional) \u2014 Batch: [{id}, ...]\n      id (string, required)\n\nResponse:\n    { results: ("ok" | {error})[] }',
+      "add_mode": "# variable_collections.add_mode\nAdd a mode to a collection\n\nParams:\n    items (array, required) \u2014 Array of {collectionId, name}\n      collectionId (string, required) \u2014 Collection ID or name\n      name (string, required) \u2014 Mode name\n\nResponse:\n    { results: ({id} | {error})[] }",
+      "rename_mode": '# variable_collections.rename_mode\nRename a mode\n\nParams:\n    items (array, required) \u2014 Array of {collectionId, modeId, name}\n      collectionId (string, required) \u2014 Collection ID or name\n      modeId (string, required) \u2014 Mode ID or name (e.g. "Dark")\n      name (string, required) \u2014 New name\n\nResponse:\n    { results: ("ok" | {error} | object)[] }',
+      "remove_mode": '# variable_collections.remove_mode\nRemove a mode from a collection\n\nParams:\n    items (array, required) \u2014 Array of {collectionId, modeId}\n      collectionId (string, required) \u2014 Collection ID or name\n      modeId (string, required) \u2014 Mode ID or name (e.g. "Dark")\n\nResponse:\n    { results: ("ok" | {error})[] }'
     }
   },
   "variables": {
-    "summary": '# variables\nSearch and update design variables within a collection.\n\nMethods:\n  list                 Search variables within a collection [read]\n  get                  Get variable detail by name [read]\n  create               Create variables in a collection. Use valuesByMode for per-mode control, or value to set all modes at once. [create]\n  update               Update variable metadata and/or set values [edit]\n  delete               Delete variables [edit]\n\n// Search and update variables within a collection. collectionId is required on all methods.\n// Use variable_collections to create full token sets (collection + modes + variables in one call).\n// ---\n// query: prefix match first, then substring. "bg/" matches bg/canvas, bg/surface, etc.\n// valuesByMode: values keyed by mode name. On create, value sets all modes; on update, value sets the default mode only.\n// Aliases: {type: "VARIABLE_ALIAS", name: "other/variable"}.\n// scopes: ALL_SCOPES, TEXT_CONTENT, WIDTH_HEIGHT, GAP, CORNER_RADIUS, ALL_FILLS, FRAME_FILL, SHAPE_FILL,\n//   TEXT_FILL, STROKE_COLOR, STROKE_FLOAT, EFFECT_FLOAT, EFFECT_COLOR, OPACITY, FONT_FAMILY, FONT_STYLE,\n//   FONT_WEIGHT, FONT_SIZE, LINE_HEIGHT, LETTER_SPACING, PARAGRAPH_SPACING, PARAGRAPH_INDENT\n\nUse variables(method: "help", topic: "<method>") for method details.',
+    "summary": '# variables\nSearch and update design variables within a collection.\n\nMethods:\n  list                 Search variables within a collection [read]\n  get                  Get variable detail by name [read]\n  create               Create variables in a collection. Use valuesByMode for per-mode control, or value to set all modes at once. [create]\n  update               Update variable metadata and/or set values [edit]\n  delete               Delete variables [edit]\n\n// Search and update variables within a collection. collectionId is required on all methods.\n// Use variable_collections to create full token sets (collection + modes + variables in one call).\n// ---\n// query: prefix match first, then substring. "bg/" matches bg/canvas, bg/surface, etc.\n// valuesByMode: values keyed by mode name. On create, value sets all modes; on update, value sets the default mode only.\n// Aliases in variable values use {type: "VARIABLE_ALIAS", name: "other/variable"}.\n// Paint[] VariableAlias uses {type:"VARIABLE_ALIAS", id:"<VariableID>"}; get IDs from variables.get/list or variable_collections.get. Prefer *VariableName helpers when available.\n// scopes: ALL_SCOPES, TEXT_CONTENT, WIDTH_HEIGHT, GAP, CORNER_RADIUS, ALL_FILLS, FRAME_FILL, SHAPE_FILL,\n//   TEXT_FILL, STROKE_COLOR, STROKE_FLOAT, EFFECT_FLOAT, EFFECT_COLOR, OPACITY, FONT_FAMILY, FONT_STYLE,\n//   FONT_WEIGHT, FONT_SIZE, LINE_HEIGHT, LETTER_SPACING, PARAGRAPH_SPACING, PARAGRAPH_INDENT\n\nUse variables(method: "help", topic: "<method>") for method details.\n// Shared types:\n// Color: hex "#RGB"|"#RGBA"|"#RRGGBB"|"#RRGGBBAA" or {r: 0-1, g: 0-1, b: 0-1, a?: 0-1}\n// VariableAlias: {type: "VARIABLE_ALIAS", id: string}. The id must be a Figma VariableID; discover it via variables.get/list or variable_collections.get. Prefer colorVariableName/fillVariableName/strokeVariableName when available; Paint[] VariableAlias is mainly for precise Paint[] round-trips and gradient stop bindings.\n// Transform: [[number, number, number], [number, number, number]] (Figma Plugin API 2\xD73 matrix)\n// BlendMode: "PASS_THROUGH"|"NORMAL"|"DARKEN"|"MULTIPLY"|"LINEAR_BURN"|"COLOR_BURN"|"LIGHTEN"|"SCREEN"|"LINEAR_DODGE"|"COLOR_DODGE"|"OVERLAY"|"SOFT_LIGHT"|"HARD_LIGHT"|"DIFFERENCE"|"EXCLUSION"|"HUE"|"SATURATION"|"COLOR"|"LUMINOSITY"\n// ColorStop: {position: 0-1, color: Color, boundVariables?: {color?: VariableAlias}}\n// GradientPaint: {type: "GRADIENT_LINEAR"|"GRADIENT_RADIAL"|"GRADIENT_ANGULAR"|"GRADIENT_DIAMOND", gradientTransform: Transform, gradientStops: ColorStop[], visible?: boolean, opacity?: number, blendMode?: BlendMode}. Use gradientTransform + gradientStops (basic left-to-right: [[1,0,0],[0,1,0]]); do not use CSS gradients or REST gradientHandlePositions.\n// Paint: Paint[] authoring accepts only SOLID and GRADIENT_LINEAR/GRADIENT_RADIAL/GRADIENT_ANGULAR/GRADIENT_DIAMOND. SolidPaint: {type: "SOLID", color: Color, visible?: boolean, opacity?: number, blendMode?: BlendMode, boundVariables?: {color?: VariableAlias}}. GradientPaint authoring: {type: GRADIENT_*, gradientTransform: Transform, gradientStops: ColorStop[], visible?, opacity?, blendMode?}; bind variables on gradientStops[].boundVariables.color, not top-level gradient boundVariables. Do not pass IMAGE/VIDEO/PATTERN to create/update Paint[]; those may appear only in readback metadata from existing Figma content. Use imageUrl/images for image authoring. VIDEO/PATTERN authoring is not supported here. Do not use CSS gradients or REST gradientHandlePositions.',
     "methods": {
-      "list": '# variables.list\nSearch variables within a collection\n\nExample: variables(method:"list", collectionId:"Colors", query:"bg/")\n\nParams:\n    collectionId (string, required) \u2014 Collection ID or name\n    query (string, optional) \u2014 Search query \u2014 prefix match first, then substring fallback\n    type (COLOR | FLOAT | STRING | BOOLEAN, optional) \u2014 Filter by variable type\n    fields (string[], optional) \u2014 Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.\n    offset (number, optional) \u2014 Skip N items for pagination (default 0)\n    limit (number, optional) \u2014 Max items per page (default 100)',
-      "get": '# variables.get\nGet variable detail by name\n\nParams:\n    name (string, required) \u2014 Variable name (unique within collection)\n    collectionId (string, required) \u2014 Collection ID or name\n    fields (string[], optional) \u2014 Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.',
-      "create": '# variables.create\nCreate variables in a collection. Use valuesByMode for per-mode control, or value to set all modes at once.\n\nExample: variables(method:"create", collectionId:"Colors", items:[{name:"bg/primary", type:"COLOR", valuesByMode:{"Light":"#FFF","Dark":"#111"}, scopes:["ALL_FILLS"]}])\n\nParams:\n    collectionId (string, required) \u2014 Collection ID or name\n    items (VariableCreateItem[], required) \u2014 Array of variables to create\n      name (string, required) \u2014 Variable name (must be unique within collection)\n      type (COLOR | FLOAT | STRING | BOOLEAN, required) \u2014 Variable type\n      value (variable_value, optional) \u2014 Sets all modes to this value. Use valuesByMode for per-mode control.\n      valuesByMode (object, optional) \u2014 Values keyed by mode name (e.g. {"Light": "#FFF", "Dark": "#111"}). Takes precedence over value.\n      description (string, optional) \u2014 Variable description\n      scopes (string[], optional) \u2014 Restrict where variable can be applied (default: ALL_SCOPES)',
-      "update": '# variables.update\nUpdate variable metadata and/or set values\n\nExample: variables(method:"update", collectionId:"Colors", items:[{name:"bg/primary", valuesByMode:{"Light":"#FFF","Dark":"#222"}}])\n\nParams:\n    collectionId (string, required) \u2014 Collection ID or name\n    items (VariableUpdateItem[], required) \u2014 Array of variable updates\n      name (string, required) \u2014 Variable name\n      rename (string, optional) \u2014 Rename the variable\n      description (string, optional) \u2014 Set description\n      scopes (string[], optional) \u2014 Update scopes\n      value (variable_value, optional) \u2014 Shorthand \u2014 sets the default mode value. Use valuesByMode for multi-mode.\n      valuesByMode (object, optional) \u2014 Values keyed by mode name. Takes precedence over value.',
-      "delete": "# variables.delete\nDelete variables\n\nParams:\n    collectionId (string, required) \u2014 Collection ID or name\n    name (string, optional) \u2014 Variable name\n    items (array, optional) \u2014 Batch: [{name}, ...]\n      name (string, required)"
+      "list": '# variables.list\nSearch variables within a collection\n\nExample: variables(method:"list", collectionId:"Tokens", query:"bg/")\n\nParams:\n    collectionId (string, required) \u2014 Collection ID or name\n    query (string, optional) \u2014 Search query \u2014 prefix match first, then substring fallback\n    type (COLOR | FLOAT | STRING | BOOLEAN, optional) \u2014 Filter by variable type\n    fields (string[], optional) \u2014 Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.\n    offset (number, optional) \u2014 Skip N items for pagination (default 0)\n    limit (number, optional) \u2014 Max items per page (default 100)\n\nResponse:\n    totalCount (number, required)\n    returned (number, optional)\n    offset (number, optional)\n    limit (number, optional)\n    items (array, required)\n      id (string, required) \u2014 Figma VariableID. Use as VariableAlias.id in Paint[] when needed.\n      name (string, required)\n      type (string, optional) \u2014 COLOR | FLOAT | STRING | BOOLEAN\n      valuesByMode (object, optional) \u2014 Values keyed by mode name\n      scopes (string[], optional)\n      description (string, optional)\n// Shared types:\n// Color: hex "#RGB"|"#RGBA"|"#RRGGBB"|"#RRGGBBAA" or {r: 0-1, g: 0-1, b: 0-1, a?: 0-1}\n// VariableAlias: {type: "VARIABLE_ALIAS", id: string}. The id must be a Figma VariableID; discover it via variables.get/list or variable_collections.get. Prefer colorVariableName/fillVariableName/strokeVariableName when available; Paint[] VariableAlias is mainly for precise Paint[] round-trips and gradient stop bindings.\n// Transform: [[number, number, number], [number, number, number]] (Figma Plugin API 2\xD73 matrix)\n// BlendMode: "PASS_THROUGH"|"NORMAL"|"DARKEN"|"MULTIPLY"|"LINEAR_BURN"|"COLOR_BURN"|"LIGHTEN"|"SCREEN"|"LINEAR_DODGE"|"COLOR_DODGE"|"OVERLAY"|"SOFT_LIGHT"|"HARD_LIGHT"|"DIFFERENCE"|"EXCLUSION"|"HUE"|"SATURATION"|"COLOR"|"LUMINOSITY"\n// ColorStop: {position: 0-1, color: Color, boundVariables?: {color?: VariableAlias}}\n// GradientPaint: {type: "GRADIENT_LINEAR"|"GRADIENT_RADIAL"|"GRADIENT_ANGULAR"|"GRADIENT_DIAMOND", gradientTransform: Transform, gradientStops: ColorStop[], visible?: boolean, opacity?: number, blendMode?: BlendMode}. Use gradientTransform + gradientStops (basic left-to-right: [[1,0,0],[0,1,0]]); do not use CSS gradients or REST gradientHandlePositions.\n// Paint: Paint[] authoring accepts only SOLID and GRADIENT_LINEAR/GRADIENT_RADIAL/GRADIENT_ANGULAR/GRADIENT_DIAMOND. SolidPaint: {type: "SOLID", color: Color, visible?: boolean, opacity?: number, blendMode?: BlendMode, boundVariables?: {color?: VariableAlias}}. GradientPaint authoring: {type: GRADIENT_*, gradientTransform: Transform, gradientStops: ColorStop[], visible?, opacity?, blendMode?}; bind variables on gradientStops[].boundVariables.color, not top-level gradient boundVariables. Do not pass IMAGE/VIDEO/PATTERN to create/update Paint[]; those may appear only in readback metadata from existing Figma content. Use imageUrl/images for image authoring. VIDEO/PATTERN authoring is not supported here. Do not use CSS gradients or REST gradientHandlePositions.',
+      "get": '# variables.get\nGet variable detail by name\n\nParams:\n    name (string, required) \u2014 Variable name (unique within collection)\n    collectionId (string, required) \u2014 Collection ID or name\n    fields (string[], optional) \u2014 Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.\n\nResponse:\n    id (string, required) \u2014 Figma VariableID. Use as VariableAlias.id in Paint[] when needed.\n    name (string, required)\n    type (COLOR | FLOAT | STRING | BOOLEAN, required)\n    collectionId (string, required) \u2014 Collection display name\n    valuesByMode (Record<string, number | boolean | string | Color | {type: "VARIABLE_ALIAS", name: string}>, required) \u2014 Values keyed by mode name (e.g. "Light", "Dark")\n    description (string, optional) \u2014 Variable description\n    scopes (string[], optional) \u2014 Where this variable can be applied\n// Shared types:\n// Color: hex "#RGB"|"#RGBA"|"#RRGGBB"|"#RRGGBBAA" or {r: 0-1, g: 0-1, b: 0-1, a?: 0-1}\n// VariableAlias: {type: "VARIABLE_ALIAS", id: string}. The id must be a Figma VariableID; discover it via variables.get/list or variable_collections.get. Prefer colorVariableName/fillVariableName/strokeVariableName when available; Paint[] VariableAlias is mainly for precise Paint[] round-trips and gradient stop bindings.\n// Transform: [[number, number, number], [number, number, number]] (Figma Plugin API 2\xD73 matrix)\n// BlendMode: "PASS_THROUGH"|"NORMAL"|"DARKEN"|"MULTIPLY"|"LINEAR_BURN"|"COLOR_BURN"|"LIGHTEN"|"SCREEN"|"LINEAR_DODGE"|"COLOR_DODGE"|"OVERLAY"|"SOFT_LIGHT"|"HARD_LIGHT"|"DIFFERENCE"|"EXCLUSION"|"HUE"|"SATURATION"|"COLOR"|"LUMINOSITY"\n// ColorStop: {position: 0-1, color: Color, boundVariables?: {color?: VariableAlias}}\n// GradientPaint: {type: "GRADIENT_LINEAR"|"GRADIENT_RADIAL"|"GRADIENT_ANGULAR"|"GRADIENT_DIAMOND", gradientTransform: Transform, gradientStops: ColorStop[], visible?: boolean, opacity?: number, blendMode?: BlendMode}. Use gradientTransform + gradientStops (basic left-to-right: [[1,0,0],[0,1,0]]); do not use CSS gradients or REST gradientHandlePositions.\n// Paint: Paint[] authoring accepts only SOLID and GRADIENT_LINEAR/GRADIENT_RADIAL/GRADIENT_ANGULAR/GRADIENT_DIAMOND. SolidPaint: {type: "SOLID", color: Color, visible?: boolean, opacity?: number, blendMode?: BlendMode, boundVariables?: {color?: VariableAlias}}. GradientPaint authoring: {type: GRADIENT_*, gradientTransform: Transform, gradientStops: ColorStop[], visible?, opacity?, blendMode?}; bind variables on gradientStops[].boundVariables.color, not top-level gradient boundVariables. Do not pass IMAGE/VIDEO/PATTERN to create/update Paint[]; those may appear only in readback metadata from existing Figma content. Use imageUrl/images for image authoring. VIDEO/PATTERN authoring is not supported here. Do not use CSS gradients or REST gradientHandlePositions.',
+      "create": '# variables.create\nCreate variables in a collection. Use valuesByMode for per-mode control, or value to set all modes at once.\n\nExample: variables(method:"create", collectionId:"Tokens", items:[{name:"bg/warning", type:"COLOR", value:"#F59E0B", scopes:["ALL_FILLS"]}])\n\nParams:\n    collectionId (string, required) \u2014 Collection ID or name\n    items (VariableCreateItem[], required) \u2014 Array of variables to create\n      name (string, required) \u2014 Variable name (must be unique within collection)\n      type (COLOR | FLOAT | STRING | BOOLEAN, required) \u2014 Variable type\n      value (variable_value, optional) \u2014 Sets all modes to this value. Use valuesByMode for per-mode control.\n      valuesByMode (object, optional) \u2014 Values keyed by mode name (e.g. {"Light": "#FFF", "Dark": "#111"}). Takes precedence over value.\n      description (string, optional) \u2014 Variable description\n      scopes (string[], optional) \u2014 Restrict where variable can be applied (default: ALL_SCOPES)\n\nResponse:\n    { results: ({id} | {error})[] }',
+      "update": '# variables.update\nUpdate variable metadata and/or set values\n\nExample: variables(method:"update", collectionId:"Tokens", items:[{name:"bg/accent", value:"#1D4ED8"}])\n\nParams:\n    collectionId (string, required) \u2014 Collection ID or name\n    items (VariableUpdateItem[], required) \u2014 Array of variable updates\n      name (string, required) \u2014 Variable name\n      rename (string, optional) \u2014 Rename the variable\n      description (string, optional) \u2014 Set description\n      scopes (string[], optional) \u2014 Update scopes\n      value (variable_value, optional) \u2014 Shorthand \u2014 sets the default mode value. Use valuesByMode for multi-mode.\n      valuesByMode (object, optional) \u2014 Values keyed by mode name. Takes precedence over value.\n\nResponse:\n    { results: ("ok" | {error} | object)[] }',
+      "delete": '# variables.delete\nDelete variables\n\nParams:\n    collectionId (string, required) \u2014 Collection ID or name\n    name (string, optional) \u2014 Variable name\n    items (array, optional) \u2014 Batch: [{name}, ...]\n      name (string, required)\n\nResponse:\n    { results: ("ok" | {error})[] }'
     }
   },
   "version_history": {
@@ -1210,7 +1511,10 @@ Save a named version to the file's version history
 
 Params:
     title (string, required) \u2014 Version title (e.g., "Added hero sections with website copy")
-    description (string, optional) \u2014 Optional longer description of what changed`
+    description (string, optional) \u2014 Optional longer description of what changed
+
+Response:
+    id (string, required) \u2014 Version ID returned by Figma`
     }
   }
 };
@@ -1361,6 +1665,113 @@ var colorRgba = z2.preprocess((v) => {
   z2.string()
   // Non-hex strings pass through for handler-level style/variable resolution
 ])).describe('Hex "#FF0000", {r,g,b,a?} 0-1, or style/variable name.');
+var variableAlias = z2.object({
+  type: z2.literal("VARIABLE_ALIAS"),
+  id: z2.string()
+}).strict().describe('{type:"VARIABLE_ALIAS", id:string}. Discover VariableIDs via variables.get/list or variable_collections.get; prefer *VariableName helpers when available.');
+var transform = z2.tuple([
+  z2.tuple([z2.coerce.number(), z2.coerce.number(), z2.coerce.number()]),
+  z2.tuple([z2.coerce.number(), z2.coerce.number(), z2.coerce.number()])
+]).describe("Figma Plugin API Transform: [[number,number,number],[number,number,number]]");
+var blendMode = z2.enum([
+  "PASS_THROUGH",
+  "NORMAL",
+  "DARKEN",
+  "MULTIPLY",
+  "LINEAR_BURN",
+  "COLOR_BURN",
+  "LIGHTEN",
+  "SCREEN",
+  "LINEAR_DODGE",
+  "COLOR_DODGE",
+  "OVERLAY",
+  "SOFT_LIGHT",
+  "HARD_LIGHT",
+  "DIFFERENCE",
+  "EXCLUSION",
+  "HUE",
+  "SATURATION",
+  "COLOR",
+  "LUMINOSITY"
+]);
+var paintColor = z2.preprocess((v) => {
+  if (typeof v === "string") return parseHex(v) ?? v;
+  return v;
+}, z2.object({
+  r: z2.coerce.number().min(0).max(1),
+  g: z2.coerce.number().min(0).max(1),
+  b: z2.coerce.number().min(0).max(1),
+  a: z2.coerce.number().min(0).max(1).optional()
+}).strict()).describe('Paint color: hex "#FF0000"/"#FF000080" or {r,g,b,a?} 0-1. Non-hex strings are not valid inside Paint[].');
+var paintBoundVariables = z2.object({
+  color: variableAlias.optional()
+}).strict();
+var commonPaintFields = {
+  visible: flexBool(z2.boolean()).optional(),
+  opacity: z2.coerce.number().min(0).max(1).optional(),
+  blendMode: blendMode.optional()
+};
+var colorStop = z2.object({
+  position: z2.coerce.number().min(0).max(1),
+  color: paintColor,
+  boundVariables: paintBoundVariables.optional()
+}).strict().describe("ColorStop: {position:0..1, color: Color, boundVariables?: {color: VariableAlias}}");
+var solidPaint = z2.object({
+  type: z2.literal("SOLID"),
+  color: paintColor,
+  boundVariables: paintBoundVariables.optional(),
+  ...commonPaintFields
+}).strict();
+var gradientPaint = z2.object({
+  type: z2.enum(["GRADIENT_LINEAR", "GRADIENT_RADIAL", "GRADIENT_ANGULAR", "GRADIENT_DIAMOND"]),
+  gradientTransform: transform,
+  gradientStops: z2.array(colorStop),
+  ...commonPaintFields
+}).strict().describe("GradientPaint: use gradientTransform + gradientStops. Do not use REST gradientHandlePositions.");
+var imageFilters = z2.object({
+  exposure: z2.coerce.number().optional(),
+  contrast: z2.coerce.number().optional(),
+  saturation: z2.coerce.number().optional(),
+  temperature: z2.coerce.number().optional(),
+  tint: z2.coerce.number().optional(),
+  highlights: z2.coerce.number().optional(),
+  shadows: z2.coerce.number().optional()
+}).strict();
+var imagePaint = z2.object({
+  type: z2.literal("IMAGE"),
+  scaleMode: z2.enum(["FILL", "FIT", "CROP", "TILE"]),
+  imageHash: z2.string().nullable(),
+  imageTransform: transform.optional(),
+  scalingFactor: z2.coerce.number().optional(),
+  rotation: z2.coerce.number().optional(),
+  filters: imageFilters.optional(),
+  ...commonPaintFields
+}).strict();
+var videoPaint = z2.object({
+  type: z2.literal("VIDEO"),
+  scaleMode: z2.enum(["FILL", "FIT", "CROP", "TILE"]),
+  videoHash: z2.string().nullable(),
+  videoTransform: transform.optional(),
+  scalingFactor: z2.coerce.number().optional(),
+  rotation: z2.coerce.number().optional(),
+  filters: imageFilters.optional(),
+  ...commonPaintFields
+}).strict();
+var patternPaint = z2.object({
+  type: z2.literal("PATTERN"),
+  sourceNodeId: z2.string(),
+  tileType: z2.enum(["RECTANGULAR", "HORIZONTAL_HEXAGONAL", "VERTICAL_HEXAGONAL"]),
+  scalingFactor: z2.coerce.number(),
+  spacing: z2.object({ x: z2.coerce.number(), y: z2.coerce.number() }).strict(),
+  horizontalAlignment: z2.enum(["START", "CENTER", "END"]),
+  ...commonPaintFields
+}).strict();
+var paintInput = z2.union([solidPaint, gradientPaint], {
+  error: "Invalid Paint[] payload. Supported Paint[] authoring types: SOLID, GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; do not use CSS gradients, REST gradientHandlePositions, IMAGE, VIDEO, or PATTERN."
+}).describe("Paint[] authoring input supports SOLID and Figma gradient paints only. Images use imageUrl/images endpoint; VIDEO and PATTERN authoring are not supported here.");
+var paint = paintInput.describe("Paint[] authoring input. Supports SOLID and gradients: GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; REST gradientHandlePositions is not accepted. IMAGE/VIDEO/PATTERN are readback-only metadata, not authoring input.");
+var paintArray = flexJson(z2.array(paintInput)).describe("Paint[] input array. Authoring accepts only SOLID and gradients: GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use imageUrl/images for images; VIDEO/PATTERN authoring is not supported here.");
+var paintArrayLoose = flexJson(z2.array(z2.unknown())).describe("Paint[] input array. Authoring accepts only SOLID and gradients. Adapter validates details and returns guidance; CSS gradients, REST gradientHandlePositions, IMAGE, VIDEO, and PATTERN are not supported as authoring input. Use imageUrl/images for images.");
 var variableValue = z2.preprocess((v) => {
   if (typeof v === "string") return parseHex(v) ?? v;
   return v;
@@ -1438,6 +1849,7 @@ var tools = [
         if (params.id === void 0) throw new Error('delete_category requires "id"');
       }
       if (!params.items) return;
+      if (Array.isArray(params.items) && params.items.length === 0) throw new Error('items: [] is a no-op. Batch calls need at least one item. Omit items to use single-item params, or pass one or more item objects. Use annotations(method: "help", topic: "' + m + '") to see valid item shapes.');
       if (m === "get") {
         const itemSchema = z3.object({
           id: z3.string(),
@@ -1450,8 +1862,11 @@ var tools = [
             throw new Error(e.issues.map((i) => {
               const path = i.path.join(".");
               const shape = itemSchema instanceof z3.ZodObject ? itemSchema.shape : null;
-              const desc = shape?.[i.path[1]]?.description;
-              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "");
+              const field = String(i.path[1] ?? i.path[0] ?? "");
+              const desc = shape?.[field]?.description;
+              const paintField = field === "paints" || field === "fills" || field === "strokes";
+              const paintHelp = paintField ? ' Invalid Paint[] payload. Supported Paint[] authoring types: SOLID, GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; do not use CSS gradients or REST gradientHandlePositions. IMAGE/VIDEO/PATTERN are readback-only metadata, not Paint[] authoring input; use imageUrl/images for images. For examples call annotations(method:"help", topic:"get").' : "";
+              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "") + paintHelp;
             }).join("; "));
           }
           throw e;
@@ -1469,8 +1884,11 @@ var tools = [
             throw new Error(e.issues.map((i) => {
               const path = i.path.join(".");
               const shape = itemSchema instanceof z3.ZodObject ? itemSchema.shape : null;
-              const desc = shape?.[i.path[1]]?.description;
-              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "");
+              const field = String(i.path[1] ?? i.path[0] ?? "");
+              const desc = shape?.[field]?.description;
+              const paintField = field === "paints" || field === "fills" || field === "strokes";
+              const paintHelp = paintField ? ' Invalid Paint[] payload. Supported Paint[] authoring types: SOLID, GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; do not use CSS gradients or REST gradientHandlePositions. IMAGE/VIDEO/PATTERN are readback-only metadata, not Paint[] authoring input; use imageUrl/images for images. For examples call annotations(method:"help", topic:"set").' : "";
+              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "") + paintHelp;
             }).join("; "));
           }
           throw e;
@@ -1491,8 +1909,11 @@ var tools = [
             throw new Error(e.issues.map((i) => {
               const path = i.path.join(".");
               const shape = itemSchema instanceof z3.ZodObject ? itemSchema.shape : null;
-              const desc = shape?.[i.path[1]]?.description;
-              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "");
+              const field = String(i.path[1] ?? i.path[0] ?? "");
+              const desc = shape?.[field]?.description;
+              const paintField = field === "paints" || field === "fills" || field === "strokes";
+              const paintHelp = paintField ? ' Invalid Paint[] payload. Supported Paint[] authoring types: SOLID, GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; do not use CSS gradients or REST gradientHandlePositions. IMAGE/VIDEO/PATTERN are readback-only metadata, not Paint[] authoring input; use imageUrl/images for images. For examples call annotations(method:"help", topic:"add").' : "";
+              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "") + paintHelp;
             }).join("; "));
           }
           throw e;
@@ -1510,8 +1931,11 @@ var tools = [
             throw new Error(e.issues.map((i) => {
               const path = i.path.join(".");
               const shape = itemSchema instanceof z3.ZodObject ? itemSchema.shape : null;
-              const desc = shape?.[i.path[1]]?.description;
-              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "");
+              const field = String(i.path[1] ?? i.path[0] ?? "");
+              const desc = shape?.[field]?.description;
+              const paintField = field === "paints" || field === "fills" || field === "strokes";
+              const paintHelp = paintField ? ' Invalid Paint[] payload. Supported Paint[] authoring types: SOLID, GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; do not use CSS gradients or REST gradientHandlePositions. IMAGE/VIDEO/PATTERN are readback-only metadata, not Paint[] authoring input; use imageUrl/images for images. For examples call annotations(method:"help", topic:"remove").' : "";
+              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "") + paintHelp;
             }).join("; "));
           }
           throw e;
@@ -1522,16 +1946,17 @@ var tools = [
   },
   {
     name: "components",
-    description: '/** Create and manage reusable components and variant sets. Use method "help" for detailed parameter docs. */\n  clone     (id?, name?, parentId?, x?, y?, items?: { id: string; name?: string; parentId?: string; x?: number; y?: number }[], depth?) \u2192 { results: {id}[] }  // Duplicate nodes \u2014 produces a same-type copy (frame\u2192frame, instance\u2192instance, component\u2192component). Instance clones reference the same source component; they do not duplicate the component definition.\n  audit     (id, rules?, maxDepth?, maxFindings?, minSeverity?: error|unsafe|heuristic|style|verbose, skipInstances?) \u2192 { nodeId?, nodeName?, categories? }  // Run lint on a node \u2014 returns severity-ranked findings\n  reparent  (items: { id: string; parentId: string; index?: number }[]) \u2192 { results: "ok"[] }  // Move nodes into a new parent\n  list      (query?, offset?, limit?) \u2192 { totalCount, items }  // List local component names (variant sets as single entries)\n  get       (id?, names?, depth?, verbose?) \u2192 { results, _truncated? }  // Get component detail \u2014 property definitions + optional node tree for structural inspection\n  create    (type: component|from_node|variant_set, items: (ComponentItem | FromNodeItem | VariantSetItem)[]) \u2192 { results: {id}[] }  // Create components\n  commit    (id) \u2192 { results: {id}[] }  // Commit a staged component \u2014 unwraps from [STAGED] container into the original target location.\n  update    (items: UpdatePropertyItem[], depth?) \u2192 { results: ("ok" | {error})[] }  // Add, edit, or delete component properties\n  delete    (id) \u2192 { results: "ok"[] }  // Delete components or component sets\n// depth: omit \u2192 id+name stubs | 0 \u2192 props + child stubs | N \u2192 recurse N | -1 \u2192 full tree\n// fields: whitelist e.g. ["fills","opacity"] \u2014 id, name, type always included. Pass ["*"] for all.\n// layoutSizingHorizontal/Vertical: FIXED | HUG | FILL \u2014 how the node sizes within auto-layout.\n// Colors: fillVariableName/strokeVariableName bind by name \u2014 preferred over raw color values.\n// Note: node-based endpoints (frames, text, instances, components) use `results` as the list key.\n//   Standalone endpoints (styles, variables, variable_collections) use `items`. Components.list uses `items` (catalog view).',
+    description: '/** Create and manage reusable components and variant sets. Use method "help" for detailed parameter docs. */\n  clone     (id?, name?, parentId?, x?, y?, items?: { id: string; name?: string; parentId?: string; x?: number; y?: number }[], depth?) \u2192 { results: {id}[] }  // Duplicate nodes \u2014 produces a same-type copy (frame\u2192frame, instance\u2192instance, component\u2192component). Instance clones reference the same source component; they do not duplicate the component definition.\n  scale     (id?, factor?, items?: { id: string; factor: number }[]) \u2192 { results: "ok"[] }  // Proportionally rescale a node subtree using Figma\'s visual Scale tool behavior. This is for visual/artifact scaling, not responsive layout resizing.\n  audit     (id, rules?, maxDepth?, maxFindings?, minSeverity?: error|unsafe|heuristic|style|verbose, skipInstances?) \u2192 { nodeId?, nodeName?, categories? }  // Run lint on a node \u2014 returns severity-ranked findings\n  reparent  (items: { id: string; parentId: string; index?: number }[]) \u2192 { results: "ok"[] }  // Move nodes into a new parent\n  list      (query?, offset?, limit?) \u2192 { totalCount, items }  // List local component names (variant sets as single entries)\n  get       (id?, names?, depth?, verbose?) \u2192 { results, _truncated? }  // Get component detail \u2014 property definitions + optional node tree for structural inspection\n  create    (type: component|from_node|variant_set, items: (ComponentItem | FromNodeItem | VariantSetItem)[]) \u2192 { results: {id}[] }  // Create components\n  commit    (id) \u2192 { results: {id}[] }  // Commit a staged component \u2014 unwraps from [STAGED] container into the original target location.\n  update    (items: UpdatePropertyItem[], depth?) \u2192 { results: ("ok" | {error})[] }  // Add, edit, or delete component properties\n  delete    (id) \u2192 { results: "ok"[] }  // Delete components or component sets\n// depth: omit \u2192 id+name stubs | 0 \u2192 props + child stubs | N \u2192 recurse N | -1 \u2192 full tree\n// fields: whitelist e.g. ["fills","opacity"] \u2014 id, name, type always included. Pass ["*"] for all.\n// layoutSizingHorizontal/Vertical: FIXED | HUG | FILL \u2014 how the node sizes within auto-layout.\n// Colors: fillVariableName/strokeVariableName bind by name \u2014 preferred over raw color values.\n// Note: node-based endpoints (frames, text, instances, components) use `results` as the list key.\n//   Standalone endpoints (styles, variables, variable_collections) use `items`. Components.list uses `items` (catalog view).',
     schema: (caps2) => filterMethodsByTier({
-      method: z3.enum(["clone", "audit", "reparent", "list", "get", "create", "commit", "update", "delete", "help"]),
+      method: z3.enum(["clone", "scale", "audit", "reparent", "list", "get", "create", "commit", "update", "delete", "help"]),
       id: z3.string().optional().describe("Node ID"),
       name: z3.string().optional().describe("Rename the clone (set before appending to parent \u2014 required when cloning a variant into its component set to avoid duplicate names)"),
       parentId: z3.string().optional().describe("Parent node ID. Omit to place at current page root."),
       x: z3.coerce.number().optional().describe("X position (default: 0)"),
       y: z3.coerce.number().optional().describe("Y position (default: 0)"),
-      items: flexJson(z3.array(z3.record(z3.string(), z3.unknown()))).optional().describe("Array of {id, ...properties} to clone/reparent/update"),
+      items: flexJson(z3.array(z3.record(z3.string(), z3.unknown()))).optional().describe("Array of {id, ...properties} to clone/scale/reparent/update"),
       depth: z3.coerce.number().optional().describe("Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited."),
+      factor: z3.coerce.number().optional().describe("Scale factor, >= 0.01. 0.5 = 50%, 2 = 200%. Scales children, text, strokes, effects, and layout geometry from the node's top-left. On auto-layout or HUG/FILL nodes, Figma may resolve responsive sizing to fixed width/height."),
       rules: flexStringList(z3.array(z3.string())).optional().describe('Rules to check. Default: ["all"]. Categories: "component", "composition", "token", "naming", "wcag".'),
       maxDepth: z3.coerce.number().optional().describe("Max tree depth (default: 10)"),
       maxFindings: z3.coerce.number().optional().describe("Max findings (default: 50)"),
@@ -1544,10 +1969,16 @@ var tools = [
       verbose: z3.boolean().optional().describe("Include all properties (bounding box, constraints, text style details). Default false \u2014 returns slim, actionable output."),
       type: z3.enum(["component", "from_node", "variant_set"]).optional().describe("Discriminant for create method"),
       topic: z3.string().optional().describe('Help topic \u2014 method name for endpoint help, e.g. "create"')
-    }, caps2, { "clone": "create", "audit": "read", "reparent": "edit", "list": "read", "get": "read", "create": "create", "commit": "edit", "update": "edit", "delete": "edit", "help": "read" }),
+    }, caps2, { "clone": "create", "scale": "edit", "audit": "read", "reparent": "edit", "list": "read", "get": "read", "create": "create", "commit": "edit", "update": "edit", "delete": "edit", "help": "read" }),
     tier: "read",
     validate: (params) => {
       const m = params.method;
+      if (m === "create") {
+        const itemDiscriminant = Array.isArray(params.items) ? params.items.find((it) => it && typeof it === "object" && typeof it.type === "string")?.type : void 0;
+        if (params.type === void 0) {
+          throw new Error(itemDiscriminant ? 'components.create uses top-level "type", not "type" inside items. Move the item value to the top level and use help for valid item shapes.' : 'components.create requires top-level "type" (component, from_node, variant_set). Use components(method: "help", topic: "create") for valid item shapes.');
+        }
+      }
       if (m === "commit") {
         if (params.id === void 0) throw new Error('commit requires "id"');
       }
@@ -1555,6 +1986,7 @@ var tools = [
         if (params.id === void 0) throw new Error('delete requires "id"');
       }
       if (!params.items) return;
+      if (Array.isArray(params.items) && params.items.length === 0) throw new Error('items: [] is a no-op. Batch calls need at least one item. Omit items to use single-item params, or pass one or more item objects. Use components(method: "help", topic: "' + m + '") to see valid item shapes.');
       if (m === "create") {
         if (params.items) {
           if (params.type === "variant_set") for (const it of params.items) {
@@ -1578,13 +2010,13 @@ var tools = [
             opacity: token.optional().describe("Opacity (0-1) or variable name"),
             blendMode: z3.enum(["PASS_THROUGH", "NORMAL", "DARKEN", "MULTIPLY", "LINEAR_BURN", "COLOR_BURN", "LIGHTEN", "SCREEN", "LINEAR_DODGE", "COLOR_DODGE", "OVERLAY", "SOFT_LIGHT", "HARD_LIGHT", "DIFFERENCE", "EXCLUSION", "HUE", "SATURATION", "COLOR", "LUMINOSITY"]).optional(),
             effectStyleName: z3.string().optional().describe("Effect style name (e.g. 'Shadow/Card') for shadows, blurs"),
-            fills: z3.array(z3.record(z3.string(), z3.unknown())).optional().describe("Fill paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] for transparent. Primary way to set fills."),
+            fills: paintArrayLoose.optional().describe("Fill Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] for transparent. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables; use imageUrl/images for image authoring. IMAGE/VIDEO/PATTERN may appear in readback metadata only. Primary way to set non-image fills."),
             fillColor: colorRgba.optional().describe("Shorthand \u2014 sets a single solid fill (auto-binds to matching variable/style)"),
             fillStyleName: z3.string().optional().describe("Paint style name for fill"),
-            fillVariableName: z3.string().optional().describe("Color variable by name e.g. 'bg/primary'"),
+            fillVariableName: z3.string().optional().describe("Color variable by name e.g. 'bg/surface'"),
             imageUrl: z3.string().optional().describe("Image source \u2014 'pexel:<id>' for Pexels photos, a public URL, or a local file path. SVGs are inserted as vectors; raster images become IMAGE fills."),
             imageScaleMode: z3.enum(["FILL", "FIT", "CROP", "TILE"]).optional().describe("How the image is scaled within the frame (default: FILL)"),
-            strokes: z3.array(z3.record(z3.string(), z3.unknown())).optional().describe("Stroke paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] to clear. Primary way to set strokes."),
+            strokes: paintArrayLoose.optional().describe("Stroke Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] to clear. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables. IMAGE/VIDEO/PATTERN may appear in readback metadata only. Primary way to set strokes."),
             strokeColor: colorRgba.optional().describe("Shorthand \u2014 sets a single solid stroke (auto-binds to matching variable/style)"),
             strokeStyleName: z3.string().optional().describe("Paint style name for stroke"),
             strokeVariableName: z3.string().optional().describe("Color variable by name for stroke"),
@@ -1621,7 +2053,7 @@ var tools = [
             maxHeight: z3.coerce.number().optional().describe("Max height for responsive auto-layout"),
             annotations: flexJson(z3.array(z3.record(z3.string(), z3.unknown()))).optional().describe("Set annotations \u2014 [{label?, labelMarkdown?, properties?, categoryId?}]. Properties validated per node type."),
             description: z3.string().optional().describe("Component description (shown in Figma's component panel)"),
-            children: flexJson(z3.array(z3.record(z3.string(), z3.unknown()))).optional().describe('Inline child nodes \u2014 build nested trees in one call. Types: text: {type:"text", text, componentPropertyName?, fontFamily?, fontSize?, fontWeight?, fontStyle?, fontColor?, layoutSizingHorizontal?}. frame: {type:"frame", name?, layoutMode?, fillColor?, width?, layoutSizingHorizontal?, children?}. instance: {type:"instance", componentId, componentPropertyName?, variantProperties?, properties?}. component: {type:"component", name, children?}. All params from text/frame endpoints are supported on their respective types. componentPropertyName auto-creates and binds a TEXT (text) or INSTANCE_SWAP (instance) property. Always set layoutSizingHorizontal + layoutSizingVertical on children inside auto-layout parents (FILL, HUG, or FIXED). Example: children:[{type:"text", text:"Label", componentPropertyName:"Label", fontSize:14, fontColorVariableName:"text/primary", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}, {type:"frame", name:"Actions", layoutMode:"HORIZONTAL", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG", itemSpacing:8, children:[{type:"instance", componentId:"1:2", componentPropertyName:"Action", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}]}]\n'),
+            children: flexJson(z3.array(z3.record(z3.string(), z3.unknown()))).optional().describe('Inline child nodes \u2014 build nested trees in one call. Types: text: {type:"text", text, componentPropertyName?, textStyleName?, fontColorVariableName?, layoutSizingHorizontal?}. frame: {type:"frame", name?, layoutMode?, fillVariableName?, itemSpacing?, layoutSizingHorizontal?, children?}. instance: {type:"instance", componentId, componentPropertyName?, variantProperties?, properties?}. component: {type:"component", name, children?}. rectangle / ellipse / line: same params as the corresponding frames(method:"create", type:"rectangle"|"ellipse"|"line") branch. All params from text/frame endpoints are supported on their respective types. Inline fills/strokes accept Paint[] authoring input: SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. Do not use CSS gradients, REST gradientHandlePositions, or IMAGE/VIDEO/PATTERN in Paint[] authoring. componentPropertyName auto-creates and binds a TEXT (text) or INSTANCE_SWAP (instance) property. Always set layoutSizingHorizontal + layoutSizingVertical on children inside auto-layout parents (FILL, HUG, or FIXED). Example: children:[{type:"ellipse", name:"Dot", width:6, height:6, fillVariableName:"status/active"}, {type:"text", name:"Label", text:"Button", componentPropertyName:"Label", textStyleName:"Body/Medium", fontColorVariableName:"text/primary", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}, {type:"frame", name:"Actions", layoutMode:"HORIZONTAL", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG", itemSpacing:"space/8", children:[{type:"instance", componentId:"1:2", componentPropertyName:"Action", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}]}]\n'),
             properties: flexJson(z3.array(z3.record(z3.string(), z3.unknown()))).optional().describe("Component properties to define at creation: [{propertyName, type, defaultValue}]. TEXT properties for inline children with componentPropertyName are created automatically.")
           }).passthrough(),
           "from_node": z3.object({
@@ -1642,13 +2074,13 @@ var tools = [
             opacity: token.optional().describe("Opacity (0-1) or variable name"),
             blendMode: z3.enum(["PASS_THROUGH", "NORMAL", "DARKEN", "MULTIPLY", "LINEAR_BURN", "COLOR_BURN", "LIGHTEN", "SCREEN", "LINEAR_DODGE", "COLOR_DODGE", "OVERLAY", "SOFT_LIGHT", "HARD_LIGHT", "DIFFERENCE", "EXCLUSION", "HUE", "SATURATION", "COLOR", "LUMINOSITY"]).optional(),
             effectStyleName: z3.string().optional().describe("Effect style name (e.g. 'Shadow/Card') for shadows, blurs"),
-            fills: z3.array(z3.record(z3.string(), z3.unknown())).optional().describe("Fill paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] for transparent. Primary way to set fills."),
+            fills: paintArrayLoose.optional().describe("Fill Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] for transparent. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables; use imageUrl/images for image authoring. IMAGE/VIDEO/PATTERN may appear in readback metadata only. Primary way to set non-image fills."),
             fillColor: colorRgba.optional().describe("Shorthand \u2014 sets a single solid fill (auto-binds to matching variable/style)"),
             fillStyleName: z3.string().optional().describe("Paint style name for fill"),
-            fillVariableName: z3.string().optional().describe("Color variable by name e.g. 'bg/primary'"),
+            fillVariableName: z3.string().optional().describe("Color variable by name e.g. 'bg/surface'"),
             imageUrl: z3.string().optional().describe("Image source \u2014 'pexel:<id>' for Pexels photos, a public URL, or a local file path. SVGs are inserted as vectors; raster images become IMAGE fills."),
             imageScaleMode: z3.enum(["FILL", "FIT", "CROP", "TILE"]).optional().describe("How the image is scaled within the frame (default: FILL)"),
-            strokes: z3.array(z3.record(z3.string(), z3.unknown())).optional().describe("Stroke paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] to clear. Primary way to set strokes."),
+            strokes: paintArrayLoose.optional().describe("Stroke Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] to clear. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables. IMAGE/VIDEO/PATTERN may appear in readback metadata only. Primary way to set strokes."),
             strokeColor: colorRgba.optional().describe("Shorthand \u2014 sets a single solid stroke (auto-binds to matching variable/style)"),
             strokeStyleName: z3.string().optional().describe("Paint style name for stroke"),
             strokeVariableName: z3.string().optional().describe("Color variable by name for stroke"),
@@ -1686,24 +2118,26 @@ var tools = [
             annotations: flexJson(z3.array(z3.record(z3.string(), z3.unknown()))).optional().describe("Set annotations \u2014 [{label?, labelMarkdown?, properties?, categoryId?}]. Properties validated per node type."),
             componentIds: flexStringList(z3.array(z3.string())).optional().describe("Existing component IDs to combine (min 2). Alternative to children."),
             variantPropertyName: z3.string().optional().describe("Rename the auto-generated variant property (default: 'Property 1')"),
-            children: flexJson(z3.array(z3.record(z3.string(), z3.unknown()))).optional().describe('Inline variant components. Each must be {type:"component", name, children?, ...frame_params}. All variants must share the same child structure. Alternative to componentIds \u2014 do not combine both.')
+            children: flexJson(z3.array(z3.record(z3.string(), z3.unknown()))).optional().describe('Inline variant components. Each must be {type:"component", name, children?, ...frame_params}. Variant children use the same inline child types as components.create, including rectangle / ellipse / line. All variants must share the same child structure. Alternative to componentIds \u2014 do not combine both.')
           }).passthrough()
         };
         const s = params.type && schemas[params.type];
-        if (s) {
-          try {
-            params.items = z3.array(s).parse(params.items);
-          } catch (e) {
-            if (e instanceof z3.ZodError) {
-              throw new Error(e.issues.map((i) => {
-                const path = i.path.join(".");
-                const shape = s instanceof z3.ZodObject ? s.shape : null;
-                const desc = shape?.[i.path[1]]?.description;
-                return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "");
-              }).join("; "));
-            }
-            throw e;
+        if (!s) throw new Error('components.create: unknown type. Use components(method: "help", topic: "create") for valid types and item shapes.');
+        try {
+          params.items = z3.array(s).parse(params.items);
+        } catch (e) {
+          if (e instanceof z3.ZodError) {
+            throw new Error(e.issues.map((i) => {
+              const path = i.path.join(".");
+              const shape = s instanceof z3.ZodObject ? s.shape : null;
+              const field = String(i.path[1] ?? i.path[0] ?? "");
+              const desc = shape?.[field]?.description;
+              const paintField = field === "paints" || field === "fills" || field === "strokes";
+              const paintHelp = paintField ? ' Invalid Paint[] payload. Supported Paint[] authoring types: SOLID, GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; do not use CSS gradients or REST gradientHandlePositions. IMAGE/VIDEO/PATTERN are readback-only metadata, not Paint[] authoring input; use imageUrl/images for images. For examples call components(method:"help", topic:"create").' : "";
+              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "") + paintHelp;
+            }).join("; "));
           }
+          throw e;
         }
       }
       if (m === "update") {
@@ -1723,15 +2157,18 @@ var tools = [
             throw new Error(e.issues.map((i) => {
               const path = i.path.join(".");
               const shape = itemSchema instanceof z3.ZodObject ? itemSchema.shape : null;
-              const desc = shape?.[i.path[1]]?.description;
-              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "");
+              const field = String(i.path[1] ?? i.path[0] ?? "");
+              const desc = shape?.[field]?.description;
+              const paintField = field === "paints" || field === "fills" || field === "strokes";
+              const paintHelp = paintField ? ' Invalid Paint[] payload. Supported Paint[] authoring types: SOLID, GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; do not use CSS gradients or REST gradientHandlePositions. IMAGE/VIDEO/PATTERN are readback-only metadata, not Paint[] authoring input; use imageUrl/images for images. For examples call components(method:"help", topic:"update").' : "";
+              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "") + paintHelp;
             }).join("; "));
           }
           throw e;
         }
       }
     },
-    commandMap: { "clone": "components.clone", "audit": "components.audit", "reparent": "components.reparent", "list": "components.list", "get": "components.get", "create": "components.create", "commit": "components.commit", "update": "components.update", "delete": "components.delete" }
+    commandMap: { "clone": "components.clone", "scale": "components.scale", "audit": "components.audit", "reparent": "components.reparent", "list": "components.list", "get": "components.get", "create": "components.create", "commit": "components.commit", "update": "components.update", "delete": "components.delete" }
   },
   {
     name: "connection",
@@ -1781,9 +2218,9 @@ var tools = [
   },
   {
     name: "frames",
-    description: '/** Create and manage frames, shapes, auto-layout containers, sections, and SVG nodes. Use method "help" for detailed parameter docs. */\n  get       (id, fields?, depth?, verbose?) \u2192 { results: Node[], _truncated?, _notice? }  // Get serialized node data\n  list      (query?, types?, parentId?, fields?, offset?, limit?) \u2192 { totalCount, returned?, offset?, limit?, results }  // Search for nodes (returns stubs only \u2014 use get with depth for full properties)\n  update    (items: PatchItem[]) \u2192 { results: ("ok" | {error})[] }  // Patch node properties\n  delete    (id?, items?: { id?: string }[]) \u2192 { results: "ok"[] }  // Delete nodes\n  clone     (id?, name?, parentId?, x?, y?, items?: { id: string; name?: string; parentId?: string; x?: number; y?: number }[], depth?) \u2192 { results: {id}[] }  // Duplicate nodes \u2014 produces a same-type copy (frame\u2192frame, instance\u2192instance, component\u2192component). Instance clones reference the same source component; they do not duplicate the component definition.\n  audit     (id, rules?, maxDepth?, maxFindings?, minSeverity?: error|unsafe|heuristic|style|verbose, skipInstances?) \u2192 { nodeId?, nodeName?, categories? }  // Run lint on a node \u2014 returns severity-ranked findings\n  reparent  (items: { id: string; parentId: string; index?: number }[]) \u2192 { results: "ok"[] }  // Move nodes into a new parent\n  create    (type: frame|auto_layout|section|rectangle|ellipse|line|group|boolean_operation|svg|slot, items: (FrameItem | AutoLayoutItem | SectionItem | RectangleItem | EllipseItem | LineItem | GroupItem | BooleanOperationItem | SvgItem | SlotItem)[]) \u2192 { results: {id}[] }  // Create frame-like containers\n  commit    (id) \u2192 { results: {id}[] }  // Commit a staged node \u2014 unwraps from [STAGED] container into the original target location.\n  export    (id, format?: PNG|JPG|SVG|SVG_STRING|PDF, scale?) \u2192 { imageData?, mimeType? }  // Export a node as PNG, JPG, SVG, SVG_STRING, or PDF\n// depth: omit \u2192 id+name stubs | 0 \u2192 props + child stubs | N \u2192 recurse N | -1 \u2192 full tree\n// fields: whitelist e.g. ["fills","opacity"] \u2014 id, name, type always included. Pass ["*"] for all.\n// layoutSizingHorizontal/Vertical: FIXED | HUG | FILL \u2014 how the node sizes within auto-layout.\n// Colors: fillVariableName/strokeVariableName bind by name \u2014 preferred over raw color values.\n// Note: node-based endpoints (frames, text, instances, components) use `results` as the list key.\n//   Standalone endpoints (styles, variables, variable_collections) use `items`. Components.list uses `items` (catalog view).',
+    description: '/** Create and manage frames, shapes, auto-layout containers, sections, and SVG nodes. Use method "help" for detailed parameter docs. */\n  get       (id, fields?, depth?, verbose?) \u2192 { results: Node[], _truncated?, _notice? }  // Get serialized node data\n  list      (query?, types?, parentId?, fields?, offset?, limit?) \u2192 { totalCount, returned?, offset?, limit?, results }  // Search for nodes (returns stubs only \u2014 use get with depth for full properties)\n  update    (items: PatchItem[]) \u2192 { results: ("ok" | {error})[] }  // Patch node properties\n  delete    (id?, items?: { id?: string }[]) \u2192 { results: "ok"[] }  // Delete nodes\n  clone     (id?, name?, parentId?, x?, y?, items?: { id: string; name?: string; parentId?: string; x?: number; y?: number }[], depth?) \u2192 { results: {id}[] }  // Duplicate nodes \u2014 produces a same-type copy (frame\u2192frame, instance\u2192instance, component\u2192component). Instance clones reference the same source component; they do not duplicate the component definition.\n  scale     (id?, factor?, items?: { id: string; factor: number }[]) \u2192 { results: "ok"[] }  // Proportionally rescale a node subtree using Figma\'s visual Scale tool behavior. This is for visual/artifact scaling, not responsive layout resizing.\n  audit     (id, rules?, maxDepth?, maxFindings?, minSeverity?: error|unsafe|heuristic|style|verbose, skipInstances?) \u2192 { nodeId?, nodeName?, categories? }  // Run lint on a node \u2014 returns severity-ranked findings\n  reparent  (items: { id: string; parentId: string; index?: number }[]) \u2192 { results: "ok"[] }  // Move nodes into a new parent\n  create    (type: frame|auto_layout|section|rectangle|ellipse|line|group|boolean_operation|svg|slot, items: (FrameItem | AutoLayoutItem | SectionItem | RectangleItem | EllipseItem | LineItem | GroupItem | BooleanOperationItem | SvgItem | SlotItem)[]) \u2192 { results: {id}[] }  // Create frame-like containers\n  commit    (id) \u2192 { results: {id}[] }  // Commit a staged node \u2014 unwraps from [STAGED] container into the original target location.\n  export    (id, format?: PNG|JPG|SVG|SVG_STRING|PDF, scale?) \u2192 { imageData?, mimeType? }  // Export a node as PNG, JPG, SVG, SVG_STRING, or PDF\n// depth: omit \u2192 id+name stubs | 0 \u2192 props + child stubs | N \u2192 recurse N | -1 \u2192 full tree\n// fields: whitelist e.g. ["fills","opacity"] \u2014 id, name, type always included. Pass ["*"] for all.\n// layoutSizingHorizontal/Vertical: FIXED | HUG | FILL \u2014 how the node sizes within auto-layout.\n// Colors: fillVariableName/strokeVariableName bind by name \u2014 preferred over raw color values.\n// Note: node-based endpoints (frames, text, instances, components) use `results` as the list key.\n//   Standalone endpoints (styles, variables, variable_collections) use `items`. Components.list uses `items` (catalog view).',
     schema: (caps2) => filterMethodsByTier({
-      method: z3.enum(["get", "list", "update", "delete", "clone", "audit", "reparent", "create", "commit", "export", "help"]),
+      method: z3.enum(["get", "list", "update", "delete", "clone", "scale", "audit", "reparent", "create", "commit", "export", "help"]),
       id: z3.string().optional().describe("Node ID"),
       fields: flexStringList(z3.array(z3.string())).optional().describe('Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.'),
       depth: z3.coerce.number().optional().describe("Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited."),
@@ -1793,10 +2230,11 @@ var tools = [
       parentId: z3.string().optional().describe("Search only within this subtree"),
       offset: z3.coerce.number().optional().default(0).describe("Skip N items for pagination (default 0)"),
       limit: z3.coerce.number().optional().default(100).describe("Max items per page (default 100)"),
-      items: flexJson(z3.array(z3.record(z3.string(), z3.unknown()))).optional().describe("Array of {id, ...properties} to update/delete/clone/reparent"),
+      items: flexJson(z3.array(z3.record(z3.string(), z3.unknown()))).optional().describe("Array of {id, ...properties} to update/delete/clone/scale/reparent"),
       name: z3.string().optional().describe("Rename the clone (set before appending to parent \u2014 required when cloning a variant into its component set to avoid duplicate names)"),
       x: z3.coerce.number().optional().describe("X position (default: 0)"),
       y: z3.coerce.number().optional().describe("Y position (default: 0)"),
+      factor: z3.coerce.number().optional().describe("Scale factor, >= 0.01. 0.5 = 50%, 2 = 200%. Scales children, text, strokes, effects, and layout geometry from the node's top-left. On auto-layout or HUG/FILL nodes, Figma may resolve responsive sizing to fixed width/height."),
       rules: flexStringList(z3.array(z3.string())).optional().describe('Rules to check. Default: ["all"]. Categories: "component", "composition", "token", "naming", "wcag".'),
       maxDepth: z3.coerce.number().optional().describe("Max tree depth (default: 10)"),
       maxFindings: z3.coerce.number().optional().describe("Max findings (default: 50)"),
@@ -1806,10 +2244,16 @@ var tools = [
       format: z3.enum(["PNG", "JPG", "SVG", "SVG_STRING", "PDF"]).optional().describe("Export format (default: PNG). SVG_STRING returns raw SVG text."),
       scale: z3.coerce.number().optional().describe("Export scale (default: 1, only for PNG/JPG)"),
       topic: z3.string().optional().describe('Help topic \u2014 method name for endpoint help, e.g. "create"')
-    }, caps2, { "get": "read", "list": "read", "update": "edit", "delete": "edit", "clone": "create", "audit": "read", "reparent": "edit", "create": "create", "commit": "edit", "export": "read", "help": "read" }),
+    }, caps2, { "get": "read", "list": "read", "update": "edit", "delete": "edit", "clone": "create", "scale": "edit", "audit": "read", "reparent": "edit", "create": "create", "commit": "edit", "export": "read", "help": "read" }),
     tier: "read",
     validate: (params) => {
       const m = params.method;
+      if (m === "create") {
+        const itemDiscriminant = Array.isArray(params.items) ? params.items.find((it) => it && typeof it === "object" && typeof it.type === "string")?.type : void 0;
+        if (params.type === void 0) {
+          throw new Error(itemDiscriminant ? 'frames.create uses top-level "type", not "type" inside items. Move the item value to the top level and use help for valid item shapes.' : 'frames.create requires top-level "type" (frame, auto_layout, section, rectangle, ellipse, line, group, boolean_operation, svg, slot). Use frames(method: "help", topic: "create") for valid item shapes.');
+        }
+      }
       if (m === "commit") {
         if (params.id === void 0) throw new Error('commit requires "id"');
       }
@@ -1817,6 +2261,7 @@ var tools = [
         if (params.id === void 0) throw new Error('export requires "id"');
       }
       if (!params.items) return;
+      if (Array.isArray(params.items) && params.items.length === 0) throw new Error('items: [] is a no-op. Batch calls need at least one item. Omit items to use single-item params, or pass one or more item objects. Use frames(method: "help", topic: "' + m + '") to see valid item shapes.');
       if (m === "create") {
         const schemas = {
           "frame": z3.object({
@@ -1832,13 +2277,13 @@ var tools = [
             opacity: token.optional().describe("Opacity (0-1) or variable name"),
             blendMode: z3.enum(["PASS_THROUGH", "NORMAL", "DARKEN", "MULTIPLY", "LINEAR_BURN", "COLOR_BURN", "LIGHTEN", "SCREEN", "LINEAR_DODGE", "COLOR_DODGE", "OVERLAY", "SOFT_LIGHT", "HARD_LIGHT", "DIFFERENCE", "EXCLUSION", "HUE", "SATURATION", "COLOR", "LUMINOSITY"]).optional(),
             effectStyleName: z3.string().optional().describe("Effect style name (e.g. 'Shadow/Card') for shadows, blurs"),
-            fills: z3.array(z3.record(z3.string(), z3.unknown())).optional().describe("Fill paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] for transparent. Primary way to set fills."),
+            fills: paintArrayLoose.optional().describe("Fill Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] for transparent. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables; use imageUrl/images for image authoring. IMAGE/VIDEO/PATTERN may appear in readback metadata only. Primary way to set non-image fills."),
             fillColor: colorRgba.optional().describe("Shorthand \u2014 sets a single solid fill (auto-binds to matching variable/style)"),
             fillStyleName: z3.string().optional().describe("Paint style name for fill"),
-            fillVariableName: z3.string().optional().describe("Color variable by name e.g. 'bg/primary'"),
+            fillVariableName: z3.string().optional().describe("Color variable by name e.g. 'bg/surface'"),
             imageUrl: z3.string().optional().describe("Image source \u2014 'pexel:<id>' for Pexels photos, a public URL, or a local file path. SVGs are inserted as vectors; raster images become IMAGE fills."),
             imageScaleMode: z3.enum(["FILL", "FIT", "CROP", "TILE"]).optional().describe("How the image is scaled within the frame (default: FILL)"),
-            strokes: z3.array(z3.record(z3.string(), z3.unknown())).optional().describe("Stroke paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] to clear. Primary way to set strokes."),
+            strokes: paintArrayLoose.optional().describe("Stroke Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] to clear. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables. IMAGE/VIDEO/PATTERN may appear in readback metadata only. Primary way to set strokes."),
             strokeColor: colorRgba.optional().describe("Shorthand \u2014 sets a single solid stroke (auto-binds to matching variable/style)"),
             strokeStyleName: z3.string().optional().describe("Paint style name for stroke"),
             strokeVariableName: z3.string().optional().describe("Color variable by name for stroke"),
@@ -1875,7 +2320,7 @@ var tools = [
             maxHeight: z3.coerce.number().optional().describe("Max height for responsive auto-layout"),
             annotations: flexJson(z3.array(z3.record(z3.string(), z3.unknown()))).optional().describe("Set annotations \u2014 [{label?, labelMarkdown?, properties?, categoryId?}]. Properties validated per node type."),
             clipsContent: flexBool(z3.boolean()).optional(),
-            children: flexJson(z3.array(z3.record(z3.string(), z3.unknown()))).optional().describe('Inline child nodes \u2014 build nested trees in one call. Types: text: {type:"text", text, fontFamily?, fontSize?, fontWeight?, fontStyle?, fontColor?, layoutSizingHorizontal?}. frame: {type:"frame", name?, layoutMode?, fillColor?, width?, layoutSizingHorizontal?, children?}. instance: {type:"instance", componentId, variantProperties?, properties?}. component: {type:"component", name, children?}. All params from text/frame endpoints are supported on their respective types. Always set layoutSizingHorizontal + layoutSizingVertical on children inside auto-layout parents (FILL, HUG, or FIXED). Example: children:[{type:"text", text:"Title", fontSize:20, layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}, {type:"frame", name:"Row", layoutMode:"HORIZONTAL", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG", itemSpacing:8, children:[{type:"instance", componentId:"1:2", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}]}] Inside components: add componentPropertyName to auto-bind TEXT or INSTANCE_SWAP properties.\n')
+            children: flexJson(z3.array(z3.record(z3.string(), z3.unknown()))).optional().describe('Inline child nodes \u2014 build nested trees in one call. Types: text: {type:"text", text, textStyleName?, fontColorVariableName?, layoutSizingHorizontal?}. frame: {type:"frame", name?, layoutMode?, fillVariableName?, itemSpacing?, layoutSizingHorizontal?, children?}. instance: {type:"instance", componentId, variantProperties?, properties?}. component: {type:"component", name, children?}. rectangle / ellipse / line: same params as the corresponding frames(method:"create", type:"rectangle"|"ellipse"|"line") branch. All params from text/frame endpoints are supported on their respective types. Inline fills/strokes accept Paint[] authoring input: SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. Do not use CSS gradients, REST gradientHandlePositions, or IMAGE/VIDEO/PATTERN in Paint[] authoring. Always set layoutSizingHorizontal + layoutSizingVertical on children inside auto-layout parents (FILL, HUG, or FIXED). Example: children:[{type:"ellipse", name:"Dot", width:6, height:6, fillVariableName:"status/active"}, {type:"text", name:"Title", text:"Title", textStyleName:"Heading/Medium", fontColorVariableName:"text/primary", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}, {type:"frame", name:"Row", layoutMode:"HORIZONTAL", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG", itemSpacing:"space/8", children:[{type:"instance", componentId:"1:2", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}]}] Inside components: add componentPropertyName to auto-bind TEXT or INSTANCE_SWAP properties.\n')
           }).passthrough(),
           "auto_layout": z3.object({
             name: z3.string().optional().describe("Node name"),
@@ -1890,13 +2335,13 @@ var tools = [
             opacity: token.optional().describe("Opacity (0-1) or variable name"),
             blendMode: z3.enum(["PASS_THROUGH", "NORMAL", "DARKEN", "MULTIPLY", "LINEAR_BURN", "COLOR_BURN", "LIGHTEN", "SCREEN", "LINEAR_DODGE", "COLOR_DODGE", "OVERLAY", "SOFT_LIGHT", "HARD_LIGHT", "DIFFERENCE", "EXCLUSION", "HUE", "SATURATION", "COLOR", "LUMINOSITY"]).optional(),
             effectStyleName: z3.string().optional().describe("Effect style name (e.g. 'Shadow/Card') for shadows, blurs"),
-            fills: z3.array(z3.record(z3.string(), z3.unknown())).optional().describe("Fill paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] for transparent. Primary way to set fills."),
+            fills: paintArrayLoose.optional().describe("Fill Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] for transparent. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables; use imageUrl/images for image authoring. IMAGE/VIDEO/PATTERN may appear in readback metadata only. Primary way to set non-image fills."),
             fillColor: colorRgba.optional().describe("Shorthand \u2014 sets a single solid fill (auto-binds to matching variable/style)"),
             fillStyleName: z3.string().optional().describe("Paint style name for fill"),
-            fillVariableName: z3.string().optional().describe("Color variable by name e.g. 'bg/primary'"),
+            fillVariableName: z3.string().optional().describe("Color variable by name e.g. 'bg/surface'"),
             imageUrl: z3.string().optional().describe("Image source \u2014 'pexel:<id>' for Pexels photos, a public URL, or a local file path. SVGs are inserted as vectors; raster images become IMAGE fills."),
             imageScaleMode: z3.enum(["FILL", "FIT", "CROP", "TILE"]).optional().describe("How the image is scaled within the frame (default: FILL)"),
-            strokes: z3.array(z3.record(z3.string(), z3.unknown())).optional().describe("Stroke paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] to clear. Primary way to set strokes."),
+            strokes: paintArrayLoose.optional().describe("Stroke Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] to clear. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables. IMAGE/VIDEO/PATTERN may appear in readback metadata only. Primary way to set strokes."),
             strokeColor: colorRgba.optional().describe("Shorthand \u2014 sets a single solid stroke (auto-binds to matching variable/style)"),
             strokeStyleName: z3.string().optional().describe("Paint style name for stroke"),
             strokeVariableName: z3.string().optional().describe("Color variable by name for stroke"),
@@ -1934,7 +2379,7 @@ var tools = [
             annotations: flexJson(z3.array(z3.record(z3.string(), z3.unknown()))).optional().describe("Set annotations \u2014 [{label?, labelMarkdown?, properties?, categoryId?}]. Properties validated per node type."),
             clipsContent: flexBool(z3.boolean()).optional(),
             nodeIds: flexStringList(z3.array(z3.string())).optional().describe("Existing node IDs to wrap into auto-layout"),
-            children: flexJson(z3.array(z3.record(z3.string(), z3.unknown()))).optional().describe('Inline child nodes \u2014 build nested trees in one call. Types: text: {type:"text", text, fontFamily?, fontSize?, fontWeight?, fontStyle?, fontColor?, layoutSizingHorizontal?}. frame: {type:"frame", name?, layoutMode?, fillColor?, width?, layoutSizingHorizontal?, children?}. instance: {type:"instance", componentId, variantProperties?, properties?}. component: {type:"component", name, children?}. All params from text/frame endpoints are supported on their respective types. Always set layoutSizingHorizontal + layoutSizingVertical on children inside auto-layout parents (FILL, HUG, or FIXED). Example: children:[{type:"text", text:"Title", fontSize:20, layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}, {type:"frame", name:"Row", layoutMode:"HORIZONTAL", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG", itemSpacing:8, children:[{type:"instance", componentId:"1:2", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}]}] Inside components: add componentPropertyName to auto-bind TEXT or INSTANCE_SWAP properties.\n')
+            children: flexJson(z3.array(z3.record(z3.string(), z3.unknown()))).optional().describe('Inline child nodes \u2014 build nested trees in one call. Types: text: {type:"text", text, textStyleName?, fontColorVariableName?, layoutSizingHorizontal?}. frame: {type:"frame", name?, layoutMode?, fillVariableName?, itemSpacing?, layoutSizingHorizontal?, children?}. instance: {type:"instance", componentId, variantProperties?, properties?}. component: {type:"component", name, children?}. rectangle / ellipse / line: same params as the corresponding frames(method:"create", type:"rectangle"|"ellipse"|"line") branch. All params from text/frame endpoints are supported on their respective types. Inline fills/strokes accept Paint[] authoring input: SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. Do not use CSS gradients, REST gradientHandlePositions, or IMAGE/VIDEO/PATTERN in Paint[] authoring. Always set layoutSizingHorizontal + layoutSizingVertical on children inside auto-layout parents (FILL, HUG, or FIXED). Example: children:[{type:"ellipse", name:"Dot", width:6, height:6, fillVariableName:"status/active"}, {type:"text", name:"Title", text:"Title", textStyleName:"Heading/Medium", fontColorVariableName:"text/primary", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}, {type:"frame", name:"Row", layoutMode:"HORIZONTAL", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG", itemSpacing:"space/8", children:[{type:"instance", componentId:"1:2", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}]}] Inside components: add componentPropertyName to auto-bind TEXT or INSTANCE_SWAP properties.\n')
           }).passthrough(),
           "section": z3.object({
             name: z3.string().describe("Section name"),
@@ -1943,10 +2388,10 @@ var tools = [
             y: z3.coerce.number().optional().describe("Y position (default: 0)"),
             width: z3.coerce.number().optional().describe("Width (default: 500)"),
             height: z3.coerce.number().optional().describe("Height (default: 500)"),
-            fills: z3.array(z3.record(z3.string(), z3.unknown())).optional().describe("Fill paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] for transparent"),
+            fills: paintArrayLoose.optional().describe("Fill Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] for transparent. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables; use imageUrl/images for image authoring. IMAGE/VIDEO/PATTERN may appear in readback metadata only"),
             fillColor: colorRgba.optional().describe("Shorthand \u2014 sets a single solid fill (auto-binds to matching variable/style)"),
             fillStyleName: z3.string().optional().describe("Paint style name for fill"),
-            fillVariableName: z3.string().optional().describe("Color variable by name e.g. 'bg/primary'"),
+            fillVariableName: z3.string().optional().describe("Color variable by name e.g. 'bg/surface'"),
             imageUrl: z3.string().optional().describe("Image source \u2014 'pexel:<id>', public URL, or local file path"),
             imageScaleMode: z3.enum(["FILL", "FIT", "CROP", "TILE"]).optional().describe("How the image is scaled (default: FILL)")
           }).passthrough(),
@@ -1957,13 +2402,13 @@ var tools = [
             y: z3.coerce.number().optional().describe("Y position (default: 0)"),
             width: z3.coerce.number().optional().describe("Width in px (default: 100)"),
             height: z3.coerce.number().optional().describe("Height in px (default: 100)"),
-            fills: z3.array(z3.record(z3.string(), z3.unknown())).optional().describe("Fill paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] for transparent"),
+            fills: paintArrayLoose.optional().describe("Fill Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] for transparent. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables; use imageUrl/images for image authoring. IMAGE/VIDEO/PATTERN may appear in readback metadata only"),
             fillColor: colorRgba.optional().describe("Shorthand \u2014 sets a single solid fill (auto-binds to matching variable/style)"),
             fillStyleName: z3.string().optional().describe("Paint style name for fill"),
-            fillVariableName: z3.string().optional().describe("Color variable by name e.g. 'bg/primary'"),
+            fillVariableName: z3.string().optional().describe("Color variable by name e.g. 'bg/surface'"),
             imageUrl: z3.string().optional().describe("Image source \u2014 'pexel:<id>', public URL, or local file path"),
             imageScaleMode: z3.enum(["FILL", "FIT", "CROP", "TILE"]).optional().describe("How the image is scaled (default: FILL)"),
-            strokes: z3.array(z3.record(z3.string(), z3.unknown())).optional().describe("Stroke paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] to clear"),
+            strokes: paintArrayLoose.optional().describe("Stroke Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] to clear. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables. IMAGE/VIDEO/PATTERN may appear in readback metadata only"),
             strokeColor: colorRgba.optional().describe("Shorthand \u2014 sets a single solid stroke (auto-binds to matching variable/style)"),
             strokeVariableName: z3.string().optional().describe("Color variable by name for stroke"),
             strokeWeight: token.optional(),
@@ -1984,13 +2429,13 @@ var tools = [
             y: z3.coerce.number().optional().describe("Y position (default: 0)"),
             width: z3.coerce.number().optional().describe("Width in px (default: 100)"),
             height: z3.coerce.number().optional().describe("Height in px (default: 100, same as width for circle)"),
-            fills: z3.array(z3.record(z3.string(), z3.unknown())).optional().describe("Fill paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] for transparent"),
+            fills: paintArrayLoose.optional().describe("Fill Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] for transparent. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables; use imageUrl/images for image authoring. IMAGE/VIDEO/PATTERN may appear in readback metadata only"),
             fillColor: colorRgba.optional().describe("Shorthand \u2014 sets a single solid fill (auto-binds to matching variable/style)"),
             fillStyleName: z3.string().optional().describe("Paint style name for fill"),
-            fillVariableName: z3.string().optional().describe("Color variable by name e.g. 'bg/primary'"),
+            fillVariableName: z3.string().optional().describe("Color variable by name e.g. 'bg/surface'"),
             imageUrl: z3.string().optional().describe("Image source \u2014 'pexel:<id>', public URL, or local file path"),
             imageScaleMode: z3.enum(["FILL", "FIT", "CROP", "TILE"]).optional().describe("How the image is scaled (default: FILL)"),
-            strokes: z3.array(z3.record(z3.string(), z3.unknown())).optional().describe("Stroke paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] to clear"),
+            strokes: paintArrayLoose.optional().describe("Stroke Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] to clear. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables. IMAGE/VIDEO/PATTERN may appear in readback metadata only"),
             strokeColor: colorRgba.optional().describe("Shorthand \u2014 sets a single solid stroke (auto-binds to matching variable/style)"),
             strokeVariableName: z3.string().optional().describe("Color variable by name for stroke"),
             strokeWeight: token.optional(),
@@ -2006,7 +2451,7 @@ var tools = [
             y: z3.coerce.number().optional().describe("Y position (default: 0)"),
             length: z3.coerce.number().optional().describe("Line length in px (default: 100)"),
             rotation: z3.coerce.number().optional().describe("Rotation in degrees (default: 0 = horizontal)"),
-            strokes: z3.array(z3.record(z3.string(), z3.unknown())).optional().describe("Stroke paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] to clear"),
+            strokes: paintArrayLoose.optional().describe("Stroke Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] to clear. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables. IMAGE/VIDEO/PATTERN may appear in readback metadata only"),
             strokeColor: colorRgba.optional().describe("Line color (default: black, auto-binds to matching variable/style)"),
             strokeVariableName: z3.string().optional().describe("Color variable by name for stroke"),
             strokeWeight: token.optional().describe("Line thickness (default: 1)"),
@@ -2020,6 +2465,10 @@ var tools = [
             parentId: z3.string().optional().describe("Parent node ID. Omit to place at current page root.")
           }).passthrough(),
           "boolean_operation": z3.object({
+            fillStyleName: z3.string().optional().describe("Paint style to apply to vector fills"),
+            fillVariableName: z3.string().optional().describe("Color variable by name for vector fills"),
+            strokeStyleName: z3.string().optional().describe("Paint style to apply to vector strokes"),
+            strokeVariableName: z3.string().optional().describe("Color variable by name for vector strokes"),
             operation: z3.enum(["UNION", "SUBTRACT", "INTERSECT", "EXCLUDE"]).describe("Boolean operation type"),
             nodeIds: z3.array(z3.string()).describe("Node IDs to combine (min 2, first node is the base for SUBTRACT)"),
             name: z3.string().optional().describe("Result node name"),
@@ -2049,13 +2498,13 @@ var tools = [
             opacity: token.optional().describe("Opacity (0-1) or variable name"),
             blendMode: z3.enum(["PASS_THROUGH", "NORMAL", "DARKEN", "MULTIPLY", "LINEAR_BURN", "COLOR_BURN", "LIGHTEN", "SCREEN", "LINEAR_DODGE", "COLOR_DODGE", "OVERLAY", "SOFT_LIGHT", "HARD_LIGHT", "DIFFERENCE", "EXCLUSION", "HUE", "SATURATION", "COLOR", "LUMINOSITY"]).optional(),
             effectStyleName: z3.string().optional().describe("Effect style name (e.g. 'Shadow/Card') for shadows, blurs"),
-            fills: z3.array(z3.record(z3.string(), z3.unknown())).optional().describe("Fill paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] for transparent. Primary way to set fills."),
+            fills: paintArrayLoose.optional().describe("Fill Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] for transparent. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables; use imageUrl/images for image authoring. IMAGE/VIDEO/PATTERN may appear in readback metadata only. Primary way to set non-image fills."),
             fillColor: colorRgba.optional().describe("Shorthand \u2014 sets a single solid fill (auto-binds to matching variable/style)"),
             fillStyleName: z3.string().optional().describe("Paint style name for fill"),
-            fillVariableName: z3.string().optional().describe("Color variable by name e.g. 'bg/primary'"),
+            fillVariableName: z3.string().optional().describe("Color variable by name e.g. 'bg/surface'"),
             imageUrl: z3.string().optional().describe("Image source \u2014 'pexel:<id>' for Pexels photos, a public URL, or a local file path. SVGs are inserted as vectors; raster images become IMAGE fills."),
             imageScaleMode: z3.enum(["FILL", "FIT", "CROP", "TILE"]).optional().describe("How the image is scaled within the frame (default: FILL)"),
-            strokes: z3.array(z3.record(z3.string(), z3.unknown())).optional().describe("Stroke paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] to clear. Primary way to set strokes."),
+            strokes: paintArrayLoose.optional().describe("Stroke Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] to clear. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables. IMAGE/VIDEO/PATTERN may appear in readback metadata only. Primary way to set strokes."),
             strokeColor: colorRgba.optional().describe("Shorthand \u2014 sets a single solid stroke (auto-binds to matching variable/style)"),
             strokeStyleName: z3.string().optional().describe("Paint style name for stroke"),
             strokeVariableName: z3.string().optional().describe("Color variable by name for stroke"),
@@ -2095,24 +2544,26 @@ var tools = [
           }).passthrough()
         };
         const s = params.type && schemas[params.type];
-        if (s) {
-          try {
-            params.items = z3.array(s).parse(params.items);
-          } catch (e) {
-            if (e instanceof z3.ZodError) {
-              throw new Error(e.issues.map((i) => {
-                const path = i.path.join(".");
-                const shape = s instanceof z3.ZodObject ? s.shape : null;
-                const desc = shape?.[i.path[1]]?.description;
-                return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "");
-              }).join("; "));
-            }
-            throw e;
+        if (!s) throw new Error('frames.create: unknown type. Use frames(method: "help", topic: "create") for valid types and item shapes.');
+        try {
+          params.items = z3.array(s).parse(params.items);
+        } catch (e) {
+          if (e instanceof z3.ZodError) {
+            throw new Error(e.issues.map((i) => {
+              const path = i.path.join(".");
+              const shape = s instanceof z3.ZodObject ? s.shape : null;
+              const field = String(i.path[1] ?? i.path[0] ?? "");
+              const desc = shape?.[field]?.description;
+              const paintField = field === "paints" || field === "fills" || field === "strokes";
+              const paintHelp = paintField ? ' Invalid Paint[] payload. Supported Paint[] authoring types: SOLID, GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; do not use CSS gradients or REST gradientHandlePositions. IMAGE/VIDEO/PATTERN are readback-only metadata, not Paint[] authoring input; use imageUrl/images for images. For examples call frames(method:"help", topic:"create").' : "";
+              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "") + paintHelp;
+            }).join("; "));
           }
+          throw e;
         }
       }
     },
-    commandMap: { "get": "frames.get", "list": "frames.list", "update": "frames.update", "delete": "frames.delete", "clone": "frames.clone", "audit": "frames.audit", "reparent": "frames.reparent", "create": "frames.create", "commit": "frames.commit", "export": "frames.export" }
+    commandMap: { "get": "frames.get", "list": "frames.list", "update": "frames.update", "delete": "frames.delete", "clone": "frames.clone", "scale": "frames.scale", "audit": "frames.audit", "reparent": "frames.reparent", "create": "frames.create", "commit": "frames.commit", "export": "frames.export" }
   },
   {
     name: "icons",
@@ -2174,9 +2625,9 @@ var tools = [
   },
   {
     name: "instances",
-    description: '/** Create and manage component instances. Use method "help" for detailed parameter docs. */\n  list      (query?, types?, parentId?, fields?, offset?, limit?) \u2192 { totalCount, returned?, offset?, limit?, results }  // Search for nodes (returns stubs only \u2014 use get with depth for full properties)\n  delete    (id?, items?: { id?: string }[]) \u2192 { results: "ok"[] }  // Delete nodes\n  clone     (id?, name?, parentId?, x?, y?, items?: { id: string; name?: string; parentId?: string; x?: number; y?: number }[], depth?) \u2192 { results: {id}[] }  // Duplicate nodes \u2014 produces a same-type copy (frame\u2192frame, instance\u2192instance, component\u2192component). Instance clones reference the same source component; they do not duplicate the component definition.\n  audit     (id, rules?, maxDepth?, maxFindings?, minSeverity?: error|unsafe|heuristic|style|verbose, skipInstances?) \u2192 { nodeId?, nodeName?, categories? }  // Run lint on a node \u2014 returns severity-ranked findings\n  reparent  (items: { id: string; parentId: string; index?: number }[]) \u2192 { results: "ok"[] }  // Move nodes into a new parent\n  get       (id, fields?, depth?, verbose?) \u2192 { results, _truncated? }  // Get instance detail with component properties and overrides\n  create    (items: InstanceCreateItem[], depth?) \u2192 { results: {id}[] }  // Create component instances\n  update    (items: InstanceUpdateItem[]) \u2192 { results: ("ok" | {error})[] }  // Set instance properties\n  swap      (items: { id: string; componentId: string }[]) \u2192 { results: ("ok" | {error})[] }  // Swap instance component (preserves overrides)\n  detach    (items: { id: string }[]) \u2192 { results: {id}[] }  // Detach instances from their component (converts to frame)\n  reset_overrides(items: { id: string }[]) \u2192 { results: ("ok" | {error})[] }  // Reset all overrides on instances to match their main component\n// depth: omit \u2192 id+name stubs | 0 \u2192 props + child stubs | N \u2192 recurse N | -1 \u2192 full tree\n// fields: whitelist e.g. ["fills","opacity"] \u2014 id, name, type always included. Pass ["*"] for all.\n// layoutSizingHorizontal/Vertical: FIXED | HUG | FILL \u2014 how the node sizes within auto-layout.\n// Colors: fillVariableName/strokeVariableName bind by name \u2014 preferred over raw color values.\n// Note: node-based endpoints (frames, text, instances, components) use `results` as the list key.\n//   Standalone endpoints (styles, variables, variable_collections) use `items`. Components.list uses `items` (catalog view).',
+    description: '/** Create and manage component instances. Use method "help" for detailed parameter docs. */\n  list      (query?, types?, parentId?, fields?, offset?, limit?) \u2192 { totalCount, returned?, offset?, limit?, results }  // Search for nodes (returns stubs only \u2014 use get with depth for full properties)\n  delete    (id?, items?: { id?: string }[]) \u2192 { results: "ok"[] }  // Delete nodes\n  clone     (id?, name?, parentId?, x?, y?, items?: { id: string; name?: string; parentId?: string; x?: number; y?: number }[], depth?) \u2192 { results: {id}[] }  // Duplicate nodes \u2014 produces a same-type copy (frame\u2192frame, instance\u2192instance, component\u2192component). Instance clones reference the same source component; they do not duplicate the component definition.\n  scale     (id?, factor?, items?: { id: string; factor: number }[]) \u2192 { results: "ok"[] }  // Proportionally rescale a node subtree using Figma\'s visual Scale tool behavior. This is for visual/artifact scaling, not responsive layout resizing.\n  audit     (id, rules?, maxDepth?, maxFindings?, minSeverity?: error|unsafe|heuristic|style|verbose, skipInstances?) \u2192 { nodeId?, nodeName?, categories? }  // Run lint on a node \u2014 returns severity-ranked findings\n  reparent  (items: { id: string; parentId: string; index?: number }[]) \u2192 { results: "ok"[] }  // Move nodes into a new parent\n  get       (id, fields?, depth?, verbose?) \u2192 { results, _truncated? }  // Get instance detail with component properties and overrides\n  create    (items: InstanceCreateItem[], depth?) \u2192 { results: {id}[] }  // Create component instances\n  update    (items: InstanceUpdateItem[]) \u2192 { results: ("ok" | {error})[] }  // Set instance properties\n  swap      (items: { id: string; componentId: string }[]) \u2192 { results: ("ok" | {error})[] }  // Swap instance component (preserves overrides)\n  detach    (items: { id: string }[]) \u2192 { results: {id}[] }  // Detach instances from their component (converts to frame)\n  reset_overrides(items: { id: string }[]) \u2192 { results: ("ok" | {error})[] }  // Reset all overrides on instances to match their main component\n// depth: omit \u2192 id+name stubs | 0 \u2192 props + child stubs | N \u2192 recurse N | -1 \u2192 full tree\n// fields: whitelist e.g. ["fills","opacity"] \u2014 id, name, type always included. Pass ["*"] for all.\n// layoutSizingHorizontal/Vertical: FIXED | HUG | FILL \u2014 how the node sizes within auto-layout.\n// Colors: fillVariableName/strokeVariableName bind by name \u2014 preferred over raw color values.\n// Note: node-based endpoints (frames, text, instances, components) use `results` as the list key.\n//   Standalone endpoints (styles, variables, variable_collections) use `items`. Components.list uses `items` (catalog view).',
     schema: (caps2) => filterMethodsByTier({
-      method: z3.enum(["list", "delete", "clone", "audit", "reparent", "get", "create", "update", "swap", "detach", "reset_overrides", "help"]),
+      method: z3.enum(["list", "delete", "clone", "scale", "audit", "reparent", "get", "create", "update", "swap", "detach", "reset_overrides", "help"]),
       query: z3.string().optional().describe("Name search query (case-insensitive substring match)"),
       types: flexStringList(z3.array(z3.string())).optional().describe('Filter by node types (e.g. ["FRAME", "TEXT"])'),
       parentId: z3.string().optional().describe("Search only within this subtree"),
@@ -2184,11 +2635,12 @@ var tools = [
       offset: z3.coerce.number().optional().default(0).describe("Skip N items for pagination (default 0)"),
       limit: z3.coerce.number().optional().default(100).describe("Max items per page (default 100)"),
       id: z3.string().optional().describe("Single node ID"),
-      items: flexJson(z3.array(z3.record(z3.string(), z3.unknown()))).optional().describe("Array of {id, ...properties} to delete/clone/reparent/create/update/swap/detach/reset_overrides"),
+      items: flexJson(z3.array(z3.record(z3.string(), z3.unknown()))).optional().describe("Array of {id, ...properties} to delete/clone/scale/reparent/create/update/swap/detach/reset_overrides"),
       name: z3.string().optional().describe("Rename the clone (set before appending to parent \u2014 required when cloning a variant into its component set to avoid duplicate names)"),
       x: z3.coerce.number().optional().describe("X position (default: 0)"),
       y: z3.coerce.number().optional().describe("Y position (default: 0)"),
       depth: z3.coerce.number().optional().describe("Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited."),
+      factor: z3.coerce.number().optional().describe("Scale factor, >= 0.01. 0.5 = 50%, 2 = 200%. Scales children, text, strokes, effects, and layout geometry from the node's top-left. On auto-layout or HUG/FILL nodes, Figma may resolve responsive sizing to fixed width/height."),
       rules: flexStringList(z3.array(z3.string())).optional().describe('Rules to check. Default: ["all"]. Categories: "component", "composition", "token", "naming", "wcag".'),
       maxDepth: z3.coerce.number().optional().describe("Max tree depth (default: 10)"),
       maxFindings: z3.coerce.number().optional().describe("Max findings (default: 50)"),
@@ -2196,7 +2648,7 @@ var tools = [
       skipInstances: flexBool(z3.boolean()).optional().describe("Skip instance internals \u2014 findings inside instances are owned by the component (default: true)"),
       verbose: z3.boolean().optional().describe("Include all properties (bounding box, constraints, text style details). Default false \u2014 returns slim, actionable output."),
       topic: z3.string().optional().describe('Help topic \u2014 method name for endpoint help, e.g. "create"')
-    }, caps2, { "list": "read", "delete": "edit", "clone": "create", "audit": "read", "reparent": "edit", "get": "read", "create": "create", "update": "edit", "swap": "edit", "detach": "edit", "reset_overrides": "edit", "help": "read" }),
+    }, caps2, { "list": "read", "delete": "edit", "clone": "create", "scale": "edit", "audit": "read", "reparent": "edit", "get": "read", "create": "create", "update": "edit", "swap": "edit", "detach": "edit", "reset_overrides": "edit", "help": "read" }),
     tier: "read",
     validate: (params) => {
       const m = params.method;
@@ -2204,6 +2656,7 @@ var tools = [
         if (params.id === void 0) throw new Error('get requires "id"');
       }
       if (!params.items) return;
+      if (Array.isArray(params.items) && params.items.length === 0) throw new Error('items: [] is a no-op. Batch calls need at least one item. Omit items to use single-item params, or pass one or more item objects. Use instances(method: "help", topic: "' + m + '") to see valid item shapes.');
       if (m === "create") {
         for (const it of params.items) {
           if (it.id !== void 0 && it.componentId === void 0) {
@@ -2245,8 +2698,11 @@ var tools = [
             throw new Error(e.issues.map((i) => {
               const path = i.path.join(".");
               const shape = itemSchema instanceof z3.ZodObject ? itemSchema.shape : null;
-              const desc = shape?.[i.path[1]]?.description;
-              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "");
+              const field = String(i.path[1] ?? i.path[0] ?? "");
+              const desc = shape?.[field]?.description;
+              const paintField = field === "paints" || field === "fills" || field === "strokes";
+              const paintHelp = paintField ? ' Invalid Paint[] payload. Supported Paint[] authoring types: SOLID, GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; do not use CSS gradients or REST gradientHandlePositions. IMAGE/VIDEO/PATTERN are readback-only metadata, not Paint[] authoring input; use imageUrl/images for images. For examples call instances(method:"help", topic:"create").' : "";
+              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "") + paintHelp;
             }).join("; "));
           }
           throw e;
@@ -2254,11 +2710,11 @@ var tools = [
       }
       if (m === "update") {
         const itemSchema = z3.object({
-          fills: z3.array(z3.record(z3.string(), z3.unknown())).optional().describe("Fill paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] for transparent. Primary way to set fills."),
+          fills: paintArrayLoose.optional().describe("Fill Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] for transparent. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables; use imageUrl/images for image authoring. IMAGE/VIDEO/PATTERN may appear in readback metadata only. Primary way to set non-image fills."),
           fillColor: colorRgba.optional().describe("Shorthand \u2014 sets a single solid fill (auto-binds to matching variable/style)"),
           fillStyleName: z3.string().optional().describe("Paint style name for fill"),
-          fillVariableName: z3.string().optional().describe("Color variable by name e.g. 'bg/primary'"),
-          strokes: z3.array(z3.record(z3.string(), z3.unknown())).optional().describe("Stroke paints array \u2014 e.g. [{type: 'SOLID', color: '#hex'}] or [] to clear. Primary way to set strokes."),
+          fillVariableName: z3.string().optional().describe("Color variable by name e.g. 'bg/surface'"),
+          strokes: paintArrayLoose.optional().describe("Stroke Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. [] to clear. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables. IMAGE/VIDEO/PATTERN may appear in readback metadata only. Primary way to set strokes."),
           strokeColor: colorRgba.optional().describe("Shorthand \u2014 sets a single solid stroke (auto-binds to matching variable/style)"),
           strokeStyleName: z3.string().optional().describe("Paint style name for stroke"),
           strokeVariableName: z3.string().optional().describe("Color variable by name for stroke"),
@@ -2339,8 +2795,11 @@ var tools = [
             throw new Error(e.issues.map((i) => {
               const path = i.path.join(".");
               const shape = itemSchema instanceof z3.ZodObject ? itemSchema.shape : null;
-              const desc = shape?.[i.path[1]]?.description;
-              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "");
+              const field = String(i.path[1] ?? i.path[0] ?? "");
+              const desc = shape?.[field]?.description;
+              const paintField = field === "paints" || field === "fills" || field === "strokes";
+              const paintHelp = paintField ? ' Invalid Paint[] payload. Supported Paint[] authoring types: SOLID, GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; do not use CSS gradients or REST gradientHandlePositions. IMAGE/VIDEO/PATTERN are readback-only metadata, not Paint[] authoring input; use imageUrl/images for images. For examples call instances(method:"help", topic:"update").' : "";
+              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "") + paintHelp;
             }).join("; "));
           }
           throw e;
@@ -2358,8 +2817,11 @@ var tools = [
             throw new Error(e.issues.map((i) => {
               const path = i.path.join(".");
               const shape = itemSchema instanceof z3.ZodObject ? itemSchema.shape : null;
-              const desc = shape?.[i.path[1]]?.description;
-              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "");
+              const field = String(i.path[1] ?? i.path[0] ?? "");
+              const desc = shape?.[field]?.description;
+              const paintField = field === "paints" || field === "fills" || field === "strokes";
+              const paintHelp = paintField ? ' Invalid Paint[] payload. Supported Paint[] authoring types: SOLID, GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; do not use CSS gradients or REST gradientHandlePositions. IMAGE/VIDEO/PATTERN are readback-only metadata, not Paint[] authoring input; use imageUrl/images for images. For examples call instances(method:"help", topic:"swap").' : "";
+              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "") + paintHelp;
             }).join("; "));
           }
           throw e;
@@ -2376,8 +2838,11 @@ var tools = [
             throw new Error(e.issues.map((i) => {
               const path = i.path.join(".");
               const shape = itemSchema instanceof z3.ZodObject ? itemSchema.shape : null;
-              const desc = shape?.[i.path[1]]?.description;
-              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "");
+              const field = String(i.path[1] ?? i.path[0] ?? "");
+              const desc = shape?.[field]?.description;
+              const paintField = field === "paints" || field === "fills" || field === "strokes";
+              const paintHelp = paintField ? ' Invalid Paint[] payload. Supported Paint[] authoring types: SOLID, GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; do not use CSS gradients or REST gradientHandlePositions. IMAGE/VIDEO/PATTERN are readback-only metadata, not Paint[] authoring input; use imageUrl/images for images. For examples call instances(method:"help", topic:"detach").' : "";
+              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "") + paintHelp;
             }).join("; "));
           }
           throw e;
@@ -2394,15 +2859,18 @@ var tools = [
             throw new Error(e.issues.map((i) => {
               const path = i.path.join(".");
               const shape = itemSchema instanceof z3.ZodObject ? itemSchema.shape : null;
-              const desc = shape?.[i.path[1]]?.description;
-              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "");
+              const field = String(i.path[1] ?? i.path[0] ?? "");
+              const desc = shape?.[field]?.description;
+              const paintField = field === "paints" || field === "fills" || field === "strokes";
+              const paintHelp = paintField ? ' Invalid Paint[] payload. Supported Paint[] authoring types: SOLID, GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; do not use CSS gradients or REST gradientHandlePositions. IMAGE/VIDEO/PATTERN are readback-only metadata, not Paint[] authoring input; use imageUrl/images for images. For examples call instances(method:"help", topic:"reset_overrides").' : "";
+              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "") + paintHelp;
             }).join("; "));
           }
           throw e;
         }
       }
     },
-    commandMap: { "list": "instances.list", "delete": "instances.delete", "clone": "instances.clone", "audit": "instances.audit", "reparent": "instances.reparent", "get": "instances.get", "create": "instances.create", "update": "instances.update", "swap": "instances.swap", "detach": "instances.detach", "reset_overrides": "instances.reset_overrides" }
+    commandMap: { "list": "instances.list", "delete": "instances.delete", "clone": "instances.clone", "scale": "instances.scale", "audit": "instances.audit", "reparent": "instances.reparent", "get": "instances.get", "create": "instances.create", "update": "instances.update", "swap": "instances.swap", "detach": "instances.detach", "reset_overrides": "instances.reset_overrides" }
   },
   {
     name: "library",
@@ -2475,6 +2943,7 @@ var tools = [
     validate: (params) => {
       const m = params.method;
       if (!params.items) return;
+      if (Array.isArray(params.items) && params.items.length === 0) throw new Error('items: [] is a no-op. Batch calls need at least one item. Omit items to use single-item params, or pass one or more item objects. Use lint(method: "help", topic: "' + m + '") to see valid item shapes.');
       if (m === "fix") {
         for (const it of params.items) {
           if (it.id !== void 0 && it.nodeId === void 0) {
@@ -2494,8 +2963,11 @@ var tools = [
             throw new Error(e.issues.map((i) => {
               const path = i.path.join(".");
               const shape = itemSchema instanceof z3.ZodObject ? itemSchema.shape : null;
-              const desc = shape?.[i.path[1]]?.description;
-              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "");
+              const field = String(i.path[1] ?? i.path[0] ?? "");
+              const desc = shape?.[field]?.description;
+              const paintField = field === "paints" || field === "fills" || field === "strokes";
+              const paintHelp = paintField ? ' Invalid Paint[] payload. Supported Paint[] authoring types: SOLID, GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; do not use CSS gradients or REST gradientHandlePositions. IMAGE/VIDEO/PATTERN are readback-only metadata, not Paint[] authoring input; use imageUrl/images for images. For examples call lint(method:"help", topic:"fix").' : "";
+              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "") + paintHelp;
             }).join("; "));
           }
           throw e;
@@ -2546,6 +3018,7 @@ var tools = [
         if (params.index === void 0) throw new Error('remove requires "index"');
       }
       if (!params.items) return;
+      if (Array.isArray(params.items) && params.items.length === 0) throw new Error('items: [] is a no-op. Batch calls need at least one item. Omit items to use single-item params, or pass one or more item objects. Use prototyping(method: "help", topic: "' + m + '") to see valid item shapes.');
       if (m === "add") {
         const itemSchema = z3.object({
           id: z3.string().describe("Node ID"),
@@ -2571,8 +3044,11 @@ var tools = [
             throw new Error(e.issues.map((i) => {
               const path = i.path.join(".");
               const shape = itemSchema instanceof z3.ZodObject ? itemSchema.shape : null;
-              const desc = shape?.[i.path[1]]?.description;
-              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "");
+              const field = String(i.path[1] ?? i.path[0] ?? "");
+              const desc = shape?.[field]?.description;
+              const paintField = field === "paints" || field === "fills" || field === "strokes";
+              const paintHelp = paintField ? ' Invalid Paint[] payload. Supported Paint[] authoring types: SOLID, GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; do not use CSS gradients or REST gradientHandlePositions. IMAGE/VIDEO/PATTERN are readback-only metadata, not Paint[] authoring input; use imageUrl/images for images. For examples call prototyping(method:"help", topic:"add").' : "";
+              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "") + paintHelp;
             }).join("; "));
           }
           throw e;
@@ -2602,7 +3078,7 @@ var tools = [
   },
   {
     name: "styles",
-    description: '/** CRUD for local paint, text, effect, and grid styles. Use method "help" for detailed parameter docs. */\n  list      (type?: paint|text|effect|grid, fields?, offset?, limit?) \u2192 { totalCount, items }  // List local styles with optional type filter\n  get       (id, fields?) \u2192 { id, name, type, paints?, fontFamily?, fontSize?, effects?, layoutGrids? }  // Get full style detail by ID\n  create    (type: paint|text|effect|grid, items: (PaintItem | TextItem | EffectItem | GridItem)[]) \u2192 { results: {id}[] }  // Create local styles\n  update    (type?: paint|text|effect|grid, items: PatchStyleItem[]) \u2192 { results: ("ok" | {error})[] }  // Update styles by ID or name\n  delete    (id?, items?: { id: string }[]) \u2192 { results: "ok"[] }  // Delete styles\n// Styles are named, reusable design properties that can be applied to nodes. Four types:\n//   paint: a named color (applied to fills/strokes), text: typography settings, effect: shadows/blurs, grid: layout grids.\n// All ID params accept both IDs and display names (case-insensitive). Use whichever you have.',
+    description: '/** CRUD for local paint, text, effect, and grid styles. Use method "help" for detailed parameter docs. */\n  list      (type?: paint|text|effect|grid, fields?, offset?, limit?) \u2192 { totalCount, items }  // List local styles with optional type filter\n  get       (id, fields?) \u2192 { id, name, type, paints?: Paint[], boundVariables?, fontFamily?, fontSize?, effects?, layoutGrids? }  // Get full style detail by ID\n  create    (type: paint|text|effect|grid, items: (PaintItem | TextItem | EffectItem | GridItem)[]) \u2192 { results: {id}[] }  // Create local styles\n  update    (type?: paint|text|effect|grid, items: PatchStyleItem[]) \u2192 { results: ("ok" | {error})[] }  // Update styles by ID or name\n  delete    (id?, items?: { id: string }[]) \u2192 { results: "ok"[] }  // Delete styles\n// Styles are named, reusable design properties that can be applied to nodes. Four types:\n//   paint: named PaintStyle.paints (applied to fills/strokes), text: typography settings, effect: shadows/blurs, grid: layout grids.\n// All ID params accept both IDs and display names (case-insensitive). Use whichever you have.\n// Shared types:\n// Color: hex "#RGB"|"#RGBA"|"#RRGGBB"|"#RRGGBBAA" or {r: 0-1, g: 0-1, b: 0-1, a?: 0-1}\n// VariableAlias: {type: "VARIABLE_ALIAS", id: string}. The id must be a Figma VariableID; discover it via variables.get/list or variable_collections.get. Prefer colorVariableName/fillVariableName/strokeVariableName when available; Paint[] VariableAlias is mainly for precise Paint[] round-trips and gradient stop bindings.\n// Transform: [[number, number, number], [number, number, number]] (Figma Plugin API 2\xD73 matrix)\n// BlendMode: "PASS_THROUGH"|"NORMAL"|"DARKEN"|"MULTIPLY"|"LINEAR_BURN"|"COLOR_BURN"|"LIGHTEN"|"SCREEN"|"LINEAR_DODGE"|"COLOR_DODGE"|"OVERLAY"|"SOFT_LIGHT"|"HARD_LIGHT"|"DIFFERENCE"|"EXCLUSION"|"HUE"|"SATURATION"|"COLOR"|"LUMINOSITY"\n// ColorStop: {position: 0-1, color: Color, boundVariables?: {color?: VariableAlias}}\n// GradientPaint: {type: "GRADIENT_LINEAR"|"GRADIENT_RADIAL"|"GRADIENT_ANGULAR"|"GRADIENT_DIAMOND", gradientTransform: Transform, gradientStops: ColorStop[], visible?: boolean, opacity?: number, blendMode?: BlendMode}. Use gradientTransform + gradientStops (basic left-to-right: [[1,0,0],[0,1,0]]); do not use CSS gradients or REST gradientHandlePositions.\n// Paint: Paint[] authoring accepts only SOLID and GRADIENT_LINEAR/GRADIENT_RADIAL/GRADIENT_ANGULAR/GRADIENT_DIAMOND. SolidPaint: {type: "SOLID", color: Color, visible?: boolean, opacity?: number, blendMode?: BlendMode, boundVariables?: {color?: VariableAlias}}. GradientPaint authoring: {type: GRADIENT_*, gradientTransform: Transform, gradientStops: ColorStop[], visible?, opacity?, blendMode?}; bind variables on gradientStops[].boundVariables.color, not top-level gradient boundVariables. Do not pass IMAGE/VIDEO/PATTERN to create/update Paint[]; those may appear only in readback metadata from existing Figma content. Use imageUrl/images for image authoring. VIDEO/PATTERN authoring is not supported here. Do not use CSS gradients or REST gradientHandlePositions.',
     schema: (caps2) => filterMethodsByTier({
       method: z3.enum(["list", "get", "create", "update", "delete", "help"]),
       type: z3.enum(["paint", "text", "effect", "grid"]).optional().describe("Filter by style type"),
@@ -2619,13 +3095,21 @@ var tools = [
       if (m === "get") {
         if (params.id === void 0) throw new Error('get requires "id"');
       }
+      if (m === "create") {
+        const itemDiscriminant = Array.isArray(params.items) ? params.items.find((it) => it && typeof it === "object" && typeof it.type === "string")?.type : void 0;
+        if (params.type === void 0) {
+          throw new Error(itemDiscriminant ? 'styles.create uses top-level "type", not "type" inside items. Move the item value to the top level and use help for valid item shapes.' : 'styles.create requires top-level "type" (paint, text, effect, grid). Use styles(method: "help", topic: "create") for valid item shapes.');
+        }
+      }
       if (!params.items) return;
+      if (Array.isArray(params.items) && params.items.length === 0) throw new Error('items: [] is a no-op. Batch calls need at least one item. Omit items to use single-item params, or pass one or more item objects. Use styles(method: "help", topic: "' + m + '") to see valid item shapes.');
       if (m === "create") {
         const schemas = {
           "paint": z3.object({
             name: z3.string().describe("Style name"),
-            color: colorRgba.optional().describe("Color value. Optional when colorVariableName is provided."),
-            colorVariableName: z3.string().optional().describe("Bind to a COLOR variable by name (style tracks the variable). Can be used alone \u2014 color is resolved from the variable."),
+            paints: paintArrayLoose.optional().describe('PaintStyle.paints authoring array. Accepts only SOLID and GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND, using gradientTransform + gradientStops, opacity/blendMode, and gradientStops[].boundVariables.color. Mutually exclusive with color/colorVariableName shorthands. Do not pass IMAGE/VIDEO/PATTERN, CSS gradients, REST gradientHandlePositions, or top-level gradient boundVariables. Use imageUrl/images for image authoring on nodes; VIDEO/PATTERN authoring is not supported here. For examples call styles(method:"help", topic:"create").'),
+            color: colorRgba.optional().describe("Single-solid shorthand color. Optional when colorVariableName or paints is provided."),
+            colorVariableName: z3.string().optional().describe("Single-solid shorthand: bind to a COLOR variable by name (style tracks the variable). Can be used alone \u2014 color is resolved from the variable."),
             description: z3.string().optional().describe("Style description")
           }).passthrough(),
           "text": z3.object({
@@ -2649,25 +3133,27 @@ var tools = [
           }).passthrough(),
           "grid": z3.object({
             name: z3.string().describe("Style name"),
-            layoutGrids: flexJson(z3.array(z3.record(z3.string(), z3.unknown()))).describe("Array of LayoutGrid objects"),
+            layoutGrids: flexJson(z3.array(z3.record(z3.string(), z3.unknown()))).describe("Array of LayoutGrid objects. Conditional shapes: GRID requires sectionSize and does not use alignment/count/gutterSize/offset; ROWS/COLUMNS use alignment/count/gutterSize/offset, and sectionSize only for fixed alignments MIN/MAX/CENTER. For alignment:STRETCH, omit sectionSize."),
             description: z3.string().optional().describe("Style description")
           }).passthrough()
         };
         const s = params.type && schemas[params.type];
-        if (s) {
-          try {
-            params.items = z3.array(s).parse(params.items);
-          } catch (e) {
-            if (e instanceof z3.ZodError) {
-              throw new Error(e.issues.map((i) => {
-                const path = i.path.join(".");
-                const shape = s instanceof z3.ZodObject ? s.shape : null;
-                const desc = shape?.[i.path[1]]?.description;
-                return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "");
-              }).join("; "));
-            }
-            throw e;
+        if (!s) throw new Error('styles.create: unknown type. Use styles(method: "help", topic: "create") for valid types and item shapes.');
+        try {
+          params.items = z3.array(s).parse(params.items);
+        } catch (e) {
+          if (e instanceof z3.ZodError) {
+            throw new Error(e.issues.map((i) => {
+              const path = i.path.join(".");
+              const shape = s instanceof z3.ZodObject ? s.shape : null;
+              const field = String(i.path[1] ?? i.path[0] ?? "");
+              const desc = shape?.[field]?.description;
+              const paintField = field === "paints" || field === "fills" || field === "strokes";
+              const paintHelp = paintField ? ' Invalid Paint[] payload. Supported Paint[] authoring types: SOLID, GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; do not use CSS gradients or REST gradientHandlePositions. IMAGE/VIDEO/PATTERN are readback-only metadata, not Paint[] authoring input; use imageUrl/images for images. For examples call styles(method:"help", topic:"create").' : "";
+              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "") + paintHelp;
+            }).join("; "));
           }
+          throw e;
         }
       }
       if (m === "update") {
@@ -2675,8 +3161,9 @@ var tools = [
           id: z3.string().describe("Style ID or name"),
           name: z3.string().optional().describe("Rename the style"),
           description: z3.string().optional().describe("Style description"),
-          color: colorRgba.optional().describe("New color (paint styles)"),
-          colorVariableName: z3.string().optional().describe("Bind to a COLOR variable by name (paint styles)"),
+          paints: paintArrayLoose.optional().describe('Replace PaintStyle.paints. Accepts only SOLID and GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND, using gradientTransform + gradientStops, opacity/blendMode, and gradientStops[].boundVariables.color. Mutually exclusive with color/colorVariableName. Do not pass IMAGE/VIDEO/PATTERN, CSS gradients, REST gradientHandlePositions, or top-level gradient boundVariables. Use imageUrl/images for image authoring on nodes; VIDEO/PATTERN authoring is not supported here. For examples call styles(method:"help", topic:"update").'),
+          color: colorRgba.optional().describe("New single-solid color shorthand (paint styles)"),
+          colorVariableName: z3.string().optional().describe("Bind to a COLOR variable by name using single-solid shorthand (paint styles)"),
           fontFamily: z3.string().optional(),
           fontStyle: z3.string().optional(),
           fontSize: z3.coerce.number().optional(),
@@ -2688,7 +3175,7 @@ var tools = [
           paragraphSpacing: z3.coerce.number().optional().describe("Paragraph spacing (px)"),
           leadingTrim: z3.enum(["CAP_HEIGHT", "NONE"]).optional(),
           effects: flexJson(z3.array(z3.record(z3.string(), z3.unknown()))).optional().describe("Array of Effect objects"),
-          layoutGrids: flexJson(z3.array(z3.record(z3.string(), z3.unknown()))).optional().describe("Array of LayoutGrid objects (grid styles)")
+          layoutGrids: flexJson(z3.array(z3.record(z3.string(), z3.unknown()))).optional().describe("Array of LayoutGrid objects (grid styles). Conditional shapes: GRID requires sectionSize and does not use alignment/count/gutterSize/offset; ROWS/COLUMNS use alignment/count/gutterSize/offset, and sectionSize only for fixed alignments MIN/MAX/CENTER. For alignment:STRETCH, omit sectionSize.")
         }).passthrough();
         try {
           params.items = z3.array(itemSchema).parse(params.items);
@@ -2697,8 +3184,11 @@ var tools = [
             throw new Error(e.issues.map((i) => {
               const path = i.path.join(".");
               const shape = itemSchema instanceof z3.ZodObject ? itemSchema.shape : null;
-              const desc = shape?.[i.path[1]]?.description;
-              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "");
+              const field = String(i.path[1] ?? i.path[0] ?? "");
+              const desc = shape?.[field]?.description;
+              const paintField = field === "paints" || field === "fills" || field === "strokes";
+              const paintHelp = paintField ? ' Invalid Paint[] payload. Supported Paint[] authoring types: SOLID, GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; do not use CSS gradients or REST gradientHandlePositions. IMAGE/VIDEO/PATTERN are readback-only metadata, not Paint[] authoring input; use imageUrl/images for images. For examples call styles(method:"help", topic:"update").' : "";
+              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "") + paintHelp;
             }).join("; "));
           }
           throw e;
@@ -2715,8 +3205,11 @@ var tools = [
             throw new Error(e.issues.map((i) => {
               const path = i.path.join(".");
               const shape = itemSchema instanceof z3.ZodObject ? itemSchema.shape : null;
-              const desc = shape?.[i.path[1]]?.description;
-              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "");
+              const field = String(i.path[1] ?? i.path[0] ?? "");
+              const desc = shape?.[field]?.description;
+              const paintField = field === "paints" || field === "fills" || field === "strokes";
+              const paintHelp = paintField ? ' Invalid Paint[] payload. Supported Paint[] authoring types: SOLID, GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; do not use CSS gradients or REST gradientHandlePositions. IMAGE/VIDEO/PATTERN are readback-only metadata, not Paint[] authoring input; use imageUrl/images for images. For examples call styles(method:"help", topic:"delete").' : "";
+              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "") + paintHelp;
             }).join("; "));
           }
           throw e;
@@ -2727,9 +3220,9 @@ var tools = [
   },
   {
     name: "text",
-    description: '/** Create and manage text nodes. Use method "help" for detailed parameter docs. */\n  get       (id, fields?, depth?, verbose?) \u2192 { results: Node[], _truncated?, _notice? }  // Get serialized node data\n  list      (query?, types?, parentId?, fields?, offset?, limit?) \u2192 { totalCount, returned?, offset?, limit?, results }  // Search for nodes (returns stubs only \u2014 use get with depth for full properties)\n  update    (items: PatchItem[]) \u2192 { results: ("ok" | {error})[] }  // Patch node properties\n  delete    (id?, items?: { id?: string }[]) \u2192 { results: "ok"[] }  // Delete nodes\n  clone     (id?, name?, parentId?, x?, y?, items?: { id: string; name?: string; parentId?: string; x?: number; y?: number }[], depth?) \u2192 { results: {id}[] }  // Duplicate nodes \u2014 produces a same-type copy (frame\u2192frame, instance\u2192instance, component\u2192component). Instance clones reference the same source component; they do not duplicate the component definition.\n  audit     (id, rules?, maxDepth?, maxFindings?, minSeverity?: error|unsafe|heuristic|style|verbose, skipInstances?) \u2192 { nodeId?, nodeName?, categories? }  // Run lint on a node \u2014 returns severity-ranked findings\n  reparent  (items: { id: string; parentId: string; index?: number }[]) \u2192 { results: "ok"[] }  // Move nodes into a new parent\n  create    (items: TextItem[], depth?) \u2192 { results: {id}[] }  // Create text nodes\n  set_content(items: { nodeId: string; text: string }[], depth?) \u2192 { results: "ok"[] }  // Replace text content on existing text nodes\n  scan      (items: { nodeId: string; limit?: number; includePath?: boolean; includeGeometry?: boolean }[]) \u2192 { results: ("ok" | {error})[] }  // Scan all text nodes within a subtree\n// depth: omit \u2192 id+name stubs | 0 \u2192 props + child stubs | N \u2192 recurse N | -1 \u2192 full tree\n// fields: whitelist e.g. ["fills","opacity"] \u2014 id, name, type always included. Pass ["*"] for all.\n// layoutSizingHorizontal/Vertical: FIXED | HUG | FILL \u2014 how the node sizes within auto-layout.\n// Colors: fillVariableName/strokeVariableName bind by name \u2014 preferred over raw color values.\n// Note: node-based endpoints (frames, text, instances, components) use `results` as the list key.\n//   Standalone endpoints (styles, variables, variable_collections) use `items`. Components.list uses `items` (catalog view).',
+    description: '/** Create and manage text nodes. Use method "help" for detailed parameter docs. */\n  get       (id, fields?, depth?, verbose?) \u2192 { results: Node[], _truncated?, _notice? }  // Get serialized node data\n  list      (query?, types?, parentId?, fields?, offset?, limit?) \u2192 { totalCount, returned?, offset?, limit?, results }  // Search for nodes (returns stubs only \u2014 use get with depth for full properties)\n  update    (items: PatchItem[]) \u2192 { results: ("ok" | {error})[] }  // Patch node properties\n  delete    (id?, items?: { id?: string }[]) \u2192 { results: "ok"[] }  // Delete nodes\n  clone     (id?, name?, parentId?, x?, y?, items?: { id: string; name?: string; parentId?: string; x?: number; y?: number }[], depth?) \u2192 { results: {id}[] }  // Duplicate nodes \u2014 produces a same-type copy (frame\u2192frame, instance\u2192instance, component\u2192component). Instance clones reference the same source component; they do not duplicate the component definition.\n  scale     (id?, factor?, items?: { id: string; factor: number }[]) \u2192 { results: "ok"[] }  // Proportionally rescale a node subtree using Figma\'s visual Scale tool behavior. This is for visual/artifact scaling, not responsive layout resizing.\n  audit     (id, rules?, maxDepth?, maxFindings?, minSeverity?: error|unsafe|heuristic|style|verbose, skipInstances?) \u2192 { nodeId?, nodeName?, categories? }  // Run lint on a node \u2014 returns severity-ranked findings\n  reparent  (items: { id: string; parentId: string; index?: number }[]) \u2192 { results: "ok"[] }  // Move nodes into a new parent\n  create    (items: TextItem[], depth?) \u2192 { results: {id}[] }  // Create text nodes\n  set_content(items: { nodeId: string; text: string }[], depth?) \u2192 { results: "ok"[] }  // Replace text content on existing text nodes\n  scan      (items: { nodeId: string; limit?: number; includePath?: boolean; includeGeometry?: boolean }[]) \u2192 { results: ("ok" | {error})[] }  // Scan all text nodes within a subtree\n// depth: omit \u2192 id+name stubs | 0 \u2192 props + child stubs | N \u2192 recurse N | -1 \u2192 full tree\n// fields: whitelist e.g. ["fills","opacity"] \u2014 id, name, type always included. Pass ["*"] for all.\n// layoutSizingHorizontal/Vertical: FIXED | HUG | FILL \u2014 how the node sizes within auto-layout.\n// Colors: fillVariableName/strokeVariableName bind by name \u2014 preferred over raw color values.\n// Note: node-based endpoints (frames, text, instances, components) use `results` as the list key.\n//   Standalone endpoints (styles, variables, variable_collections) use `items`. Components.list uses `items` (catalog view).',
     schema: (caps2) => filterMethodsByTier({
-      method: z3.enum(["get", "list", "update", "delete", "clone", "audit", "reparent", "create", "set_content", "scan", "help"]),
+      method: z3.enum(["get", "list", "update", "delete", "clone", "scale", "audit", "reparent", "create", "set_content", "scan", "help"]),
       id: z3.string().optional().describe("Node ID"),
       fields: flexStringList(z3.array(z3.string())).optional().describe('Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.'),
       depth: z3.coerce.number().optional().describe("Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited."),
@@ -2739,21 +3232,23 @@ var tools = [
       parentId: z3.string().optional().describe("Search only within this subtree"),
       offset: z3.coerce.number().optional().default(0).describe("Skip N items for pagination (default 0)"),
       limit: z3.coerce.number().optional().default(100).describe("Max items per page (default 100)"),
-      items: flexJson(z3.array(z3.record(z3.string(), z3.unknown()))).optional().describe("Array of {id, ...properties} to update/delete/clone/reparent/create/set_content/scan"),
+      items: flexJson(z3.array(z3.record(z3.string(), z3.unknown()))).optional().describe("Array of {id, ...properties} to update/delete/clone/scale/reparent/create/set_content/scan"),
       name: z3.string().optional().describe("Rename the clone (set before appending to parent \u2014 required when cloning a variant into its component set to avoid duplicate names)"),
       x: z3.coerce.number().optional().describe("X position (default: 0)"),
       y: z3.coerce.number().optional().describe("Y position (default: 0)"),
+      factor: z3.coerce.number().optional().describe("Scale factor, >= 0.01. 0.5 = 50%, 2 = 200%. Scales children, text, strokes, effects, and layout geometry from the node's top-left. On auto-layout or HUG/FILL nodes, Figma may resolve responsive sizing to fixed width/height."),
       rules: flexStringList(z3.array(z3.string())).optional().describe('Rules to check. Default: ["all"]. Categories: "component", "composition", "token", "naming", "wcag".'),
       maxDepth: z3.coerce.number().optional().describe("Max tree depth (default: 10)"),
       maxFindings: z3.coerce.number().optional().describe("Max findings (default: 50)"),
       minSeverity: z3.enum(["error", "unsafe", "heuristic", "style", "verbose"]).optional().describe("Minimum severity to report (default: style). Set to 'verbose' to include AAA contrast and line-height checks."),
       skipInstances: flexBool(z3.boolean()).optional().describe("Skip instance internals \u2014 findings inside instances are owned by the component (default: true)"),
       topic: z3.string().optional().describe('Help topic \u2014 method name for endpoint help, e.g. "create"')
-    }, caps2, { "get": "read", "list": "read", "update": "edit", "delete": "edit", "clone": "create", "audit": "read", "reparent": "edit", "create": "create", "set_content": "edit", "scan": "read", "help": "read" }),
+    }, caps2, { "get": "read", "list": "read", "update": "edit", "delete": "edit", "clone": "create", "scale": "edit", "audit": "read", "reparent": "edit", "create": "create", "set_content": "edit", "scan": "read", "help": "read" }),
     tier: "read",
     validate: (params) => {
       const m = params.method;
       if (!params.items) return;
+      if (Array.isArray(params.items) && params.items.length === 0) throw new Error('items: [] is a no-op. Batch calls need at least one item. Omit items to use single-item params, or pass one or more item objects. Use text(method: "help", topic: "' + m + '") to see valid item shapes.');
       if (m === "create") {
         for (const it of params.items) {
           if (it.characters !== void 0 && it.text === void 0) {
@@ -2776,7 +3271,7 @@ var tools = [
           letterSpacing: letterSpacing.optional(),
           textCase: z3.enum(["ORIGINAL", "UPPER", "LOWER", "TITLE", "SMALL_CAPS", "SMALL_CAPS_FORCED"]).optional(),
           textDecoration: z3.enum(["NONE", "UNDERLINE", "STRIKETHROUGH"]).optional(),
-          fills: z3.array(z3.record(z3.string(), z3.unknown())).optional().describe("Text color paints \u2014 e.g. [{type: 'SOLID', color: '#hex'}]. Same as node fills."),
+          fills: paintArrayLoose.optional().describe("Text Paint[] authoring \u2014 accepts only SOLID or GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND with gradientTransform + gradientStops. Same as node fills. Do not use CSS gradients, REST gradientHandlePositions, IMAGE/VIDEO/PATTERN, or top-level gradient boundVariables. IMAGE/VIDEO/PATTERN may appear in readback metadata only."),
           fontColor: colorRgba.optional().describe("Shorthand \u2014 sets text color (auto-binds to matching variable/style)"),
           fontColorVariableName: z3.string().optional().describe("Bind color variable by name e.g. 'text/primary'"),
           fontColorStyleName: z3.string().optional().describe("Apply paint style \u2014 overrides fontColor"),
@@ -2798,8 +3293,11 @@ var tools = [
             throw new Error(e.issues.map((i) => {
               const path = i.path.join(".");
               const shape = itemSchema instanceof z3.ZodObject ? itemSchema.shape : null;
-              const desc = shape?.[i.path[1]]?.description;
-              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "");
+              const field = String(i.path[1] ?? i.path[0] ?? "");
+              const desc = shape?.[field]?.description;
+              const paintField = field === "paints" || field === "fills" || field === "strokes";
+              const paintHelp = paintField ? ' Invalid Paint[] payload. Supported Paint[] authoring types: SOLID, GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; do not use CSS gradients or REST gradientHandlePositions. IMAGE/VIDEO/PATTERN are readback-only metadata, not Paint[] authoring input; use imageUrl/images for images. For examples call text(method:"help", topic:"create").' : "";
+              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "") + paintHelp;
             }).join("; "));
           }
           throw e;
@@ -2827,19 +3325,22 @@ var tools = [
             throw new Error(e.issues.map((i) => {
               const path = i.path.join(".");
               const shape = itemSchema instanceof z3.ZodObject ? itemSchema.shape : null;
-              const desc = shape?.[i.path[1]]?.description;
-              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "");
+              const field = String(i.path[1] ?? i.path[0] ?? "");
+              const desc = shape?.[field]?.description;
+              const paintField = field === "paints" || field === "fills" || field === "strokes";
+              const paintHelp = paintField ? ' Invalid Paint[] payload. Supported Paint[] authoring types: SOLID, GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; do not use CSS gradients or REST gradientHandlePositions. IMAGE/VIDEO/PATTERN are readback-only metadata, not Paint[] authoring input; use imageUrl/images for images. For examples call text(method:"help", topic:"set_content").' : "";
+              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "") + paintHelp;
             }).join("; "));
           }
           throw e;
         }
       }
     },
-    commandMap: { "get": "text.get", "list": "text.list", "update": "text.update", "delete": "text.delete", "clone": "text.clone", "audit": "text.audit", "reparent": "text.reparent", "create": "text.create", "set_content": "text.set_content", "scan": "text.scan" }
+    commandMap: { "get": "text.get", "list": "text.list", "update": "text.update", "delete": "text.delete", "clone": "text.clone", "scale": "text.scale", "audit": "text.audit", "reparent": "text.reparent", "create": "text.create", "set_content": "text.set_content", "scan": "text.scan" }
   },
   {
     name: "variable_collections",
-    description: '/** CRUD for variable collections \u2014 the document-level API for design tokens. Use method "help" for detailed parameter docs. */\n  list      (fields?, offset?, limit?) \u2192 { totalCount, items }  // List variable collections\n  get       (id, fields?) \u2192 { id?, name?, modes?, variables? }  // Get collection with all variables and values (full document)\n  create    (items: { name: string; modes?: string[]; variables?: { name: string; type: "COLOR" | "FLOAT" | "STRING" | "BOOLEAN"; value?: number | boolean | string | Color | {type: "VARIABLE_ALIAS", name: string}; valuesByMode?: Record<string, unknown>; description?: string; scopes?: string[] }[] }[]) \u2192 { results: {id}[] }  // Create a collection with modes and variables in one call\n  update    (items: { id: string; name: string }[]) \u2192 { results: ("ok" | {error})[] }  // Rename collections\n  delete    (id?, items?: { id: string }[]) \u2192 { results: "ok"[] }  // Delete collections\n  add_mode  (items: { collectionId: string; name: string }[]) \u2192 { results: {modeId}[] }  // Add a mode to a collection\n  rename_mode(items: { collectionId: string; modeId: string; name: string }[]) \u2192 { results: ("ok" | {error})[] }  // Rename a mode\n  remove_mode(items: { collectionId: string; modeId: string }[]) \u2192 { results: "ok"[] }  // Remove a mode from a collection\n// Variable collections group design tokens and define their modes (e.g. Light/Dark, Desktop/Mobile).\n// All ID params accept both IDs and display names.\n// Shared types:\n// Color: hex "#FF0000" or {r: 0-1, g: 0-1, b: 0-1, a?: 0-1}',
+    description: '/** CRUD for variable collections \u2014 the document-level API for design tokens. Use method "help" for detailed parameter docs. */\n  list      (fields?, offset?, limit?) \u2192 { totalCount, items }  // List variable collections\n  get       (id, fields?) \u2192 { id?, name?, modes?, variables? }  // Get collection with all variables and values (full document)\n  create    (items: { name: string; modes?: string[]; variables?: { name: string; type: "COLOR" | "FLOAT" | "STRING" | "BOOLEAN"; value?: number | boolean | string | Color | {type: "VARIABLE_ALIAS", name: string}; valuesByMode?: Record<string, unknown>; description?: string; scopes?: string[] }[] }[]) \u2192 { results: {id}[] }  // Create a collection with modes and variables in one call\n  update    (items: { id: string; name: string }[]) \u2192 { results: ("ok" | {error})[] }  // Rename collections\n  delete    (id?, items?: { id: string }[]) \u2192 { results: "ok"[] }  // Delete collections\n  add_mode  (items: { collectionId: string; name: string }[]) \u2192 { results: {modeId}[] }  // Add a mode to a collection\n  rename_mode(items: { collectionId: string; modeId: string; name: string }[]) \u2192 { results: ("ok" | {error})[] }  // Rename a mode\n  remove_mode(items: { collectionId: string; modeId: string }[]) \u2192 { results: "ok"[] }  // Remove a mode from a collection\n// Variable collections group design tokens and define their modes (e.g. Light/Dark, Desktop/Mobile).\n// All ID params accept both IDs and display names.\n// Shared types:\n// Color: hex "#RGB"|"#RGBA"|"#RRGGBB"|"#RRGGBBAA" or {r: 0-1, g: 0-1, b: 0-1, a?: 0-1}',
     schema: (caps2) => filterMethodsByTier({
       method: z3.enum(["list", "get", "create", "update", "delete", "add_mode", "rename_mode", "remove_mode", "help"]),
       fields: flexStringList(z3.array(z3.string())).optional().describe('Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.'),
@@ -2856,6 +3357,7 @@ var tools = [
         if (params.id === void 0) throw new Error('get requires "id"');
       }
       if (!params.items) return;
+      if (Array.isArray(params.items) && params.items.length === 0) throw new Error('items: [] is a no-op. Batch calls need at least one item. Omit items to use single-item params, or pass one or more item objects. Use variable_collections(method: "help", topic: "' + m + '") to see valid item shapes.');
       if (m === "create") {
         const itemSchema = z3.object({
           name: z3.string().describe("Collection name"),
@@ -2869,8 +3371,11 @@ var tools = [
             throw new Error(e.issues.map((i) => {
               const path = i.path.join(".");
               const shape = itemSchema instanceof z3.ZodObject ? itemSchema.shape : null;
-              const desc = shape?.[i.path[1]]?.description;
-              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "");
+              const field = String(i.path[1] ?? i.path[0] ?? "");
+              const desc = shape?.[field]?.description;
+              const paintField = field === "paints" || field === "fills" || field === "strokes";
+              const paintHelp = paintField ? ' Invalid Paint[] payload. Supported Paint[] authoring types: SOLID, GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; do not use CSS gradients or REST gradientHandlePositions. IMAGE/VIDEO/PATTERN are readback-only metadata, not Paint[] authoring input; use imageUrl/images for images. For examples call variable_collections(method:"help", topic:"create").' : "";
+              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "") + paintHelp;
             }).join("; "));
           }
           throw e;
@@ -2888,8 +3393,11 @@ var tools = [
             throw new Error(e.issues.map((i) => {
               const path = i.path.join(".");
               const shape = itemSchema instanceof z3.ZodObject ? itemSchema.shape : null;
-              const desc = shape?.[i.path[1]]?.description;
-              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "");
+              const field = String(i.path[1] ?? i.path[0] ?? "");
+              const desc = shape?.[field]?.description;
+              const paintField = field === "paints" || field === "fills" || field === "strokes";
+              const paintHelp = paintField ? ' Invalid Paint[] payload. Supported Paint[] authoring types: SOLID, GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; do not use CSS gradients or REST gradientHandlePositions. IMAGE/VIDEO/PATTERN are readback-only metadata, not Paint[] authoring input; use imageUrl/images for images. For examples call variable_collections(method:"help", topic:"update").' : "";
+              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "") + paintHelp;
             }).join("; "));
           }
           throw e;
@@ -2906,8 +3414,11 @@ var tools = [
             throw new Error(e.issues.map((i) => {
               const path = i.path.join(".");
               const shape = itemSchema instanceof z3.ZodObject ? itemSchema.shape : null;
-              const desc = shape?.[i.path[1]]?.description;
-              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "");
+              const field = String(i.path[1] ?? i.path[0] ?? "");
+              const desc = shape?.[field]?.description;
+              const paintField = field === "paints" || field === "fills" || field === "strokes";
+              const paintHelp = paintField ? ' Invalid Paint[] payload. Supported Paint[] authoring types: SOLID, GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; do not use CSS gradients or REST gradientHandlePositions. IMAGE/VIDEO/PATTERN are readback-only metadata, not Paint[] authoring input; use imageUrl/images for images. For examples call variable_collections(method:"help", topic:"delete").' : "";
+              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "") + paintHelp;
             }).join("; "));
           }
           throw e;
@@ -2925,8 +3436,11 @@ var tools = [
             throw new Error(e.issues.map((i) => {
               const path = i.path.join(".");
               const shape = itemSchema instanceof z3.ZodObject ? itemSchema.shape : null;
-              const desc = shape?.[i.path[1]]?.description;
-              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "");
+              const field = String(i.path[1] ?? i.path[0] ?? "");
+              const desc = shape?.[field]?.description;
+              const paintField = field === "paints" || field === "fills" || field === "strokes";
+              const paintHelp = paintField ? ' Invalid Paint[] payload. Supported Paint[] authoring types: SOLID, GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; do not use CSS gradients or REST gradientHandlePositions. IMAGE/VIDEO/PATTERN are readback-only metadata, not Paint[] authoring input; use imageUrl/images for images. For examples call variable_collections(method:"help", topic:"add_mode").' : "";
+              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "") + paintHelp;
             }).join("; "));
           }
           throw e;
@@ -2945,8 +3459,11 @@ var tools = [
             throw new Error(e.issues.map((i) => {
               const path = i.path.join(".");
               const shape = itemSchema instanceof z3.ZodObject ? itemSchema.shape : null;
-              const desc = shape?.[i.path[1]]?.description;
-              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "");
+              const field = String(i.path[1] ?? i.path[0] ?? "");
+              const desc = shape?.[field]?.description;
+              const paintField = field === "paints" || field === "fills" || field === "strokes";
+              const paintHelp = paintField ? ' Invalid Paint[] payload. Supported Paint[] authoring types: SOLID, GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; do not use CSS gradients or REST gradientHandlePositions. IMAGE/VIDEO/PATTERN are readback-only metadata, not Paint[] authoring input; use imageUrl/images for images. For examples call variable_collections(method:"help", topic:"rename_mode").' : "";
+              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "") + paintHelp;
             }).join("; "));
           }
           throw e;
@@ -2964,8 +3481,11 @@ var tools = [
             throw new Error(e.issues.map((i) => {
               const path = i.path.join(".");
               const shape = itemSchema instanceof z3.ZodObject ? itemSchema.shape : null;
-              const desc = shape?.[i.path[1]]?.description;
-              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "");
+              const field = String(i.path[1] ?? i.path[0] ?? "");
+              const desc = shape?.[field]?.description;
+              const paintField = field === "paints" || field === "fills" || field === "strokes";
+              const paintHelp = paintField ? ' Invalid Paint[] payload. Supported Paint[] authoring types: SOLID, GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; do not use CSS gradients or REST gradientHandlePositions. IMAGE/VIDEO/PATTERN are readback-only metadata, not Paint[] authoring input; use imageUrl/images for images. For examples call variable_collections(method:"help", topic:"remove_mode").' : "";
+              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "") + paintHelp;
             }).join("; "));
           }
           throw e;
@@ -2976,7 +3496,7 @@ var tools = [
   },
   {
     name: "variables",
-    description: '/** Search and update design variables within a collection. Use method "help" for detailed parameter docs. */\n  list      (collectionId, query?, type?: COLOR|FLOAT|STRING|BOOLEAN, fields?, offset?, limit?) \u2192 { totalCount, items }  // Search variables within a collection\n  get       (name, collectionId, fields?) \u2192 { name, type, collectionId, valuesByMode: Record<string, number | boolean | string | Color | {type: "VARIABLE_ALIAS", name: string}>, description?, scopes? }  // Get variable detail by name\n  create    (collectionId, items: VariableCreateItem[]) \u2192 { results: {name}[] }  // Create variables in a collection. Use valuesByMode for per-mode control, or value to set all modes at once.\n  update    (collectionId, items: VariableUpdateItem[]) \u2192 { results: ("ok" | {error})[] }  // Update variable metadata and/or set values\n  delete    (collectionId, name?, items?: { name: string }[]) \u2192 { results: "ok"[] }  // Delete variables\n// Search and update variables within a collection. collectionId is required on all methods.\n// Use variable_collections to create full token sets (collection + modes + variables in one call).\n// Shared types:\n// Color: hex "#FF0000" or {r: 0-1, g: 0-1, b: 0-1, a?: 0-1}',
+    description: '/** Search and update design variables within a collection. Use method "help" for detailed parameter docs. */\n  list      (collectionId, query?, type?: COLOR|FLOAT|STRING|BOOLEAN, fields?, offset?, limit?) \u2192 { totalCount, items }  // Search variables within a collection\n  get       (name, collectionId, fields?) \u2192 { id, name, type, collectionId, valuesByMode: Record<string, number | boolean | string | Color | {type: "VARIABLE_ALIAS", name: string}>, description?, scopes? }  // Get variable detail by name\n  create    (collectionId, items: VariableCreateItem[]) \u2192 { results: {id, name}[] }  // Create variables in a collection. Use valuesByMode for per-mode control, or value to set all modes at once.\n  update    (collectionId, items: VariableUpdateItem[]) \u2192 { results: ("ok" | {error})[] }  // Update variable metadata and/or set values\n  delete    (collectionId, name?, items?: { name: string }[]) \u2192 { results: "ok"[] }  // Delete variables\n// Search and update variables within a collection. collectionId is required on all methods.\n// Use variable_collections to create full token sets (collection + modes + variables in one call).\n// Shared types:\n// Color: hex "#RGB"|"#RGBA"|"#RRGGBB"|"#RRGGBBAA" or {r: 0-1, g: 0-1, b: 0-1, a?: 0-1}',
     schema: (caps2) => filterMethodsByTier({
       method: z3.enum(["list", "get", "create", "update", "delete", "help"]),
       collectionId: z3.string().optional().describe("Collection ID or name"),
@@ -3009,6 +3529,7 @@ var tools = [
         if (params.collectionId === void 0) throw new Error('delete requires "collectionId"');
       }
       if (!params.items) return;
+      if (Array.isArray(params.items) && params.items.length === 0) throw new Error('items: [] is a no-op. Batch calls need at least one item. Omit items to use single-item params, or pass one or more item objects. Use variables(method: "help", topic: "' + m + '") to see valid item shapes.');
       if (m === "create") {
         const itemSchema = z3.object({
           name: z3.string().describe("Variable name (must be unique within collection)"),
@@ -3025,8 +3546,11 @@ var tools = [
             throw new Error(e.issues.map((i) => {
               const path = i.path.join(".");
               const shape = itemSchema instanceof z3.ZodObject ? itemSchema.shape : null;
-              const desc = shape?.[i.path[1]]?.description;
-              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "");
+              const field = String(i.path[1] ?? i.path[0] ?? "");
+              const desc = shape?.[field]?.description;
+              const paintField = field === "paints" || field === "fills" || field === "strokes";
+              const paintHelp = paintField ? ' Invalid Paint[] payload. Supported Paint[] authoring types: SOLID, GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; do not use CSS gradients or REST gradientHandlePositions. IMAGE/VIDEO/PATTERN are readback-only metadata, not Paint[] authoring input; use imageUrl/images for images. For examples call variables(method:"help", topic:"create").' : "";
+              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "") + paintHelp;
             }).join("; "));
           }
           throw e;
@@ -3048,8 +3572,11 @@ var tools = [
             throw new Error(e.issues.map((i) => {
               const path = i.path.join(".");
               const shape = itemSchema instanceof z3.ZodObject ? itemSchema.shape : null;
-              const desc = shape?.[i.path[1]]?.description;
-              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "");
+              const field = String(i.path[1] ?? i.path[0] ?? "");
+              const desc = shape?.[field]?.description;
+              const paintField = field === "paints" || field === "fills" || field === "strokes";
+              const paintHelp = paintField ? ' Invalid Paint[] payload. Supported Paint[] authoring types: SOLID, GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; do not use CSS gradients or REST gradientHandlePositions. IMAGE/VIDEO/PATTERN are readback-only metadata, not Paint[] authoring input; use imageUrl/images for images. For examples call variables(method:"help", topic:"update").' : "";
+              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "") + paintHelp;
             }).join("; "));
           }
           throw e;
@@ -3066,8 +3593,11 @@ var tools = [
             throw new Error(e.issues.map((i) => {
               const path = i.path.join(".");
               const shape = itemSchema instanceof z3.ZodObject ? itemSchema.shape : null;
-              const desc = shape?.[i.path[1]]?.description;
-              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "");
+              const field = String(i.path[1] ?? i.path[0] ?? "");
+              const desc = shape?.[field]?.description;
+              const paintField = field === "paints" || field === "fills" || field === "strokes";
+              const paintHelp = paintField ? ' Invalid Paint[] payload. Supported Paint[] authoring types: SOLID, GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, GRADIENT_DIAMOND. Use gradientTransform + gradientStops; do not use CSS gradients or REST gradientHandlePositions. IMAGE/VIDEO/PATTERN are readback-only metadata, not Paint[] authoring input; use imageUrl/images for images. For examples call variables(method:"help", topic:"delete").' : "";
+              return path + ": " + i.message + (desc ? " (expected: " + desc + ")" : "") + paintHelp;
             }).join("; "));
           }
           throw e;
@@ -3124,10 +3654,10 @@ var guidelinesList = [
   }
 ];
 var guidelinesContent = {
-  "component-structure": '# Component Structure\n\nComponents need correct sizing, property bindings, and token usage to work well as instances.\n\n## Width Constraints\n\nComponents with text content need a width \u2014 otherwise text never wraps.\n\n- Set `width` and `layoutSizingHorizontal:"FIXED"` on cards, panels, list items\n- HUG on both axes is only correct for buttons, badges, icons \u2014 intrinsically-sized elements\n\n## Property Bindings\n\nEvery text node inside a component should be bound to a TEXT property so instances can edit the content.\n\n- On creation: `children:[{type:"text", text:"Title", componentPropertyName:"Title"}]` auto-creates and binds\n- On creation: `children:[{type:"text", text:"Title", componentPropertyName:"Title"}]` auto-creates and binds\n- After creation: `frames(method:"update", items:[{id:"<textNodeId>", componentPropertyName:"<propName>"}])`\n- For existing nodes with many text children: `components(method:"create", type:"from_node", exposeText:true)`\n\nOrphaned properties (defined but not bound to any node) should be deleted:\n```\ncomponents(method:"update", items:[{id, propertyName:"<key>", action:"delete"}])\n```\n\n## Variant Sets\n\nGroup related components as variants \u2014 don\'t leave them as separate components.\n\n- Name variants with the property format: `Style=Primary`, `Style=Secondary`\n- Combine: `components(method:"create", type:"variant_set", items:[{componentIds:[...], name:"Button"}])`\n- Instances pick variants via `variantProperties:{"Style":"Primary"}`\n\n### Adding Variants to an Existing Set\n\nClone an existing variant into the same set with a new name. The `name` param is required \u2014 without it, the duplicate name corrupts the set.\n\n**Add a new value to an existing dimension** (e.g. State=Hover):\n```\ncomponents(method:"clone", id:"<variant_id>", name:"Style=Primary, State=Hover", parentId:"<set_id>")\n```\nClone one variant per combination. For a Style\xD7State set, adding State=Hover requires two clones (one per Style). Use batch `items` for efficiency:\n```\ncomponents(method:"clone", items:[\n  {id:"<Primary/Default>", name:"Style=Primary, State=Hover", parentId:"<set_id>"},\n  {id:"<Secondary/Default>", name:"Style=Secondary, State=Hover", parentId:"<set_id>"}\n])\n```\nThen patch the new variants: `frames(method:"update", items:[{id:"<new>", fillVariableName:"color/hover"}])`\n\n**Add a new dimension** (e.g. Size=sm to a Style\xD7State set):\n1. Batch rename existing variants to include the new dimension: `frames(method:"update", items:[{id:"<each>", name:"..., Size=md"}])`\n2. Batch clone all variants with the new value: `components(method:"clone", items:[{id:"<each>", name:"..., Size=sm", parentId:"<set_id>"}])`\n3. Batch patch the new variants: `frames(method:"update", items:[{id:"<each>", padding:8, minHeight:32}])`\n\nProperty bindings (TEXT, INSTANCE_SWAP) are preserved on cloned variants.\n\n## Slots\n\nSlots are placeholder containers inside components that instance users can fill with custom content.\n\n- Create at component root: `frames(method:"create", type:"slot", items:[{parentId:"<comp_id>", name:"Content"}])`\n- Create nested inside a frame within a component: `frames(method:"create", type:"slot", items:[{parentId:"<frame_id>", name:"Content"}])`\n- In instances, add content by using the slot\'s ID as `parentId` on any create/reparent call\n- Empty slots are normal \u2014 they don\'t trigger lint warnings\n\n## Checking\n\nRun `components(method:"audit", id)` \u2014 checks both lint rules and property bindings in one call.',
+  "component-structure": '# Component Structure\n\nComponents need correct sizing, property bindings, and token usage to work well as instances.\n\n## Width Constraints\n\nComponents with text content need a width \u2014 otherwise text never wraps.\n\n- Set `width` and `layoutSizingHorizontal:"FIXED"` on cards, panels, list items\n- HUG on both axes is only correct for buttons, badges, icons \u2014 intrinsically-sized elements\n\n## Property Bindings\n\nEvery text node inside a component should be bound to a TEXT property so instances can edit the content.\n\n- On creation: `children:[{type:"text", text:"Title", componentPropertyName:"Title"}]` auto-creates and binds\n- On creation: `children:[{type:"text", text:"Title", componentPropertyName:"Title"}]` auto-creates and binds\n- After creation: `frames(method:"update", items:[{id:"<textNodeId>", componentPropertyName:"<propName>"}])`\n- For existing nodes with many text children: `components(method:"create", type:"from_node", exposeText:true)`\n\nOrphaned properties (defined but not bound to any node) should be deleted:\n```\ncomponents(method:"update", items:[{id, propertyName:"<key>", action:"delete"}])\n```\n\n## Variant Sets\n\nGroup related components as variants \u2014 don\'t leave them as separate components.\n\n- Name variants with the property format: `Style=Primary`, `Style=Secondary`\n- Combine: `components(method:"create", type:"variant_set", items:[{componentIds:[...], name:"Button"}])`\n- Instances pick variants via `variantProperties:{"Style":"Primary"}`\n\n### Adding Variants to an Existing Set\n\nClone an existing variant into the same set with a new name. The `name` param is required \u2014 without it, the duplicate name corrupts the set.\n\n**Add a new value to an existing dimension** (e.g. State=Hover):\n```\ncomponents(method:"clone", id:"<variant_id>", name:"Style=Primary, State=Hover", parentId:"<set_id>")\n```\nClone one variant per combination. For a Style\xD7State set, adding State=Hover requires two clones (one per Style). Use batch `items` for efficiency:\n```\ncomponents(method:"clone", items:[\n  {id:"<Primary/Default>", name:"Style=Primary, State=Hover", parentId:"<set_id>"},\n  {id:"<Secondary/Default>", name:"Style=Secondary, State=Hover", parentId:"<set_id>"}\n])\n```\nThen patch the new variants: `frames(method:"update", items:[{id:"<new>", fillVariableName:"color/hover"}])`\n\n**Add a new dimension** (e.g. Size=sm to a Style\xD7State set):\n1. Batch rename existing variants to include the new dimension: `frames(method:"update", items:[{id:"<each>", name:"..., Size=md"}])`\n2. Batch clone all variants with the new value: `components(method:"clone", items:[{id:"<each>", name:"..., Size=sm", parentId:"<set_id>"}])`\n3. Batch patch the new variants: `frames(method:"update", items:[{id:"<each>", padding:"space/8"}])`\n\nProperty bindings (TEXT, INSTANCE_SWAP) are preserved on cloned variants.\n\n## Slots\n\nSlots are placeholder containers inside components that instance users can fill with custom content.\n\n- Create at component root: `frames(method:"create", type:"slot", items:[{parentId:"<comp_id>", name:"Content"}])`\n- Create nested inside a frame within a component: `frames(method:"create", type:"slot", items:[{parentId:"<frame_id>", name:"Content"}])`\n- In instances, add content by using the slot\'s ID as `parentId` on any create/reparent call\n- Empty slots are normal \u2014 they don\'t trigger lint warnings\n\n## Checking\n\nRun `components(method:"audit", id)` \u2014 checks both lint rules and property bindings in one call.',
   "library-components": '# Working with Library Components\n\nLibrary components are read-only \u2014 they come from external team libraries and cannot be edited in the current file.\n\n## Reading\n\nWhen reading nodes, library instances appear as stubs with their overridable properties:\n```\n{name: "Header", type: "INSTANCE", componentProperties: {"Platform": "Desktop"}}\n```\n\nLibrary internals are hidden: no `componentId`, no variable names, no style names. You see resolved values (hex colors, numbers) instead.\n\n## Using\n\nPlace library instances via `instances(method:"create", items:[{componentId:"<id>"}])` when you have a local component ID. For library components, instances are already placed by the designer \u2014 interact via `instances(method:"update")` to set properties.\n\n## Customizing\n\nTo edit a library component, clone it into the local file first:\n\n```\ncomponents(method:"clone", id:"<instanceId>")\n```\n\nThis resolves the instance to its source component (or full component set) and creates a local copy with a new ID. Edit the local copy freely \u2014 it is independent of the library.\n\nDo not attempt to `components(method:"get")` or `components(method:"update")` a library component directly \u2014 these will error.\n\n## Overriding Instance Properties\n\nUse `instances(method:"update")` to change overridable properties on library instances:\n```\ninstances(method:"update", items:[{id:"<instanceId>", properties:{"Label":"New Text", "State":"Hover"}}])\n```\n\nProperty names are clean (no hash suffixes needed for update \u2014 the system resolves partial keys).',
   "responsive-designs": '# Responsive Sizing\n\n## Workflow: Top-Down Sizing\n\nBuild layouts from the outside in:\n\n1. **Set the container first.** Every container needs an explicit width \u2014 either `width` + `layoutSizingHorizontal:"FIXED"` for shells and bounded panels, or `layoutSizingHorizontal:"FILL"` inside an auto-layout parent. Set `layoutMode` (VERTICAL or HORIZONTAL) and spacing/padding.\n2. **Children fill the container.** Use `layoutSizingHorizontal:"FILL"` on children so they stretch to the available space. Use `layoutSizingVertical:"HUG"` so height follows content.\n3. **Only leaves use HUG on both axes.** Buttons, badges, icons \u2014 elements with short, predictable content that should shrink-wrap.\n\nThis ensures every level of the tree has a clear width constraint. Text wraps, FILL children stretch, and the layout adapts when the container resizes.\n\nAlways set BOTH axes explicitly on every node. Omitting sizing leads to unintended defaults.\n\n## FIXED / FILL / HUG\n\n- **FIXED** \u2014 explicit bounded widths: page shell, sidebar, modal max-width, specimen frames\n- **FILL** \u2014 children that adapt to parent: cards, rows, panels, nav stacks, text that should wrap. Use `minWidth`/`maxWidth` for responsive constraints.\n- **HUG** \u2014 content-sized leaves only: icons, badges, pills, button labels\n\n## Anti-patterns: HUG/HUG\n\nHUG on both axes is the most common cause of broken layouts. It means "shrink to fit my content on both axes" \u2014 the container has no opinion about its own size and collapses to whatever its children measure.\n\n**Why HUG/HUG breaks designs:**\n\n1. **Text never wraps.** A HUG-width container grows to fit the longest text line. Body text becomes a single very long line instead of wrapping at a readable width. The design looks correct with short placeholder text but breaks with real content.\n\n2. **Layouts don\'t adapt.** HUG/HUG containers ignore their parent\'s width. A card inside a responsive column won\'t stretch to fill available space \u2014 it stays at its content width, leaving gaps or overflowing.\n\n3. **FILL children become under-constrained.** A child with `layoutSizingHorizontal:"FILL"` inside a HUG-width parent has no space to fill \u2014 the parent defers its width to its children, but the FILL child defers its width to the parent. The result is under-constrained sizing that produces unpredictable or collapsed layouts.\n\n4. **Cascading failures.** One HUG/HUG container at the top of a tree forces every child to resolve its own width. The entire layout becomes rigid and content-dependent instead of responsive.\n\n**HUG/HUG is only correct for:**\n- Buttons, pills, badges, chips \u2014 intrinsically-sized leaf elements with short, predictable content\n- Icon containers with fixed-size children\n- Inline tags and status indicators\n\n**For everything else, set at least one axis to FIXED or FILL:**\n- Cards, panels, list rows \u2192 `layoutSizingHorizontal:"FILL"`, vertical `HUG`. Add `minWidth`/`maxWidth` for responsive bounds.\n- Shells, sidebars, modals \u2192 `width` + `layoutSizingHorizontal:"FIXED"`, vertical `FILL` or `HUG`\n- Full-width sections \u2192 `layoutSizingHorizontal:"FILL"`, `layoutSizingVertical:"HUG"`\n\n## Wrapping Layouts (layoutWrap)\n\n`layoutWrap: WRAP` enables children to flow into new rows when they exceed the container width \u2014 like CSS `flex-wrap`. This only works with **HORIZONTAL** auto-layout. Figma does not support wrap on VERTICAL layouts.\n\n**When to use wrap:**\n- Card grids with a fixed number of columns at a known width\n- Tag/chip collections where items flow into multiple rows\n- Any layout where items should reflow based on available width\n\n**Horizontal wrap pattern:**\n```\nframes.create(type: "auto_layout", layoutMode: "HORIZONTAL", layoutWrap: "WRAP",\n  itemSpacing: "space/16", counterAxisSpacing: "space/16")\n```\nChildren use FIXED width to control column count. `counterAxisSpacing` sets the gap between wrapped rows.\n\n**Vertical grid alternative:**\nSince VERTICAL layouts cannot wrap, build column-based grids by nesting VERTICAL columns inside a HORIZONTAL parent:\n```\nouter (HORIZONTAL, itemSpacing: 20, FILL width)\n  col-1 (VERTICAL, FILL width, HUG height, itemSpacing: 20)\n  col-2 (VERTICAL, FILL width, HUG height, itemSpacing: 20)\n  col-3 (VERTICAL, FILL width, HUG height, itemSpacing: 20)\n```\nEach column gets equal width via FILL. Reparent items into columns for column-first ordering. This handles variable card heights per column independently.\n\n## Component Sizing\n\nComponent roots use `FILL` when placed in a parent \u2014 they adapt to context, not a fixed specimen width. Use `FIXED` only for the specimen (the component definition itself when it needs a specific preview width).\n\nExample sidebar item:\n- Instance: `FILL` in parent nav stack\n- Icon child: fixed 18x18\n- Label child: `FILL`\n- Badge child: `HUG`\n\n## Text Sizing\n\n- Body text inside containers: prefer `FILL` width, `HUG` height (auto-wraps)\n- Single-line labels: prefer `FILL` horizontal (truncates if needed)\n- Standalone headings: `HUG` is fine\n\nInside auto-layout parents, target `layoutSizingHorizontal:"FILL"` + `layoutSizingVertical:"HUG"` + `textAutoResize:"HEIGHT"` for text that should wrap. These are not auto-applied \u2014 set them explicitly on text.create or text.update.\n\n## Checklist\n\nBefore finalizing a layout, verify:\n1. No container with text has HUG on the horizontal axis (unless it\'s a button/badge)\n2. Children use FILL on the axis that should absorb available space \u2014 not blindly on both axes. Compact controls in horizontal rows often stay HUG vertically.\n3. Top-level containers have an explicit width (FIXED) or stretch to their parent (FILL)\n4. Run `lint(method:"check", nodeId:"<rootId>", rules:["composition"])` to catch overflow-parent, unbounded-hug, and fixed-in-autolayout issues',
-  "token-discipline": '# Token Discipline\n\nEvery color, spacing value, and text style should come from a design token \u2014 not hardcoded values.\n\n## Colors\n\nBind fills and strokes to color variables instead of hex values.\n\n- Fill: `fillVariableName:"bg/primary"` or `fillStyleName:"Surface/Primary"`\n- Stroke: `strokeVariableName:"border/default"`\n- Text color: `fontColorVariableName:"text/primary"`\n\nIf no matching variable exists, create one first:\n```\nvariables(method:"create", collectionId:"Colors", items:[{name:"bg/accent", type:"COLOR", valuesByMode:{"Light":"#E8F0FE","Dark":"#1A3A5C"}, scopes:["ALL_FILLS"]}])\n```\n\n## Spacing and Radius\n\nPass a variable name string instead of a number for cornerRadius, padding, itemSpacing, strokeWeight, opacity.\n\n- `cornerRadius:"radius/8"` not `cornerRadius:8`\n- `paddingTop:"space/16"` not `paddingTop:16`\n- `itemSpacing:"space/8"` not `itemSpacing:8`\n\nCreate FLOAT variables with appropriate scopes:\n```\nvariables(method:"create", collectionId:"Metrics", items:[{name:"space/12", type:"FLOAT", value:12, scopes:["GAP","WIDTH_HEIGHT"]}])\n```\n\n## Text Styles\n\nApply text styles by name \u2014 don\'t set fontSize/fontFamily/fontWeight manually.\n\n- `textStyleName:"Body/M"` on text.create or frames.update\n- Create styles with `styles(method:"create", type:"text", items:[{name:"Body/M", fontFamily:"Inter", fontSize:14, lineHeight:{value:20, unit:"PIXELS"}}])`\n\n## Common Scopes\n\nCOLOR variables:\n- `ALL_FILLS` \u2014 background fills\n- `TEXT_FILL` \u2014 text color\n- `STROKE_COLOR` \u2014 borders and outlines\n\nFLOAT variables:\n- `GAP`, `WIDTH_HEIGHT` \u2014 spacing and padding\n- `CORNER_RADIUS` \u2014 border radius\n- `STROKE_FLOAT` \u2014 stroke weight\n- `OPACITY` \u2014 transparency\n\n## Checking\n\nLint rules `hardcoded-color`, `hardcoded-token`, `no-text-style` catch unbound values. Run `audit` on any node to check.',
+  "token-discipline": '# Token Discipline\n\nEvery color, spacing value, and text style should come from a design token \u2014 not hardcoded values.\n\n## Colors\n\nBind fills and strokes to color variables instead of hex values.\n\n- Fill: `fillVariableName:"bg/surface"` or `fillStyleName:"Surface/Primary"`\n- Stroke: `strokeVariableName:"border/subtle"`\n- Text color: `fontColorVariableName:"text/primary"`\n\nIf no matching variable exists, create one first:\n```\nvariables(method:"create", collectionId:"Tokens", items:[{name:"bg/warning", type:"COLOR", value:"#F59E0B", scopes:["ALL_FILLS"]}])\n```\n\n## Spacing and Radius\n\nPass a variable name string instead of a number for cornerRadius, padding, itemSpacing, strokeWeight, opacity.\n\n- `cornerRadius:"radius/8"` not `cornerRadius:8`\n- `paddingTop:"space/16"` not `paddingTop:16`\n- `itemSpacing:"space/8"` not `itemSpacing:8`\n\nCreate FLOAT variables with appropriate scopes:\n```\nvariables(method:"create", collectionId:"Tokens", items:[{name:"space/32", type:"FLOAT", value:32, scopes:["GAP"]}])\n```\n\n## Text Styles\n\nApply text styles by name \u2014 don\'t set fontSize/fontFamily/fontWeight manually.\n\n- `textStyleName:"Body/M"` on text.create or frames.update\n- Create styles with `styles(method:"create", type:"text", items:[{name:"Body/M", fontFamily:"Inter", fontSize:14, lineHeight:{value:20, unit:"PIXELS"}}])`\n\n## Common Scopes\n\nCOLOR variables:\n- `ALL_FILLS` \u2014 background fills\n- `TEXT_FILL` \u2014 text color\n- `STROKE_COLOR` \u2014 borders and outlines\n\nFLOAT variables:\n- `GAP`, `WIDTH_HEIGHT` \u2014 spacing and padding\n- `CORNER_RADIUS` \u2014 border radius\n- `STROKE_FLOAT` \u2014 stroke weight\n- `OPACITY` \u2014 transparency\n\n## Checking\n\nLint rules `hardcoded-color`, `hardcoded-token`, `no-text-style` catch unbound values. Run `audit` on any node to check.',
   "vibma-workflow": '# Vibma Workflow\n\nWork with the tool in a predictable sequence: read before writing, create parents before children, verify after mutations.\n\n## Build Order\n\n1. `connection.create` \u2192 `connection.get` to verify\n2. Inspect existing structure: `document.get`, `variables.list`, `styles.list`, `components.list`\n3. Create design tokens: variable collections \u2192 variables \u2192 text styles \u2192 effect styles\n4. Create components from tokens\n5. Assemble screens from component instances\n6. Verify with `lint.check` and `frames.export`\n\n## Parent-First Rule\n\nCreate parent containers before children. Dependent creates must be sequential \u2014 never parallelize when the child needs the parent ID.\n\n## Component Creation\n\nBuild components early \u2014 they are the building blocks for screens. A component IS a frame: create it directly with layout properties, then add children.\n\n- Use `components.create(type: "component")` with properties for TEXT, BOOLEAN, INSTANCE_SWAP\n- TEXT properties auto-bind to child text nodes with matching names\n- Group related components into variant sets with `components.create(type: "variant_set")` for state dimensions (Style, Size, State)\n- Use flat components (not variant sets) for INSTANCE_SWAP slots like icons or avatars\n- Assemble screens from `instances.create`, not by cloning frames\n\n## Placement Rule\n\nAlways pass `x` and `y` for top-level nodes and clones. Do not stack everything at `0,0`.\n\n## Instance Rule\n\nCall `components.get` or `instances.get` to discover property keys (including `#suffix`) before setting overrides. Do not guess property names.\n\n## Verify After Mutations\n\n`"ok"` means the write succeeded, not that the result is correct. Read back the node after clone, swap, mode pinning, or large batch updates.'
 };
 function resolveGuideline(topic) {
@@ -4064,7 +4594,8 @@ async function registerAllTools(server2, sendCommand, caps2) {
           return { content: [{ type: "text", text }] };
         }
         const teamFromEnv = process.env.FIGMA_TEAM_ID;
-        let { file, team } = params;
+        const { file } = params;
+        let { team } = params;
         const needsTarget = (m) => m === "list" || m === "get" && filterRegistryByQuery("").length === 0;
         if (!file && !team && needsTarget(method) && teamFromEnv) team = teamFromEnv;
         if (method === "list") {
@@ -4494,9 +5025,9 @@ See "Version mismatch" in CARRYME.md or DRAGME.md for update steps.`;
             type: "text",
             text: connected ? `Tunnel reset: ${body.message}. Reconnected on port ${activePort}.
 
-IMPORTANT: The Figma plugin was also disconnected. Ask the user to reopen the Vibma plugin, then call connection(method: "create") followed by connection(method: "get").` : `Tunnel reset: ${body.message}. Reconnection in progress.
+IMPORTANT: The Figma plugin was also disconnected from the tunnel. Ask the user to use the existing Vibma plugin window and click Connect again if needed, then call connection(method: "create") followed by connection(method: "get").` : `Tunnel reset: ${body.message}. Reconnection in progress.
 
-IMPORTANT: The Figma plugin was also disconnected. Ask the user to reopen the Vibma plugin, then call connection(method: "create") to retry.`
+IMPORTANT: The Figma plugin was also disconnected from the tunnel. Ask the user to use the existing Vibma plugin window and click Connect again if needed, then call connection(method: "create") to retry.`
           }]
         };
       }