@design-twin/dtwin 0.1.0 → 0.1.2

package/README.md

@@ -14,9 +14,18 @@ the package, `@design-twin/dtwin`, from npm:
 bun add -g @design-twin/dtwin   # puts `dtwin` in ~/.bun/bin (on your PATH via the Bun installer)
 ```
 `npm i -g @design-twin/dtwin` installs the same thing, but `dtwin` still runs on Bun: without Bun on PATH it stops at
-`env: bun: No such file or directory`. The package also carries the built Figma plugin (`figma-plugin/manifest.json`
-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/`).
+`env: bun: No such file or directory`. The package also carries the built Figma plugin, which `dtwin plugin install`
+(or `dtwin init`) copies to a per-user folder for you to import once — see [The Figma plugin: `dtwin plugin`](#the-figma-plugin-dtwin-plugin) —
+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) are spelt through `$(brew --prefix)/opt/dtwin/…`, which
+survives an upgrade — not the versioned `Cellar/dtwin/<version>/` folder the next `brew upgrade` deletes. The Figma
+plugin is imported from its per-user copy (`dtwin plugin`), which `brew upgrade` leaves where it is.
 
 Or from a clone (to work on the code):
 ```
@@ -35,11 +44,13 @@ The plugin manifest allows the bridge in **both** dev and published builds
 (`allowedDomains: ws://localhost:{8787,8788,8789}`). Those three ports are the only ones the plugin can dial — `FIGMA_BRIDGE_PORT` is
 validated against them and exits rather than binding a port nothing could ever reach.
 
-> **Re-import the plugin after its manifest changes — required for library reads.** The manifest declares
-> `"permissions": ["teamlibrary"]`, without which Figma denies the team-library APIs. A plugin
-> imported from an older manifest keeps running happily and simply returns **no libraries** — a silent
-> empty result, not an error. If `--list-libraries` / `figma_list_libraries` shows nothing, re-import
-> `figma-plugin/manifest.json` (Plugins → Development → Import plugin from manifest…) first.
+> **Library reads need the manifest's permission.** The manifest declares `"permissions": ["teamlibrary"]`,
+> without which Figma denies the team-library APIs. A plugin still running an older manifest keeps working
+> and simply returns **no libraries** — a silent empty result, not an error. If `--list-libraries` /
+> `figma_list_libraries` shows nothing, turn on Plugins → Development → **Hot reload plugin** and reopen the plugin;
+> if it is still empty, re-import the manifest `dtwin plugin path` prints (Plugins → Development → Import plugin from
+> manifest…). Updates need no re-import: `dtwin plugin update` (or any dtwin that starts a bridge) replaces the files
+> in place, and with hot reload on, reopening the plugin runs them — a changed manifest's permissions included.
 
 **Languages:** the whole bridge is **TypeScript** (ESM) under `src/` — `figma-pull.ts` (read CLI),
 `server-core.ts` (WS core), `figma-mcp.ts` (MCP server), and the modules they share. From a checkout,
@@ -182,7 +193,7 @@ README documents the flags, and either spelling is fine everywhere:
 | `dtwin serve` · `stop` · `status` | `--serve` · `--stop` · `--daemon-status` |
 | `dtwin token` · `token show` · `token rotate` · `token forget` | `--token-status` · `--show-token` · `--rotate-token` · `--forget-token` |
 | `dtwin help` | `--help` |
-| `dtwin doctor` · `dtwin init` · `dtwin mcp` · `dtwin seed` | their own entry points (no flag form) |
+| `dtwin doctor` · `dtwin init` · `dtwin mcp` · `dtwin seed` · `dtwin plugin` | their own entry points (no flag form) |
 
 Every verb has its own page: `dtwin <verb> --help` (e.g. `dtwin whoami --help`, `dtwin serve --help`) prints
 that verb's flags and exits without starting a bridge. `outDir` is **positional** (`dtwin pull my-dir`):
@@ -196,6 +207,38 @@ With no outDir the export lands in `design/export` — the only place doctor, cr
 build-screen read. Never pull into bare `design`: that writes a second, parallel export tree beside
 `design/export/` (dtwin warns when it sees one).
 
+## The Figma plugin: `dtwin plugin`
+
+The plugin is not on Figma Community; it is imported into Figma **desktop** as a development plugin (Plugins →
+Development → Import plugin from manifest…). Figma remembers the manifest's path, so the folder must not move — and a
+path inside the npm package does (Bun's and npm's
+global folders differ, a Node version manager gives each Node its own, a `bunx` cache comes and goes, an uninstall
+deletes it). So the package's plugin is copied to one per-user folder, beside the bridge token, and imported from there
+once:
+
+```
+dtwin plugin install     # copy it to <config dir>/figma-plugin and print the one-time import step (--open shows it)
+dtwin plugin update      # the same, then says to reopen the plugin (and when the manifest changed too)
+dtwin plugin status      # (default) installed where, and is it this dtwin's? (--json)
+dtwin plugin path        # the manifest to import, on stdout
+dtwin plugin uninstall   # remove the copied files (then remove the plugin in Figma: Plugins → Manage plugins)
+```
+
+`<config dir>` is the bridge token's: `~/.config/design-twin` (or `$XDG_CONFIG_HOME/design-twin`), `%APPDATA%\design-twin`
+on Windows, `DESIGNTWIN_CONFIG_DIR` overriding both. The folder is hidden in a file picker: on macOS press ⌘⇧G and paste
+the path; on Windows paste it into the File name box. `dtwin init` installs (or refreshes) the copy and prints the same
+step. Install writes only the files that differ, each one atomically, under a lock, and is safe to run any number of times.
+
+**Updates need no command.** Once a copy is installed, every `dtwin` that starts a bridge (a command, `dtwin serve`, the
+MCP server) first brings it up to its own package's files, so after `bun add -g @design-twin/dtwin@latest` you only
+reopen the plugin — with Plugins → Development → **Hot reload plugin** on. With it on, reopening runs the replaced
+`code.js` / `ui.html` and picks up a changed manifest's permissions too (seen in Figma desktop 126); with it off, Figma
+kept running the code it had already loaded. An update whose manifest changed says so, with re-importing as the
+fallback if a new permission still does not work. Nothing is created that you did not
+install, the network is never touched, and a `dtwin` running from a **repo checkout** never refreshes the copy —
+developers import `figma-plugin/manifest.json` from the checkout itself (`dtwin plugin path` prints that one there).
+`dtwin doctor` reports the copy as its "Plugin files" line.
+
 ## Seed the component map from Code Connect: `dtwin seed`
 
 If the project you are building already has Code Connect files, they are the Figma-component →
@@ -811,13 +854,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" } : {}
         };
       }
     }
@@ -4001,9 +4069,11 @@
             // freshly reloaded one, since neither startedAt nor code.js's mtime can. Reused verbatim by
             // the `hello` announcement below (main.ts's get-identity -> ui.html -> bridge), so `whoami`,
             // `dtwin list clients` and `dtwin doctor` can never disagree about which build is running.
-            pluginVersion: "0.1.0",
+            pluginVersion: "0.1.2",
             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.2",
   "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/bridge-holder.ts

@@ -30,6 +30,7 @@ import { commitToken, daemonAddressOf, humanMs } from "./settings.ts";
 import type { BridgeSettings } from "./settings.ts";
 import type { Bridge, BridgeOptions } from "./server-core.ts";
 import { errMsg } from "./errmsg.ts";
+import { refreshInstalledPlugin } from "./plugin-install.ts";
 
 export type Lifetime = "one-shot" | "serve" | "session";
 
@@ -131,6 +132,9 @@ export function bridgeHolder(lifetime: Lifetime, deps: HolderDeps): Holder {
       settings = c.settings;
       for (const line of c.notice) log(line);
     }
+    // About to hold the bridge, so no plugin is connected to this process yet: the moment to bring an installed
+    // per-user copy of the plugin up to this package's (plugin-install.ts — once per process, never from a checkout).
+    refreshInstalledPlugin(log);
     let failed: (e: Error) => void = () => {};
     const bindFailed = new Promise<never>((_, reject) => { failed = reject; });
     const b = deps.createBridge(settings, survive ? { onListenError: (e) => failed(e) } : {});

package/src/cli-commands.ts

@@ -407,6 +407,7 @@ export const VERB_ROWS = [
   { word: "doctor", to: "routed", usage: "  dtwin doctor [--wait N] [--json]         # diagnose the setup; changes nothing. See doctor --help" },
   { word: "init", to: "routed", usage: "  dtwin init [--mcp] [--dry-run]           # set up the project you are building. See init --help" },
   { word: "seed", to: "routed", usage: "  dtwin seed [codeRoot] [outDir]           # components.json from your Code Connect files. See seed --help", help: SEED_HELP },
+  { word: "plugin", to: "routed", usage: "  dtwin plugin [install|update|status|path] # the Figma plugin's per-user copy, to import once. See plugin --help" },
   { word: "mcp", to: "routed", usage: "  dtwin mcp                                # run the MCP server (what .mcp.json points at). See mcp --help", help: MCP_HELP },
   { word: "help", to: "--help", usage: "  dtwin help                               = --help" },
   {

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/doctor.ts

@@ -39,6 +39,8 @@ import { ifDefined } from "./json-util.ts";
 import * as LAYOUT from "./project-layout.ts";
 import { isOurMcpEntry, mcpEntryProblems, PROFILES, readMcpJson } from "./init.ts";
 import { daemonRowStalenessNote } from "./staleness.ts";
+import { describeState, pluginState } from "./plugin-install.ts";
+import type { PluginState } from "./plugin-install.ts";
 // The manifest's allowedDomains ports and the FIGMA_BRIDGE_PORT parse — ports.ts, the same list and
 // parse settings.ts reads the port with. A bad value is a finding here (the very case this exists to diagnose).
 import { ALLOWED_PORTS, parsePortEnv } from "./ports.ts";
@@ -51,7 +53,7 @@ import { exitCli } from "./stdio.ts";
 import { daemonAddressOf, readSettings, tokenSetting } from "./settings.ts";
 
 /** Every check this report can carry, by id — what `--json` consumers key on. */
-export type CheckId = "bun" | "token" | "daemon" | "port" | "plugin" | "project" | "profile" | "layout" | "export" | "map" | "mcp";
+export type CheckId = "bun" | "token" | "daemon" | "port" | "plugin" | "plugin-files" | "project" | "profile" | "layout" | "export" | "map" | "mcp";
 
 /** One line of the report. `next` is the single next step (absent, or undefined, when there is none). `skipped`: the
  *  check could not run (a warn), so nothing it would have verified was — the report is not ok beside one. */
@@ -327,6 +329,14 @@ function exportChecks(v: ExportVerdict, rel: string): Check[] {
 // custom stack written in design/profile.md), plus design/profile.md read after a bundled profile as the project's own
 // rules. An older project's root profiles/<profile>.md is read the same way.
 export const OVERLAY_FILE = path.join(LAYOUT.DESIGN_DIR, "profile.md");
+// The plugin's files on disk (plugin-install.ts), not the running plugin: is there a per-user copy to import, and is it
+// this dtwin's? Read only — doctor never installs or refreshes it. A note, never a failure: someone who imported from
+// a clone or the package folder before is still working.
+function checkPluginFiles(s: PluginState): Check {
+  const d = describeState(s);
+  return d.ok ? ok("plugin-files", "Plugin files", d.detail) : warn("plugin-files", "Plugin files", d.detail, d.next);
+}
+
 function checkProfile(cwd: string): Check {
   let profile: string | null = null;
   try {
@@ -549,6 +559,7 @@ async function run({ cwd = process.cwd(), waitSec = 10, onCheck, onWait }: RunOp
     }
   }
   if (tok.shadowed) add(checkToken(tok, pluginCheck, viaDaemon));
+  add(checkPluginFiles(pluginState()));
 
   add(...checkProject(cwd));
   return { ok: reportOk(checks), checks };
@@ -599,4 +610,4 @@ async function main(argv: string[]): Promise<void> {
   process.exitCode = report.ok ? 0 : 1;
 }
 
-export { checkBun, checkToken, checkDaemon, sharedTokenNote, resolvePort, ephemeralPortWarning, checkPort, checkPlugin, checkProject, exportChecks, reportOk, probePort, probePlugin, run, main };
+export { checkBun, checkToken, checkDaemon, sharedTokenNote, resolvePort, ephemeralPortWarning, checkPort, checkPlugin, checkPluginFiles, checkProject, exportChecks, reportOk, probePort, probePlugin, run, main };

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)"));
@@ -1141,6 +1146,7 @@ const ROUTES = {
   init: async (args) => { (await import("./init.ts")).main(args); },
   doctor: async (args) => { await (await import("./doctor.ts")).main(args); },
   seed: async (args) => { (await import("./seed-components.ts")).main(args); },
+  plugin: async (args) => { (await import("./plugin-install.ts")).main(args); },
 } satisfies Record<RoutedVerb, (args: string[]) => Promise<void>>;
 const routed = (word: string | undefined): word is RoutedVerb => word !== undefined && Object.hasOwn(ROUTES, word);
 
@@ -1172,7 +1178,7 @@ async function runMcp(args: string[]): Promise<void> {
 // first, then --version/--help, then the arguments are parsed, THEN the settings are read (settings.ts — port, token
 // with --token-file, limits) and the command runs.
 async function cli(argv: string[]): Promise<void> {
-  // `dtwin mcp|init|doctor|seed` — their own entry points, before anything else runs (in particular before
+  // `dtwin mcp|init|doctor|seed|plugin` — their own entry points, before anything else runs (in particular before
   // the settings are read): `dtwin mcp` is taken ONLY when the first argument is exactly "mcp", so `dtwin …` and
   // importing this module from the test suites are untouched, and `bun bridge/src/figma-mcp.ts` still works.
   const word = argv[0];

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).
@@ -31,6 +31,8 @@ import type { ResolvedToken } from "./token-store.ts";
 import * as LAYOUT from "./project-layout.ts";
 import { ifDefined, isRecord } from "./json-util.ts";
 import { exitCli } from "./stdio.ts";
+import { errMsg } from "./errmsg.ts";
+import { hiddenHint, installPlugin, nextSteps, pluginHome, pluginSource } from "./plugin-install.ts";
 
 /** One .mcp.json server entry, as init writes it. */
 export interface McpEntry {
@@ -106,8 +108,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 +144,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 +164,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 +179,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 +391,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;
@@ -376,9 +402,25 @@ function main(argv: string[]): void {
   if (dry) for (const a of actions) log(`${a.kind === "write" ? "would write" : a.kind === "mkdir" ? "would create" : a.kind} ${"path" in a ? a.path + " — " : ""}${a.note}`);
   else apply(cwd, actions, log);
 
-  // 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));
+  // The Figma plugin's manifest: a repo checkout's own figma-plugin/, else the per-user copy (plugin-install.ts),
+  // installed — or refreshed — here from the files the npm package carries, so the path to import never moves.
+  // Neither: the step names the repo instead.
+  const manifest = ((): string | null => {
+    const source = pluginSource();
+    if (!source) return null;
+    if (source.kind === "checkout") return path.join(source.dir, "manifest.json");
+    if (dry) { log(`would install the Figma plugin to ${pluginHome()} (dtwin plugin install)`); return path.join(pluginHome(), "manifest.json"); }
+    try {
+      const r = installPlugin(source);
+      log(`plugin  Figma plugin v${r.version ?? "?"} ${r.status === "current" ? "already up to date" : r.status} at ${r.home}`);
+      if (r.status !== "installed") for (const s of nextSteps(r)) log("        " + s);
+      return r.manifest;
+    } catch (e) {
+      log(`warn    could not install the Figma plugin to ${pluginHome()} (${errMsg(e)}); import the package's own copy instead`);
+      // Spelt through opt under Homebrew: Figma remembers the path, and a Cellar one is gone after an upgrade.
+      return path.join(stableKegPath(source.dir), "manifest.json");
+    }
+  })();
   // 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.
@@ -400,7 +442,8 @@ function main(argv: string[]): void {
   })();
 
   const steps = [
-    "In Figma DESKTOP: Plugins → Development → Import plugin from manifest… → " + (manifest ?? "figma-plugin/manifest.json from a clone of the Design Twin repo (this install does not include it)"),
+    "In Figma DESKTOP, once: Plugins → Development → Import plugin from manifest… → " + (manifest ?? "figma-plugin/manifest.json from a clone of the Design Twin repo (this install does not include it)") +
+      (manifest && hiddenHint(manifest) ? ` (${hiddenHint(manifest) ?? ""})` : ""),
     "Run the plugin (Plugins → Development → Design Twin), paste the bridge token into its \"Bridge token\" field, Save:  dtwin --show-token | pbcopy",
   ];
   if (!pluginInstalled) {
@@ -421,4 +464,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 };

package/src/plugin-install.ts

@@ -0,0 +1,285 @@
+// plugin-install.ts — the Figma plugin's per-user copy, and `dtwin plugin install|update|status|path|uninstall`.
+//
+// The plugin cannot be listed on Figma Community, so it is imported as a development plugin: Plugins → Development →
+// Import plugin from manifest…. Figma remembers the manifest's PATH, so the folder it was imported from must not move —
+// and then replacing the files there is the whole update. With Plugins → Development → Hot reload plugin ON,
+// reopening the plugin runs the new code and picks up a changed manifest's permissions too (seen live, Figma
+// desktop 126); with it OFF, Figma kept running the code it had loaded. A path inside the npm package does move (Bun's and npm's global
+// folders differ, a Node version manager gives every Node its own prefix, a bunx cache is replaced whenever Bun likes,
+// an uninstall deletes it), so an install copies the plugin to ONE per-user folder, next to the bridge token:
+// <configDir>/figma-plugin (token-store.ts: ~/.config/design-twin, %APPDATA%\design-twin on Windows,
+// DESIGNTWIN_CONFIG_DIR overriding both). That is the path to import, once.
+//
+// A copy whose manifest.json changed (permissions, networkAccess) says so, with re-importing as the fallback for when
+// reopening does not pick the change up.
+//
+// The copy is refreshed — never created — whenever this process is about to bind a bridge (refreshInstalledPlugin,
+// from bridge-holder.ts): an upgraded package brings its plugin along with no command to remember, and at that moment
+// no plugin is connected to this process, so no export of ours is mid-run when the files change. A dtwin running from
+// a repo checkout never refreshes it: a developer imports figma-plugin/ itself, and their copy is theirs.
+//
+// Each file is written atomically (atomic-write.ts: a tmp file and a rename — the folder itself is never swapped,
+// since the path Figma holds must stay the one it imported), ui.html and code.js before manifest.json, install.json
+// last, all under one lock (file-lock.ts), so two processes refreshing at once write each file once and a reader
+// never sees half a file.
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { writeFileAtomic } from "./atomic-write.ts";
+import { errMsg } from "./errmsg.ts";
+import { withFileLock } from "./file-lock.ts";
+import { sha256Hex } from "./hash.ts";
+import { BRIDGE_VERSION } from "./staleness.ts";
+import { exitCli } from "./stdio.ts";
+import { configDir } from "./token-store.ts";
+
+/** The files Figma loads: the manifest and the two it names (bridge/pack.ts ships exactly these). */
+export const PLUGIN_FILES = ["manifest.json", "code.js", "ui.html"] as const;
+type PluginFile = (typeof PLUGIN_FILES)[number];
+// The manifest last: a manifest that names code.js / ui.html is never on disk before they are.
+const WRITE_ORDER: readonly PluginFile[] = ["ui.html", "code.js", "manifest.json"];
+const RECORD = "install.json";
+
+/** Where the plugin is installed for this user: <configDir>/figma-plugin. */
+export const pluginHome = (): string => path.join(configDir(), "figma-plugin");
+const lockOf = (home: string): string => home + ".lock";
+
+/** Where this dtwin's plugin files are: a repo checkout's figma-plugin/ (bridge/src/ → ../../figma-plugin/, told
+ *  apart by the ui.template.html no package ships), else the copy the npm package carries (../figma-plugin/,
+ *  bridge/pack.ts). null: neither (a package packed without it). */
+export interface PluginSource { dir: string; kind: "checkout" | "package" }
+export function pluginSource(here: string = import.meta.dirname): PluginSource | null {
+  const checkout = path.join(here, "..", "..", "figma-plugin");
+  if (fs.existsSync(path.join(checkout, "ui.template.html")) && fs.existsSync(path.join(checkout, "manifest.json"))) return { dir: checkout, kind: "checkout" };
+  const packaged = path.join(here, "..", "figma-plugin");
+  if (PLUGIN_FILES.every((f) => fs.existsSync(path.join(packaged, f)))) return { dir: packaged, kind: "package" };
+  return null;
+}
+
+/** What install.json records: the version installed, each file's sha256, from where, when. */
+export interface InstallRecord { version: string | null; files: Record<string, string>; from: PluginSource["kind"]; installedAt: string }
+
+function readRecord(home: string): InstallRecord | null {
+  try {
+    const r: unknown = JSON.parse(fs.readFileSync(path.join(home, RECORD), "utf8"));
+    if (typeof r !== "object" || r === null || !("files" in r) || typeof r.files !== "object" || r.files === null) return null;
+    return r as InstallRecord; // shape checked above; every other field is only printed
+  } catch { return null; }
+}
+const shaOf = (file: string): string | null => {
+  try { return sha256Hex(fs.readFileSync(file)); } catch { return null; }
+};
+const shas = (dir: string): Record<PluginFile, string | null> =>
+  Object.fromEntries(PLUGIN_FILES.map((f) => [f, shaOf(path.join(dir, f))])) as Record<PluginFile, string | null>;
+
+/** The per-user copy as it is now, against this dtwin's own plugin files. */
+export interface PluginState {
+  home: string;
+  /** the manifest to import into Figma: the checkout's own when this dtwin runs from one, else the installed copy's */
+  importPath: string;
+  source: PluginSource | null;
+  /** every plugin file is in the home folder */
+  installed: boolean;
+  record: InstallRecord | null;
+  /** the installed files are byte-for-byte this dtwin's (null: not installed, or nothing to compare with) */
+  current: boolean | null;
+}
+export function pluginState(source: PluginSource | null = pluginSource(), home: string = pluginHome()): PluginState {
+  const have = shas(home);
+  const installed = PLUGIN_FILES.every((f) => have[f] !== null);
+  const want = source ? shas(source.dir) : null;
+  const current = installed && want ? PLUGIN_FILES.every((f) => have[f] === want[f]) : null;
+  const importPath = source?.kind === "checkout" ? path.join(source.dir, "manifest.json") : path.join(home, "manifest.json");
+  return { home, importPath, source, installed, record: readRecord(home), current };
+}
+
+export interface InstallResult {
+  status: "installed" | "updated" | "current";
+  home: string;
+  manifest: string;
+  version: string | null;
+  /** the files rewritten, in the order written */
+  written: PluginFile[];
+  /** an earlier copy's manifest.json differed (permissions / network access): if reopening does not pick it up, re-import */
+  manifestChanged: boolean;
+}
+
+/** Copy `source`'s plugin files into `home`, writing only the ones that differ. Idempotent: an up-to-date copy is
+ *  left untouched ("current"). */
+export function installPlugin(source: PluginSource, home: string = pluginHome(), now: () => Date = () => new Date()): InstallResult {
+  fs.mkdirSync(path.dirname(home), { recursive: true });
+  return withFileLock(lockOf(home), () => {
+    const have = shas(home);
+    const fresh = !PLUGIN_FILES.some((f) => have[f] !== null);
+    const bytes = Object.fromEntries(PLUGIN_FILES.map((f) => [f, fs.readFileSync(path.join(source.dir, f))])) as Record<PluginFile, Buffer>;
+    const want = Object.fromEntries(PLUGIN_FILES.map((f) => [f, sha256Hex(bytes[f])])) as Record<PluginFile, string>;
+    const written = WRITE_ORDER.filter((f) => have[f] !== want[f]);
+    for (const f of written) writeFileAtomic(path.join(home, f), bytes[f]);
+    const record = readRecord(home);
+    const recordStale = !record || record.version !== BRIDGE_VERSION || PLUGIN_FILES.some((f) => record.files[f] !== want[f]);
+    if (written.length || recordStale) {
+      const next: InstallRecord = { version: BRIDGE_VERSION, files: want, from: source.kind, installedAt: now().toISOString() };
+      writeFileAtomic(path.join(home, RECORD), JSON.stringify(next, null, 2) + "\n");
+    }
+    return {
+      status: fresh ? "installed" : written.length ? "updated" : "current",
+      home,
+      manifest: path.join(home, "manifest.json"),
+      version: BRIDGE_VERSION,
+      written,
+      manifestChanged: !fresh && have["manifest.json"] !== null && have["manifest.json"] !== want["manifest.json"],
+    };
+  });
+}
+
+/** Remove the files an install wrote (and the folder, once empty). Anything else in it is left alone. */
+export function uninstallPlugin(home: string = pluginHome()): string[] {
+  if (!fs.existsSync(home)) return [];
+  return withFileLock(lockOf(home), () => {
+    const removed: string[] = [];
+    for (const f of [...PLUGIN_FILES, RECORD]) {
+      const p = path.join(home, f);
+      if (fs.existsSync(p)) { fs.rmSync(p, { force: true }); removed.push(f); }
+    }
+    try { fs.rmdirSync(home); } catch { /* not empty, or gone: left as it is */ }
+    return removed;
+  });
+}
+
+// Reopening runs replaced files only while Figma's hot reload is on; with it off, Figma kept the old code.
+const REOPEN = "reopen the plugin in Figma (Plugins → Development → Design Twin) with Plugins → Development → Hot reload plugin on, to run the new code";
+const importStep = (manifest: string): string => "Plugins → Development → Import plugin from manifest… → " + manifest;
+/** The manifest's folder is hidden in a file picker (a dot folder, or AppData on Windows): how to get there anyway. */
+export function hiddenHint(manifest: string): string | null {
+  if (process.platform === "darwin" && manifest.split(path.sep).some((s) => s.startsWith("."))) return "the folder is hidden in Finder: in the file picker press ⌘⇧G and paste the path";
+  if (process.platform === "win32") return "the folder is hidden in Explorer: paste the path into the file picker's File name box";
+  return null;
+}
+/** What to do in Figma after an install, an update or nothing (empty: nothing to do). */
+export function nextSteps(r: InstallResult): string[] {
+  if (r.status === "installed") {
+    const hint = hiddenHint(r.manifest);
+    return ["once, in Figma DESKTOP: " + importStep(r.manifest), ...(hint ? [hint] : []),
+      "imported the plugin from somewhere else before (a clone, the package folder)? Remove that one: Plugins → Manage plugins"];
+  }
+  if (r.manifestChanged) return [REOPEN + "; its manifest (permissions / network access) changed too — if a new permission still does not work, re-import once: " + importStep(r.manifest)];
+  if (r.status === "updated") return [REOPEN + " — no re-import needed"];
+  return [];
+}
+
+let refreshed = false;
+/** Bring an EXISTING per-user copy up to this dtwin's plugin files — once per process, never from a checkout, never
+ *  creating one. Failures are logged, never thrown: a refresh must not stop a bridge from starting. */
+export function refreshInstalledPlugin(log: (m: string) => void, source: PluginSource | null = pluginSource(), home: string = pluginHome()): InstallResult | null {
+  if (refreshed) return null;
+  refreshed = true;
+  if (source?.kind !== "package" || !fs.existsSync(path.join(home, RECORD))) return null;
+  try {
+    const r = installPlugin(source, home);
+    if (r.status !== "current") log(`updated the Figma plugin at ${home} to v${r.version ?? "?"} — ` + (nextSteps(r)[0] ?? ""));
+    return r;
+  } catch (e) {
+    log(`could not refresh the Figma plugin at ${home}: ${errMsg(e)} — run \`dtwin plugin update\``);
+    return null;
+  }
+}
+/** Test seam: let refreshInstalledPlugin run again in this process. */
+export const resetRefreshForTests = (): void => { refreshed = false; };
+
+/** One line on the state, for `dtwin plugin status` and doctor. */
+export function describeState(s: PluginState): { ok: boolean; detail: string; next?: string } {
+  if (s.source?.kind === "checkout") return { ok: true, detail: `this dtwin runs from a repo checkout — import ${s.importPath} itself (the per-user copy is not refreshed from here)` };
+  if (!s.installed) {
+    if (!s.source) return { ok: false, detail: "this dtwin carries no Figma plugin files", next: "reinstall it: bun add -g @design-twin/dtwin" };
+    return { ok: false, detail: `not installed in ${s.home}`, next: `dtwin plugin install, then (once) in Figma DESKTOP: ${importStep(s.importPath)}` };
+  }
+  const v = s.record?.version ? `v${s.record.version} ` : "";
+  if (s.current === false) return { ok: false, detail: `${v}at ${s.home} differs from this dtwin's (v${BRIDGE_VERSION ?? "?"})`, next: "dtwin plugin update" };
+  return { ok: true, detail: `${v}installed at ${s.home} — import ${s.importPath}` };
+}
+
+function reveal(manifest: string): void {
+  const [cmd, args] = process.platform === "darwin" ? ["open", ["-R", manifest]]
+    : process.platform === "win32" ? ["explorer", ["/select," + manifest]]
+    : ["xdg-open", [path.dirname(manifest)]];
+  try {
+    const p = spawn(cmd, args, { stdio: "ignore", detached: true });
+    p.on("error", () => { /* no file manager: the path is printed anyway */ });
+    p.unref();
+  } catch { /* the path is printed anyway */ }
+}
+
+export const PLUGIN_HELP =
+  "dtwin plugin [install|update|status|path|uninstall] [--json] [--open]\n\n" +
+  "  The Figma plugin is imported into Figma DESKTOP as a development plugin, from a folder that must not move.\n" +
+  "  install    copy this dtwin's plugin to a per-user folder (" + path.join("<config dir>", "figma-plugin") + ", beside the bridge\n" +
+  "             token; DESIGNTWIN_CONFIG_DIR moves it) and print the one-time import step. Writes only what differs.\n" +
+  "  update     the same, then says to reopen the plugin (with Plugins → Development → Hot reload plugin on)\n" +
+  "  status     (default) where it is installed, and whether it matches this dtwin\n" +
+  "  path       print the manifest to import (stdout): a checkout's own figma-plugin/manifest.json, else the copy's\n" +
+  "  uninstall  remove the copied files (then remove the plugin in Figma: Plugins → Manage plugins)\n\n" +
+  "  --json     machine output on stdout\n" +
+  "  --open     show the manifest in Finder / Explorer (install, update, path)\n\n" +
+  "  Once installed, the copy is kept current by itself: every dtwin that starts a bridge refreshes it from its own\n" +
+  "  package, so after upgrading @design-twin/dtwin you only reopen the plugin (hot reload on). Never from a checkout.\n" +
+  "  Needs no bridge, no plugin and no token; never touches the network.";
+
+const SUBS = ["install", "update", "status", "path", "uninstall"] as const;
+type Sub = (typeof SUBS)[number];
+const isSub = (s: string | undefined): s is Sub => SUBS.some((x) => x === s);
+
+export function main(argv: string[]): void {
+  if (argv.includes("--help") || argv.includes("-h")) { console.log(PLUGIN_HELP); exitCli(0); }
+  const json = argv.includes("--json"), open = argv.includes("--open");
+  const rest = argv.filter((a) => a !== "--json" && a !== "--open");
+  const word = rest[0] ?? "status";
+  if (!isSub(word) || rest.length > 1) {
+    console.error(`[dtwin plugin] error: unknown \`dtwin plugin ${rest.join(" ")}\` — use: dtwin plugin [${SUBS.join("|")}] [--json] [--open]`);
+    exitCli(1);
+  }
+  const log = (m: string): void => console.error("[dtwin plugin] " + m);
+  const source = pluginSource();
+
+  if (word === "status" || word === "path") {
+    const s = pluginState(source);
+    if (word === "path") {
+      console.log(json ? JSON.stringify({ importPath: s.importPath, installed: s.installed || s.source?.kind === "checkout" }) : s.importPath);
+      if (!s.installed && s.source?.kind !== "checkout") log("not installed yet — run `dtwin plugin install`");
+      if (open) reveal(s.importPath);
+      return;
+    }
+    const d = describeState(s);
+    if (json) console.log(JSON.stringify({ ...s, version: BRIDGE_VERSION, ok: d.ok, detail: d.detail, ...(d.next ? { next: d.next } : {}) }, null, 2));
+    else {
+      log(`${d.ok ? "✓" : "!"} ${d.detail}`);
+      if (d.next) log("  → " + d.next);
+    }
+    return;
+  }
+
+  if (word === "uninstall") {
+    const removed = uninstallPlugin();
+    if (json) console.log(JSON.stringify({ home: pluginHome(), removed }));
+    else log(removed.length ? `removed ${removed.join(", ")} from ${pluginHome()} — now remove the plugin in Figma too: Plugins → Manage plugins` : `nothing installed in ${pluginHome()}`);
+    return;
+  }
+
+  if (!source) {
+    log("error: this dtwin carries no Figma plugin files to install — reinstall it: bun add -g @design-twin/dtwin");
+    exitCli(1);
+  }
+  let r: InstallResult;
+  try { r = installPlugin(source); } catch (e) {
+    log(`error: could not install the Figma plugin into ${pluginHome()}: ${errMsg(e)}`);
+    exitCli(1);
+  }
+  const steps = nextSteps(r);
+  if (json) console.log(JSON.stringify({ ...r, next: steps }, null, 2));
+  else {
+    const what = r.status === "current" ? "already up to date" : r.status;
+    log(`✓ Figma plugin v${r.version ?? "?"} ${what} at ${r.home}`);
+    for (const s of steps) log("  → " + s);
+    if (source.kind === "checkout") log("  note: this dtwin runs from a repo checkout — you can import figma-plugin/manifest.json there directly");
+  }
+  if (open) reveal(r.manifest);
+}