figma-relai 0.7.10 → 0.8.0

package/dist/{chunk-PYVHVZTO.js → chunk-62ZA4AUN.js}

@@ -4,81 +4,13 @@ import {
 } from "./chunk-SDINVROO.js";
 import {
   loadToken,
-  noteAuthFailure
-} from "./chunk-VS2FNFYC.js";
+  noteAuthFailure,
+  stateDir
+} from "./chunk-INWZM5QK.js";
 import {
   __export
 } from "./chunk-2H7UOFLK.js";
 
-// src/version.ts
-var VERSION = "0.7.10";
-
-// src/server.ts
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-function createServer() {
-  return new McpServer(
-    {
-      name: "Relai",
-      version: VERSION
-    },
-    {
-      instructions: `
-You control Figma through ~30 consolidated tools. Pairing with the Figma plugin is automatic \u2014 just call any tool; join_room is only needed if an error reports multiple plugins.
-
-\u{1F4D6} UNDERSTAND (start here):
-  get_document_overview \u2014 structure, page/component/style/variable counts
-  get_selection_context \u2014 full context for what the designer selected
-  get_node_details \u2014 deep single-node inspection (CSS, token bindings)
-  search_nodes \u2014 find nodes by name/type \xB7 get_node_data \u2014 raw data/tree/css
-  get_design_tokens \u2014 variable collections, modes, styles
-  screenshot \u2014 see the canvas (use this to verify your work visually)
-
-\u{1F50D} DIAGNOSE:
-  analyze_design \u2014 aspect: color/layout/components/accessibility, or
-    "overall" for a weighted 0-100 health score across all four
-  diff_nodes \u2014 compare two nodes, or checkpoint save/compare to audit
-    what changed on a node over an editing session
-
-\u270F\uFE0F EDIT:
-  create_node \u2014 any node type (rectangle/frame/text/svg/image/\u2026)
-  set_properties \u2014 one call for geometry, fills, strokes, effects, text,
-    auto-layout, constraints, style/variable bindings, on one or many nodes
-  set_text \u2014 single, bulk, or character-range text edits
-  edit_structure \u2014 group/reparent/reorder/clone/flatten/boolean/delete
-  navigate \u2014 focus/select/viewport/switch_page \xB7 manage_pages
-
-\u{1F9F1} DESIGN SYSTEM:
-  manage_components \u2014 create/variants/instantiate/overrides/props/detach
-  manage_variables \u2014 collections, modes, tokens, bind/unbind
-  manage_styles \u2014 paint/text/effect/grid styles
-  import_from_library \u2014 bring in library components/styles/variables
-
-\u{1F4E6} ASSETS: export_asset (PNG/JPG/SVG/PDF) \xB7 add_image (URL or fill)
-\u{1F4DD} ANNOTATIONS: annotate (Dev Mode annotations)
-\u{1F4AC} COMMENTS: manage_comments \u2014 read/apply/reply to file comments
-  (needs FIGMA_TOKEN env; the tool explains setup when missing)
-
-\u2705 VERIFY: verify_changes \xB7 validate_design_rules
-
-\u26A1 ADVANCED:
-  batch_execute \u2014 run many plugin-level commands in one round-trip
-  execute_figma \u2014 run JavaScript against the Figma Plugin API directly
-    (the escape hatch when no tool fits; small incremental scripts,
-     screenshot between steps; the designer can disable it)
-
-OPERATING PRINCIPLES:
-- Inspect context BEFORE changing things; don't assume selection state
-- After visual edits, verify: screenshot or verify_changes
-- Colors are RGBA in 0-1 range (Figma format), not 0-255
-- layoutSizing FILL requires the node's PARENT to have auto-layout;
-  set layoutMode on a frame before padding/alignment/spacing
-- Responses include recommended_next tools \u2014 follow them
-- Errors name the node, its type, and the fix \u2014 read them, don't retry blindly
-`
-    }
-  );
-}
-
 // ../shared/src/types/commands.ts
 var FIGMA_COMMANDS = [
   // Document & Selection
@@ -487,7 +419,7 @@ var PITFALLS = [
   {
     pattern: null,
     hint: "",
-    doc: "**Text edits inside a component SET propagate to every variant.** Applying a text style to one variant's label retypes the matching layer in all of them \u2014 same for `textDecoration` and text fills, at node level and via `setRange*` alike. Renaming the layer does not break the link (matching is positional). So a set whose sizes need DIFFERENT text styles cannot be styled in place: apply the styles while the components are still standalone and combine afterwards \u2014 an atom does not save you either unless the atom's variants are standalone components rather than a set of their own. Two more from the same afternoon: `combineAsVariants` drops `textDecoration`, and a decoration written in the same execution as `setTextStyleIdAsync` is clobbered by the style landing \u2014 set it in a later call."
+    doc: "**Text edits inside a component SET propagate to every variant.** Applying a text style to one variant's label retypes the matching layer in all of them \u2014 same for `textDecoration` and text fills, at node level and via `setRange*` alike. Renaming the layer does not break the link (matching is positional). So a set whose sizes need DIFFERENT text styles cannot be styled in place: apply the styles while the components are still standalone and combine afterwards \u2014 an atom does not save you either unless the atom's variants are standalone components rather than a set of their own. Layers bound to one TEXT component property are linked through the property as well: every layer whose `characters` references it shares a single `textDecoration` \u2014 write it on one variant and all of them change, re-binding a layer pulls it back to the shared value, and only a layer whose reference is removed keeps its own. The binding step writes too: pointing five variants' titles at a new TEXT property replaced their `characters` with the property's default and reset their underline to `NONE`, while the `combineAsVariants` just before it had kept every variant's underline. So a label whose decoration differs per variant cannot sit on a shared TEXT property. And a decoration written in the same execution as `setTextStyleIdAsync` is clobbered by the style landing \u2014 set it in a later call."
   },
   {
     pattern: null,
@@ -547,22 +479,22 @@ var PITFALLS = [
   {
     pattern: null,
     hint: "",
-    doc: '**A plain write clears a variable-bound component property only on the node you write to \u2014 read back to confirm which node still holds the alias.** `instance.setProperties({ key: "diamond" })` does drop the `VARIABLE_ALIAS` on that instance (measured both with a different value and with the token\'s own resolved string). What surprises people is where the binding *else* lives: set it on one instance and the main component keeps its own alias, so re-reading the master still reports bound; and an instance nested two levels down (`.Icon Content` inside a `Body Cell` inside a `Column`) carries its own override that the parent write never touches. Always read the property back on the exact node you meant to change, and sweep nested instances separately.'
+    doc: '**A plain write clears a variable-bound component property only on the node you write to \u2014 read back to confirm which node still holds the alias.** `instance.setProperties({ key: "diamond" })` does drop the `VARIABLE_ALIAS` on that instance (measured both with a different value and with the token\'s own resolved string). What surprises people is where the binding *else* lives: set it on one instance and the main component keeps its own alias, so re-reading the master still reports bound; and an instance nested two levels down (an icon instance inside a `Body Cell` inside a `Column`) carries its own override that the parent write never touches. Always read the property back on the exact node you meant to change, and sweep nested instances separately.'
   },
   {
     pattern: null,
     hint: "",
-    doc: '**Component property keys are `name#id`, and the name may itself contain `#`** \u2014 `.Icon Content` ships `Icon Name#4866:0`, `Icon Name w/##4866:28` and `Icon Name w/###4866:56`. Splitting on the *first* `#` maps the last two to the same base name, so a lookup silently binds only one of them and the duotone layers keep their placeholder glyph. Split on `lastIndexOf("#")`. The mirror trick is useful: matching on the `#id` tail alone follows a property across a rename, since `editComponentProperty` keeps the id.'
+    doc: '**Component property keys are `name#id`, and the name may itself contain `#`** \u2014 an icon component can ship `Icon Name#4866:0`, `Icon Name w/##4866:28` and `Icon Name w/###4866:56`. Splitting on the *first* `#` maps the last two to the same base name, so a lookup silently binds only one of them and the duotone layers keep their placeholder glyph. Split on `lastIndexOf("#")`. The mirror trick is useful: matching on the `#id` tail alone follows a property across a rename, since `editComponentProperty` keeps the id.'
   },
   {
     pattern: null,
     hint: "",
-    doc: "**A plugin-created instance placed under an explicit variable mode stays stuck on the placeholder, and waiting does not fix it.** Create an instance, drop it under a node whose Theme mode differs from the page's, and read it back: the nested variant *does* swap (`iconFamily=Phosphor` \u2192 `FA7`), but a component property bound to a variable resolves to the new variant's **default** rather than to the token, so every icon reads as the placeholder glyph. Measured: still wrong after three minutes untouched \u2014 in `characters` and in the rendered screenshot alike \u2014 and setting the *same* mode again changes nothing. What unsticks it is `clearExplicitVariableModeForCollection` followed by `setExplicitVariableModeForCollection`; the binding was never destroyed, only unresolved. (Distinct from the few-second repaint lag a designer sees after switching a theme by hand on content that already exists.) A brand-switch probe built and screenshotted in one pass will therefore report that a whole file's icon tokens are broken when nothing is wrong: clear-and-re-set before reading, and confirm against a node that was already in the file."
+    doc: "**An instance under an explicit variable mode can get stuck on the placeholder \u2014 when a plugin creates it there, or switches its variant there \u2014 and waiting does not fix it.** Create an instance, drop it under a node whose Theme mode differs from the page's, and read it back: the nested variant *does* swap (`iconFamily=Phosphor` \u2192 `FA7`), but a component property bound to a variable resolves to the new variant's **default** rather than to the token, so every icon reads as the placeholder glyph. Measured: still wrong after three minutes untouched \u2014 in `characters` and in the rendered screenshot alike \u2014 and setting the *same* mode again changes nothing. What unsticks it is `clearExplicitVariableModeForCollection` and then `setExplicitVariableModeForCollection` **in two separate `execute_figma` calls**: clearing and re-setting inside one script leaves it stuck (measured both when read 1.5 seconds later in the same script and when read in the next call). The binding was never destroyed, only unresolved. The order does not matter: appending to a parent with no explicit mode and setting the parent's mode in a later call leaves the same placeholder. Nor does it take a new instance: switching an existing instance's variant with `setProperties` under a pinned parent drops the same way \u2014 glyph properties fall back to the unbound placeholder, icon fills to the default variable, a bound size to none \u2014 but only in modes that swap a nested instance to a different variant than its main uses; where the mode resolves to the main's own icon family, nothing drops. Clear-then-set in separate calls restored every binding in both cases. It is not a sure cure: in another probe (five button instances created in one call, their parent's mode set in the next), clearing and setting the mode in two further calls, then setting it on each instance too, left the two loading buttons' variable-bound glyph names on the placeholder. Writing the resolved values with `setProperties` did stick there, as long as only properties whose value differs are written: writes that repeated the variant properties' current values flipped the nested icon to the main's own variant in 2 of 7 cases (both on the instances with bound glyph names), and writing the differing value back fixed it. That write costs the binding \u2014 a plain write drops the alias on that node (see the plain-write entry) \u2014 so it suits a throwaway probe, not a file's instances. (Distinct from the few-second repaint lag a designer sees after switching a theme by hand on content that already exists.) A brand-switch probe built and screenshotted in one pass will therefore report that a whole file's icon tokens are broken when nothing is wrong: clear in one call, set in the next, read after that \u2014 and confirm against a node that was already in the file."
   },
   {
     pattern: null,
     hint: "",
-    doc: "**`variable.remove()` succeeds even when instances still bind it, and the variable keeps working \u2014 so a retirement can look clean and change nothing.** After removing it, `getLocalVariablesAsync()` no longer lists it (the designer sees it gone from the panel) but `getVariableByIdAsync(id)` still resolves it, the bindings still render its last value, and no error is raised anywhere. The trap is upstream, in the consumer scan that told you it was safe: a walker that does `if (node.type === 'INSTANCE') { check its componentProperties; return }` never descends into nested instances, and component-property bindings mostly live there \u2014 an `.Icon Content` inside a `Body Cell` inside a `Column`. One retirement measured 0 consumers by that walk and 160 by a walk that recursed. Before removing a variable, recurse through instance children; afterwards the id keeps resolving forever (it is a tombstone, not proof of failure), so verify instead that it has left `getLocalVariablesAsync()` and that a recursive scan finds zero bindings."
+    doc: "**`variable.remove()` succeeds even when instances still bind it, and the variable keeps working \u2014 so a retirement can look clean and change nothing.** After removing it, `getLocalVariablesAsync()` no longer lists it (the designer sees it gone from the panel) but `getVariableByIdAsync(id)` still resolves it, the bindings still render its last value, and no error is raised anywhere. The trap is upstream, in the consumer scan that told you it was safe: a walker that does `if (node.type === 'INSTANCE') { check its componentProperties; return }` never descends into nested instances, and component-property bindings mostly live there \u2014 an icon instance inside a `Body Cell` inside a `Column`. One retirement measured 0 consumers by that walk and 160 by a walk that recursed. Before removing a variable, recurse through instance children; afterwards the id keeps resolving forever (it is a tombstone, not proof of failure), so verify instead that it has left `getLocalVariablesAsync()` and that a recursive scan finds zero bindings."
   },
   {
     pattern: null,
@@ -575,9 +507,9 @@ var PITFALLS = [
     doc: "**`setBoundVariable` takes a Variable object, not an id string** \u2014 the string form throws `Cannot call setBoundVariable with a variable id. Please pass a variable object`. Fetch the variable first (`getVariableByIdAsync`, or a map built from `getLocalVariablesAsync`) and pass the object itself."
   },
   {
-    pattern: null,
-    hint: "",
-    doc: "**Rebinding width/height on a node INSIDE an instance is a silent no-op** \u2014 `setBoundVariable` returns without error and `boundVariables` still shows the old id afterwards. Only `setBoundVariable(field, null)` (unbind) persists there. Stuck overrides \u2014 bindings an instance kept from a main that has since been cleaned \u2014 can therefore never be re-pointed from code, only cleared; and if the main is already clean, clearing IS the correct repair (the node falls back to the main's shape, pixels stay put). Measured on 301 soft-deleted `Size/height/12` bindings (2026-08-12): rebind reported success \xD7301 and changed nothing; unbind cleared every one. Always read the field back after writing \u2014 success without verification is how this one hides."
+    pattern: "cannot be overridden in an instance: size",
+    hint: "The size of a node inside an instance cannot be overridden from code: rescale() throws this, and resize(), resizeWithoutConstraints() and setBoundVariable('width'|'height', v) return without error and change nothing. Change the size in the main component (e.g. a variant with that size) or swap the nested instance. To back out of a half-done attempt, removeOverrides() on the nested instance clears only that layer and below \u2014 the outer instance keeps its own overrides.",
+    doc: "**Giving a node INSIDE an instance a new width/height from code does nothing \u2014 rebinding width/height and `resize()` are silent no-ops, and `rescale()` throws.** `setBoundVariable` returns without error and `boundVariables` still shows the old id afterwards. Only `setBoundVariable(field, null)` (unbind) persists there. On a nested instance (a logo inside a footer instance), `resize()`, `resizeWithoutConstraints()` and `resize()` after `unlockAspectRatio()` all returned normally and read back the old 105.3\xD748, and `rescale(0.75)` threw `This property cannot be overridden in an instance: size` \u2014 change the size in the main (a variant with that size) instead. To back out, `removeOverrides()` on the nested instance clears only the overrides from that layer down; the outer instance keeps its own. Stuck overrides \u2014 bindings an instance kept from a main that has since been cleaned \u2014 can therefore never be re-pointed from code, only cleared; and if the main is already clean, clearing IS the correct repair (the node falls back to the main's shape, pixels stay put). Measured on 301 soft-deleted `Size/height/12` bindings (2026-08-12): rebind reported success \xD7301 and changed nothing; unbind cleared every one. Always read the field back after writing \u2014 success without verification is how this one hides. One sizing write does persist inside an instance: setting `layoutSizingHorizontal` / `layoutSizingVertical` to `HUG` on the inner node is kept, and it also clears stale overrides that point at nodes which no longer exist."
   },
   {
     pattern: "Component set (for node )?has existing errors",
@@ -602,10 +534,233 @@ var PITFALLS = [
   {
     pattern: null,
     hint: "",
-    doc: "**`combineAsVariants` re-keys every component property and can drop a TEXT property's `characters` reference on the way.** The ids in property keys (`title#1033:0`) belong to the standalone components; combining mints new set-level keys (`title#7527:4`) \u2014 so any key strings you saved before combining are stale afterwards. Worse, the re-wiring is lossy: in one measured combine the `title` reference survived on all variants while the `description` reference vanished from all of them, with no error. After every combine, audit `componentPropertyReferences` across all variants against the set's `componentPropertyDefinitions` and re-wire the orphans (survival is luck, not a rule \u2014 this is the same disease as duplicated variants keeping no references, in a different coat)."
+    doc: "**`combineAsVariants` re-keys every component property and can drop a TEXT property's `characters` reference on the way.** The ids in property keys (`title#1033:0`) belong to the standalone components; combining mints new set-level keys (`title#7527:4`) \u2014 so any key strings you saved before combining are stale afterwards. Worse, the re-wiring is lossy: in one measured combine the `title` reference survived on all variants while the `description` reference vanished from all of them, with no error. Existing instances do ride through the re-keying: when `combineAsVariants` turned a lone component into a set of one variant (the second was added afterwards), its TEXT key changed (`text#N:61` \u2192 `text#N:62`), the reference survived, and all 176 instances kept their text, size and position. After every combine, audit `componentPropertyReferences` across all variants against the set's `componentPropertyDefinitions` and re-wire the orphans (survival is luck, not a rule \u2014 this is the same disease as duplicated variants keeping no references, in a different coat)."
+  },
+  {
+    pattern: null,
+    hint: "",
+    doc: "**Writing `textAutoResize` resets a text node's truncation.** Assigning `NONE`, `HEIGHT` or `WIDTH_AND_HEIGHT` \u2014 including the value it already holds \u2014 sets `textTruncation` back to `DISABLED` and `maxLines` to `null`, with no error (24/24 cases, auto-layout children and free nodes alike). The deprecated `TRUNCATE` keeps `ENDING` but still drops `maxLines`; don't lean on it. `resize()` and `layoutSizingHorizontal` leave `textTruncation` alone, but they can flip `textAutoResize` between `HEIGHT` and `WIDTH_AND_HEIGHT` on the way. Order the writes: `textAutoResize` first, then `textTruncation` and `maxLines`, and re-read all three after any sizing change. On a node whose `textAutoResize` is `NONE`, writing `ENDING` reads back as `TRUNCATE`, and `maxLines = 1` is accepted but reads back `null`."
+  },
+  {
+    pattern: "Removing this node is not allowed",
+    hint: "Some nodes cannot be removed from the Plugin API. Known source: an INSTANCE with slots keeps each slot's content in a parentless FRAME (parent === null); while the instance lives that FRAME is its slot storage, and once the instance is removed \u2014 made by createInstance() or by clone() \u2014 the FRAME stays behind: remove() on it, or on the instances inside it, throws this, and getInstancesAsync() still returns those instances. Leave it, exclude nodes whose ancestor chain never reaches a PAGE from audits, and stop building probes out of slot-bearing instances.",
+    doc: "**Removing an instance that has slots leaves undeletable orphans behind \u2014 whether it came from `createInstance()` or `clone()`.** An instance with SLOT content keeps each slot's content in a `FRAME` with `parent === null`, holding the slotted instances; while the instance exists that frame is its live storage, not litter. Delete the instance and the frame stays. It sits on no page and nothing shows it, but `remove()` on it (or on the instances inside it) throws `Removing this node is not allowed`, and `component.getInstancesAsync()` keeps returning those instances: one probe that cloned slot-bearing instances to check variable modes took a component set's instance count (summed over its variants) from 545 to 959, and two probes built with `createInstance()` and deleted again left 24 such frames. Whether reopening the file clears them has not been measured. Don't build probes out of slot-bearing instances \u2014 to see one under another mode, resolve its variables against an existing node in that mode (`variable.resolveForConsumer(node)`) \u2014 and in instance audits drop any result whose ancestor chain never reaches a PAGE."
+  },
+  {
+    pattern: null,
+    hint: "",
+    doc: "**Overriding an instance's text freezes the layer's styling along with it.** Writing `characters` on a text layer inside an instance stores the layer's `styledTextSegments` in the override, so the layer stops following its main per variant: an instance made from a variant whose title has a 1px underline, switched to a variant whose title has a 2px one, kept its own text *and* the 1px \u2014 and it will not follow a later change to the main's text styling either. Binding the layer to a TEXT property instead has its own edge: switch to a variant whose layer is not bound to that property and the text reverts to that variant's own. Create the instance from the variant it should show before overriding its text, and read the decoration back after any variant switch."
+  },
+  {
+    pattern: null,
+    hint: "",
+    doc: "**An instance reads its main component's pluginData as its own, and emptying a key on the instance leaves an override behind.** `instance.getPluginData(key)` returns the main's value when the instance never set one \u2014 clear the key on the main and it disappears from every instance, and a sweep that counts keys node by node counts each inherited copy again (one cleanup found 188 keys, 94 of them inherited). Writing `''` on an instance does empty its value, but `pluginData` stays in that instance's `overriddenFields`, and nothing removes that entry alone: `removeOverrides()` also discards every rename and resize beside it. Clear a marker on the node you set it on, and don't read a key found on an instance as proof that the instance itself was marked."
+  },
+  {
+    pattern: "createVMObject",
+    hint: "getNodeByIdAsync was handed the bare number of a variable or variable collection \u2014 they share the N:M id counter with nodes, and instead of returning null the call throws. Read variables with figma.variables.getVariableByIdAsync('VariableID:N:M') and collections with getVariableCollectionByIdAsync('VariableCollectionId:N:M'); when scanning an id range, wrap each getNodeByIdAsync in its own try/catch.",
+    doc: "**`getNodeByIdAsync` throws on the bare id of a variable or collection.** Variables and collections draw from the same `N:M` counter as nodes, so a scan over an id range lands on them: `getNodeByIdAsync('N:M')` for a variable's number throws `unsupported type in createVMObject: VARIABLE` (`VARIABLE_SET` for a collection) instead of returning `null`, while the prefixed `VariableID:N:M` just returns `null`. Catch per id when sweeping ranges, and resolve variables through `figma.variables.getVariableByIdAsync`."
+  },
+  {
+    pattern: "Empty range selected",
+    hint: "Range APIs reject empty ranges \u2014 end must be greater than start. On an empty text node getRangeAllFontNames(0, node.characters.length) is (0, 0) and throws; read node.fontName there (it is never mixed on empty text), and skip range calls whenever start === end.",
+    doc: "**Range reads throw on an empty range, so an empty text node breaks the usual font-loading loop.** `getRangeAllFontNames(0, node.characters.length)` on a node whose `characters` is `\"\"` throws `Empty range selected. 'end' must be greater than 'start'`, and so does any `getRange*` read with `start === end` (`getRangeFontName(0, 0)`, `getRangeAllFontNames(1, 1)` on `\"ab\"`). `node.fontName` answers normally there and `getStyledTextSegments(['fontName'])` returns `[]`. Load `fontName` when the text is empty, and call range APIs only when `end > start`."
+  },
+  {
+    pattern: null,
+    hint: "",
+    doc: '**`exportAsync` renders only what a clipping ancestor leaves visible, so pixel diffs of clipped content compare nothing.** By default a node is exported at its `absoluteRenderBounds`, which a `clipsContent` ancestor cuts: a 100\xD7300 child of a clipping 100\xD7100 frame exports as 100\xD7100, and a child clipped away entirely (its `absoluteRenderBounds` is `null`) exports as a 1\xD71 image \u2014 so the hidden rows of a clipped table "match" before and after whatever you changed in them. `exportAsync({ format: "PNG", useAbsoluteBounds: true })` renders the whole node, byte-identical to exporting it with the ancestor unclipped; use it for before/after comparisons, or compare `absoluteRenderBounds` with `absoluteBoundingBox` before trusting a diff.'
+  },
+  {
+    pattern: null,
+    hint: "",
+    doc: "**Switching a nested instance's variant can discard the overrides its container put inside it.** Inside a component, `setProperties({ state: \"default\" })` on a nested icon button moved it to the new variant but dropped what the component had set on the button's icon: the three glyph properties bound to variables came back as the new variant's unbound default, and the icon's bound fill as the default variable \u2014 only the binding on the icon's variant property (`style`) survived. No error, and instances of the component show the placeholder from then on. After switching a nested instance's variant, re-read its content node by node and rebind from a sibling variant that is already in the target state."
+  },
+  {
+    pattern: null,
+    hint: "",
+    doc: "**Slot content that is already on another variant when it enters the slot can come back with ids that resolve to nothing.** If a nested instance in the content is already on a different variant than the component defines for it when the content lands in the slot \u2014 an explicit mode swapped an icon to another family, or an override set a menu item to `state=hovered` \u2014 its descendants get ids missing the slot's segment: `getNodeByIdAsync` answers `null` for them, and two items can report the same id. Switching the variant after the content is in the slot keeps the ids whole. The repair measured on a 311-node menu: clear the mode in one call, set the swapped item to its default variant in place in the next and back in the one after, then set the mode \u2014 14 unreadable nodes went to 0; clearing and re-setting the mode alone fixed 13 of them, not a hidden layer. Walk slot content with a per-node try/catch that records the path instead of stopping."
+  },
+  {
+    pattern: null,
+    hint: "",
+    doc: "**When a variable mode swaps a nested instance to another variant, the swap is stored as overrides, and later binding changes on the main stop reaching it.** Eighteen instances were created in one call and their parents' Theme modes set in the next: in the mode that resolves the nested icon to the main's own variant, the nested instance carried no overrides; in each of the five modes that swapped it, it carried `boundVariables`, `componentProperties`, `fills`, `name`, both axis sizing modes and `targetAspectRatio` as overrides. Rebinding that nested instance's `style` property to a new variable in the main then reached only the unswapped instance \u2014 the other five kept reading the old variable \u2014 while fresh instances with the modes set again all showed the new binding. Instances that were already in the file carried the same overrides. After changing a binding in a main, re-create probe instances rather than re-reading old ones, and read `overrides` on the nested layer before trusting that the change reached instances under other modes."
+  },
+  {
+    pattern: null,
+    hint: "",
+    doc: "**A VECTOR whose corners are rounded per vertex ignores `cornerRadius` writes on an instance, and only `rescale` scales those corners.** When the radius lives in `vectorNetwork.vertices[i].cornerRadius` (a glyph outline with 12 and 9 rounded vertices), writing the node's `cornerRadius` inside an instance adds a `cornerRadius` entry to `overrides` and nothing else: it reads back the main's 0.449, the vertices keep it, and the render is pixel-identical. Writing the main's value back leaves the entry behind; only `removeOverrides()` clears it, along with every other override on that instance. `resize()` scales the outline but not the vertex radii, so an instance resized 2.4\xD7 draws sharper corners than the main scaled 2.4\xD7 (alpha differs by up to 175/255 at the corners). `rescale(2.4)` scales the vertex radii too (0.449 \u2192 1.079, within 16/255 of the scaled main), but it does not coexist with a variable-bound height: binding `height` after `rescale` resets `scaleFactor` to 1 and the radii to 0.449 (with the aspect ratio locked as well), and `rescale` after binding multiplies the bound height (72 \u2192 259.2). Pick either the bound height or proportional corners."
+  },
+  {
+    pattern: null,
+    hint: "",
+    doc: "**A bound paint's `color` is only a fallback \u2014 and one component set kept the fallback on screen.** `figma.variables.setBoundVariableForPaint(paint, 'color', v)` returns the paint with your `color` untouched (a `{0,0,0}` placeholder stays `{0,0,0}`). Assigned through `fills` or `setRangeFills`, the stored color is normally replaced by the variable's resolved value: in eight probes (node fills on text and on a rectangle; `setRangeFills` over a whole text, part of one, a text in a set variant, in a standalone component and on a TEXT-property layer) it read back as the resolved gray, and the exported ones rendered it. But four ranges written with `setRangeFills` in two variants of a working component set kept `{0,0,0}` while still bound, and rendered black; a scan of the 168 bound paints around them found no other mismatch, and the trigger was not isolated. Build bound paints with the resolved color (take `{ r, g, b }` from `v.resolveForConsumer(node).value` \u2014 it carries `a`, and a paint's `color` has no alpha) instead of a dummy, and after writing compare each bound paint's stored `color` with the resolved value. The same showed up on an instance whose fill override was bound to the very variable its main uses but stored `{0,0,0}`: it exported black where the main exported light."
+  },
+  {
+    pattern: null,
+    hint: "",
+    doc: "**A blank symbol in a text node is not proof the font lacks it \u2014 the node can be holding a stale layout.** Key labels drew `\u2318` as empty space on some nodes and fine on others, all in the same monospace font, which has no `\u2318`, `\u21E7` or `\u23CE`: Figma draws those with its own fallback glyph, and the blank nodes held an old layout \u2014 `width` 7, the missing-glyph advance, where drawn ones measured 9 for `\u2318`/`\u23CE` and 8 for `\u21E7`. Switching the font does not help: a font whose file does contain `\u2318` and `\u23CE` still drew the same fallback glyph, and writing that font on the key text inside the masters' nested instances spread wrongly \u2014 145 of the file's 301 keys came out wrong, including keys with no symbol at all. What brought the glyph back was a fresh layout, reached the long way: on the five keys that had been given that font, `removeOverrides()` (which also returned the TEXT property to the main's default), then restoring the layer name and writing the property back to its symbol \u2014 the glyph appeared and the five keys grew 1\u20132 px. Writing the same value again without clearing first was not tried. Before blaming the font, compare the node's `width` with a node that renders; to repair, clear the overrides, write the text property back, and re-read the width."
+  },
+  {
+    pattern: null,
+    hint: "",
+    doc: "**`remove()` on a COMPONENT leaves its id resolving, so a `null` lookup cannot confirm the cleanup.** After removing a component \u2014 standalone, or a variant removed along with its set \u2014 `getNodeByIdAsync(id)` still returns it, children included, with `parent === null` and `removed === false`; calling `remove()` on it again returns normally and changes nothing. Measured on four components removed in the call that created them; the COMPONENT_SET itself, and plain frames, text and rectangles removed the same way, did resolve to `null`. The component sits on no page and no page's children list it, but id sweeps find it; whether it goes away later has not been measured. Confirm component cleanup by ancestry (the chain must no longer reach a PAGE) rather than `null`, and build temporary probes from frames or instances of existing components rather than new components."
+  },
+  {
+    pattern: null,
+    hint: "",
+    doc: "**Renaming a variant axis with `editComponentProperty` unbinds the instances, and can reset their plain overrides too.** Instances bound to that property keep their value but lose the `boundVariables.componentProperties` alias, nested explicit overrides included. In one measured rename, 71 instances whose value for the axis was a plain override \u2014 not bound to anything \u2014 fell back to the set's default variant. Right after rebinding, some instances kept an old value that disagreed with what the mode resolves to; writing the value first and then rebinding fixed them. Before renaming an axis, record every instance's value and binding for it; afterwards write the values back, rebind, and read both back."
+  },
+  {
+    pattern: null,
+    hint: "",
+    doc: "**`figma.skipInvisibleInstanceChildren` is plugin-wide, not per script.** Setting it to `true` \u2014 a common speed-up for `findAll` \u2014 hides invisible sublayers of instances from every search that runs while it is set, not only the script that set it. Relai puts the previous value back after each `execute_figma` script, so it does not leak into later commands; set it again in every script that wants it, and while it is on, do not read an instance sublayer missing from a search as deleted."
   }
 ];
 
+// ../shared/src/types/call.ts
+var ERROR_CODES = [
+  // Server: reaching the relay and the plugin
+  "not_connected",
+  // no live link to the relay when the call was made; nothing was sent
+  "relay_unresponsive",
+  // the relay did not answer a room listing or join in time; nothing changed
+  "plugin_absent",
+  // no Figma plugin is in the target room
+  "room_ambiguous",
+  // several plugins are open and the call did not say which room
+  "room_changed",
+  // the session was re-paired to a room on a different file; resend to confirm
+  "wrong_file",
+  // the target file's name is not the expected one (server precheck or plugin recheck)
+  "cannot_verify_file",
+  // an expected file was given but the plugin did not report its file name
+  // Plugin: refused before the command ran
+  "unknown_command",
+  // the plugin has no handler for the command (plugin older than the server)
+  "denied_by_designer",
+  // the designer declined the approval card
+  "approval_timeout",
+  // nobody answered the approval card before it timed out
+  "cancelled",
+  // Stop pressed before the command started or while its card waited; also skipped batch items
+  "guard_blocked",
+  // the write touches a page the designer marked as a no-go zone
+  "scope_locked",
+  // the write falls outside the designer's scope lock
+  "designer_only",
+  // the command is reserved for the designer's panel
+  "code_exec_disabled",
+  // code execution is switched off in the panel
+  "node_not_found",
+  // a referenced node does not exist (checked before any change)
+  "precondition_failed",
+  // a referenced node has the wrong type or is locked (checked before any change)
+  "capacity_exceeded",
+  // file memory (precedents or rulesets) is full
+  "invalid_params",
+  // the arguments are malformed (from the plugin or the server's own checks)
+  "script_compile_error",
+  // the script did not compile, so none of it ran
+  // Plugin: failed while running
+  "script_error",
+  // the script threw while running; scripts are not atomic, earlier changes stay
+  "handler_error",
+  // any other error thrown by a command handler
+  "figma_internal",
+  // Figma itself reported an internal error (it reads like a connection error but is not one)
+  // Server: lost track of a request in flight
+  "timeout",
+  // no result arrived in time; the command may have run
+  "link_dropped",
+  // the link to the plugin closed while the request was in flight
+  "cancel_unconfirmed",
+  // Stop was pressed but no real result followed in time
+  // Server: tools that do not go through the plugin
+  "tool_error"
+  // a tool that talks to Figma's REST API or local state failed
+];
+function isErrorCode(value) {
+  return typeof value === "string" && ERROR_CODES.includes(value);
+}
+var ERROR_DEFAULTS = {
+  not_connected: { outcome: "not_applied", retry: "retryable" },
+  relay_unresponsive: { outcome: "not_applied", retry: "retryable" },
+  plugin_absent: { outcome: "not_applied", retry: "needs_human" },
+  room_ambiguous: { outcome: "not_applied", retry: "fix_input" },
+  room_changed: { outcome: "not_applied", retry: "retryable" },
+  wrong_file: { outcome: "not_applied", retry: "fix_input" },
+  cannot_verify_file: { outcome: "not_applied", retry: "fix_input" },
+  unknown_command: { outcome: "not_applied", retry: "needs_human" },
+  denied_by_designer: { outcome: "not_applied", retry: "needs_human" },
+  approval_timeout: { outcome: "not_applied", retry: "needs_human" },
+  cancelled: { outcome: "not_applied", retry: "needs_human" },
+  guard_blocked: { outcome: "not_applied", retry: "needs_human" },
+  scope_locked: { outcome: "not_applied", retry: "needs_human" },
+  designer_only: { outcome: "not_applied", retry: "needs_human" },
+  code_exec_disabled: { outcome: "not_applied", retry: "needs_human" },
+  node_not_found: { outcome: "not_applied", retry: "read_canvas_first" },
+  precondition_failed: { outcome: "not_applied", retry: "fix_input" },
+  capacity_exceeded: { outcome: "not_applied", retry: "fix_input" },
+  invalid_params: { outcome: "not_applied", retry: "fix_input" },
+  script_compile_error: { outcome: "not_applied", retry: "fix_input" },
+  script_error: { outcome: "unknown", retry: "read_canvas_first" },
+  handler_error: { outcome: "unknown", retry: "read_canvas_first" },
+  figma_internal: { outcome: "unknown", retry: "read_canvas_first" },
+  timeout: { outcome: "unknown", retry: "read_canvas_first" },
+  link_dropped: { outcome: "unknown", retry: "read_canvas_first" },
+  cancel_unconfirmed: { outcome: "unknown", retry: "read_canvas_first" },
+  tool_error: { outcome: "not_applied", retry: "fix_input" }
+};
+var CATEGORY_CODES = {
+  precondition_failed: { code: "precondition_failed" },
+  invalid_input: { code: "invalid_params" },
+  type_mismatch: { code: "precondition_failed" },
+  partial_failure: { code: "tool_error", outcome: "applied", retry: "read_canvas_first", partial: true },
+  state_changed: { code: "tool_error", outcome: "not_applied", retry: "read_canvas_first" },
+  capability_limit: { code: "capacity_exceeded" },
+  connection_error: { code: "not_connected" }
+};
+var RelaiError = class extends Error {
+  code;
+  outcome;
+  retry;
+  partial;
+  constructor(code, message, options = {}) {
+    super(message);
+    this.name = "RelaiError";
+    this.code = code;
+    this.outcome = options.outcome ?? ERROR_DEFAULTS[code].outcome;
+    this.retry = options.retry ?? ERROR_DEFAULTS[code].retry;
+    if (options.partial) this.partial = true;
+  }
+};
+var PROTOCOL_VERSION = 2;
+var CALL_META_KEY = "io.github.syoooo.figma-relai/call";
+function aggregateOutcome(outcomes) {
+  if (outcomes.includes("unknown")) return { outcome: "unknown" };
+  if (outcomes.includes("applied")) {
+    return outcomes.includes("not_applied") ? { outcome: "applied", partial: true } : { outcome: "applied" };
+  }
+  return { outcome: "not_applied" };
+}
+function inferLegacyCode(error) {
+  const message = typeof error === "string" ? error : error?.message ?? "";
+  const pick = (code) => ({ code, ...ERROR_DEFAULTS[code] });
+  if (message.includes("no-go zone")) return pick("guard_blocked");
+  if (message.includes("Scope lock:")) return pick("scope_locked");
+  if (message.includes("Code execution is disabled")) return pick("code_exec_disabled");
+  if (message.includes("Node not found") || / has been deleted\. /.test(message)) {
+    return pick("node_not_found");
+  }
+  if (message.includes("Denied by designer")) return pick("denied_by_designer");
+  if (typeof error !== "string" && error?.cancelled === true && message.includes("Cancelled by designer")) {
+    return pick("cancel_unconfirmed");
+  }
+  if (message.includes("Unknown command")) return pick("unknown_command");
+  return pick("handler_error");
+}
+
 // ../shared/src/utils/color.ts
 function rgbaToHex(color) {
   const r = Math.round(color.r * 255);
@@ -696,6 +851,9 @@ var reorderDirectionSchema = z.enum([
 ]);
 
 // ../shared/src/relay-core.ts
+function isAllowedOrigin(origin) {
+  return origin === void 0 || origin === null || origin === "" || origin === "null";
+}
 var RelayCore = class {
   rooms = /* @__PURE__ */ new Map();
   lastActivity = /* @__PURE__ */ new Map();
@@ -880,105 +1038,298 @@ var RelayCore = class {
   }
 };
 
-// src/tools/core/file-identity.ts
-function addressableKey(identity) {
-  return identity.branchKey ?? identity.fileKey;
+// src/version.ts
+var VERSION = "0.8.0";
+
+// src/tools/index.ts
+import { z as z24 } from "zod";
+
+// src/tools/core/helpers.ts
+function textResult(text) {
+  return { content: [{ type: "text", text }] };
 }
-function describeIdentity(identity) {
-  return identity.branchName ? `${identity.fileName} (branch "${identity.branchName}")` : identity.fileName;
+function jsonResult(value) {
+  return textResult(typeof value === "string" ? value : JSON.stringify(value, null, 2));
 }
-async function figmaApi(token, path) {
-  const res = await fetch(`https://api.figma.com/v1${path}`, {
-    headers: { "X-Figma-Token": token }
-  });
-  noteAuthFailure(res.status);
-  const json = await res.json().catch(() => ({}));
-  return { ok: res.ok, status: res.status, json };
+function errorResult(error) {
+  const code = error instanceof RelaiError ? error.code : "tool_error";
+  const retry = error instanceof RelaiError ? error.retry : ERROR_DEFAULTS.tool_error.retry;
+  const meta = { v: 1, error: { code, retry }, calls: [] };
+  return {
+    ...textResult(`Error: ${error instanceof Error ? error.message : String(error)}`),
+    isError: true,
+    _meta: { [CALL_META_KEY]: meta }
+  };
 }
-var FileIdentityError = class extends Error {
-};
-async function resolveFileIdentity(sendCommand) {
-  const probe = await sendCommand("get_file_identity", {});
-  const cached = probe?.identity?.fileKey ? probe.identity : null;
-  if (cached && cached.by === VERSION) return cached;
-  const rootName = probe?.rootName ?? "";
-  const candidates = probe?.candidates ?? [];
-  if (candidates.length === 0) {
-    if (cached) return cached;
-    throw new FileIdentityError(
-      "This file publishes no components, so its key cannot be resolved from the plugin (figma.fileKey is private-plugin-only)."
-    );
+
+// src/call-envelope.ts
+import { AsyncLocalStorage as AsyncLocalStorage2 } from "async_hooks";
+import { z as z2 } from "zod";
+
+// src/call-scope.ts
+import { AsyncLocalStorage } from "async_hooks";
+var slots = new AsyncLocalStorage();
+function runInCommandSlot(slot, fn) {
+  return slots.run(slot, fn);
+}
+function currentCommandSlot() {
+  return slots.getStore();
+}
+function noteSettled(slot, settled) {
+  if (slot && !slot.closed) slot.settled = settled;
+}
+
+// src/result-files.ts
+import { mkdirSync, readdirSync, statSync, unlinkSync, writeFileSync } from "fs";
+import { join } from "path";
+import { randomUUID } from "crypto";
+var KEEP_FILES = 50;
+var MAX_AGE_MS = 24 * 60 * 60 * 1e3;
+function resultsDir() {
+  return join(stateDir(), "results");
+}
+function writeResultFile(callId, text) {
+  try {
+    const dir = resultsDir();
+    mkdirSync(dir, { recursive: true, mode: 448 });
+    pruneResultFiles(dir, KEEP_FILES - 1);
+    const id = (callId ?? "").replace(/[^A-Za-z0-9_-]/g, "") || randomUUID();
+    const path = join(dir, `${Date.now()}-${id}.${looksLikeJson(text) ? "json" : "txt"}`);
+    writeFileSync(path, text, { mode: 384 });
+    return path;
+  } catch {
+    return void 0;
   }
-  const token = loadToken();
-  if (!token) {
-    throw new FileIdentityError(
-      "Resolving the file key needs a Figma token \u2014 store one with `npx -y figma-relai@latest login`."
-    );
+}
+function pruneResultFiles(dir = resultsDir(), keep = KEEP_FILES) {
+  const now = Date.now();
+  const files = readdirSync(dir).filter((name) => name.endsWith(".json") || name.endsWith(".txt")).map((name) => ({ path: join(dir, name), mtime: statSync(join(dir, name)).mtimeMs })).sort((a, b) => b.mtime - a.mtime);
+  files.forEach((file, index) => {
+    if (index >= keep || now - file.mtime > MAX_AGE_MS) {
+      try {
+        unlinkSync(file.path);
+      } catch {
+      }
+    }
+  });
+}
+function looksLikeJson(text) {
+  try {
+    JSON.parse(text);
+    return true;
+  } catch {
+    return false;
   }
-  let main = null;
-  const statuses = [];
-  for (const c of candidates) {
-    const paths = c.kind === "set" ? ["/component_sets/", "/components/"] : ["/components/", "/component_sets/"];
-    for (const p of paths) {
-      const res = await figmaApi(token, `${p}${c.key}`);
-      statuses.push(res.status);
-      const meta = res.json.meta ?? {};
-      if (res.ok && typeof meta.file_key === "string") {
-        main = { fileKey: meta.file_key, via: c.key };
-        break;
+}
+
+// src/call-envelope.ts
+var MAX_TEXT_CHARS = 5e4;
+var RECEIPT_LABEL = "[relai]";
+var scopes = new AsyncLocalStorage2();
+var WRAPPED = /* @__PURE__ */ Symbol("relai.callEnvelope");
+var ENVELOPED_SERVER = /* @__PURE__ */ Symbol("relai.envelopedServer");
+var TARGET_SHAPE = {
+  room: z2.string().optional().describe("Target this plugin room for this call only (see join_room)."),
+  expect_file: z2.string().optional().describe("Refuse unless the target file's name is exactly this.")
+};
+function currentCallTarget() {
+  const scope = scopes.getStore();
+  return {
+    ...scope?.room !== void 0 ? { room: scope.room } : {},
+    ...scope?.expectFile !== void 0 ? { expectFile: scope.expectFile } : {}
+  };
+}
+function withCallEnvelope(server, sendCommand) {
+  if (server[ENVELOPED_SERVER]) return { server, sendCommand };
+  const wrappedServer = new Proxy(server, {
+    get(target, prop, receiver) {
+      if (prop === ENVELOPED_SERVER) return true;
+      if (prop !== "tool") return Reflect.get(target, prop, receiver);
+      return (name, ...rest) => {
+        if (rest.length !== 3 && rest.length !== 4 || typeof rest[0] !== "string") {
+          throw new Error(
+            `Tool "${name}" must be registered as (name, description, shape, [annotations,] handler) to get a call envelope`
+          );
+        }
+        const handler = rest[rest.length - 1];
+        const annotations = rest.length === 4 ? rest[2] : void 0;
+        const wrapped = envelopeHandler(name, handler, annotations?.readOnlyHint === true);
+        const shape = { ...TARGET_SHAPE, ...rest[1] };
+        return target.tool.call(target, name, rest[0], shape, ...rest.slice(2, -1), wrapped);
+      };
+    }
+  });
+  const wrappedSend = async (command, params, timeoutMs) => {
+    const scope = scopes.getStore();
+    const slot = { closed: false };
+    try {
+      const result = await runInCommandSlot(slot, () => sendCommand(command, params, timeoutMs));
+      slot.closed = true;
+      if (scope) recordSuccess(scope, command, slot, result);
+      return result;
+    } catch (error) {
+      slot.closed = true;
+      const coded = toRelaiError(error);
+      if (scope) {
+        scope.receipts.push({ id: slot.settled?.id ?? "", command, outcome: coded.outcome, code: coded.code });
+        if (coded.partial) scope.partial = true;
+        if (slot.settled?.cancelRequested) scope.cancelRequested = true;
+        scope.lastError = coded;
       }
+      throw coded;
+    }
+  };
+  return { server: wrappedServer, sendCommand: wrappedSend };
+}
+function envelopeHandler(name, handler, readOnly) {
+  const wrapped = async (...args) => {
+    const scope = { receipts: [], partial: false, cancelRequested: false };
+    const { room, expect_file: expectFile, ...own } = args[0] ?? {};
+    if (typeof room === "string") scope.room = room;
+    if (typeof expectFile === "string") scope.expectFile = expectFile;
+    const toolArgs = args[0] === void 0 ? args : [own, ...args.slice(1)];
+    let result;
+    try {
+      result = await scopes.run(scope, () => Promise.resolve(handler(...toolArgs)));
+    } catch (error) {
+      result = errorResult(error);
+    }
+    return finalizeResult(name, result, scope, readOnly);
+  };
+  wrapped[WRAPPED] = true;
+  return wrapped;
+}
+function toRelaiError(error) {
+  if (error instanceof RelaiError) return error;
+  const message = error instanceof Error ? error.message : String(error);
+  const { code, outcome, retry } = inferLegacyCode(message);
+  return new RelaiError(code, message, { outcome, retry });
+}
+function recordSuccess(scope, command, slot, result) {
+  const meta = slot.settled?.meta;
+  const receipt = { id: slot.settled?.id ?? "", command, outcome: meta?.outcome ?? "applied" };
+  if (typeof meta?.write === "boolean") receipt.write = meta.write;
+  if (meta?.partial) scope.partial = true;
+  if (meta?.file) scope.file = meta.file;
+  if (slot.settled?.cancelRequested) scope.cancelRequested = true;
+  if (command === "batch_execute" && Array.isArray(result)) {
+    receipt.items = result.map(batchItem);
+    if (!meta) {
+      const judged = aggregateOutcome(receipt.items.map((item) => item.outcome));
+      receipt.outcome = judged.outcome;
+      if (judged.partial) scope.partial = true;
     }
-    if (main) break;
   }
-  if (!main) {
-    const denied = statuses.length > 0 && statuses.every((s) => s === 401 || s === 403);
-    throw new FileIdentityError(
-      denied ? "Figma rejected the token on every probe (401/403) \u2014 it is expired or lacks the file content read scope. Re-run `npx -y figma-relai@latest login`." : "None of this file's published component keys resolved."
-    );
+  scope.receipts.push(receipt);
+}
+function batchItem(raw) {
+  const item = raw ?? {};
+  const command = typeof item.command === "string" ? item.command : "";
+  const code = isErrorCode(item.code) ? item.code : void 0;
+  const stated = item.outcome === "applied" || item.outcome === "not_applied" || item.outcome === "unknown" ? item.outcome : void 0;
+  if (item.success === true) return { command, outcome: stated ?? "applied" };
+  if (code) return { command, outcome: stated ?? ERROR_DEFAULTS[code].outcome, code };
+  const legacy = inferLegacyCode(typeof item.error === "string" ? item.error : "");
+  return { command, outcome: stated ?? legacy.outcome, code: legacy.code };
+}
+function finalizeResult(name, result, scope, readOnly) {
+  const declared = result._meta?.[CALL_META_KEY] ?? void 0;
+  const content = [...result.content ?? []];
+  const bodyIndex = content.findIndex((item) => item.type === "text" && typeof item.text === "string");
+  const body = bodyIndex >= 0 ? content[bodyIndex].text : void 0;
+  const receipts = scope.receipts;
+  const last = receipts[receipts.length - 1];
+  let isError = result.isError === true;
+  if (!isError && last?.code && body?.startsWith("Error: ")) isError = true;
+  let error = declared?.error;
+  if (isError && last?.code && scope.lastError) {
+    error = { code: scope.lastError.code, retry: scope.lastError.retry };
+  } else if (isError && !error) {
+    error = { code: "tool_error", retry: ERROR_DEFAULTS.tool_error.retry };
   }
-  const file = await figmaApi(token, `/files/${main.fileKey}?branch_data=true&depth=1`);
-  const identity = {
-    fileKey: main.fileKey,
-    fileName: typeof file.json.name === "string" ? file.json.name : rootName,
-    by: VERSION
-  };
-  if (rootName && rootName !== identity.fileName) {
-    const branches = file.json.branches ?? [];
-    const hit = branches.find((b) => b.name === rootName);
-    if (hit?.key) {
-      identity.branchKey = hit.key;
-      identity.branchName = hit.name;
+  const isRead = (r) => r.write === false || r.write === void 0 && readOnly;
+  const calls = receipts.map(
+    (r) => isRead(r) && r.outcome !== "applied" ? { ...r, outcome: "not_applied" } : r
+  );
+  let outcome;
+  let partial = scope.partial;
+  if (calls.length > 0) {
+    const writes = calls.filter((r) => !isRead(r));
+    if (writes.length > 0) {
+      const judged = aggregateOutcome(writes.map((r) => r.outcome));
+      outcome = judged.outcome;
+      partial = partial || judged.partial === true;
+    } else {
+      outcome = !isError && calls.some((r) => r.outcome === "applied") ? "applied" : "not_applied";
     }
   }
-  try {
-    await sendCommand("set_file_identity", { identity, componentKey: main.via });
-  } catch {
+  if (declared?.outcome) {
+    outcome = outcome === "unknown" ? "unknown" : declared.outcome;
+    partial = partial || declared.partial === true;
   }
-  return identity;
+  if (error && outcome === "unknown") error = { ...error, retry: "read_canvas_first" };
+  let truncated = declared?.truncated;
+  if (body !== void 0 && body.length > MAX_TEXT_CHARS) {
+    const whole = !truncated;
+    const file = truncated?.file ?? (whole ? writeResultFile(last?.id, body) : void 0);
+    const cut = {
+      total: whole ? body.length : truncated.total,
+      returned: MAX_TEXT_CHARS,
+      unit: "chars",
+      ...file ? { file } : {}
+    };
+    truncated = cut;
+    content[bodyIndex] = {
+      ...content[bodyIndex],
+      text: `${body.slice(0, MAX_TEXT_CHARS)}
+\u2026 [truncated: returned ${cut.returned} of ${cut.total} chars; ` + (file ? `the full result is in ${file}]` : "the full result could not be saved]")
+    };
+  }
+  const meta = {
+    v: 1,
+    ...outcome ? { outcome } : {},
+    ...outcome && partial ? { partial: true } : {},
+    ...error ? { error } : {},
+    calls,
+    ...scope.file || scope.room ? { target: { ...scope.room ? { room: scope.room } : {}, ...scope.file ? { file: scope.file } : {} } } : {},
+    ...truncated ? { truncated } : {}
+  };
+  const wrote = calls.some((r) => !isRead(r));
+  const showReceipt = isError || outcome === "unknown" || partial || scope.room !== void 0 || scope.expectFile !== void 0 || wrote && outcome !== void 0;
+  if (showReceipt) {
+    content.push({ type: "text", text: receiptLine(meta, last?.id, scope.cancelRequested) });
+  }
+  const { _meta: existingMeta, ...rest } = result;
+  return {
+    ...rest,
+    content,
+    ...isError ? { isError: true } : {},
+    _meta: { ...existingMeta ?? {}, [CALL_META_KEY]: meta }
+  };
+}
+var OUTCOME_WORDS = {
+  applied: "applied \u2014 the command ran",
+  not_applied: "not_applied \u2014 nothing was changed",
+  unknown: "unknown \u2014 it may have changed the file; read the canvas before retrying"
+};
+function receiptLine(meta, callId, cancelRequested) {
+  const parts = [
+    meta.outcome ? `${RECEIPT_LABEL} ${OUTCOME_WORDS[meta.outcome]}${meta.partial ? " (partly: some of it was written)" : ""}` : `${RECEIPT_LABEL} failed`
+  ];
+  if (meta.error) parts.push(meta.error.code);
+  if (cancelRequested) parts.push("the designer pressed Stop");
+  if (callId) parts.push(`call ${callId.slice(0, 8)}`);
+  if (meta.target?.file) parts.push(`file "${meta.target.file}"`);
+  if (meta.target?.room) parts.push(`room ${meta.target.room}`);
+  return parts.join(" \xB7 ");
 }
-
-// src/tools/index.ts
-import { z as z23 } from "zod";
 
 // src/tools/core/create.ts
 var create_exports = {};
 __export(create_exports, {
   register: () => register
 });
-import { z as z2 } from "zod";
-
-// src/tools/core/helpers.ts
-function textResult(text) {
-  return { content: [{ type: "text", text }] };
-}
-function jsonResult(value) {
-  return textResult(typeof value === "string" ? value : JSON.stringify(value, null, 2));
-}
-function errorResult(error) {
-  return textResult(`Error: ${error instanceof Error ? error.message : String(error)}`);
-}
-
-// src/tools/core/create.ts
+import { z as z3 } from "zod";
 var NODE_KINDS = [
   "rectangle",
   "frame",
@@ -1018,33 +1369,33 @@ function register(server, sendCommand) {
     "create_node",
     "Create a node in Figma: rectangle, frame, text, ellipse, polygon, star, line, section, slice, svg (from markup), image (from URL), or FigJam connector/table/sticky/code_block. Returns the new node's id \u2014 style it further with set_properties. For component instances use manage_components.",
     {
-      type: z2.enum(NODE_KINDS).describe("What to create"),
-      x: z2.number().optional().describe("X position (default 0)"),
-      y: z2.number().optional().describe("Y position (default 0)"),
+      type: z3.enum(NODE_KINDS).describe("What to create"),
+      x: z3.number().optional().describe("X position (default 0)"),
+      y: z3.number().optional().describe("Y position (default 0)"),
       width: dimensionSchema.optional(),
       height: dimensionSchema.optional(),
-      name: z2.string().optional(),
-      parentId: z2.string().optional().describe("Parent node id (default: current page)"),
-      text: z2.string().optional().describe("Text content (text/sticky)"),
-      fontSize: z2.number().positive().optional().describe("text only"),
-      fontWeight: z2.number().optional().describe("text only (e.g. 400, 700)"),
+      name: z3.string().optional(),
+      parentId: z3.string().optional().describe("Parent node id (default: current page)"),
+      text: z3.string().optional().describe("Text content (text/sticky)"),
+      fontSize: z3.number().positive().optional().describe("text only"),
+      fontWeight: z3.number().optional().describe("text only (e.g. 400, 700)"),
       fontColor: colorSchema.optional().describe("text only"),
       fillColor: colorSchema.optional().describe("frame/rectangle/section fill"),
       strokeColor: colorSchema.optional().describe("frame/rectangle/section stroke"),
-      cornerRadius: z2.number().min(0).optional().describe("section corner radius \u2014 a new section defaults to radius 2 with a 10% black stroke, which matches no design system; pass what yours uses (for other node types, set radius with set_properties)"),
-      pointCount: z2.number().int().min(3).optional().describe("polygon/star points"),
-      innerRadius: z2.number().min(0).max(1).optional().describe("star inner radius ratio"),
-      length: z2.number().positive().optional().describe("line length"),
-      rotation: z2.number().optional().describe("line rotation in degrees"),
-      strokeWeight: z2.number().min(0).optional().describe("line stroke weight"),
-      svg: z2.string().optional().describe("SVG markup (type=svg)"),
-      url: z2.string().optional().describe("Image URL (type=image)"),
-      scaleMode: z2.enum(["FILL", "FIT", "CROP", "TILE"]).optional().describe("image only"),
-      rows: z2.number().int().positive().optional().describe("table only"),
-      cols: z2.number().int().positive().optional().describe("table only"),
-      startNodeId: z2.string().optional().describe("connector only"),
-      endNodeId: z2.string().optional().describe("connector only"),
-      lineType: z2.enum(["ELBOWED", "STRAIGHT"]).optional().describe("connector only")
+      cornerRadius: z3.number().min(0).optional().describe("section corner radius \u2014 a new section defaults to radius 2 with a 10% black stroke, which matches no design system; pass what yours uses (for other node types, set radius with set_properties)"),
+      pointCount: z3.number().int().min(3).optional().describe("polygon/star points"),
+      innerRadius: z3.number().min(0).max(1).optional().describe("star inner radius ratio"),
+      length: z3.number().positive().optional().describe("line length"),
+      rotation: z3.number().optional().describe("line rotation in degrees"),
+      strokeWeight: z3.number().min(0).optional().describe("line stroke weight"),
+      svg: z3.string().optional().describe("SVG markup (type=svg)"),
+      url: z3.string().optional().describe("Image URL (type=image)"),
+      scaleMode: z3.enum(["FILL", "FIT", "CROP", "TILE"]).optional().describe("image only"),
+      rows: z3.number().int().positive().optional().describe("table only"),
+      cols: z3.number().int().positive().optional().describe("table only"),
+      startNodeId: z3.string().optional().describe("connector only"),
+      endNodeId: z3.string().optional().describe("connector only"),
+      lineType: z3.enum(["ELBOWED", "STRAIGHT"]).optional().describe("connector only")
     },
     async ({ type, ...params }) => {
       try {
@@ -1067,69 +1418,69 @@ __export(properties_exports, {
   propertiesSchema: () => propertiesSchema,
   register: () => register2
 });
-import { z as z3 } from "zod";
-var effectSchema = z3.object({
-  type: z3.enum(["DROP_SHADOW", "INNER_SHADOW", "LAYER_BLUR", "BACKGROUND_BLUR"]),
+import { z as z4 } from "zod";
+var effectSchema = z4.object({
+  type: z4.enum(["DROP_SHADOW", "INNER_SHADOW", "LAYER_BLUR", "BACKGROUND_BLUR"]),
   color: colorSchema.optional().describe("Shadow color (shadows only)"),
-  offsetX: z3.number().optional(),
-  offsetY: z3.number().optional(),
-  radius: z3.number().min(0).optional().describe("Blur radius"),
-  spread: z3.number().optional()
+  offsetX: z4.number().optional(),
+  offsetY: z4.number().optional(),
+  radius: z4.number().min(0).optional().describe("Blur radius"),
+  spread: z4.number().optional()
 });
-var propertiesSchema = z3.object({
+var propertiesSchema = z4.object({
   // Geometry
-  x: z3.number().optional(),
-  y: z3.number().optional(),
+  x: z4.number().optional(),
+  y: z4.number().optional(),
   width: dimensionSchema.optional(),
   height: dimensionSchema.optional(),
-  rotation: z3.number().optional().describe("Degrees"),
+  rotation: z4.number().optional().describe("Degrees"),
   // Identity / visibility
-  name: z3.string().optional(),
-  visible: z3.boolean().optional(),
-  locked: z3.boolean().optional(),
-  opacity: z3.number().min(0).max(1).optional(),
+  name: z4.string().optional(),
+  visible: z4.boolean().optional(),
+  locked: z4.boolean().optional(),
+  opacity: z4.number().min(0).max(1).optional(),
   blendMode: blendModeSchema.optional(),
   // Paint
   fillColor: colorSchema.optional(),
-  fills: z3.array(z3.record(z3.unknown())).optional().describe("Raw Paint[] \u2014 replaces the whole fill list; [] clears all fills"),
-  strokes: z3.array(z3.record(z3.unknown())).optional().describe("Raw Paint[] \u2014 replaces the whole stroke list; [] clears all strokes"),
+  fills: z4.array(z4.record(z4.unknown())).optional().describe("Raw Paint[] \u2014 replaces the whole fill list; [] clears all fills"),
+  strokes: z4.array(z4.record(z4.unknown())).optional().describe("Raw Paint[] \u2014 replaces the whole stroke list; [] clears all strokes"),
   strokeColor: colorSchema.optional(),
-  strokeWeight: z3.number().min(0).optional(),
-  cornerRadius: z3.number().min(0).optional(),
-  corners: z3.array(z3.boolean()).length(4).optional().describe("With cornerRadius: apply per corner [TL, TR, BR, BL]"),
-  gradient: z3.object({ gradientType: gradientTypeSchema, stops: z3.array(gradientStopSchema).min(2) }).optional(),
+  strokeWeight: z4.number().min(0).optional(),
+  cornerRadius: z4.number().min(0).optional(),
+  corners: z4.array(z4.boolean()).length(4).optional().describe("With cornerRadius: apply per corner [TL, TR, BR, BL]"),
+  gradient: z4.object({ gradientType: gradientTypeSchema, stops: z4.array(gradientStopSchema).min(2) }).optional(),
   // Effects (replaces existing effects list entry of same type)
-  effects: z3.array(effectSchema).optional(),
-  removeEffects: z3.boolean().optional(),
+  effects: z4.array(effectSchema).optional(),
+  removeEffects: z4.boolean().optional(),
   // Text
-  text: z3.string().optional().describe("Text content (TEXT nodes)"),
+  text: z4.string().optional().describe("Text content (TEXT nodes)"),
   // Auto-layout (frame itself)
   layoutMode: layoutModeSchema.optional(),
   layoutWrap: layoutWrapSchema.optional().describe("WRAP requires layoutMode HORIZONTAL"),
-  paddingTop: z3.number().min(0).optional(),
-  paddingRight: z3.number().min(0).optional(),
-  paddingBottom: z3.number().min(0).optional(),
-  paddingLeft: z3.number().min(0).optional(),
+  paddingTop: z4.number().min(0).optional(),
+  paddingRight: z4.number().min(0).optional(),
+  paddingBottom: z4.number().min(0).optional(),
+  paddingLeft: z4.number().min(0).optional(),
   primaryAxisAlignItems: primaryAxisAlignSchema.optional(),
   counterAxisAlignItems: counterAxisAlignSchema.optional(),
-  itemSpacing: z3.number().optional(),
-  counterAxisSpacing: z3.number().optional(),
+  itemSpacing: z4.number().optional(),
+  counterAxisSpacing: z4.number().optional(),
   // Auto-layout (as a child; FILL requires the PARENT to have auto-layout)
   layoutSizingHorizontal: sizingModeSchema.optional(),
   layoutSizingVertical: sizingModeSchema.optional(),
   // Constraints & sizing limits
   constraintsHorizontal: constraintTypeSchema.optional(),
   constraintsVertical: constraintTypeSchema.optional(),
-  minWidth: z3.number().min(0).optional(),
-  maxWidth: z3.number().min(0).optional(),
-  minHeight: z3.number().min(0).optional(),
-  maxHeight: z3.number().min(0).optional(),
-  aspectRatioLocked: z3.boolean().optional(),
-  clipsContent: z3.boolean().optional(),
+  minWidth: z4.number().min(0).optional(),
+  maxWidth: z4.number().min(0).optional(),
+  minHeight: z4.number().min(0).optional(),
+  maxHeight: z4.number().min(0).optional(),
+  aspectRatioLocked: z4.boolean().optional(),
+  clipsContent: z4.boolean().optional(),
   // Design-system bindings
-  styleId: z3.string().optional().describe("Apply a paint/text/effect/grid style by id"),
-  styleType: z3.enum(["PAINT", "TEXT", "EFFECT", "GRID"]).optional(),
-  boundVariables: z3.record(z3.string()).optional().describe('Bind variables: {"fills": "VariableID:...", "width": "..."}')
+  styleId: z4.string().optional().describe("Apply a paint/text/effect/grid style by id"),
+  styleType: z4.enum(["PAINT", "TEXT", "EFFECT", "GRID"]).optional(),
+  boundVariables: z4.record(z4.string()).optional().describe('Bind variables: {"fills": "VariableID:...", "width": "..."}')
 }).strict();
 function defined(obj) {
   return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== void 0));
@@ -1226,9 +1577,9 @@ function register2(server, sendCommand) {
     "set_properties",
     "Set any visual/layout/text properties on one or more nodes in a single call: geometry (x/y/width/height/rotation), fills/strokes/gradients/cornerRadius/opacity/effects, text content, auto-layout (layoutMode, padding, alignment, spacing, layoutSizing \u2014 FILL requires the parent to have auto-layout), constraints, style application, and variable bindings. Groups map to focused operations with per-operation success/error reporting. dryRun:true previews the mapped command list without touching the canvas.",
     {
-      nodeIds: z3.array(z3.string()).min(1).describe("Node IDs to update"),
+      nodeIds: z4.array(z4.string()).min(1).describe("Node IDs to update"),
       properties: propertiesSchema.describe("Properties to apply to every listed node"),
-      dryRun: z3.boolean().optional().describe("Preview only \u2014 return the plan, execute nothing")
+      dryRun: z4.boolean().optional().describe("Preview only \u2014 return the plan, execute nothing")
     },
     { idempotentHint: true },
     async ({ nodeIds, properties, dryRun }) => {
@@ -1267,13 +1618,13 @@ var structure_exports = {};
 __export(structure_exports, {
   register: () => register3
 });
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 function register3(server, sendCommand) {
   server.tool(
     "edit_structure",
     "Structural operations on nodes: group/ungroup, reparent (move into another parent), reorder (z-order), clone, flatten to vector, boolean operations (union/subtract/intersect/exclude), delete. group/boolean/delete take nodeIds; the rest take nodeId.",
     {
-      operation: z4.enum([
+      operation: z5.enum([
         "group",
         "ungroup",
         "reparent",
@@ -1283,14 +1634,14 @@ function register3(server, sendCommand) {
         "boolean",
         "delete"
       ]),
-      nodeId: z4.string().optional().describe("Target node (ungroup/reparent/reorder/clone/flatten)"),
-      nodeIds: z4.array(z4.string()).optional().describe("Target nodes (group/boolean/delete)"),
-      parentId: z4.string().optional().describe("reparent: new parent"),
-      index: z4.number().int().min(0).optional().describe("reparent: insertion index"),
+      nodeId: z5.string().optional().describe("Target node (ungroup/reparent/reorder/clone/flatten)"),
+      nodeIds: z5.array(z5.string()).optional().describe("Target nodes (group/boolean/delete)"),
+      parentId: z5.string().optional().describe("reparent: new parent"),
+      index: z5.number().int().min(0).optional().describe("reparent: insertion index"),
       direction: reorderDirectionSchema.optional().describe("reorder direction"),
       booleanOperation: booleanOperationSchema.optional().describe("boolean: which operation"),
-      x: z4.number().optional().describe("clone: position of the copy"),
-      y: z4.number().optional()
+      x: z5.number().optional().describe("clone: position of the copy"),
+      y: z5.number().optional()
     },
     async ({ operation, nodeId, nodeIds, parentId, index, direction, booleanOperation, x, y }) => {
       try {
@@ -1354,22 +1705,22 @@ var text_exports = {};
 __export(text_exports, {
   register: () => register4
 });
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 function register4(server, sendCommand) {
   server.tool(
     "set_text",
     "Edit text nodes. Modes: single (nodeId + text), bulk (items \u2014 efficient for many nodes, e.g. translations), or character-range styling (nodeId + range with fontSize/fontWeight/letterSpacing/lineHeight). Fonts load automatically with fallbacks. To find text nodes first, use search_nodes or get_selection_context.",
     {
-      nodeId: z5.string().optional().describe("Target text node (single / range mode)"),
-      text: z5.string().optional().describe("New content (single mode)"),
-      items: z5.array(z5.object({ nodeId: z5.string(), text: z5.string() })).optional().describe("Bulk replacements"),
-      range: z5.object({
-        start: z5.number().int().min(0),
-        end: z5.number().int().positive(),
-        fontSize: z5.number().positive().optional(),
-        fontWeight: z5.number().optional(),
-        letterSpacing: z5.number().optional(),
-        lineHeight: z5.number().optional()
+      nodeId: z6.string().optional().describe("Target text node (single / range mode)"),
+      text: z6.string().optional().describe("New content (single mode)"),
+      items: z6.array(z6.object({ nodeId: z6.string(), text: z6.string() })).optional().describe("Bulk replacements"),
+      range: z6.object({
+        start: z6.number().int().min(0),
+        end: z6.number().int().positive(),
+        fontSize: z6.number().positive().optional(),
+        fontWeight: z6.number().optional(),
+        letterSpacing: z6.number().optional(),
+        lineHeight: z6.number().optional()
       }).refine((r) => r.end > r.start, { message: "end must be greater than start" }).optional().describe("Style a character range [start, end)")
     },
     async ({ nodeId, text, items, range }) => {
@@ -1405,13 +1756,13 @@ var components_exports = {};
 __export(components_exports, {
   register: () => register5
 });
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 function register5(server, sendCommand) {
   server.tool(
     "manage_components",
     "Component workflow: list local components, create a component from a node, create_set (combine components as variants), instantiate (place an instance by componentKey OR by the node id of a local component \u2014 an unpublished component has no importable key, so the id is the way), add_property / bind_property (declare a TEXT/BOOLEAN/INSTANCE_SWAP property on a SET \u2014 never on a single variant \u2014 then point a layer's characters/visible at it, in every variant at once with layerName), get_props / set_props (component properties on an instance; get_props on a variant answers with its set's definitions), get_overrides / set_overrides (copy overrides from a source instance to targets), reset_instance (clear ALL overrides so the instance re-inherits its main component \u2014 returns property snapshots before/after so you can re-apply what mattered), detach.",
     {
-      action: z6.enum([
+      action: z7.enum([
         "list",
         "create",
         "create_set",
@@ -1425,21 +1776,21 @@ function register5(server, sendCommand) {
         "add_property",
         "bind_property"
       ]),
-      nodeId: z6.string().optional().describe("Target node (create/get_props/set_props/reset_instance/detach)"),
-      componentIds: z6.array(z6.string()).optional().describe("create_set: components to combine"),
-      componentKey: z6.string().optional().describe("instantiate: component key (or node id)"),
-      x: z6.number().optional().describe("instantiate: position"),
-      y: z6.number().optional(),
-      properties: z6.record(z6.union([z6.string(), z6.boolean()])).optional().describe("set_props: property name \u2192 value (variant/text/boolean/swap)"),
-      sourceInstanceId: z6.string().optional().describe("set_overrides: copy from this instance"),
-      targetNodeIds: z6.array(z6.string()).optional().describe("set_overrides: apply to these"),
-      instanceNodeId: z6.string().optional().describe("get_overrides: instance to inspect"),
-      propertyName: z6.string().optional().describe("add_property: the name designers will see (e.g. hasLabel, text)"),
-      propertyType: z6.enum(["TEXT", "BOOLEAN", "INSTANCE_SWAP"]).optional().describe("add_property: VARIANT axes come from variant names, so they are not addable here"),
-      defaultValue: z6.union([z6.string(), z6.boolean()]).optional().describe("add_property: the value a fresh instance starts with"),
-      propertyKey: z6.string().optional().describe("bind_property: the key add_property returned (name#id)"),
-      field: z6.enum(["characters", "visible", "mainComponent"]).optional().describe("bind_property: which part of the layer the property drives \u2014 text, show/hide, or which component sits in a swap slot"),
-      layerName: z6.string().optional().describe("bind_property: bind this layer in EVERY variant of the set at once")
+      nodeId: z7.string().optional().describe("Target node (create/get_props/set_props/reset_instance/detach)"),
+      componentIds: z7.array(z7.string()).optional().describe("create_set: components to combine"),
+      componentKey: z7.string().optional().describe("instantiate: component key (or node id)"),
+      x: z7.number().optional().describe("instantiate: position"),
+      y: z7.number().optional(),
+      properties: z7.record(z7.union([z7.string(), z7.boolean()])).optional().describe("set_props: property name \u2192 value (variant/text/boolean/swap)"),
+      sourceInstanceId: z7.string().optional().describe("set_overrides: copy from this instance"),
+      targetNodeIds: z7.array(z7.string()).optional().describe("set_overrides: apply to these"),
+      instanceNodeId: z7.string().optional().describe("get_overrides: instance to inspect"),
+      propertyName: z7.string().optional().describe("add_property: the name designers will see (e.g. hasLabel, text)"),
+      propertyType: z7.enum(["TEXT", "BOOLEAN", "INSTANCE_SWAP"]).optional().describe("add_property: VARIANT axes come from variant names, so they are not addable here"),
+      defaultValue: z7.union([z7.string(), z7.boolean()]).optional().describe("add_property: the value a fresh instance starts with"),
+      propertyKey: z7.string().optional().describe("bind_property: the key add_property returned (name#id)"),
+      field: z7.enum(["characters", "visible", "mainComponent"]).optional().describe("bind_property: which part of the layer the property drives \u2014 text, show/hide, or which component sits in a swap slot"),
+      layerName: z7.string().optional().describe("bind_property: bind this layer in EVERY variant of the set at once")
     },
     async (args) => {
       try {
@@ -1519,7 +1870,7 @@ __export(variables_exports, {
   scopeWarning: () => scopeWarning,
   suggestScopes: () => suggestScopes
 });
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 var SCOPE_BY_NAME = [
   [/radius|corner/i, ["CORNER_RADIUS"]],
   [/border-width|stroke-width|stroke\b/i, ["STROKE_FLOAT"]],
@@ -1542,9 +1893,9 @@ var SCOPE_MENU = {
 function suggestScopes(name, resolvedType) {
   const menu = SCOPE_MENU[resolvedType];
   if (!menu) return null;
-  for (const [pattern, scopes] of SCOPE_BY_NAME) {
+  for (const [pattern, scopes2] of SCOPE_BY_NAME) {
     if (!pattern.test(name)) continue;
-    const usable = scopes.filter((s) => menu.indexOf(s) >= 0);
+    const usable = scopes2.filter((s) => menu.indexOf(s) >= 0);
     if (usable.length) return usable;
   }
   return null;
@@ -1586,26 +1937,26 @@ function register6(server, sendCommand) {
     "manage_variables",
     "Design-token variables: list_collections / list (variables in a collection) / snapshot (compact whole-file inventory \u2014 every collection and variable name/type in one call; take one before branch merges or bulk edits, diff after) / create_collection / update_collection / delete_collection / create (pass valuesByMode to set every mode \u2014 and alias by variable NAME \u2014 in the same call) / update / delete / add_mode / remove_mode / rename_mode / set_scopes / set_code_syntax / remove_code_syntax / create_alias / bind (variable\u2192node property) / unbind / set_node_mode / get_node_modes / tokenize (find hardcoded colors & numbers that match existing variables and bind them \u2014 fix:false to preview, fix:true to apply; scope with nodeId, default current page). Pass only the fields the action needs.",
     {
-      action: z7.enum(Object.keys(ACTIONS)),
-      collectionId: z7.string().optional(),
-      variableId: z7.string().optional(),
-      targetVariableId: z7.string().optional().describe("create_alias: variable to alias to"),
-      nodeId: z7.string().optional().describe("bind/unbind/set_node_mode/get_node_modes"),
-      name: z7.string().optional(),
-      description: z7.string().optional(),
-      modes: z7.array(z7.string()).optional().describe("create_collection: mode names"),
-      modeId: z7.string().optional(),
-      resolvedType: z7.enum(["COLOR", "FLOAT", "STRING", "BOOLEAN"]).optional(),
-      value: z7.unknown().optional().describe("Variable value (color object, number, string, bool)"),
-      valuesByMode: z7.record(z7.unknown()).optional().describe(
+      action: z8.enum(Object.keys(ACTIONS)),
+      collectionId: z8.string().optional(),
+      variableId: z8.string().optional(),
+      targetVariableId: z8.string().optional().describe("create_alias: variable to alias to"),
+      nodeId: z8.string().optional().describe("bind/unbind/set_node_mode/get_node_modes"),
+      name: z8.string().optional(),
+      description: z8.string().optional(),
+      modes: z8.array(z8.string()).optional().describe("create_collection: mode names"),
+      modeId: z8.string().optional(),
+      resolvedType: z8.enum(["COLOR", "FLOAT", "STRING", "BOOLEAN"]).optional(),
+      value: z8.unknown().optional().describe("Variable value (color object, number, string, bool)"),
+      valuesByMode: z8.record(z8.unknown()).optional().describe(
         'create: every mode in one call, keyed by mode NAME or id \u2014 {"Light": {"r":1,"g":1,"b":1}, "Dark": {"aliasOf": "Color/gray/900"}}. `aliasOf` takes a variable id or its exact name, so a brand-mode token lands in one round-trip instead of create + one alias per mode.'
       ),
-      property: z7.string().optional().describe('bind/unbind: node property (e.g. "fills", "width")'),
-      scopes: z7.array(z7.string()).optional(),
-      platform: z7.enum(["WEB", "ANDROID", "iOS"]).optional(),
-      hiddenFromPublishing: z7.boolean().optional(),
-      fix: z7.boolean().optional().describe("tokenize: apply the bindings (false = report only)"),
-      tolerance: z7.number().optional().describe("tokenize: OKLab \u0394E for color matches (default 0.02 \u2248 visually identical)")
+      property: z8.string().optional().describe('bind/unbind: node property (e.g. "fills", "width")'),
+      scopes: z8.array(z8.string()).optional(),
+      platform: z8.enum(["WEB", "ANDROID", "iOS"]).optional(),
+      hiddenFromPublishing: z8.boolean().optional(),
+      fix: z8.boolean().optional().describe("tokenize: apply the bindings (false = report only)"),
+      tolerance: z8.number().optional().describe("tokenize: OKLab \u0394E for color matches (default 0.02 \u2248 visually identical)")
     },
     async (args) => {
       try {
@@ -1636,13 +1987,13 @@ var styles_exports = {};
 __export(styles_exports, {
   register: () => register7
 });
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 function register7(server, sendCommand) {
   server.tool(
     "manage_styles",
     "Shared styles: list all local styles; create_paint / create_text / create_effect / create_grid; update (name/properties); delete; apply (style to a node); reorder. To bind variables instead of styles, use manage_variables.",
     {
-      action: z8.enum([
+      action: z9.enum([
         "list",
         "create_paint",
         "create_text",
@@ -1653,26 +2004,26 @@ function register7(server, sendCommand) {
         "apply",
         "reorder"
       ]),
-      name: z8.string().optional().describe("Style name (create_*/update)"),
-      styleId: z8.string().optional().describe("Target style (update/delete/apply/reorder)"),
-      styleType: z8.enum(["PAINT", "TEXT", "EFFECT", "GRID"]).optional().describe("apply/reorder"),
-      nodeId: z8.string().optional().describe("apply: target node"),
+      name: z9.string().optional().describe("Style name (create_*/update)"),
+      styleId: z9.string().optional().describe("Target style (update/delete/apply/reorder)"),
+      styleType: z9.enum(["PAINT", "TEXT", "EFFECT", "GRID"]).optional().describe("apply/reorder"),
+      nodeId: z9.string().optional().describe("apply: target node"),
       color: colorSchema.optional().describe("create_paint/create_effect"),
       gradientType: gradientTypeSchema.optional(),
-      gradientStops: z8.array(gradientStopSchema).optional(),
-      fontFamily: z8.string().optional().describe("create_text"),
-      fontSize: z8.number().positive().optional(),
-      fontWeight: z8.number().optional(),
-      lineHeight: z8.number().optional(),
-      letterSpacing: z8.number().optional(),
-      effectType: z8.enum(["DROP_SHADOW", "INNER_SHADOW", "LAYER_BLUR", "BACKGROUND_BLUR"]).optional().describe("create_effect"),
-      offsetX: z8.number().optional(),
-      offsetY: z8.number().optional(),
-      radius: z8.number().min(0).optional(),
-      spread: z8.number().optional(),
-      grids: z8.array(z8.record(z8.unknown())).optional().describe("create_grid: layout grid objects"),
-      properties: z8.record(z8.unknown()).optional().describe("update: properties to change"),
-      afterStyleId: z8.string().optional().describe("reorder: place after this style")
+      gradientStops: z9.array(gradientStopSchema).optional(),
+      fontFamily: z9.string().optional().describe("create_text"),
+      fontSize: z9.number().positive().optional(),
+      fontWeight: z9.number().optional(),
+      lineHeight: z9.number().optional(),
+      letterSpacing: z9.number().optional(),
+      effectType: z9.enum(["DROP_SHADOW", "INNER_SHADOW", "LAYER_BLUR", "BACKGROUND_BLUR"]).optional().describe("create_effect"),
+      offsetX: z9.number().optional(),
+      offsetY: z9.number().optional(),
+      radius: z9.number().min(0).optional(),
+      spread: z9.number().optional(),
+      grids: z9.array(z9.record(z9.unknown())).optional().describe("create_grid: layout grid objects"),
+      properties: z9.record(z9.unknown()).optional().describe("update: properties to change"),
+      afterStyleId: z9.string().optional().describe("reorder: place after this style")
     },
     async (args) => {
       try {
@@ -1751,18 +2102,18 @@ var pages_exports = {};
 __export(pages_exports, {
   register: () => register8
 });
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 function register8(server, sendCommand) {
   server.tool(
     "manage_pages",
     "Page operations: list all pages, create/rename/delete a page, or set a page's background color. To make a page current, use navigate with switch_page. Guards: list_guards shows the designer's AI no-go zones; guard/unguard change them \u2014 ONLY do that when the designer explicitly asks (guards are theirs; every change shows in their activity feed). Writes into a guarded page are rejected at dispatch.",
     {
-      action: z9.enum(["list", "create", "rename", "delete", "set_background", "list_guards", "guard", "unguard"]),
-      pageId: z9.string().optional().describe("Target page (rename/delete/set_background/guard/unguard)"),
-      name: z9.string().optional().describe("Page name (create/rename)"),
+      action: z10.enum(["list", "create", "rename", "delete", "set_background", "list_guards", "guard", "unguard"]),
+      pageId: z10.string().optional().describe("Target page (rename/delete/set_background/guard/unguard)"),
+      name: z10.string().optional().describe("Page name (create/rename)"),
       color: colorSchema.optional().describe("Background color (set_background)"),
-      afterPageId: z9.string().optional().describe("create: put the new page right after this one \u2014 pages are ordered by meaning, and a new one lands at the bottom otherwise"),
-      index: z9.number().int().min(0).optional().describe("create: exact position instead of afterPageId")
+      afterPageId: z10.string().optional().describe("create: put the new page right after this one \u2014 pages are ordered by meaning, and a new one lands at the bottom otherwise"),
+      index: z10.number().int().min(0).optional().describe("create: exact position instead of afterPageId")
     },
     async ({ action, pageId, name, color, afterPageId, index }) => {
       try {
@@ -1809,19 +2160,19 @@ var navigate_exports = {};
 __export(navigate_exports, {
   register: () => register9
 });
-import { z as z10 } from "zod";
+import { z as z11 } from "zod";
 function register9(server, sendCommand) {
   server.tool(
     "navigate",
     "Control the designer's view: focus (scroll+zoom to a node), select (set the selection), get_viewport / set_viewport (x/y/zoom), or switch_page.",
     {
-      action: z10.enum(["focus", "select", "get_viewport", "set_viewport", "switch_page"]),
-      nodeId: z10.string().optional().describe("focus target"),
-      nodeIds: z10.array(z10.string()).optional().describe("select targets"),
-      x: z10.number().optional().describe("set_viewport center x"),
-      y: z10.number().optional(),
-      zoom: z10.number().positive().optional(),
-      pageId: z10.string().optional().describe("switch_page target")
+      action: z11.enum(["focus", "select", "get_viewport", "set_viewport", "switch_page"]),
+      nodeId: z11.string().optional().describe("focus target"),
+      nodeIds: z11.array(z11.string()).optional().describe("select targets"),
+      x: z11.number().optional().describe("set_viewport center x"),
+      y: z11.number().optional(),
+      zoom: z11.number().positive().optional(),
+      pageId: z11.string().optional().describe("switch_page target")
     },
     async ({ action, nodeId, nodeIds, x, y, zoom, pageId }) => {
       try {
@@ -1856,15 +2207,15 @@ var assets_exports = {};
 __export(assets_exports, {
   register: () => register10
 });
-import { z as z11 } from "zod";
+import { z as z12 } from "zod";
 function register10(server, sendCommand) {
   server.tool(
     "export_asset",
     "Export a node as PNG/JPG/SVG/PDF. Returns base64 data for saving to disk. For a quick visual check of your work, prefer the screenshot tool (returns a viewable image).",
     {
-      nodeId: z11.string().describe("Node to export"),
+      nodeId: z12.string().describe("Node to export"),
       format: exportFormatSchema.optional().describe("Default PNG"),
-      scale: z11.number().positive().optional().describe("Export scale (default 1)")
+      scale: z12.number().positive().optional().describe("Export scale (default 1)")
     },
     { readOnlyHint: true },
     async ({ nodeId, format, scale }) => {
@@ -1880,15 +2231,15 @@ function register10(server, sendCommand) {
     "add_image",
     "Place an image: from a URL (creates a new image node) or as a fill on an existing node (base64 imageData). scaleMode controls how the image fits.",
     {
-      url: z11.string().optional().describe("Image URL \u2014 creates a new node"),
-      nodeId: z11.string().optional().describe("Existing node \u2014 sets its fill from imageData"),
-      imageData: z11.string().optional().describe("Base64 image data (with nodeId)"),
-      x: z11.number().optional(),
-      y: z11.number().optional(),
-      width: z11.number().positive().optional(),
-      height: z11.number().positive().optional(),
-      name: z11.string().optional(),
-      scaleMode: z11.enum(["FILL", "FIT", "CROP", "TILE"]).optional()
+      url: z12.string().optional().describe("Image URL \u2014 creates a new node"),
+      nodeId: z12.string().optional().describe("Existing node \u2014 sets its fill from imageData"),
+      imageData: z12.string().optional().describe("Base64 image data (with nodeId)"),
+      x: z12.number().optional(),
+      y: z12.number().optional(),
+      width: z12.number().positive().optional(),
+      height: z12.number().positive().optional(),
+      name: z12.string().optional(),
+      scaleMode: z12.enum(["FILL", "FIT", "CROP", "TILE"]).optional()
     },
     async ({ url, nodeId, imageData, x, y, width, height, name, scaleMode }) => {
       try {
@@ -1917,14 +2268,14 @@ var library_exports = {};
 __export(library_exports, {
   register: () => register11
 });
-import { z as z12 } from "zod";
+import { z as z13 } from "zod";
 function register11(server, sendCommand) {
   server.tool(
     "import_from_library",
     "Import a component, style, or variable from an enabled team library by its key. Keys come from get_design_system's libraryCatalog, which resolves each library this file draws from and lists everything it publishes \u2014 not just what the file already uses. If the library you want is not in that catalog, it is listed under librariesNotCatalogued with what to do about it. Imported components can then be instantiated with manage_components.",
     {
-      kind: z12.enum(["component", "style", "variable"]),
-      key: z12.string().describe("Library key")
+      kind: z13.enum(["component", "style", "variable"]),
+      key: z13.string().describe("Library key")
     },
     async ({ kind, key }) => {
       try {
@@ -1943,21 +2294,21 @@ var annotate_exports = {};
 __export(annotate_exports, {
   register: () => register12
 });
-import { z as z13 } from "zod";
+import { z as z14 } from "zod";
 function register12(server, sendCommand) {
   server.tool(
     "annotate",
-    "Read or write Dev Mode annotations. get: read annotations on a node. set: add/update one annotation (labelMarkdown). set_multiple: batch annotations.",
+    "Read or write Dev Mode annotations. get: read annotations on a node. set: add one annotation (labelMarkdown); existing annotations are kept, and a node type that takes none is an error. set_multiple: batch annotations.",
     {
-      action: z13.enum(["get", "set", "set_multiple"]),
-      nodeId: z13.string().optional().describe("Target node (get/set)"),
-      labelMarkdown: z13.string().optional().describe("Annotation text (set)"),
-      categoryId: z13.string().optional(),
-      annotations: z13.array(
-        z13.object({
-          nodeId: z13.string(),
-          labelMarkdown: z13.string(),
-          categoryId: z13.string().optional()
+      action: z14.enum(["get", "set", "set_multiple"]),
+      nodeId: z14.string().optional().describe("Target node (get/set)"),
+      labelMarkdown: z14.string().optional().describe("Annotation text (set)"),
+      categoryId: z14.string().optional(),
+      annotations: z14.array(
+        z14.object({
+          nodeId: z14.string(),
+          labelMarkdown: z14.string(),
+          categoryId: z14.string().optional()
         })
       ).optional().describe("Batch annotations (set_multiple)")
     },
@@ -1988,16 +2339,16 @@ var read_exports = {};
 __export(read_exports, {
   register: () => register13
 });
-import { z as z14 } from "zod";
+import { z as z15 } from "zod";
 function register13(server, sendCommand) {
   server.tool(
     "get_node_data",
     "Raw node data at a chosen detail level: summary (shallow), tree (sparse structure for orientation), full (deeper serialization), css (CSS representation), variables (bound variable ids). For human-oriented summaries prefer get_node_details / get_selection_context.",
     {
-      nodeIds: z14.array(z14.string()).min(1).describe("One or more node ids"),
-      detail: z14.enum(["summary", "tree", "full", "css", "variables"]).optional().describe("Default summary"),
-      depth: z14.number().int().min(0).optional().describe("Override serialization depth"),
-      maxNodes: z14.number().int().positive().optional().describe("Override node budget")
+      nodeIds: z15.array(z15.string()).min(1).describe("One or more node ids"),
+      detail: z15.enum(["summary", "tree", "full", "css", "variables"]).optional().describe("Default summary"),
+      depth: z15.number().int().min(0).optional().describe("Override serialization depth"),
+      maxNodes: z15.number().int().positive().optional().describe("Override node budget")
     },
     { readOnlyHint: true },
     async ({ nodeIds, detail = "summary", depth, maxNodes }) => {
@@ -2037,22 +2388,42 @@ function register13(server, sendCommand) {
 // src/tools/core/execute.ts
 var execute_exports = {};
 __export(execute_exports, {
+  pluginTruncation: () => pluginTruncation,
   register: () => register14
 });
-import { z as z15 } from "zod";
+import { z as z16 } from "zod";
+var LEGACY_PLUGIN_LIMIT = 5e4;
+function pluginTruncation(result) {
+  const r = result;
+  if (!r || typeof r !== "object") return void 0;
+  const t = r.truncated;
+  if (t && typeof t === "object" && typeof t.total === "number" && typeof t.returned === "number") {
+    return { total: t.total, returned: t.returned, unit: "chars" };
+  }
+  if (t === true && typeof r.result === "string") {
+    const cut = /… \[truncated (\d+) chars/.exec(r.result);
+    if (cut) {
+      return { total: Number(cut[1]) + LEGACY_PLUGIN_LIMIT, returned: LEGACY_PLUGIN_LIMIT, unit: "chars" };
+    }
+  }
+  return void 0;
+}
 function register14(server, sendCommand) {
   server.tool(
     "execute_figma",
     "Run JavaScript against the Figma Plugin API inside the plugin sandbox \u2014 the escape hatch for anything the other tools don't cover. The code runs in an async function with `figma` AND `relai` in scope. relai helpers avoid the classic pitfalls: relai.text(parent, chars, {font,size,color}) loads fonts first; relai.autoLayout(direction, props) makes a hugging auto-layout frame; relai.set(node, props) applies layoutMode first and routes width/height through resize; relai.hug(node); relai.focusRing(node); await relai.page(p => ...) finds pages by content, not name; relai.query('FRAME[name^=Card] > TEXT') is a CSS-like search (types, name matchers, descendant/child, comma); relai.placeholder(node) shows a construction veil \u2014 remove with (node, false) when done. Errors carry a Hint with the fix; scripts are NOT atomic \u2014 on error, partial changes persist, so keep scripts small and idempotent. Nodes created via relai plus any node ids you RETURN are linted for silent mistakes (e.g. spread shadows without clipsContent) and come back as `warnings`. Return ALL created/mutated node ids. Work incrementally; verify with screenshot. When BUILDING UI: call get_design_system first and instantiate the file's own components / bind its variables instead of drawing raw shapes \u2014 hand-drawn near-copies of existing components read as drift to the design team. The designer can disable this tool via the plugin's 'Allow code execution' toggle.",
     {
-      code: z15.string().describe("JavaScript source. May use await. Return a JSON-serializable value."),
-      description: z15.string().optional().describe("One line shown in the plugin's activity feed describing what this does"),
-      timeoutMs: z15.number().int().min(1e3).max(3e5).optional().describe("Execution timeout in ms (default 60000) \u2014 raise for scripts creating hundreds of nodes")
+      code: z16.string().describe("JavaScript source. May use await. Return a JSON-serializable value."),
+      description: z16.string().optional().describe("One line shown in the plugin's activity feed describing what this does"),
+      timeoutMs: z16.number().int().min(1e3).max(3e5).optional().describe("Execution timeout in ms (default 60000) \u2014 raise for scripts creating hundreds of nodes")
     },
     async ({ code, description, timeoutMs }) => {
       try {
         const result = await sendCommand("execute_code", { code, description }, timeoutMs ?? 6e4);
-        return jsonResult(result);
+        const truncated = pluginTruncation(result);
+        if (!truncated) return jsonResult(result);
+        const meta = { v: 1, calls: [], truncated };
+        return { ...jsonResult(result), _meta: { [CALL_META_KEY]: meta } };
       } catch (error) {
         return errorResult(error);
       }
@@ -2066,7 +2437,86 @@ __export(comments_exports, {
   parseFileKey: () => parseFileKey,
   register: () => register15
 });
-import { z as z16 } from "zod";
+import { z as z17 } from "zod";
+
+// src/tools/core/file-identity.ts
+function addressableKey(identity) {
+  return identity.branchKey ?? identity.fileKey;
+}
+function describeIdentity(identity) {
+  return identity.branchName ? `${identity.fileName} (branch "${identity.branchName}")` : identity.fileName;
+}
+async function figmaApi(token, path) {
+  const res = await fetch(`https://api.figma.com/v1${path}`, {
+    headers: { "X-Figma-Token": token }
+  });
+  noteAuthFailure(res.status);
+  const json = await res.json().catch(() => ({}));
+  return { ok: res.ok, status: res.status, json };
+}
+var FileIdentityError = class extends Error {
+};
+async function resolveFileIdentity(sendCommand) {
+  const probe = await sendCommand("get_file_identity", {});
+  const cached = probe?.identity?.fileKey ? probe.identity : null;
+  if (cached && cached.by === VERSION) return cached;
+  const rootName = probe?.rootName ?? "";
+  const candidates = probe?.candidates ?? [];
+  if (candidates.length === 0) {
+    if (cached) return cached;
+    throw new FileIdentityError(
+      "This file publishes no components, so its key cannot be resolved from the plugin (figma.fileKey is private-plugin-only)."
+    );
+  }
+  const token = loadToken();
+  if (!token) {
+    throw new FileIdentityError(
+      "Resolving the file key needs a Figma token \u2014 store one with `npx -y figma-relai@latest login`."
+    );
+  }
+  let main = null;
+  const statuses = [];
+  for (const c of candidates) {
+    const paths = c.kind === "set" ? ["/component_sets/", "/components/"] : ["/components/", "/component_sets/"];
+    for (const p of paths) {
+      const res = await figmaApi(token, `${p}${c.key}`);
+      statuses.push(res.status);
+      const meta = res.json.meta ?? {};
+      if (res.ok && typeof meta.file_key === "string") {
+        main = { fileKey: meta.file_key, via: c.key };
+        break;
+      }
+    }
+    if (main) break;
+  }
+  if (!main) {
+    const denied = statuses.length > 0 && statuses.every((s) => s === 401 || s === 403);
+    throw new FileIdentityError(
+      denied ? "Figma rejected the token on every probe (401/403) \u2014 it is expired or lacks the file content read scope. Re-run `npx -y figma-relai@latest login`." : "None of this file's published component keys resolved."
+    );
+  }
+  const file = await figmaApi(token, `/files/${main.fileKey}?branch_data=true&depth=1`);
+  const identity = {
+    fileKey: main.fileKey,
+    fileName: typeof file.json.name === "string" ? file.json.name : rootName,
+    by: VERSION
+  };
+  if (rootName && rootName !== identity.fileName) {
+    const branches = file.json.branches ?? [];
+    const hit = branches.find((b) => b.name === rootName);
+    if (hit?.key) {
+      identity.branchKey = hit.key;
+      identity.branchName = hit.name;
+    }
+  }
+  try {
+    await sendCommand("set_file_identity", { identity, componentKey: main.via });
+  } catch {
+  }
+  return identity;
+}
+
+// src/tools/core/comments.ts
 var API = "https://api.figma.com/v1";
 function parseFileKey(input) {
   const url = input.match(/figma\.com\/(?:file|design)\/([A-Za-z0-9]+)/);
@@ -2120,15 +2570,15 @@ function register15(server, sendCommand) {
     "manage_comments",
     "Read and write comments on the Figma file: list (with node anchors \u2014 great for 'apply the feedback in the comments' or polling for designer requests; filter with unresolved:true and since:<ISO date>), add (optionally pinned to a node), reply, delete. Comment-driven workflow: designers leave asks as comments in Figma; poll list (unresolved + since last check), do the work, then reply on the thread with what was done. Requires a FIGMA_TOKEN env var (personal access token with comment scopes, generated at figma.com Settings \u2192 Security); the canvas tools work without it. The file is resolved from the plugin automatically (via a published component key, and the branch you are on \u2014 comments live per branch); pass fileUrl if this file publishes nothing.",
     {
-      action: z16.enum(["list", "add", "reply", "delete"]),
-      fileUrl: z16.string().optional().describe("Figma file URL or key (auto-detected when omitted)"),
-      message: z16.string().optional().describe("Comment text (add/reply)"),
-      commentId: z16.string().optional().describe("Target comment (reply/delete)"),
-      nodeId: z16.string().optional().describe("add: pin the comment to this node"),
-      x: z16.number().optional().describe("add: canvas position (with y, when not pinning to a node)"),
-      y: z16.number().optional(),
-      since: z16.string().optional().describe("list: only comments created after this ISO 8601 timestamp"),
-      unresolved: z16.boolean().optional().describe("list: only unresolved threads")
+      action: z17.enum(["list", "add", "reply", "delete"]),
+      fileUrl: z17.string().optional().describe("Figma file URL or key (auto-detected when omitted)"),
+      message: z17.string().optional().describe("Comment text (add/reply)"),
+      commentId: z17.string().optional().describe("Target comment (reply/delete)"),
+      nodeId: z17.string().optional().describe("add: pin the comment to this node"),
+      x: z17.number().optional().describe("add: canvas position (with y, when not pinning to a node)"),
+      y: z17.number().optional(),
+      since: z17.string().optional().describe("list: only comments created after this ISO 8601 timestamp"),
+      unresolved: z17.boolean().optional().describe("list: only unresolved threads")
     },
     async ({ action, fileUrl, message, commentId, nodeId, x, y, since, unresolved }) => {
       const token = loadToken();
@@ -2235,14 +2685,14 @@ __export(design_system_exports, {
   probeFailureNote: () => probeFailureNote,
   register: () => register16
 });
-import { z as z17 } from "zod";
+import { z as z18 } from "zod";
 function register16(server, sendCommand) {
   server.tool(
     "get_design_system",
     "Inventory the design system available to this file \u2014 call this BEFORE building UI, then prefer instantiating existing components (manage_components action:instantiate takes local and library keys) and binding existing variables over drawing raw shapes. Reports: local components/styles/variable collections with usage counts, remote components/styles the file already uses, enabled libraries' variable collections, and \u2014 with a token stored (`npx figma-relai login`) \u2014 the FULL published catalog of every library this file consumes, resolved automatically. What the file already uses is never the whole library: a component the file has not placed yet is invisible until this catalog is read. A library the file has drawn from NOTHING at all cannot be resolved either \u2014 those are named under librariesNotCatalogued, with the one step that fixes it. Results are cached per session \u2014 pass refresh:true after big library changes.",
     {
-      refresh: z17.boolean().optional().describe("Rescan instead of using the session cache"),
-      libraryFileUrl: z17.string().optional().describe(
+      refresh: z18.boolean().optional().describe("Rescan instead of using the session cache"),
+      libraryFileUrl: z18.string().optional().describe(
         "Optional. Catalog THIS library file instead of the auto-resolved ones (figma.com URL or key)"
       )
     },
@@ -2281,7 +2731,7 @@ function register16(server, sendCommand) {
     "manage_conventions",
     "The file's law: conventions (statutes) + precedents (case law), stored INSIDE this Figma file so they travel with it to every future session from any AI client. action:get returns both \u2014 read them BEFORE working and follow them like user instructions. Conventions are a markdown doc (action:set overwrites). Precedents are single adjudications the designer made \u2014 record one (action:record_precedent, one sentence, with refs to the tokens/nodes/pages it concerns) whenever the designer rules on something durable ('this deviation is intent, not drift', 'never restructure this table'), and SAY in your reply that you recorded it. Write results automatically surface precedents whose refs they touch.",
     {
-      action: z17.enum([
+      action: z18.enum([
         "get",
         "set",
         "record_precedent",
@@ -2289,16 +2739,18 @@ function register16(server, sendCommand) {
         "update_precedent",
         "remove_precedent"
       ]),
-      content: z17.string().optional().describe("set: the full markdown doc (overwrites; max 20k chars)"),
-      kind: z17.enum(["decision", "intent", "correction"]).optional().describe("record/update_precedent: decision (an approval/rejection), intent (a deviation that is deliberate), correction (a do-it-differently ruling). Default intent"),
-      text: z17.string().optional().describe("record/update_precedent: the adjudication, one sentence, \u2264280 chars"),
-      id: z17.string().optional().describe("update/remove_precedent: precedent id (from list_precedents)"),
-      refs: z17.object({
-        tokens: z17.array(z17.string()).optional().describe("Variable IDs this precedent concerns"),
-        nodes: z17.array(z17.string()).optional().describe("Node IDs this precedent concerns"),
-        pages: z17.array(z17.string()).optional().describe("Page IDs this precedent concerns")
+      content: z18.string().optional().describe("set: the full markdown doc (overwrites; max 20k chars)"),
+      kind: z18.enum(["decision", "intent", "correction"]).optional().describe("record/update_precedent: decision (an approval/rejection), intent (a deviation that is deliberate), correction (a do-it-differently ruling). Default intent"),
+      text: z18.string().optional().describe("record/update_precedent: the adjudication, one sentence, \u2264280 chars"),
+      id: z18.string().optional().describe("update/remove_precedent: precedent id (from list_precedents)"),
+      refs: z18.object({
+        tokens: z18.array(z18.string()).optional().describe(
+          'Variable IDs this precedent concerns, with the "VariableID:" prefix (a bare N:M gets it added; an id that names no variable is an error and nothing is saved)'
+        ),
+        nodes: z18.array(z18.string()).optional().describe("Node IDs this precedent concerns"),
+        pages: z18.array(z18.string()).optional().describe("Page IDs this precedent concerns")
       }).optional().describe("What the precedent is anchored to \u2014 enables in-band surfacing when writes touch these"),
-      limit: z17.number().optional().describe("list_precedents: max entries returned (default 50)")
+      limit: z18.number().optional().describe("list_precedents: max entries returned (default 50)")
     },
     async ({ action, content, kind, text, id, refs, limit }) => {
       try {
@@ -2480,7 +2932,7 @@ var rulesets_exports = {};
 __export(rulesets_exports, {
   register: () => register17
 });
-import { z as z18 } from "zod";
+import { z as z19 } from "zod";
 var ACTIONS2 = {
   list: ["list_rulesets", []],
   save: ["save_ruleset", ["name", "conventions", "fromFile", "autoRestore", "provenance"]],
@@ -2497,20 +2949,20 @@ var ACTIONS2 = {
 function register17(server, sendCommand) {
   server.tool(
     "manage_rulesets",
-    "Kits (rulesets) \u2014 named common-ancestor law the plugin keeps on the designer's machine, spanning every file it opens (one designer usually runs one product; its files share the same law). The panel shows this as the KIT row in the connection cluster \u2014 when speaking to the designer, call it a kit, not a ruleset. A file LINKS to one ruleset; the file's own carried conventions stay the working copy. Figma DISCARDS file-carried law on branch\u2192main merges \u2014 a linked ruleset is the recovery: status shows 'file-empty' after a merge, restore (or the set's autoRestore switch) re-seeds it. Actions: list / status (this file's state: in-sync, file-empty, drifted\u2026) / save (name + conventions, or fromFile:true to capture this file's law) / link (optionally restore:true) / unlink / restore (ruleset\u2192file, also seeds promoted precedents; REFUSED when the file's law is newer than the kit's \u2014 status.newer says which side is, and push is usually the fix \u2014 pass force:true to override) / push (file\u2192ruleset \u2014 the file's law becomes the ancestor) / promote (id \u2014 copy one precedent into the linked ruleset so every linked file inherits it) / delete / export (markdown package with provenance frontmatter) / import (markdown). Pass only the fields the action needs.",
+    "Kits (rulesets) \u2014 named common-ancestor law the plugin keeps on the designer's machine, spanning every file it opens (one designer usually runs one product; its files share the same law). The panel shows this as the KIT row in the connection cluster \u2014 when speaking to the designer, call it a kit, not a ruleset. A file LINKS to one ruleset; the file's own carried conventions stay the working copy. Figma DISCARDS file-carried law on branch\u2192main merges \u2014 a linked ruleset is the recovery: status shows 'file-empty' after a merge, restore (or the set's autoRestore switch) re-seeds it. Actions: list / status (this file's state: in-sync, file-empty, drifted\u2026) / save (name + conventions, or fromFile:true to capture this file's law) / link (optionally restore:true) / unlink / restore (ruleset\u2192file, also seeds promoted precedents \u2014 all or none: when the file memory can't hold them the law is still restored and precedentsSkipped says so; consolidate, then restore again \u2014 seeds merge by id, so only the missing ones are added; REFUSED when the file's law is newer than the kit's \u2014 status.newer says which side is, and push is usually the fix \u2014 pass force:true to override) / push (file\u2192ruleset \u2014 the file's law becomes the ancestor) / promote (id \u2014 copy one precedent into the linked ruleset so every linked file inherits it) / delete / export (markdown package with provenance frontmatter) / import (markdown). Pass only the fields the action needs.",
     {
-      action: z18.enum(Object.keys(ACTIONS2)),
-      name: z18.string().optional().describe("Ruleset name (save/link/delete/export; import fallback)"),
-      conventions: z18.string().optional().describe("save: full conventions markdown (or use fromFile)"),
-      fromFile: z18.boolean().optional().describe("save: capture this file's current conventions"),
-      autoRestore: z18.boolean().optional().describe("save: restore without asking when a linked file's law is found wiped"),
-      provenance: z18.string().optional().describe("save: where this law comes from (author/repo)"),
-      restore: z18.boolean().optional().describe("link: immediately restore the ruleset into the file"),
-      force: z18.boolean().optional().describe(
+      action: z19.enum(Object.keys(ACTIONS2)),
+      name: z19.string().optional().describe("Ruleset name (save/link/delete/export; import fallback)"),
+      conventions: z19.string().optional().describe("save: full conventions markdown (or use fromFile)"),
+      fromFile: z19.boolean().optional().describe("save: capture this file's current conventions"),
+      autoRestore: z19.boolean().optional().describe("save: restore without asking when a linked file's law is found wiped"),
+      provenance: z19.string().optional().describe("save: where this law comes from (author/repo)"),
+      restore: z19.boolean().optional().describe("link: immediately restore the ruleset into the file"),
+      force: z19.boolean().optional().describe(
         "restore/link: replace the file's law even when it is NEWER than the kit's; push: overwrite a kit that has moved since this file last synced it. Without this, an overwrite that would discard someone else's version is refused \u2014 say which side you mean to keep."
       ),
-      id: z18.string().optional().describe("promote: precedent id (list_precedents shows them)"),
-      markdown: z18.string().optional().describe("import: a ruleset package exported earlier")
+      id: z19.string().optional().describe("promote: precedent id (list_precedents shows them)"),
+      markdown: z19.string().optional().describe("import: a ruleset package exported earlier")
     },
     async (args) => {
       try {
@@ -2532,7 +2984,7 @@ var batch_exports = {};
 __export(batch_exports, {
   register: () => register18
 });
-import { z as z19 } from "zod";
+import { z as z20 } from "zod";
 function textResult2(text) {
   return { content: [{ type: "text", text }] };
 }
@@ -2541,13 +2993,13 @@ function register18(server, sendCommand) {
     "batch_execute",
     "Execute multiple commands in a single round-trip. Use when performing 3+ similar operations (e.g., styling multiple nodes, creating many elements). Commands run sequentially. Pass dryRun:true to preview the exact command list without touching the canvas \u2014 useful for showing the designer a plan before a large batch.",
     {
-      commands: z19.array(
-        z19.object({
-          command: z19.string().describe("Command name"),
-          params: z19.record(z19.string(), z19.unknown()).optional().describe("Command parameters")
+      commands: z20.array(
+        z20.object({
+          command: z20.string().describe("Command name"),
+          params: z20.record(z20.string(), z20.unknown()).optional().describe("Command parameters")
         })
       ).describe("Array of commands to execute sequentially"),
-      dryRun: z19.boolean().optional().describe("Preview only \u2014 return the plan, execute nothing")
+      dryRun: z20.boolean().optional().describe("Preview only \u2014 return the plan, execute nothing")
     },
     async ({ commands, dryRun }) => {
       try {
@@ -2581,7 +3033,7 @@ __export(context_exports, {
   register: () => register19,
   styleCountsFrom: () => styleCountsFrom
 });
-import { z as z20 } from "zod";
+import { z as z21 } from "zod";
 
 // src/semantic/response.ts
 function standardResult(opts) {
@@ -2606,8 +3058,18 @@ function errorResult2(category, message, recovery, extra) {
   };
   if (extra?.preconditions) error.preconditions = extra.preconditions;
   if (extra?.partial_result !== void 0) error.partial_result = extra.partial_result;
+  const { code, outcome, retry, partial } = CATEGORY_CODES[category];
+  const meta = {
+    v: 1,
+    ...outcome ? { outcome } : {},
+    ...partial ? { partial } : {},
+    error: { code, retry: retry ?? ERROR_DEFAULTS[code].retry },
+    calls: []
+  };
   return {
-    content: [{ type: "text", text: JSON.stringify({ error }, null, 2) }]
+    content: [{ type: "text", text: JSON.stringify({ error }, null, 2) }],
+    isError: true,
+    _meta: { [CALL_META_KEY]: meta }
   };
 }
 function noSelectionError() {
@@ -2824,7 +3286,7 @@ function register19(server, sendCommand) {
   );
   server.tool(
     "get_selection_context",
-    "Get full context for the current Figma selection: node properties, fills, layout, token bindings, and children summary. Use as the starting point for any inspection or modification workflow. Follow with analyze_* tools or update_node.",
+    "Get full context for the current Figma selection: node properties, fills, layout, token bindings, and children summary. Use as the starting point for any inspection or modification workflow. Follow with analyze_design or set_properties.",
     {},
     { readOnlyHint: true },
     async () => {
@@ -2869,8 +3331,8 @@ function register19(server, sendCommand) {
           data,
           warnings,
           recommended_next: [
-            { tool: "analyze_color_usage", reason: "Audit color consistency and token coverage" },
-            { tool: "update_node", reason: "Modify selected node properties" },
+            { tool: "analyze_design", reason: "Audit color consistency and token coverage", args: { aspect: "color" } },
+            { tool: "set_properties", reason: "Modify selected node properties" },
             { tool: "screenshot", reason: "Visually inspect the selection" }
           ]
         });
@@ -2885,9 +3347,9 @@ function register19(server, sendCommand) {
   );
   server.tool(
     "get_node_details",
-    "Get a single node's full properties, CSS, token bindings, and children. Use after search_nodes or get_selection_context to inspect a specific node. Follow with update_node or analyze_* tools.",
+    "Get a single node's full properties, CSS, token bindings, and children. Use after search_nodes or get_selection_context to inspect a specific node. Follow with set_properties or analyze_design.",
     {
-      nodeId: z20.string().describe("The node ID to inspect")
+      nodeId: z21.string().describe("The node ID to inspect")
     },
     { readOnlyHint: true },
     async ({ nodeId }) => {
@@ -2909,7 +3371,7 @@ function register19(server, sendCommand) {
           return errorResult2(
             "invalid_input",
             `Could not process node '${nodeId}'`,
-            { suggestion: "Try get_node_info directly for raw data", tool: "get_node_info" }
+            { suggestion: "Try get_node_data for raw data", tool: "get_node_data" }
           );
         }
         const bv = boundVars?.boundVariables || null;
@@ -2929,8 +3391,8 @@ function register19(server, sendCommand) {
           summary: `'${node.name}' (${node.type}, ${node.size.width}\xD7${node.size.height})${node.tokenCoverage != null ? `. Token coverage: ${Math.round(node.tokenCoverage * 100)}%` : ""}`,
           data,
           recommended_next: [
-            { tool: "update_node", reason: "Modify this node's properties", args: { nodeId } },
-            { tool: "analyze_color_usage", reason: "Check color token usage", args: { nodeId } }
+            { tool: "set_properties", reason: "Modify this node's properties", args: { nodeIds: [nodeId] } },
+            { tool: "analyze_design", reason: "Check color token usage", args: { aspect: "color", nodeId } }
           ]
         });
       } catch (error) {
@@ -2944,11 +3406,11 @@ function register19(server, sendCommand) {
   );
   server.tool(
     "search_nodes",
-    "Search for nodes by name and/or type within a scope. Returns matching node IDs, names, and types. Use to find specific elements before inspecting or modifying them. Follow with get_node_details or update_node.",
+    "Search for nodes by name and/or type within a scope. Returns matching node IDs, names, and types. Use to find specific elements before inspecting or modifying them. Follow with get_node_details or set_properties.",
     {
-      query: z20.string().optional().describe("Name substring to search for"),
-      types: z20.array(z20.string()).optional().describe("Node types to filter: FRAME, TEXT, COMPONENT, INSTANCE, RECTANGLE, etc."),
-      parentId: z20.string().optional().describe("Scope search to children of this node (default: current page)")
+      query: z21.string().optional().describe("Name substring to search for"),
+      types: z21.array(z21.string()).optional().describe("Node types to filter: FRAME, TEXT, COMPONENT, INSTANCE, RECTANGLE, etc."),
+      parentId: z21.string().optional().describe("Scope search to children of this node (default: current page)")
     },
     { readOnlyHint: true },
     async ({ query, types, parentId }) => {
@@ -2977,7 +3439,7 @@ function register19(server, sendCommand) {
           data,
           recommended_next: matches.length > 0 ? [
             { tool: "get_node_details", reason: "Inspect a specific node", args: { nodeId: matches[0].id } },
-            { tool: "navigate_to", reason: "Focus on a found node", args: { nodeId: matches[0].id } }
+            { tool: "navigate", reason: "Focus on a found node", args: { action: "focus", nodeId: matches[0].id } }
           ] : [
             { tool: "get_document_overview", reason: "Check document structure" }
           ]
@@ -2993,7 +3455,7 @@ function register19(server, sendCommand) {
   );
   server.tool(
     "get_design_tokens",
-    "Get an overview of the design token system: variable collections, modes, variable counts, and style counts. Use to understand the design system before binding tokens or creating new variables. Follow with manage_variables or bind_tokens.",
+    "Get an overview of the design token system: variable collections, modes, variable counts, and style counts. Use to understand the design system before binding tokens or creating new variables. Follow with manage_variables.",
     {},
     { readOnlyHint: true },
     async () => {
@@ -3019,7 +3481,7 @@ function register19(server, sendCommand) {
           data,
           recommended_next: [
             { tool: "manage_variables", reason: "Create or update design tokens" },
-            { tool: "analyze_color_usage", reason: "Check token coverage on selected nodes" }
+            { tool: "analyze_design", reason: "Check token coverage on selected nodes", args: { aspect: "color" } }
           ]
         });
       } catch (error) {
@@ -3035,7 +3497,7 @@ function register19(server, sendCommand) {
     "screenshot",
     "Take a PNG screenshot of a node or the current view. Returns an image visible to the AI. Use to visually verify changes or inspect design details. Works for both context inspection and verification after modifications.",
     {
-      nodeId: z20.string().optional().describe("Node ID to screenshot (default: current view)")
+      nodeId: z21.string().optional().describe("Node ID to screenshot (default: current view)")
     },
     { readOnlyHint: true },
     async ({ nodeId }) => {
@@ -3058,7 +3520,7 @@ function register19(server, sendCommand) {
                   measured: result.size ? { node: result.node, size: result.size, children: result.children, dominantColors: result.dominantColors } : void 0,
                   recommended_next: [
                     { tool: "get_selection_context", reason: "Get structured data about the selection" },
-                    { tool: "update_node", reason: "Make changes based on what you see" }
+                    { tool: "set_properties", reason: "Make changes based on what you see" }
                   ]
                 })
               }
@@ -3096,7 +3558,7 @@ __export(analysis_exports, {
   collectColorIssues: () => collectColorIssues,
   register: () => register20
 });
-import { z as z21 } from "zod";
+import { z as z22 } from "zod";
 
 // src/semantic/health.ts
 var WEIGHTS = { color: 0.3, layout: 0.25, components: 0.2, accessibility: 0.25 };
@@ -3168,10 +3630,10 @@ function register20(server, sendCommand) {
     "analyze_design",
     `Audit the design from one aspect: color (token coverage, unbound fills/strokes), layout (auto-layout quality, spacing consistency), components (detached instances, component health), accessibility (WCAG contrast incl. large-text thresholds, touch targets, minimum text sizes), tokens (hardcoded values that match an existing variable \u2014 each finding names the variable to bind; fix in one shot with manage_variables action:tokenize fix:true), overall (runs color/layout/components/accessibility and returns a weighted 0-100 health score \u2014 good for audits and reports), voice (the file's statistical fingerprint: radius/spacing/type signatures, tokenized-paint and instance rates \u2014 what "sounds like this file"), readiness (0-100 agent-readiness score with top gaps: conventions, precedents, semantic tokens, components), ghosts (stale references to soft-deleted variables \u2014 they still render but are invisible in pickers and dead on publish), or token_debt (component tokens nobody binds, and component tokens that alias ANOTHER component's token instead of the shared upstream \u2014 both look right on the canvas and bite later). Defaults to the current selection; tokens/voice/ghosts default to the current page.`,
     {
-      aspect: z21.enum(["color", "layout", "components", "accessibility", "tokens", "overall", "voice", "readiness", "ghosts", "token_debt"]),
-      nodeId: z21.string().optional().describe("Root node to analyze (default: current selection)"),
-      pageIds: z21.array(z21.string()).optional().describe("voice/ghosts: pages to scan (default: current page; ghosts auto-chunks any count)"),
-      platform: z21.enum(["desktop", "mobile"]).optional().describe("accessibility: target-size profile \u2014 desktop 24px (default), mobile 44px")
+      aspect: z22.enum(["color", "layout", "components", "accessibility", "tokens", "overall", "voice", "readiness", "ghosts", "token_debt"]),
+      nodeId: z22.string().optional().describe("Root node to analyze (default: current selection)"),
+      pageIds: z22.array(z22.string()).optional().describe("voice/ghosts: pages to scan (default: current page; ghosts auto-chunks any count)"),
+      platform: z22.enum(["desktop", "mobile"]).optional().describe("accessibility: target-size profile \u2014 desktop 24px (default), mobile 44px")
     },
     { readOnlyHint: true },
     async ({ aspect, nodeId, pageIds, platform }) => {
@@ -3252,7 +3714,9 @@ async function runTokenDebt(sendCommand, pageIds) {
   }
   const unused = (head.candidates ?? []).filter((c) => !used.has(c.id));
   const borrows = head.borrowedTokens ?? [];
-  const summary = `${borrows.length} borrowed token${borrows.length === 1 ? "" : "s"}, ${unused.length} unused across ${pagesScanned.length} page${pagesScanned.length === 1 ? "" : "s"}`;
+  const borrowCount = head.borrowCount ?? borrows.length;
+  const borrowsTruncated = borrowCount > borrows.length;
+  const summary = `${borrowCount} borrowed token${borrowCount === 1 ? "" : "s"}` + (borrowsTruncated ? ` (showing ${borrows.length})` : "") + `, ${unused.length} unused across ${pagesScanned.length} page${pagesScanned.length === 1 ? "" : "s"}`;
   return standardResult({
     summary: summary + (head.noAliasLayer ? " \u2014 this file has no alias layer, so nothing counts as a foundation: the unused list is plain variables, not component tokens" : "") + (pagesScanned.length <= 1 ? " \u2014 only one page was walked; pass pageIds for the whole file before treating anything as unused" : ""),
     data: {
@@ -3261,6 +3725,8 @@ async function runTokenDebt(sendCommand, pageIds) {
       instancesScanned,
       foundationGroups: head.foundationGroups,
       borrowedTokens: borrows,
+      borrowCount,
+      borrowsTruncated,
       unusedTokens: unused.slice(0, 40),
       unusedCount: unused.length,
       allScopesByGroup: head.allScopesByGroup,
@@ -3404,9 +3870,9 @@ async function runOverallAudit(aspectHandlers, nodeId) {
 function registerAnalysisTools(server, sendCommand) {
   server.tool(
     "analyze_color_usage",
-    "Audit color consistency and design token coverage for a node tree. Reports which fill/stroke colors are not bound to variables. Use after get_selection_context to diagnose token gaps. Follow with bind_tokens to fix issues.",
+    "Audit color consistency and design token coverage for a node tree. Reports which fill/stroke colors are not bound to variables. Use after get_selection_context to diagnose token gaps. Follow with manage_variables action:tokenize to fix issues.",
     {
-      nodeId: z21.string().optional().describe("Root node to analyze (default: current selection)")
+      nodeId: z22.string().optional().describe("Root node to analyze (default: current selection)")
     },
     { readOnlyHint: true },
     async ({ nodeId }) => {
@@ -3473,10 +3939,10 @@ function registerAnalysisTools(server, sendCommand) {
           data,
           warnings,
           recommended_next: unboundColors.length > 0 ? [
-            { tool: "bind_tokens", reason: "Bind unbound colors to design tokens" },
+            { tool: "manage_variables", reason: "Bind unbound colors that match an existing variable", args: { action: "tokenize" } },
             { tool: "get_design_tokens", reason: "See available tokens for binding" }
           ] : [
-            { tool: "analyze_layout_quality", reason: "Check layout quality next" }
+            { tool: "analyze_design", reason: "Check layout quality next", args: { aspect: "layout" } }
           ]
         });
       } catch (error) {
@@ -3490,9 +3956,9 @@ function registerAnalysisTools(server, sendCommand) {
   );
   server.tool(
     "analyze_layout_quality",
-    "Check layout quality: auto-layout usage, magic numbers in spacing/padding, and sizing consistency. Use after get_selection_context to find layout improvements. Follow with set_auto_layout to fix issues.",
+    "Check layout quality: auto-layout usage, magic numbers in spacing/padding, and sizing consistency. Use after get_selection_context to find layout improvements. Follow with set_properties (auto-layout) to fix issues.",
     {
-      nodeId: z21.string().optional().describe("Root node to analyze (default: current selection)")
+      nodeId: z22.string().optional().describe("Root node to analyze (default: current selection)")
     },
     { readOnlyHint: true },
     async ({ nodeId }) => {
@@ -3530,7 +3996,7 @@ function registerAnalysisTools(server, sendCommand) {
             message: i.issue,
             nodeId: i.nodeId
           })),
-          recommended_next: issues.length > 0 ? [{ tool: "set_auto_layout", reason: "Fix layout issues on specific frames" }] : [{ tool: "analyze_color_usage", reason: "Check color token coverage next" }]
+          recommended_next: issues.length > 0 ? [{ tool: "set_properties", reason: "Fix layout issues on specific frames (auto-layout, spacing, sizing)" }] : [{ tool: "analyze_design", reason: "Check color token coverage next", args: { aspect: "color" } }]
         });
       } catch (error) {
         return errorResult2(
@@ -3543,9 +4009,9 @@ function registerAnalysisTools(server, sendCommand) {
   );
   server.tool(
     "analyze_component_health",
-    "Check component system health: detached instances, unused components, and override consistency. Use to audit design system adherence. Follow with create_component or update_instance to fix issues.",
+    "Check component system health: detached instances, unused components, and override consistency. Use to audit design system adherence. Follow with manage_components to fix issues.",
     {
-      nodeId: z21.string().optional().describe("Scope to analyze (default: current page)")
+      nodeId: z22.string().optional().describe("Scope to analyze (default: current page)")
     },
     { readOnlyHint: true },
     async ({ nodeId }) => {
@@ -3596,10 +4062,10 @@ function registerAnalysisTools(server, sendCommand) {
   );
   server.tool(
     "analyze_accessibility",
-    "Check accessibility: text contrast ratios against backgrounds, interactive target sizes (WCAG 2.5.8: 24px desktop default, 44px with platform:mobile). Use to ensure designs meet WCAG guidelines. Follow with update_node to fix contrast or sizing issues.",
+    "Check accessibility: text contrast ratios against backgrounds, interactive target sizes (WCAG 2.5.8: 24px desktop default, 44px with platform:mobile). Use to ensure designs meet WCAG guidelines. Follow with set_properties to fix contrast or sizing issues.",
     {
-      nodeId: z21.string().optional().describe("Root node to analyze (default: current selection)"),
-      platform: z21.enum(["desktop", "mobile"]).optional().describe("Target-size profile: desktop 24px (default), mobile 44px")
+      nodeId: z22.string().optional().describe("Root node to analyze (default: current selection)"),
+      platform: z22.enum(["desktop", "mobile"]).optional().describe("Target-size profile: desktop 24px (default), mobile 44px")
     },
     { readOnlyHint: true },
     async ({ nodeId, platform }) => {
@@ -3630,7 +4096,7 @@ function registerAnalysisTools(server, sendCommand) {
             message: i.issue,
             nodeId: i.nodeId
           })),
-          recommended_next: issues.length > 0 ? [{ tool: "update_node", reason: "Fix accessibility issues" }] : [{ tool: "validate_design_rules", reason: "Run full design validation" }]
+          recommended_next: issues.length > 0 ? [{ tool: "set_properties", reason: "Fix accessibility issues" }] : [{ tool: "validate_design_rules", reason: "Run full design validation" }]
         });
       } catch (error) {
         return errorResult2(
@@ -3641,14 +4107,15 @@ function registerAnalysisTools(server, sendCommand) {
       }
     }
   );
-  const CHECKPOINT_KEY = "relai.checkpoint";
+  const CHECKPOINT_LIMIT = 200;
+  const checkpoints = /* @__PURE__ */ new Map();
   server.tool(
     "diff_nodes",
-    `Compare two nodes and list their differences (fills, strokes, size, layout, etc.), or audit changes over time with checkpoints: checkpoint:"save" snapshots nodeIdA's key properties; checkpoint:"compare" later diffs the current state against that snapshot \u2014 useful before/after an editing session to show the designer exactly what changed.`,
+    `Compare two nodes and list their differences (fills, strokes, size, layout, etc.), or audit changes over time with checkpoints: checkpoint:"save" snapshots nodeIdA's key properties; checkpoint:"compare" later diffs the current state against that snapshot \u2014 useful before/after an editing session to show the designer exactly what changed. Checkpoints are kept in the Relai server's memory, never written to the file, and a server restart clears them.`,
     {
-      nodeIdA: z21.string().describe("First node ID (or the checkpoint target)"),
-      nodeIdB: z21.string().optional().describe("Second node ID (omit when using checkpoint)"),
-      checkpoint: z21.enum(["save", "compare"]).optional().describe("save: snapshot nodeIdA now; compare: diff current vs saved snapshot")
+      nodeIdA: z22.string().describe("First node ID (or the checkpoint target)"),
+      nodeIdB: z22.string().optional().describe("Second node ID (omit when using checkpoint)"),
+      checkpoint: z22.enum(["save", "compare"]).optional().describe("save: snapshot nodeIdA now (held in server memory until the server restarts, not in the file); compare: diff current vs saved snapshot")
     },
     { readOnlyHint: true },
     async ({ nodeIdA, nodeIdB, checkpoint }) => {
@@ -3656,32 +4123,25 @@ function registerAnalysisTools(server, sendCommand) {
         if (checkpoint === "save") {
           const node = await sendCommand("get_node_info", { nodeId: nodeIdA, depth: 2 });
           if (!node) return errorResult2("invalid_input", `Node '${nodeIdA}' not found`, { suggestion: "Check node ID", tool: "search_nodes" });
-          const summary = normalizeNode(node);
-          await sendCommand("set_plugin_data", {
-            nodeId: nodeIdA,
-            key: CHECKPOINT_KEY,
-            value: JSON.stringify({ ts: Date.now(), name: node.name, summary })
-          });
+          checkpoints.delete(nodeIdA);
+          checkpoints.set(nodeIdA, { ts: Date.now(), name: node.name, summary: normalizeNode(node) });
+          if (checkpoints.size > CHECKPOINT_LIMIT) checkpoints.delete(checkpoints.keys().next().value);
           return standardResult({
-            summary: `Checkpoint saved for '${node.name}' (${nodeIdA}). Run diff_nodes with checkpoint:"compare" after editing to see what changed.`,
+            summary: `Checkpoint saved for '${node.name}' (${nodeIdA}) in server memory. Run diff_nodes with checkpoint:"compare" after editing to see what changed.`,
             data: { nodeId: nodeIdA, saved: true },
             recommended_next: []
           });
         }
         if (checkpoint === "compare") {
-          const [node, stored] = await Promise.all([
-            sendCommand("get_node_info", { nodeId: nodeIdA, depth: 2 }),
-            sendCommand("get_plugin_data", { nodeId: nodeIdA, key: CHECKPOINT_KEY })
-          ]);
-          if (!node) return errorResult2("invalid_input", `Node '${nodeIdA}' not found`, { suggestion: "Check node ID", tool: "search_nodes" });
-          const raw = typeof stored === "string" ? stored : stored?.value;
-          if (!raw) {
-            return errorResult2("invalid_input", `No checkpoint saved on '${nodeIdA}'`, {
-              suggestion: 'Save one first with checkpoint:"save"',
+          const saved = checkpoints.get(nodeIdA);
+          if (!saved) {
+            return errorResult2("invalid_input", `No checkpoint for '${nodeIdA}' in this server session`, {
+              suggestion: `Save one first with checkpoint:"save" \u2014 checkpoints are held in server memory (the latest ${CHECKPOINT_LIMIT}) and a server restart clears them`,
               tool: "diff_nodes"
             });
           }
-          const saved = JSON.parse(raw);
+          const node = await sendCommand("get_node_info", { nodeId: nodeIdA, depth: 2 });
+          if (!node) return errorResult2("invalid_input", `Node '${nodeIdA}' not found`, { suggestion: "Check node ID", tool: "search_nodes" });
           const before = saved.summary;
           const after = normalizeNode(node);
           const differences2 = [];
@@ -3697,7 +4157,7 @@ function registerAnalysisTools(server, sendCommand) {
             compareField(differences2, "layout.gap", before.layout?.gap, after.layout?.gap);
             compareField(differences2, "layout.padding", before.layout?.padding, after.layout?.padding);
           }
-          const age = Math.round((Date.now() - (saved.ts ?? Date.now())) / 1e3);
+          const age = Math.round((Date.now() - saved.ts) / 1e3);
           return standardResult({
             summary: differences2.length === 0 ? `'${node.name}' is unchanged since the checkpoint ${age}s ago` : `${differences2.length} propert${differences2.length === 1 ? "y" : "ies"} changed on '${node.name}' since the checkpoint ${age}s ago`,
             data: {
@@ -3745,7 +4205,7 @@ function registerAnalysisTools(server, sendCommand) {
         return standardResult({
           summary: differences.length === 0 ? `'${nodeA.name}' and '${nodeB.name}' are identical in key properties` : `${differences.length} difference(s) between '${nodeA.name}' and '${nodeB.name}'`,
           data,
-          recommended_next: differences.length > 0 ? [{ tool: "update_node", reason: "Align properties between nodes" }] : []
+          recommended_next: differences.length > 0 ? [{ tool: "set_properties", reason: "Align properties between nodes" }] : []
         });
       } catch (error) {
         return errorResult2(
@@ -3832,7 +4292,7 @@ function analyzeLayoutNode(node, issues, _counters) {
           nodeName: node.name,
           issue: `Frame '${node.name}' has ${node.children.length} children but no auto-layout`,
           severity: "warning",
-          suggestion: "Add auto-layout with set_auto_layout for responsive behavior"
+          suggestion: "Add auto-layout with set_properties for responsive behavior"
         });
       }
     }
@@ -3946,14 +4406,14 @@ var verification_exports = {};
 __export(verification_exports, {
   register: () => register21
 });
-import { z as z22 } from "zod";
+import { z as z23 } from "zod";
 function register21(server, sendCommand) {
   server.tool(
     "verify_changes",
-    "Verify that a node's current properties match expected values. Use after update_node, set_auto_layout, or batch_execute to confirm changes applied correctly. Returns match/mismatch for each checked field.",
+    "Verify that a node's current properties match expected values. Use after set_properties or batch_execute to confirm changes applied correctly. Returns match/mismatch for each checked field.",
     {
-      nodeId: z22.string().describe("Node ID to verify"),
-      expected: z22.record(z22.string(), z22.unknown()).describe("Expected property values, e.g. { fill: '#3B82F6', cornerRadius: 8 }")
+      nodeId: z23.string().describe("Node ID to verify"),
+      expected: z23.record(z23.string(), z23.unknown()).describe("Expected property values, e.g. { fill: '#3B82F6', cornerRadius: 8 }")
     },
     { readOnlyHint: true },
     async ({ nodeId, expected }) => {
@@ -3989,7 +4449,7 @@ function register21(server, sendCommand) {
         return standardResult({
           summary: allMatch ? `All ${fields.length} checked properties match expected values` : `${fields.filter((f) => !f.match).length} of ${fields.length} properties don't match expected values`,
           data,
-          recommended_next: allMatch ? [{ tool: "screenshot", reason: "Visually confirm the changes" }] : [{ tool: "update_node", reason: "Re-apply changes that didn't match", args: { nodeId } }]
+          recommended_next: allMatch ? [{ tool: "screenshot", reason: "Visually confirm the changes" }] : [{ tool: "set_properties", reason: "Re-apply changes that didn't match", args: { nodeIds: [nodeId] } }]
         });
       } catch (error) {
         return errorResult2(
@@ -4004,8 +4464,8 @@ function register21(server, sendCommand) {
     "validate_design_rules",
     "Run design quality rules on a node: token coverage, token scopes, cross-component token borrowing, dimension stability across states, fixed-size text that would clip, auto-layout usage, naming conventions, and accessibility basics. Use after modifications and before calling a component done \u2014 these rules catch the faults that look perfect on the canvas and surface weeks later in someone else's file. Returns pass/fail for each rule with fix suggestions.",
     {
-      nodeId: z22.string().optional().describe("Root node to validate (default: current selection)"),
-      platform: z22.enum(["desktop", "mobile"]).optional().describe("Target-size profile for the touch rule: desktop 24px (default), mobile 44px")
+      nodeId: z23.string().optional().describe("Root node to validate (default: current selection)"),
+      platform: z23.enum(["desktop", "mobile"]).optional().describe("Target-size profile for the touch rule: desktop 24px (default), mobile 44px")
     },
     { readOnlyHint: true },
     async ({ nodeId, platform }) => {
@@ -4044,7 +4504,7 @@ function register21(server, sendCommand) {
           severity: coverage >= 0.5 ? "warning" : "error",
           message: `Token coverage: ${Math.round(coverage * 100)}%${coverageDetail} (target: 80%+)`,
           nodeId: targetId,
-          fix: coverage < 0.8 ? { tool: "bind_tokens", reason: "Bind unbound properties to design tokens", args: { nodeId: targetId } } : void 0
+          fix: coverage < 0.8 ? { tool: "manage_variables", reason: "Bind hardcoded values that match an existing variable", args: { action: "tokenize", nodeId: targetId } } : void 0
         });
         if (nodeInfo.type === "FRAME" || nodeInfo.type === "COMPONENT") {
           const hasAutoLayout = nodeInfo.layoutMode && nodeInfo.layoutMode !== "NONE";
@@ -4055,7 +4515,7 @@ function register21(server, sendCommand) {
             severity: "warning",
             message: hasAutoLayout ? `Auto-layout: ${nodeInfo.layoutMode}` : hasChildren ? `No auto-layout on frame with ${nodeInfo.children.length} children` : "No children requiring auto-layout",
             nodeId: targetId,
-            fix: !hasAutoLayout && hasChildren ? { tool: "set_auto_layout", reason: "Add auto-layout for responsive behavior", args: { nodeId: targetId } } : void 0
+            fix: !hasAutoLayout && hasChildren ? { tool: "set_properties", reason: "Add auto-layout for responsive behavior", args: { nodeIds: [targetId] } } : void 0
           });
         }
         const hasDefaultName = /^(Frame|Rectangle|Ellipse|Group|Text|Vector|Line|Polygon|Star)\s*\d*$/.test(nodeInfo.name);
@@ -4065,7 +4525,7 @@ function register21(server, sendCommand) {
           severity: "info",
           message: hasDefaultName ? `'${nodeInfo.name}' uses a default Figma name \u2014 rename for clarity` : `Name '${nodeInfo.name}' looks intentional`,
           nodeId: targetId,
-          fix: hasDefaultName ? { tool: "update_node", reason: "Rename with a semantic name", args: { nodeId: targetId } } : void 0
+          fix: hasDefaultName ? { tool: "set_properties", reason: "Rename with a semantic name", args: { nodeIds: [targetId] } } : void 0
         });
         try {
           const drift = await sendCommand("audit_voice_drift", { nodeId: targetId }, 6e4);
@@ -4092,7 +4552,7 @@ function register21(server, sendCommand) {
             severity: "warning",
             message: adequate ? `Target size: ${Math.round(w)}\xD7${Math.round(h)}px (OK, minimum ${minTarget}px)` : `Target size: ${Math.round(w)}\xD7${Math.round(h)}px (minimum ${minTarget}\xD7${minTarget}px \u2014 WCAG 2.5.8${minTarget >= 44 ? ", mobile" : ""})`,
             nodeId: targetId,
-            fix: !adequate ? { tool: "update_node", reason: "Increase size to meet the target-size minimum", args: { nodeId: targetId } } : void 0
+            fix: !adequate ? { tool: "set_properties", reason: "Increase size to meet the target-size minimum", args: { nodeIds: [targetId] } } : void 0
           });
         }
         try {
@@ -4206,8 +4666,8 @@ function register21(server, sendCommand) {
     "verify_visual",
     "The write\u2192see\u2192assert loop in one call: screenshots a node AND (optionally) checks expected property values. Returns the image plus structured pass/fail. Use after visual edits instead of separate screenshot + verify_changes calls.",
     {
-      nodeId: z22.string().describe("Node to verify"),
-      expected: z22.record(z22.string(), z22.unknown()).optional().describe("Expected property values, e.g. { cornerRadius: 8, width: 320 }")
+      nodeId: z23.string().describe("Node to verify"),
+      expected: z23.record(z23.string(), z23.unknown()).optional().describe("Expected property values, e.g. { cornerRadius: 8, width: 320 }")
     },
     { readOnlyHint: true },
     async ({ nodeId, expected }) => {
@@ -4305,7 +4765,7 @@ function registerRoomTool(server, joinRoom, listRooms) {
     "join_room",
     "Connect to a specific Figma plugin instance. Usually unnecessary \u2014 pairing is automatic when one plugin is connected. Call with no arguments to LIST the connected plugins (room + file name) instead of typing the room by hand, then call again with the room you want.",
     {
-      room: z23.string().optional().describe("Room name shown in the Figma plugin. Omit to list connected rooms.")
+      room: z24.string().optional().describe("Room name shown in the Figma plugin. Omit to list connected rooms.")
     },
     async ({ room }) => {
       try {
@@ -4328,21 +4788,28 @@ ${lines.join("\n")}`
             }]
           };
         }
-        await joinRoom(room);
-        return {
-          content: [
-            { type: "text", text: `Successfully joined room: ${room}` }
-          ]
+        const report = await joinRoom(room);
+        const where = report.pluginPresent ? ` \u2014 "${report.file ?? "unnamed file"}"${report.branchOf ? `, a branch of "${report.branchOf}"` : ""}.` : " \u2014 no plugin is there yet; commands will fail until that file's plugin opens.";
+        const meta = {
+          v: 1,
+          calls: [],
+          target: {
+            room: report.room,
+            ...report.file ? { file: report.file } : {},
+            ...report.branchOf ? { branchOf: report.branchOf } : {}
+          }
         };
-      } catch (error) {
         return {
           content: [
             {
               type: "text",
-              text: `Error joining room: ${error instanceof Error ? error.message : String(error)}`
+              text: `Joined room ${room}${where} Every agent in this MCP server process (one client session) shares this room \u2014 a join_room from any of them moves them all.`
             }
-          ]
+          ],
+          _meta: { [CALL_META_KEY]: meta }
         };
+      } catch (error) {
+        return errorResult(error);
       }
     }
   );
@@ -4350,9 +4817,9 @@ ${lines.join("\n")}`
 function registerEventsTool(server, consumeEvents, getSessionLog) {
   server.tool(
     "get_events",
-    "Activity since the last check. scope 'designer' (default): the designer's selection/node/page changes (also piggybacked as designer_events on command results). scope 'agent': this session's own command log \u2014 every plugin command sent, with success/duration \u2014 useful for summarizing what was changed. 'all': both.",
+    "Activity since the last check. scope 'designer' (default): the designer's selection/node/page changes (also piggybacked as designer_events on command results). scope 'agent': this session's own command log \u2014 every plugin command sent, with success/duration, outcome (applied/not_applied/unknown) and error code \u2014 useful for summarizing what was changed. 'all': both.",
     {
-      scope: z23.enum(["designer", "agent", "all"]).optional()
+      scope: z24.enum(["designer", "agent", "all"]).optional()
     },
     { readOnlyHint: true },
     async ({ scope = "designer" }) => {
@@ -4376,8 +4843,9 @@ function registerEventsTool(server, consumeEvents, getSessionLog) {
   );
 }
 function registerAllTools(server, sendCommand) {
+  const env = withCallEnvelope(server, sendCommand);
   for (const [mod] of moduleCategories) {
-    mod.register(server, sendCommand);
+    mod.register(env.server, env.sendCommand);
   }
 }
 function listToolCatalog() {
@@ -4396,8 +4864,92 @@ function listToolCatalog() {
   return catalog;
 }
 
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+function createServer() {
+  return new McpServer(
+    {
+      name: "Relai",
+      version: VERSION
+    },
+    {
+      instructions: `
+You control Figma through ~30 consolidated tools. Pairing with the Figma plugin is automatic \u2014 just call any tool; join_room is only needed if an error reports multiple plugins. With several files open, pass room (or expect_file) on each call instead of relying on the session's default room.
+
+\u{1F4D6} UNDERSTAND (start here):
+  get_document_overview \u2014 structure, page/component/style/variable counts
+  get_selection_context \u2014 full context for what the designer selected
+  get_node_details \u2014 deep single-node inspection (CSS, token bindings)
+  search_nodes \u2014 find nodes by name/type \xB7 get_node_data \u2014 raw data/tree/css
+  get_design_tokens \u2014 variable collections, modes, styles
+  screenshot \u2014 see the canvas (use this to verify your work visually)
+
+\u{1F50D} DIAGNOSE:
+  analyze_design \u2014 aspect: color/layout/components/accessibility, or
+    "overall" for a weighted 0-100 health score across all four
+  diff_nodes \u2014 compare two nodes, or checkpoint save/compare to audit
+    what changed on a node over an editing session
+
+\u270F\uFE0F EDIT:
+  create_node \u2014 any node type (rectangle/frame/text/svg/image/\u2026)
+  set_properties \u2014 one call for geometry, fills, strokes, effects, text,
+    auto-layout, constraints, style/variable bindings, on one or many nodes
+  set_text \u2014 single, bulk, or character-range text edits
+  edit_structure \u2014 group/reparent/reorder/clone/flatten/boolean/delete
+  navigate \u2014 focus/select/viewport/switch_page \xB7 manage_pages
+
+\u{1F9F1} DESIGN SYSTEM:
+  manage_components \u2014 create/variants/instantiate/overrides/props/detach
+  manage_variables \u2014 collections, modes, tokens, bind/unbind
+  manage_styles \u2014 paint/text/effect/grid styles
+  import_from_library \u2014 bring in library components/styles/variables
+
+\u{1F4E6} ASSETS: export_asset (PNG/JPG/SVG/PDF) \xB7 add_image (URL or fill)
+\u{1F4DD} ANNOTATIONS: annotate (Dev Mode annotations)
+\u{1F4AC} COMMENTS: manage_comments \u2014 read/apply/reply to file comments
+  (needs FIGMA_TOKEN env; the tool explains setup when missing)
+
+\u2705 VERIFY: verify_changes \xB7 validate_design_rules
+
+\u26A1 ADVANCED:
+  batch_execute \u2014 run many plugin-level commands in one round-trip
+  execute_figma \u2014 run JavaScript against the Figma Plugin API directly
+    (the escape hatch when no tool fits; small incremental scripts,
+     screenshot between steps; the designer can disable it)
+
+OPERATING PRINCIPLES:
+- Inspect context BEFORE changing things; don't assume selection state
+- After visual edits, verify: screenshot or verify_changes
+- Colors are RGBA in 0-1 range (Figma format), not 0-255
+- layoutSizing FILL requires the node's PARENT to have auto-layout;
+  set layoutMode on a frame before padding/alignment/spacing
+- Responses include recommended_next tools \u2014 follow them
+- Errors name the node, its type, and the fix \u2014 read them, don't retry blindly
+
+READING RESULTS:
+- Writes and failures end with a "[relai]" line saying whether Figma changed:
+  applied (the command ran) \xB7 not_applied (nothing changed) \xB7
+  unknown (it may have changed \u2014 read the canvas before retrying;
+  never resend a write blindly)
+- Failures set isError and name an error code (e.g. timeout, guard_blocked);
+  the full receipt is in _meta["${CALL_META_KEY}"]
+- Text over 50,000 characters is cut; the cut notice names a local file
+  that holds the full result
+
+TARGETING A FILE (every tool except join_room and get_events):
+- room: send this one call to that plugin room; the session's default room
+  (set by join_room, shared by every agent in this server process) stays put
+- expect_file: refuse unless the target file's name is exactly this
+  (a branch has its own name); a refusal changes nothing (not_applied)
+- room_changed: the plugin moved to a different file since the last call;
+  nothing was sent, and sending again continues in the new file
+`
+    }
+  );
+}
+
 // ../../docs/skills/figma-plugin-api.md
-var figma_plugin_api_default = '# Figma Plugin API Cheat Sheet \u2014 for `execute_figma`\n\nRules and patterns for writing code that runs in the plugin sandbox. Work in small incremental scripts and `screenshot` between steps.\n\n## Non-negotiable rules (dynamic-page mode)\n\n- **Node lookup is async**: `await figma.getNodeByIdAsync(id)` \u2014 `getNodeById` throws in this plugin.\n- **Load pages before traversal**: `await page.loadAsync()` before `page.findAll(...)` on a non-current page; `figma.currentPage` is always loaded.\n- **Load fonts before ANY text edit**: `await figma.loadFontAsync(textNode.fontName)` \u2014 if `fontName === figma.mixed`, load every range: `for (const f of textNode.getRangeAllFontNames(0, textNode.characters.length)) await figma.loadFontAsync(f)`.\n- **`figma.mixed` is a Symbol**: properties like `fontSize`, `cornerRadius`, `fills` return it when values differ across ranges/children. Check `=== figma.mixed` before using; never JSON-serialize it.\n\n## Common patterns\n\n```js\n// Selection\nconst sel = figma.currentPage.selection;          // read\nfigma.currentPage.selection = [node];             // write\n\n// Create + place\nconst frame = figma.createFrame();\nframe.resize(320, 200);                            // width/height are read-only; use resize()\nparent.appendChild(frame);                         // default parent is currentPage\n\n// Fills/strokes are ARRAYS and must be reassigned wholesale\nnode.fills = [{ type: "SOLID", color: { r: 1, g: 0.5, b: 0 } }];  // rgb 0-1, no alpha key \u2014 use opacity\nconst fills = JSON.parse(JSON.stringify(node.fills));              // clone before mutating\nfills[0].color.r = 0; node.fills = fills;\n\n// Auto-layout: set layoutMode FIRST, then padding/spacing/align\nframe.layoutMode = "VERTICAL";\nframe.itemSpacing = 8; frame.paddingTop = 16;\nchild.layoutSizingHorizontal = "FILL";             // requires PARENT with auto-layout\n\n// Components\nconst comp = await figma.importComponentByKeyAsync(key);  // team library\nconst inst = comp.createInstance();\ninst.setProperties({ Variant: "Primary" });        // throws on unknown property names\n\n// Variables\nconst collections = await figma.variables.getLocalVariableCollectionsAsync();\nconst v = figma.variables.createVariable("name", collection, "COLOR");\nv.setValueForMode(modeId, { r: 0, g: 0, b: 0 });\nnode.setBoundVariable("fills", v);                 // binding paint needs figma.variables.setBoundVariableForPaint on the paint object for fills in older APIs \u2014 prefer setBoundVariable where available\n\n// Export (returns Uint8Array)\nconst bytes = await node.exportAsync({ format: "PNG", constraint: { type: "SCALE", value: 2 } });\n```\n\n## `relai.*` helpers \u2014 the shortest path is the correct one\n\nAlongside `figma`, scripts get a `relai` object whose helpers are immune to the pitfalls below. Prefer them:\n\n```js\nawait relai.text(parent, "Hello", { font: {family:"IBM Plex Mono", style:"Regular"}, size: 14, color: {r:0,g:0,b:0} });\n                                          // loads the font BEFORE writing characters\nconst card = relai.autoLayout("VERTICAL", { name: "Card", itemSpacing: 8 });\n                                          // auto-layout frame, both axes hugging\nrelai.set(node, { layoutMode: "HORIZONTAL", width: 320, opacity: 0.9 });\n                                          // layoutMode applied first; width/height via resize()\nrelai.hug(node);                          // HUG that sticks \u2014 call after appending children\nrelai.focusRing(button);                  // clipsContent + double spread shadows that render\nconst page = await relai.page(p => p.children.some(c => c.name === "Button"));\n                                          // find pages by CONTENT \u2014 names get renamed\nconst titles = relai.query(\'FRAME[name^=Card] > TEXT\');\n                                          // CSS-like search on the current page; relai.query(node, sel) scopes to a subtree.\n                                          // Supported: TYPE, *, [name=] [name*=] [name^=] [name$=], descendant, >, comma.\n                                          // NOT supported: pseudo-classes, dot-paths, sibling combinators \u2014 use findAll.\nrelai.placeholder(section);               // construction veil so the designer sees work-in-progress\nrelai.placeholder(section, false);        // ALWAYS remove when the section is done\n```\n\nTwo important facts: **scripts are NOT atomic** \u2014 on error, changes made before the throw persist, so keep scripts small and clean up after failures; and results may carry a `warnings` array for silent mistakes the lint catches on relai-created nodes and any node ids you return (e.g. spread shadows on a non-clipping frame). Convention: **return every created/mutated node id** (`return { createdNodeIds: [...] }`) \u2014 it powers both follow-up calls and the lint.\n\n## Pitfalls that throw (or silently do the wrong thing)\n\nWhen one of these throws inside `execute_figma`, the error already carries the remedy as a `Hint:` \u2014 this list is generated from the same registry (`packages/shared/src/pitfalls.ts`).\n\n<!-- PITFALLS:START -->\n- **`not a function` errors may name no symbol** \u2014 Figma\'s VM drops the subject. Usual cause: APIs from other agent tools that don\'t exist here (`node.query()`, `figma.notify()`). Use `findAll`/`findAllWithCriteria` for search; bisect when the message names nothing.\n- **Editing text without loading its font throws** (`unloaded font`). `await figma.loadFontAsync(textNode.fontName)` first; new TextNodes default to Inter Regular; when `fontName === figma.mixed`, load every font from `getRangeAllFontNames()`.\n- **`getNodeById` throws in dynamic-page mode** \u2014 always `await figma.getNodeByIdAsync(id)`.\n- **Traversing a non-current page throws until you `await page.loadAsync()`** \u2014 `figma.currentPage` is always loaded, other pages are not. Two things make this bite later than it should. `getNodeByIdAsync` resolves a node on an unloaded page perfectly well, so a handler handed a node id looks healthy right up to the moment it walks children. And the page is often already loaded by whatever ran first, so identical code passes in a session where another tool touched that page and throws in one where it did not \u2014 which reads as flakiness rather than a missing load. Load the page you need yourself; and if the caller swallows handler errors, this stops being a failure and becomes a check that silently disappears.\n- **`layoutSizingHorizontal/Vertical` throw without auto-layout** \u2014 FILL requires the parent to have a `layoutMode`, HUG requires it on the node itself.\n- **`createPage()` throws on the free plan once a file has 3 pages** \u2014 reuse an existing page instead.\n- **`width`/`height` are read-only** \u2014 use `node.resize(w, h)`.\n- **`figma.mixed` is a Symbol** returned by `fontSize`, `cornerRadius`, `fills` etc. when values differ across ranges/children \u2014 check `=== figma.mixed` before use; never JSON-serialize it.\n- **Exact-name lookups are fragile** \u2014 designers rename pages and layers freely; locate nodes by type/content instead of `name ===`.\n- **Stale node ids throw `does not exist`** \u2014 nodes get deleted while you work; re-read before editing and check `node.removed`.\n- **Nodes are non-extensible** \u2014 `node.myCustomProp = x` throws `object is not extensible`; use `setPluginData` or return the data instead.\n- **Shadow `spread` renders only on shapes or frames with `clipsContent: true`** \u2014 a focus ring built from spread shadows is invisible on a non-clipping frame/component.\n- **`resize()` on an auto-layout frame silently pins that axis to FIXED**, overriding `primaryAxisSizingMode: "AUTO"`. Append children first, then set `layoutSizingHorizontal = "HUG"`; use `resize` only for the fixed cross-axis.\n- **Per-corner radius** (`topLeftRadius` \u2026) only exists on RectangleCornerMixin nodes (rectangles, frames, components) \u2014 polygons, stars and lines throw.\n- **Instance children can\'t be added or removed** \u2014 detach first, or edit the main component.\n- **Figma\'s slot feature (Convert to slot, \u21E7\u2318S) has no Plugin API** \u2014 no createSlot/convertToSlot exists (verified against typings 1.123 and at runtime, 2026-07). Scaffold a frame named "Slot", select it for the designer (navigate select), and let them press the shortcut.\n- **A converted SLOT node stops hugging** \u2014 after the designer converts a frame to a slot it carries its own fixed size. Re-assert `layoutSizingVertical = "HUG"` (and the intended horizontal mode) on the SLOT node afterwards; the API can still edit its layout props.\n- **Variantizing can silently pin the hug axis to FIXED** \u2014 observed after clone \u2192 counterAxisSizingMode/width-variable changes \u2192 combineAsVariants: the variants\' `primaryAxisSizingMode` ended up FIXED though the source hugged. Always verify sizing modes on every variant after combineAsVariants and re-assert `"AUTO"`.\n- **A backgrounded Figma window suspends the plugin iframe** \u2014 timers freeze and the socket can\'t pong, so the relay\'s staleness sweep kicks the plugin and the frozen 2s redial never fires until the window regains attention. The panel redials on visibilitychange/focus (ui.html \u22650.2.4); when a paired plugin goes missing mid-session, ask the designer to click the Figma window before assuming anything is broken.\n- **A freshly-converted slot can still report `type: "FRAME"` to the Plugin API** \u2014 the layer panel shows the slot badge while getNodeByIdAsync returns FRAME (a reload boundary was observed to fix it). Never gate automation on `type === "SLOT"`; match the frame by name and trust the designer\'s visual confirmation.\n- **Deleted variables are soft-deleted ghosts** \u2014 `getVariableByIdAsync` still resolves them with name AND working values (`Variable` has no `removed` property), so bindings to them keep rendering while being invisible in pickers and dead on publish. To test aliveness, check membership in `getLocalVariablesAsync()` (remote variables are legitimately absent \u2014 check `variable.remote`).\n- **Variables cannot be reordered via the API** (`variableIds` is read-only; the `move\u2026After` methods exist only for styles) \u2014 new variables always append last; panel order is manual-drag only. NEVER delete-and-recreate variables to reorder: bindings reference variable IDs, so every binding in the file silently dies (observed in production; the ghosts keep rendering, hiding the damage).\n- **A remote (library) text style dominates variable bindings** \u2014 on text with a remote style applied, `setBoundVariable` writes appear to succeed but snap back to the style\'s own bindings. Clear the style first (`await setTextStyleIdAsync("")`), then bind.\n- **Binding writes inside instances silently revert \u2014 with two escape hatches.** `setBoundVariable` on a node nested inside an INSTANCE succeeds without error, then reverts (instance roots placed directly in a main ARE writable; anything deeper is not). What does persist: reassigning the whole `fills`/`strokes` array (variable-bound paints ride inside), and range-level `setRangeBoundVariable` on text. Verify after writing; never trust the call alone.\n- **A bound `strokeWeight` renders nothing while `strokes` is empty, and wrappers don\'t hug stroke thickness.** A LINE\'s visible weight lives entirely in its stroke paint; the frame around it keeps its own raw height/width, so the panel shows an unbound number with empty Fill/Stroke \u2014 looking broken when it isn\'t. Inspect the LINE child\'s stroke bindings, not the wrapper; and bind the wrapper\'s thickness-axis dimension to the same variable so nothing stays raw.\n- **`setBoundVariable("strokeWeight", \u2026)` is a silent no-op on FRAME-family nodes.** Frames and components bind stroke weight per side \u2014 `strokeTopWeight` / `strokeRightWeight` / `strokeBottomWeight` / `strokeLeftWeight`; the uniform `strokeWeight` field only binds on stroke-geometry nodes like LINE. No error is thrown, the binding just never appears \u2014 read back `boundVariables` after writing.\n- **Cloning a variant escapes its component set \u2014 onto whatever page the user is viewing.** `variant.clone()` parents the copy to `figma.currentPage` as a standalone COMPONENT (not into the set) \u2014 plain nodes inside components clone to the current page too. Every `componentPropertyReferences` pointing at set-level properties is silently severed, and native SLOT children are demoted to plain FRAMEs (slot-ness needs set context). Recover by `componentSet.appendChild(clone)`, re-assigning ALL references (`visible`, `slotContentId`, \u2026) \u2014 a SLOT can be restored by cloning a surviving SLOT node from a sibling variant (SLOT clones keep their type) and relinking `componentPropertyReferences.slotContentId`. Audit every set-scoped feature after adoption; none of it comes back on its own.\n- **Uneven variant renames/deletes poison the whole component set.** If variants end up with mismatched axis segments (some carry `axis=value`, others don\'t) or duplicate names, the set enters an error state where `componentPropertyDefinitions` AND every instance\'s `variantProperties`/`setProperties` throw (`Component set has existing errors`). Escape: rename stragglers so all variants share the same axes with unique values (temporary `legacy-*` values work), which heals the set \u2014 then migrate and delete.\n- **`setProperties` DOES work on instances nested inside other instances** \u2014 it records as an override on the outer instance. Only variable-binding writes (`setBoundVariable`) silently revert inside instance internals. Don\'t skip nested instances when migrating variant or boolean properties; skip them only for binding writes.\n- **`Plugin runtime aborted` is an out-of-memory, not a timeout.** The stack shows `deepWrap` recursing into `newString` before `abort`. Reading deep-wrapped properties \u2014 `componentProperties`, `overrides`, `boundVariables`, `exportSettings` \u2014 copies a fresh object into the QuickJS sandbox on EVERY access, so a loop over tens of thousands of instances kills the runtime even though each read looks free. Chunk the scan and keep only the fields you need. (Real case: `componentProperties` over 29,861 instances aborted; the same scan over 7,139 was fine.)\n- **What a file USES is not what its library HAS.** `get_design_system`\'s remote-used list only reports components the file already placed \u2014 a library component nobody has dragged in yet is invisible to the plugin, and no amount of scanning the document will reveal it. Read the published catalog before concluding a component doesn\'t exist (one real case: a design system\'s `TextArea` was declared missing and hand-rebuilt from a stretched `Text Field`, because the file had never used the real one).\n- **A component property\'s identity is the `#id` suffix, not its display name.** Renaming `show label#4525:247` to `hasLabel#4525:247` in the library keeps every instance\'s override \u2014 text and boolean values survive a library update untouched. VARIANT axes are the opposite: they have no id and are matched by name, so renaming an axis or its values (`layout=horizontal` \u2192 `labelPosition=side`) is the only thing that actually drops instances back to a default. When auditing a library migration, snapshot the variant axes and ignore the renamed text/boolean props.\n- **`importComponentSetByKeyAsync` returns the file\'s LOCAL copy, not the latest published version.** If the file holds a stale copy of a library component, the import hands back the stale one and looks authoritative. To see what is actually published, read `componentPropertyDefinitions` over REST (`/v1/files/{key}/nodes?ids={node_id}&depth=1`) and compare. Importing is also expensive \u2014 each call materialises the whole set (a 72-variant set is thousands of nodes), and a handful in one script will abort the sandbox.\n- **GRID auto-layout has read-only positions and imperative setters.** `gridRowAnchorIndex` / `gridColumnAnchorIndex` are readonly \u2014 move a child with `node.setGridChildPosition(row, column)` (spans stay writable: `gridColumnSpan`). `gridColumnSizes` / `gridRowSizes` reject array assignment (`no setter for property`), but `gridColumnCount` / `gridRowCount` are writable and each returned `GridTrackSize` has `.type` / `.value` setters \u2014 so add a track by raising the count, then set the new track\'s type. Shrinking the row count is how you drop a leftover empty row.\n- **`figma.root.findAll` throws in dynamic-page mode until you `await figma.loadAllPagesAsync()`.** Page-scoped work never needs it: `figma.currentPage` is already loaded and `relai.query` searches from a node you pass. Load the whole document only when the search genuinely spans pages \u2014 on a 40-page file it is seconds of work and memory.\n- **`instance.mainComponent` throws in dynamic-page mode** \u2014 `await instance.getMainComponentAsync()`. The same rule catches every sync sibling of an async API (`getNodeById`, `textStyleId =`, `page.children` on an unloaded page): when the message says *use X instead*, it means the whole traversal from that point is async.\n- **A variant has no component property definitions of its own** (`Can only get component property definitions of a component set or non-variant component`). They belong to the COMPONENT_SET \u2014 read `node.parent` when a variant is what you have, and add new TEXT/BOOLEAN properties to the set too: adding them to a single variant either fails or leaves the other variants without them.\n- **`SPACE_BETWEEN` centres a lone child.** A header built as label + value with the value hidden by default looks correct in the variant you were staring at and lands centred everywhere else \u2014 because Figma spreads a single item to the middle rather than leaving it at the start. When one side is optional, align the row `MIN` and let the first child FILL: the optional one stays pinned to the far edge when it appears, and the other stays put when it does not.\n- **Applying a text style changes the node\'s font, so a `characters` write right after it can throw for a font nobody loaded.** `await node.setTextStyleIdAsync(id)` may swap the family or weight; load the *new* font (`await figma.loadFontAsync(node.fontName)`) before writing text. Applying the style is also the last word on properties it owns \u2014 a `textDecoration` written in the same breath is overwritten by the style landing, so set it in a later call.\n- **Text edits inside a component SET propagate to every variant.** Applying a text style to one variant\'s label retypes the matching layer in all of them \u2014 same for `textDecoration` and text fills, at node level and via `setRange*` alike. Renaming the layer does not break the link (matching is positional). So a set whose sizes need DIFFERENT text styles cannot be styled in place: apply the styles while the components are still standalone and combine afterwards \u2014 an atom does not save you either unless the atom\'s variants are standalone components rather than a set of their own. Two more from the same afternoon: `combineAsVariants` drops `textDecoration`, and a decoration written in the same execution as `setTextStyleIdAsync` is clobbered by the style landing \u2014 set it in a later call.\n- **Writing `leadingTrim` on a text node detaches its text style** and strands the style\'s typography variables as node-level bindings \u2014 the node keeps rendering but no longer follows the style. `textDecoration` is safe (the style survives); `leadingTrim` is not. When a cap-trimmed label needs to sit in a full line box (so an icon beside it doesn\'t hang below the baseline, and toggling the icon doesn\'t change the height), leave the trim alone and bind the PARENT frame\'s height to the same leading variable the style uses.\n- **A variable bound to a component property\'s VALUE hides from `boundVariables`.** `node.boundVariables.componentProperties` lists the VARIANT properties and nothing else \u2014 a token bound to a TEXT or INSTANCE_SWAP property (an icon glyph name, a swapped instance) lives only in `instance.componentProperties[key].boundVariables.value`. Read one location and every such token looks unreferenced. Bindings authored as a property\'s *default* sit in a third place, `componentPropertyDefinitions[key].boundVariables`, on the SET.\n- **"Plugin runtime aborted" is out of memory, not a timeout**, and reading `instance.componentProperties` in bulk is the fastest way there: the getter deep-wraps every property object, so 1,000 instances costs about 4 seconds and 5,700 kills the sandbox. Memory is only reclaimed when the command returns, so the fix is slices \u2014 walk a fixed number of nodes per command and have the caller ask again \u2014 not a tidier traversal inside one script.\n- **`component.clone()` loses every `componentPropertyReferences` until it is back inside a SET** \u2014 and it does not get them back when you append it. Cloning a variant to make a new one therefore yields a variant whose label, `show*` toggles and swaps are all dead: the layers are there, the wiring is not. The clone renders convincingly because each layer keeps the *value* it had. After `set.appendChild(clone)`, walk the source variant and the clone in `findAll` order and copy `componentPropertyReferences` node for node.\n- **An instance whose variant you deleted becomes a ghost, and `setProperties` cannot reach it.** It still reports a `mainComponent` \u2014 named after the *deleted* variant, parented to the live set \u2014 but its `componentProperties` no longer carry the set\'s variant axes, so writes are dropped without an error. Figma does not fall back to the default variant. The repair is `instance.swapComponent(targetVariant)` and then `setProperties`; a variant-count audit will not find these, because the set itself looks healthy.\n- **SLOT properties are per-node and giving two of them the same name does not merge them.** A set whose variants each carry their own slot ends up with two entries \u2014 `Items Slot#1938:15` and `Items Slot#1938:18` \u2014 and renaming them alike only makes the panel show two rows nobody can tell apart, which is worse than the honest `Sm`/`Md` names. The consequence worth knowing before designing around it: content placed in one variant\'s slot does **not** survive switching to a variant that owns the other slot, and there is no way to express "one slot, shared across variants" today.\n- **`componentPropertyReferences` cannot be set on a layer inside a nested instance \u2014 but almost everything else on that layer can.** The references belong to that instance\'s own main component, so writing them throws `Cannot set component property references on instance sublayer`. The trap is over-correcting: excluding instance sublayers from the *paint* loop as well leaves half the job done and no error, because fills, characters and visibility on those same sublayers are perfectly writable \u2014 and in a component whose label or icon lives inside a nested atom, that is exactly where the colour you meant to change lives. Skip sublayers when copying references; include them when painting.\n- **Deleting a layer from a component can silently orphan instance-side overrides on layers you did not touch.** Figma re-creates part of the instance\'s subtree with fresh node ids, and any override keyed to the old ids is dropped \u2014 on the instance only. The component still renders correctly, which is exactly why nobody notices: the master is where you look. After removing layers from a set, diff each instance against its main property by property; a screenshot of the component proves nothing about its instances.\n- **Setting `layoutSizingHorizontal/Vertical = "FIXED"` right after `insertChild` freezes the node at the size the row just stretched it to**, not the size it wants. An icon instance that is 12\xD712 on its own lands in a 16-tall row, gets stretched, and the FIXED you meant as *don\'t grow* records 16\xD716 permanently. Insert, let the layout settle, and set `layoutAlign`/`layoutGrow` instead \u2014 or copy the posture of a healthy sibling in the same row rather than asserting sizing modes from scratch.\n- **A component that sizes itself from the inside must not be re-sized from the outside.** Where a wrapper hugs a child whose own width/height are bound to size tokens, the wrapper carries no bindings at all \u2014 that absence *is* the mechanism. Binding the outer instance\'s width/height to look tidy overrides the child and pins one size across every variant, and the mistake is invisible because the number is right in whichever variant you were looking at. Before binding a dimension, check whether the node already derives it.\n- **A long editing session leaves `findAll` enumerating instance sublayers that no longer exist.** After a few hundred `swapComponent` calls and nested component-property writes, `page.findAll` still returns proxies whose ids are gone: touching one \u2014 `getMainComponentAsync`, or merely `.name` \u2014 throws *The node (instance sublayer or table cell) with id \u2026 does not exist*, while `getNodeByIdAsync` on the same id answers `null`. The document is fine (it renders and validates); it is the enumeration that is stale, and a plugin reload clears it. Two consequences for doc-wide sweeps: wrap each node in its own try/catch, and never read the failing node inside the catch to report it.\n- **A plain write clears a variable-bound component property only on the node you write to \u2014 read back to confirm which node still holds the alias.** `instance.setProperties({ key: "diamond" })` does drop the `VARIABLE_ALIAS` on that instance (measured both with a different value and with the token\'s own resolved string). What surprises people is where the binding *else* lives: set it on one instance and the main component keeps its own alias, so re-reading the master still reports bound; and an instance nested two levels down (`.Icon Content` inside a `Body Cell` inside a `Column`) carries its own override that the parent write never touches. Always read the property back on the exact node you meant to change, and sweep nested instances separately.\n- **Component property keys are `name#id`, and the name may itself contain `#`** \u2014 `.Icon Content` ships `Icon Name#4866:0`, `Icon Name w/##4866:28` and `Icon Name w/###4866:56`. Splitting on the *first* `#` maps the last two to the same base name, so a lookup silently binds only one of them and the duotone layers keep their placeholder glyph. Split on `lastIndexOf("#")`. The mirror trick is useful: matching on the `#id` tail alone follows a property across a rename, since `editComponentProperty` keeps the id.\n- **A plugin-created instance placed under an explicit variable mode stays stuck on the placeholder, and waiting does not fix it.** Create an instance, drop it under a node whose Theme mode differs from the page\'s, and read it back: the nested variant *does* swap (`iconFamily=Phosphor` \u2192 `FA7`), but a component property bound to a variable resolves to the new variant\'s **default** rather than to the token, so every icon reads as the placeholder glyph. Measured: still wrong after three minutes untouched \u2014 in `characters` and in the rendered screenshot alike \u2014 and setting the *same* mode again changes nothing. What unsticks it is `clearExplicitVariableModeForCollection` followed by `setExplicitVariableModeForCollection`; the binding was never destroyed, only unresolved. (Distinct from the few-second repaint lag a designer sees after switching a theme by hand on content that already exists.) A brand-switch probe built and screenshotted in one pass will therefore report that a whole file\'s icon tokens are broken when nothing is wrong: clear-and-re-set before reading, and confirm against a node that was already in the file.\n- **`variable.remove()` succeeds even when instances still bind it, and the variable keeps working \u2014 so a retirement can look clean and change nothing.** After removing it, `getLocalVariablesAsync()` no longer lists it (the designer sees it gone from the panel) but `getVariableByIdAsync(id)` still resolves it, the bindings still render its last value, and no error is raised anywhere. The trap is upstream, in the consumer scan that told you it was safe: a walker that does `if (node.type === \'INSTANCE\') { check its componentProperties; return }` never descends into nested instances, and component-property bindings mostly live there \u2014 an `.Icon Content` inside a `Body Cell` inside a `Column`. One retirement measured 0 consumers by that walk and 160 by a walk that recursed. Before removing a variable, recurse through instance children; afterwards the id keeps resolving forever (it is a tombstone, not proof of failure), so verify instead that it has left `getLocalVariablesAsync()` and that a recursive scan finds zero bindings.\n- **`clone()` on a variant downgrades a SLOT child to a plain FRAME and drops its `slotContentId` reference** \u2014 the copy looks right and quietly loses the slot. Re-assigning `componentPropertyReferences = { slotContentId: \'<Slot#id>\' }` to the cloned frame restores the behaviour: the master still reports `FRAME`, but instances of it materialise a real `SLOT` child, expose the SLOT property, and accept appended content. There is no `figma.createSlot()`, so this reassignment is the only repair from code; duplicating the variant in the Figma UI keeps the SLOT type intact. Relai\'s post-run lint now names the slotless variants, but only for component sets it can reach \u2014 return the ids of what you cloned.\n- **`setBoundVariable` takes a Variable object, not an id string** \u2014 the string form throws `Cannot call setBoundVariable with a variable id. Please pass a variable object`. Fetch the variable first (`getVariableByIdAsync`, or a map built from `getLocalVariablesAsync`) and pass the object itself.\n- **Rebinding width/height on a node INSIDE an instance is a silent no-op** \u2014 `setBoundVariable` returns without error and `boundVariables` still shows the old id afterwards. Only `setBoundVariable(field, null)` (unbind) persists there. Stuck overrides \u2014 bindings an instance kept from a main that has since been cleaned \u2014 can therefore never be re-pointed from code, only cleared; and if the main is already clean, clearing IS the correct repair (the node falls back to the main\'s shape, pixels stay put). Measured on 301 soft-deleted `Size/height/12` bindings (2026-08-12): rebind reported success \xD7301 and changed nothing; unbind cleared every one. Always read the field back after writing \u2014 success without verification is how this one hides.\n- **One broken component set crashes a whole-file property scan**: `instance.componentProperties` (and a set\'s `componentPropertyDefinitions`) throw `Component set has existing errors` when the backing set has variant conflicts \u2014 and the set may not even be on any page (a soft-deleted draft still referenced by one forgotten instance). A file-wide audit that reads properties uncaught dies on the first such instance. Guard each read with try/catch, report skips, and find the culprit cheaply: collect unique `mainComponent.parent` sets across instances and probe `componentPropertyDefinitions` on each (a few hundred sets) instead of touching every instance.\n- **Dot-prefixed components are never published**, so their keys 404 on every REST endpoint. Figma hides `.`-prefixed assets from the publish dialog; they exist only nested inside published parents. When resolving a key \u2192 file via `/v1/components/{key}`, skip names starting with `.` \u2014 and note a component SET\'s key resolves only at `/v1/component_sets/{key}`, never at `/v1/components/{key}` (and vice versa). Relatedly, `/v1/files/{key}/components` returns the individual VARIANTS (`size=md, state=default`); the components a designer names live in `/component_sets`.\n- **Freshly created frames and components count their strokes into hug sizing** \u2014 `strokesIncludedInLayout` defaults to `true`, so a hairline bottom divider makes an auto-layout row report 40.5 instead of 40, and an outlined container reports two extra pixels. The half-pixel survives into every instance and into any math you do on the height. Components that should keep integer dimensions need `strokesIncludedInLayout = false` set explicitly; existing hand-built components in a file often already have it off, which is why cloning them behaves differently from building from scratch.\n- **Converting a frame to a Slot in the Figma UI freezes its sizing at FIXED and strips the property references of everything inside it.** The converted node keeps the width/height it had at conversion time as a hard FIXED size (a later `layoutSizingHorizontal = "HUG"` is rejected; `"FILL"` is accepted), and a TEXT child that carried a `characters` reference (`label#\u2026`) comes out with the reference gone while the component property itself survives on the set \u2014 the panel shows the control, typing into it does nothing. After any frame\u2192Slot conversion: re-assert the slot\'s sizing explicitly and re-wire `componentPropertyReferences` on its former children. (`figma.createSlot` does not exist \u2014 conversion is UI-only, so this cleanup is always manual-plus-script.)\n- **`combineAsVariants` re-keys every component property and can drop a TEXT property\'s `characters` reference on the way.** The ids in property keys (`title#1033:0`) belong to the standalone components; combining mints new set-level keys (`title#7527:4`) \u2014 so any key strings you saved before combining are stale afterwards. Worse, the re-wiring is lossy: in one measured combine the `title` reference survived on all variants while the `description` reference vanished from all of them, with no error. After every combine, audit `componentPropertyReferences` across all variants against the set\'s `componentPropertyDefinitions` and re-wire the orphans (survival is luck, not a rule \u2014 this is the same disease as duplicated variants keeping no references, in a different coat).\n<!-- PITFALLS:END -->\n\nAlso: `resize(w, h)` throws on `w <= 0 || h <= 0`; `layoutWrap = "WRAP"` is HORIZONTAL-only, `counterAxisAlignItems = "BASELINE"` too; writing to `locked` nodes is allowed by the API but surprises designers \u2014 check first.\n\n## Return values\n\nReturn JSON-serializable data (the bridge summarizes nodes automatically and truncates >50k chars). Prefer returning `{ id, name, type }` summaries over whole nodes. `console.log` is captured and returned in `logs`.\n\n---\n\n*Tool parameter contracts are deliberately not duplicated in this document \u2014 every tool is self-describing over MCP, and `npx figma-relai docs <tool>` (or the generated `docs/manifest.json`) is the always-current reference.*\n';
+var figma_plugin_api_default = "# Figma Plugin API Cheat Sheet \u2014 for `execute_figma`\n\nRules and patterns for writing code that runs in the plugin sandbox. Work in small incremental scripts and `screenshot` between steps.\n\n## Non-negotiable rules (dynamic-page mode)\n\n- **Node lookup is async**: `await figma.getNodeByIdAsync(id)` \u2014 `getNodeById` throws in this plugin.\n- **Load pages before traversal**: `await page.loadAsync()` before `page.findAll(...)` on a non-current page; `figma.currentPage` is always loaded.\n- **Load fonts before ANY text edit**: `await figma.loadFontAsync(textNode.fontName)` \u2014 if `fontName === figma.mixed`, load every range: `for (const f of textNode.getRangeAllFontNames(0, textNode.characters.length)) await figma.loadFontAsync(f)`.\n- **`figma.mixed` is a Symbol**: properties like `fontSize`, `cornerRadius`, `fills` return it when values differ across ranges/children. Check `=== figma.mixed` before using; never JSON-serialize it.\n\n## Common patterns\n\n```js\n// Selection\nconst sel = figma.currentPage.selection;          // read\nfigma.currentPage.selection = [node];             // write\n\n// Create + place\nconst frame = figma.createFrame();\nframe.resize(320, 200);                            // width/height are read-only; use resize()\nparent.appendChild(frame);                         // default parent is currentPage\n\n// Fills/strokes are ARRAYS and must be reassigned wholesale\nnode.fills = [{ type: \"SOLID\", color: { r: 1, g: 0.5, b: 0 } }];  // rgb 0-1, no alpha key \u2014 use opacity\nconst fills = JSON.parse(JSON.stringify(node.fills));              // clone before mutating\nfills[0].color.r = 0; node.fills = fills;\n\n// Auto-layout: set layoutMode FIRST, then padding/spacing/align\nframe.layoutMode = \"VERTICAL\";\nframe.itemSpacing = 8; frame.paddingTop = 16;\nchild.layoutSizingHorizontal = \"FILL\";             // requires PARENT with auto-layout\n\n// Components\nconst comp = await figma.importComponentByKeyAsync(key);  // team library\nconst inst = comp.createInstance();\ninst.setProperties({ Variant: \"Primary\" });        // throws on unknown property names\n\n// Variables\nconst collections = await figma.variables.getLocalVariableCollectionsAsync();\nconst v = figma.variables.createVariable(\"name\", collection, \"COLOR\");\nv.setValueForMode(modeId, { r: 0, g: 0, b: 0 });\nnode.setBoundVariable(\"fills\", v);                 // binding paint needs figma.variables.setBoundVariableForPaint on the paint object for fills in older APIs \u2014 prefer setBoundVariable where available\n\n// Export (returns Uint8Array)\nconst bytes = await node.exportAsync({ format: \"PNG\", constraint: { type: \"SCALE\", value: 2 } });\n```\n\n## `relai.*` helpers \u2014 the shortest path is the correct one\n\nAlongside `figma`, scripts get a `relai` object whose helpers are immune to the pitfalls below. Prefer them:\n\n```js\nawait relai.text(parent, \"Hello\", { font: {family:\"IBM Plex Mono\", style:\"Regular\"}, size: 14, color: {r:0,g:0,b:0} });\n                                          // loads the font BEFORE writing characters\nconst card = relai.autoLayout(\"VERTICAL\", { name: \"Card\", itemSpacing: 8 });\n                                          // auto-layout frame, both axes hugging\nrelai.set(node, { layoutMode: \"HORIZONTAL\", width: 320, opacity: 0.9 });\n                                          // layoutMode applied first; width/height via resize()\nrelai.hug(node);                          // HUG that sticks \u2014 call after appending children\nrelai.focusRing(button);                  // clipsContent + double spread shadows that render\nconst page = await relai.page(p => p.children.some(c => c.name === \"Button\"));\n                                          // find pages by CONTENT \u2014 names get renamed\nconst titles = relai.query('FRAME[name^=Card] > TEXT');\n                                          // CSS-like search on the current page; relai.query(node, sel) scopes to a subtree.\n                                          // Supported: TYPE, *, [name=] [name*=] [name^=] [name$=], descendant, >, comma.\n                                          // NOT supported: pseudo-classes, dot-paths, sibling combinators \u2014 use findAll.\nrelai.placeholder(section);               // construction veil so the designer sees work-in-progress\nrelai.placeholder(section, false);        // ALWAYS remove when the section is done\n```\n\nTwo important facts: **scripts are NOT atomic** \u2014 on error, changes made before the throw persist, so keep scripts small and clean up after failures; and results may carry a `warnings` array for silent mistakes the lint catches on relai-created nodes and any node ids you return (e.g. spread shadows on a non-clipping frame). Convention: **return every created/mutated node id** (`return { createdNodeIds: [...] }`) \u2014 it powers both follow-up calls and the lint.\n\n## Pitfalls that throw (or silently do the wrong thing)\n\nWhen one of these throws inside `execute_figma`, the error already carries the remedy as a `Hint:` \u2014 this list is generated from the same registry (`packages/shared/src/pitfalls.ts`).\n\n<!-- PITFALLS:START -->\n- **`not a function` errors may name no symbol** \u2014 Figma's VM drops the subject. Usual cause: APIs from other agent tools that don't exist here (`node.query()`, `figma.notify()`). Use `findAll`/`findAllWithCriteria` for search; bisect when the message names nothing.\n- **Editing text without loading its font throws** (`unloaded font`). `await figma.loadFontAsync(textNode.fontName)` first; new TextNodes default to Inter Regular; when `fontName === figma.mixed`, load every font from `getRangeAllFontNames()`.\n- **`getNodeById` throws in dynamic-page mode** \u2014 always `await figma.getNodeByIdAsync(id)`.\n- **Traversing a non-current page throws until you `await page.loadAsync()`** \u2014 `figma.currentPage` is always loaded, other pages are not. Two things make this bite later than it should. `getNodeByIdAsync` resolves a node on an unloaded page perfectly well, so a handler handed a node id looks healthy right up to the moment it walks children. And the page is often already loaded by whatever ran first, so identical code passes in a session where another tool touched that page and throws in one where it did not \u2014 which reads as flakiness rather than a missing load. Load the page you need yourself; and if the caller swallows handler errors, this stops being a failure and becomes a check that silently disappears.\n- **`layoutSizingHorizontal/Vertical` throw without auto-layout** \u2014 FILL requires the parent to have a `layoutMode`, HUG requires it on the node itself.\n- **`createPage()` throws on the free plan once a file has 3 pages** \u2014 reuse an existing page instead.\n- **`width`/`height` are read-only** \u2014 use `node.resize(w, h)`.\n- **`figma.mixed` is a Symbol** returned by `fontSize`, `cornerRadius`, `fills` etc. when values differ across ranges/children \u2014 check `=== figma.mixed` before use; never JSON-serialize it.\n- **Exact-name lookups are fragile** \u2014 designers rename pages and layers freely; locate nodes by type/content instead of `name ===`.\n- **Stale node ids throw `does not exist`** \u2014 nodes get deleted while you work; re-read before editing and check `node.removed`.\n- **Nodes are non-extensible** \u2014 `node.myCustomProp = x` throws `object is not extensible`; use `setPluginData` or return the data instead.\n- **Shadow `spread` renders only on shapes or frames with `clipsContent: true`** \u2014 a focus ring built from spread shadows is invisible on a non-clipping frame/component.\n- **`resize()` on an auto-layout frame silently pins that axis to FIXED**, overriding `primaryAxisSizingMode: \"AUTO\"`. Append children first, then set `layoutSizingHorizontal = \"HUG\"`; use `resize` only for the fixed cross-axis.\n- **Per-corner radius** (`topLeftRadius` \u2026) only exists on RectangleCornerMixin nodes (rectangles, frames, components) \u2014 polygons, stars and lines throw.\n- **Instance children can't be added or removed** \u2014 detach first, or edit the main component.\n- **Figma's slot feature (Convert to slot, \u21E7\u2318S) has no Plugin API** \u2014 no createSlot/convertToSlot exists (verified against typings 1.123 and at runtime, 2026-07). Scaffold a frame named \"Slot\", select it for the designer (navigate select), and let them press the shortcut.\n- **A converted SLOT node stops hugging** \u2014 after the designer converts a frame to a slot it carries its own fixed size. Re-assert `layoutSizingVertical = \"HUG\"` (and the intended horizontal mode) on the SLOT node afterwards; the API can still edit its layout props.\n- **Variantizing can silently pin the hug axis to FIXED** \u2014 observed after clone \u2192 counterAxisSizingMode/width-variable changes \u2192 combineAsVariants: the variants' `primaryAxisSizingMode` ended up FIXED though the source hugged. Always verify sizing modes on every variant after combineAsVariants and re-assert `\"AUTO\"`.\n- **A backgrounded Figma window suspends the plugin iframe** \u2014 timers freeze and the socket can't pong, so the relay's staleness sweep kicks the plugin and the frozen 2s redial never fires until the window regains attention. The panel redials on visibilitychange/focus (ui.html \u22650.2.4); when a paired plugin goes missing mid-session, ask the designer to click the Figma window before assuming anything is broken.\n- **A freshly-converted slot can still report `type: \"FRAME\"` to the Plugin API** \u2014 the layer panel shows the slot badge while getNodeByIdAsync returns FRAME (a reload boundary was observed to fix it). Never gate automation on `type === \"SLOT\"`; match the frame by name and trust the designer's visual confirmation.\n- **Deleted variables are soft-deleted ghosts** \u2014 `getVariableByIdAsync` still resolves them with name AND working values (`Variable` has no `removed` property), so bindings to them keep rendering while being invisible in pickers and dead on publish. To test aliveness, check membership in `getLocalVariablesAsync()` (remote variables are legitimately absent \u2014 check `variable.remote`).\n- **Variables cannot be reordered via the API** (`variableIds` is read-only; the `move\u2026After` methods exist only for styles) \u2014 new variables always append last; panel order is manual-drag only. NEVER delete-and-recreate variables to reorder: bindings reference variable IDs, so every binding in the file silently dies (observed in production; the ghosts keep rendering, hiding the damage).\n- **A remote (library) text style dominates variable bindings** \u2014 on text with a remote style applied, `setBoundVariable` writes appear to succeed but snap back to the style's own bindings. Clear the style first (`await setTextStyleIdAsync(\"\")`), then bind.\n- **Binding writes inside instances silently revert \u2014 with two escape hatches.** `setBoundVariable` on a node nested inside an INSTANCE succeeds without error, then reverts (instance roots placed directly in a main ARE writable; anything deeper is not). What does persist: reassigning the whole `fills`/`strokes` array (variable-bound paints ride inside), and range-level `setRangeBoundVariable` on text. Verify after writing; never trust the call alone.\n- **A bound `strokeWeight` renders nothing while `strokes` is empty, and wrappers don't hug stroke thickness.** A LINE's visible weight lives entirely in its stroke paint; the frame around it keeps its own raw height/width, so the panel shows an unbound number with empty Fill/Stroke \u2014 looking broken when it isn't. Inspect the LINE child's stroke bindings, not the wrapper; and bind the wrapper's thickness-axis dimension to the same variable so nothing stays raw.\n- **`setBoundVariable(\"strokeWeight\", \u2026)` is a silent no-op on FRAME-family nodes.** Frames and components bind stroke weight per side \u2014 `strokeTopWeight` / `strokeRightWeight` / `strokeBottomWeight` / `strokeLeftWeight`; the uniform `strokeWeight` field only binds on stroke-geometry nodes like LINE. No error is thrown, the binding just never appears \u2014 read back `boundVariables` after writing.\n- **Cloning a variant escapes its component set \u2014 onto whatever page the user is viewing.** `variant.clone()` parents the copy to `figma.currentPage` as a standalone COMPONENT (not into the set) \u2014 plain nodes inside components clone to the current page too. Every `componentPropertyReferences` pointing at set-level properties is silently severed, and native SLOT children are demoted to plain FRAMEs (slot-ness needs set context). Recover by `componentSet.appendChild(clone)`, re-assigning ALL references (`visible`, `slotContentId`, \u2026) \u2014 a SLOT can be restored by cloning a surviving SLOT node from a sibling variant (SLOT clones keep their type) and relinking `componentPropertyReferences.slotContentId`. Audit every set-scoped feature after adoption; none of it comes back on its own.\n- **Uneven variant renames/deletes poison the whole component set.** If variants end up with mismatched axis segments (some carry `axis=value`, others don't) or duplicate names, the set enters an error state where `componentPropertyDefinitions` AND every instance's `variantProperties`/`setProperties` throw (`Component set has existing errors`). Escape: rename stragglers so all variants share the same axes with unique values (temporary `legacy-*` values work), which heals the set \u2014 then migrate and delete.\n- **`setProperties` DOES work on instances nested inside other instances** \u2014 it records as an override on the outer instance. Only variable-binding writes (`setBoundVariable`) silently revert inside instance internals. Don't skip nested instances when migrating variant or boolean properties; skip them only for binding writes.\n- **`Plugin runtime aborted` is an out-of-memory, not a timeout.** The stack shows `deepWrap` recursing into `newString` before `abort`. Reading deep-wrapped properties \u2014 `componentProperties`, `overrides`, `boundVariables`, `exportSettings` \u2014 copies a fresh object into the QuickJS sandbox on EVERY access, so a loop over tens of thousands of instances kills the runtime even though each read looks free. Chunk the scan and keep only the fields you need. (Real case: `componentProperties` over 29,861 instances aborted; the same scan over 7,139 was fine.)\n- **What a file USES is not what its library HAS.** `get_design_system`'s remote-used list only reports components the file already placed \u2014 a library component nobody has dragged in yet is invisible to the plugin, and no amount of scanning the document will reveal it. Read the published catalog before concluding a component doesn't exist (one real case: a design system's `TextArea` was declared missing and hand-rebuilt from a stretched `Text Field`, because the file had never used the real one).\n- **A component property's identity is the `#id` suffix, not its display name.** Renaming `show label#4525:247` to `hasLabel#4525:247` in the library keeps every instance's override \u2014 text and boolean values survive a library update untouched. VARIANT axes are the opposite: they have no id and are matched by name, so renaming an axis or its values (`layout=horizontal` \u2192 `labelPosition=side`) is the only thing that actually drops instances back to a default. When auditing a library migration, snapshot the variant axes and ignore the renamed text/boolean props.\n- **`importComponentSetByKeyAsync` returns the file's LOCAL copy, not the latest published version.** If the file holds a stale copy of a library component, the import hands back the stale one and looks authoritative. To see what is actually published, read `componentPropertyDefinitions` over REST (`/v1/files/{key}/nodes?ids={node_id}&depth=1`) and compare. Importing is also expensive \u2014 each call materialises the whole set (a 72-variant set is thousands of nodes), and a handful in one script will abort the sandbox.\n- **GRID auto-layout has read-only positions and imperative setters.** `gridRowAnchorIndex` / `gridColumnAnchorIndex` are readonly \u2014 move a child with `node.setGridChildPosition(row, column)` (spans stay writable: `gridColumnSpan`). `gridColumnSizes` / `gridRowSizes` reject array assignment (`no setter for property`), but `gridColumnCount` / `gridRowCount` are writable and each returned `GridTrackSize` has `.type` / `.value` setters \u2014 so add a track by raising the count, then set the new track's type. Shrinking the row count is how you drop a leftover empty row.\n- **`figma.root.findAll` throws in dynamic-page mode until you `await figma.loadAllPagesAsync()`.** Page-scoped work never needs it: `figma.currentPage` is already loaded and `relai.query` searches from a node you pass. Load the whole document only when the search genuinely spans pages \u2014 on a 40-page file it is seconds of work and memory.\n- **`instance.mainComponent` throws in dynamic-page mode** \u2014 `await instance.getMainComponentAsync()`. The same rule catches every sync sibling of an async API (`getNodeById`, `textStyleId =`, `page.children` on an unloaded page): when the message says *use X instead*, it means the whole traversal from that point is async.\n- **A variant has no component property definitions of its own** (`Can only get component property definitions of a component set or non-variant component`). They belong to the COMPONENT_SET \u2014 read `node.parent` when a variant is what you have, and add new TEXT/BOOLEAN properties to the set too: adding them to a single variant either fails or leaves the other variants without them.\n- **`SPACE_BETWEEN` centres a lone child.** A header built as label + value with the value hidden by default looks correct in the variant you were staring at and lands centred everywhere else \u2014 because Figma spreads a single item to the middle rather than leaving it at the start. When one side is optional, align the row `MIN` and let the first child FILL: the optional one stays pinned to the far edge when it appears, and the other stays put when it does not.\n- **Applying a text style changes the node's font, so a `characters` write right after it can throw for a font nobody loaded.** `await node.setTextStyleIdAsync(id)` may swap the family or weight; load the *new* font (`await figma.loadFontAsync(node.fontName)`) before writing text. Applying the style is also the last word on properties it owns \u2014 a `textDecoration` written in the same breath is overwritten by the style landing, so set it in a later call.\n- **Text edits inside a component SET propagate to every variant.** Applying a text style to one variant's label retypes the matching layer in all of them \u2014 same for `textDecoration` and text fills, at node level and via `setRange*` alike. Renaming the layer does not break the link (matching is positional). So a set whose sizes need DIFFERENT text styles cannot be styled in place: apply the styles while the components are still standalone and combine afterwards \u2014 an atom does not save you either unless the atom's variants are standalone components rather than a set of their own. Layers bound to one TEXT component property are linked through the property as well: every layer whose `characters` references it shares a single `textDecoration` \u2014 write it on one variant and all of them change, re-binding a layer pulls it back to the shared value, and only a layer whose reference is removed keeps its own. The binding step writes too: pointing five variants' titles at a new TEXT property replaced their `characters` with the property's default and reset their underline to `NONE`, while the `combineAsVariants` just before it had kept every variant's underline. So a label whose decoration differs per variant cannot sit on a shared TEXT property. And a decoration written in the same execution as `setTextStyleIdAsync` is clobbered by the style landing \u2014 set it in a later call.\n- **Writing `leadingTrim` on a text node detaches its text style** and strands the style's typography variables as node-level bindings \u2014 the node keeps rendering but no longer follows the style. `textDecoration` is safe (the style survives); `leadingTrim` is not. When a cap-trimmed label needs to sit in a full line box (so an icon beside it doesn't hang below the baseline, and toggling the icon doesn't change the height), leave the trim alone and bind the PARENT frame's height to the same leading variable the style uses.\n- **A variable bound to a component property's VALUE hides from `boundVariables`.** `node.boundVariables.componentProperties` lists the VARIANT properties and nothing else \u2014 a token bound to a TEXT or INSTANCE_SWAP property (an icon glyph name, a swapped instance) lives only in `instance.componentProperties[key].boundVariables.value`. Read one location and every such token looks unreferenced. Bindings authored as a property's *default* sit in a third place, `componentPropertyDefinitions[key].boundVariables`, on the SET.\n- **\"Plugin runtime aborted\" is out of memory, not a timeout**, and reading `instance.componentProperties` in bulk is the fastest way there: the getter deep-wraps every property object, so 1,000 instances costs about 4 seconds and 5,700 kills the sandbox. Memory is only reclaimed when the command returns, so the fix is slices \u2014 walk a fixed number of nodes per command and have the caller ask again \u2014 not a tidier traversal inside one script.\n- **`component.clone()` loses every `componentPropertyReferences` until it is back inside a SET** \u2014 and it does not get them back when you append it. Cloning a variant to make a new one therefore yields a variant whose label, `show*` toggles and swaps are all dead: the layers are there, the wiring is not. The clone renders convincingly because each layer keeps the *value* it had. After `set.appendChild(clone)`, walk the source variant and the clone in `findAll` order and copy `componentPropertyReferences` node for node.\n- **An instance whose variant you deleted becomes a ghost, and `setProperties` cannot reach it.** It still reports a `mainComponent` \u2014 named after the *deleted* variant, parented to the live set \u2014 but its `componentProperties` no longer carry the set's variant axes, so writes are dropped without an error. Figma does not fall back to the default variant. The repair is `instance.swapComponent(targetVariant)` and then `setProperties`; a variant-count audit will not find these, because the set itself looks healthy.\n- **SLOT properties are per-node and giving two of them the same name does not merge them.** A set whose variants each carry their own slot ends up with two entries \u2014 `Items Slot#1938:15` and `Items Slot#1938:18` \u2014 and renaming them alike only makes the panel show two rows nobody can tell apart, which is worse than the honest `Sm`/`Md` names. The consequence worth knowing before designing around it: content placed in one variant's slot does **not** survive switching to a variant that owns the other slot, and there is no way to express \"one slot, shared across variants\" today.\n- **`componentPropertyReferences` cannot be set on a layer inside a nested instance \u2014 but almost everything else on that layer can.** The references belong to that instance's own main component, so writing them throws `Cannot set component property references on instance sublayer`. The trap is over-correcting: excluding instance sublayers from the *paint* loop as well leaves half the job done and no error, because fills, characters and visibility on those same sublayers are perfectly writable \u2014 and in a component whose label or icon lives inside a nested atom, that is exactly where the colour you meant to change lives. Skip sublayers when copying references; include them when painting.\n- **Deleting a layer from a component can silently orphan instance-side overrides on layers you did not touch.** Figma re-creates part of the instance's subtree with fresh node ids, and any override keyed to the old ids is dropped \u2014 on the instance only. The component still renders correctly, which is exactly why nobody notices: the master is where you look. After removing layers from a set, diff each instance against its main property by property; a screenshot of the component proves nothing about its instances.\n- **Setting `layoutSizingHorizontal/Vertical = \"FIXED\"` right after `insertChild` freezes the node at the size the row just stretched it to**, not the size it wants. An icon instance that is 12\xD712 on its own lands in a 16-tall row, gets stretched, and the FIXED you meant as *don't grow* records 16\xD716 permanently. Insert, let the layout settle, and set `layoutAlign`/`layoutGrow` instead \u2014 or copy the posture of a healthy sibling in the same row rather than asserting sizing modes from scratch.\n- **A component that sizes itself from the inside must not be re-sized from the outside.** Where a wrapper hugs a child whose own width/height are bound to size tokens, the wrapper carries no bindings at all \u2014 that absence *is* the mechanism. Binding the outer instance's width/height to look tidy overrides the child and pins one size across every variant, and the mistake is invisible because the number is right in whichever variant you were looking at. Before binding a dimension, check whether the node already derives it.\n- **A long editing session leaves `findAll` enumerating instance sublayers that no longer exist.** After a few hundred `swapComponent` calls and nested component-property writes, `page.findAll` still returns proxies whose ids are gone: touching one \u2014 `getMainComponentAsync`, or merely `.name` \u2014 throws *The node (instance sublayer or table cell) with id \u2026 does not exist*, while `getNodeByIdAsync` on the same id answers `null`. The document is fine (it renders and validates); it is the enumeration that is stale, and a plugin reload clears it. Two consequences for doc-wide sweeps: wrap each node in its own try/catch, and never read the failing node inside the catch to report it.\n- **A plain write clears a variable-bound component property only on the node you write to \u2014 read back to confirm which node still holds the alias.** `instance.setProperties({ key: \"diamond\" })` does drop the `VARIABLE_ALIAS` on that instance (measured both with a different value and with the token's own resolved string). What surprises people is where the binding *else* lives: set it on one instance and the main component keeps its own alias, so re-reading the master still reports bound; and an instance nested two levels down (an icon instance inside a `Body Cell` inside a `Column`) carries its own override that the parent write never touches. Always read the property back on the exact node you meant to change, and sweep nested instances separately.\n- **Component property keys are `name#id`, and the name may itself contain `#`** \u2014 an icon component can ship `Icon Name#4866:0`, `Icon Name w/##4866:28` and `Icon Name w/###4866:56`. Splitting on the *first* `#` maps the last two to the same base name, so a lookup silently binds only one of them and the duotone layers keep their placeholder glyph. Split on `lastIndexOf(\"#\")`. The mirror trick is useful: matching on the `#id` tail alone follows a property across a rename, since `editComponentProperty` keeps the id.\n- **An instance under an explicit variable mode can get stuck on the placeholder \u2014 when a plugin creates it there, or switches its variant there \u2014 and waiting does not fix it.** Create an instance, drop it under a node whose Theme mode differs from the page's, and read it back: the nested variant *does* swap (`iconFamily=Phosphor` \u2192 `FA7`), but a component property bound to a variable resolves to the new variant's **default** rather than to the token, so every icon reads as the placeholder glyph. Measured: still wrong after three minutes untouched \u2014 in `characters` and in the rendered screenshot alike \u2014 and setting the *same* mode again changes nothing. What unsticks it is `clearExplicitVariableModeForCollection` and then `setExplicitVariableModeForCollection` **in two separate `execute_figma` calls**: clearing and re-setting inside one script leaves it stuck (measured both when read 1.5 seconds later in the same script and when read in the next call). The binding was never destroyed, only unresolved. The order does not matter: appending to a parent with no explicit mode and setting the parent's mode in a later call leaves the same placeholder. Nor does it take a new instance: switching an existing instance's variant with `setProperties` under a pinned parent drops the same way \u2014 glyph properties fall back to the unbound placeholder, icon fills to the default variable, a bound size to none \u2014 but only in modes that swap a nested instance to a different variant than its main uses; where the mode resolves to the main's own icon family, nothing drops. Clear-then-set in separate calls restored every binding in both cases. It is not a sure cure: in another probe (five button instances created in one call, their parent's mode set in the next), clearing and setting the mode in two further calls, then setting it on each instance too, left the two loading buttons' variable-bound glyph names on the placeholder. Writing the resolved values with `setProperties` did stick there, as long as only properties whose value differs are written: writes that repeated the variant properties' current values flipped the nested icon to the main's own variant in 2 of 7 cases (both on the instances with bound glyph names), and writing the differing value back fixed it. That write costs the binding \u2014 a plain write drops the alias on that node (see the plain-write entry) \u2014 so it suits a throwaway probe, not a file's instances. (Distinct from the few-second repaint lag a designer sees after switching a theme by hand on content that already exists.) A brand-switch probe built and screenshotted in one pass will therefore report that a whole file's icon tokens are broken when nothing is wrong: clear in one call, set in the next, read after that \u2014 and confirm against a node that was already in the file.\n- **`variable.remove()` succeeds even when instances still bind it, and the variable keeps working \u2014 so a retirement can look clean and change nothing.** After removing it, `getLocalVariablesAsync()` no longer lists it (the designer sees it gone from the panel) but `getVariableByIdAsync(id)` still resolves it, the bindings still render its last value, and no error is raised anywhere. The trap is upstream, in the consumer scan that told you it was safe: a walker that does `if (node.type === 'INSTANCE') { check its componentProperties; return }` never descends into nested instances, and component-property bindings mostly live there \u2014 an icon instance inside a `Body Cell` inside a `Column`. One retirement measured 0 consumers by that walk and 160 by a walk that recursed. Before removing a variable, recurse through instance children; afterwards the id keeps resolving forever (it is a tombstone, not proof of failure), so verify instead that it has left `getLocalVariablesAsync()` and that a recursive scan finds zero bindings.\n- **`clone()` on a variant downgrades a SLOT child to a plain FRAME and drops its `slotContentId` reference** \u2014 the copy looks right and quietly loses the slot. Re-assigning `componentPropertyReferences = { slotContentId: '<Slot#id>' }` to the cloned frame restores the behaviour: the master still reports `FRAME`, but instances of it materialise a real `SLOT` child, expose the SLOT property, and accept appended content. There is no `figma.createSlot()`, so this reassignment is the only repair from code; duplicating the variant in the Figma UI keeps the SLOT type intact. Relai's post-run lint now names the slotless variants, but only for component sets it can reach \u2014 return the ids of what you cloned.\n- **`setBoundVariable` takes a Variable object, not an id string** \u2014 the string form throws `Cannot call setBoundVariable with a variable id. Please pass a variable object`. Fetch the variable first (`getVariableByIdAsync`, or a map built from `getLocalVariablesAsync`) and pass the object itself.\n- **Giving a node INSIDE an instance a new width/height from code does nothing \u2014 rebinding width/height and `resize()` are silent no-ops, and `rescale()` throws.** `setBoundVariable` returns without error and `boundVariables` still shows the old id afterwards. Only `setBoundVariable(field, null)` (unbind) persists there. On a nested instance (a logo inside a footer instance), `resize()`, `resizeWithoutConstraints()` and `resize()` after `unlockAspectRatio()` all returned normally and read back the old 105.3\xD748, and `rescale(0.75)` threw `This property cannot be overridden in an instance: size` \u2014 change the size in the main (a variant with that size) instead. To back out, `removeOverrides()` on the nested instance clears only the overrides from that layer down; the outer instance keeps its own. Stuck overrides \u2014 bindings an instance kept from a main that has since been cleaned \u2014 can therefore never be re-pointed from code, only cleared; and if the main is already clean, clearing IS the correct repair (the node falls back to the main's shape, pixels stay put). Measured on 301 soft-deleted `Size/height/12` bindings (2026-08-12): rebind reported success \xD7301 and changed nothing; unbind cleared every one. Always read the field back after writing \u2014 success without verification is how this one hides. One sizing write does persist inside an instance: setting `layoutSizingHorizontal` / `layoutSizingVertical` to `HUG` on the inner node is kept, and it also clears stale overrides that point at nodes which no longer exist.\n- **One broken component set crashes a whole-file property scan**: `instance.componentProperties` (and a set's `componentPropertyDefinitions`) throw `Component set has existing errors` when the backing set has variant conflicts \u2014 and the set may not even be on any page (a soft-deleted draft still referenced by one forgotten instance). A file-wide audit that reads properties uncaught dies on the first such instance. Guard each read with try/catch, report skips, and find the culprit cheaply: collect unique `mainComponent.parent` sets across instances and probe `componentPropertyDefinitions` on each (a few hundred sets) instead of touching every instance.\n- **Dot-prefixed components are never published**, so their keys 404 on every REST endpoint. Figma hides `.`-prefixed assets from the publish dialog; they exist only nested inside published parents. When resolving a key \u2192 file via `/v1/components/{key}`, skip names starting with `.` \u2014 and note a component SET's key resolves only at `/v1/component_sets/{key}`, never at `/v1/components/{key}` (and vice versa). Relatedly, `/v1/files/{key}/components` returns the individual VARIANTS (`size=md, state=default`); the components a designer names live in `/component_sets`.\n- **Freshly created frames and components count their strokes into hug sizing** \u2014 `strokesIncludedInLayout` defaults to `true`, so a hairline bottom divider makes an auto-layout row report 40.5 instead of 40, and an outlined container reports two extra pixels. The half-pixel survives into every instance and into any math you do on the height. Components that should keep integer dimensions need `strokesIncludedInLayout = false` set explicitly; existing hand-built components in a file often already have it off, which is why cloning them behaves differently from building from scratch.\n- **Converting a frame to a Slot in the Figma UI freezes its sizing at FIXED and strips the property references of everything inside it.** The converted node keeps the width/height it had at conversion time as a hard FIXED size (a later `layoutSizingHorizontal = \"HUG\"` is rejected; `\"FILL\"` is accepted), and a TEXT child that carried a `characters` reference (`label#\u2026`) comes out with the reference gone while the component property itself survives on the set \u2014 the panel shows the control, typing into it does nothing. After any frame\u2192Slot conversion: re-assert the slot's sizing explicitly and re-wire `componentPropertyReferences` on its former children. (`figma.createSlot` does not exist \u2014 conversion is UI-only, so this cleanup is always manual-plus-script.)\n- **`combineAsVariants` re-keys every component property and can drop a TEXT property's `characters` reference on the way.** The ids in property keys (`title#1033:0`) belong to the standalone components; combining mints new set-level keys (`title#7527:4`) \u2014 so any key strings you saved before combining are stale afterwards. Worse, the re-wiring is lossy: in one measured combine the `title` reference survived on all variants while the `description` reference vanished from all of them, with no error. Existing instances do ride through the re-keying: when `combineAsVariants` turned a lone component into a set of one variant (the second was added afterwards), its TEXT key changed (`text#N:61` \u2192 `text#N:62`), the reference survived, and all 176 instances kept their text, size and position. After every combine, audit `componentPropertyReferences` across all variants against the set's `componentPropertyDefinitions` and re-wire the orphans (survival is luck, not a rule \u2014 this is the same disease as duplicated variants keeping no references, in a different coat).\n- **Writing `textAutoResize` resets a text node's truncation.** Assigning `NONE`, `HEIGHT` or `WIDTH_AND_HEIGHT` \u2014 including the value it already holds \u2014 sets `textTruncation` back to `DISABLED` and `maxLines` to `null`, with no error (24/24 cases, auto-layout children and free nodes alike). The deprecated `TRUNCATE` keeps `ENDING` but still drops `maxLines`; don't lean on it. `resize()` and `layoutSizingHorizontal` leave `textTruncation` alone, but they can flip `textAutoResize` between `HEIGHT` and `WIDTH_AND_HEIGHT` on the way. Order the writes: `textAutoResize` first, then `textTruncation` and `maxLines`, and re-read all three after any sizing change. On a node whose `textAutoResize` is `NONE`, writing `ENDING` reads back as `TRUNCATE`, and `maxLines = 1` is accepted but reads back `null`.\n- **Removing an instance that has slots leaves undeletable orphans behind \u2014 whether it came from `createInstance()` or `clone()`.** An instance with SLOT content keeps each slot's content in a `FRAME` with `parent === null`, holding the slotted instances; while the instance exists that frame is its live storage, not litter. Delete the instance and the frame stays. It sits on no page and nothing shows it, but `remove()` on it (or on the instances inside it) throws `Removing this node is not allowed`, and `component.getInstancesAsync()` keeps returning those instances: one probe that cloned slot-bearing instances to check variable modes took a component set's instance count (summed over its variants) from 545 to 959, and two probes built with `createInstance()` and deleted again left 24 such frames. Whether reopening the file clears them has not been measured. Don't build probes out of slot-bearing instances \u2014 to see one under another mode, resolve its variables against an existing node in that mode (`variable.resolveForConsumer(node)`) \u2014 and in instance audits drop any result whose ancestor chain never reaches a PAGE.\n- **Overriding an instance's text freezes the layer's styling along with it.** Writing `characters` on a text layer inside an instance stores the layer's `styledTextSegments` in the override, so the layer stops following its main per variant: an instance made from a variant whose title has a 1px underline, switched to a variant whose title has a 2px one, kept its own text *and* the 1px \u2014 and it will not follow a later change to the main's text styling either. Binding the layer to a TEXT property instead has its own edge: switch to a variant whose layer is not bound to that property and the text reverts to that variant's own. Create the instance from the variant it should show before overriding its text, and read the decoration back after any variant switch.\n- **An instance reads its main component's pluginData as its own, and emptying a key on the instance leaves an override behind.** `instance.getPluginData(key)` returns the main's value when the instance never set one \u2014 clear the key on the main and it disappears from every instance, and a sweep that counts keys node by node counts each inherited copy again (one cleanup found 188 keys, 94 of them inherited). Writing `''` on an instance does empty its value, but `pluginData` stays in that instance's `overriddenFields`, and nothing removes that entry alone: `removeOverrides()` also discards every rename and resize beside it. Clear a marker on the node you set it on, and don't read a key found on an instance as proof that the instance itself was marked.\n- **`getNodeByIdAsync` throws on the bare id of a variable or collection.** Variables and collections draw from the same `N:M` counter as nodes, so a scan over an id range lands on them: `getNodeByIdAsync('N:M')` for a variable's number throws `unsupported type in createVMObject: VARIABLE` (`VARIABLE_SET` for a collection) instead of returning `null`, while the prefixed `VariableID:N:M` just returns `null`. Catch per id when sweeping ranges, and resolve variables through `figma.variables.getVariableByIdAsync`.\n- **Range reads throw on an empty range, so an empty text node breaks the usual font-loading loop.** `getRangeAllFontNames(0, node.characters.length)` on a node whose `characters` is `\"\"` throws `Empty range selected. 'end' must be greater than 'start'`, and so does any `getRange*` read with `start === end` (`getRangeFontName(0, 0)`, `getRangeAllFontNames(1, 1)` on `\"ab\"`). `node.fontName` answers normally there and `getStyledTextSegments(['fontName'])` returns `[]`. Load `fontName` when the text is empty, and call range APIs only when `end > start`.\n- **`exportAsync` renders only what a clipping ancestor leaves visible, so pixel diffs of clipped content compare nothing.** By default a node is exported at its `absoluteRenderBounds`, which a `clipsContent` ancestor cuts: a 100\xD7300 child of a clipping 100\xD7100 frame exports as 100\xD7100, and a child clipped away entirely (its `absoluteRenderBounds` is `null`) exports as a 1\xD71 image \u2014 so the hidden rows of a clipped table \"match\" before and after whatever you changed in them. `exportAsync({ format: \"PNG\", useAbsoluteBounds: true })` renders the whole node, byte-identical to exporting it with the ancestor unclipped; use it for before/after comparisons, or compare `absoluteRenderBounds` with `absoluteBoundingBox` before trusting a diff.\n- **Switching a nested instance's variant can discard the overrides its container put inside it.** Inside a component, `setProperties({ state: \"default\" })` on a nested icon button moved it to the new variant but dropped what the component had set on the button's icon: the three glyph properties bound to variables came back as the new variant's unbound default, and the icon's bound fill as the default variable \u2014 only the binding on the icon's variant property (`style`) survived. No error, and instances of the component show the placeholder from then on. After switching a nested instance's variant, re-read its content node by node and rebind from a sibling variant that is already in the target state.\n- **Slot content that is already on another variant when it enters the slot can come back with ids that resolve to nothing.** If a nested instance in the content is already on a different variant than the component defines for it when the content lands in the slot \u2014 an explicit mode swapped an icon to another family, or an override set a menu item to `state=hovered` \u2014 its descendants get ids missing the slot's segment: `getNodeByIdAsync` answers `null` for them, and two items can report the same id. Switching the variant after the content is in the slot keeps the ids whole. The repair measured on a 311-node menu: clear the mode in one call, set the swapped item to its default variant in place in the next and back in the one after, then set the mode \u2014 14 unreadable nodes went to 0; clearing and re-setting the mode alone fixed 13 of them, not a hidden layer. Walk slot content with a per-node try/catch that records the path instead of stopping.\n- **When a variable mode swaps a nested instance to another variant, the swap is stored as overrides, and later binding changes on the main stop reaching it.** Eighteen instances were created in one call and their parents' Theme modes set in the next: in the mode that resolves the nested icon to the main's own variant, the nested instance carried no overrides; in each of the five modes that swapped it, it carried `boundVariables`, `componentProperties`, `fills`, `name`, both axis sizing modes and `targetAspectRatio` as overrides. Rebinding that nested instance's `style` property to a new variable in the main then reached only the unswapped instance \u2014 the other five kept reading the old variable \u2014 while fresh instances with the modes set again all showed the new binding. Instances that were already in the file carried the same overrides. After changing a binding in a main, re-create probe instances rather than re-reading old ones, and read `overrides` on the nested layer before trusting that the change reached instances under other modes.\n- **A VECTOR whose corners are rounded per vertex ignores `cornerRadius` writes on an instance, and only `rescale` scales those corners.** When the radius lives in `vectorNetwork.vertices[i].cornerRadius` (a glyph outline with 12 and 9 rounded vertices), writing the node's `cornerRadius` inside an instance adds a `cornerRadius` entry to `overrides` and nothing else: it reads back the main's 0.449, the vertices keep it, and the render is pixel-identical. Writing the main's value back leaves the entry behind; only `removeOverrides()` clears it, along with every other override on that instance. `resize()` scales the outline but not the vertex radii, so an instance resized 2.4\xD7 draws sharper corners than the main scaled 2.4\xD7 (alpha differs by up to 175/255 at the corners). `rescale(2.4)` scales the vertex radii too (0.449 \u2192 1.079, within 16/255 of the scaled main), but it does not coexist with a variable-bound height: binding `height` after `rescale` resets `scaleFactor` to 1 and the radii to 0.449 (with the aspect ratio locked as well), and `rescale` after binding multiplies the bound height (72 \u2192 259.2). Pick either the bound height or proportional corners.\n- **A bound paint's `color` is only a fallback \u2014 and one component set kept the fallback on screen.** `figma.variables.setBoundVariableForPaint(paint, 'color', v)` returns the paint with your `color` untouched (a `{0,0,0}` placeholder stays `{0,0,0}`). Assigned through `fills` or `setRangeFills`, the stored color is normally replaced by the variable's resolved value: in eight probes (node fills on text and on a rectangle; `setRangeFills` over a whole text, part of one, a text in a set variant, in a standalone component and on a TEXT-property layer) it read back as the resolved gray, and the exported ones rendered it. But four ranges written with `setRangeFills` in two variants of a working component set kept `{0,0,0}` while still bound, and rendered black; a scan of the 168 bound paints around them found no other mismatch, and the trigger was not isolated. Build bound paints with the resolved color (take `{ r, g, b }` from `v.resolveForConsumer(node).value` \u2014 it carries `a`, and a paint's `color` has no alpha) instead of a dummy, and after writing compare each bound paint's stored `color` with the resolved value. The same showed up on an instance whose fill override was bound to the very variable its main uses but stored `{0,0,0}`: it exported black where the main exported light.\n- **A blank symbol in a text node is not proof the font lacks it \u2014 the node can be holding a stale layout.** Key labels drew `\u2318` as empty space on some nodes and fine on others, all in the same monospace font, which has no `\u2318`, `\u21E7` or `\u23CE`: Figma draws those with its own fallback glyph, and the blank nodes held an old layout \u2014 `width` 7, the missing-glyph advance, where drawn ones measured 9 for `\u2318`/`\u23CE` and 8 for `\u21E7`. Switching the font does not help: a font whose file does contain `\u2318` and `\u23CE` still drew the same fallback glyph, and writing that font on the key text inside the masters' nested instances spread wrongly \u2014 145 of the file's 301 keys came out wrong, including keys with no symbol at all. What brought the glyph back was a fresh layout, reached the long way: on the five keys that had been given that font, `removeOverrides()` (which also returned the TEXT property to the main's default), then restoring the layer name and writing the property back to its symbol \u2014 the glyph appeared and the five keys grew 1\u20132 px. Writing the same value again without clearing first was not tried. Before blaming the font, compare the node's `width` with a node that renders; to repair, clear the overrides, write the text property back, and re-read the width.\n- **`remove()` on a COMPONENT leaves its id resolving, so a `null` lookup cannot confirm the cleanup.** After removing a component \u2014 standalone, or a variant removed along with its set \u2014 `getNodeByIdAsync(id)` still returns it, children included, with `parent === null` and `removed === false`; calling `remove()` on it again returns normally and changes nothing. Measured on four components removed in the call that created them; the COMPONENT_SET itself, and plain frames, text and rectangles removed the same way, did resolve to `null`. The component sits on no page and no page's children list it, but id sweeps find it; whether it goes away later has not been measured. Confirm component cleanup by ancestry (the chain must no longer reach a PAGE) rather than `null`, and build temporary probes from frames or instances of existing components rather than new components.\n- **Renaming a variant axis with `editComponentProperty` unbinds the instances, and can reset their plain overrides too.** Instances bound to that property keep their value but lose the `boundVariables.componentProperties` alias, nested explicit overrides included. In one measured rename, 71 instances whose value for the axis was a plain override \u2014 not bound to anything \u2014 fell back to the set's default variant. Right after rebinding, some instances kept an old value that disagreed with what the mode resolves to; writing the value first and then rebinding fixed them. Before renaming an axis, record every instance's value and binding for it; afterwards write the values back, rebind, and read both back.\n- **`figma.skipInvisibleInstanceChildren` is plugin-wide, not per script.** Setting it to `true` \u2014 a common speed-up for `findAll` \u2014 hides invisible sublayers of instances from every search that runs while it is set, not only the script that set it. Relai puts the previous value back after each `execute_figma` script, so it does not leak into later commands; set it again in every script that wants it, and while it is on, do not read an instance sublayer missing from a search as deleted.\n<!-- PITFALLS:END -->\n\nAlso: `resize(w, h)` throws on `w <= 0 || h <= 0`; `layoutWrap = \"WRAP\"` is HORIZONTAL-only, `counterAxisAlignItems = \"BASELINE\"` too; writing to `locked` nodes is allowed by the API but surprises designers \u2014 check first.\n\n## Return values\n\nReturn JSON-serializable data (the bridge summarizes nodes automatically and truncates >50k chars). Prefer returning `{ id, name, type }` summaries over whole nodes. `console.log` is captured and returned in `logs`.\n\n---\n\n*Tool parameter contracts are deliberately not duplicated in this document \u2014 every tool is self-describing over MCP, and `npx figma-relai docs <tool>` (or the generated `docs/manifest.json`) is the always-current reference.*\n";
 
 // ../../docs/skills/design-tokens-strategy.md
 var design_tokens_strategy_default = "# Design Tokens Strategy \u2014 4-Tier Token Architecture\n\n## Token Hierarchy\n\n### Tier 1 \u2014 Core (static)\nRaw values. Never referenced directly by components.\n- Naming: `color-static/{hue}/{shade}`, `spacing-static/{value}`\n- Examples: `color-static/slate/50`, `color-static/rose/500`\n- Single mode: Value\n- hiddenFromPublishing: true\n\n### Tier 1 \u2014 Core (dynamic)\nReferences static tokens. Handles Light/Dark inversion.\n- Naming: `color-dynamic/{hue}/{shade}`\n- Light mode: shade 50 \u2192 static/50, shade 900 \u2192 static/900\n- Dark mode: shade 50 \u2192 static/900, shade 900 \u2192 static/50 (inverted)\n- 2 modes: Light / Dark\n- hiddenFromPublishing: true\n\n### Tier 2 \u2014 Themes\nSemantic tokens. Define brand personality.\n- Naming: `color/{role}/{variant}`, `typography/{style}/{property}`, `border/{type}/{size}`\n- Color roles: background, content, border, icon\n- Color variants: surface-page, surface-default, surface-subtle, surface-knockout, disabled, utility/{status}/{emphasis|subtle}\n- Typography: headline-{lg|md|sm}, title-{lg|md}, body-{lg|md|sm}[-bold], label-{lg|md|sm}, code-{md|sm}[-bold]\n- Each typography style has: font-family, font-weight, font-size, letter-spacing, line-height\n- Modes: one per brand (e.g., Brand A, Brand B)\n- description: required \u2014 explain purpose and usage constraints\n- scopes: set appropriately (TEXT_FILL for content, STROKE_COLOR for border, FRAME_FILL for background, etc.)\n\n### Tier 3 \u2014 Components\nComponent-specific tokens. Reference Tier 2 or dynamic Tier 1.\n- Naming: `{component}/color/{role}/{state}`, `{component}/size/{variant}`\n- States: default, hover, pressed, disabled, selected, selected-hover, selected-pressed, selected-disabled\n- Sizes: sm, md, lg\n- Examples: `button/color/background/default`, `button/size/md`, `navigation/color/content/selected`\n- Modes: same as Tier 2 (one per brand)\n- Not every component needs Tier 3 \u2014 only when reuse or shared decision-making justifies it\n\n## Key Rules\n- Components MUST reference tokens only \u2014 never raw hex/px values\n- Tier 1 is internal plumbing \u2014 never expose to consumers\n- Adding a new brand = adding a mode to Tier 2 and Tier 3 collections\n- Light/Dark switching is handled entirely in Tier 1 dynamic \u2014 no brand-level light/dark logic needed\n\n## Workflow\n1. `get_design_tokens` \u2192 understand existing collections and modes\n2. `manage_variables` (list) with collectionId \u2192 inspect current tokens\n3. `manage_variables` (create_collection) \u2192 new collection with modes\n4. `manage_variables` (create) \u2192 define tokens with values per mode\n5. `manage_variables` (bind) \u2192 connect tokens to node properties\n6. `manage_variables` (set_scopes) \u2192 restrict UI picker visibility\n7. `manage_variables` (set_code_syntax) \u2192 set Dev Mode code references\n\n## Verification\n- `analyze_design` (aspect: color) \u2192 find unbound colors (token coverage)\n- `validate_design_rules` \u2192 check token_coverage rule\n- `get_node_data` (detail: variables) on key nodes \u2192 confirm bindings are correct\n\n---\n\n*Tool parameter contracts are deliberately not duplicated in this document \u2014 every tool is self-describing over MCP, and `npx figma-relai docs <tool>` (or the generated `docs/manifest.json`) is the always-current reference.*\n";
@@ -4424,7 +4976,7 @@ var design_system_first_default = '# Design-system-first building\n\nThe differe
 var janitorial_cleanup_default = '# Janitorial cleanup\n\nThe chores designers postpone for months \u2014 layer renaming, token drift, spacing normalization \u2014 are where an agent earns trust fastest. These jobs are big, mechanical, and easy to verify. Do them conservatively and loudly.\n\n## Ground rules\n\n- **Preview before bulk.** Use `dryRun:true` on `batch_execute` / `set_properties`, or report findings first (`analyze_design`), and tell the designer the scale ("about 140 renames on this page \u2014 go?"). If the plugin\'s approval gate is on, big writes will ask them anyway.\n- **Scope tightly.** Work page by page (or within the designer\'s selection). Never sweep the whole file unasked.\n- **Never rename or restyle library instances\' internals** \u2014 only top-level frames/groups the team owns.\n\n## Recipes\n\n### Rename layers by content\n`Frame 427` tells nobody anything. Walk the target scope with `execute_figma` + `relai.query`, and derive names:\n- A frame whose only text child says "Submit" \u2192 `Button/Submit` (match the file\'s existing naming pattern from `get_design_system`, don\'t invent one).\n- Text nodes \u2192 their content, truncated (`Heading: Pricing plans`).\n- Skip nodes that already have deliberate names (anything not matching `/^(Frame|Group|Rectangle|Ellipse|Vector|Line) \\d+$/`).\nReturn the rename list; apply via one `batch_execute` of `rename_node` commands.\n\n### Tokenize hardcoded values\n`analyze_design aspect:"tokens"` finds hardcoded colors/numbers that visually match existing variables; `manage_variables action:"tokenize" fix:true` binds them in one pass. Report anything close-but-not-matching (deltaE just over tolerance) instead of silently snapping it.\n\n### Normalize spacing\nIn auto-layout scopes, collect `itemSpacing`/padding values; flag off-scale values (not on the file\'s 4/8pt grid or spacing variables) and propose the nearest on-scale value. Apply only after the designer confirms the mapping.\n\n### Sweep detached instances\n`analyze_design aspect:"components"` lists likely-detached instances. Offer to re-link obvious ones (matching component still exists) and just report the rest \u2014 re-attaching wrong is worse than detached.\n\n## Report format\n\nEnd with counts and jump-points: what changed, what was skipped and why, node ids for spot-checking (the designer can click entries in the plugin feed).\n\n---\n\n*Tool parameter contracts are deliberately not duplicated in this document \u2014 every tool is self-describing over MCP, and `npx figma-relai docs <tool>` (or the generated `docs/manifest.json`) is the always-current reference.*\n';
 
 // ../../docs/skills/memory-and-precedents.md
-var memory_and_precedents_default = '# File memory & precedents\n\nEvery Figma file this plugin touches can carry its own case law: **precedents** \u2014 single adjudications the designer made, stored inside the file (shared plugin data) so they reach every future session from any AI client. Conventions are the statutes; precedents are the case law. Together they are the file\'s law, and `manage_conventions action:get` returns both.\n\nWhen a write touches something a precedent references, **the file speaks**: the ruling arrives attached to your tool result. Treat it as the designer\'s voice from a past session calling a halt \u2014 the four-act shape is always the same: they said it once, the file kept it, you came to "fix" it knowing nothing, their words stop you. Back off before you undo something intentional.\n\n## Read before you work\n\nAt the start of any session that will modify the file, call `manage_conventions action:get`. Treat what comes back the way you treat user instructions:\n\n- `content` \u2014 the conventions doc (statutes).\n- `precedents` \u2014 recent adjudications (case law), newest first, with `precedentCount` for the total.\n\nA precedent outranks your own judgment about what "looks wrong". If a precedent says a deviation is intent, do not "fix" it \u2014 and do not re-ask about it.\n\n## When to record\n\nRecord a precedent (`action:record_precedent`) when the designer **rules** on something durable. The signal is adjudication language:\n\n- "This is intentional, not drift" \u2192 `kind: "intent"`\n- "Approved \u2014 but never restructure this table again" \u2192 `kind: "decision"`\n- "Don\'t do it that way; do X instead" \u2192 `kind: "correction"`\n\nOne precedent = one sentence (\u2264280 chars), written so a future session with zero context understands the ruling. Attach `refs` \u2014 the variable IDs, node IDs, or page IDs the ruling concerns \u2014 because refs power in-band surfacing: any future write that touches them gets the precedent attached to its result automatically.\n\n**Always say in your reply that you recorded it** ("\u5DF2\u8BB0\u5165\u6587\u4EF6\u8BB0\u5FC6: \u2026"). Recording silently breaks the designer\'s trust in what the file knows.\n\n## When NOT to record\n\n- Transient, one-off choices ("make this one red for the screenshot").\n- Anything already in the conventions doc (point to it instead; propose a conventions edit if it deserves statute status).\n- Secrets, personal information, or anything about people rather than the file.\n- Your own inferences the designer has not confirmed. Precedents are the DESIGNER\'s rulings, not your observations. When unsure, ask: "\u8BB0\u4E3A\u5224\u4F8B\u5417?"\n\n## Promote rulings into enforcement\n\nWhen conventions or repeated precedents describe something ENFORCEABLE, propose the promotion \u2014 never enact it silently:\n\n- "Never touch page X" (in conventions or a repeated ruling) \u2192 send a panel proposal: `propose_rule` (via batch_execute) with `kind: "page_guard"`, the `pageIds`, and a `reason` that QUOTES the sentence it comes from. The designer gets a card and decides there; do not wait for the verdict and do not guard on your own. Mention in your reply that you proposed it.\n- Repeated identical adjudications ("this is intent" three times on the same token family) \u2192 offer to consolidate them into one conventions line, then remove the superseded precedents.\n\nGuards belong to the designer: never guard/unguard on your own judgment, and mention any guard change in your reply.\n\n## Kits \u2014 the law\'s common ancestor\n\nA designer who runs one product keeps its shared law as a **kit** (`manage_rulesets`; the panel\'s KIT row) \u2014 named, stored by the plugin on their machine, spanning every file. The file\'s carried law stays the working copy; the kit is the ancestor it descends from. When speaking to the designer, say kit.\n\nThis matters because **Figma discards file-carried law on branch\u2192main merges**. At session start, if `manage_rulesets action:status` says `file-empty`, the law was wiped: say so, and restore it (`action:restore`) with the designer\'s consent \u2014 or note it happened automatically when the set\'s autoRestore is on. Other states: `drifted` means file and ancestor differ \u2014 the designer chooses pull (`restore`) or promote the file\'s version (`push`); never resolve drift on your own.\n\nWhen the designer rules something clearly product-wide (not one-file-local), offer to promote that precedent into the linked kit (`action:promote` with the precedent id) so every linked file inherits it on restore.\n\n## Reporting style as trust matures\n\nEarly sessions: report every change. Once the designer clearly stops reading full receipts (they say "\u7B80\u62A5\u5C31\u597D" or approve digests), switch to digest mode: lead with **the two changes you are least sure about** and anything a precedent or guard touched, then one line for the rest ("\u5176\u4F59 N \u5904\u6309\u89C4\u7EA6"). Full detail must always remain one question away \u2014 digest is a summary, never a omission. Never digest away errors, guard rejections, or precedent hits.\n\n## Maintenance\n\n- The designer sees and can delete every entry in the plugin panel (Memory section). Their record, their rules.\n- Memory holds 200 entries / 64KB. When recording fails with a capacity error, offer a consolidation pass: `list_precedents`, merge superseded rulings into fewer summary entries (`record_precedent` the summaries, `remove_precedent` the merged ones), preserving every still-active ruling. Show the merge plan before applying it.\n- If a precedent contradicts current reality (the token it references is gone, the ruling was reversed), ask the designer whether to update or remove it \u2014 never silently drop case law.\n';
+var memory_and_precedents_default = '# File memory & precedents\n\nEvery Figma file this plugin touches can carry its own case law: **precedents** \u2014 single adjudications the designer made, stored inside the file (shared plugin data) so they reach every future session from any AI client. Conventions are the statutes; precedents are the case law. Together they are the file\'s law, and `manage_conventions action:get` returns both.\n\nWhen a write touches something a precedent references, **the file speaks**: the ruling arrives attached to your tool result. Treat it as the designer\'s voice from a past session calling a halt \u2014 the four-act shape is always the same: they said it once, the file kept it, you came to "fix" it knowing nothing, their words stop you. Back off before you undo something intentional.\n\n## Read before you work\n\nAt the start of any session that will modify the file, call `manage_conventions action:get`. Treat what comes back the way you treat user instructions:\n\n- `content` \u2014 the conventions doc (statutes).\n- `precedents` \u2014 recent adjudications (case law), newest first, with `precedentCount` for the total.\n\nA precedent outranks your own judgment about what "looks wrong". If a precedent says a deviation is intent, do not "fix" it \u2014 and do not re-ask about it.\n\n## When to record\n\nRecord a precedent (`action:record_precedent`) when the designer **rules** on something durable. The signal is adjudication language:\n\n- "This is intentional, not drift" \u2192 `kind: "intent"`\n- "Approved \u2014 but never restructure this table again" \u2192 `kind: "decision"`\n- "Don\'t do it that way; do X instead" \u2192 `kind: "correction"`\n\nOne precedent = one sentence (\u2264280 chars), written so a future session with zero context understands the ruling. Attach `refs` \u2014 the variable IDs, node IDs, or page IDs the ruling concerns \u2014 because refs power in-band surfacing: any future write that touches them gets the precedent attached to its result automatically.\n\n**Always say in your reply that you recorded it** ("\u5DF2\u8BB0\u5165\u6587\u4EF6\u8BB0\u5FC6: \u2026"). Recording silently breaks the designer\'s trust in what the file knows.\n\n## When NOT to record\n\n- Transient, one-off choices ("make this one red for the screenshot").\n- Anything already in the conventions doc (point to it instead; propose a conventions edit if it deserves statute status).\n- Secrets, personal information, or anything about people rather than the file.\n- Your own inferences the designer has not confirmed. Precedents are the DESIGNER\'s rulings, not your observations. When unsure, ask: "\u8BB0\u4E3A\u5224\u4F8B\u5417?"\n\n## Promote rulings into enforcement\n\nWhen conventions or repeated precedents describe something ENFORCEABLE, propose the promotion \u2014 never enact it silently:\n\n- "Never touch page X" (in conventions or a repeated ruling) \u2192 send a panel proposal: `propose_rule` (via batch_execute) with `kind: "page_guard"`, the `pageIds`, and a `reason` that QUOTES the sentence it comes from. The designer gets a card and decides there; do not wait for the verdict and do not guard on your own. Mention in your reply that you proposed it.\n- Repeated identical adjudications ("this is intent" three times on the same token family) \u2192 offer to consolidate them into one conventions line, then remove the superseded precedents.\n\nGuards belong to the designer: never guard/unguard on your own judgment, and mention any guard change in your reply.\n\n## Kits \u2014 the law\'s common ancestor\n\nA designer who runs one product keeps its shared law as a **kit** (`manage_rulesets`; the panel\'s KIT row) \u2014 named, stored by the plugin on their machine, spanning every file. The file\'s carried law stays the working copy; the kit is the ancestor it descends from. When speaking to the designer, say kit.\n\nThis matters because **Figma discards file-carried law on branch\u2192main merges**. At session start, if `manage_rulesets action:status` says `file-empty`, the law was wiped: say so, and restore it (`action:restore`) with the designer\'s consent \u2014 or note it happened automatically when the set\'s autoRestore is on. Other states: `drifted` means file and ancestor differ \u2014 the designer chooses pull (`restore`) or promote the file\'s version (`push`); never resolve drift on your own.\n\nWhen the designer rules something clearly product-wide (not one-file-local), offer to promote that precedent into the linked kit (`action:promote` with the precedent id) so every linked file inherits it on restore.\n\n## Reporting style as trust matures\n\nEarly sessions: report every change. Once the designer clearly stops reading full receipts (they say "\u7B80\u62A5\u5C31\u597D" or approve digests), switch to digest mode: lead with **the two changes you are least sure about** and anything a precedent or guard touched, then one line for the rest ("\u5176\u4F59 N \u5904\u6309\u89C4\u7EA6"). Full detail must always remain one question away \u2014 digest is a summary, never a omission. Never digest away errors, guard rejections, or precedent hits.\n\n## Maintenance\n\n- The designer sees and can delete every entry in the plugin panel (Memory section). Their record, their rules.\n- Memory holds 200 entries / 64KB. The size cap applies to rewrites too: an `update_precedent` that grows the memory past it is refused, while one that shrinks it always passes. A restore from a kit writes the conventions but skips the whole batch of seed precedents when they would not fit (`precedentsSkipped` in the result) \u2014 consolidate, then restore again. When recording fails with a capacity error, offer a consolidation pass: `list_precedents`, merge superseded rulings into fewer summary entries (`record_precedent` the summaries, `remove_precedent` the merged ones), preserving every still-active ruling. Show the merge plan before applying it.\n- If a precedent contradicts current reality (the token it references is gone, the ruling was reversed), ask the designer whether to update or remove it \u2014 never silently drop case law.\n';
 
 // ../../docs/skills/qa-gate.md
 var qa_gate_default = '# QA gate \u2014 the full physical, on demand\n\nHuman-triggered, review-moment audit of a file (or a set of pages). Run it when the designer says "\u4F53\u68C0" / "is this ready for review?" / before a library merge. It composes the gauges into one report with receipts.\n\n## The pass\n\nRun in this order (each is read-only):\n\n1. `manage_conventions action:get` \u2014 the law you\'ll be judging against (conventions + precedents). If precedents mark deviations as intent, they are NOT findings \u2014 the file already ruled. List them as "waived by precedent", never as problems.\n2. `analyze_design aspect:readiness` \u2014 agent-readiness score + top gaps.\n3. `analyze_design aspect:ghosts` (pass `pageIds` for a multi-page pass) \u2014 stale references to soft-deleted variables. Any ghost count > 0 is a red flag for publish.\n4. `analyze_design aspect:voice` \u2014 the file\'s signature (radius/spacing/type, tokenized-paint rate, instance rate).\n5. `analyze_design aspect:overall` on the key screens the designer names (health score 0-100).\n6. `analyze_design aspect:tokens` \u2014 hardcoded values that match existing variables (each is one `tokenize` away from bound).\n\n## The report\n\nProduce a compact markdown report, structured exactly like this:\n\n```\n# QA gate \u2014 <file name> \u2014 <date>\nverdict: PASS | PASS WITH NOTES | BLOCK\n\nreadiness  NN/100   (top gap: \u2026)\nghosts     N refs   (0 required for publish)\nhealth     NN/100   (screens: \u2026)\ntokens     N unbound-but-matchable\nvoice      radius \u2026, spacing \u2026, \u2026% tokenized\n\n## findings (ranked)\n1. [BLOCK|NOTE] \u2026 \u2014 evidence: <numbers/nodeIds> \u2014 fix: <one tool call>\n\u2026\n\n## precedent-protected (not findings)\n- \u2026 (per precedent "\u2026", YYYY-MM-DD)\n```\n\nVerdict rules: any ghosts or health < 60 on a named key screen \u2192 BLOCK; readiness < 50 \u2192 note it but readiness alone never blocks; everything protected by a precedent is listed separately, never as a finding.\n\n## Rules\n\n- Numbers unedited: report what the tools returned, never round a failing number into a passing one.\n- Findings must carry evidence (counts, nodeIds) and a one-call fix each.\n- Offer \u2014 do not perform \u2014 fixes. The QA gate is a read-only pass; repairs are a separate, approved session.\n- If the designer wants the report in-file: create a page named `\xB7 QA Report <date>` and write the report as text there (ask first \u2014 it adds a page to their file).\n- Big files: run ghosts page-set by page-set (`pageIds`) instead of one giant pass, and say which pages were covered. Silence about coverage reads as "covered everything" \u2014 never let it.\n';
@@ -4511,16 +5063,24 @@ function registerPrompts(server) {
 }
 
 export {
-  VERSION,
-  createServer,
   FIGMA_COMMANDS,
+  isErrorCode,
+  RelaiError,
+  PROTOCOL_VERSION,
+  inferLegacyCode,
+  isAllowedOrigin,
   RelayCore,
   PITFALLS,
+  currentCommandSlot,
+  noteSettled,
+  currentCallTarget,
+  VERSION,
   resolveFileIdentity,
   registerRoomTool,
   registerEventsTool,
   registerAllTools,
   listToolCatalog,
+  createServer,
   registerPrompts
 };
-//# sourceMappingURL=chunk-PYVHVZTO.js.map
+//# sourceMappingURL=chunk-62ZA4AUN.js.map