@ufira/vibma 1.0.0 → 1.1.0

package/dist/tools/registry.js

@@ -27,10 +27,15 @@ function mcpError(prefix, error) {
 // src/tools/generated/help.ts
 var helpDirectory = `# Available Endpoints
 
+[node-inspection]
+  annotations              Read and manage design annotations and annotation categories.
+  selection                Read and set the current Figma selection.
+
 [design-system]
   components               Create and manage reusable components and variant sets.
   fonts                    Search available fonts in Figma.
   instances                Create and manage component instances.
+  library                  Discover and inspect published team library components and styles via Figma REST API.
   styles                   CRUD for local paint, text, effect, and grid styles.
   variable_collections     CRUD for variable collections \u2014 the document-level API for design tokens.
   variables                Search and update design variables within a collection.
@@ -44,6 +49,8 @@ var helpDirectory = `# Available Endpoints
 
 [creation]
   frames                   Create and manage frames, shapes, auto-layout containers, sections, and SVG nodes.
+  icons                    Search and create icons from 200k+ open-source icons via Iconify.
+  images                   Search stock photos from Pexels and apply image fills.
   text                     Create and manage text nodes.
 
 [quality]
@@ -52,19 +59,38 @@ var helpDirectory = `# Available Endpoints
 [interaction]
   prototyping              Manage prototype interactions, reactions, and navigation flows.
 
-[node-inspection]
-  selection                Read and set the current Figma selection.
-
 Topics:
   missing_tools            Why create or edit tools are missing and how to fix it
 
 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.',
+    "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',
+      "update_category": `# annotations.update_category
+Update an annotation category's label or color
+
+Example: annotations(method:"update_category", id:"cat:123", label:"Layout", color:"teal")
+
+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'
+    }
+  },
   "components": {
-    "summary": '# components\nCreate and manage reusable components and variant sets.\n\nMethods:\n  clone                Duplicate nodes [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  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.',
     "methods": {
-      "clone": "# components.clone\nDuplicate nodes\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.",
       "audit": `# components.audit
 Run lint on a node \u2014 returns severity-ranked findings
 
@@ -93,15 +119,17 @@ Discriminant: type (component | from_node | variant_set)
     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)
-    opacity (string, optional) \u2014 Opacity (0-1) or variable name
     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)
-    layoutPositioning (AUTO | ABSOLUTE, optional) \u2014 ABSOLUTE = floating inside auto-layout parent
+    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
@@ -112,13 +140,11 @@ Discriminant: type (component | from_node | variant_set)
     strokeLeftWeight (string, optional)
     strokeRightWeight (string, optional)
     strokeAlign (INSIDE | OUTSIDE | CENTER, optional) \u2014 Stroke position (default: INSIDE)
-    strokesIncludedInLayout (boolean, optional) \u2014 Include stroke width in layout measurements (default: false)
     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)
-    effectStyleName (string, optional) \u2014 Effect style name (e.g. 'Shadow/Card') for shadows, blurs
     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.
@@ -128,15 +154,18 @@ Discriminant: type (component | from_node | variant_set)
     paddingLeft (string, optional)
     primaryAxisAlignItems (MIN | MAX | CENTER | SPACE_BETWEEN, optional)
     counterAxisAlignItems (MIN | MAX | CENTER | BASELINE, optional)
-    layoutSizingHorizontal (FIXED | HUG | FILL, optional)
-    layoutSizingVertical (FIXED | HUG | FILL, 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
-    overflowDirection (NONE | HORIZONTAL | VERTICAL | BOTH, optional) \u2014 Scroll overflow in prototype (default: NONE)
+    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"}]}]
 
@@ -159,15 +188,17 @@ Discriminant: type (component | from_node | variant_set)
     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)
-    opacity (string, optional) \u2014 Opacity (0-1) or variable name
     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)
-    layoutPositioning (AUTO | ABSOLUTE, optional) \u2014 ABSOLUTE = floating inside auto-layout parent
+    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
@@ -178,13 +209,11 @@ Discriminant: type (component | from_node | variant_set)
     strokeLeftWeight (string, optional)
     strokeRightWeight (string, optional)
     strokeAlign (INSIDE | OUTSIDE | CENTER, optional) \u2014 Stroke position (default: INSIDE)
-    strokesIncludedInLayout (boolean, optional) \u2014 Include stroke width in layout measurements (default: false)
     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)
-    effectStyleName (string, optional) \u2014 Effect style name (e.g. 'Shadow/Card') for shadows, blurs
     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.
@@ -194,15 +223,18 @@ Discriminant: type (component | from_node | variant_set)
     paddingLeft (string, optional)
     primaryAxisAlignItems (MIN | MAX | CENTER | SPACE_BETWEEN, optional)
     counterAxisAlignItems (MIN | MAX | CENTER | BASELINE, optional)
-    layoutSizingHorizontal (FIXED | HUG | FILL, optional)
-    layoutSizingVertical (FIXED | HUG | FILL, 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
-    overflowDirection (NONE | HORIZONTAL | VERTICAL | BOTH, optional) \u2014 Scroll overflow in prototype (default: NONE)
+    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.`,
@@ -237,7 +269,7 @@ Discriminant: type (component | from_node | variant_set)
     }
   },
   "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 [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// 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  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.',
     "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)',
@@ -260,15 +292,14 @@ Params:
       strokeLeftWeight (string, optional)
       strokeRightWeight (string, optional)
       strokeAlign (INSIDE | OUTSIDE | CENTER, optional) \u2014 Stroke position (default: INSIDE)
-      strokesIncludedInLayout (boolean, optional) \u2014 Include stroke width in layout measurements (default: false)
       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) \u2014 Opacity (0-1) or variable name
       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
       layoutMode (NONE | HORIZONTAL | VERTICAL, optional) \u2014 Layout direction (default: NONE)
@@ -282,6 +313,7 @@ Params:
       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)
       layoutSizingHorizontal (FIXED | HUG | FILL, optional)
       layoutSizingVertical (FIXED | HUG | FILL, optional)
       layoutPositioning (AUTO | ABSOLUTE, optional) \u2014 ABSOLUTE = floating inside auto-layout parent
@@ -313,6 +345,8 @@ Params:
       width (number, optional)
       height (number, optional)
       clearFill (boolean, optional) \u2014 Remove all fills
+      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)
       effects (array, optional) \u2014 Effect array (DROP_SHADOW, INNER_SHADOW, LAYER_BLUR, BACKGROUND_BLUR)
       overflowDirection (NONE | HORIZONTAL | VERTICAL | BOTH, optional) \u2014 Scroll overflow in prototype (default: NONE)
       constraints (object, optional)
@@ -322,9 +356,10 @@ Params:
         variableId (string, optional)
       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\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": "# 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.",
       "audit": `# frames.audit
 Run lint on a node \u2014 returns severity-ranked findings
 
@@ -351,15 +386,17 @@ Discriminant: type (frame | auto_layout | section | rectangle | ellipse | line |
     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)
-    opacity (string, optional) \u2014 Opacity (0-1) or variable name
     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)
-    layoutPositioning (AUTO | ABSOLUTE, optional) \u2014 ABSOLUTE = floating inside auto-layout parent
+    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
@@ -370,13 +407,11 @@ Discriminant: type (frame | auto_layout | section | rectangle | ellipse | line |
     strokeLeftWeight (string, optional)
     strokeRightWeight (string, optional)
     strokeAlign (INSIDE | OUTSIDE | CENTER, optional) \u2014 Stroke position (default: INSIDE)
-    strokesIncludedInLayout (boolean, optional) \u2014 Include stroke width in layout measurements (default: false)
     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)
-    effectStyleName (string, optional) \u2014 Effect style name (e.g. 'Shadow/Card') for shadows, blurs
     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.
@@ -386,15 +421,18 @@ Discriminant: type (frame | auto_layout | section | rectangle | ellipse | line |
     paddingLeft (string, optional)
     primaryAxisAlignItems (MIN | MAX | CENTER | SPACE_BETWEEN, optional)
     counterAxisAlignItems (MIN | MAX | CENTER | BASELINE, optional)
-    layoutSizingHorizontal (FIXED | HUG | FILL, optional)
-    layoutSizingVertical (FIXED | HUG | FILL, 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
-    overflowDirection (NONE | HORIZONTAL | VERTICAL | BOTH, optional) \u2014 Scroll overflow in prototype (default: NONE)
+    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.
 
@@ -407,15 +445,17 @@ Discriminant: type (frame | auto_layout | section | rectangle | ellipse | line |
     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)
-    opacity (string, optional) \u2014 Opacity (0-1) or variable name
     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)
-    layoutPositioning (AUTO | ABSOLUTE, optional) \u2014 ABSOLUTE = floating inside auto-layout parent
+    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
@@ -426,13 +466,11 @@ Discriminant: type (frame | auto_layout | section | rectangle | ellipse | line |
     strokeLeftWeight (string, optional)
     strokeRightWeight (string, optional)
     strokeAlign (INSIDE | OUTSIDE | CENTER, optional) \u2014 Stroke position (default: INSIDE)
-    strokesIncludedInLayout (boolean, optional) \u2014 Include stroke width in layout measurements (default: false)
     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)
-    effectStyleName (string, optional) \u2014 Effect style name (e.g. 'Shadow/Card') for shadows, blurs
     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.
@@ -442,15 +480,18 @@ Discriminant: type (frame | auto_layout | section | rectangle | ellipse | line |
     paddingLeft (string, optional)
     primaryAxisAlignItems (MIN | MAX | CENTER | SPACE_BETWEEN, optional)
     counterAxisAlignItems (MIN | MAX | CENTER | BASELINE, optional)
-    layoutSizingHorizontal (FIXED | HUG | FILL, optional)
-    layoutSizingVertical (FIXED | HUG | FILL, 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
-    overflowDirection (NONE | HORIZONTAL | VERTICAL | BOTH, optional) \u2014 Scroll overflow in prototype (default: NONE)
+    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.
@@ -467,6 +508,8 @@ Discriminant: type (frame | auto_layout | section | rectangle | ellipse | line |
     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)
 
   ## rectangle \u2014 Rectangle shape node
     name (string, optional) \u2014 Layer name (default: 'Rectangle')
@@ -479,6 +522,8 @@ Discriminant: type (frame | auto_layout | section | rectangle | ellipse | line |
     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
@@ -491,6 +536,7 @@ Discriminant: type (frame | auto_layout | section | rectangle | ellipse | line |
     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')
@@ -503,6 +549,8 @@ Discriminant: type (frame | auto_layout | section | rectangle | ellipse | line |
     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
@@ -510,6 +558,7 @@ Discriminant: type (frame | auto_layout | section | rectangle | ellipse | line |
     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')
@@ -524,6 +573,7 @@ Discriminant: type (frame | auto_layout | section | rectangle | ellipse | line |
     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)
@@ -537,25 +587,65 @@ Discriminant: type (frame | auto_layout | section | rectangle | ellipse | line |
     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)
-    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`,
+    y (number, optional) \u2014 Y position (default: 0)`,
       "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)"
     }
   },
+  "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)',
+      "create": `# icons.create
+Create an icon node in Figma from an Iconify icon name
+
+Example: icons(method:"create", icon:"lucide:home", size:24, colorVariableName:"text/primary", parentId:"1:2")
+
+Params:
+    icon (string, required) \u2014 Icon name \u2014 "prefix:name" e.g. "lucide:home", "mdi:account"
+    size (number, optional) \u2014 Icon size in px (default 24, square)
+    name (string, optional) \u2014 Layer name (default: icon name)
+    parentId (string, optional) \u2014 Parent node ID. Omit for current page root.
+    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')`
+    }
+  },
+  "images": {
+    "summary": '# images\nSearch stock photos from Pexels and apply image fills.\n\nMethods:\n  search               Search photos by keyword via Pexels API [read]\n  preview              Preview a photo by ID \u2014 returns the image so you can see it before placing [read]\n\n// Workflow: search \u2192 preview \u2192 place.\n// Search returns slim photo objects: { id, alt, avg_color, width, height }.\n// Preview returns the actual image so you can visually confirm before placing.\n// To place: pass imageUrl:"pexel:<id>" to frames.create or frames.update.\n// Attribution (photographer credit) is applied automatically as node description.\n// User-provided image URLs also work \u2014 any public image URL can be used as imageUrl on frames.\n// Powered by Pexels (pexels.com) \u2014 free stock photos. Requires PEXELS_API_KEY env var.\n\nUse images(method: "help", topic: "<method>") for method details.',
+    "methods": {
+      "search": `# images.search
+Search photos by keyword via Pexels API
+
+Example: images(method:"search", query:"sunset beach", orientation:"landscape", per_page:5)
+
+Params:
+    query (string, required) \u2014 Search keyword (e.g. "sunset", "office", "nature")
+    orientation (landscape | portrait | square, optional) \u2014 Filter by photo orientation
+    size (large | medium | small, optional) \u2014 Minimum photo size
+    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'
+    }
+  },
   "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 [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: components.list \u2192 instances.create with componentId + properties (one call). No separate update needed for text/boolean overrides.\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  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.',
     "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\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": "# 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.",
       "audit": `# instances.audit
 Run lint on a node \u2014 returns severity-ranked findings
 
@@ -571,13 +661,13 @@ Params:
       "create": `# instances.create
 Create component instances
 
-Example: instances(method:"create", items:[{componentId:"1:23", variantProperties:{"Size":"Large"}, properties:{"Label":"Click me"}, parentId:"2:45", layoutSizingHorizontal:"FILL"}])
+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
 
 Params:
     items (InstanceCreateItem[], required) \u2014 Array of {componentId, variantProperties?, x?, y?, parentId?, layoutSizingHorizontal?, ...}
-      opacity (string, optional) \u2014 Opacity (0-1) or variable name
       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
       layoutSizingHorizontal (FIXED | HUG | FILL, optional)
@@ -587,7 +677,9 @@ Params:
       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
-      componentId (string, required) \u2014 Component or component set ID
+      componentId (string, optional) \u2014 Local component or component set ID. Pass this OR componentKey.
+      componentKey (string, optional) \u2014 Published library component key \u2014 imports from a team library via importComponentByKeyAsync. Discover keys via library(method:"components", ...); the library tool auto-resolves names \u2192 keys so you normally pass componentName instead.
+      componentName (string, optional) \u2014 Name of a component previously discovered via the library tool. Resolved to a componentKey MCP-side \u2014 the agent never handles the raw key. Preferred over componentKey for context hygiene.
       sizing (contextual, optional) \u2014 "contextual": infer FILL/HUG from parent layout (e.g. FILL horizontally in a VERTICAL auto-layout parent). Omit to inherit sizing from the component definition.
       variantProperties (object, optional) \u2014 Pick variant e.g. {"Style":"Secondary"}
       properties (object, optional) \u2014 Set component properties inline e.g. {"Label":"Click me", "ShowIcon":true}. Same as instances.update properties.
@@ -596,6 +688,7 @@ Params:
       y (number, optional)
       width (number, optional) \u2014 Override width (resize)
       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.`,
       "update": `# instances.update
@@ -619,15 +712,14 @@ Params:
       strokeLeftWeight (string, optional)
       strokeRightWeight (string, optional)
       strokeAlign (INSIDE | OUTSIDE | CENTER, optional) \u2014 Stroke position (default: INSIDE)
-      strokesIncludedInLayout (boolean, optional) \u2014 Include stroke width in layout measurements (default: false)
       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) \u2014 Opacity (0-1) or variable name
       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
       layoutMode (NONE | HORIZONTAL | VERTICAL, optional) \u2014 Layout direction (default: NONE)
@@ -641,6 +733,7 @@ Params:
       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)
       layoutSizingHorizontal (FIXED | HUG | FILL, optional)
       layoutSizingVertical (FIXED | HUG | FILL, optional)
       layoutPositioning (AUTO | ABSOLUTE, optional) \u2014 ABSOLUTE = floating inside auto-layout parent
@@ -687,6 +780,67 @@ Params:
       "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"
     }
   },
+  "library": {
+    "summary": `# library
+Discover and inspect published team library components and styles via Figma REST API.
+
+Methods:
+  list                 List all published components, sets, and styles. Minimal shapes, no pagination. Populates the MCP name\u2192key registry. [read]
+  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. [read]
+
+// Discover components and styles published to team libraries \u2014 external files not open in Figma.
+// Requires FIGMA_API_TOKEN env var (Personal Access Token with library_content:read scope).
+// Accepts a file URL/key, a team URL/ID, or falls back to the FIGMA_TEAM_ID env var if neither is passed.
+//
+// Two-step flow (discovery \u2192 use):
+//   1. list \u2192 populates the MCP name\u2192key registry (one-shot, no pagination, no side effects in Figma)
+//   2. get  \u2192 rich details for any number of queries: componentPropertyDefinitions, variant options, defaults, usage hint
+//   3. use  \u2192 instances(method:"create", items:[{componentName:"..."}]) or frames/text with fillStyleName/textStyleName
+//
+// list returns { libraries: [{ name, sections: [{ name, components, componentSets, styles }] }] }.
+// Libraries are grouped by source Figma file, then by section (containing frame) \u2014 mirroring Figma's Libraries browser.
+// Use the library and section names to identify the right component when multiple libraries expose overlapping names.
+//
+// get returns the same nested hierarchy as list, but each leaf is a full detail object (properties, variant options,
+// defaults, copy-pasteable usage hint) instead of a bare name. Pass library and/or section params to narrow results
+// when names collide \u2014 e.g. library(method:"get", query:"Item", library:"macOS", section:"Sidebars").
+//
+// No import step needed. Every *Name referenced in a later tool call (componentName, fillStyleName,
+// textStyleName, effectStyleName) is auto-resolved from the registry and imported on demand via
+// figma.importComponentByKeyAsync / importStyleByKeyAsync. Local styles always take precedence \u2014
+// library fallback only kicks in when no local style with that exact name exists.
+//
+// The raw 40-char component/style keys NEVER enter agent context \u2014 the MCP holds them internally.
+//
+// list must be called before get / before any name reference in other tools \u2014 the registry is initially empty.
+// Results are cached for 5 minutes.
+//
+// Name collisions across files: first-seen wins; subsequent entries with the same name are re-keyed with
+// " (in <frame>)" suffix in the registry so you can still address them.
+
+Use library(method: "help", topic: "<method>") for method details.`,
+    "methods": {
+      "list": `# library.list
+List all published components, sets, and styles. Minimal shapes, no pagination. Populates the MCP name\u2192key registry.
+
+Example: library(method:"list")  // uses FIGMA_TEAM_ID env var; or pass file/team explicitly
+
+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.`,
+      "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.
+
+Example: library(method:"get", query:["item","header"], library:"macOS", section:"Sidebars")  // batch query scoped to a specific library and section
+
+Params:
+    query (string[], required) \u2014 One or more substring queries (case-insensitive, matched against name OR description). Pass a single string or an array. Matches from multiple queries are merged and deduped by registered name before details are fetched.
+    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.`
+    }
+  },
   "lint": {
     "summary": `# lint
 Run design quality and accessibility checks.
@@ -745,7 +899,18 @@ Methods:
 
 Use lint(method: "help", topic: "<method>") for method details.`,
     "methods": {
-      "check": '# lint.check\nRun design linter on a node tree\n\nExample: lint(method:"check", nodeId:"0:1", rules:["wcag","hardcoded-color"])\n\nParams:\n    nodeId (string, optional) \u2014 Node ID to lint. If omitted: 1 selected node \u2192 lints that node, 2+ selected \u2192 lints entire page (not the selection), 0 selected \u2192 error. Always pass nodeId explicitly for reliable targeting.\n    rules (string[], optional) \u2014 Rules to run. Default: ["all"]. Categories: "component", "composition", "token", "naming", "wcag"/"accessibility". Or specific rule names.\n    maxDepth (number, optional) \u2014 Max tree depth (default: 10)\n    maxFindings (number, optional) \u2014 Max findings (default: 50)',
+      "check": `# lint.check
+Run design linter on a node tree
+
+Example: lint(method:"check", nodeId:"0:1", rules:["wcag","hardcoded-color"])
+
+Params:
+    nodeId (string, optional) \u2014 Node ID to lint. If omitted: 1 selected node \u2192 lints that node, 2+ selected \u2192 lints entire page (not the selection), 0 selected \u2192 error. Always pass nodeId explicitly for reliable targeting.
+    rules (string[], optional) \u2014 Rules to run. Default: ["all"]. Categories: "component", "composition", "token", "naming", "wcag"/"accessibility". Or specific rule names.
+    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"
     }
   },
@@ -776,7 +941,7 @@ Use lint(method: "help", topic: "<method>") for method details.`,
     }
   },
   "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 [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  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.',
     "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)',
@@ -799,15 +964,14 @@ Params:
       strokeLeftWeight (string, optional)
       strokeRightWeight (string, optional)
       strokeAlign (INSIDE | OUTSIDE | CENTER, optional) \u2014 Stroke position (default: INSIDE)
-      strokesIncludedInLayout (boolean, optional) \u2014 Include stroke width in layout measurements (default: false)
       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) \u2014 Opacity (0-1) or variable name
       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
       layoutMode (NONE | HORIZONTAL | VERTICAL, optional) \u2014 Layout direction (default: NONE)
@@ -821,6 +985,7 @@ Params:
       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)
       layoutSizingHorizontal (FIXED | HUG | FILL, optional)
       layoutSizingVertical (FIXED | HUG | FILL, optional)
       layoutPositioning (AUTO | ABSOLUTE, optional) \u2014 ABSOLUTE = floating inside auto-layout parent
@@ -852,6 +1017,8 @@ Params:
       width (number, optional)
       height (number, optional)
       clearFill (boolean, optional) \u2014 Remove all fills
+      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)
       effects (array, optional) \u2014 Effect array (DROP_SHADOW, INNER_SHADOW, LAYER_BLUR, BACKGROUND_BLUR)
       overflowDirection (NONE | HORIZONTAL | VERTICAL | BOTH, optional) \u2014 Scroll overflow in prototype (default: NONE)
       constraints (object, optional)
@@ -861,9 +1028,10 @@ Params:
         variableId (string, optional)
       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\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": "# 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.",
       "audit": `# text.audit
 Run lint on a node \u2014 returns severity-ranked findings
 
@@ -909,6 +1077,7 @@ Params:
       textAutoResize (NONE | WIDTH_AND_HEIGHT | HEIGHT | TRUNCATE, optional) \u2014 NONE (fixed box), WIDTH_AND_HEIGHT (grow both), HEIGHT (fixed width, auto height), TRUNCATE (fixed + ellipsis)
       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"
@@ -1032,6 +1201,7 @@ function registerTools(server, sendCommand, caps, tools) {
           return { content: [{ type: "text", text }] };
         }
         if (tool.validate) tool.validate(params);
+        if (tool.preProcess) await tool.preProcess(params);
         const command = resolveCommand(tool, params);
         params._caps = caps;
         const result = await sendCommand(command, params, timeout);