dominus-cli 0.6.0 → 2.1.0

package/dist/mcp.js

@@ -1,16 +1,58 @@
 #!/usr/bin/env node
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { z } from 'zod';
-import { WebSocket, WebSocketServer } from 'ws';
+import fs3 from 'fs';
+import path3 from 'path';
+import os from 'os';
 import { EventEmitter } from 'events';
+import { WebSocket, WebSocketServer } from 'ws';
 import { nanoid } from 'nanoid';
-import fs from 'fs';
-import initSqlJs from 'sql.js';
-import path from 'path';
-import os from 'os';
+import { z } from 'zod';
+import { randomUUID, randomBytes, timingSafeEqual, randomInt } from 'crypto';
 
+var DOMINUS_DIR = path3.join(os.homedir(), ".dominus");
+var CONFIG_PATH = path3.join(DOMINUS_DIR, "config.json");
+path3.join(DOMINUS_DIR, "dominus.db");
+path3.join(DOMINUS_DIR, "rules.json");
+var DEFAULTS = {
+  provider: "openai",
+  apiBaseUrl: "",
+  model: "",
+  port: 18088,
+  maxToolIterations: 25,
+  maxVerifyRetries: 3,
+  tokenBudget: 128e3,
+  autoIndex: true,
+  autoLearn: true,
+  userName: "Developer"
+};
+function ensureDir() {
+  if (!fs3.existsSync(DOMINUS_DIR)) {
+    fs3.mkdirSync(DOMINUS_DIR, { recursive: true });
+  }
+}
+function readJson(filePath, defaults) {
+  try {
+    if (fs3.existsSync(filePath)) {
+      const raw = fs3.readFileSync(filePath, "utf-8");
+      return { ...defaults, ...JSON.parse(raw) };
+    }
+  } catch {
+  }
+  return { ...defaults };
+}
+function loadConfig() {
+  ensureDir();
+  return readJson(CONFIG_PATH, DEFAULTS);
+}
+function getDominusDir() {
+  ensureDir();
+  return DOMINUS_DIR;
+}
+var DOMINUS_PROTOCOL_VERSION = 2;
+var MAX_MESSAGE_BYTES = 1024 * 1024;
 var StudioMsg = {
+  HELLO: "studio:hello",
   CONNECTED: "studio:connected",
   DISCONNECTED: "studio:disconnected",
   EXPLORER: "studio:explorer",
@@ -21,421 +63,206 @@ var StudioMsg = {
   SCRIPT_CHANGED: "studio:script:changed",
   RESPONSE: "studio:response",
   REFLECTION: "studio:reflection",
-  TEST_RESULTS: "studio:test:results"
+  TEST_RESULTS: "studio:test:results",
+  PAIRING_REQUIRED: "server:pairing_required",
+  AUTHENTICATED: "server:authenticated",
+  AUTH_REJECTED: "server:auth_rejected"
+};
+var ControllerMsg = {
+  HELLO: "controller:hello",
+  WELCOME: "controller:welcome",
+  RELAY: "controller:relay",
+  TARGET_STATE: "controller:target_state",
+  SET_ACTIVE_CONNECTION: "controller:set_active_connection",
+  LIST_PENDING: "controller:list_pending",
+  APPROVE_CONNECTION: "controller:approve_connection"
 };
 var CliMsg = {
-  GET_EXPLORER: "cli:get:explorer",
-  GET_SCRIPT: "cli:get:script",
-  SET_SCRIPT: "cli:set:script",
-  RUN_CODE: "cli:run",
-  GET_PROPERTIES: "cli:get:properties",
-  GET_DESCENDANTS_PROPERTIES: "cli:get:descendants:properties",
-  SET_PROPERTIES: "cli:set:properties",
-  INSERT_INSTANCE: "cli:insert",
-  DELETE_INSTANCE: "cli:delete",
-  GET_SELECTION: "cli:get:selection",
-  SELECT: "cli:select",
-  SEARCH_SCRIPTS: "cli:search:scripts",
-  GET_OUTPUT: "cli:get:output",
-  RUN_TESTS: "cli:run:tests",
-  EXECUTE_RUN_TEST: "cli:test:run",
-  EXECUTE_PLAY_TEST: "cli:test:play",
-  END_TEST: "cli:test:end",
-  BUILD_UI: "cli:build:ui",
-  GET_REFLECTION: "cli:get:reflection",
-  UPLOAD_ASSET: "cli:upload:asset",
-  SERIALIZE_UI: "cli:serialize:ui",
-  MOVE_INSTANCE: "cli:move:instance",
-  UNDO: "cli:undo",
-  REDO: "cli:redo",
-  BULK_SET_PROPERTIES: "cli:bulk:set:properties",
-  FIND_REPLACE_SCRIPTS: "cli:find:replace:scripts"
+  V2_GET_TREE: "studio:v2:get_tree",
+  V2_INSPECT: "studio:v2:inspect",
+  V2_GET_SELECTION: "studio:v2:get_selection",
+  V2_READ_SCRIPT: "studio:v2:read_script",
+  V2_UPDATE_SCRIPT: "studio:v2:update_script",
+  V2_APPLY: "studio:v2:apply",
+  V2_DELETE: "studio:v2:delete",
+  V2_BUILD_UI: "studio:v2:build_ui",
+  V2_SNAPSHOT_UI: "studio:v2:snapshot_ui",
+  V2_RUN_TEST: "studio:v2:run_test",
+  V2_GET_OUTPUT: "studio:v2:get_output",
+  V2_GET_REFLECTION: "studio:v2:get_reflection"
 };
 function createMessage(type, payload) {
   return { id: nanoid(), type, payload, ts: Date.now() };
 }
 function parseMessage(raw) {
+  if (Buffer.byteLength(raw, "utf8") > MAX_MESSAGE_BYTES) {
+    throw new Error(`WebSocket message exceeds ${MAX_MESSAGE_BYTES} bytes`);
+  }
   try {
-    return JSON.parse(raw);
+    const parsed = JSON.parse(raw);
+    return wsMessageSchema.parse(parsed);
   } catch {
     throw new Error(`Failed to parse WebSocket message: ${raw.slice(0, 100)}`);
   }
 }
 function serializeMessage(msg) {
-  return JSON.stringify(msg);
-}
-
-// src/transport/ws-server.ts
-var DominusServer = class extends EventEmitter {
-  wss = null;
-  /** All connected Studio instances, keyed by placeId (0 for unknown) */
-  studioClients = /* @__PURE__ */ new Map();
-  /** Reverse lookup: ws → placeId */
-  wsToPlaceId = /* @__PURE__ */ new Map();
-  /** Which placeId to target. 0 = auto-select if only one is connected. */
-  activePlaceId = 0;
-  controllers = /* @__PURE__ */ new Set();
-  pendingRequests = /* @__PURE__ */ new Map();
-  relayRequests = /* @__PURE__ */ new Map();
-  port;
-  constructor(port = 18088) {
-    super();
-    this.port = port;
-  }
-  start(maxRetries = 0) {
-    return new Promise((resolve, reject) => {
-      const tryPort = (port, attempt) => {
-        const wss = new WebSocketServer({ port });
-        wss.on("listening", () => {
-          this.wss = wss;
-          this.port = port;
-          this.wss.on("connection", (ws) => this.handleConnection(ws));
-          this.emit("server:started", { port });
-          resolve();
-        });
-        wss.on("error", (err) => {
-          if (err.code === "EADDRINUSE" && attempt < maxRetries) {
-            wss.close();
-            tryPort(port + 1, attempt + 1);
-          } else {
-            this.emit("server:error", err);
-            reject(err);
-          }
-        });
-      };
-      tryPort(this.port, 0);
-    });
-  }
-  handleConnection(ws) {
-    let identified = false;
-    ws.on("message", (raw) => {
-      try {
-        const msg = parseMessage(raw.toString());
-        if (!identified) {
-          if (msg.type === StudioMsg.CONNECTED) {
-            identified = true;
-            this.setStudioClient(ws, msg);
-            return;
-          }
-          if (msg.type === "controller:connect") {
-            identified = true;
-            this.addController(ws);
-            ws.send(serializeMessage(createMessage("controller:welcome", {
-              studioConnected: this.isConnected(),
-              port: this.port,
-              connections: this.listConnections(),
-              activePlaceId: this.activePlaceId
-            })));
-            return;
-          }
-        }
-        if (this.controllers.has(ws)) {
-          this.handleControllerMessage(ws, msg);
-        } else {
-          this.handleStudioMessage(ws, msg);
-        }
-      } catch (err) {
-        this.emit("server:error", err);
-      }
-    });
-    ws.on("close", () => {
-      if (this.controllers.has(ws)) {
-        this.controllers.delete(ws);
-        for (const [id, controllerWs] of this.relayRequests) {
-          if (controllerWs === ws) this.relayRequests.delete(id);
-        }
-      } else {
-        const placeId = this.wsToPlaceId.get(ws);
-        if (placeId !== void 0) {
-          const conn = this.studioClients.get(placeId);
-          this.studioClients.delete(placeId);
-          this.wsToPlaceId.delete(ws);
-          this.emit("studio:disconnected", { placeId, placeName: conn?.placeName });
-          this.broadcastToControllers("studio:disconnected", { placeId, placeName: conn?.placeName });
-          for (const [id, pending] of this.pendingRequests) {
-            clearTimeout(pending.timer);
-            pending.reject(new Error(`Studio disconnected (place ${placeId})`));
-            this.pendingRequests.delete(id);
-          }
-          if (this.activePlaceId === placeId) {
-            this.activePlaceId = 0;
-          }
-        }
-      }
-    });
-    ws.on("error", (err) => {
-      this.emit("server:error", err);
-    });
-  }
-  setStudioClient(ws, msg) {
-    const payload = msg.payload;
-    const placeId = payload.placeId ?? 0;
-    const existing = this.studioClients.get(placeId);
-    if (existing && existing.ws !== ws) {
-      existing.ws.close();
-      this.wsToPlaceId.delete(existing.ws);
-    }
-    const conn = {
-      ws,
-      connectedAt: Date.now(),
-      studioVersion: payload.studioVersion,
-      placeId,
-      placeName: payload.placeName
-    };
-    this.studioClients.set(placeId, conn);
-    this.wsToPlaceId.set(ws, placeId);
-    this.emit("studio:connected", { ...payload, placeId });
-    this.broadcastToControllers("studio:connected", { ...payload, placeId });
-  }
-  addController(ws) {
-    this.controllers.add(ws);
-    this.emit("controller:connected");
-  }
-  broadcastToControllers(type, payload) {
-    const msg = serializeMessage(createMessage(type, payload));
-    for (const ws of this.controllers) {
-      if (ws.readyState === WebSocket.OPEN) {
-        ws.send(msg);
-      }
-    }
-  }
-  handleControllerMessage(controllerWs, msg) {
-    const target = this.resolveTarget();
-    if (!target || target.ws.readyState !== WebSocket.OPEN) {
-      controllerWs.send(serializeMessage({
-        id: msg.id,
-        type: StudioMsg.RESPONSE,
-        payload: { error: this.getTargetError() },
-        ts: Date.now()
-      }));
-      return;
-    }
-    this.relayRequests.set(msg.id, controllerWs);
-    target.ws.send(serializeMessage(msg));
-  }
-  handleStudioMessage(ws, msg) {
-    if (msg.type === StudioMsg.CONNECTED) {
-      const payload = msg.payload;
-      const placeId = this.wsToPlaceId.get(ws);
-      if (placeId !== void 0) {
-        const conn = this.studioClients.get(placeId);
-        if (conn) {
-          conn.studioVersion = payload.studioVersion;
-          conn.placeId = payload.placeId;
-          conn.placeName = payload.placeName;
-        }
-      }
-      this.emit("studio:connected", payload);
-      this.broadcastToControllers("studio:connected", payload);
-      return;
-    }
-    if (msg.type === StudioMsg.RESPONSE) {
-      const controllerWs = this.relayRequests.get(msg.id);
-      if (controllerWs && controllerWs.readyState === WebSocket.OPEN) {
-        controllerWs.send(serializeMessage(msg));
-        this.relayRequests.delete(msg.id);
-        return;
-      }
-      const pending = this.pendingRequests.get(msg.id);
-      if (pending) {
-        clearTimeout(pending.timer);
-        pending.resolve(msg);
-        this.pendingRequests.delete(msg.id);
-      }
-      return;
-    }
-    this.emit(msg.type, msg.payload);
-    this.emit("message", msg);
-    this.broadcastToControllers(msg.type, msg.payload);
-  }
-  /** Resolve which Studio connection to target */
-  resolveTarget() {
-    if (this.studioClients.size === 0) return null;
-    if (this.activePlaceId !== 0) {
-      const conn = this.studioClients.get(this.activePlaceId);
-      if (conn && conn.ws.readyState === WebSocket.OPEN) return conn;
-      return null;
-    }
-    if (this.studioClients.size === 1) {
-      const conn = this.studioClients.values().next().value;
-      if (conn.ws.readyState === WebSocket.OPEN) return conn;
-      return null;
-    }
-    return null;
-  }
-  /** Generate an appropriate error message when no target found */
-  getTargetError() {
-    if (this.studioClients.size === 0) return "No Studio connection";
-    if (this.activePlaceId !== 0) {
-      return `Active place ${this.activePlaceId} is not connected. Use set_active_place or list_connections.`;
-    }
-    const places = [...this.studioClients.values()].map((c) => `${c.placeName ?? "Unknown"} (${c.placeId})`);
-    return `Multiple Studio instances connected: ${places.join(", ")}. Use set_active_place to choose one.`;
-  }
-  sendRequest(type, payload, timeoutMs = 1e4) {
-    return new Promise((resolve, reject) => {
-      const target = this.resolveTarget();
-      if (!target || target.ws.readyState !== WebSocket.OPEN) {
-        reject(new Error(this.getTargetError()));
-        return;
-      }
-      const msg = createMessage(type, payload);
-      const timer = setTimeout(() => {
-        this.pendingRequests.delete(msg.id);
-        reject(new Error(`Request timed out: ${type}`));
-      }, timeoutMs);
-      this.pendingRequests.set(msg.id, {
-        resolve,
-        reject,
-        timer
-      });
-      target.ws.send(serializeMessage(msg));
-    });
-  }
-  sendNotification(type, payload) {
-    const target = this.resolveTarget();
-    if (!target || target.ws.readyState !== WebSocket.OPEN) return;
-    const msg = createMessage(type, payload);
-    target.ws.send(serializeMessage(msg));
-  }
-  isConnected() {
-    return this.resolveTarget() !== null;
-  }
-  getConnectionInfo() {
-    return this.resolveTarget();
-  }
-  listConnections() {
-    return [...this.studioClients.values()].filter((c) => c.ws.readyState === WebSocket.OPEN).map((c) => ({
-      placeId: c.placeId ?? 0,
-      placeName: c.placeName,
-      studioVersion: c.studioVersion,
-      connectedAt: c.connectedAt
-    }));
-  }
-  getActivePlaceId() {
-    return this.activePlaceId;
-  }
-  setActivePlaceId(placeId) {
-    this.activePlaceId = placeId;
+  const serialized = JSON.stringify(msg);
+  if (Buffer.byteLength(serialized, "utf8") > MAX_MESSAGE_BYTES) {
+    throw new Error(`WebSocket message exceeds ${MAX_MESSAGE_BYTES} bytes`);
   }
-  getPort() {
-    return this.port;
+  return serialized;
+}
+var wsMessageSchema = z.object({
+  id: z.string().min(1).max(128),
+  type: z.string().min(1).max(128),
+  payload: z.unknown(),
+  ts: z.number().finite()
+}).strict();
+var TOKEN_FILE = "bridge-token";
+function loadOrCreateBridgeToken() {
+  const tokenPath = path3.join(getDominusDir(), TOKEN_FILE);
+  try {
+    const existing = fs3.readFileSync(tokenPath, "utf8").trim();
+    if (existing.length >= 32) return existing;
+  } catch {
   }
-  stop() {
-    return new Promise((resolve) => {
-      for (const conn of this.studioClients.values()) {
-        conn.ws.close();
-      }
-      this.studioClients.clear();
-      this.wsToPlaceId.clear();
-      for (const ws of this.controllers) {
-        ws.close();
-      }
-      this.controllers.clear();
-      for (const [, pending] of this.pendingRequests) {
-        clearTimeout(pending.timer);
-        pending.reject(new Error("Server shutting down"));
-      }
-      this.pendingRequests.clear();
-      this.relayRequests.clear();
-      if (this.wss) {
-        this.wss.close(() => resolve());
-      } else {
-        resolve();
-      }
-    });
+  const token = randomBytes(32).toString("base64url");
+  fs3.writeFileSync(tokenPath, `${token}
+`, { encoding: "utf8", mode: 384 });
+  try {
+    fs3.chmodSync(tokenPath, 384);
+  } catch {
   }
-};
+  return token;
+}
+function tokensEqual(actual, expected) {
+  if (typeof actual !== "string") return false;
+  const actualBuffer = Buffer.from(actual);
+  const expectedBuffer = Buffer.from(expected);
+  return actualBuffer.length === expectedBuffer.length && timingSafeEqual(actualBuffer, expectedBuffer);
+}
+function createPairingCode() {
+  return randomInt(1e5, 1e6).toString();
+}
+
+// src/transport/ws-client.ts
 var DominusClient = class extends EventEmitter {
   ws = null;
   port;
-  studioConnected = false;
+  token;
+  connectTimeoutMs;
   connections = /* @__PURE__ */ new Map();
-  activePlaceId = 0;
+  activeConnectionId = null;
   pendingRequests = /* @__PURE__ */ new Map();
-  constructor(port = 18088) {
+  constructor(port = 18088, options = {}) {
     super();
     this.port = port;
+    this.token = options.token ?? loadOrCreateBridgeToken();
+    this.connectTimeoutMs = options.connectTimeoutMs ?? 8e3;
   }
   connect() {
     return new Promise((resolve, reject) => {
-      const url = `ws://localhost:${this.port}`;
-      const ws = new WebSocket(url);
+      const ws = new WebSocket(`ws://127.0.0.1:${this.port}`, {
+        perMessageDeflate: false,
+        maxPayload: 1024 * 1024
+      });
+      let settled = false;
+      const timer = setTimeout(() => {
+        if (!settled) {
+          settled = true;
+          ws.close(1008, "Dominus controller handshake timed out");
+          reject(new Error("Timed out authenticating with the Dominus bridge"));
+        }
+      }, this.connectTimeoutMs);
       ws.on("open", () => {
         this.ws = ws;
-        ws.send(serializeMessage(createMessage("controller:connect", {})));
-        this.emit("server:started", { port: this.port, relay: true });
-        resolve();
+        ws.send(serializeMessage(createMessage(ControllerMsg.HELLO, {
+          protocolVersion: DOMINUS_PROTOCOL_VERSION,
+          token: this.token
+        })));
       });
       ws.on("message", (raw) => {
         try {
           const msg = parseMessage(raw.toString());
+          if (msg.type === ControllerMsg.WELCOME && !settled) {
+            settled = true;
+            clearTimeout(timer);
+            this.applyWelcome(msg.payload);
+            this.emit("server:started", { port: this.port, relay: true });
+            resolve();
+            return;
+          }
+          if (msg.type === StudioMsg.AUTH_REJECTED && !settled) {
+            settled = true;
+            clearTimeout(timer);
+            const payload = msg.payload;
+            reject(new Error(payload.error ?? "Dominus controller authentication failed"));
+            ws.close(1008, "Controller authentication failed");
+            return;
+          }
           this.handleMessage(msg);
         } catch (err) {
           this.emit("server:error", err);
         }
       });
       ws.on("close", () => {
+        clearTimeout(timer);
         this.ws = null;
-        this.studioConnected = false;
-        this.emit("studio:disconnected");
-        for (const [id, pending] of this.pendingRequests) {
-          clearTimeout(pending.timer);
-          pending.reject(new Error("Relay connection lost"));
-          this.pendingRequests.delete(id);
+        this.connections.clear();
+        this.activeConnectionId = null;
+        if (!settled) {
+          settled = true;
+          reject(new Error("Dominus bridge closed before authentication completed"));
         }
+        this.rejectPending(new Error("Dominus relay connection lost"));
+        this.emit("studio:disconnected");
       });
       ws.on("error", (err) => {
-        if (!this.ws) reject(err);
+        if (!settled) {
+          settled = true;
+          clearTimeout(timer);
+          reject(err);
+        }
         this.emit("server:error", err);
       });
     });
   }
+  applyWelcome(payload) {
+    const welcome = payload;
+    this.replaceConnections(welcome.connections ?? []);
+    this.activeConnectionId = welcome.activeConnectionId ?? null;
+    if (!this.resolveTargetInfo() && this.connections.size === 1) {
+      this.activeConnectionId = this.connections.keys().next().value ?? null;
+    }
+  }
   handleMessage(msg) {
-    if (msg.type === "controller:welcome") {
-      const p = msg.payload;
-      this.studioConnected = p.studioConnected;
-      if (p.connections) {
-        this.connections.clear();
-        for (const c of p.connections) {
-          this.connections.set(c.placeId, {
-            connectedAt: c.connectedAt,
-            studioVersion: c.studioVersion,
-            placeId: c.placeId,
-            placeName: c.placeName
-          });
-        }
-      }
-      if (p.activePlaceId !== void 0) {
-        this.activePlaceId = p.activePlaceId;
+    if (msg.type === ControllerMsg.TARGET_STATE) {
+      const payload = msg.payload;
+      this.replaceConnections(payload.connections ?? []);
+      if (this.activeConnectionId && !this.connections.has(this.activeConnectionId)) {
+        this.activeConnectionId = null;
       }
-      if (this.studioConnected) {
-        this.emit("studio:connected", {});
+      if (!this.activeConnectionId && this.connections.size === 1) {
+        this.activeConnectionId = this.connections.keys().next().value ?? null;
       }
+      this.emit("controller:target_state", payload);
       return;
     }
-    if (msg.type === "studio:connected") {
-      this.studioConnected = true;
-      const payload = msg.payload;
-      const placeId = payload.placeId ?? 0;
-      this.connections.set(placeId, {
-        connectedAt: Date.now(),
-        studioVersion: payload.studioVersion,
-        placeId,
-        placeName: payload.placeName
-      });
-      this.emit("studio:connected", payload);
+    if (msg.type === StudioMsg.CONNECTED) {
+      const connection = msg.payload;
+      this.connections.set(connection.connectionId, toConnectionInfo(connection));
+      if (!this.activeConnectionId && this.connections.size === 1) {
+        this.activeConnectionId = connection.connectionId;
+      }
+      this.emit("studio:connected", connection);
       return;
     }
-    if (msg.type === "studio:disconnected") {
+    if (msg.type === StudioMsg.DISCONNECTED) {
       const payload = msg.payload;
-      const placeId = payload.placeId ?? 0;
-      this.connections.delete(placeId);
-      if (this.connections.size === 0) {
-        this.studioConnected = false;
-      }
-      if (this.activePlaceId === placeId) {
-        this.activePlaceId = 0;
+      if (payload.connectionId) this.connections.delete(payload.connectionId);
+      if (this.activeConnectionId === payload.connectionId) this.activeConnectionId = null;
+      if (!this.activeConnectionId && this.connections.size === 1) {
+        this.activeConnectionId = this.connections.keys().next().value ?? null;
       }
       this.emit("studio:disconnected", payload);
       return;
@@ -444,90 +271,192 @@ var DominusClient = class extends EventEmitter {
       const pending = this.pendingRequests.get(msg.id);
       if (pending) {
         clearTimeout(pending.timer);
-        pending.resolve(msg);
         this.pendingRequests.delete(msg.id);
+        pending.resolve(msg);
       }
       return;
     }
     this.emit(msg.type, msg.payload);
     this.emit("message", msg);
   }
-  sendRequest(type, payload, timeoutMs = 1e4) {
+  replaceConnections(connections) {
+    this.connections.clear();
+    for (const connection of connections) {
+      this.connections.set(connection.connectionId, toConnectionInfo(connection));
+    }
+  }
+  sendMessage(message) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      throw new Error("Not connected to the Dominus bridge");
+    }
+    this.ws.send(serializeMessage(message));
+  }
+  waitForResponse(message, timeoutMs) {
     return new Promise((resolve, reject) => {
-      if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
-        reject(new Error("Not connected to Dominus server"));
-        return;
-      }
-      if (!this.studioConnected) {
-        reject(new Error("Studio not connected"));
-        return;
+      const timer = setTimeout(() => {
+        this.pendingRequests.delete(message.id);
+        reject(new Error(`Dominus request timed out: ${message.type}`));
+      }, timeoutMs);
+      this.pendingRequests.set(message.id, {
+        resolve,
+        reject,
+        timer
+      });
+      try {
+        this.sendMessage(message);
+      } catch (err) {
+        clearTimeout(timer);
+        this.pendingRequests.delete(message.id);
+        reject(err);
       }
-      const msg = createMessage(type, payload);
+    });
+  }
+  async sendControlRequest(type, payload, timeoutMs = 1e4) {
+    const response = await this.waitForResponse(createMessage(type, payload), timeoutMs);
+    const result = response.payload;
+    if (result.error || result.success === false) throw new Error(result.error ?? `${type} failed`);
+    return result;
+  }
+  sendRequest(type, payload, timeoutMs = 15e3) {
+    const target = this.resolveTargetInfo();
+    if (!target || !this.activeConnectionId) {
+      return Promise.reject(new Error(this.connections.size > 1 ? "Multiple Studio sessions are connected. Call dominus_select_studio first." : "No authenticated Roblox Studio connection"));
+    }
+    const request = createMessage(type, payload);
+    const relay = createMessage(ControllerMsg.RELAY, {
+      connectionId: this.activeConnectionId,
+      request
+    });
+    return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
-        this.pendingRequests.delete(msg.id);
-        reject(new Error(`Request timed out: ${type}`));
+        this.pendingRequests.delete(request.id);
+        reject(new Error(`Studio request timed out: ${type}`));
       }, timeoutMs);
-      this.pendingRequests.set(msg.id, {
+      this.pendingRequests.set(request.id, {
         resolve,
         reject,
         timer
       });
-      this.ws.send(serializeMessage(msg));
+      try {
+        this.sendMessage(relay);
+      } catch (err) {
+        clearTimeout(timer);
+        this.pendingRequests.delete(request.id);
+        reject(err);
+      }
     });
   }
   sendNotification(type, payload) {
-    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
-    const msg = createMessage(type, payload);
-    this.ws.send(serializeMessage(msg));
+    if (!this.activeConnectionId) return;
+    const request = createMessage(type, payload);
+    this.sendMessage(createMessage(ControllerMsg.RELAY, {
+      connectionId: this.activeConnectionId,
+      request
+    }));
   }
   isConnected() {
-    return this.studioConnected && this.connections.size > 0;
+    return this.resolveTargetInfo() !== null;
   }
   getConnectionInfo() {
-    if (this.connections.size === 0) return null;
-    const target = this.activePlaceId !== 0 ? this.connections.get(this.activePlaceId) : this.connections.values().next().value;
-    if (!target) return null;
+    const target = this.resolveTargetInfo();
+    if (!target || !this.ws) return null;
     return { ...target, ws: this.ws };
   }
   listConnections() {
-    return [...this.connections.values()].map((c) => ({
-      placeId: c.placeId ?? 0,
-      placeName: c.placeName,
-      studioVersion: c.studioVersion,
-      connectedAt: c.connectedAt
+    return [...this.connections.values()].map((connection) => ({
+      placeId: connection.placeId ?? 0,
+      connectionId: connection.connectionId,
+      clientId: connection.clientId,
+      placeName: connection.placeName,
+      studioVersion: connection.studioVersion,
+      connectedAt: connection.connectedAt,
+      active: connection.connectionId === this.activeConnectionId
     }));
   }
+  async listPendingConnections() {
+    const result = await this.sendControlRequest(
+      ControllerMsg.LIST_PENDING,
+      {}
+    );
+    return result.pending;
+  }
+  async approveConnection(connectionId, pairingCode) {
+    const result = await this.sendControlRequest(
+      ControllerMsg.APPROVE_CONNECTION,
+      { connectionId, pairingCode }
+    );
+    return result.connection;
+  }
+  getActiveConnectionId() {
+    return this.activeConnectionId;
+  }
+  async setActiveConnectionId(connectionId) {
+    if (connectionId && !this.connections.has(connectionId)) {
+      throw new Error(`Studio connection ${connectionId} is not connected`);
+    }
+    await this.sendControlRequest(ControllerMsg.SET_ACTIVE_CONNECTION, { connectionId });
+    this.activeConnectionId = connectionId;
+  }
   getActivePlaceId() {
-    return this.activePlaceId;
+    return this.resolveTargetInfo()?.placeId ?? 0;
   }
   setActivePlaceId(placeId) {
-    this.activePlaceId = placeId;
+    if (placeId === 0) {
+      void this.setActiveConnectionId(null);
+      return;
+    }
+    const matches = [...this.connections.values()].filter((connection) => connection.placeId === placeId);
+    if (matches.length !== 1) {
+      throw new Error(matches.length === 0 ? `Place ${placeId} is not connected` : `Place ${placeId} has multiple Studio sessions; select a connectionId instead`);
+    }
+    void this.setActiveConnectionId(matches[0].connectionId);
+  }
+  resolveTargetInfo() {
+    if (this.activeConnectionId) return this.connections.get(this.activeConnectionId) ?? null;
+    if (this.connections.size === 1) return this.connections.values().next().value ?? null;
+    return null;
   }
   getPort() {
     return this.port;
   }
   stop() {
+    this.rejectPending(new Error("Dominus client is shutting down"));
     return new Promise((resolve) => {
-      for (const [, pending] of this.pendingRequests) {
-        clearTimeout(pending.timer);
-        pending.reject(new Error("Client shutting down"));
+      if (!this.ws) {
+        resolve();
+        return;
       }
-      this.pendingRequests.clear();
-      if (this.ws) {
-        this.ws.close();
-        this.ws = null;
-      }
-      resolve();
+      const ws = this.ws;
+      this.ws = null;
+      ws.once("close", resolve);
+      ws.close(1e3, "Dominus client shutdown");
     });
   }
+  rejectPending(error) {
+    for (const pending of this.pendingRequests.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(error);
+    }
+    this.pendingRequests.clear();
+  }
 };
+function toConnectionInfo(connection) {
+  return {
+    connectedAt: connection.connectedAt,
+    connectionId: connection.connectionId,
+    clientId: connection.clientId,
+    studioVersion: connection.studioVersion,
+    placeId: connection.placeId,
+    placeName: connection.placeName
+  };
+}
 async function isPortInUse(port) {
   return new Promise((resolve) => {
-    const ws = new WebSocket(`ws://localhost:${port}`);
+    const ws = new WebSocket(`ws://127.0.0.1:${port}`);
     const timer = setTimeout(() => {
       ws.close();
       resolve(false);
-    }, 1e3);
+    }, 750);
     ws.on("open", () => {
       clearTimeout(timer);
       ws.close();
@@ -539,999 +468,1300 @@ async function isPortInUse(port) {
     });
   });
 }
-var DOMINUS_DIR = path.join(os.homedir(), ".dominus");
-var CONFIG_PATH = path.join(DOMINUS_DIR, "config.json");
-var DB_PATH = path.join(DOMINUS_DIR, "dominus.db");
-path.join(DOMINUS_DIR, "rules.json");
-var DEFAULTS = {
-  provider: "openai",
-  apiBaseUrl: "",
-  model: "",
-  port: 18088,
-  maxToolIterations: 25,
-  maxVerifyRetries: 3,
-  tokenBudget: 128e3,
-  autoIndex: true,
-  autoLearn: true,
-  userName: "Developer"
-};
-function ensureDir() {
-  if (!fs.existsSync(DOMINUS_DIR)) {
-    fs.mkdirSync(DOMINUS_DIR, { recursive: true });
+var HANDSHAKE_TIMEOUT_MS = 8e3;
+var PAIRING_TTL_MS = 5 * 6e4;
+var RATE_WINDOW_MS = 1e4;
+var RATE_LIMIT = 250;
+var DominusServer = class extends EventEmitter {
+  wss = null;
+  studioClients = /* @__PURE__ */ new Map();
+  wsToConnectionId = /* @__PURE__ */ new Map();
+  pendingConnections = /* @__PURE__ */ new Map();
+  controllers = /* @__PURE__ */ new Set();
+  socketRoles = /* @__PURE__ */ new Map();
+  pendingRequests = /* @__PURE__ */ new Map();
+  relayRequests = /* @__PURE__ */ new Map();
+  rateState = /* @__PURE__ */ new Map();
+  token;
+  host;
+  maxPayloadBytes;
+  handshakeTimeoutMs;
+  activeConnectionId = null;
+  port;
+  constructor(port = 18088, options = {}) {
+    super();
+    this.port = port;
+    this.token = options.token ?? loadOrCreateBridgeToken();
+    this.host = options.host ?? "127.0.0.1";
+    this.maxPayloadBytes = options.maxPayloadBytes ?? MAX_MESSAGE_BYTES;
+    this.handshakeTimeoutMs = options.handshakeTimeoutMs ?? HANDSHAKE_TIMEOUT_MS;
   }
-}
-function readJson(filePath, defaults) {
-  try {
-    if (fs.existsSync(filePath)) {
-      const raw = fs.readFileSync(filePath, "utf-8");
-      return { ...defaults, ...JSON.parse(raw) };
+  start(maxRetries = 0) {
+    return new Promise((resolve, reject) => {
+      const tryPort = (port, attempt) => {
+        const wss = new WebSocketServer({
+          port,
+          host: this.host,
+          maxPayload: this.maxPayloadBytes,
+          perMessageDeflate: false
+        });
+        wss.on("listening", () => {
+          this.wss = wss;
+          this.port = port;
+          wss.on("connection", (ws) => this.handleConnection(ws));
+          this.emit("server:started", { port, host: this.host });
+          resolve();
+        });
+        wss.on("error", (err) => {
+          if (err.code === "EADDRINUSE" && attempt < maxRetries) {
+            wss.close();
+            tryPort(port + 1, attempt + 1);
+            return;
+          }
+          this.emit("server:error", err);
+          reject(err);
+        });
+      };
+      tryPort(this.port, 0);
+    });
+  }
+  handleConnection(ws) {
+    this.socketRoles.set(ws, "unknown");
+    this.rateState.set(ws, { startedAt: Date.now(), count: 0 });
+    const handshakeTimer = setTimeout(() => {
+      if (this.socketRoles.get(ws) === "unknown") {
+        ws.close(1008, "Dominus handshake timed out");
+      }
+    }, this.handshakeTimeoutMs);
+    ws.on("message", (raw) => {
+      try {
+        if (!this.consumeRateBudget(ws) || rawByteLength(raw) > this.maxPayloadBytes) {
+          ws.close(1009, "Dominus message limit exceeded");
+          return;
+        }
+        const msg = parseMessage(raw.toString());
+        const role = this.socketRoles.get(ws) ?? "unknown";
+        if (role === "unknown") {
+          clearTimeout(handshakeTimer);
+          this.handleHandshake(ws, msg);
+        } else if (role === "controller") {
+          this.handleControllerMessage(ws, msg);
+        } else if (role === "studio") {
+          this.handleStudioMessage(ws, msg);
+        }
+      } catch (err) {
+        this.emit("server:error", err);
+        this.sendSafe(ws, createMessage(StudioMsg.AUTH_REJECTED, {
+          error: err instanceof Error ? err.message : String(err)
+        }));
+      }
+    });
+    ws.on("close", () => {
+      clearTimeout(handshakeTimer);
+      this.cleanupSocket(ws);
+    });
+    ws.on("error", (err) => this.emit("server:error", err));
+  }
+  consumeRateBudget(ws) {
+    const now = Date.now();
+    const state = this.rateState.get(ws) ?? { startedAt: now, count: 0 };
+    if (now - state.startedAt >= RATE_WINDOW_MS) {
+      state.startedAt = now;
+      state.count = 0;
     }
-  } catch {
+    state.count += 1;
+    this.rateState.set(ws, state);
+    return state.count <= RATE_LIMIT;
   }
-  return { ...defaults };
-}
-function loadConfig() {
-  ensureDir();
-  return readJson(CONFIG_PATH, DEFAULTS);
-}
-function getDbPath() {
-  ensureDir();
-  return DB_PATH;
-}
-
-// src/memory/store.ts
-var db = null;
-var dbPath;
-var SCHEMA = `
-CREATE TABLE IF NOT EXISTS facts (
-  id          INTEGER PRIMARY KEY AUTOINCREMENT,
-  project_id  TEXT NOT NULL,
-  content     TEXT NOT NULL,
-  category    TEXT NOT NULL,
-  source      TEXT,
-  relevance   REAL DEFAULT 1.0,
-  created_at  INTEGER NOT NULL,
-  accessed_at INTEGER NOT NULL
-);
-
-CREATE TABLE IF NOT EXISTS summaries (
-  id          INTEGER PRIMARY KEY AUTOINCREMENT,
-  project_id  TEXT NOT NULL,
-  session_id  TEXT NOT NULL,
-  summary     TEXT NOT NULL,
-  created_at  INTEGER NOT NULL
-);
-
-CREATE TABLE IF NOT EXISTS messages (
-  id          INTEGER PRIMARY KEY AUTOINCREMENT,
-  session_id  TEXT NOT NULL,
-  role        TEXT NOT NULL,
-  content     TEXT NOT NULL,
-  tool_name   TEXT,
-  created_at  INTEGER NOT NULL
-);
-
-CREATE TABLE IF NOT EXISTS script_index (
-  id          INTEGER PRIMARY KEY AUTOINCREMENT,
-  project_id  TEXT NOT NULL,
-  path        TEXT NOT NULL,
-  class_name  TEXT NOT NULL,
-  summary     TEXT,
-  line_count  INTEGER,
-  last_hash   TEXT,
-  updated_at  INTEGER NOT NULL
-);
-
-CREATE INDEX IF NOT EXISTS idx_facts_project ON facts(project_id);
-CREATE INDEX IF NOT EXISTS idx_facts_category ON facts(project_id, category);
-CREATE INDEX IF NOT EXISTS idx_scripts_project ON script_index(project_id);
-CREATE INDEX IF NOT EXISTS idx_messages_session ON messages(session_id);
-CREATE INDEX IF NOT EXISTS idx_summaries_project ON summaries(project_id);
-`;
-function persist() {
-  if (!db) return;
-  const data = db.export();
-  fs.writeFileSync(dbPath, Buffer.from(data));
-}
-async function initMemoryStore() {
-  if (db) return;
-  dbPath = getDbPath();
-  const SQL = await initSqlJs();
-  if (fs.existsSync(dbPath)) {
-    const buffer = fs.readFileSync(dbPath);
-    db = new SQL.Database(buffer);
-  } else {
-    db = new SQL.Database();
-  }
-  db.run(SCHEMA);
-  persist();
-}
-function getDb() {
-  if (!db) throw new Error("Memory store not initialized. Call initMemoryStore() first.");
-  return db;
-}
-function storeFact(fact) {
-  const d = getDb();
-  d.run(
-    `INSERT INTO facts (project_id, content, category, source, relevance, created_at, accessed_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?)`,
-    [
-      fact.projectId,
-      fact.content,
-      fact.category,
-      fact.source ?? null,
-      fact.relevance,
-      fact.createdAt,
-      fact.accessedAt
-    ]
-  );
-  persist();
-  const stmt = d.prepare("SELECT last_insert_rowid()");
-  stmt.step();
-  const row = stmt.get();
-  stmt.free();
-  return row?.[0] ?? 0;
-}
-function recallFacts(projectId, query, limit = 10) {
-  const d = getDb();
-  const keywords = query.toLowerCase().split(/\s+/).filter((w) => w.length > 2);
-  if (keywords.length === 0) {
-    const result2 = d.exec(
-      `SELECT * FROM facts WHERE project_id = ? ORDER BY relevance DESC, accessed_at DESC LIMIT ?`,
-      [projectId, limit]
-    );
-    return rowsToFacts(result2);
-  }
-  const likeClauses = keywords.map(() => `LOWER(content) LIKE ?`).join(" OR ");
-  const likeParams = keywords.map((k) => `%${k}%`);
-  const result = d.exec(
-    `SELECT * FROM facts WHERE project_id = ? AND (${likeClauses})
-     ORDER BY relevance DESC, accessed_at DESC LIMIT ?`,
-    [projectId, ...likeParams, limit]
-  );
-  const facts = rowsToFacts(result);
-  for (const fact of facts) {
-    if (fact.id) {
-      d.run(`UPDATE facts SET accessed_at = ? WHERE id = ?`, [Date.now(), fact.id]);
+  handleHandshake(ws, msg) {
+    if (msg.type === StudioMsg.HELLO) {
+      const hello = validateStudioHello(msg.payload);
+      if (tokensEqual(hello.token, this.token)) {
+        this.authorizeStudio(ws, hello, randomUUID());
+      } else {
+        this.createPendingStudio(ws, hello);
+      }
+      return;
     }
+    if (msg.type === ControllerMsg.HELLO) {
+      const payload = msg.payload;
+      if (payload.protocolVersion !== DOMINUS_PROTOCOL_VERSION || !tokensEqual(payload.token, this.token)) {
+        this.sendSafe(ws, createMessage(StudioMsg.AUTH_REJECTED, { error: "Invalid Dominus controller credentials" }));
+        ws.close(1008, "Unauthorized controller");
+        return;
+      }
+      this.socketRoles.set(ws, "controller");
+      this.controllers.add(ws);
+      this.sendSafe(ws, createMessage(ControllerMsg.WELCOME, {
+        protocolVersion: DOMINUS_PROTOCOL_VERSION,
+        port: this.port,
+        connections: this.listConnections(),
+        activeConnectionId: this.activeConnectionId
+      }));
+      return;
+    }
+    this.sendSafe(ws, createMessage(StudioMsg.AUTH_REJECTED, {
+      error: `Expected ${StudioMsg.HELLO} or ${ControllerMsg.HELLO}`
+    }));
+    ws.close(1008, "Invalid Dominus handshake");
   }
-  if (facts.length > 0) persist();
-  return facts;
-}
-function rowsToFacts(result) {
-  if (!result[0]) return [];
-  return result[0].values.map((row) => ({
-    id: row[0],
-    projectId: row[1],
-    content: row[2],
-    category: row[3],
-    source: row[4],
-    relevance: row[5],
-    createdAt: row[6],
-    accessedAt: row[7]
-  }));
-}
-function getScriptIndex(projectId) {
-  const d = getDb();
-  const result = d.exec(
-    `SELECT path, summary, class_name FROM script_index WHERE project_id = ? ORDER BY path`,
-    [projectId]
-  );
-  if (!result[0]) return [];
-  return result[0].values.map((row) => ({
-    path: row[0],
-    summary: row[1] || void 0,
-    className: row[2]
-  }));
-}
-
-// src/agent/internal-memory.ts
-var INTERNAL_MEMORY = `## Internal Memory \u2014 Known Quirks & Lessons
-
-These are built-in lessons that ship with Dominus. Follow them exactly.
-
-### create_ui \u2014 property format
-- Each node accepts properties in **either** of two shapes:
-  - **Flattened (preferred)**: props as top-level keys next to \`ClassName\`, \`Name\`, \`Children\`.
-    \`\`\`json
-    { "ClassName": "TextButton", "Name": "Btn", "Text": "OK", "Size": [0, 100, 0, 40] }
-    \`\`\`
-  - **Nested bag**: props grouped under \`properties\` / \`Properties\` / \`props\` / \`Props\`.
-    \`\`\`json
-    { "ClassName": "TextButton", "Name": "Btn",
-      "properties": { "Text": "OK", "Size": [0, 100, 0, 40] } }
-    \`\`\`
-- Do NOT mix a nested \`properties\` bag with flattened props of the same name \u2014 the bag wins.
-- Reserved keys (never treated as instance properties): \`ClassName\`, \`className\`, \`Name\`, \`name\`, \`Children\`, \`children\`, \`properties\`, \`Properties\`, \`props\`, \`Props\`.
-
-### build_multiple \u2014 schema is strict
-- Top-level keys only: \`name\`, \`className\`, \`position\`, \`size\`, \`color\`, \`material\`, \`anchored\`, \`shape\`, \`transparency\`, \`parent\`, \`canCollide\`.
-- Does NOT accept a nested \`properties\` bag. For anything outside those fields use \`insert_instance\` + \`set_properties\`.
-- \`shape\` values: \`Block\`, \`Ball\`, \`Cylinder\`, \`Wedge\`.
-
-### Color formats (accepted everywhere)
-- Hex: \`"#RRGGBB"\`
-- RGB string: \`"rgb(255, 128, 0)"\`
-- BrickColor name: \`"Bright red"\`, \`"Institutional white"\`, \`"Really black"\`, etc.
-- Array: \`[r, g, b]\` (0\u20131 floats) or \`[255, 128, 0]\` (auto-detected if any value > 1)
-
-### UDim2 / UDim / Vector2 / Color3 coercion (create_ui)
-- UDim2: \`[xScale, xOffset, yScale, yOffset]\` or \`{XScale, XOffset, YScale, YOffset}\`.
-- UDim: \`[scale, offset]\` or a plain number (treated as pixels).
-- Vector2 (e.g. \`AnchorPoint\`): \`[x, y]\` or \`{x, y}\`.
-- 2-element arrays are auto-disambiguated by property name (\`AnchorPoint\` \u2192 Vector2, \`CornerRadius\` \u2192 UDim).
-
-### Common GUI property names
-- GUI uses \`Size\`/\`Position\` as **UDim2** \u2014 never Vector3.
-- \`BackgroundColor3\`, \`TextColor3\`, \`BorderColor3\`, \`ImageColor3\` \u2192 Color3.
-- \`Font\` accepts a string enum name like \`"GothamBold"\`, \`"SourceSans"\`.
-- Enum properties take the string name: \`"Center"\`, \`"Left"\`, \`"Fit"\`.
-
-### Tool selection cheat-sheet
-- Single 3D part \u2192 \`create_part\`
-- Many 3D parts (tree, building, vehicle) \u2192 \`build_multiple\` with \`groupName\`
-- Full UI tree \u2192 \`create_ui\` (one call, never loop \`insert_instance\` for UI)
-- **Convert/export existing UI \u2192 \`serialize_ui\`** (NOT get_descendants_properties)
-- Adjusting an existing instance \u2192 \`set_properties\` (not \`run_code\`)
-- **Inspecting user's selection \u2192 \`get_selection\`, then \`get_properties\` or \`serialize_ui\`**
-- **Reading properties \u2192 \`get_properties\` (NEVER \`run_code\` with dump scripts)**
-- **Browsing the tree \u2192 \`get_explorer\`**
-- **Multiple Studios open \u2192 \`list_connections\` to see all, \`set_active_place\` to target one**
-- Anything exotic or procedural \u2192 \`run_code\` as last resort
-
-### NEVER use run_code for:
-- Getting properties of an instance \u2192 use \`get_properties\` or \`serialize_ui\`
-- Dumping selection info \u2192 use \`inspect_selection\` (ONE call does it all)
-- Inspecting an instance + its children \u2192 use \`inspect_instance\`
-- Converting UI to Roact/React \u2192 use \`convert_ui_to_code\`
-- Creating instances \u2192 use \`create_part\`, \`create_ui\`, \`insert_instance\`, \`build_multiple\`
-- Modifying properties \u2192 use \`set_properties\` or \`bulk_set_properties\`
-- Reading scripts \u2192 use \`read_script\`
-- Browsing the explorer \u2192 use \`get_explorer\`
-\`run_code\` is ONLY for procedural logic, terrain generation, raycasts, physics queries, or custom algorithms with no tool equivalent.
-
-### Composite skill tools (prefer these over chaining)
-- \`inspect_selection\` \u2014 Returns paths + compact properties for all selected instances in ONE call. Use when user says "my selection" or "what I selected".
-- \`inspect_instance\` \u2014 Returns compact properties + children tree for a single instance in ONE call. Combines get_properties + get_explorer.
-- \`convert_ui_to_code\` \u2014 Serializes a UI tree and generates a Roact/React component. Use when user says "turn this into a component" or "convert to React".
-
-### Verification habits
-- After a build, call \`get_explorer\` or \`get_selection\` to confirm the tree looks right.
-- After editing a script, read it back.
-- After \`run_code\`, check \`get_output\` for errors.
-
-### serialize_ui \u2014 the RIGHT tool for UI conversion
-- **Use \`serialize_ui\` when converting existing UI to Roact/React/Fusion components.** It returns a minimal JSON tree with only non-default properties, already in JSON-friendly formats.
-- **Do NOT use \`get_descendants_properties\` for UI conversion** \u2014 it returns a flat list with ~50+ properties per instance (including read-only, deprecated, nil, and default values), which bloats context and confuses conversion.
-- \`serialize_ui\` output maps 1:1 to \`create_ui\` input \u2014 you can round-trip UI through it.
-- The tree structure preserves parent-child hierarchy, so Roact/React children mapping is direct.
-
-### UI \u2192 Roact/React conversion cheat-sheet
-- \`serialize_ui\` path \u2192 JSON tree \u2192 map each node to \`Roact.createElement(ClassName, props, childrenDict)\`
-- UDim2 arrays \`[xS, xO, yS, yO]\` \u2192 \`UDim2.new(xS, xO, yS, yO)\`
-- Color3 hex strings \u2192 \`Color3.fromHex("#RRGGBB")\`
-- Vector2 arrays \u2192 \`Vector2.new(x, y)\`
-- UDim arrays \u2192 \`UDim.new(s, o)\`
-- Enum strings like \`"Center"\` \u2192 \`Enum.TextXAlignment.Center\`
-- FontFace \u2192 \`Font.new(family, weight, style)\`
-- UI modifiers (UICorner, UIStroke, UIGradient, UIListLayout, UIPadding) are CHILDREN not props
-- Use instance Name as dictionary key in children table
-`;
-
-// src/mcp/server.ts
-var bridge;
-async function startMcpServer() {
-  const config = loadConfig();
-  await initMemoryStore();
-  const portTaken = await isPortInUse(config.port);
-  if (portTaken) {
-    const client = new DominusClient(config.port);
-    await client.connect();
-    bridge = client;
-  } else {
-    const server = new DominusServer(config.port);
-    await server.start();
-    bridge = server;
+  createPendingStudio(ws, hello) {
+    const connectionId = randomUUID();
+    const requestedAt = Date.now();
+    const pending = {
+      ws,
+      pairingCode: createPairingCode(),
+      hello,
+      info: {
+        connectionId,
+        clientId: hello.clientId,
+        placeId: hello.placeId ?? 0,
+        placeName: hello.placeName,
+        studioVersion: hello.studioVersion,
+        requestedAt,
+        expiresAt: requestedAt + PAIRING_TTL_MS
+      }
+    };
+    this.pendingConnections.set(connectionId, pending);
+    this.socketRoles.set(ws, "pending");
+    this.sendSafe(ws, createMessage(StudioMsg.PAIRING_REQUIRED, {
+      connectionId,
+      pairingCode: pending.pairingCode,
+      expiresAt: pending.info.expiresAt
+    }));
+    this.emit("studio:pairing_required", pending.info);
   }
-  const mcp = new McpServer({
-    name: "dominus",
-    version: "0.6.0"
-  }, {
-    instructions: INTERNAL_MEMORY
-  });
-  function luaStr(s) {
-    return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r")}"`;
-  }
-  function resolvePath(dotPath) {
-    const parts = dotPath.split(".");
-    let r = "game";
-    for (const p of parts) r += `[${luaStr(p)}]`;
-    return r;
-  }
-  function cleanNum(n) {
-    if (Number.isInteger(n)) return String(n);
-    const rounded = Math.round(n * 1e3) / 1e3;
-    return String(rounded);
-  }
-  function generateComponentCode(tree, componentName, framework) {
-    const isReact = framework === "react";
-    const lib = isReact ? "React" : "Roact";
-    const lines = [];
-    lines.push(`local ${lib} = require(game.ReplicatedStorage.Packages.${isReact ? "React" : "Roact"})`);
-    if (isReact) {
-      lines.push(`local e = React.createElement`);
-    } else {
-      lines.push(`local e = Roact.createElement`);
-    }
-    lines.push("");
-    lines.push(`local function ${componentName}()`);
-    lines.push(`	return ${renderNode(tree, 1)}`);
-    lines.push("end");
-    lines.push("");
-    lines.push(`return ${componentName}`);
-    return lines.join("\n");
-  }
-  function renderNode(node, depth) {
-    const indent = "	".repeat(depth);
-    const indent2 = "	".repeat(depth + 1);
-    const className = node.ClassName || "Frame";
-    const children = node.Children || [];
-    node.Name;
-    const props = [];
-    const skipKeys = /* @__PURE__ */ new Set(["ClassName", "Name", "Children", "className", "name", "children"]);
-    for (const [key, val] of Object.entries(node)) {
-      if (skipKeys.has(key)) continue;
-      props.push(`${indent2}${key} = ${luaValue(val, depth + 1)},`);
+  authorizeStudio(ws, hello, connectionId) {
+    const connection = {
+      ws,
+      connectionId,
+      clientId: hello.clientId,
+      connectedAt: Date.now(),
+      studioVersion: hello.studioVersion,
+      placeId: hello.placeId ?? 0,
+      placeName: hello.placeName
+    };
+    this.pendingConnections.delete(connectionId);
+    this.studioClients.set(connectionId, connection);
+    this.wsToConnectionId.set(ws, connectionId);
+    this.socketRoles.set(ws, "studio");
+    if (!this.activeConnectionId || !this.studioClients.has(this.activeConnectionId)) {
+      this.activeConnectionId = connectionId;
     }
-    const childEntries = [];
-    for (const child of children) {
-      const childName = child.Name || child.ClassName || "Child";
-      childEntries.push(`${indent2}${childName} = ${renderNode(child, depth + 1)},`);
+    this.sendSafe(ws, createMessage(StudioMsg.AUTHENTICATED, {
+      protocolVersion: DOMINUS_PROTOCOL_VERSION,
+      connectionId,
+      token: this.token
+    }));
+    const info = this.toPlaceInfo(connection);
+    this.emit("studio:connected", info);
+    this.broadcastToControllers(StudioMsg.CONNECTED, info);
+    this.broadcastTargetState();
+    return connection;
+  }
+  handleControllerMessage(controllerWs, msg) {
+    if (msg.type === ControllerMsg.RELAY) {
+      const payload = msg.payload;
+      const request = parseMessage(JSON.stringify(payload.request));
+      const target = this.resolveConnection(typeof payload.connectionId === "string" ? payload.connectionId : null);
+      if (!target) {
+        this.sendResponse(controllerWs, request.id, { error: this.getTargetError() });
+        return;
+      }
+      this.relayRequests.set(request.id, { controllerWs, targetWs: target.ws });
+      this.sendSafe(target.ws, request);
+      return;
     }
-    const hasProps = props.length > 0;
-    const hasChildren = childEntries.length > 0;
-    if (!hasProps && !hasChildren) {
-      return `e("${className}", {})`;
+    if (msg.type === ControllerMsg.SET_ACTIVE_CONNECTION) {
+      const payload = msg.payload;
+      const connectionId = typeof payload.connectionId === "string" ? payload.connectionId : null;
+      if (connectionId && !this.studioClients.has(connectionId)) {
+        this.sendResponse(controllerWs, msg.id, { success: false, error: `Studio connection ${connectionId} is not connected` });
+        return;
+      }
+      this.sendResponse(controllerWs, msg.id, { success: true, connectionId });
+      return;
     }
-    const parts = [];
-    parts.push(`e("${className}", {`);
-    if (hasProps) {
-      parts.push(...props);
+    if (msg.type === ControllerMsg.LIST_PENDING) {
+      this.sendResponse(controllerWs, msg.id, { success: true, pending: this.getPendingInfos() });
+      return;
     }
-    if (hasChildren) {
-      parts.push(`${indent2}}, {`);
-      parts.push(...childEntries);
-      parts.push(`${indent}})`);
-    } else {
-      parts.push(`${indent}})`);
+    if (msg.type === ControllerMsg.APPROVE_CONNECTION) {
+      const payload = msg.payload;
+      this.approveConnection(String(payload.connectionId ?? ""), String(payload.pairingCode ?? "")).then((connection) => this.sendResponse(controllerWs, msg.id, { success: true, connection })).catch((err) => this.sendResponse(controllerWs, msg.id, {
+        success: false,
+        error: err instanceof Error ? err.message : String(err)
+      }));
+      return;
     }
-    return parts.join("\n");
-  }
-  function luaValue(val, _depth) {
-    if (val === null || val === void 0) return "nil";
-    if (typeof val === "boolean") return String(val);
-    if (typeof val === "number") return cleanNum(val);
-    if (typeof val === "string") {
-      if (val.startsWith("#") && val.length === 7) {
-        return `Color3.fromHex("${val}")`;
+    this.sendResponse(controllerWs, msg.id, { error: `Unsupported controller message: ${msg.type}` });
+  }
+  handleStudioMessage(ws, msg) {
+    if (msg.type === StudioMsg.RESPONSE) {
+      const relay = this.relayRequests.get(msg.id);
+      if (relay) {
+        if (relay.targetWs !== ws) {
+          this.emit("server:error", new Error(`Ignored relayed response ${msg.id} from the wrong Studio session`));
+          return;
+        }
+        this.sendSafe(relay.controllerWs, msg);
+        this.relayRequests.delete(msg.id);
+        return;
       }
-      if (/^[A-Z][a-zA-Z]+$/.test(val)) {
-        return `"${val}"`;
+      const pending = this.pendingRequests.get(msg.id);
+      if (pending) {
+        if (pending.targetWs !== ws) {
+          this.emit("server:error", new Error(`Ignored response ${msg.id} from the wrong Studio session`));
+          return;
+        }
+        clearTimeout(pending.timer);
+        this.pendingRequests.delete(msg.id);
+        pending.resolve(msg);
       }
-      return `"${val.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n")}"`;
+      return;
     }
-    if (Array.isArray(val)) {
-      if (val.length === 4 && val.every((v) => typeof v === "number")) {
-        return `UDim2.new(${val.map(cleanNum).join(", ")})`;
-      }
-      if (val.length === 2 && val.every((v) => typeof v === "number")) {
-        return `Vector2.new(${val.map(cleanNum).join(", ")})`;
-      }
-      if (val.length === 3 && val.every((v) => typeof v === "number")) {
-        const allSmall = val.every((v) => v <= 1);
-        if (allSmall) return `Color3.new(${val.map(cleanNum).join(", ")})`;
-        return `Color3.fromRGB(${val.map((v) => String(Math.round(v))).join(", ")})`;
+    this.emit(msg.type, msg.payload);
+    this.emit("message", msg);
+  }
+  cleanupSocket(ws) {
+    const role = this.socketRoles.get(ws);
+    this.socketRoles.delete(ws);
+    this.rateState.delete(ws);
+    if (role === "controller") {
+      this.controllers.delete(ws);
+      for (const [id, relay] of this.relayRequests) {
+        if (relay.controllerWs === ws) this.relayRequests.delete(id);
       }
-      return `{${val.map((v) => luaValue(v, _depth)).join(", ")}}`;
-    }
-    if (typeof val === "object") {
-      const entries = Object.entries(val);
-      if (entries.length === 0) return "{}";
-      return `{
-${entries.map(([k, v]) => `${"	".repeat(_depth + 1)}${k} = ${luaValue(v, _depth + 1)}`).join(",\n")}
-${"	".repeat(_depth)}}`;
-    }
-    return String(val);
-  }
-  mcp.tool(
-    "read_script",
-    "Read the source code of a script in Roblox Studio",
-    { path: z.string().describe('Full instance path, e.g. "ServerScriptService.GameManager"') },
-    async ({ path: path2 }) => {
-      assertConnected();
-      const res = await bridge.sendRequest(CliMsg.GET_SCRIPT, { path: path2 });
-      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
-    }
-  );
-  mcp.tool(
-    "edit_script",
-    "Replace the entire source code of a script in Roblox Studio",
-    {
-      path: z.string().describe("Full instance path"),
-      source: z.string().describe("New complete source code")
-    },
-    async ({ path: path2, source }) => {
-      assertConnected();
-      const res = await bridge.sendRequest(CliMsg.SET_SCRIPT, { path: path2, source });
-      return { content: [{ type: "text", text: JSON.stringify(res.payload) }] };
-    }
-  );
-  mcp.tool(
-    "run_code",
-    "Execute arbitrary Luau code in Roblox Studio. LAST RESORT \u2014 only use when no dedicated tool exists. Do NOT use for: reading properties (use get_properties/inspect_selection/serialize_ui), creating instances (use create_part/create_ui/insert_instance/build_multiple), modifying properties (use set_properties/bulk_set_properties), or inspecting the tree (use get_explorer). Valid uses: complex procedural generation, terrain algorithms, raycasting, physics queries, custom logic with no tool equivalent.",
-    { code: z.string().describe("Luau code to execute") },
-    async ({ code }) => {
-      assertConnected();
-      const res = await bridge.sendRequest(CliMsg.RUN_CODE, { code });
-      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+      return;
     }
-  );
-  mcp.tool(
-    "get_explorer",
-    "Get the DataModel explorer tree from Roblox Studio",
-    {
-      rootPath: z.string().optional().describe("Root path to start from. Omit for entire tree."),
-      maxDepth: z.number().optional().default(3).describe("Maximum tree depth")
-    },
-    async ({ rootPath, maxDepth }) => {
-      assertConnected();
-      const res = await bridge.sendRequest(CliMsg.GET_EXPLORER, {
-        rootPath: rootPath ?? null,
-        maxDepth
-      });
-      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+    if (role === "pending") {
+      for (const [id, pending] of this.pendingConnections) {
+        if (pending.ws === ws) this.pendingConnections.delete(id);
+      }
+      return;
     }
-  );
-  mcp.tool(
-    "get_properties",
-    "Get all properties of a single instance in Roblox Studio. Returns property name, value, type, and category. For inspecting UI trees, prefer serialize_ui (structured tree) or get_descendants_properties (flat list with compact filtering).",
-    {
-      path: z.string().describe('Full instance path (e.g. "Workspace.Part", "StarterGui.MyUI.Frame")'),
-      compact: z.boolean().optional().default(true).describe("Strip read-only, nil, deprecated, and default-valued properties (default true). Set false for full dump.")
-    },
-    async ({ path: path2, compact }) => {
-      assertConnected();
-      const res = await bridge.sendRequest(CliMsg.GET_PROPERTIES, { path: path2, compact });
-      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+    const connectionId = this.wsToConnectionId.get(ws);
+    if (!connectionId) return;
+    const connection = this.studioClients.get(connectionId);
+    this.wsToConnectionId.delete(ws);
+    this.studioClients.delete(connectionId);
+    for (const [id, pending] of this.pendingRequests) {
+      if (pending.targetWs === ws) {
+        clearTimeout(pending.timer);
+        pending.reject(new Error(`Studio disconnected (${connectionId})`));
+        this.pendingRequests.delete(id);
+      }
     }
-  );
-  mcp.tool(
-    "get_descendants_properties",
-    "Easily get all descendants of a UI instance (or any instance) and all of their properties. By default uses compact mode which strips read-only, nil, deprecated, and default-valued properties to keep responses small.",
-    {
-      path: z.string().describe('Full instance path (e.g., "Workspace.Part", "StarterGui.ScreenGui")'),
-      compact: z.boolean().optional().default(true).describe("Strip noisy/default properties (default true). Set false for full dump."),
-      outputFile: z.string().optional().describe("Optional file path to write to prevent limit errors/timeouts")
-    },
-    async ({ path: path2, compact, outputFile }) => {
-      assertConnected();
-      const res = await bridge.sendRequest(CliMsg.GET_DESCENDANTS_PROPERTIES, { path: path2, compact, outputFile }, 1e3 * 60 * 5);
-      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+    for (const [id, relay] of this.relayRequests) {
+      if (relay.targetWs === ws) {
+        this.sendResponse(relay.controllerWs, id, { error: `Studio disconnected (${connectionId})` });
+        this.relayRequests.delete(id);
+      }
     }
-  );
-  mcp.tool(
-    "set_properties",
-    "Set properties on an instance in Roblox Studio",
-    {
-      path: z.string().describe("Full instance path"),
-      properties: z.record(z.unknown()).describe("Key-value pairs of properties to set")
-    },
-    async ({ path: path2, properties }) => {
-      assertConnected();
-      const res = await bridge.sendRequest(CliMsg.SET_PROPERTIES, { path: path2, properties });
-      return { content: [{ type: "text", text: JSON.stringify(res.payload) }] };
+    if (this.activeConnectionId === connectionId) {
+      this.activeConnectionId = this.studioClients.size === 1 ? this.studioClients.keys().next().value ?? null : null;
     }
-  );
-  mcp.tool(
-    "insert_instance",
-    "Create a new instance in the Roblox Studio DataModel",
-    {
-      className: z.string().describe('Class name (e.g. "Part", "Script")'),
-      parentPath: z.string().describe("Parent instance path"),
-      name: z.string().describe("Name for the new instance"),
-      properties: z.record(z.unknown()).optional().describe("Optional properties to set")
-    },
-    async ({ className, parentPath, name, properties }) => {
-      assertConnected();
-      const res = await bridge.sendRequest(CliMsg.INSERT_INSTANCE, {
-        className,
-        parentPath,
-        name,
-        properties: properties ?? {}
-      });
-      return { content: [{ type: "text", text: JSON.stringify(res.payload) }] };
+    const info = connection ? this.toPlaceInfo(connection) : { connectionId };
+    this.emit("studio:disconnected", info);
+    this.broadcastToControllers(StudioMsg.DISCONNECTED, info);
+    this.broadcastTargetState();
+  }
+  resolveConnection(connectionId = this.activeConnectionId) {
+    if (connectionId) {
+      const connection = this.studioClients.get(connectionId);
+      return connection?.ws.readyState === WebSocket.OPEN ? connection : null;
     }
-  );
-  mcp.tool(
-    "delete_instance",
-    "Delete an instance from the Roblox Studio DataModel",
-    { path: z.string().describe("Full instance path to delete") },
-    async ({ path: path2 }) => {
-      assertConnected();
-      const res = await bridge.sendRequest(CliMsg.DELETE_INSTANCE, { path: path2 });
-      return { content: [{ type: "text", text: JSON.stringify(res.payload) }] };
+    if (this.studioClients.size === 1) {
+      const connection = this.studioClients.values().next().value;
+      return connection?.ws.readyState === WebSocket.OPEN ? connection : null;
     }
-  );
-  mcp.tool(
-    "get_selection",
-    'Get the currently selected instances in Roblox Studio. Returns paths and class names of all selected objects. Use this FIRST when the user says "my selection" or "what I have selected". Then use get_properties or serialize_ui on the returned paths to inspect details.',
-    {},
-    async () => {
-      assertConnected();
-      const res = await bridge.sendRequest(CliMsg.GET_SELECTION, {});
-      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+    return null;
+  }
+  getTargetError() {
+    if (this.studioClients.size === 0) return "No authenticated Roblox Studio connection";
+    if (this.activeConnectionId) return `Studio connection ${this.activeConnectionId} is unavailable`;
+    return "Multiple Studio sessions are connected. Call dominus_select_studio with a connectionId.";
+  }
+  getPendingInfos() {
+    const now = Date.now();
+    for (const [id, pending] of this.pendingConnections) {
+      if (pending.info.expiresAt <= now || pending.ws.readyState !== WebSocket.OPEN) {
+        this.pendingConnections.delete(id);
+        pending.ws.close(1008, "Pairing expired");
+      }
     }
-  );
-  mcp.tool(
-    "search_scripts",
-    "Search all scripts in Roblox Studio for a text pattern",
-    {
-      query: z.string().describe("Text to search for"),
-      maxResults: z.number().optional().default(20).describe("Max results")
-    },
-    async ({ query, maxResults }) => {
-      assertConnected();
-      const res = await bridge.sendRequest(CliMsg.SEARCH_SCRIPTS, { query, maxResults });
-      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+    return [...this.pendingConnections.values()].map(({ info }) => ({ ...info }));
+  }
+  toPlaceInfo(connection) {
+    return {
+      placeId: connection.placeId ?? 0,
+      connectionId: connection.connectionId,
+      clientId: connection.clientId,
+      placeName: connection.placeName,
+      studioVersion: connection.studioVersion,
+      connectedAt: connection.connectedAt,
+      active: connection.connectionId === this.activeConnectionId
+    };
+  }
+  broadcastToControllers(type, payload) {
+    const message = createMessage(type, payload);
+    for (const controller of this.controllers) this.sendSafe(controller, message);
+  }
+  broadcastTargetState() {
+    this.broadcastToControllers(ControllerMsg.TARGET_STATE, {
+      connections: this.listConnections(),
+      defaultActiveConnectionId: this.activeConnectionId
+    });
+  }
+  sendResponse(ws, id, payload) {
+    this.sendSafe(ws, { id, type: StudioMsg.RESPONSE, payload, ts: Date.now() });
+  }
+  sendSafe(ws, message) {
+    if (ws.readyState !== WebSocket.OPEN) return;
+    try {
+      ws.send(serializeMessage(message));
+    } catch (err) {
+      this.emit("server:error", err);
     }
-  );
-  mcp.tool(
-    "get_output",
-    "Get recent output log from Roblox Studio",
-    {
-      limit: z.number().optional().default(50).describe("Max entries"),
-      level: z.enum(["info", "warn", "error"]).optional().describe("Filter by level")
-    },
-    async ({ limit, level }) => {
-      assertConnected();
-      const res = await bridge.sendRequest(CliMsg.GET_OUTPUT, {
-        limit,
-        level: level ?? null
+  }
+  sendRequest(type, payload, timeoutMs = 15e3) {
+    return new Promise((resolve, reject) => {
+      const target = this.resolveConnection();
+      if (!target) {
+        reject(new Error(this.getTargetError()));
+        return;
+      }
+      const message = createMessage(type, payload);
+      const timer = setTimeout(() => {
+        this.pendingRequests.delete(message.id);
+        reject(new Error(`Studio request timed out: ${type}`));
+      }, timeoutMs);
+      this.pendingRequests.set(message.id, {
+        resolve,
+        reject,
+        timer,
+        targetWs: target.ws
       });
-      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
-    }
-  );
-  mcp.tool(
-    "get_class_info",
-    "Look up the schema of any Roblox class using ReflectionService. Returns all properties (with types), methods (with parameters), and events. ALWAYS use this before creating or modifying GUI elements to know correct property names and types.",
-    { className: z.string().describe('Roblox class name, e.g. "Frame", "TextLabel", "Part", "MeshPart"') },
-    async ({ className }) => {
-      assertConnected();
-      const res = await bridge.sendRequest(CliMsg.GET_REFLECTION, { className });
-      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+      this.sendSafe(target.ws, message);
+    });
+  }
+  sendNotification(type, payload) {
+    const target = this.resolveConnection();
+    if (target) this.sendSafe(target.ws, createMessage(type, payload));
+  }
+  isConnected() {
+    return this.resolveConnection() !== null;
+  }
+  getConnectionInfo() {
+    return this.resolveConnection();
+  }
+  listConnections() {
+    return [...this.studioClients.values()].filter(({ ws }) => ws.readyState === WebSocket.OPEN).map((connection) => this.toPlaceInfo(connection));
+  }
+  async listPendingConnections() {
+    return this.getPendingInfos();
+  }
+  async approveConnection(connectionId, pairingCode) {
+    const pending = this.pendingConnections.get(connectionId);
+    if (!pending || pending.info.expiresAt <= Date.now()) {
+      throw new Error("Pairing request not found or expired");
     }
-  );
-  mcp.tool(
-    "create_ui",
-    'Create an entire UI tree in one call. Pass a declarative JSON tree \u2014 ClassName, Name, properties, Children. All types auto-coerced in Luau (UDim2, Color3, Font, enums). 10x faster than run_code. UDim2: [xScale, xOffset, yScale, yOffset]. Color3: "#hex" or "rgb(r,g,b)". Font: "GothamBold". Enums: string names.',
-    {
-      parent: z.string().optional().describe('Parent: "StarterGui", "PlayerGui", or path. Default: StarterGui'),
-      tree: z.record(z.unknown()).describe(
-        'Root UI node: {ClassName, Name, properties..., Children: [{...}, ...]}. UDim2 as [xScale, xOffset, yScale, yOffset], Color3 as "#hex", Font as "GothamBold"'
-      ),
-      animate: z.boolean().optional().describe("If true, task.wait() will be injected between creation of nodes so that the UI writes out dynamically.")
-    },
-    async ({ parent, tree, animate }) => {
-      assertConnected();
-      const res = await bridge.sendRequest(
-        CliMsg.BUILD_UI,
-        { parent: parent ?? "StarterGui", tree, animate }
-      );
-      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+    if (pending.pairingCode !== pairingCode) {
+      throw new Error("Pairing code is incorrect");
     }
-  );
-  mcp.tool(
-    "run_tests",
-    "Run tests by requiring ModuleScripts matching test naming conventions (*.test, *.spec, *Test, *Spec). Lightweight \u2014 does not enter Run/Play mode.",
-    { testName: z.string().optional().describe("Specific test name, or omit to run all") },
-    async ({ testName }) => {
-      assertConnected();
-      const res = await bridge.sendRequest(CliMsg.RUN_TESTS, {
-        testName: testName ?? null
-      });
-      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+    const connection = this.authorizeStudio(pending.ws, pending.hello, connectionId);
+    return this.toPlaceInfo(connection);
+  }
+  getActiveConnectionId() {
+    return this.activeConnectionId;
+  }
+  async setActiveConnectionId(connectionId) {
+    if (connectionId && !this.studioClients.has(connectionId)) {
+      throw new Error(`Studio connection ${connectionId} is not connected`);
     }
-  );
-  mcp.tool(
-    "execute_run_test",
-    "Start a Run mode test session using StudioTestService:ExecuteRunModeAsync(). This actually enters Run mode in Studio. Pass args that server scripts can retrieve via GetTestArgs(). Yields until EndTest() is called or the session stops. Returns the value from EndTest(). Use for headless automated tests \u2014 no player, just server scripts.",
-    { args: z.unknown().optional().describe("Arguments passed to the test session. Server scripts get this via StudioTestService:GetTestArgs()") },
-    async ({ args }) => {
-      assertConnected();
-      const res = await bridge.sendRequest(CliMsg.EXECUTE_RUN_TEST, { args: args ?? null }, 12e4);
-      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+    this.activeConnectionId = connectionId;
+    this.broadcastTargetState();
+  }
+  getActivePlaceId() {
+    return this.resolveConnection()?.placeId ?? 0;
+  }
+  setActivePlaceId(placeId) {
+    if (placeId === 0) {
+      this.activeConnectionId = null;
+      return;
     }
-  );
-  mcp.tool(
-    "execute_play_test",
-    "Start a solo Play mode test session using StudioTestService:ExecutePlayModeAsync(). This enters Play mode with a player character. Pass args that server scripts can retrieve via GetTestArgs(). Yields until EndTest() is called or the session stops. Returns the value from EndTest(). Use for tests needing a player character and full client-server simulation.",
-    { args: z.unknown().optional().describe("Arguments passed to the test session. Server scripts get this via StudioTestService:GetTestArgs()") },
-    async ({ args }) => {
-      assertConnected();
-      const res = await bridge.sendRequest(CliMsg.EXECUTE_PLAY_TEST, { args: args ?? null }, 12e4);
-      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+    const matches = [...this.studioClients.values()].filter((connection) => connection.placeId === placeId);
+    if (matches.length !== 1) {
+      throw new Error(matches.length === 0 ? `Place ${placeId} is not connected` : `Place ${placeId} has multiple Studio sessions; select a connectionId instead`);
     }
-  );
-  mcp.tool(
-    "create_part",
-    "Create a Part with position, size, color, material \u2014 all in one call. Faster than insert_instance + set_properties.",
-    {
-      name: z.string().describe("Name for the part"),
-      parent: z.string().optional().describe("Parent path (default: Workspace)"),
-      shape: z.enum(["Block", "Ball", "Cylinder", "Wedge", "CornerWedge"]).optional().describe("Part shape"),
-      position: z.object({ x: z.number(), y: z.number(), z: z.number() }).optional().describe("World position"),
-      size: z.object({ x: z.number(), y: z.number(), z: z.number() }).optional().describe("Size in studs"),
-      color: z.string().optional().describe('Hex "#00FF00", BrickColor name, or "rgb(0,255,0)"'),
-      material: z.string().optional().describe("Plastic, Wood, Grass, Neon, Metal, etc."),
-      transparency: z.number().optional().describe("0=opaque, 1=invisible"),
-      anchored: z.boolean().optional().describe("Anchored (default: true)"),
-      canCollide: z.boolean().optional().describe("Has collision")
-    },
-    async (params) => {
-      assertConnected();
-      const properties = {};
-      if (params.position) properties.Position = { X: params.position.x, Y: params.position.y, Z: params.position.z };
-      if (params.size) properties.Size = { X: params.size.x, Y: params.size.y, Z: params.size.z };
-      if (params.color) {
-        const c = params.color;
-        if (c.startsWith("#")) properties.Color = c;
-        else if (c.startsWith("rgb")) {
-          const m = c.match(/(\d+)/g);
-          if (m && m.length >= 3) properties.Color = { red: parseInt(m[0]), green: parseInt(m[1]), blue: parseInt(m[2]) };
-        } else properties.BrickColor = c;
+    this.activeConnectionId = matches[0].connectionId;
+  }
+  getPort() {
+    return this.port;
+  }
+  stop() {
+    return new Promise((resolve) => {
+      for (const pending of this.pendingRequests.values()) {
+        clearTimeout(pending.timer);
+        pending.reject(new Error("Dominus bridge is shutting down"));
       }
-      if (params.material) properties.Material = params.material;
-      if (params.transparency !== void 0) properties.Transparency = params.transparency;
-      if (params.anchored !== void 0) properties.Anchored = params.anchored;
-      else properties.Anchored = true;
-      if (params.canCollide !== void 0) properties.CanCollide = params.canCollide;
-      if (params.shape && params.shape !== "Block") properties.Shape = params.shape;
-      const className = params.shape === "Wedge" ? "WedgePart" : params.shape === "CornerWedge" ? "CornerWedgePart" : "Part";
-      const res = await bridge.sendRequest(CliMsg.INSERT_INSTANCE, {
-        className,
-        parentPath: params.parent ?? "Workspace",
-        name: params.name,
-        properties
+      this.pendingRequests.clear();
+      this.relayRequests.clear();
+      for (const ws of this.socketRoles.keys()) ws.close(1001, "Dominus bridge shutdown");
+      this.studioClients.clear();
+      this.pendingConnections.clear();
+      this.controllers.clear();
+      this.socketRoles.clear();
+      this.wsToConnectionId.clear();
+      if (this.wss) this.wss.close(() => resolve());
+      else resolve();
+    });
+  }
+};
+function validateStudioHello(payload) {
+  if (!payload || typeof payload !== "object") throw new Error("Invalid Studio hello payload");
+  const hello = payload;
+  if (hello.protocolVersion !== DOMINUS_PROTOCOL_VERSION) {
+    throw new Error(`Studio plugin protocol ${hello.protocolVersion ?? "unknown"} is incompatible; expected ${DOMINUS_PROTOCOL_VERSION}`);
+  }
+  if (typeof hello.clientId !== "string" || hello.clientId.length < 8 || hello.clientId.length > 128) {
+    throw new Error("Studio hello is missing a valid clientId");
+  }
+  if (typeof hello.studioVersion !== "string" || hello.studioVersion.length > 128) {
+    throw new Error("Studio hello is missing studioVersion");
+  }
+  if (hello.placeName && hello.placeName.length > 256) throw new Error("Studio placeName is too long");
+  return hello;
+}
+function rawByteLength(raw) {
+  if (typeof raw === "string") return Buffer.byteLength(raw);
+  if (Array.isArray(raw)) return raw.reduce((total, item) => total + item.byteLength, 0);
+  return raw.byteLength;
+}
+
+// src/mcp/instructions.ts
+var DOMINUS_MCP_INSTRUCTIONS = `Dominus 2 is a Roblox Studio engineering MCP server.
+
+Required workflow for Studio changes:
+1. Call dominus_status and select the intended Studio connection when more than one is open.
+2. Inspect the relevant tree, selection, instances, scripts, and Roblox API references before editing.
+3. Form a short plan with explicit acceptance checks.
+4. Use stable instance refs returned by Dominus. Prefer instanceId; retain pathSegments as fallback context.
+5. Apply the smallest coherent mutation. Script updates require the expectedRevision returned by studio_read_script.
+6. Read the affected instances back and compare exact values, hierarchy, and source revisions.
+7. Run an appropriate Studio test when behavior changed. Report verification evidence and any remaining uncertainty.
+
+Safety rules:
+- Never invent instance IDs or Roblox API members.
+- Do not retry a failed write unchanged. Inspect the error and current state first.
+- Deletion is a separate destructive tool and requires explicit user intent.
+- studio_apply is transactional. Keep related edits together, but stay within its documented limits.
+- UI fidelity work must snapshot and inspect the result after building; verify fonts, UDim2 values, colors, strokes, and hierarchy.
+- Dominus intentionally has no arbitrary Luau execution tool.`;
+
+// src/mcp/resources.ts
+function registerDominusResources(server, bridge) {
+  server.registerResource("dominus-status", "dominus://status", {
+    title: "Dominus 2 Studio Status",
+    description: "Current authenticated Roblox Studio sessions and selected target.",
+    mimeType: "application/json"
+  }, async (uri) => ({
+    contents: [{
+      uri: uri.href,
+      mimeType: "application/json",
+      text: JSON.stringify({
+        protocolVersion: 2,
+        activeConnectionId: bridge.getActiveConnectionId(),
+        connections: bridge.listConnections(),
+        pendingConnections: await bridge.listPendingConnections()
+      }, null, 2)
+    }]
+  }));
+  server.registerPrompt("dominus-workflow", {
+    title: "Dominus 2 Engineering Workflow",
+    description: "Inspect, plan, apply, verify, and test a Roblox Studio change safely."
+  }, async () => ({
+    messages: [{
+      role: "user",
+      content: { type: "text", text: DOMINUS_MCP_INSTRUCTIONS }
+    }]
+  }));
+}
+
+// src/mcp/result.ts
+function toolResult(output) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
+    structuredContent: output,
+    isError: !output.success
+  };
+}
+function success(data = {}) {
+  return toolResult({ success: true, data });
+}
+function failure(error, data) {
+  return toolResult({
+    success: false,
+    error: error instanceof Error ? error.message : String(error),
+    data
+  });
+}
+var instanceRefSchema = z.object({
+  instanceId: z.string().uuid().optional(),
+  pathSegments: z.array(z.string().min(1).max(256)).min(1).max(100).optional()
+}).refine((value) => Boolean(value.instanceId || value.pathSegments), {
+  message: "Provide instanceId or pathSegments"
+});
+var toolOutputSchema = {
+  success: z.boolean(),
+  data: z.record(z.unknown()).optional(),
+  error: z.string().optional()
+};
+async function callStudio(bridge, command, payload, timeoutMs = 15e3) {
+  try {
+    const response = await bridge.sendRequest(command, payload, timeoutMs);
+    const result = response.payload;
+    if (!result || typeof result !== "object") return failure("Studio returned an invalid response");
+    if (result.success === false || typeof result.error === "string") {
+      return failure(result.error ?? "Studio command failed", result);
+    }
+    return success(result);
+  } catch (err) {
+    return failure(err);
+  }
+}
+function ref(value) {
+  return value;
+}
+
+// src/mcp/tools/connections.ts
+function registerConnectionTools(server, bridge) {
+  server.registerTool("dominus_status", {
+    title: "Dominus Studio Status",
+    description: "List authenticated and pending Roblox Studio sessions, the active target, and bridge health. Call this before Studio work.",
+    inputSchema: {},
+    outputSchema: toolOutputSchema,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+  }, async () => {
+    try {
+      const pending = await bridge.listPendingConnections();
+      return success({
+        protocolVersion: 2,
+        port: bridge.getPort(),
+        activeConnectionId: bridge.getActiveConnectionId(),
+        connections: bridge.listConnections(),
+        pendingConnections: pending
       });
-      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+    } catch (err) {
+      return failure(err);
     }
-  );
-  mcp.tool(
-    "clone_instance",
-    "Clone an existing instance, optionally rename it, move it, or offset its position",
-    {
-      path: z.string().describe("Path of instance to clone"),
-      newName: z.string().optional().describe("Name for the clone"),
-      newParent: z.string().optional().describe("Parent path for the clone"),
-      offset: z.object({ x: z.number(), y: z.number(), z: z.number() }).optional().describe("Position offset from original")
+  });
+  server.registerTool("dominus_pair_studio", {
+    title: "Pair Roblox Studio",
+    description: "Approve a first-time Studio plugin connection using the connection ID and six-digit code printed in Roblox Studio Output.",
+    inputSchema: {
+      connectionId: z.string().uuid(),
+      pairingCode: z.string().regex(/^\d{6}$/)
     },
-    async (params) => {
-      assertConnected();
-      const lines = [`local orig = ${resolvePath(params.path)}`, `local clone = orig:Clone()`];
-      if (params.newName) lines.push(`clone.Name = ${luaStr(params.newName)}`);
-      if (params.newParent) {
-        lines.push(`clone.Parent = ${resolvePath(params.newParent)}`);
-      } else {
-        lines.push(`clone.Parent = orig.Parent`);
-      }
-      if (params.offset) {
-        lines.push(`if clone:IsA("BasePart") then`);
-        lines.push(`  clone.Position = clone.Position + Vector3.new(${params.offset.x}, ${params.offset.y}, ${params.offset.z})`);
-        lines.push(`end`);
-      }
-      lines.push(`print("Cloned: " .. clone:GetFullName())`);
-      const res = await bridge.sendRequest(CliMsg.RUN_CODE, { code: lines.join("\n") });
-      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+    outputSchema: toolOutputSchema,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }
+  }, async ({ connectionId, pairingCode }) => {
+    try {
+      const connection = await bridge.approveConnection(connectionId, pairingCode);
+      return success({ connection });
+    } catch (err) {
+      return failure(err);
     }
-  );
-  mcp.tool(
-    "group_instances",
-    "Group multiple instances into a Model or Folder. All listed instances become children of the new group.",
-    {
-      paths: z.array(z.string()).describe("Array of instance paths to group"),
-      groupName: z.string().describe("Name for the group"),
-      groupClass: z.enum(["Model", "Folder"]).optional().describe("Container class (default: Model)"),
-      parent: z.string().optional().describe("Parent path (default: Workspace)")
-    },
-    async (params) => {
-      assertConnected();
-      const gc = params.groupClass ?? "Model";
-      const parent = params.parent ?? "Workspace";
-      const code = [
-        `local group = Instance.new(${luaStr(gc)})`,
-        `group.Name = ${luaStr(params.groupName)}`,
-        `group.Parent = ${resolvePath(parent)}`,
-        ...params.paths.map((p) => `${resolvePath(p)}.Parent = group`),
-        `print("Grouped ${params.paths.length} instances into: " .. group:GetFullName())`
-      ].join("\n");
-      const res = await bridge.sendRequest(CliMsg.RUN_CODE, { code });
-      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+  });
+  server.registerTool("dominus_select_studio", {
+    title: "Select Studio Session",
+    description: "Choose the exact Studio connection targeted by subsequent tools. Uses connectionId, not placeId, so duplicate windows are safe.",
+    inputSchema: { connectionId: z.string().uuid().nullable() },
+    outputSchema: toolOutputSchema,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+  }, async ({ connectionId }) => {
+    try {
+      await bridge.setActiveConnectionId(connectionId);
+      return success({ activeConnectionId: bridge.getActiveConnectionId() });
+    } catch (err) {
+      return failure(err);
     }
-  );
-  mcp.tool(
-    "build_multiple",
-    "Create many parts/instances in one batch. Send an array of specs \u2014 all created in a single round-trip. Ideal for building trees, houses, vehicles. Supports hex colors, rgb() colors, and BrickColor names.",
-    {
-      parts: z.array(z.object({
-        name: z.string(),
-        className: z.string().optional(),
-        parent: z.string().optional(),
-        position: z.object({ x: z.number(), y: z.number(), z: z.number() }).optional(),
-        size: z.object({ x: z.number(), y: z.number(), z: z.number() }).optional(),
-        color: z.string().optional().describe('Hex "#RRGGBB", "rgb(r,g,b)", or BrickColor name'),
-        material: z.string().optional().describe("Enum.Material name: Plastic, Wood, Neon, Glass, etc."),
-        transparency: z.number().optional(),
-        anchored: z.boolean().optional(),
-        canCollide: z.boolean().optional(),
-        shape: z.enum(["Block", "Ball", "Cylinder", "Wedge"]).optional()
-      })).describe("Array of part specifications"),
-      groupName: z.string().optional().describe("Group all parts into a Model with this name"),
-      groupParent: z.string().optional().describe("Parent for the group (default: Workspace)")
-    },
-    async (params) => {
-      assertConnected();
-      const parts = params.parts;
-      const groupName = params.groupName;
-      const groupParent = params.groupParent ?? "Workspace";
-      const lines = [];
-      if (groupName) {
-        lines.push(`local _group = Instance.new("Model")`);
-        lines.push(`_group.Name = ${luaStr(groupName)}`);
-        lines.push(`_group.Parent = ${resolvePath(groupParent)}`);
-      }
-      for (let i = 0; i < parts.length; i++) {
-        const p = parts[i];
-        const v = `_p${i}`;
-        const cn = p.className ?? (p.shape === "Wedge" ? "WedgePart" : "Part");
-        lines.push(`local ${v} = Instance.new(${luaStr(cn)})`);
-        lines.push(`${v}.Name = ${luaStr(p.name)}`);
-        if (p.position) lines.push(`${v}.Position = Vector3.new(${p.position.x}, ${p.position.y}, ${p.position.z})`);
-        if (p.size) lines.push(`${v}.Size = Vector3.new(${p.size.x}, ${p.size.y}, ${p.size.z})`);
-        if (p.color) {
-          if (p.color.startsWith("#")) {
-            lines.push(`${v}.Color = Color3.fromHex(${luaStr(p.color)})`);
-          } else if (p.color.startsWith("rgb(")) {
-            const m = p.color.match(/rgb\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*\)/);
-            if (m) lines.push(`${v}.Color = Color3.fromRGB(${m[1]}, ${m[2]}, ${m[3]})`);
-          } else {
-            lines.push(`${v}.BrickColor = BrickColor.new(${luaStr(p.color)})`);
-          }
-        }
-        if (p.material) lines.push(`${v}.Material = Enum.Material.${p.material}`);
-        if (p.transparency !== void 0) lines.push(`${v}.Transparency = ${p.transparency}`);
-        lines.push(`${v}.Anchored = ${p.anchored ?? true}`);
-        if (p.canCollide !== void 0) lines.push(`${v}.CanCollide = ${p.canCollide}`);
-        if (p.shape && p.shape !== "Block" && cn === "Part") lines.push(`${v}.Shape = Enum.PartType.${p.shape}`);
-        lines.push(`${v}.Parent = ${groupName ? "_group" : resolvePath(p.parent ?? "Workspace")}`);
-      }
-      lines.push(`print("Built ${parts.length} parts${groupName ? ` in ${groupName}` : ""}")`);
-      const res = await bridge.sendRequest(CliMsg.RUN_CODE, { code: lines.join("\n") });
-      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+  });
+}
+var GITHUB_RAW_BASE = "https://raw.githubusercontent.com/Roblox/creator-docs/main/content/en-us/reference/engine";
+var GITHUB_TREE_URL = "https://api.github.com/repos/Roblox/creator-docs/git/trees/main?recursive=1";
+var KIND_FOLDERS = {
+  class: "classes",
+  datatype: "datatypes",
+  enum: "enums",
+  global: "globals",
+  library: "libraries"
+};
+var MEMBER_SECTIONS = [
+  "properties",
+  "methods",
+  "events",
+  "callbacks",
+  "constructors",
+  "functions",
+  "items",
+  "constants",
+  "math_operations"
+];
+var remoteTreeCache = null;
+async function getRobloxApiReference(name, opts = {}) {
+  const normalizedName = normalizeLookupName(name);
+  const kinds = opts.kind && opts.kind !== "any" ? [opts.kind] : Object.keys(KIND_FOLDERS);
+  for (const kind of kinds) {
+    const doc = await readReferenceYaml(normalizedName, kind, opts);
+    if (!doc) continue;
+    const reference = parseReferenceYaml(doc.content, {
+      kind,
+      sourceUrl: doc.sourceUrl
+    });
+    markDefinedOn(reference, reference.name);
+    if (opts.includeInherited && reference.kind === "class") {
+      const inherited = await collectInheritedMembers(reference, opts, /* @__PURE__ */ new Set([reference.name]));
+      reference.inheritedClasses = inherited.classes;
+      reference.inheritedMembers = inherited.members;
     }
-  );
-  mcp.tool(
-    "serialize_ui",
-    "Serialize an existing Roblox UI tree into a compact, create_ui-compatible JSON tree. This is the reverse of create_ui \u2014 reads any GUI instance and returns a declarative JSON tree with ClassName, Name, non-default properties (Color3 as hex, UDim2 as arrays, etc.), and Children. Perfect for: converting existing UI to Roact/React components, cloning/templating, understanding UI structure, or refactoring. Use this INSTEAD of get_descendants_properties when you need to recreate or convert UI.",
-    {
-      path: z.string().describe('Instance path to serialize (e.g. "StarterGui.MyScreenGui")'),
-      maxDepth: z.number().optional().default(50).describe("Maximum tree depth (default 50)")
-    },
-    async ({ path: path2, maxDepth }) => {
-      assertConnected();
-      const res = await bridge.sendRequest(
-        CliMsg.SERIALIZE_UI,
-        { path: path2, maxDepth },
-        1e3 * 60 * 2
-      );
-      if (!res.payload.success) {
-        return { content: [{ type: "text", text: `Error: ${res.payload.error ?? "Serialization failed"}` }] };
-      }
-      return { content: [{ type: "text", text: JSON.stringify(res.payload.tree, null, 2) }] };
+    return reference;
+  }
+  throw new Error(`Roblox API reference not found for "${name}"`);
+}
+async function collectInheritedMembers(reference, opts, visited) {
+  const classes = [];
+  const members = {};
+  for (const parent of reference.inherits) {
+    if (!parent || visited.has(parent)) continue;
+    visited.add(parent);
+    const doc = await readReferenceYaml(parent, "class", opts);
+    if (!doc) continue;
+    const parentReference = parseReferenceYaml(doc.content, {
+      kind: "class",
+      sourceUrl: doc.sourceUrl
+    });
+    markDefinedOn(parentReference, parentReference.name);
+    classes.push(parentReference.name);
+    mergeMembers(members, parentReference.members);
+    const inherited = await collectInheritedMembers(parentReference, opts, visited);
+    classes.push(...inherited.classes);
+    mergeMembers(members, inherited.members);
+  }
+  return { classes, members };
+}
+function markDefinedOn(reference, className) {
+  for (const section of Object.values(reference.members)) {
+    for (const member of section) {
+      member.definedOn = className;
     }
-  );
-  mcp.tool(
-    "inspect_selection",
-    `Inspect the user's current selection in Roblox Studio. Returns the selected instance paths AND their properties (compact) in a single call. Use this FIRST when the user says "my selection", "what I selected", or "the selected thing". Much better than calling get_selection + get_properties separately.`,
-    {},
-    async () => {
-      assertConnected();
-      const selRes = await bridge.sendRequest(CliMsg.GET_SELECTION, {});
-      const paths = selRes.payload?.paths ?? [];
-      if (paths.length === 0) {
-        return { content: [{ type: "text", text: "No instances selected in Studio." }] };
-      }
-      const results = {};
-      for (const p of paths.slice(0, 10)) {
-        try {
-          const propRes = await bridge.sendRequest(
-            CliMsg.GET_PROPERTIES,
-            { path: p, compact: true }
-          );
-          results[p] = propRes.payload.properties ?? propRes.payload;
-        } catch {
-          results[p] = { error: "Failed to read properties" };
-        }
-      }
-      if (paths.length > 10) {
-        results["_truncated"] = `${paths.length - 10} more instances not shown`;
-      }
-      return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
+  }
+}
+function mergeMembers(target, source) {
+  for (const [section, members] of Object.entries(source)) {
+    target[section] ??= [];
+    target[section].push(...members);
+  }
+}
+async function searchRobloxApi(query, opts = {}) {
+  const limit = Math.max(1, Math.min(opts.limit ?? 10, 50));
+  const normalizedQuery = normalizeSearchText(query);
+  const kinds = opts.kind && opts.kind !== "any" ? [opts.kind] : Object.keys(KIND_FOLDERS);
+  const entries = await listReferenceEntries(opts);
+  return entries.filter((entry) => kinds.includes(entry.kind)).map((entry) => ({
+    ...entry,
+    score: scoreSearchResult(normalizedQuery, entry.name, entry.kind)
+  })).filter((entry) => entry.score > 0).sort((a, b) => b.score - a.score || a.name.localeCompare(b.name)).slice(0, limit);
+}
+function parseReferenceYaml(raw, opts = {}) {
+  const kind = opts.kind ?? normalizeKind(readTopScalar(raw, "type")) ?? "class";
+  const members = {};
+  for (const section of MEMBER_SECTIONS) {
+    const parsed = parseMemberSection(raw, section);
+    if (parsed.length > 0) {
+      members[section] = parsed;
     }
-  );
-  mcp.tool(
-    "inspect_instance",
-    "Inspect a single instance: returns its compact properties AND its children tree in one call. Combines get_properties + get_explorer into a single round-trip. Use when you need to understand an instance and its subtree.",
-    {
-      path: z.string().describe('Full instance path (e.g. "Workspace.MyModel")'),
-      childDepth: z.number().optional().default(2).describe("How deep to show the children tree (default 2)")
-    },
-    async ({ path: path2, childDepth }) => {
-      assertConnected();
-      const [propRes, treeRes] = await Promise.all([
-        bridge.sendRequest(
-          CliMsg.GET_PROPERTIES,
-          { path: path2, compact: true }
-        ),
-        bridge.sendRequest(
-          CliMsg.GET_EXPLORER,
-          { rootPath: path2, maxDepth: childDepth ?? 2 }
-        )
-      ]);
+  }
+  return {
+    name: readTopScalar(raw, "name") || "Unknown",
+    kind,
+    summary: cleanDocText(readTopScalar(raw, "summary")),
+    description: cleanDocText(readTopScalar(raw, "description")),
+    inherits: readTopList(raw, "inherits"),
+    tags: readTopList(raw, "tags"),
+    deprecationMessage: cleanDocText(readTopScalar(raw, "deprecation_message")),
+    sourceUrl: opts.sourceUrl ?? "",
+    members
+  };
+}
+function normalizeKind(value) {
+  if (value === "class" || value === "datatype" || value === "enum" || value === "global" || value === "library") {
+    return value;
+  }
+  return void 0;
+}
+async function readReferenceYaml(name, kind, opts) {
+  const localRoot = resolveDocsRoot(opts.docsRoot);
+  const folder = KIND_FOLDERS[kind];
+  const fileName = `${name}.yaml`;
+  if (localRoot) {
+    const localPath = path3.join(localRoot, folder, fileName);
+    if (fs3.existsSync(localPath)) {
       return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({
-            properties: propRes.payload.properties ?? propRes.payload,
-            children: treeRes.payload.tree ?? treeRes.payload
-          }, null, 2)
-        }]
+        content: fs3.readFileSync(localPath, "utf-8"),
+        sourceUrl: toCreatorDocsUrl(kind, name)
       };
     }
-  );
-  mcp.tool(
-    "convert_ui_to_code",
-    'Convert an existing Roblox UI tree into Roact/React-lua component code. Serializes the UI at the given path, then generates a ready-to-use Luau component. Use when the user asks to "turn this into a component", "convert to React", or "make a Roact version".',
-    {
-      path: z.string().describe('Path to the UI instance to convert (e.g. "StarterGui.MyScreenGui.MainFrame")'),
-      framework: z.enum(["roact", "react"]).optional().default("react").describe('Target framework: "roact" (legacy) or "react" (react-lua, default)'),
-      componentName: z.string().optional().describe("Name for the generated component (defaults to instance Name)")
-    },
-    async ({ path: path2, framework, componentName }) => {
-      assertConnected();
-      const res = await bridge.sendRequest(
-        CliMsg.SERIALIZE_UI,
-        { path: path2, maxDepth: 50 },
-        1e3 * 60 * 2
-      );
-      if (!res.payload.success || !res.payload.tree) {
-        return { content: [{ type: "text", text: `Error serializing UI: ${res.payload.error ?? "Unknown error"}` }] };
+  }
+  const sourceUrl = `${GITHUB_RAW_BASE}/${folder}/${encodeURIComponent(fileName)}`;
+  try {
+    return {
+      content: await fetchText(sourceUrl),
+      sourceUrl: toCreatorDocsUrl(kind, name)
+    };
+  } catch {
+    return null;
+  }
+}
+async function listReferenceEntries(opts) {
+  const localRoot = resolveDocsRoot(opts.docsRoot);
+  if (localRoot) {
+    const entries = [];
+    for (const [kind, folder] of Object.entries(KIND_FOLDERS)) {
+      const dir = path3.join(localRoot, folder);
+      if (!fs3.existsSync(dir)) continue;
+      for (const file of fs3.readdirSync(dir)) {
+        if (!file.endsWith(".yaml")) continue;
+        const name = path3.basename(file, ".yaml");
+        entries.push({ name, kind, score: 0, sourceUrl: toCreatorDocsUrl(kind, name) });
       }
-      const tree = res.payload.tree;
-      const name = componentName || tree.Name || "GeneratedComponent";
-      const fw = framework || "react";
-      const code = generateComponentCode(tree, name, fw);
-      return { content: [{ type: "text", text: code }] };
     }
-  );
-  mcp.tool(
-    "list_connections",
-    "List all Roblox Studio instances currently connected to Dominus. Shows placeId, placeName, and connection time for each. Use this when working with multiple Studio windows.",
-    {},
-    async () => {
-      const connections = bridge.listConnections();
-      const activePlaceId = bridge.getActivePlaceId();
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({
-            activePlaceId: activePlaceId || "auto",
-            connections: connections.map((c) => ({
-              ...c,
-              active: activePlaceId === 0 && connections.length === 1 ? true : c.placeId === activePlaceId
-            }))
-          }, null, 2)
-        }]
-      };
+    return entries;
+  }
+  const tree = await getRemoteTree();
+  const prefix = "content/en-us/reference/engine/";
+  return tree.filter((entry) => entry.type === "blob").map((entry) => entry.path).filter((entryPath) => entryPath.startsWith(prefix) && entryPath.endsWith(".yaml")).flatMap((entryPath) => {
+    const rest = entryPath.slice(prefix.length);
+    const [folder, file] = rest.split("/");
+    const kind = folderToKind(folder);
+    if (!kind || !file) return [];
+    const name = path3.basename(file, ".yaml");
+    return [{ name, kind, score: 0, sourceUrl: toCreatorDocsUrl(kind, name) }];
+  });
+}
+async function getRemoteTree() {
+  if (remoteTreeCache) return remoteTreeCache;
+  const payload = JSON.parse(await fetchText(GITHUB_TREE_URL));
+  remoteTreeCache = payload.tree ?? [];
+  return remoteTreeCache;
+}
+function folderToKind(folder) {
+  for (const [kind, value] of Object.entries(KIND_FOLDERS)) {
+    if (value === folder) return kind;
+  }
+  return void 0;
+}
+function resolveDocsRoot(explicitRoot) {
+  const candidates = [
+    explicitRoot,
+    process.env.ROBLOX_CREATOR_DOCS_PATH,
+    path3.join(process.cwd(), ".tmp", "creator-docs")
+  ].filter(Boolean);
+  for (const candidate of candidates) {
+    const normalized = normalizeDocsRoot(candidate);
+    if (normalized && fs3.existsSync(normalized)) return normalized;
+  }
+  return null;
+}
+function normalizeDocsRoot(root) {
+  const engineRoot = path3.join(root, "content", "en-us", "reference", "engine");
+  if (fs3.existsSync(engineRoot)) return engineRoot;
+  const directClasses = path3.join(root, "classes");
+  if (fs3.existsSync(directClasses)) return root;
+  return null;
+}
+function normalizeLookupName(name) {
+  const trimmed = name.trim();
+  const ownerName = trimmed.split(":")[0];
+  const lastToken = ownerName.split(".").pop() ?? ownerName;
+  return lastToken.replace(/[^A-Za-z0-9_]/g, "");
+}
+function normalizeSearchText(value) {
+  return value.trim().toLowerCase().replace(/[^a-z0-9_]+/g, "");
+}
+function scoreSearchResult(query, name, kind) {
+  if (!query) return 1;
+  const normalizedName = normalizeSearchText(name);
+  if (normalizedName === query) return 100;
+  if (normalizedName.startsWith(query)) return 75;
+  if (normalizedName.includes(query)) return 50;
+  const kindScore = kind.includes(query) ? 10 : 0;
+  return kindScore;
+}
+function toCreatorDocsUrl(kind, name) {
+  return `https://create.roblox.com/docs/reference/engine/${KIND_FOLDERS[kind]}/${name}`;
+}
+async function fetchText(url) {
+  const response = await fetch(url, {
+    headers: { "User-Agent": "Dominus Roblox API docs lookup" }
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
+  }
+  return response.text();
+}
+function readTopScalar(raw, key) {
+  const lines = raw.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const match = lines[i].match(new RegExp(`^${escapeRegExp(key)}:\\s*(.*)$`));
+    if (!match) continue;
+    return readYamlValue(lines, i, 0, match[1]);
+  }
+  return "";
+}
+function readTopList(raw, key) {
+  const lines = raw.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const match = lines[i].match(new RegExp(`^${escapeRegExp(key)}:\\s*(.*)$`));
+    if (!match) continue;
+    const inline = match[1].trim();
+    if (inline === "[]" || inline === "") {
+      if (inline === "[]") return [];
+      return readIndentedList(lines, i + 1, 2);
     }
-  );
-  mcp.tool(
-    "set_active_place",
-    "Set which Roblox Studio instance to target when multiple are connected. Pass placeId=0 to reset to auto mode (works when only one is connected). Call list_connections first to see available placeIds.",
-    {
-      placeId: z.number().describe("The placeId to target. Use 0 to reset to auto-select.")
-    },
-    async ({ placeId }) => {
-      const connections = bridge.listConnections();
-      if (placeId !== 0 && !connections.some((c) => c.placeId === placeId)) {
-        const available = connections.map((c) => `${c.placeName ?? "Unknown"} (${c.placeId})`).join(", ");
-        return {
-          content: [{
-            type: "text",
-            text: `Place ${placeId} is not connected. Available: ${available || "none"}`
-          }]
-        };
-      }
-      bridge.setActivePlaceId(placeId);
-      if (placeId === 0) {
-        return { content: [{ type: "text", text: "Active place reset to auto-select." }] };
-      }
-      const target = connections.find((c) => c.placeId === placeId);
-      return {
-        content: [{
-          type: "text",
-          text: `Active place set to ${target?.placeName ?? "Unknown"} (${placeId})`
-        }]
-      };
+    return [unquote(inline)];
+  }
+  return [];
+}
+function parseMemberSection(raw, section) {
+  const sectionLines = extractTopSection(raw, section);
+  if (sectionLines.length === 0) return [];
+  const items = splitMemberItems(sectionLines);
+  return items.map((item) => parseMemberItem(item, section)).filter((item) => Boolean(item));
+}
+function extractTopSection(raw, section) {
+  const lines = raw.split(/\r?\n/);
+  const start = lines.findIndex((line) => line === `${section}:`);
+  if (start === -1) return [];
+  const result = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^[A-Za-z_][A-Za-z0-9_]*:/.test(lines[i])) break;
+    result.push(lines[i]);
+  }
+  return result;
+}
+function splitMemberItems(lines) {
+  const items = [];
+  let current = [];
+  for (const line of lines) {
+    if (/^  - /.test(line)) {
+      if (current.length > 0) items.push(current);
+      current = [line];
+      continue;
     }
-  );
-  mcp.tool(
-    "recall_memory",
-    "Search persistent memory for facts about the current Roblox project",
-    { query: z.string().describe("What to search for") },
-    async ({ query }) => {
-      const facts = recallFacts("current", query, 15);
-      const scripts = getScriptIndex("current");
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({ facts: facts.map((f) => f.content), scriptIndex: scripts }, null, 2)
-        }]
-      };
+    if (current.length > 0) current.push(line);
+  }
+  if (current.length > 0) items.push(current);
+  return items;
+}
+function parseMemberItem(lines, section) {
+  const name = readMemberScalar(lines, "name");
+  if (!name) return null;
+  const member = {
+    name,
+    memberType: section,
+    type: readMemberScalar(lines, "type") || readMemberScalar(lines, "return_type"),
+    summary: cleanDocText(readMemberScalar(lines, "summary")),
+    description: cleanDocText(readMemberScalar(lines, "description")),
+    parameters: readNestedObjects(lines, "parameters"),
+    returns: readNestedObjects(lines, "returns"),
+    tags: readMemberList(lines, "tags"),
+    security: readSecurity(lines),
+    threadSafety: readMemberScalar(lines, "thread_safety"),
+    category: readMemberScalar(lines, "category"),
+    deprecationMessage: cleanDocText(readMemberScalar(lines, "deprecation_message"))
+  };
+  const value = Number(readMemberScalar(lines, "value"));
+  if (Number.isFinite(value)) member.value = value;
+  return member;
+}
+function readMemberScalar(lines, key) {
+  for (let i = 0; i < lines.length; i++) {
+    const firstLinePattern = new RegExp(`^  - ${escapeRegExp(key)}:\\s*(.*)$`);
+    const fieldPattern = new RegExp(`^    ${escapeRegExp(key)}:\\s*(.*)$`);
+    const firstLineMatch = lines[i].match(firstLinePattern);
+    const fieldMatch = lines[i].match(fieldPattern);
+    const match = firstLineMatch ?? fieldMatch;
+    if (!match) continue;
+    return readYamlValue(lines, i, firstLineMatch ? 2 : 4, match[1]);
+  }
+  return "";
+}
+function readMemberList(lines, key) {
+  for (let i = 0; i < lines.length; i++) {
+    const match = lines[i].match(new RegExp(`^    ${escapeRegExp(key)}:\\s*(.*)$`));
+    if (!match) continue;
+    const inline = match[1].trim();
+    if (inline === "[]") return [];
+    if (inline) return [unquote(inline)];
+    return readIndentedList(lines, i + 1, 6);
+  }
+  return [];
+}
+function readNestedObjects(lines, key) {
+  const start = lines.findIndex((line) => line === `    ${key}:`);
+  if (start === -1) return [];
+  const nested = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^    [A-Za-z_][A-Za-z0-9_]*:/.test(lines[i])) break;
+    nested.push(lines[i]);
+  }
+  const items = [];
+  let current = [];
+  for (const line of nested) {
+    if (/^      - /.test(line)) {
+      if (current.length > 0) items.push(current);
+      current = [line];
+      continue;
     }
-  );
-  mcp.tool(
-    "remember",
-    "Store a fact about the project in persistent memory for future sessions",
-    {
-      fact: z.string().describe("The fact to remember"),
-      category: z.enum(["architecture", "pattern", "preference", "bug", "api", "general"]).describe("Category")
+    if (current.length > 0) current.push(line);
+  }
+  if (current.length > 0) items.push(current);
+  return items.map((item) => ({
+    name: readNestedScalar(item, "name"),
+    type: readNestedScalar(item, "type"),
+    summary: cleanDocText(readNestedScalar(item, "summary")),
+    default: readNestedScalar(item, "default")
+  }));
+}
+function readNestedScalar(lines, key) {
+  for (let i = 0; i < lines.length; i++) {
+    const firstLinePattern = new RegExp(`^      - ${escapeRegExp(key)}:\\s*(.*)$`);
+    const fieldPattern = new RegExp(`^        ${escapeRegExp(key)}:\\s*(.*)$`);
+    const firstLineMatch = lines[i].match(firstLinePattern);
+    const fieldMatch = lines[i].match(fieldPattern);
+    const match = firstLineMatch ?? fieldMatch;
+    if (!match) continue;
+    return readYamlValue(lines, i, firstLineMatch ? 6 : 8, match[1]);
+  }
+  return "";
+}
+function readSecurity(lines) {
+  const start = lines.findIndex((line) => line === "    security:");
+  if (start === -1) return void 0;
+  return {
+    read: readIndentedScalar(lines, start + 1, "read", 6),
+    write: readIndentedScalar(lines, start + 1, "write", 6)
+  };
+}
+function readIndentedScalar(lines, start, key, indent) {
+  const pattern = new RegExp(`^\\s{${indent}}${escapeRegExp(key)}:\\s*(.*)$`);
+  for (let i = start; i < lines.length; i++) {
+    if (indentOf(lines[i]) < indent) break;
+    const match = lines[i].match(pattern);
+    if (match) return unquote(match[1].trim());
+  }
+  return "";
+}
+function readYamlValue(lines, index, indent, rawValue) {
+  const value = rawValue.trim();
+  if (value === "|-" || value === "|") {
+    return readBlock(lines, index + 1, indent + 2);
+  }
+  if (value === "''" || value === '""') return "";
+  return unquote(value);
+}
+function readBlock(lines, start, minIndent) {
+  const block = [];
+  for (let i = start; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() && indentOf(line) < minIndent) break;
+    block.push(line.slice(Math.min(minIndent, line.length)));
+  }
+  return block.join("\n").trim();
+}
+function readIndentedList(lines, start, indent) {
+  const pattern = new RegExp(`^\\s{${indent}}-\\s*(.*)$`);
+  const values = [];
+  for (let i = start; i < lines.length; i++) {
+    if (lines[i].trim() && indentOf(lines[i]) < indent) break;
+    const match = lines[i].match(pattern);
+    if (match) values.push(unquote(match[1].trim()));
+  }
+  return values;
+}
+function cleanDocText(value) {
+  return value.replace(/\r/g, "").replace(/[ \t]+\n/g, "\n").trim();
+}
+function indentOf(line) {
+  return line.match(/^ */)?.[0].length ?? 0;
+}
+function unquote(value) {
+  if (value.startsWith("'") && value.endsWith("'") || value.startsWith('"') && value.endsWith('"')) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// src/mcp/tools/docs.ts
+var kindSchema = z.enum(["any", "class", "datatype", "enum", "global", "library"]);
+function registerDocsTools(server) {
+  server.registerTool("roblox_search_api", {
+    title: "Search Roblox API",
+    description: "Search the official Roblox Creator Docs engine API mirror by exact or partial class, datatype, enum, global, or library name.",
+    inputSchema: {
+      query: z.string().min(1).max(100),
+      kind: kindSchema.optional().default("any"),
+      limit: z.number().int().min(1).max(25).optional().default(10)
     },
-    async ({ fact, category }) => {
-      const now = Date.now();
-      storeFact({ projectId: "current", content: fact, category, source: "mcp", relevance: 1, createdAt: now, accessedAt: now });
-      return { content: [{ type: "text", text: `Remembered: ${fact}` }] };
+    outputSchema: toolOutputSchema,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
+  }, async ({ query, kind, limit }) => {
+    try {
+      return success({ results: await searchRobloxApi(query, { kind, limit }) });
+    } catch (err) {
+      return failure(err);
     }
-  );
-  mcp.resource(
-    "studio://status",
-    "studio://status",
-    async () => {
-      const info = bridge.getConnectionInfo();
-      return {
-        contents: [{
-          uri: "studio://status",
-          text: JSON.stringify({
-            connected: bridge.isConnected(),
-            placeName: info?.placeName,
-            placeId: info?.placeId,
-            studioVersion: info?.studioVersion,
-            port: bridge.getPort()
-          }, null, 2),
-          mimeType: "application/json"
-        }]
-      };
+  });
+  server.registerTool("roblox_get_api", {
+    title: "Get Roblox API Reference",
+    description: "Read an official Roblox engine API reference including members, types, security, thread safety, inheritance, and source URL.",
+    inputSchema: {
+      name: z.string().min(1).max(100),
+      kind: kindSchema.optional().default("any"),
+      includeInherited: z.boolean().optional().default(true)
+    },
+    outputSchema: toolOutputSchema,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
+  }, async ({ name, kind, includeInherited }) => {
+    try {
+      const reference = await getRobloxApiReference(name, { kind, includeInherited });
+      return success({ reference });
+    } catch (err) {
+      return failure(err);
     }
-  );
-  const transport = new StdioServerTransport();
-  await mcp.connect(transport);
+  });
 }
-function assertConnected() {
-  if (!bridge.isConnected()) {
-    throw new Error(
-      "Roblox Studio is not connected. Open Studio and click the Dominus plugin Connect button."
-    );
+var propertiesSchema = z.record(z.unknown()).refine(
+  (properties) => Object.keys(properties).length <= 100,
+  "At most 100 properties are allowed per operation"
+);
+var setPropertiesOperation = z.object({
+  op: z.literal("setProperties"),
+  target: instanceRefSchema,
+  properties: propertiesSchema
+});
+var createOperation = z.object({
+  op: z.literal("create"),
+  parent: instanceRefSchema,
+  className: z.string().min(1).max(100),
+  name: z.string().min(1).max(256),
+  properties: propertiesSchema.optional()
+});
+var moveOperation = z.object({
+  op: z.literal("move"),
+  target: instanceRefSchema,
+  parent: instanceRefSchema
+});
+var mutationOperation = z.discriminatedUnion("op", [
+  setPropertiesOperation,
+  createOperation,
+  moveOperation
+]);
+var uiNodeSchema = z.lazy(() => z.object({
+  ClassName: z.string().min(1).max(100),
+  Name: z.string().min(1).max(256).optional(),
+  properties: propertiesSchema.optional(),
+  Children: z.array(uiNodeSchema).max(1e3).optional()
+}));
+function registerStudioTools(server, bridge) {
+  server.registerTool("studio_get_tree", {
+    title: "Inspect Studio Tree",
+    description: "Read a deterministic Studio hierarchy and receive stable instance refs. Use refs from this result in later calls.",
+    inputSchema: {
+      root: instanceRefSchema.optional(),
+      maxDepth: z.number().int().min(0).max(12).optional().default(3),
+      maxNodes: z.number().int().min(1).max(5e3).optional().default(1e3)
+    },
+    outputSchema: toolOutputSchema,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+  }, ({ root, maxDepth, maxNodes }) => callStudio(bridge, CliMsg.V2_GET_TREE, {
+    root: root ? ref(root) : void 0,
+    maxDepth,
+    maxNodes
+  }));
+  server.registerTool("studio_inspect", {
+    title: "Inspect Studio Instances",
+    description: "Read typed property values and immediate children for up to 20 instance refs. Returns writable metadata from live ReflectionService.",
+    inputSchema: {
+      targets: z.array(instanceRefSchema).min(1).max(20),
+      compact: z.boolean().optional().default(true)
+    },
+    outputSchema: toolOutputSchema,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+  }, ({ targets, compact }) => callStudio(bridge, CliMsg.V2_INSPECT, { targets, compact }));
+  server.registerTool("studio_get_selection", {
+    title: "Get Studio Selection",
+    description: "Return the user current Roblox Studio selection as stable instance refs.",
+    inputSchema: {},
+    outputSchema: toolOutputSchema,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+  }, () => callStudio(bridge, CliMsg.V2_GET_SELECTION, {}));
+  server.registerTool("studio_read_script", {
+    title: "Read Studio Script",
+    description: "Read a Script, LocalScript, or ModuleScript and receive its source plus a revision required for conflict-safe updates.",
+    inputSchema: { target: instanceRefSchema },
+    outputSchema: toolOutputSchema,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+  }, ({ target }) => callStudio(bridge, CliMsg.V2_READ_SCRIPT, { target }));
+  server.registerTool("studio_update_script", {
+    title: "Update Studio Script",
+    description: "Replace script source only if expectedRevision still matches the editor. Read the script again after updating to verify it.",
+    inputSchema: {
+      target: instanceRefSchema,
+      source: z.string().max(75e4),
+      expectedRevision: z.string().regex(/^\d+:[0-9a-f]{8}$/)
+    },
+    outputSchema: toolOutputSchema,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }
+  }, ({ target, source, expectedRevision }) => callStudio(
+    bridge,
+    CliMsg.V2_UPDATE_SCRIPT,
+    { target, source, expectedRevision },
+    6e4
+  ));
+  server.registerTool("studio_apply", {
+    title: "Apply Atomic Studio Mutations",
+    description: "Atomically set properties, create instances, and move instances. Any failed operation cancels and undoes the entire batch.",
+    inputSchema: { operations: z.array(mutationOperation).min(1).max(100) },
+    outputSchema: toolOutputSchema,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }
+  }, ({ operations }) => callStudio(bridge, CliMsg.V2_APPLY, { operations }, 6e4));
+  server.registerTool("studio_delete_instances", {
+    title: "Delete Studio Instances",
+    description: "Destructively delete up to 50 instances in one undoable recording. Only call when the user explicitly requested deletion or cleanup.",
+    inputSchema: {
+      targets: z.array(instanceRefSchema).min(1).max(50),
+      confirm: z.literal(true)
+    },
+    outputSchema: toolOutputSchema,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false }
+  }, ({ targets, confirm }) => callStudio(bridge, CliMsg.V2_DELETE, { targets, confirm }, 6e4));
+  server.registerTool("studio_build_ui", {
+    title: "Build Atomic Roblox UI",
+    description: "Build and validate a declarative UI tree off-tree, then commit it in one undoable operation. Existing UI is replaced only when replaceExisting is true.",
+    inputSchema: {
+      parent: instanceRefSchema.optional(),
+      tree: uiNodeSchema,
+      replaceExisting: z.boolean().optional().default(false),
+      maxDepth: z.number().int().min(1).max(50).optional().default(30),
+      maxNodes: z.number().int().min(1).max(3e3).optional().default(1e3)
+    },
+    outputSchema: toolOutputSchema,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false }
+  }, ({ parent, tree, replaceExisting, maxDepth, maxNodes }) => callStudio(
+    bridge,
+    CliMsg.V2_BUILD_UI,
+    { parent, tree, replaceExisting, maxDepth, maxNodes },
+    12e4
+  ));
+  server.registerTool("studio_snapshot_ui", {
+    title: "Snapshot Roblox UI",
+    description: "Serialize a live UI subtree into typed, studio_build_ui-compatible data for fidelity checks and read-back verification.",
+    inputSchema: {
+      target: instanceRefSchema,
+      maxDepth: z.number().int().min(0).max(50).optional().default(30)
+    },
+    outputSchema: toolOutputSchema,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+  }, ({ target, maxDepth }) => callStudio(bridge, CliMsg.V2_SNAPSHOT_UI, { target, maxDepth }, 12e4));
+  server.registerTool("studio_run_test", {
+    title: "Run Roblox Studio Test",
+    description: "Run a bounded StudioTestService run, play, or multiplayer scenario. The game test harness must call StudioTestService:EndTest with its result.",
+    inputSchema: {
+      mode: z.enum(["run", "play", "multiplayer"]).optional().default("run"),
+      args: z.unknown().optional(),
+      players: z.number().int().min(1).max(8).optional().default(1),
+      timeoutMs: z.number().int().min(5e3).max(6e5).optional().default(12e4)
+    },
+    outputSchema: toolOutputSchema,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }
+  }, ({ mode, args, players, timeoutMs }) => callStudio(
+    bridge,
+    CliMsg.V2_RUN_TEST,
+    { mode, args, players, timeoutMs },
+    timeoutMs + 15e3
+  ));
+  server.registerTool("studio_get_output", {
+    title: "Read Studio Output",
+    description: "Read the bounded Studio output buffer, optionally filtered by severity. Dominus transport messages are excluded.",
+    inputSchema: {
+      limit: z.number().int().min(1).max(500).optional().default(100),
+      level: z.enum(["info", "warn", "error"]).optional()
+    },
+    outputSchema: toolOutputSchema,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+  }, ({ limit, level }) => callStudio(bridge, CliMsg.V2_GET_OUTPUT, { limit, level }));
+  server.registerTool("studio_get_reflection", {
+    title: "Read Live Roblox Reflection",
+    description: "Read current ReflectionService fields for a class in the connected Studio, including Type, Display category, and permission metadata.",
+    inputSchema: { className: z.string().min(1).max(100) },
+    outputSchema: toolOutputSchema,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+  }, ({ className }) => callStudio(bridge, CliMsg.V2_GET_REFLECTION, { className }));
+}
+
+// src/mcp/server.ts
+var VERSION = "2.1.0";
+function createDominusMcpServer(bridge) {
+  const server = new McpServer({
+    name: "dominus-2",
+    version: VERSION
+  }, {
+    instructions: DOMINUS_MCP_INSTRUCTIONS
+  });
+  registerConnectionTools(server, bridge);
+  registerStudioTools(server, bridge);
+  registerDocsTools(server);
+  registerDominusResources(server, bridge);
+  return server;
+}
+async function createStudioBridge(port) {
+  if (await isPortInUse(port)) {
+    const client = new DominusClient(port);
+    await client.connect();
+    return client;
+  }
+  const server = new DominusServer(port);
+  try {
+    await server.start();
+    return server;
+  } catch (err) {
+    const error = err;
+    if (error.code !== "EADDRINUSE") throw err;
+    const client = new DominusClient(port);
+    await client.connect();
+    return client;
   }
 }
+async function startMcpServer() {
+  const config = loadConfig();
+  const bridge = await createStudioBridge(config.port);
+  const server = createDominusMcpServer(bridge);
+  const transport = new StdioServerTransport();
+  let stopped = false;
+  const stop = async () => {
+    if (stopped) return;
+    stopped = true;
+    await bridge.stop();
+  };
+  process.once("SIGINT", () => void stop().finally(() => process.exit(0)));
+  process.once("SIGTERM", () => void stop().finally(() => process.exit(0)));
+  await server.connect(transport);
+}
 
 // src/mcp/index.ts
 startMcpServer().catch((err) => {