@design-twin/dtwin 0.1.0 → 0.1.1

package/README.md

@@ -18,6 +18,14 @@ bun add -g @design-twin/dtwin   # puts `dtwin` in ~/.bun/bin (on your PATH via t
 inside it — `dtwin init` prints the full path to import) and the design-to-code bundles the MCP server's
 `design_get_component` / `design_drift_lint` load (`layer/`).
 
+Or with Homebrew (macOS, Linux), which installs Bun for you and keeps both up to date with `brew upgrade`:
+```
+brew install its-magdy/tap/dtwin
+```
+The formula installs the same npm package into Homebrew's prefix; every release updates it. Paths `dtwin init` writes
+(the `.mcp.json` server entry, the plugin manifest it prints) are spelt through `$(brew --prefix)/opt/dtwin/…`, which
+survives an upgrade — not the versioned `Cellar/dtwin/<version>/` folder the next `brew upgrade` deletes.
+
 Or from a clone (to work on the code):
 ```
 git clone https://github.com/its-magdy/design-twin.git && cd design-twin
@@ -811,13 +819,38 @@ execution**, unlike some community servers; a `fill` / `color` must be a hex col
 `#rrggbb` or `#rrggbbaa` with the `#`, never a name like `red` — and anything else is refused (by the
 schema here, and by the plugin for a write from another client) instead of painted as a wrong colour; `dryRun: true` returns a preview of what each op would
 create or overwrite without touching the file — there is no undo from the MCP side, so preview anything
-that overwrites; refused outright when the file is in read-only Dev Mode), and two that read the export already on disk and
+that overwrites; refused outright when the file is in read-only Dev Mode — and **refused unless the designer has
+ticked "Allow edits"** in the plugin window, see below), and two that read the export already on disk and
 need no Figma connection — `design_get_component` (one component's variant node trees) and
 `design_drift_lint` (the component map vs the export; see below). The frame-walking export tools accept opt-in read flags
 `css` / `measurements` / `pluginData` / `motion` / `sharedData`; `figma_export_design_system` doesn't
 take them (it never walks a node — see below) but DOES take `variantVisuals`, since the component
 catalog it builds is exactly what that flag enriches.
 
+### "Allow edits" — the plugin changes nothing until the designer opts in
+The plugin window has an **Allow edits** checkbox, **off by default**. While it is off the plugin only reads:
+every `figma_write` batch is refused whole, before any op runs, and the tool returns this error (nothing in the
+file changed):
+
+> Edits are off in the Design Twin plugin — tick 'Allow edits' in the plugin window, then retry. Nothing in the file was changed.
+
+That is not something an agent can fix. **Ask the user to tick "Allow edits" in the Design Twin plugin window,
+then retry the same call.** The plugin's main thread holds the setting and checks it on every write; nothing on
+the bridge side can turn it on.
+
+- **Dry run still works while it is off.** `dryRun: true` previews the batch as before and adds `editsAllowed`
+  (read from the plugin's `whoami`): `false` → a real write would be refused right now (the preview also carries
+  `wouldRefuse` with the sentence above); `true` → it would be applied; `null` → unknown (no plugin connected,
+  several connected with no `client`, or a plugin built before the opt-in). Check it before asking the user to
+  review a preview, so the request to tick the box comes in the same breath.
+- **The setting is per user, for every file.** It is saved in Figma's `clientStorage`, which is already scoped
+  to one user and this plugin. It is not per file: the plugin cannot reliably name a file (`fileKey` is only for
+  private plugins, and file names repeat), and a per-file flag stored in the document would itself be an edit.
+  Untick it when you are done.
+- **No write is silent.** Each applied batch (and each refused one) shows a Figma toast and a line in the plugin
+  window, e.g. "Design Twin applied 3 edits to this file."
+- `dtwin whoami` prints the state (`edits: off — …` / `edits: ALLOWED — …`) and `editsAllowed` is in its JSON.
+
 ### `writeToDisk` — the export path that doesn't go through the context window
 Every export tool takes `writeToDisk: true` (plus an optional `outDir`). It writes the export through
 the same `write-out.ts` the CLI uses — same layout, by construction — and returns a **compact index**

package/figma-plugin/code.js

@@ -792,6 +792,7 @@
   function missingWriteFields(op, fields) {
     return WRITE_OPS[op].required.filter((k) => fields[k] === void 0);
   }
+  var EDITS_OFF_MESSAGE = "Edits are off in the Design Twin plugin \u2014 tick 'Allow edits' in the plugin window, then retry. Nothing in the file was changed.";
   var COMMAND_TRAITS = {
     ping: { run: "identity", export: false },
     whoami: { run: "identity", export: false },
@@ -3847,6 +3848,35 @@
     return { designSystem, layersDoc, assets: r.assets.slice() };
   }
 
+  // src/edits.ts
+  var KEY = "allowEdits";
+  var allowed = false;
+  var loaded = (async () => {
+    try {
+      allowed = await figma.clientStorage.getAsync(KEY) === true;
+    } catch (e) {
+      console.error("[export] could not read the Allow edits setting; edits stay off:", e);
+      allowed = false;
+    }
+  })();
+  async function editsAllowed() {
+    await loaded;
+    return allowed;
+  }
+  function editsAllowedNow() {
+    return allowed;
+  }
+  async function setEditsAllowed(on) {
+    await loaded;
+    allowed = on;
+    try {
+      await figma.clientStorage.setAsync(KEY, on);
+    } catch (e) {
+      console.error("[export] could not save the Allow edits setting:", e);
+    }
+    return allowed;
+  }
+
   // src/writes.ts
   function solidPaint(hex, what) {
     const c = parseHexColor(hex);
@@ -3868,11 +3898,17 @@
     if (p.type === "PAGE") await p.loadAsync();
     return p;
   }
+  var EditsRevoked = class extends Error {
+  };
+  function consent() {
+    if (!editsAllowedNow()) throw new EditsRevoked("'Allow edits' was turned off in the Design Twin plugin partway through this batch \u2014 the ops before this one were applied. Tick 'Allow edits' in the plugin window, then retry the rest.");
+  }
   async function applyWrite(op) {
     switch (op.op) {
       case "createFrame": {
         const parent = await resolveParent(op.parentId);
         const fill = op.fill ? solidPaint(op.fill, "createFrame fill") : null;
+        consent();
         const f = figma.createFrame();
         if (op.name) f.name = op.name;
         if (op.width && op.height) f.resize(op.width, op.height);
@@ -3891,8 +3927,13 @@
       case "createText": {
         const parent = await resolveParent(op.parentId);
         const fill = op.fill ? solidPaint(op.fill, "createText fill") : null;
+        consent();
         const t = figma.createText();
         await figma.loadFontAsync(t.fontName);
+        if (!editsAllowedNow()) {
+          t.remove();
+          consent();
+        }
         t.characters = op.text || "";
         if (op.fontSize) t.fontSize = op.fontSize;
         if (fill) t.fills = [fill];
@@ -3907,7 +3948,9 @@
         const nd = op.nodeId ? await figma.getNodeByIdAsync(op.nodeId) : null;
         if (!nd) throw new Error("setFill: no node with id '" + op.nodeId + "' (invalid or removed)");
         if (!("fills" in nd)) throw new Error("setFill: node '" + nd.name + "' (" + nd.type + ") has no fills");
-        nd.fills = [solidPaint(op.color, "setFill color")];
+        const paint = solidPaint(op.color, "setFill color");
+        consent();
+        nd.fills = [paint];
         return ifDefined("id", op.nodeId);
       }
       case "setText": {
@@ -3915,6 +3958,7 @@
         if (!nd) throw new Error("setText: no node with id '" + op.nodeId + "' (invalid or removed)");
         if (nd.type !== "TEXT") throw new Error("setText: node '" + nd.name + "' is a " + nd.type + ", not TEXT");
         await loadNodeFonts(nd);
+        consent();
         nd.characters = op.text || "";
         return ifDefined("id", op.nodeId);
       }
@@ -3923,8 +3967,31 @@
     }
   }
   async function applyWrites(ops) {
-    const list = Array.isArray(ops) ? ops : [];
+    const r = await gatedWrites(Array.isArray(ops) ? ops : []);
+    announce(r);
+    return r;
+  }
+  function announce(r) {
+    const n = r.applied.length;
+    const edits = n + " edit" + (n === 1 ? "" : "s");
+    let text = null;
+    if (r.refused === "edits-off") text = n ? "Design Twin applied " + edits + ", then stopped \u2014 'Allow edits' was turned off." : "Design Twin refused an edit request \u2014 'Allow edits' is off.";
+    else if (r.ok && n) text = "Design Twin applied " + edits + " to this file.";
+    else if (!r.ok && n) text = "Design Twin applied " + edits + ", then one failed: " + (r.error || "unknown error");
+    if (text === null) return;
+    try {
+      figma.notify(text, r.ok ? void 0 : { error: true });
+    } catch (e) {
+      console.error("[export] figma.notify failed:", e);
+    }
+    const m = { type: "writes", applied: n, ok: r.ok, text };
+    figma.ui.postMessage(m);
+  }
+  async function gatedWrites(list) {
     const applied = [];
+    if (list.length && !await editsAllowed()) {
+      return { ok: false, applied, refused: "edits-off", error: EDITS_OFF_MESSAGE };
+    }
     if (list.length && figma.editorType === "dev") {
       const first2 = list[0];
       return {
@@ -3948,7 +4015,8 @@
           applied,
           failedAt: i,
           failedOp: op && op.op,
-          error: errMsg(e)
+          error: errMsg(e),
+          ...e instanceof EditsRevoked ? { refused: "edits-off" } : {}
         };
       }
     }
@@ -4003,7 +4071,9 @@
             // `dtwin list clients` and `dtwin doctor` can never disagree about which build is running.
             pluginVersion: "0.1.0",
             fileKey: fileKey === void 0 ? null : fileKey,
-            fileKeyAvailable: typeof fileKey === "string" && fileKey.length > 0
+            fileKeyAvailable: typeof fileKey === "string" && fileKey.length > 0,
+            // So figma_write's dry run can say a real write would be refused before anyone sends one.
+            editsAllowed: await editsAllowed()
           };
           return r;
         };
@@ -4065,6 +4135,8 @@
       // cost class as listPages depth 2, not that of an export.
       case "listLibraries":
         return () => listLibraries();
+      // applyWrites refuses the batch whole while "Allow edits" is off (edits.ts) — the gate lives there, not
+      // here, so no caller of it can skip it.
       case "write": {
         const ops = req.args.ops;
         return () => applyWrites(ops);
@@ -4083,6 +4155,8 @@
     "get-identity",
     "run-selection",
     "run-full",
+    "get-allow-edits",
+    "set-allow-edits",
     "cancel",
     "bridge"
   ]);
@@ -4159,6 +4233,14 @@
         post2({ type: "identity", identity });
         break;
       }
+      case "get-allow-edits": {
+        post2({ type: "allow-edits", allowed: await editsAllowed() });
+        break;
+      }
+      case "set-allow-edits": {
+        post2({ type: "allow-edits", allowed: await setEditsAllowed(raw.allowed === true) });
+        break;
+      }
       case "run-selection": {
         await runSelection();
         break;

package/figma-plugin/ui.html

@@ -60,6 +60,13 @@
      have to look ALIVE — a bar frozen at 0% reads as a hang. */
   #progress.indet #bar { width: 30%; animation: indet 1.2s linear infinite; }
   @keyframes indet { from { margin-left: -30%; } to { margin-left: 100%; } }
+  /* "Allow edits": always visible (never inside the collapsed connection section), because it is the one
+     control an agent will ask the designer to find. */
+  #edits-row { display: flex; align-items: center; gap: 8px; font-size: 13px; cursor: pointer; margin: 6px 0; }
+  #edits-row input { flex: 0 0 auto; width: 14px; height: 14px; margin: 0; padding: 0; }
+  #edits-state { margin-left: auto; font-size: 11px; padding: 1px 7px; border-radius: 9px;
+                 background: var(--figma-color-bg-secondary, #f6f6f6); color: var(--figma-color-text-tertiary, #888); }
+  #edits-state.on { background: var(--figma-color-bg-warning-tertiary, #fff4e0); color: var(--figma-color-text-warning, #8a5a00); }
   #cancel { border-color: var(--figma-color-border-danger-strong, #c0362c); color: var(--figma-color-text-danger, #c0362c); }
 </style>
 
@@ -85,6 +92,17 @@
 
 <div class="hint">Save the downloads into your project's <code>design/</code> folder (assets into <code>design/assets/</code>).</div>
 
+<div class="sep"></div>
+<div class="label">Edits</div>
+<!-- Off by default. While it is off the plugin only READS this file: every edit request from the bridge is
+     refused before anything changes (figma-plugin/src/edits.ts is the authority, not this checkbox). -->
+<label id="edits-row" for="allow-edits">
+  <input id="allow-edits" type="checkbox" disabled />
+  <span>Allow edits</span>
+  <span id="edits-state">off</span>
+</label>
+<div class="hint" id="edits-hint" style="margin-top:2px">Lets Claude Code change this file over the bridge (add frames and text, set fills and text). Off: it can only read. Every change is announced here.</div>
+
 <div class="sep"></div>
 <!-- Optional. Closed by default; opened automatically only when it needs the user (a rejected token). -->
 <details id="connect">
@@ -307,9 +325,9 @@ var DesignTwinRelay = (() => {
       var p = $("progress"); if (p) p.hidden = false;
       setProgress(null);
       setBusy(true);
-      setStatus(info.source === "bridge"
-        ? "Export in progress — requested over the bridge (" + info.label + ")…"
-        : "Exporting…");
+      setStatus(info.source !== "bridge" ? "Exporting…"
+        : info.label === "write" ? "Applying edits requested over the bridge…"
+        : "Export in progress — requested over the bridge (" + info.label + ")…");
     }
     // Tear the run chrome down. Deliberately does NOT clear `cancelSent`: the main thread sends
     // run-end BEFORE the error that the cancellation produced, and both need to know it was a cancel.
@@ -452,6 +470,18 @@ var DesignTwinRelay = (() => {
         syncBatchButtons();
         return;
       }
+      if (m.type === "allow-edits") {
+        // The main thread's answer is the truth (edits.ts): the checkbox only ever shows what it holds.
+        var ae = $("allow-edits"); if (ae) { ae.checked = !!m.allowed; ae.disabled = false; }
+        var es = $("edits-state"); if (es) { es.textContent = m.allowed ? "on" : "off"; es.className = m.allowed ? "on" : ""; }
+        return;
+      }
+      if (m.type === "writes") {
+        // A write batch changed the file (or was refused): never silent. It arrives inside the write's own run
+        // (run-begin … run-end, and run-end leaves the status alone), so it replaces that run's line.
+        setStatus(m.text, !m.ok);
+        return;
+      }
       if (m.type === "token") {
         bridgeToken = m.token || "";
         var t = $("token"); if (t) t.value = bridgeToken;
@@ -672,6 +702,12 @@ var DesignTwinRelay = (() => {
             return a.text != null ? new Blob([a.text], { type: type }) : new Blob([b64ToBytes(a.base64)], { type: type });
           });
         };
+        var ae = $("allow-edits"); if (ae) ae.onchange = function () {
+          // Disabled until the main thread confirms, so a double toggle cannot race its own answer.
+          ae.disabled = true;
+          parent.postMessage({ pluginMessage: { type: "set-allow-edits", allowed: !!ae.checked } }, "*");
+        };
+        parent.postMessage({ pluginMessage: { type: "get-allow-edits" } }, "*");
         // Ask code.js for the stored token; connect() runs once it replies. Also proves the round-trip.
         parent.postMessage({ pluginMessage: { type: "get-token" } }, "*");
         setStatus("Ready — select a frame, or use the blue button.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@design-twin/dtwin",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Design Twin bridge: local CLI + MCP server between Claude Code and the Design Twin Figma plugin. Reads a design on the free Figma plan, fully offline.",
   "license": "MIT",
   "author": "Mohamed Magdy Omar",

package/src/commands.ts

@@ -170,6 +170,9 @@ export interface WhoamiReply {
   /** null when `figma.fileKey` is unavailable (not a private plugin) */
   fileKey: string | null;
   fileKeyAvailable: boolean;
+  /** Whether the designer has ticked "Allow edits" in the plugin window (edits.ts). Absent from a plugin
+   *  built before the opt-in existed — which applies every write it is sent. */
+  editsAllowed?: boolean;
 }
 
 /** One selected node (figma.currentPage.selection, summarised). */
@@ -285,13 +288,23 @@ export type ExportReply = FullExportReply | DesignSystemReply | ScreenReply | Sc
 export interface AppliedWrite {
   id?: string;
 }
-/** writes.ts applyWrites' reply: `ok: false` on a partial failure, with what was applied before it. */
+/** Why a whole batch was refused before any op ran — the one refusal a caller must hand to the PERSON at
+ *  the Figma window rather than fix itself. `edits-off`: the designer has not ticked "Allow edits"
+ *  (figma-plugin/src/edits.ts); nothing in the file changed. */
+export type WriteRefusal = "edits-off";
+/** The sentence a refused `edits-off` batch carries as `error`, and what figma_write shows the agent. */
+export const EDITS_OFF_MESSAGE =
+  "Edits are off in the Design Twin plugin — tick 'Allow edits' in the plugin window, then retry. Nothing in the file was changed.";
+/** writes.ts applyWrites' reply: `ok: false` on a partial failure, with what was applied before it. A batch
+ *  refused whole carries `refused` (and no `failedAt`: no op was tried); one stopped partway because the designer
+ *  unticked "Allow edits" carries `refused` AND `failedAt`, with the applied prefix. */
 export interface WriteResult {
   ok: boolean;
   applied: AppliedWrite[];
   failedAt?: number;
   failedOp?: string;
   error?: string;
+  refused?: WriteRefusal;
 }
 
 // ---------------------------------------------------------------- the map

package/src/figma-mcp.ts

@@ -36,7 +36,7 @@ import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/proto
 import type { ServerNotification, ServerRequest } from "@modelcontextprotocol/sdk/types.js";
 // The command/reply contract shared with the plugin (commands.ts): every route request below is
 // typed per command from it, so a tool cannot read a reply field the plugin never sends.
-import { WRITE_OP_NAMES, writeOpPreview, type Cmd, type Commands, type ExportReply, type WriteOp } from "./commands.ts";
+import { EDITS_OFF_MESSAGE, WRITE_OP_NAMES, writeOpPreview, type Cmd, type Commands, type ExportReply, type WriteOp } from "./commands.ts";
 // TIMEOUTS is the per-command budget table shared with the dtwin CLI. Every EXPORT tool needs a
 // budget well above server-core's 120s default (tuned for ping/getSelection, not for a walk of every
 // node on a page) — a whole-file walk is the slow case, but a single big frame is the same shape of
@@ -681,7 +681,10 @@ const writeOpShape = z.object({
 }).passthrough();
 
 // Each step is commands.ts writeOpPreview — the op's WRITE_OPS row, which the plugin's wire check (writeOpError) reads too.
-function previewWrites(ops: WriteOp[]) {
+// `editsAllowed` is the plugin's "Allow edits" checkbox as its whoami reports it: false => a real write would be
+// refused (and `wouldRefuse` says what to ask the designer); null => unknown (no plugin reachable, or one built
+// before the opt-in).
+function previewWrites(ops: WriteOp[], editsAllowed: boolean | null) {
   const steps = ops.map(writeOpPreview);
   return {
     dryRun: true,
@@ -690,10 +693,30 @@ function previewWrites(ops: WriteOp[]) {
     overwrites: steps.filter((s) => s.effect === "overwrites").length,
     invalid: steps.filter((s) => "invalid" in s).length,
     steps,
-    note: "Nothing was changed. Overwrites cannot be undone from here (only Cmd-Z in Figma). Re-call without dryRun to apply.",
+    editsAllowed,
+    ...(editsAllowed === false ? { wouldRefuse: EDITS_OFF_MESSAGE } : {}),
+    note: "Nothing was changed. Overwrites cannot be undone from here (only Cmd-Z in Figma). " +
+      (editsAllowed === false
+        ? "A real write would be REFUSED right now: 'Allow edits' is off in the Design Twin plugin window — ask the designer to tick it, then re-call without dryRun."
+        : editsAllowed === null
+          ? "Could not read the plugin's 'Allow edits' setting (no single plugin reachable); a real write is refused while it is off. Re-call without dryRun to apply."
+          : "Re-call without dryRun to apply."),
   };
 }
 
+// The dry run's read of the "Allow edits" checkbox. Never waits for a plugin to connect (the preview must answer
+// with none): nothing connected, several connected with no `client` named, or any failure, is `null` (unknown).
+async function readEditsAllowed(a: { client?: string | undefined } | undefined): Promise<boolean | null> {
+  try {
+    const n = (await route.listClients()).length;
+    if (n === 0 || (!(a && a.client) && n > 1)) return null;
+    const who = await ask("whoami", {}, { timeoutMs: TIMEOUTS.command, target: a && a.client });
+    return typeof who.editsAllowed === "boolean" ? who.editsAllowed : null;
+  } catch {
+    return null;
+  }
+}
+
 server.registerTool(
   "figma_write",
   {
@@ -705,7 +728,10 @@ server.registerTool(
       "Ops are applied in order and are NOT transactional: if one fails, the earlier ones stay applied " +
       "and their node ids are reported alongside the error so you can continue or clean up. " +
       "There is no undo from here (only the designer's own Cmd-Z) — so for anything that OVERWRITES " +
-      "(setFill/setText), call once with dryRun:true, show the user the preview, and only then apply.",
+      "(setFill/setText), call once with dryRun:true, show the user the preview, and only then apply. " +
+      "The plugin applies nothing unless the designer has ticked 'Allow edits' in its window (off by default); " +
+      "while it is off a write is refused with that instruction, and a dry run reports editsAllowed:false — " +
+      "ask the designer to tick it, then retry.",
     inputSchema: {
       ...clientShape,
       // Constrain `op` to the four ops the plugin actually implements — reject unknown ops at the
@@ -715,7 +741,7 @@ server.registerTool(
         // 50 ops is several screens' worth of frames/text, and a larger job is simply several calls.
         .max(50, "at most 50 ops per call — split a larger job into several calls (writes cannot be undone from here)")
         .describe("Ordered list of write operations (each must have an `op` field). At most 50 per call."),
-      dryRun: z.boolean().optional().describe("true = validate the batch and return a preview of what each op would create/overwrite, WITHOUT touching the Figma file (needs no plugin connection)."),
+      dryRun: z.boolean().optional().describe("true = validate the batch and return a preview of what each op would create/overwrite, WITHOUT touching the Figma file (needs no plugin connection; when one is connected it also reports editsAllowed — false means a real write would be refused)."),
     },
     // destructiveHint MUST stay true. Per the MCP schema it asserts, when false, that "the tool
     // performs only additive updates" — but setFill/setText OVERWRITE properties on nodes the user
@@ -728,10 +754,13 @@ server.registerTool(
   guarded(async (a) => {
     // The preview is built HERE, not plugin-side: it must work before a connection exists, and the
     // annotations above are only a hint — not every MCP client turns destructiveHint into a prompt.
-    if (a.dryRun) return textResult(previewWrites(a.ops || []));
+    if (a.dryRun) return textResult(previewWrites(a.ops || [], await readEditsAllowed(a)));
     // No cancel signal here (unlike the reads): a write cannot be un-applied, and aborting the wait would
     // only lose the `applied` ids below.
     const r = await ask("write", { ops: a.ops || [] }, { target: a && a.client });
+    // The designer has not consented: nothing was tried, so there is no op index and nothing to clean up. The
+    // fix is the PERSON's (a checkbox in the plugin window), so say exactly that rather than "write failed".
+    if (r.refused === "edits-off" && !r.applied.length) return errorResult(r.error || EDITS_OFF_MESSAGE);
     // Partial failure is reported as an error result, but MUST still carry `applied` — those nodes
     // exist in the document and the agent needs their ids to continue or undo.
     if (!r.ok) {

package/src/figma-pull.ts

@@ -947,6 +947,11 @@ async function whoamiCmd({ route, send, finish }: Session): Promise<void> {
   console.error("[dtwin] plugin version: " + (r.pluginVersion || "unknown (older bundle — predates version reporting)"));
   const stale = pluginStalenessNote(r.pluginVersion);
   if (stale) console.error("[dtwin] ! " + stale);
+  console.error("[dtwin] edits: " + (r.editsAllowed === true
+    ? "ALLOWED — the designer ticked 'Allow edits' in the plugin window; figma_write can change this file"
+    : r.editsAllowed === false
+      ? "off — the plugin refuses every write until the designer ticks 'Allow edits' in the plugin window (reads are unaffected)"
+      : "unknown (older bundle — predates the 'Allow edits' opt-in, and applies every write)"));
   console.error("[dtwin] fileKey: " + (r.fileKeyAvailable
     ? r.fileKey + " (available — usable as a stable routing key)"
     : "UNAVAILABLE (gated to private plugins; routing must use a server-minted id)"));

package/src/init.ts

@@ -9,7 +9,7 @@
 // Rules it keeps:
 //   - Never overwrites. Every file it would write is skipped, and said so, if it already exists;
 //     .mcp.json is MERGED (an existing "figma" entry is left exactly as it is). The one exception is
-//     an entry of OURS that can no longer start (mcpEntryProblems: a bun or figma-mcp.ts that is gone,
+//     an entry of OURS that can no longer start (mcpEntryProblems: a bun or figma-mcp.ts that is gone or spelt through a versioned Homebrew Cellar folder,
 //     a Node-era `node …/dist/figma-mcp.js`, bun without its two flags, a `bunx @design-twin/dtwin mcp` that fetches the
 //     package at start-up): --mcp re-points that entry, under
 //     its own key and keeping its other fields, at this install — and says so (--dry-run only says so).
@@ -106,8 +106,21 @@ const BUN_FLAGS = ["--no-install", "--no-env-file"] as const;
  *  process.execPath alone is the resolved file, and for a Homebrew (or any versioned) install that is a versioned path
  *  (…/Cellar/bun/1.4.2/bin/bun) the next `brew upgrade` deletes, leaving Claude Code a server it cannot start. */
 function stableBunPath(execPath: string = process.execPath, onPath: string | null = Bun.which("bun")): string {
-  if (!onPath) return execPath;
-  try { return fs.realpathSync(onPath) === fs.realpathSync(execPath) ? onPath : execPath; } catch { return execPath; }
+  if (!onPath) return stableKegPath(execPath);
+  try { return fs.realpathSync(onPath) === fs.realpathSync(execPath) ? onPath : stableKegPath(execPath); } catch { return stableKegPath(execPath); }
+}
+
+/** The upgrade-proof spelling of a path inside a Homebrew keg. Homebrew installs a formula into a versioned folder,
+ *  `<prefix>/Cellar/<formula>/<version>/…`, that the next `brew upgrade` deletes, and keeps `<prefix>/opt/<formula>` as a
+ *  symlink to whichever version is current. Bun resolves symlinks, so a file run through that opt link still sees its
+ *  Cellar path (import.meta.dirname, process.execPath) — and an absolute path written from it (.mcp.json's server and
+ *  bun, the plugin manifest Figma remembers) would stop working after one upgrade. Returns the opt spelling when it
+ *  resolves to the very same file, else `p` unchanged (not in a Cellar, or a layout where opt is elsewhere). */
+function stableKegPath(p: string): string {
+  const m = /^(.*)[\\/]Cellar[\\/]([^\\/]+)[\\/][^\\/]+(?:[\\/](.*))?$/.exec(p);
+  if (!m || m[1] === undefined || m[2] === undefined) return p;
+  const opt = path.join(m[1], "opt", m[2], m[3] ?? "");
+  try { return fs.realpathSync(opt) === fs.realpathSync(p) ? opt : p; } catch { return p; }
 }
 
 /** The bunx cache directory `dir` sits in, or null. `bunx @design-twin/dtwin …` installs the package into a cache tree
@@ -129,9 +142,16 @@ export interface EntryProbe {
   cwd?: string;
 }
 
+/** A path that works today but sits in a versioned Homebrew folder the next `brew upgrade` deletes — when the opt
+ *  spelling of it exists (stableKegPath), so init's repair has somewhere stable to point. Empty otherwise. */
+function kegProblem(what: string, p: string): string[] {
+  const stable = stableKegPath(p);
+  return stable === p ? [] : [`${what} ${p} is in a versioned Homebrew folder the next \`brew upgrade\` deletes (the stable spelling is ${stable})`];
+}
+
 /** What is wrong with an .mcp.json entry of OURS (isOurMcpEntry), one phrase each — empty when it will start: its command
  *  exists, it runs on Bun (not Node, not the old bridge/dist build), it names a server script (not a package bunx would
- *  fetch), that script exists outside a bunx cache, and bun gets the two flags before that script. The ONE rule for init (repair it) and doctor (report it). */
+ *  fetch), that script exists outside a bunx cache, neither is spelt through a versioned Homebrew Cellar folder, and bun gets the two flags before that script. The ONE rule for init (repair it) and doctor (report it). */
 function mcpEntryProblems(e: unknown, { exists = fs.existsSync, which = (c) => Bun.which(c), cwd = process.cwd() }: EntryProbe = {}): string[] {
   if (!isRecord(e) || typeof e.command !== "string" || e.command === "") return ["it has no `command`"];
   const command = e.command;
@@ -142,6 +162,7 @@ function mcpEntryProblems(e: unknown, { exists = fs.existsSync, which = (c) => B
   if (nodeShaped) out.push(`it runs on Node (\`${command}\`) — Design Twin runs on Bun only`);
   const found = /[\\/]/.test(command) ? exists(path.resolve(cwd, command)) : which(command) !== null;
   if (!found) out.push(`its command \`${command}\` ${/[\\/]/.test(command) ? "does not exist" : "is not on PATH"}`);
+  else if (/[\\/]/.test(command)) out.push(...kegProblem("its command", path.resolve(cwd, command)));
   const i = args.findIndex((a) => FIGMA_MCP_SCRIPT.test(a));
   const script = args[i];
   // No server script: the package-runner form (`bunx @design-twin/dtwin mcp`, `bun x @design-twin/dtwin mcp`, an older `npx designtwin
@@ -156,6 +177,7 @@ function mcpEntryProblems(e: unknown, { exists = fs.existsSync, which = (c) => B
   // figma-mcp.js / .mjs (bridge/dist, or the older bridge/figma-mcp.mjs) is the Node-era build: the package ships .ts now
   if (/\.m?js$/.test(script)) out.push(`it points at the old Node build (${script})`);
   else if (!exists(abs)) out.push(`its server script ${script} does not exist`);
+  else out.push(...kegProblem("its server script", abs));
   const cache = bunxCacheOf(abs);
   if (cache) out.push(`its server script is in a bunx cache (${cache}) that Bun replaces or deletes on its own`);
   if (!nodeShaped) {
@@ -367,7 +389,9 @@ function main(argv: string[]): void {
   // ran init is one this package is known to work with, spelt the way that survives its upgrades
   // (stableBunPath). The flags are the shebang's (figma-pull.ts): no auto-install from the network, and
   // the project's .env stays out of the server's environment.
-  const mcpEntry: McpEntry = { command: stableBunPath(), args: [...BUN_FLAGS, path.join(import.meta.dirname, "figma-mcp.ts")] };
+  // Under Homebrew this file runs from a versioned Cellar folder, so the directory is spelt through opt (stableKegPath).
+  const here = stableKegPath(import.meta.dirname);
+  const mcpEntry: McpEntry = { command: stableBunPath(), args: [...BUN_FLAGS, path.join(here, "figma-mcp.ts")] };
   // Run through `bunx @design-twin/dtwin init`: this very file is in bunx's cache, so no entry may point at it.
   const cache = bunxCacheOf(import.meta.dirname);
   const refuseMcp = cache ? bunxRefusal(cache) : undefined;
@@ -378,7 +402,8 @@ function main(argv: string[]): void {
 
   // The Figma plugin's manifest: a repo checkout's (bridge/src/ -> ../../figma-plugin/), else the copy the npm
   // package carries (../figma-plugin/, put there by bridge/pack.ts). Neither: the step names the repo instead.
-  const manifest = [path.join(import.meta.dirname, "..", "..", "figma-plugin", "manifest.json"), path.join(import.meta.dirname, "..", "figma-plugin", "manifest.json")].find((m) => fs.existsSync(m));
+  // Spelt from `here` too: Figma remembers the path a plugin was imported from, and a Cellar one is gone after an upgrade.
+  const manifest = [path.join(here, "..", "..", "figma-plugin", "manifest.json"), path.join(here, "..", "figma-plugin", "manifest.json")].find((m) => fs.existsSync(m));
   // Step 3 is already done for anyone who reached init THROUGH the installed plugin's help skill —
   // which is the documented path. Claude Code records installed plugins under ~/.claude; when the
   // marker is there, saying "install the plugin" is noise at best and confusing at worst.
@@ -421,4 +446,4 @@ function main(argv: string[]): void {
   );
 }
 
-export { detectProfile, plan, apply, main, isOurMcpEntry, mcpEntryProblems, stableBunPath, bunxCacheOf, readMcpJson, usesTailwind, usesVite };
+export { detectProfile, plan, apply, main, isOurMcpEntry, mcpEntryProblems, stableBunPath, stableKegPath, bunxCacheOf, readMcpJson, usesTailwind, usesVite };