@chrrxs/robloxstudio-mcp-inspector 2.19.0 → 2.20.0

package/dist/index.js

@@ -196,6 +196,9 @@ var init_bridge_service = __esm({
         }
         return removed;
       }
+      async unregisterInstanceIdEverywhere(instanceId) {
+        return this.unregisterInstanceId(instanceId);
+      }
       getInstances() {
         return Array.from(this.instances.values());
       }
@@ -451,13 +454,260 @@ var init_bridge_service = __esm({
   }
 });
 
+// ../core/dist/roblox-docs.js
+function isDocCategory(value) {
+  return DOC_CATEGORIES.includes(value);
+}
+function cacheGet(key) {
+  const entry = cache.get(key);
+  if (!entry)
+    return void 0;
+  const ttl = entry.notFound ? NEGATIVE_CACHE_TTL_MS : CACHE_TTL_MS;
+  if (Date.now() - entry.fetchedAt > ttl) {
+    cache.delete(key);
+    return void 0;
+  }
+  return entry;
+}
+function cacheSet(key, entry) {
+  if (cache.size >= MAX_CACHE_ENTRIES) {
+    const oldest = cache.keys().next().value;
+    if (oldest !== void 0)
+      cache.delete(oldest);
+  }
+  cache.set(key, entry);
+}
+function docUrl(category, name) {
+  return `${DOCS_BASE_URL}/${category}/${encodeURIComponent(name)}.md`;
+}
+async function fetchRobloxDoc(category, name) {
+  const key = `${category}/${name}`;
+  const cached = cacheGet(key);
+  if (cached) {
+    if (cached.notFound)
+      throw new DocNotFoundError(category, name);
+    return cached.content;
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  let response;
+  try {
+    response = await fetch(docUrl(category, name), {
+      signal: controller.signal,
+      headers: { Accept: "text/markdown, text/plain" }
+    });
+  } catch (error) {
+    throw new Error(`Failed to fetch Roblox docs for ${key}: ${error instanceof Error ? error.message : String(error)}`);
+  } finally {
+    clearTimeout(timer);
+  }
+  if (response.status === 404) {
+    cacheSet(key, { fetchedAt: Date.now(), notFound: true });
+    throw new DocNotFoundError(category, name);
+  }
+  if (!response.ok) {
+    throw new Error(`Failed to fetch Roblox docs for ${key}: HTTP ${response.status}`);
+  }
+  const content = await response.text();
+  cacheSet(key, { fetchedAt: Date.now(), content });
+  return content;
+}
+function listSections(markdown) {
+  const sections = [];
+  for (const line of markdown.split("\n")) {
+    const match = line.match(/^##\s+(.+?)\s*$/);
+    if (match)
+      sections.push(match[1]);
+  }
+  return sections;
+}
+function extractSection(markdown, section) {
+  const lines = markdown.split("\n");
+  const wanted = section.trim().toLowerCase();
+  let start = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const match = lines[i].match(/^##\s+(.+?)\s*$/);
+    if (match && match[1].toLowerCase() === wanted) {
+      start = i;
+      break;
+    }
+  }
+  if (start === -1)
+    return void 0;
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^##?\s+/.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start, end).join("\n").trimEnd();
+}
+async function getRobloxDoc(category, name, section) {
+  const markdown = await fetchRobloxDoc(category, name);
+  const sections = listSections(markdown);
+  if (section) {
+    const extracted = extractSection(markdown, section);
+    if (extracted === void 0) {
+      throw new Error(`Section "${section}" not found in ${category}/${name}. Available sections: ${sections.join(", ") || "(none)"}`);
+    }
+    return { content: extracted, truncated: false, sections };
+  }
+  if (markdown.length > MAX_DOC_CHARS) {
+    const head = markdown.slice(0, MAX_DOC_CHARS);
+    const note = `
+
+---
+[Truncated at ${MAX_DOC_CHARS} of ${markdown.length} characters. Re-request with the "section" parameter to read one section in full. Available sections: ${sections.join(", ")}]`;
+    return { content: head + note, truncated: true, sections };
+  }
+  return { content: markdown, truncated: false, sections };
+}
+var DOC_CATEGORIES, DOCS_BASE_URL, FETCH_TIMEOUT_MS, CACHE_TTL_MS, NEGATIVE_CACHE_TTL_MS, MAX_CACHE_ENTRIES, MAX_DOC_CHARS, cache, DocNotFoundError;
+var init_roblox_docs = __esm({
+  "../core/dist/roblox-docs.js"() {
+    "use strict";
+    DOC_CATEGORIES = ["classes", "enums", "datatypes", "libraries", "globals"];
+    DOCS_BASE_URL = "https://create.roblox.com/docs/reference/engine";
+    FETCH_TIMEOUT_MS = 15e3;
+    CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
+    NEGATIVE_CACHE_TTL_MS = 5 * 60 * 1e3;
+    MAX_CACHE_ENTRIES = 200;
+    MAX_DOC_CHARS = 5e4;
+    cache = /* @__PURE__ */ new Map();
+    DocNotFoundError = class extends Error {
+      constructor(category, name) {
+        super(`No Roblox documentation found for ${category}/${name}. Names are case-sensitive PascalCase (e.g. "ProximityPrompt", "TweenService"). Valid categories: ${DOC_CATEGORIES.join(", ")}.`);
+        this.name = "DocNotFoundError";
+      }
+    };
+  }
+});
+
+// ../core/dist/mcp-compat.js
+import { ErrorCode, ListResourceTemplatesRequestSchema, ListResourcesRequestSchema, McpError, ReadResourceRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+function registerResourceHandlers(server) {
+  server.registerCapabilities({ resources: {} });
+  server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+    resources: []
+  }));
+  server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
+    resourceTemplates: [
+      {
+        uriTemplate: "robloxdocs://classes/{className}",
+        name: "Roblox class documentation",
+        description: "Official engine reference for a class (e.g. robloxdocs://classes/ProximityPrompt) \u2014 properties, methods, events, and usage guidance as markdown.",
+        mimeType: "text/markdown"
+      },
+      {
+        uriTemplate: "robloxdocs://enums/{enumName}",
+        name: "Roblox enum documentation",
+        description: "Official engine reference for an enum (e.g. robloxdocs://enums/KeyCode).",
+        mimeType: "text/markdown"
+      },
+      {
+        uriTemplate: "robloxdocs://datatypes/{dataTypeName}",
+        name: "Roblox datatype documentation",
+        description: "Official engine reference for a datatype (e.g. robloxdocs://datatypes/CFrame).",
+        mimeType: "text/markdown"
+      },
+      {
+        uriTemplate: "robloxdocs://libraries/{libraryName}",
+        name: "Roblox library documentation",
+        description: "Official engine reference for a Luau library (e.g. robloxdocs://libraries/table).",
+        mimeType: "text/markdown"
+      },
+      {
+        uriTemplate: "robloxdocs://globals/{globalsPage}",
+        name: "Roblox globals documentation",
+        description: "Official engine reference for global functions and variables (e.g. robloxdocs://globals/LuaGlobals, robloxdocs://globals/RobloxGlobals).",
+        mimeType: "text/markdown"
+      }
+    ]
+  }));
+  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const uri = request.params.uri;
+    const match = uri.match(/^robloxdocs:\/\/([^/]+)\/([^/]+)$/);
+    if (!match || !isDocCategory(match[1])) {
+      throw new McpError(ErrorCode.InvalidParams, `Resource ${uri} not found`);
+    }
+    const [, category, rawName] = match;
+    const name = decodeURIComponent(rawName);
+    try {
+      const content = await fetchRobloxDoc(category, name);
+      return {
+        contents: [{ uri, mimeType: "text/markdown", text: content }]
+      };
+    } catch (error) {
+      if (error instanceof DocNotFoundError) {
+        throw new McpError(ErrorCode.InvalidParams, `Resource ${uri} not found. Names are case-sensitive PascalCase; valid categories: ${DOC_CATEGORIES.join(", ")}.`);
+      }
+      throw new McpError(ErrorCode.InternalError, `Failed to read ${uri}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  });
+}
+var init_mcp_compat = __esm({
+  "../core/dist/mcp-compat.js"() {
+    "use strict";
+    init_roblox_docs();
+  }
+});
+
 // ../core/dist/http-server.js
 import express from "express";
 import cors from "cors";
 import http from "http";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ErrorCode as ErrorCode2, ListToolsRequestSchema, McpError as McpError2 } from "@modelcontextprotocol/sdk/types.js";
+function parseLineRange(lineRange) {
+  const validLine = (line) => line === void 0 || line >= 1;
+  if (typeof lineRange === "string") {
+    const ranged = lineRange.match(/^\s*(\d+)?\s*[-:]\s*(\d+)?\s*$/);
+    if (ranged) {
+      const s = ranged[1] !== void 0 ? parseInt(ranged[1], 10) : void 0;
+      const e = ranged[2] !== void 0 ? parseInt(ranged[2], 10) : void 0;
+      if (!validLine(s) || !validLine(e))
+        return void 0;
+      if (s !== void 0 && e !== void 0 && s > e)
+        return void 0;
+      if (s !== void 0 || e !== void 0)
+        return { startLine: s, endLine: e };
+    }
+    const single = lineRange.match(/^\s*(\d+)\s*$/);
+    if (single) {
+      const n = parseInt(single[1], 10);
+      if (n < 1)
+        return void 0;
+      return { startLine: n, endLine: n };
+    }
+  }
+  return void 0;
+}
+function optionalLineRange(body, toolName) {
+  if (body.line_range === void 0)
+    return {};
+  const parsed = parseLineRange(body.line_range);
+  if (!parsed)
+    throw new Error(`${toolName} line_range must be a string like "42", "10-20", "10-", or "-20"`);
+  return parsed;
+}
+function optionalLineAnchor(body, toolName) {
+  const parsed = optionalLineRange(body, toolName);
+  if (parsed.startLine === void 0 && parsed.endLine === void 0)
+    return void 0;
+  if (parsed.startLine === void 0 || parsed.endLine === void 0 || parsed.endLine !== parsed.startLine) {
+    throw new Error(`${toolName} line_range must be a single line like "42"`);
+  }
+  return parsed.startLine;
+}
+function requiredClosedLineRange(body, toolName) {
+  const parsed = optionalLineRange(body, toolName);
+  if (parsed.startLine === void 0 || parsed.endLine === void 0) {
+    throw new Error(`${toolName} requires line_range as "start-end" or a single line like "42"`);
+  }
+  return { startLine: parsed.startLine, endLine: parsed.endLine };
+}
 function createHttpServer(tools, bridge, allowedTools, serverConfig) {
   const app = express();
   let mcpServerActive = false;
@@ -590,6 +840,15 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig) {
     }
     res.json({ success: true });
   });
+  app.post("/unregister-instance-id", (req, res) => {
+    const { instanceId } = req.body;
+    if (typeof instanceId !== "string" || instanceId.length === 0) {
+      res.status(400).json({ error: "instanceId is required" });
+      return;
+    }
+    const removed = bridge.unregisterInstanceId(instanceId);
+    res.json({ success: true, removed });
+  });
   app.get("/status", (req, res) => {
     const instances = bridge.getInstances();
     const publicInstances = instances.map(toPublic);
@@ -707,6 +966,7 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig) {
       try {
         trackMCPActivity();
         const server = new Server({ name: serverConfig.name, version: serverConfig.version }, { capabilities: { tools: {} } });
+        registerResourceHandlers(server);
         server.setRequestHandler(ListToolsRequestSchema, async () => ({
           tools: filteredTools.map((t) => ({
             name: t.name,
@@ -717,11 +977,11 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig) {
         server.setRequestHandler(CallToolRequestSchema, async (request) => {
           const { name, arguments: args } = request.params;
           if (allowedTools && !allowedTools.has(name)) {
-            throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+            throw new McpError2(ErrorCode2.MethodNotFound, `Unknown tool: ${name}`);
           }
           const handler = TOOL_HANDLERS[name];
           if (!handler) {
-            throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+            throw new McpError2(ErrorCode2.MethodNotFound, `Unknown tool: ${name}`);
           }
           try {
             return await handler(tools, args || {});
@@ -739,9 +999,9 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig) {
                 isError: true
               };
             }
-            if (error instanceof McpError)
+            if (error instanceof McpError2)
               throw error;
-            throw new McpError(ErrorCode.InternalError, `Tool execution failed: ${error instanceof Error ? error.message : String(error)}`);
+            throw new McpError2(ErrorCode2.InternalError, `Tool execution failed: ${error instanceof Error ? error.message : String(error)}`);
           }
         });
         const transport = new StreamableHTTPServerTransport({
@@ -847,7 +1107,9 @@ var init_http_server = __esm({
   "../core/dist/http-server.js"() {
     "use strict";
     init_bridge_service();
+    init_mcp_compat();
     TOOL_HANDLERS = {
+      get_roblox_docs: (tools, body) => tools.getRobloxDocs(body.name, body.doc_type, body.section),
       get_file_tree: (tools, body) => tools.getFileTree(body.path, body.instance_id),
       search_files: (tools, body) => tools.searchFiles(body.query, body.searchType, body.instance_id),
       get_place_info: (tools, body) => tools.getPlaceInfo(body.instance_id),
@@ -877,11 +1139,17 @@ var init_http_server = __esm({
         path: body.path,
         classFilter: body.classFilter
       }, body.instance_id),
-      get_script_source: (tools, body) => tools.getScriptSource(body.instancePath, body.startLine, body.endLine, body.instance_id),
+      get_script_source: (tools, body) => {
+        const { startLine, endLine } = optionalLineRange(body, "get_script_source");
+        return tools.getScriptSource(body.instancePath, startLine, endLine, body.instance_id);
+      },
       set_script_source: (tools, body) => tools.setScriptSource(body.instancePath, body.source, body.instance_id),
-      edit_script_lines: (tools, body) => tools.editScriptLines(body.instancePath, body.old_string, body.new_string, body.startLine, body.instance_id),
+      edit_script_lines: (tools, body) => tools.editScriptLines(body.instancePath, body.old_string, body.new_string, optionalLineAnchor(body, "edit_script_lines"), body.instance_id),
       insert_script_lines: (tools, body) => tools.insertScriptLines(body.instancePath, body.afterLine, body.newContent, body.instance_id),
-      delete_script_lines: (tools, body) => tools.deleteScriptLines(body.instancePath, body.startLine, body.endLine, body.instance_id),
+      delete_script_lines: (tools, body) => {
+        const { startLine, endLine } = requiredClosedLineRange(body, "delete_script_lines");
+        return tools.deleteScriptLines(body.instancePath, startLine, endLine, body.instance_id);
+      },
       set_attribute: (tools, body) => tools.setAttribute(body.instancePath, body.attributeName, body.attributeValue, body.valueType, body.instance_id),
       get_attributes: (tools, body) => tools.getAttributes(body.instancePath, body.instance_id),
       delete_attribute: (tools, body) => tools.deleteAttribute(body.instancePath, body.attributeName, body.instance_id),
@@ -903,8 +1171,8 @@ var init_http_server = __esm({
       solo_playtest: (tools, body) => tools.soloPlaytest(body.action, body.mode, body.timeout, body.instance_id),
       start_playtest: (tools, body) => tools.startPlaytest(body.mode, body.numPlayers, body.instance_id),
       stop_playtest: (tools, body) => tools.stopPlaytest(body.instance_id),
-      multiplayer_playtest: (tools, body) => tools.multiplayerPlaytest(body.action, body.numPlayers, body.target, body.testArgs, body.value, body.timeout, body.instance_id),
-      multiplayer_test_start: (tools, body) => tools.multiplayerTestStart(body.numPlayers, body.testArgs, body.timeout, body.instance_id),
+      multiplayer_playtest: (tools, body) => tools.multiplayerPlaytest(body.action, body.numPlayers, body.target, body.testArgs, body.value, body.timeout, body.instance_id, body.force),
+      multiplayer_test_start: (tools, body) => tools.multiplayerTestStart(body.numPlayers, body.testArgs, body.timeout, body.instance_id, body.force),
       multiplayer_test_state: (tools, body) => tools.multiplayerTestState(body.instance_id),
       multiplayer_test_add_players: (tools, body) => tools.multiplayerTestAddPlayers(body.numPlayers, body.timeout, body.instance_id),
       multiplayer_test_leave_client: (tools, body) => tools.multiplayerTestLeaveClient(body.target, body.timeout, body.instance_id),
@@ -1739,11 +2007,300 @@ var init_roblox_cookie_client = __esm({
   }
 });
 
-// ../core/dist/studio-instance-manager.js
-import { execFileSync, spawn } from "child_process";
-import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync } from "fs";
+// ../core/dist/managed-instance-registry.js
+import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
+function defaultManagedInstanceRegistryDir() {
+  if (process.env.ROBLOXSTUDIO_MCP_MANAGED_INSTANCE_REGISTRY_DIR) {
+    return process.env.ROBLOXSTUDIO_MCP_MANAGED_INSTANCE_REGISTRY_DIR;
+  }
+  if (process.platform === "win32" && process.env.LOCALAPPDATA) {
+    return path.join(process.env.LOCALAPPDATA, "robloxstudio-mcp", "managed-instances", "v1");
+  }
+  if (process.platform === "darwin") {
+    return path.join(os.homedir(), "Library", "Application Support", "robloxstudio-mcp", "managed-instances", "v1");
+  }
+  return path.join(os.homedir(), ".local", "state", "robloxstudio-mcp", "managed-instances", "v1");
+}
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function ymd(timestamp) {
+  return new Date(timestamp).toISOString().slice(0, 10);
+}
+function eventLogDate(name) {
+  const match = name.match(/^events-(\d{4}-\d{2}-\d{2})\.jsonl$/);
+  return match?.[1];
+}
+function isRecord(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const record = value;
+  return record.version === REGISTRY_VERSION && typeof record.recordId === "string" && typeof record.source === "string" && typeof record.exe === "string" && Array.isArray(record.args) && typeof record.launchedAt === "number" && typeof record.bootId === "string";
+}
+var REGISTRY_VERSION, LOCK_STALE_MS, LOCK_RETRY_MS, LOCK_TIMEOUT_MS, EVENT_RETENTION_DAYS, ManagedInstanceRegistry;
+var init_managed_instance_registry = __esm({
+  "../core/dist/managed-instance-registry.js"() {
+    "use strict";
+    REGISTRY_VERSION = 1;
+    LOCK_STALE_MS = 1e4;
+    LOCK_RETRY_MS = 25;
+    LOCK_TIMEOUT_MS = 5e3;
+    EVENT_RETENTION_DAYS = 2;
+    ManagedInstanceRegistry = class {
+      dir;
+      constructor(dir = defaultManagedInstanceRegistryDir()) {
+        this.dir = dir;
+      }
+      upsert(record) {
+        this.withLock(() => this.writeRecordUnlocked(record));
+      }
+      attachInstanceId(recordId, instanceId) {
+        this.withLock(() => {
+          const record = this.readRecordUnlocked(recordId);
+          if (!record)
+            return;
+          record.instanceId = instanceId;
+          record.attachedAt = Date.now();
+          this.writeRecordUnlocked(record);
+        });
+      }
+      findOpenByInstanceId(instanceId, options) {
+        return this.withLock(() => {
+          this.sweepUnlocked(options);
+          return this.readOpenRecordsUnlocked().find((record) => record.instanceId === instanceId);
+        });
+      }
+      findAnyByInstanceId(instanceId) {
+        return this.withLock(() => this.readRecordsUnlocked().find((record) => record.instanceId === instanceId));
+      }
+      listOpen(options) {
+        return this.withLock(() => {
+          this.sweepUnlocked(options);
+          return this.readOpenRecordsUnlocked();
+        });
+      }
+      markClosed(recordId, closedAt = Date.now()) {
+        this.withLock(() => {
+          const record = this.readRecordUnlocked(recordId);
+          if (!record)
+            return;
+          record.closedAt = closedAt;
+          this.writeRecordUnlocked(record);
+        });
+      }
+      delete(recordId) {
+        this.withLock(() => this.deleteRecordUnlocked(recordId));
+      }
+      sweep(options) {
+        this.withLock(() => this.sweepUnlocked(options));
+      }
+      logEvent(event, now = Date.now()) {
+        this.withLock(() => this.appendEventUnlocked(event, now));
+      }
+      withLock(fn) {
+        this.ensureDir();
+        const lockDir = path.join(this.dir, ".lock");
+        const deadline = Date.now() + LOCK_TIMEOUT_MS;
+        while (true) {
+          try {
+            fs.mkdirSync(lockDir);
+            break;
+          } catch (error) {
+            const code = error.code;
+            if (code !== "EEXIST")
+              throw error;
+            try {
+              const stat = fs.statSync(lockDir);
+              if (Date.now() - stat.mtimeMs > LOCK_STALE_MS) {
+                fs.rmSync(lockDir, { recursive: true, force: true });
+                continue;
+              }
+            } catch {
+              continue;
+            }
+            if (Date.now() > deadline) {
+              throw new Error(`Timed out waiting for managed instance registry lock: ${lockDir}`);
+            }
+            sleepSync(LOCK_RETRY_MS);
+          }
+        }
+        try {
+          return fn();
+        } finally {
+          fs.rmSync(lockDir, { recursive: true, force: true });
+        }
+      }
+      ensureDir() {
+        fs.mkdirSync(this.dir, { recursive: true });
+      }
+      recordPath(recordId) {
+        return path.join(this.dir, `${recordId}.json`);
+      }
+      recordFilesUnlocked() {
+        return fs.readdirSync(this.dir).filter((name) => name.endsWith(".json")).map((name) => path.join(this.dir, name));
+      }
+      readRecordUnlocked(recordId) {
+        try {
+          const parsed = JSON.parse(fs.readFileSync(this.recordPath(recordId), "utf8"));
+          return isRecord(parsed) ? parsed : void 0;
+        } catch {
+          return void 0;
+        }
+      }
+      readOpenRecordsUnlocked() {
+        return this.readRecordsUnlocked().filter((record) => record.closedAt === void 0);
+      }
+      readRecordsUnlocked() {
+        const records = [];
+        for (const file of this.recordFilesUnlocked()) {
+          try {
+            const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+            if (!isRecord(parsed))
+              continue;
+            records.push(parsed);
+          } catch {
+          }
+        }
+        return records;
+      }
+      writeRecordUnlocked(record) {
+        this.ensureDir();
+        const finalPath = this.recordPath(record.recordId);
+        const tmpPath = path.join(this.dir, `${record.recordId}.${process.pid}.${Date.now()}.tmp`);
+        const fd = fs.openSync(tmpPath, "w");
+        try {
+          fs.writeFileSync(fd, `${JSON.stringify(record, null, 2)}
+`, "utf8");
+          fs.fsyncSync(fd);
+        } finally {
+          fs.closeSync(fd);
+        }
+        fs.renameSync(tmpPath, finalPath);
+      }
+      deleteRecordUnlocked(recordId) {
+        fs.rmSync(this.recordPath(recordId), { force: true });
+      }
+      appendEventUnlocked(event, now) {
+        const file = path.join(this.dir, `events-${ymd(now)}.jsonl`);
+        fs.appendFileSync(file, `${JSON.stringify({
+          ts: new Date(now).toISOString(),
+          ...event
+        })}
+`, "utf8");
+      }
+      cleanupOldEventLogsUnlocked(now) {
+        const cutoff = ymd(now - EVENT_RETENTION_DAYS * 24 * 60 * 60 * 1e3);
+        for (const name of fs.readdirSync(this.dir)) {
+          const date = eventLogDate(name);
+          if (!date || date >= cutoff)
+            continue;
+          try {
+            fs.rmSync(path.join(this.dir, name), { force: true });
+          } catch {
+          }
+        }
+      }
+      cleanupRecord(options, record) {
+        try {
+          options.cleanupRecord?.(record);
+        } catch {
+          this.appendEventUnlocked({
+            event: "registry_cleanup_failed",
+            recordId: record.recordId,
+            instanceId: record.instanceId,
+            source: record.source,
+            reason: "cleanup_record_error"
+          }, options.now ?? Date.now());
+        }
+      }
+      sweepUnlocked(options) {
+        const now = options.now ?? Date.now();
+        this.cleanupOldEventLogsUnlocked(now);
+        for (const file of this.recordFilesUnlocked()) {
+          let parsed;
+          try {
+            parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+          } catch {
+            fs.rmSync(file, { force: true });
+            this.appendEventUnlocked({
+              event: "registry_pruned_malformed_record",
+              reason: "parse_error",
+              action: "deleted_record"
+            }, now);
+            continue;
+          }
+          if (!parsed || typeof parsed !== "object") {
+            fs.rmSync(file, { force: true });
+            this.appendEventUnlocked({
+              event: "registry_pruned_malformed_record",
+              reason: "invalid_shape",
+              action: "deleted_record"
+            }, now);
+            continue;
+          }
+          const version = parsed.version;
+          if (typeof version === "number" && version > REGISTRY_VERSION)
+            continue;
+          if (!isRecord(parsed)) {
+            fs.rmSync(file, { force: true });
+            this.appendEventUnlocked({
+              event: "registry_pruned_malformed_record",
+              reason: "invalid_shape",
+              action: "deleted_record"
+            }, now);
+            continue;
+          }
+          if (parsed.closedAt !== void 0) {
+            fs.rmSync(file, { force: true });
+            this.appendEventUnlocked({
+              event: "registry_pruned_closed_record",
+              recordId: parsed.recordId,
+              instanceId: parsed.instanceId,
+              source: parsed.source,
+              reason: "closed_at_present",
+              action: "deleted_record"
+            }, now);
+            continue;
+          }
+          if (parsed.bootId !== options.currentBootId) {
+            this.cleanupRecord(options, parsed);
+            fs.rmSync(file, { force: true });
+            this.appendEventUnlocked({
+              event: "registry_pruned_previous_boot",
+              recordId: parsed.recordId,
+              instanceId: parsed.instanceId,
+              source: parsed.source,
+              reason: "boot_id_changed",
+              action: "deleted_record_and_cleaned_baseplate"
+            }, now);
+            continue;
+          }
+          if (options.isProcessRunning && (parsed.nativeProcessId || parsed.spawnPid) && !options.isProcessRunning(parsed)) {
+            this.cleanupRecord(options, parsed);
+            fs.rmSync(file, { force: true });
+            this.appendEventUnlocked({
+              event: "registry_pruned_stale_process",
+              recordId: parsed.recordId,
+              instanceId: parsed.instanceId,
+              source: parsed.source,
+              reason: "pid_not_running",
+              action: "deleted_record_and_cleaned_baseplate"
+            }, now);
+          }
+        }
+      }
+    };
+  }
+});
+
+// ../core/dist/studio-instance-manager.js
+import { execFileSync, spawn } from "child_process";
+import { copyFileSync, existsSync, mkdirSync as mkdirSync2, readdirSync as readdirSync2, readFileSync as readFileSync2, realpathSync, rmSync as rmSync2, statSync as statSync2 } from "fs";
+import { randomUUID } from "crypto";
+import * as os2 from "os";
+import * as path2 from "path";
 function run(command, args, options = {}) {
   return execFileSync(command, args, {
     encoding: "utf8",
@@ -1755,7 +2312,7 @@ function isWsl() {
   if (process.platform !== "linux")
     return false;
   try {
-    return /microsoft|wsl/i.test(readFileSync("/proc/version", "utf8"));
+    return /microsoft|wsl/i.test(readFileSync2("/proc/version", "utf8"));
   } catch {
     return false;
   }
@@ -1784,7 +2341,7 @@ function toWslPath(windowsPath) {
   return run("wslpath", ["-u", windowsPath]);
 }
 function toStudioLaunchArg(arg) {
-  if (!isWsl() || !path.isAbsolute(arg) || !existsSync(arg))
+  if (!isWsl() || !path2.isAbsolute(arg) || !existsSync(arg))
     return arg;
   return run("wslpath", ["-w", arg]);
 }
@@ -1793,21 +2350,21 @@ function resolveEntrypointDir() {
   if (!entrypoint)
     return void 0;
   try {
-    return path.dirname(realpathSync(entrypoint));
+    return path2.dirname(realpathSync(entrypoint));
   } catch {
-    return path.dirname(path.resolve(entrypoint));
+    return path2.dirname(path2.resolve(entrypoint));
   }
 }
 function resolveBaseplateTemplatePath() {
   const entrypointDir = resolveEntrypointDir();
   const candidates = [
     ...entrypointDir ? [
-      path.join(entrypointDir, "assets", BASEPLATE_TEMPLATE_NAME),
-      path.join(entrypointDir, "..", "assets", BASEPLATE_TEMPLATE_NAME)
+      path2.join(entrypointDir, "assets", BASEPLATE_TEMPLATE_NAME),
+      path2.join(entrypointDir, "..", "assets", BASEPLATE_TEMPLATE_NAME)
     ] : [],
-    path.join(process.cwd(), "packages", "core", "assets", BASEPLATE_TEMPLATE_NAME),
-    path.join(process.cwd(), "packages", "robloxstudio-mcp", "dist", "assets", BASEPLATE_TEMPLATE_NAME),
-    path.join(process.cwd(), "assets", BASEPLATE_TEMPLATE_NAME)
+    path2.join(process.cwd(), "packages", "core", "assets", BASEPLATE_TEMPLATE_NAME),
+    path2.join(process.cwd(), "packages", "robloxstudio-mcp", "dist", "assets", BASEPLATE_TEMPLATE_NAME),
+    path2.join(process.cwd(), "assets", BASEPLATE_TEMPLATE_NAME)
   ];
   for (const candidate of candidates) {
     if (existsSync(candidate))
@@ -1816,22 +2373,22 @@ function resolveBaseplateTemplatePath() {
   throw new Error(`Baseplate template not found. Expected ${BASEPLATE_TEMPLATE_NAME} in one of: ${candidates.join(", ")}`);
 }
 function createBaseplatePlaceFile() {
-  mkdirSync(BASEPLATE_TEMP_DIR, { recursive: true });
-  const file = path.join(BASEPLATE_TEMP_DIR, `Baseplate-${process.pid}-${Date.now()}.rbxl`);
+  mkdirSync2(BASEPLATE_TEMP_DIR, { recursive: true });
+  const file = path2.join(BASEPLATE_TEMP_DIR, `Baseplate-${process.pid}-${Date.now()}.rbxl`);
   copyFileSync(resolveBaseplateTemplatePath(), file);
   return file;
 }
 function isGeneratedBaseplatePlaceFile(file) {
-  const resolvedFile = path.resolve(file);
-  return path.dirname(resolvedFile) === path.resolve(BASEPLATE_TEMP_DIR) && BASEPLATE_TEMP_NAME.test(path.basename(resolvedFile));
+  const resolvedFile = path2.resolve(file);
+  return path2.dirname(resolvedFile) === path2.resolve(BASEPLATE_TEMP_DIR) && BASEPLATE_TEMP_NAME.test(path2.basename(resolvedFile));
 }
 function cleanupManagedBaseplateFiles(record) {
   if (record.source !== "baseplate" || !record.localPlaceFile)
     return;
   if (!isGeneratedBaseplatePlaceFile(record.localPlaceFile))
     return;
-  rmSync(record.localPlaceFile, { force: true });
-  rmSync(`${record.localPlaceFile}.lock`, { force: true });
+  rmSync2(record.localPlaceFile, { force: true });
+  rmSync2(`${record.localPlaceFile}.lock`, { force: true });
 }
 function prepareStudioLaunchOptions(options) {
   if (options.source !== "baseplate" || options.localPlaceFile)
@@ -1851,11 +2408,11 @@ function resolveStudioExe() {
     throw new Error("Roblox Studio executable auto-discovery is only supported on Windows, WSL, and macOS. Set ROBLOX_STUDIO_EXE.");
   }
   const localAppData = windowsLocalAppData();
-  const root = localAppData ? path.join(toWslPath(localAppData), "Roblox", "Versions") : path.join(os.homedir(), "AppData", "Local", "Roblox", "Versions");
+  const root = localAppData ? path2.join(toWslPath(localAppData), "Roblox", "Versions") : path2.join(os2.homedir(), "AppData", "Local", "Roblox", "Versions");
   if (!existsSync(root)) {
     throw new Error(`Roblox Studio Versions folder not found: ${root}. Set ROBLOX_STUDIO_EXE.`);
   }
-  const candidates = readdirSync(root).filter((name) => name.startsWith("version-")).map((name) => path.join(root, name, "RobloxStudioBeta.exe")).filter((candidate) => existsSync(candidate)).sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
+  const candidates = readdirSync2(root).filter((name) => name.startsWith("version-")).map((name) => path2.join(root, name, "RobloxStudioBeta.exe")).filter((candidate) => existsSync(candidate)).sort((a, b) => statSync2(b).mtimeMs - statSync2(a).mtimeMs);
   if (candidates.length === 0) {
     throw new Error(`RobloxStudioBeta.exe not found under ${root}. Set ROBLOX_STUDIO_EXE.`);
   }
@@ -1871,14 +2428,14 @@ function listStudioProcesses() {
     }
     return out2.split("\n").filter(Boolean).map((line) => {
       const [pid, ...rest] = line.trim().split(/\s+/);
-      return { Id: Number(pid), Path: rest.join(" "), MainWindowTitle: "" };
+      return { Id: Number(pid), Name: "RobloxStudio", Path: rest.join(" "), MainWindowTitle: "" };
     }).filter((proc) => Number.isFinite(proc.Id));
   }
   if (process.platform !== "win32" && !isWsl())
     return [];
   let out = "";
   try {
-    out = powershell("Get-Process RobloxStudioBeta -ErrorAction SilentlyContinue | Select-Object Id,Path,MainWindowTitle | ConvertTo-Json -Compress");
+    out = powershell("Get-Process RobloxStudioBeta -ErrorAction SilentlyContinue | Select-Object Id,Name,Path,MainWindowTitle | ConvertTo-Json -Compress");
   } catch {
     return [];
   }
@@ -1887,6 +2444,27 @@ function listStudioProcesses() {
   const parsed = JSON.parse(out);
   return Array.isArray(parsed) ? parsed : [parsed];
 }
+function currentBootId() {
+  if (process.platform === "linux") {
+    try {
+      return readFileSync2("/proc/sys/kernel/random/boot_id", "utf8").trim();
+    } catch {
+    }
+  }
+  if (process.platform === "win32" || isWsl()) {
+    try {
+      return powershell('(Get-CimInstance Win32_OperatingSystem).LastBootUpTime.ToUniversalTime().ToString("o")');
+    } catch {
+    }
+  }
+  if (process.platform === "darwin") {
+    try {
+      return run("sysctl", ["-n", "kern.boottime"]);
+    } catch {
+    }
+  }
+  return `${process.platform}:${os2.hostname()}:unknown-boot`;
+}
 function buildStudioLaunchArgs(options) {
   switch (options.source) {
     case "baseplate":
@@ -1899,13 +2477,13 @@ function buildStudioLaunchArgs(options) {
       if (!options.placeId)
         throw new Error('place_id is required when source="published_place".');
       if (!options.universeId)
-        throw new Error('universe_id is required when source="published_place".');
+        throw new Error('Derived universe id is required when source="published_place".');
       return ["--task", "EditPlace", "--placeId", String(options.placeId), "--universeId", String(options.universeId)];
     case "place_revision":
       if (!options.placeId)
         throw new Error('place_id is required when source="place_revision".');
       if (!options.universeId)
-        throw new Error('universe_id is required when source="place_revision".');
+        throw new Error('Derived universe id is required when source="place_revision".');
       if (!options.placeVersion)
         throw new Error('place_version is required when launching source="place_revision".');
       return [
@@ -1923,39 +2501,69 @@ function buildStudioLaunchArgs(options) {
 function delay(ms) {
   return new Promise((resolve4) => setTimeout(resolve4, ms));
 }
+function basenameAny(filePath) {
+  return path2.basename(filePath.replace(/\\/g, "/"));
+}
 var BASEPLATE_TEMP_DIR, BASEPLATE_TEMP_NAME, BASEPLATE_TEMPLATE_NAME, StudioInstanceManager;
 var init_studio_instance_manager = __esm({
   "../core/dist/studio-instance-manager.js"() {
     "use strict";
-    BASEPLATE_TEMP_DIR = path.join(os.tmpdir(), "robloxstudio-mcp-baseplates");
+    init_managed_instance_registry();
+    BASEPLATE_TEMP_DIR = path2.join(os2.tmpdir(), "robloxstudio-mcp-baseplates");
     BASEPLATE_TEMP_NAME = /^Baseplate-\d+-\d+\.rbxl$/;
     BASEPLATE_TEMPLATE_NAME = "Baseplate.rbxl";
     StudioInstanceManager = class {
       managedByInstanceId = /* @__PURE__ */ new Map();
       pending = /* @__PURE__ */ new Set();
+      registry;
+      processAdapter;
+      constructor(options = {}) {
+        this.registry = options.registry ?? new ManagedInstanceRegistry(options.registryDir);
+        this.processAdapter = options.processAdapter ?? {};
+      }
       list() {
-        return [...this.managedByInstanceId.values(), ...this.pending].filter((instance, index, all) => all.indexOf(instance) === index);
+        this.sweepRegistry();
+        const records = [...this.managedByInstanceId.values(), ...this.pending];
+        for (const registryRecord of this.registry.listOpen(this.registrySweepOptions())) {
+          const record = this.fromRegistryRecord(registryRecord);
+          if (records.some((existing) => record.recordId && existing.recordId === record.recordId || record.instanceId && existing.instanceId === record.instanceId)) {
+            continue;
+          }
+          records.push(record);
+        }
+        return records.filter((instance, index, all) => all.indexOf(instance) === index);
       }
       get(instanceId) {
-        return this.managedByInstanceId.get(instanceId);
+        this.sweepRegistry();
+        const memoryRecord = this.managedByInstanceId.get(instanceId);
+        if (memoryRecord)
+          return memoryRecord;
+        const registryRecord = this.registry.findOpenByInstanceId(instanceId, this.registrySweepOptions());
+        return registryRecord ? this.fromRegistryRecord(registryRecord) : void 0;
       }
       attachInstanceId(record, instanceId) {
         record.instanceId = instanceId;
         this.pending.delete(record);
         this.managedByInstanceId.set(instanceId, record);
+        if (record.recordId) {
+          this.registry.attachInstanceId(record.recordId, instanceId);
+        }
       }
       async launch(options) {
+        this.sweepRegistry();
         const preparedOptions = prepareStudioLaunchOptions(options);
-        const before = new Set(listStudioProcesses().map((proc2) => proc2.Id));
-        const exe = resolveStudioExe();
+        const before = new Set(this.listStudioProcesses().map((proc2) => proc2.Id));
+        const exe = this.processAdapter.resolveStudioExe?.() ?? resolveStudioExe();
         const args = buildStudioLaunchArgs(preparedOptions).map(toStudioLaunchArg);
-        const proc = spawn(exe, args, {
+        const spawnOptions = {
           cwd: isWsl() && existsSync("/mnt/c/Windows") ? "/mnt/c/Windows" : process.cwd(),
           detached: true,
           stdio: "ignore"
-        });
+        };
+        const proc = this.processAdapter.spawnStudio ? this.processAdapter.spawnStudio(exe, args, spawnOptions) : spawn(exe, args, spawnOptions);
         proc.unref();
         const record = {
+          recordId: randomUUID(),
           source: options.source,
           spawnPid: proc.pid,
           exe,
@@ -1964,43 +2572,119 @@ var init_studio_instance_manager = __esm({
           universeId: preparedOptions.universeId,
           placeVersion: preparedOptions.placeVersion,
           localPlaceFile: preparedOptions.localPlaceFile,
-          launchedAt: Date.now()
+          launchedAt: Date.now(),
+          ownerPid: process.pid,
+          bootId: this.getCurrentBootId(),
+          deleteLocalPlaceFileOnClose: options.source === "baseplate"
         };
         this.pending.add(record);
+        this.registry.upsert(this.toRegistryRecord(record));
         const deadline = Date.now() + 5e3;
         while (Date.now() < deadline && record.nativeProcessId === void 0) {
-          const created = listStudioProcesses().find((candidate) => !before.has(candidate.Id));
+          const created = this.listStudioProcesses().find((candidate) => !before.has(candidate.Id));
           if (created) {
             record.nativeProcessId = created.Id;
+            this.registry.upsert(this.toRegistryRecord(record));
             break;
           }
           await delay(250);
         }
         if (record.nativeProcessId === void 0 && process.platform !== "win32" && !isWsl()) {
           record.nativeProcessId = proc.pid;
+          this.registry.upsert(this.toRegistryRecord(record));
         }
         return record;
       }
+      closeByInstanceId(instanceId) {
+        const memoryRecord = this.managedByInstanceId.get(instanceId);
+        if (memoryRecord)
+          return this.close(memoryRecord);
+        const registryRecord = this.registry.findAnyByInstanceId(instanceId);
+        if (!registryRecord) {
+          this.sweepRegistry();
+          return { status: "not_found", instanceId };
+        }
+        if (registryRecord.closedAt !== void 0) {
+          this.cleanupManagedRecord(registryRecord);
+          this.registry.delete(registryRecord.recordId);
+          this.registry.logEvent({
+            event: "registry_close_already_stopped",
+            recordId: registryRecord.recordId,
+            instanceId: registryRecord.instanceId,
+            source: registryRecord.source,
+            reason: "closed_at_present",
+            action: "deleted_record_and_cleaned_baseplate"
+          });
+          return { status: "already_closed", instanceId };
+        }
+        if (registryRecord.bootId !== this.getCurrentBootId()) {
+          this.cleanupManagedRecord(registryRecord);
+          this.registry.delete(registryRecord.recordId);
+          this.registry.logEvent({
+            event: "registry_pruned_previous_boot",
+            recordId: registryRecord.recordId,
+            instanceId: registryRecord.instanceId,
+            source: registryRecord.source,
+            reason: "boot_id_changed",
+            action: "deleted_record_and_cleaned_baseplate"
+          });
+          return { status: "already_closed", instanceId };
+        }
+        return this.close(this.fromRegistryRecord(registryRecord));
+      }
       close(record) {
         const processId = record.nativeProcessId ?? record.spawnPid;
         if (!processId) {
           throw new Error(`Cannot close ${record.instanceId ?? "Studio launch"} because its process id was not detected.`);
         }
-        if (process.platform === "win32" || isWsl()) {
-          powershell(`Stop-Process -Id ${Math.trunc(processId)} -Force -ErrorAction Stop`);
-        } else {
-          try {
-            process.kill(processId, "SIGTERM");
-          } catch (error) {
-            if (error.code !== "ESRCH")
-              throw error;
-          }
+        const studioProcess = this.findProcessById(processId);
+        if (!studioProcess) {
+          this.cleanupManagedRecord(record);
+          this.markClosedInMemory(record);
+          this.markClosedInRegistry(record);
+          this.registry.logEvent({
+            event: "registry_close_already_stopped",
+            recordId: record.recordId,
+            instanceId: record.instanceId,
+            source: record.source,
+            reason: "pid_not_running",
+            action: "marked_closed_and_cleaned_baseplate"
+          });
+          return { status: "already_closed", instanceId: record.instanceId };
+        }
+        if (!this.verifyProcessForRecord(record, studioProcess)) {
+          this.registry.logEvent({
+            event: "registry_process_verification_failed",
+            recordId: record.recordId,
+            instanceId: record.instanceId,
+            source: record.source,
+            reason: "identity_mismatch"
+          });
+          throw new Error("Managed Studio process identity could not be verified.");
+        }
+        try {
+          this.closeProcess(processId);
+        } catch (error) {
+          if (this.findProcessById(processId))
+            throw error;
+          this.registry.logEvent({
+            event: "registry_close_already_stopped",
+            recordId: record.recordId,
+            instanceId: record.instanceId,
+            source: record.source,
+            reason: "stop_raced_with_exit",
+            action: "marked_closed_and_cleaned_baseplate"
+          });
+          this.cleanupManagedRecord(record);
+          this.markClosedInMemory(record);
+          this.markClosedInRegistry(record);
+          return { status: "already_closed", instanceId: record.instanceId };
         }
         record.closedAt = Date.now();
-        if (record.instanceId)
-          this.managedByInstanceId.delete(record.instanceId);
-        this.pending.delete(record);
-        cleanupManagedBaseplateFiles(record);
+        this.cleanupManagedRecord(record);
+        this.markClosedInMemory(record);
+        this.markClosedInRegistry(record);
+        return { status: "closed", instanceId: record.instanceId };
       }
       closeConnectedInstance(instance) {
         const process2 = this.findProcessForConnectedInstance(instance);
@@ -2010,6 +2694,10 @@ var init_studio_instance_manager = __esm({
         this.closeProcess(process2.Id);
       }
       closeProcess(processId) {
+        if (this.processAdapter.stopProcess) {
+          this.processAdapter.stopProcess(processId);
+          return;
+        }
         if (process.platform === "win32" || isWsl()) {
           powershell(`Stop-Process -Id ${Math.trunc(processId)} -Force -ErrorAction Stop`);
         } else {
@@ -2022,7 +2710,7 @@ var init_studio_instance_manager = __esm({
         }
       }
       findProcessForConnectedInstance(instance) {
-        const processes = listStudioProcesses();
+        const processes = this.listStudioProcesses();
         if (processes.length === 0)
           return void 0;
         if (processes.length === 1)
@@ -2041,13 +2729,119 @@ var init_studio_instance_manager = __esm({
         }
         return void 0;
       }
+      listStudioProcesses() {
+        return this.processAdapter.listStudioProcesses?.() ?? listStudioProcesses();
+      }
+      getCurrentBootId() {
+        return this.processAdapter.currentBootId?.() ?? currentBootId();
+      }
+      registrySweepOptions() {
+        return {
+          currentBootId: this.getCurrentBootId(),
+          isProcessRunning: (record) => this.isRegistryProcessRunning(record),
+          cleanupRecord: (record) => this.cleanupManagedRecord(record)
+        };
+      }
+      sweepRegistry() {
+        this.registry.sweep(this.registrySweepOptions());
+      }
+      findProcessById(processId) {
+        return this.listStudioProcesses().find((proc) => proc.Id === processId);
+      }
+      isRegistryProcessRunning(record) {
+        const processId = record.nativeProcessId ?? record.spawnPid;
+        if (!processId)
+          return true;
+        const studioProcess = this.findProcessById(processId);
+        return !!studioProcess && this.verifyProcessForRecord(this.fromRegistryRecord(record), studioProcess);
+      }
+      verifyProcessForRecord(record, studioProcess) {
+        const processName = `${studioProcess.Name ?? ""} ${studioProcess.Path ?? ""}`.toLowerCase();
+        if (!processName.includes("robloxstudio"))
+          return false;
+        const processId = record.nativeProcessId ?? record.spawnPid;
+        if (record.spawnPid && record.spawnPid === processId && studioProcess.Id === processId)
+          return true;
+        const processPath = studioProcess.Path ? path2.normalize(studioProcess.Path).toLowerCase() : "";
+        const exePath = record.exe ? path2.normalize(record.exe).toLowerCase() : "";
+        if (processPath && exePath && (processPath === exePath || basenameAny(processPath) === basenameAny(exePath))) {
+          return true;
+        }
+        const commandLine = studioProcess.CommandLine ?? "";
+        if (record.localPlaceFile && commandLine.includes(path2.basename(record.localPlaceFile)))
+          return true;
+        if (record.placeId !== void 0 && commandLine.includes(String(record.placeId)))
+          return true;
+        return false;
+      }
+      cleanupManagedRecord(record) {
+        if (record.source !== "baseplate")
+          return;
+        cleanupManagedBaseplateFiles({ source: "baseplate", localPlaceFile: record.localPlaceFile });
+      }
+      markClosedInMemory(record) {
+        record.closedAt = record.closedAt ?? Date.now();
+        if (record.instanceId)
+          this.managedByInstanceId.delete(record.instanceId);
+        this.pending.delete(record);
+      }
+      markClosedInRegistry(record) {
+        if (record.recordId)
+          this.registry.markClosed(record.recordId, record.closedAt ?? Date.now());
+      }
+      toRegistryRecord(record) {
+        if (!record.recordId)
+          throw new Error("Managed Studio record is missing recordId.");
+        if (!record.bootId)
+          throw new Error("Managed Studio record is missing bootId.");
+        return {
+          version: 1,
+          recordId: record.recordId,
+          instanceId: record.instanceId,
+          source: record.source,
+          nativeProcessId: record.nativeProcessId,
+          spawnPid: record.spawnPid,
+          exe: record.exe,
+          args: record.args,
+          placeId: record.placeId,
+          universeId: record.universeId,
+          placeVersion: record.placeVersion,
+          localPlaceFile: record.localPlaceFile,
+          deleteLocalPlaceFileOnClose: record.deleteLocalPlaceFileOnClose,
+          launchedAt: record.launchedAt,
+          attachedAt: record.instanceId ? Date.now() : void 0,
+          closedAt: record.closedAt,
+          ownerPid: record.ownerPid,
+          bootId: record.bootId
+        };
+      }
+      fromRegistryRecord(record) {
+        return {
+          recordId: record.recordId,
+          source: record.source,
+          instanceId: record.instanceId,
+          nativeProcessId: record.nativeProcessId,
+          spawnPid: record.spawnPid,
+          exe: record.exe,
+          args: record.args,
+          placeId: record.placeId,
+          universeId: record.universeId,
+          placeVersion: record.placeVersion,
+          localPlaceFile: record.localPlaceFile,
+          launchedAt: record.launchedAt,
+          closedAt: record.closedAt,
+          ownerPid: record.ownerPid,
+          bootId: record.bootId,
+          deleteLocalPlaceFileOnClose: record.deleteLocalPlaceFileOnClose
+        };
+      }
     };
   }
 });
 
 // ../core/dist/image-decode.js
-import * as fs from "fs";
-import * as path2 from "path";
+import * as fs2 from "fs";
+import * as path3 from "path";
 import { inflateSync } from "zlib";
 function paethPredictor(a, b, c) {
   const p = a + b - c;
@@ -2205,11 +2999,11 @@ function decodePngToRgba(data) {
   return resizeRgbaNearest({ width, height, rgba });
 }
 function decodeImagePathToRgba(imagePath) {
-  const resolved = path2.resolve(imagePath);
-  if (!fs.existsSync(resolved)) {
+  const resolved = path3.resolve(imagePath);
+  if (!fs2.existsSync(resolved)) {
     throw new Error(`image_path not found: ${imagePath}`);
   }
-  return decodePngToRgba(fs.readFileSync(resolved));
+  return decodePngToRgba(fs2.readFileSync(resolved));
 }
 var PNG_SIGNATURE, MAX_EDITABLE_IMAGE_DIMENSION;
 var init_image_decode = __esm({
@@ -3237,9 +4031,19 @@ var init_png_encoder = __esm({
 });
 
 // ../core/dist/tools/index.js
-import * as fs2 from "fs";
-import * as os2 from "os";
-import * as path3 from "path";
+import * as fs3 from "fs";
+import * as os3 from "os";
+import * as path4 from "path";
+function multiplayerStopDisabledBody() {
+  return {
+    success: false,
+    error: "multiplayer_stop_disabled",
+    message: MULTIPLAYER_STOP_DISABLED_MESSAGE,
+    reason: "StudioTestService:EndTest does not reliably end StudioTestService multiplayer sessions from MCP right now.",
+    manualCleanupRequired: true,
+    recoveryHint: "Close the Roblox Studio multiplayer test windows manually."
+  };
+}
 function encodeImageFromRgbaResponse(response, format, quality) {
   if (!response.data || response.width === void 0 || response.height === void 0) {
     throw new Error("Render response missing data, width, or height");
@@ -3316,8 +4120,8 @@ function loadMicroProfilerBaseline(source, sourcePath) {
     if (typeof sourcePath !== "string" || sourcePath === "") {
       throw new Error("baseline_path must be a non-empty string when provided");
     }
-    const resolved = path3.resolve(sourcePath);
-    const parsed = JSON.parse(fs2.readFileSync(resolved, "utf8"));
+    const resolved = path4.resolve(sourcePath);
+    const parsed = JSON.parse(fs3.readFileSync(resolved, "utf8"));
     const record = asRecord(parsed);
     if (!record)
       throw new Error(`baseline_path did not contain a JSON object: ${resolved}`);
@@ -3765,7 +4569,7 @@ end
 error("Unsupported device simulator operation: " .. tostring(opts.operation), 0)
 `.trim();
 }
-var MAX_INLINE_IMAGE_BYTES, MAX_DEVICE_MATRIX_ENTRIES, MAX_NETWORK_PACKET_LOSS_PERCENT, STUDIO_ASSISTANT_SOURCE_IMAGE_LABEL, NETWORK_PROFILE_KEYS, NETWORK_PROFILES, ZERO_NETWORK_PROFILE, SIMULATION_PERSISTENCE_NOTES, RobloxStudioTools;
+var MAX_INLINE_IMAGE_BYTES, MAX_DEVICE_MATRIX_ENTRIES, MAX_NETWORK_PACKET_LOSS_PERCENT, STUDIO_ASSISTANT_SOURCE_IMAGE_LABEL, MULTIPLAYER_FORCE_REQUIRED_MESSAGE, MULTIPLAYER_STOP_DISABLED_MESSAGE, NETWORK_PROFILE_KEYS, NETWORK_PROFILES, ZERO_NETWORK_PROFILE, SIMULATION_PERSISTENCE_NOTES, RobloxStudioTools;
 var init_tools = __esm({
   "../core/dist/tools/index.js"() {
     "use strict";
@@ -3776,12 +4580,15 @@ var init_tools = __esm({
     init_roblox_cookie_client();
     init_studio_instance_manager();
     init_image_decode();
+    init_roblox_docs();
     init_jpeg_encoder();
     init_png_encoder();
     MAX_INLINE_IMAGE_BYTES = 6e6;
     MAX_DEVICE_MATRIX_ENTRIES = 6;
     MAX_NETWORK_PACKET_LOSS_PERCENT = 0.5;
     STUDIO_ASSISTANT_SOURCE_IMAGE_LABEL = "Studio Assistant Source Image";
+    MULTIPLAYER_FORCE_REQUIRED_MESSAGE = "StudioTestService multiplayer stop is currently disabled because StudioTestService:EndTest is broken for this flow. Pass force=true only if you understand you must manually close the multiplayer test windows afterward.";
+    MULTIPLAYER_STOP_DISABLED_MESSAGE = "Multiplayer playtest stop/end is disabled because StudioTestService:EndTest is currently broken for this flow. Manually close the Studio multiplayer test windows instead.";
     NETWORK_PROFILE_KEYS = [
       "InboundNetworkMinDelayMs",
       "OutboundNetworkMinDelayMs",
@@ -3845,6 +4652,17 @@ var init_tools = __esm({
       _textResult(body) {
         return { content: [{ type: "text", text: JSON.stringify(body) }] };
       }
+      async getRobloxDocs(name, docType, section) {
+        if (!name || typeof name !== "string") {
+          throw new Error('get_roblox_docs requires a name (e.g. "ProximityPrompt")');
+        }
+        const category = docType ?? "classes";
+        if (!isDocCategory(category)) {
+          throw new Error(`Invalid doc_type "${category}". Valid categories: ${DOC_CATEGORIES.join(", ")}`);
+        }
+        const result = await getRobloxDoc(category, name.trim(), section);
+        return { content: [{ type: "text", text: result.content }] };
+      }
       _parseTextResult(result) {
         const text = result?.content?.[0]?.text;
         if (typeof text !== "string")
@@ -4186,8 +5004,8 @@ var init_tools = __esm({
           timedOut: true
         };
       }
-      async getFileTree(path4 = "", instance_id) {
-        const response = await this._callSingle("/api/file-tree", { path: path4 }, void 0, instance_id);
+      async getFileTree(path5 = "", instance_id) {
+        const response = await this._callSingle("/api/file-tree", { path: path5 }, void 0, instance_id);
         return {
           content: [
             {
@@ -4304,9 +5122,9 @@ var init_tools = __esm({
           ]
         };
       }
-      async getProjectStructure(path4, maxDepth, scriptsOnly, instance_id) {
+      async getProjectStructure(path5, maxDepth, scriptsOnly, instance_id) {
         const response = await this._callSingle("/api/project-structure", {
-          path: path4,
+          path: path5,
           maxDepth,
           scriptsOnly
         }, void 0, instance_id);
@@ -4486,17 +5304,20 @@ var init_tools = __esm({
         const topService = typeof response.topService === "string" && response.topService.length > 0 ? response.topService : pathSegments[0] === "game" ? pathSegments[1] ?? "game" : pathSegments[0];
         const typeNote = scriptTypeInfo[response.className] || response.className;
         const serviceNote = serviceInfo[topService] || topService;
+        const showRange = Boolean(response.isPartial || response.truncated) && response.startLine !== void 0 && response.endLine !== void 0;
         const headerLines = [
           `Path:     ${pathStr}`,
           `Type:     ${typeNote}`,
           `Location: ${serviceNote}`,
-          `Lines:    ${response.lineCount} total${response.isPartial ? ` (showing ${response.startLine}-${response.endLine})` : ""}`
+          `Lines:    ${response.lineCount} total${showRange ? ` (showing ${response.startLine}-${response.endLine})` : ""}`
         ];
         if (response.enabled === false) {
           headerLines.push(`Status:   DISABLED`);
         }
-        if (response.truncated) {
-          headerLines.push(`Note:     Truncated to first 1000 lines, use startLine/endLine to read more`);
+        if (typeof response.note === "string" && response.note.length > 0) {
+          headerLines.push(`Note:     ${response.note}`);
+        } else if (response.truncated) {
+          headerLines.push(`Note:     Truncated response; use line_range to read more`);
         }
         const header = headerLines.join("\n");
         const code = response.numberedSource || response.source;
@@ -4574,7 +5395,7 @@ ${code}`
         }
         const response = await this._callSingle("/api/grep-scripts", {
           pattern,
-          ...options
+          ...options ?? {}
         }, void 0, instance_id);
         return {
           content: [
@@ -5227,9 +6048,9 @@ ${code}`
           const rawJson = mutable.raw_json;
           if (typeof rawJson === "string") {
             if (typeof outputPath === "string" && outputPath !== "") {
-              const resolvedOutputPath = path3.resolve(outputPath);
-              fs2.mkdirSync(path3.dirname(resolvedOutputPath), { recursive: true });
-              fs2.writeFileSync(resolvedOutputPath, rawJson, "utf8");
+              const resolvedOutputPath = path4.resolve(outputPath);
+              fs3.mkdirSync(path4.dirname(resolvedOutputPath), { recursive: true });
+              fs3.writeFileSync(resolvedOutputPath, rawJson, "utf8");
               mutable.output_path = resolvedOutputPath;
             }
             delete mutable.raw_json;
@@ -5290,9 +6111,9 @@ ${code}`
           const rawSnapshotBase64 = mutable.raw_snapshot_base64;
           if (typeof rawSnapshotBase64 === "string") {
             if (typeof outputPath === "string" && outputPath !== "") {
-              const resolvedOutputPath = path3.resolve(outputPath);
-              fs2.mkdirSync(path3.dirname(resolvedOutputPath), { recursive: true });
-              fs2.writeFileSync(resolvedOutputPath, Buffer.from(rawSnapshotBase64, "base64"));
+              const resolvedOutputPath = path4.resolve(outputPath);
+              fs3.mkdirSync(path4.dirname(resolvedOutputPath), { recursive: true });
+              fs3.writeFileSync(resolvedOutputPath, Buffer.from(rawSnapshotBase64, "base64"));
               mutable.output_path = resolvedOutputPath;
             }
             delete mutable.raw_snapshot_base64;
@@ -5306,9 +6127,9 @@ ${code}`
             });
           }
           if (typeof summaryOutputPath === "string" && summaryOutputPath !== "") {
-            const resolvedSummaryPath = path3.resolve(summaryOutputPath);
-            fs2.mkdirSync(path3.dirname(resolvedSummaryPath), { recursive: true });
-            fs2.writeFileSync(resolvedSummaryPath, JSON.stringify(mutable, null, 2), "utf8");
+            const resolvedSummaryPath = path4.resolve(summaryOutputPath);
+            fs3.mkdirSync(path4.dirname(resolvedSummaryPath), { recursive: true });
+            fs3.writeFileSync(resolvedSummaryPath, JSON.stringify(mutable, null, 2), "utf8");
             mutable.summary_output_path = resolvedSummaryPath;
           }
           if (!includeComparisonIndex) {
@@ -5355,6 +6176,14 @@ ${code}`
           return void 0;
         return this._positiveInteger(value, name);
       }
+      _optionalFiniteNumber(value, name) {
+        if (value === void 0 || value === null)
+          return void 0;
+        if (typeof value !== "number" || !Number.isFinite(value)) {
+          throw new Error(`${name} must be a finite number.`);
+        }
+        return value;
+      }
       _publicInstanceKey(instance) {
         return `${instance.instanceId}:${instance.role}:${instance.connectedAt}`;
       }
@@ -5367,7 +6196,7 @@ ${code}`
           return record.placeId !== void 0 && instance.placeId === record.placeId;
         }
         if ((record.source === "baseplate" || record.source === "local_file") && record.localPlaceFile) {
-          const expectedName = path3.basename(record.localPlaceFile);
+          const expectedName = path4.basename(record.localPlaceFile);
           return instance.placeName === expectedName || instance.dataModelName === expectedName;
         }
         return true;
@@ -5376,11 +6205,11 @@ ${code}`
         const response = await fetch(`https://apis.roblox.com/universes/v1/places/${placeId}/universe`);
         if (!response.ok) {
           const body = await response.text().catch(() => "");
-          throw new Error(`Could not derive universe_id for place ${placeId} (${response.status}): ${body}`);
+          throw new Error(`Could not resolve the universe for place_id ${placeId} (${response.status}): ${body}`);
         }
         const data = await response.json();
         if (typeof data.universeId !== "number" || !Number.isFinite(data.universeId)) {
-          throw new Error(`Could not derive universe_id for place ${placeId}.`);
+          throw new Error(`Could not resolve the universe for place_id ${placeId}.`);
         }
         return Math.trunc(data.universeId);
       }
@@ -5422,7 +6251,7 @@ ${code}`
             });
           }
           const placeId2 = this._positiveInteger(request.place_id, "place_id");
-          const rawMaxPageSize = this._optionalPositiveInteger(request.max_page_size, "max_page_size") ?? 10;
+          const rawMaxPageSize = Math.trunc(this._optionalFiniteNumber(request.max_page_size, "max_page_size") ?? 10);
           const maxPageSize = Math.max(1, Math.min(50, rawMaxPageSize));
           const pageToken = typeof request.page_token === "string" ? request.page_token : void 0;
           const response = await this.openCloudClient.listAssetVersions(placeId2, maxPageSize, pageToken);
@@ -5467,31 +6296,38 @@ ${code}`
         if (action === "close") {
           let record2;
           if (instance_id) {
-            record2 = this.instanceManager.get(instance_id);
-            if (!record2) {
-              const connected2 = this.bridge.getPublicInstances().filter((instance) => instance.instanceId === instance_id);
-              const edit = connected2.find((instance) => instance.role === "edit");
-              if (!edit) {
-                return this._textResult({
-                  error: "Instance is not connected or managed.",
-                  instance_id
-                });
-              }
-              try {
-                this.instanceManager.closeConnectedInstance(edit);
-                await sleep(500);
-              } catch (error) {
-                return this._textResult({
-                  error: error instanceof Error ? error.message : String(error),
-                  instance_id
-                });
-              }
-              this.bridge.unregisterInstanceId(instance_id);
+            const managedClose = this.instanceManager.closeByInstanceId(instance_id);
+            if (managedClose.status !== "not_found") {
+              await this.bridge.unregisterInstanceIdEverywhere(instance_id);
+              await sleep(500);
+              await this.bridge.unregisterInstanceIdEverywhere(instance_id);
               return this._textResult({
                 instance_id,
-                message: "Studio instance closed."
+                message: managedClose.status === "already_closed" ? "Studio instance was already closed." : "Studio instance closed."
               });
             }
+            const connected2 = this.bridge.getPublicInstances().filter((instance) => instance.instanceId === instance_id);
+            const edit = connected2.find((instance) => instance.role === "edit");
+            if (!edit) {
+              return this._textResult({
+                error: "Instance is not connected or managed.",
+                instance_id
+              });
+            }
+            try {
+              this.instanceManager.closeConnectedInstance(edit);
+              await sleep(500);
+            } catch (error) {
+              return this._textResult({
+                error: error instanceof Error ? error.message : String(error),
+                instance_id
+              });
+            }
+            await this.bridge.unregisterInstanceIdEverywhere(instance_id);
+            return this._textResult({
+              instance_id,
+              message: "Studio instance closed."
+            });
           } else {
             const active = this.instanceManager.list().filter((entry) => entry.closedAt === void 0);
             if (active.length === 0) {
@@ -5506,15 +6342,15 @@ ${code}`
             record2 = active[0];
           }
           if (record2.instanceId)
-            this.bridge.unregisterInstanceId(record2.instanceId);
-          this.instanceManager.close(record2);
+            await this.bridge.unregisterInstanceIdEverywhere(record2.instanceId);
+          const closeResult = this.instanceManager.close(record2);
           if (record2.instanceId) {
             await sleep(500);
-            this.bridge.unregisterInstanceId(record2.instanceId);
+            await this.bridge.unregisterInstanceIdEverywhere(record2.instanceId);
           }
           return this._textResult({
             instance_id: record2.instanceId,
-            message: "Studio instance closed."
+            message: closeResult.status === "already_closed" ? "Studio instance was already closed." : "Studio instance closed."
           });
         }
         const source = request.source;
@@ -5522,8 +6358,8 @@ ${code}`
           throw new Error("manage_instance action=launch requires source=baseplate|local_file|published_place|place_revision");
         }
         const launchSource = source;
-        const placeId = launchSource === "published_place" || launchSource === "place_revision" ? this._positiveInteger(request.place_id, "place_id") : this._optionalPositiveInteger(request.place_id, "place_id");
-        const placeVersion = launchSource === "place_revision" ? this._positiveInteger(request.place_version, "place_version") : this._optionalPositiveInteger(request.place_version, "place_version");
+        const placeId = launchSource === "published_place" || launchSource === "place_revision" ? this._positiveInteger(request.place_id, "place_id") : void 0;
+        const placeVersion = launchSource === "place_revision" ? this._positiveInteger(request.place_version, "place_version") : void 0;
         const localPlaceFile = typeof request.local_place_file === "string" ? request.local_place_file : void 0;
         if (launchSource === "published_place" && placeId !== void 0 && this._isLatestPublishedPlaceOpen(placeId)) {
           return this._textResult({
@@ -5531,7 +6367,7 @@ ${code}`
             message: `place_id ${placeId} is already connected. Use the existing instance or launch a specific place_revision.`
           });
         }
-        const universeId = launchSource === "published_place" || launchSource === "place_revision" ? this._optionalPositiveInteger(request.universe_id, "universe_id") ?? await this._deriveUniverseId(placeId) : this._optionalPositiveInteger(request.universe_id, "universe_id");
+        const universeId = launchSource === "published_place" || launchSource === "place_revision" ? await this._deriveUniverseId(placeId) : void 0;
         const waitForConnection = request.wait_for_connection !== false;
         const timeoutMs = this._optionalPositiveInteger(request.timeout_ms, "timeout_ms") ?? 12e4;
         const beforeKeys = new Set(this.bridge.getPublicInstances().map((instance) => this._publicInstanceKey(instance)));
@@ -5797,26 +6633,40 @@ ${code}`
         }
         return hasServer && clientCount >= 2;
       }
-      async _waitForMultiplayerStart(instanceId, clientCount, timeoutSec = 30) {
+      async _waitForMultiplayerStart(instanceId, clientCount, timeoutSec = 30, connectedAfter) {
         const deadline = Date.now() + timeoutSec * 1e3;
+        let lastPhase;
         while (Date.now() < deadline) {
           const exact = await this._waitForExactClientCount(instanceId, clientCount, 0.25, 0);
           if (exact.ok || exact.extraClients) {
+            if (exact.ok && connectedAfter !== void 0) {
+              const instances = this.bridge.getInstances().filter((inst) => inst.instanceId === instanceId);
+              const freshRoles = new Set(instances.filter((inst) => inst.connectedAt >= connectedAfter).map((inst) => inst.role));
+              const freshClientCount = [...freshRoles].filter((role) => /^client-\d+$/.test(role)).length;
+              if (!freshRoles.has("server") || freshClientCount !== clientCount) {
+                await sleep(250);
+                continue;
+              }
+            }
             return { ok: exact.ok, roles: exact.roles, timedOut: false, error: exact.extraClients ? `Expected ${clientCount} client(s), but Studio registered ${exact.clientCount}.` : void 0 };
           }
           try {
-            const editState = await this.client.request("/api/multiplayer-test-state", {}, instanceId, "edit");
+            const remainingMs = Math.max(1, Math.min(1e3, deadline - Date.now()));
+            const editState = await this.client.request("/api/multiplayer-test-state", {}, instanceId, "edit", remainingMs);
             const session = editState?.session;
-            if (session?.phase === "failed" || session?.phase === "completed") {
+            if (typeof session?.phase === "string") {
+              lastPhase = session.phase;
+            }
+            if (session?.phase === "failed") {
               return { ok: false, roles: this._rolesForInstance(instanceId), timedOut: false, phase: session.phase, error: session.error };
             }
           } catch {
           }
           await sleep(250);
         }
-        return { ok: false, roles: this._rolesForInstance(instanceId), timedOut: true };
+        return { ok: false, roles: this._rolesForInstance(instanceId), timedOut: true, phase: lastPhase };
       }
-      async multiplayerPlaytest(action, numPlayers, target, testArgs, value, timeout, instance_id) {
+      async multiplayerPlaytest(action, numPlayers, target, testArgs, value, timeout, instance_id, force) {
         if (action !== "start" && action !== "status" && action !== "add_players" && action !== "leave_client" && action !== "end") {
           throw new Error("multiplayer_playtest requires action=start|status|add_players|leave_client|end");
         }
@@ -5838,93 +6688,130 @@ ${code}`
           });
         }
         if (action === "start") {
-          const body2 = this._parseTextResult(await this.multiplayerTestStart(numPlayers, testArgs, timeout, instance_id));
-          const state = body2.state && typeof body2.state === "object" ? body2.state : {};
-          const success = body2.success === true && body2.ready === true;
-          return this._textResult(success ? {
+          if (force !== true) {
+            return this._textResult({
+              success: false,
+              action,
+              error: "multiplayer_force_required",
+              message: MULTIPLAYER_FORCE_REQUIRED_MESSAGE,
+              requiresForce: true,
+              manualCleanupRequired: true
+            });
+          }
+          const body = this._parseTextResult(await this.multiplayerTestStart(numPlayers, testArgs, timeout, instance_id, force));
+          const state = body.state && typeof body.state === "object" ? body.state : {};
+          const launched = body.success === true && body.ready === true;
+          return this._textResult(launched ? {
             success: true,
             action,
-            message: "Multiplayer playtest started.",
-            roles: Array.isArray(body2.roles) ? body2.roles : void 0,
+            message: "Multiplayer playtest started. Stop/end is disabled; close the multiplayer test windows manually when finished.",
+            ready: true,
+            manualCleanupRequired: true,
+            roles: Array.isArray(body.roles) ? body.roles : void 0,
             clientRoles: Array.isArray(state.clientRoles) ? state.clientRoles : void 0,
             playerCount: typeof state.playerCount === "number" ? state.playerCount : void 0
           } : {
             success: false,
             action,
-            error: body2.error ?? body2.wait?.error ?? "start_failed",
-            message: body2.success === true ? "Multiplayer playtest did not become ready before timeout." : body2.message ?? "Multiplayer playtest did not start.",
-            roles: Array.isArray(body2.roles) ? body2.roles : void 0
+            error: body.error ?? body.wait?.error ?? "multiplayer_start_not_detected",
+            message: body.success === true ? "Multiplayer playtest start was requested, but MCP did not detect the required server/client peers before timeout. You may need to close the test windows manually." : body.message ?? "Multiplayer playtest did not start.",
+            manualCleanupRequired: body.startRequested === true || body.launched === true ? true : void 0,
+            roles: Array.isArray(body.roles) ? body.roles : void 0
           });
         }
         if (action === "add_players") {
-          const body2 = this._parseTextResult(await this.multiplayerTestAddPlayers(numPlayers, timeout, instance_id));
-          const state = body2.state && typeof body2.state === "object" ? body2.state : {};
-          const success = body2.success === true && body2.ready === true;
+          const body = this._parseTextResult(await this.multiplayerTestAddPlayers(numPlayers, timeout, instance_id));
+          const state = body.state && typeof body.state === "object" ? body.state : {};
+          const success = body.success === true && body.ready === true;
           return this._textResult(success ? {
             success: true,
             action,
             message: "Players added.",
-            roles: Array.isArray(body2.roles) ? body2.roles : void 0,
+            roles: Array.isArray(body.roles) ? body.roles : void 0,
             clientRoles: Array.isArray(state.clientRoles) ? state.clientRoles : void 0,
             playerCount: typeof state.playerCount === "number" ? state.playerCount : void 0
           } : {
             success: false,
             action,
-            error: body2.error ?? "add_players_failed",
-            message: body2.success === true ? "Players did not finish joining before timeout." : body2.message ?? "Players were not added.",
-            roles: Array.isArray(body2.roles) ? body2.roles : void 0
+            error: body.error ?? "add_players_failed",
+            message: body.success === true ? "Players did not finish joining before timeout." : body.message ?? "Players were not added.",
+            roles: Array.isArray(body.roles) ? body.roles : void 0
           });
         }
         if (action === "leave_client") {
-          const body2 = this._parseTextResult(await this.multiplayerTestLeaveClient(target ?? "client-1", timeout, instance_id));
-          return this._textResult(body2.success === true && body2.left === true ? {
+          const body = this._parseTextResult(await this.multiplayerTestLeaveClient(target ?? "client-1", timeout, instance_id));
+          return this._textResult(body.success === true && body.left === true ? {
             success: true,
             action,
             message: "Client left.",
-            roles: Array.isArray(body2.roles) ? body2.roles : void 0
+            roles: Array.isArray(body.roles) ? body.roles : void 0
           } : {
             success: false,
             action,
-            error: body2.error ?? "leave_client_failed",
-            message: body2.message ?? "Client did not leave.",
-            roles: Array.isArray(body2.roles) ? body2.roles : void 0
+            error: body.error ?? "leave_client_failed",
+            message: body.message ?? "Client did not leave.",
+            roles: Array.isArray(body.roles) ? body.roles : void 0
           });
         }
-        const body = this._parseTextResult(await this.multiplayerTestEnd(value, timeout, instance_id));
-        return this._textResult(body.success === true && body.ended === true ? {
-          success: true,
-          action,
-          message: "Multiplayer playtest ended."
-        } : {
-          success: false,
+        return this._textResult({
           action,
-          error: body.error ?? "end_failed",
-          message: body.message ?? "Multiplayer playtest did not end.",
-          roles: Array.isArray(body.roles) ? body.roles : void 0,
-          editDone: body.editDone === false ? false : void 0
+          ...multiplayerStopDisabledBody()
         });
       }
-      async multiplayerTestStart(numPlayers, testArgs, timeout, instance_id) {
+      async multiplayerTestStart(numPlayers, testArgs, timeout, instance_id, force) {
         if (!Number.isInteger(numPlayers) || numPlayers < 1 || numPlayers > 8) {
           throw new Error("numPlayers must be an integer from 1 to 8");
         }
         const editTarget = this._resolveSingleTarget("edit", instance_id);
+        if (force !== true) {
+          return this._textResult({
+            success: false,
+            error: "multiplayer_force_required",
+            message: MULTIPLAYER_FORCE_REQUIRED_MESSAGE,
+            requiresForce: true,
+            manualCleanupRequired: true
+          });
+        }
+        const existingRuntime = this._runtimeTargetsForEquivalentInstances(editTarget.instanceId);
+        if (existingRuntime.length > 0) {
+          const roles = this._rolesForEquivalentInstances(editTarget.instanceId);
+          return this._textResult({
+            success: false,
+            error: "Multiplayer playtest already running.",
+            message: "A Studio runtime is already connected for this place. Close the existing playtest windows manually before starting another multiplayer playtest.",
+            ready: true,
+            timedOut: false,
+            roles,
+            runtimeRoles: existingRuntime.map((target) => target.role),
+            manualCleanupRequired: true
+          });
+        }
+        const startedAt = Date.now();
         const response = await this.client.request("/api/multiplayer-test-start", { numPlayers, testArgs: testArgs ?? {} }, editTarget.instanceId, editTarget.role);
         if (response?.error) {
           return { content: [{ type: "text", text: JSON.stringify(response) }] };
         }
-        const wait = await this._waitForMultiplayerStart(editTarget.instanceId, numPlayers, timeout ?? 30);
+        const wait = await this._waitForMultiplayerStart(editTarget.instanceId, numPlayers, timeout ?? 60, startedAt);
+        const launched = wait.ok;
         const state = await this._buildMultiplayerState(editTarget.instanceId);
+        const success = response.success === true && wait.ok;
         return {
           content: [{
             type: "text",
             text: JSON.stringify({
               ...response,
+              success,
               ready: wait.ok,
+              launched,
+              startRequested: response.success === true,
               timedOut: wait.timedOut,
               wait,
               roles: wait.roles,
-              state
+              state,
+              error: success ? void 0 : wait.error ?? "multiplayer_start_not_detected",
+              message: success ? "Multiplayer Studio test started and runtime peers detected." : "Multiplayer Studio test start was requested, but MCP did not detect the required server/client peers before timeout. Close the multiplayer test windows manually if Studio launched them.",
+              manualCleanupRequired: success || response.success === true ? true : void 0,
+              startedAt
             })
           }]
         };
@@ -5985,27 +6872,10 @@ ${code}`
         };
       }
       async multiplayerTestEnd(value, timeout, instance_id) {
-        const serverTarget = this._resolveSingleTarget("server", instance_id);
-        const response = await this.client.request("/api/multiplayer-test-end", { value: value ?? "ended_by_mcp" }, serverTarget.instanceId, serverTarget.role);
-        if (response?.error) {
-          return { content: [{ type: "text", text: JSON.stringify(response) }] };
-        }
-        const editDone = await this._waitForMultiplayerEditDone(serverTarget.instanceId, timeout ?? 30);
-        const wait = await this._waitForRuntimeRoles(serverTarget.instanceId, { noRuntime: true }, timeout ?? 30);
-        const state = await this._buildMultiplayerState(serverTarget.instanceId);
-        return {
-          content: [{
-            type: "text",
-            text: JSON.stringify({
-              ...response,
-              ended: wait.ok,
-              editDone,
-              timedOut: wait.timedOut,
-              roles: wait.roles,
-              state
-            })
-          }]
-        };
+        void value;
+        void timeout;
+        void instance_id;
+        return this._textResult(multiplayerStopDisabledBody());
       }
       async getConnectedInstances() {
         const instances = this.bridge.getPublicInstances();
@@ -6041,14 +6911,14 @@ ${code}`
         };
       }
       static findProjectRoot(startDir) {
-        let dir = path3.resolve(startDir);
+        let dir = path4.resolve(startDir);
         let previous = "";
         while (dir !== previous) {
-          if (fs2.existsSync(path3.join(dir, ".git")) || fs2.existsSync(path3.join(dir, "package.json"))) {
+          if (fs3.existsSync(path4.join(dir, ".git")) || fs3.existsSync(path4.join(dir, "package.json"))) {
             return dir;
           }
           previous = dir;
-          dir = path3.dirname(dir);
+          dir = path4.dirname(dir);
         }
         return null;
       }
@@ -6056,15 +6926,15 @@ ${code}`
         if (!candidate)
           return false;
         try {
-          return fs2.statSync(candidate).isDirectory();
+          return fs3.statSync(candidate).isDirectory();
         } catch {
           return false;
         }
       }
       static ensureWritableDirectory(candidate, label) {
-        const resolved = path3.resolve(candidate);
+        const resolved = path4.resolve(candidate);
         try {
-          fs2.mkdirSync(resolved, { recursive: true });
+          fs3.mkdirSync(resolved, { recursive: true });
         } catch (error) {
           throw new Error(`Unable to create ${label} build-library directory at ${resolved}: ${error.message}`);
         }
@@ -6072,7 +6942,7 @@ ${code}`
           throw new Error(`${label} build-library path is not a directory: ${resolved}`);
         }
         try {
-          fs2.accessSync(resolved, fs2.constants.W_OK);
+          fs3.accessSync(resolved, fs3.constants.W_OK);
         } catch (error) {
           throw new Error(`${label} build-library directory is not writable: ${resolved}. ${error.message}`);
         }
@@ -6083,25 +6953,25 @@ ${code}`
         if (_RobloxStudioTools._cachedLibraryPath)
           return _RobloxStudioTools._cachedLibraryPath;
         const overridePath = process.env.ROBLOXSTUDIO_MCP_BUILD_LIBRARY || process.env.BUILD_LIBRARY_PATH;
-        const cwd = path3.resolve(process.cwd());
+        const cwd = path4.resolve(process.cwd());
         const projectRoot = _RobloxStudioTools.findProjectRoot(cwd);
-        const homeLibraryPath = path3.join(os2.homedir(), ".robloxstudio-mcp", "build-library");
-        const projectLibraryPath = projectRoot ? path3.join(projectRoot, "build-library") : null;
-        const cwdLibraryPath = path3.join(cwd, "build-library");
+        const homeLibraryPath = path4.join(os3.homedir(), ".robloxstudio-mcp", "build-library");
+        const projectLibraryPath = projectRoot ? path4.join(projectRoot, "build-library") : null;
+        const cwdLibraryPath = path4.join(cwd, "build-library");
         let result;
         if (overridePath) {
           result = _RobloxStudioTools.ensureWritableDirectory(overridePath, "override");
         } else {
           const existing = [projectLibraryPath, cwdLibraryPath].find((c) => c && _RobloxStudioTools.isDirectory(c) && (() => {
             try {
-              fs2.accessSync(c, fs2.constants.W_OK);
+              fs3.accessSync(c, fs3.constants.W_OK);
               return true;
             } catch {
               return false;
             }
           })());
           if (existing) {
-            result = path3.resolve(existing);
+            result = path4.resolve(existing);
           } else if (projectLibraryPath) {
             try {
               result = _RobloxStudioTools.ensureWritableDirectory(projectLibraryPath, "project-root");
@@ -6128,12 +6998,12 @@ ${code}`
         if (response && response.success && response.buildData) {
           const buildData = response.buildData;
           const buildId = buildData.id || `${style}/exported`;
-          const filePath = path3.join(_RobloxStudioTools.findLibraryPath(), `${buildId}.json`);
-          const dirPath = path3.dirname(filePath);
-          if (!fs2.existsSync(dirPath)) {
-            fs2.mkdirSync(dirPath, { recursive: true });
+          const filePath = path4.join(_RobloxStudioTools.findLibraryPath(), `${buildId}.json`);
+          const dirPath = path4.dirname(filePath);
+          if (!fs3.existsSync(dirPath)) {
+            fs3.mkdirSync(dirPath, { recursive: true });
           }
-          fs2.writeFileSync(filePath, JSON.stringify(buildData, null, 2));
+          fs3.writeFileSync(filePath, JSON.stringify(buildData, null, 2));
           response.savedTo = filePath;
         }
         return {
@@ -6230,12 +7100,12 @@ ${code}`
         const normalizedParts = this.normalizeBuildParts(parts, new Set(Object.keys(normalizedPalette)));
         const computedBounds = bounds || this.computeBounds(normalizedParts);
         const buildData = { id, style, bounds: computedBounds, palette: normalizedPalette, parts: normalizedParts };
-        const filePath = path3.join(_RobloxStudioTools.findLibraryPath(), `${id}.json`);
-        const dirPath = path3.dirname(filePath);
-        if (!fs2.existsSync(dirPath)) {
-          fs2.mkdirSync(dirPath, { recursive: true });
+        const filePath = path4.join(_RobloxStudioTools.findLibraryPath(), `${id}.json`);
+        const dirPath = path4.dirname(filePath);
+        if (!fs3.existsSync(dirPath)) {
+          fs3.mkdirSync(dirPath, { recursive: true });
         }
-        fs2.writeFileSync(filePath, JSON.stringify(buildData, null, 2));
+        fs3.writeFileSync(filePath, JSON.stringify(buildData, null, 2));
         return {
           content: [
             {
@@ -6289,12 +7159,12 @@ ${code}`
         };
         if (seed !== void 0)
           buildData.generatorSeed = seed;
-        const filePath = path3.join(_RobloxStudioTools.findLibraryPath(), `${id}.json`);
-        const dirPath = path3.dirname(filePath);
-        if (!fs2.existsSync(dirPath)) {
-          fs2.mkdirSync(dirPath, { recursive: true });
+        const filePath = path4.join(_RobloxStudioTools.findLibraryPath(), `${id}.json`);
+        const dirPath = path4.dirname(filePath);
+        if (!fs3.existsSync(dirPath)) {
+          fs3.mkdirSync(dirPath, { recursive: true });
         }
-        fs2.writeFileSync(filePath, JSON.stringify(buildData, null, 2));
+        fs3.writeFileSync(filePath, JSON.stringify(buildData, null, 2));
         return {
           content: [
             {
@@ -6318,17 +7188,17 @@ ${code}`
         }
         let resolved;
         if (typeof buildData === "string") {
-          const filePath = path3.join(_RobloxStudioTools.findLibraryPath(), `${buildData}.json`);
-          if (!fs2.existsSync(filePath)) {
+          const filePath = path4.join(_RobloxStudioTools.findLibraryPath(), `${buildData}.json`);
+          if (!fs3.existsSync(filePath)) {
             throw new Error(`Build not found in library: ${buildData}`);
           }
-          resolved = JSON.parse(fs2.readFileSync(filePath, "utf-8"));
+          resolved = JSON.parse(fs3.readFileSync(filePath, "utf-8"));
         } else if (buildData.id && !buildData.parts) {
-          const filePath = path3.join(_RobloxStudioTools.findLibraryPath(), `${buildData.id}.json`);
-          if (!fs2.existsSync(filePath)) {
+          const filePath = path4.join(_RobloxStudioTools.findLibraryPath(), `${buildData.id}.json`);
+          if (!fs3.existsSync(filePath)) {
             throw new Error(`Build not found in library: ${buildData.id}`);
           }
-          resolved = JSON.parse(fs2.readFileSync(filePath, "utf-8"));
+          resolved = JSON.parse(fs3.readFileSync(filePath, "utf-8"));
         } else {
           resolved = buildData;
         }
@@ -6351,13 +7221,13 @@ ${code}`
         const styles = style ? [style] : ["medieval", "modern", "nature", "scifi", "misc"];
         const builds = [];
         for (const s of styles) {
-          const dirPath = path3.join(libraryPath, s);
-          if (!fs2.existsSync(dirPath))
+          const dirPath = path4.join(libraryPath, s);
+          if (!fs3.existsSync(dirPath))
             continue;
-          const files = fs2.readdirSync(dirPath).filter((f) => f.endsWith(".json"));
+          const files = fs3.readdirSync(dirPath).filter((f) => f.endsWith(".json"));
           for (const file of files) {
             try {
-              const content = fs2.readFileSync(path3.join(dirPath, file), "utf-8");
+              const content = fs3.readFileSync(path4.join(dirPath, file), "utf-8");
               const data = JSON.parse(content);
               builds.push({
                 id: data.id || `${s}/${file.replace(".json", "")}`,
@@ -6396,11 +7266,11 @@ ${code}`
         if (!id) {
           throw new Error("Build ID is required for get_build");
         }
-        const filePath = path3.join(_RobloxStudioTools.findLibraryPath(), `${id}.json`);
-        if (!fs2.existsSync(filePath)) {
+        const filePath = path4.join(_RobloxStudioTools.findLibraryPath(), `${id}.json`);
+        if (!fs3.existsSync(filePath)) {
           throw new Error(`Build not found in library: ${id}`);
         }
-        const data = JSON.parse(fs2.readFileSync(filePath, "utf-8"));
+        const data = JSON.parse(fs3.readFileSync(filePath, "utf-8"));
         const result = {
           id: data.id,
           style: data.style,
@@ -6483,11 +7353,11 @@ ${code}`
           if (!buildId) {
             throw new Error(`Invalid ${validatedKeyPath}: model key "${modelKey}" is not defined in sceneData.models`);
           }
-          const filePath = path3.join(libraryPath, `${buildId}.json`);
-          if (!fs2.existsSync(filePath)) {
+          const filePath = path4.join(libraryPath, `${buildId}.json`);
+          if (!fs3.existsSync(filePath)) {
             throw new Error(`Build not found in library: ${buildId}`);
           }
-          const content = fs2.readFileSync(filePath, "utf-8");
+          const content = fs3.readFileSync(filePath, "utf-8");
           const buildData = JSON.parse(content);
           const buildName = buildId.split("/").pop() || buildId;
           expandedBuilds.push({
@@ -6827,11 +7697,11 @@ ${code}`
         return this.resolveUploadedReferenceImageId(decalId, instance_id);
       }
       async uploadAsset(filePath, assetType, displayName, description, userId, groupId) {
-        if (!fs2.existsSync(filePath)) {
+        if (!fs3.existsSync(filePath)) {
           throw new Error(`File not found: ${filePath}`);
         }
-        const fileContent = fs2.readFileSync(filePath);
-        const fileName = path3.basename(filePath);
+        const fileContent = fs3.readFileSync(filePath);
+        const fileName = path4.basename(filePath);
         if (assetType === "Decal" && this.cookieClient.hasCookie()) {
           const result2 = await this.cookieClient.uploadDecal(fileContent, displayName, description || "");
           return {
@@ -7056,10 +7926,10 @@ ${code}`
           return { content: [{ type: "text", text: JSON.stringify({ error: "plugin returned no base64 payload" }) }] };
         }
         const bytes = Buffer.from(response.base64, "base64");
-        const resolved = path3.resolve(outputPath);
+        const resolved = path4.resolve(outputPath);
         try {
-          fs2.mkdirSync(path3.dirname(resolved), { recursive: true });
-          fs2.writeFileSync(resolved, bytes);
+          fs3.mkdirSync(path4.dirname(resolved), { recursive: true });
+          fs3.writeFileSync(resolved, bytes);
         } catch (err) {
           return { content: [{ type: "text", text: JSON.stringify({ error: `failed to write ${resolved}: ${err.message}` }) }] };
         }
@@ -7092,9 +7962,9 @@ ${code}`
         let bytes;
         let sourceLabel;
         if (source.path !== void 0) {
-          const resolved = path3.resolve(source.path);
+          const resolved = path4.resolve(source.path);
           try {
-            bytes = fs2.readFileSync(resolved);
+            bytes = fs3.readFileSync(resolved);
           } catch (err) {
             return { content: [{ type: "text", text: JSON.stringify({ error: `failed to read ${resolved}: ${err.message}` }) }] };
           }
@@ -7264,6 +8134,24 @@ var init_proxy_bridge_service = __esm({
       getInstances() {
         return this.cachedInstances;
       }
+      async unregisterInstanceIdEverywhere(instanceId) {
+        const response = await fetch(`${this.primaryBaseUrl}/unregister-instance-id`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ instanceId })
+        });
+        if (!response.ok) {
+          const body = await response.text().catch(() => "");
+          throw new Error(`Proxy unregister failed (${response.status}): ${body || response.statusText}`);
+        }
+        const result = await response.json();
+        const removed = Array.isArray(result.removed) ? result.removed : [];
+        const removedKeys = new Set(removed.map((inst) => `${inst.instanceId}\0${inst.role}`));
+        if (removedKeys.size > 0) {
+          this.cachedInstances = this.cachedInstances.filter((inst) => !removedKeys.has(`${inst.instanceId}\0${inst.role}`));
+        }
+        return removed;
+      }
       /** Called when this proxy is being discarded (e.g. promotion to primary
           replaced it). Stops the background refresh so it doesn't leak. */
       stop() {
@@ -7317,7 +8205,7 @@ var init_proxy_bridge_service = __esm({
 // ../core/dist/server.js
 import { Server as Server2 } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema as CallToolRequestSchema2, ErrorCode as ErrorCode2, ListToolsRequestSchema as ListToolsRequestSchema2, McpError as McpError2 } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema as CallToolRequestSchema2, ErrorCode as ErrorCode3, ListToolsRequestSchema as ListToolsRequestSchema2, McpError as McpError3 } from "@modelcontextprotocol/sdk/types.js";
 var RobloxStudioMCPServer;
 var init_server = __esm({
   "../core/dist/server.js"() {
@@ -7326,6 +8214,7 @@ var init_server = __esm({
     init_tools();
     init_bridge_service();
     init_proxy_bridge_service();
+    init_mcp_compat();
     RobloxStudioMCPServer = class {
       server;
       tools;
@@ -7345,6 +8234,7 @@ var init_server = __esm({
         });
         this.bridge = new BridgeService();
         this.tools = new RobloxStudioTools(this.bridge);
+        registerResourceHandlers(this.server);
         this.setupToolHandlers();
       }
       setupToolHandlers() {
@@ -7360,11 +8250,11 @@ var init_server = __esm({
         this.server.setRequestHandler(CallToolRequestSchema2, async (request) => {
           const { name, arguments: args } = request.params;
           if (!this.allowedToolNames.has(name)) {
-            throw new McpError2(ErrorCode2.MethodNotFound, `Unknown tool: ${name}`);
+            throw new McpError3(ErrorCode3.MethodNotFound, `Unknown tool: ${name}`);
           }
           const handler = TOOL_HANDLERS[name];
           if (!handler) {
-            throw new McpError2(ErrorCode2.MethodNotFound, `Unknown tool: ${name}`);
+            throw new McpError3(ErrorCode3.MethodNotFound, `Unknown tool: ${name}`);
           }
           try {
             return await handler(this.tools, args ?? {});
@@ -7382,9 +8272,9 @@ var init_server = __esm({
                 isError: true
               };
             }
-            if (error instanceof McpError2)
+            if (error instanceof McpError3)
               throw error;
-            throw new McpError2(ErrorCode2.InternalError, `Tool execution failed: ${error instanceof Error ? error.message : String(error)}`);
+            throw new McpError3(ErrorCode3.InternalError, `Tool execution failed: ${error instanceof Error ? error.message : String(error)}`);
           }
         });
       }
@@ -8049,7 +8939,7 @@ var init_definitions = __esm({
       {
         name: "get_script_source",
         category: "read",
-        description: 'Get script source. Returns "source" and "numberedSource" (line-numbered). Use startLine/endLine for large scripts.',
+        description: 'Get script source. Returns "source" and "numberedSource" (line-numbered). Pass line_range for large scripts; without a range, large scripts are truncated (see the "truncated" flag and "note") to avoid flooding the context.',
         inputSchema: {
           type: "object",
           properties: {
@@ -8057,13 +8947,9 @@ var init_definitions = __esm({
               type: "string",
               description: "Canonical path to a LuaSourceContainer"
             },
-            startLine: {
-              type: "number",
-              description: "Start line (1-indexed)"
-            },
-            endLine: {
-              type: "number",
-              description: "End line (inclusive)"
+            line_range: {
+              type: "string",
+              description: 'Line range to return: "start-end" (e.g. "100-200"), open-ended ("100-" or "-200"), or a single line ("42").'
             },
             instance_id: {
               type: "string",
@@ -8099,7 +8985,7 @@ var init_definitions = __esm({
       {
         name: "edit_script_lines",
         category: "write",
-        description: "Replace exact text in a script. Without startLine, old_string must match exactly once in the script. Pass startLine (1-indexed, from get_script_source) to anchor the edit to a specific line when old_string is ambiguous (e.g. repeated closing braces).",
+        description: 'Replace exact text in a script. Without line_range, old_string must match exactly once in the script. Pass line_range as a single line (e.g. "42") to anchor the edit when old_string is ambiguous.',
         inputSchema: {
           type: "object",
           properties: {
@@ -8109,15 +8995,15 @@ var init_definitions = __esm({
             },
             old_string: {
               type: "string",
-              description: "Exact text to find and replace. Must be unique in the script unless startLine is provided."
+              description: "Exact text to find and replace. Must be unique in the script unless line_range is provided."
             },
             new_string: {
               type: "string",
               description: "Replacement text"
             },
-            startLine: {
-              type: "number",
-              description: "Optional 1-indexed line where old_string begins. When provided, skips uniqueness check and requires old_string to match starting at that exact line."
+            line_range: {
+              type: "string",
+              description: 'Optional single line where old_string begins, such as "42". When provided, skips uniqueness check and requires old_string to match starting at that exact line.'
             },
             instance_id: {
               type: "string",
@@ -8157,7 +9043,7 @@ var init_definitions = __esm({
       {
         name: "delete_script_lines",
         category: "write",
-        description: "Delete a range of lines. 1-indexed, inclusive.",
+        description: "Delete a range of lines. line_range is 1-indexed and inclusive.",
         inputSchema: {
           type: "object",
           properties: {
@@ -8165,20 +9051,16 @@ var init_definitions = __esm({
               type: "string",
               description: "Canonical path to a LuaSourceContainer"
             },
-            startLine: {
-              type: "number",
-              description: "Start line (1-indexed)"
-            },
-            endLine: {
-              type: "number",
-              description: "End line (inclusive)"
+            line_range: {
+              type: "string",
+              description: 'Line range to delete: "start-end" (e.g. "100-200") or a single line ("42"). Open-ended ranges are not accepted for deletion.'
             },
             instance_id: {
               type: "string",
               description: "Which connected Studio place to target. Required when multiple places are connected; omit when one. Use get_connected_instances to list available IDs."
             }
           },
-          required: ["instancePath", "startLine", "endLine"]
+          required: ["instancePath", "line_range"]
         }
       },
       // === Attributes ===
@@ -8424,21 +9306,21 @@ var init_definitions = __esm({
       {
         name: "grep_scripts",
         category: "read",
-        description: "Ripgrep-inspired search across all script sources. Supports literal and Lua pattern matching, context lines, early termination, and results grouped by script with line/column numbers.",
+        description: 'Ripgrep-inspired search across all script sources. Supports literal and Lua pattern matching (with top-level "|" alternation), context lines, early termination, and results grouped by script with line/column numbers.',
         inputSchema: {
           type: "object",
           properties: {
             pattern: {
               type: "string",
-              description: "Search pattern (literal string or Lua pattern)"
+              description: 'Search text. Literal by default; with usePattern=true it is a case-sensitive Lua pattern with top-level "|" alternation (e.g. "foo|bar").'
             },
             caseSensitive: {
               type: "boolean",
-              description: "Case-sensitive search (default: false)"
+              description: "Literal search case sensitivity (default: false). Lua pattern mode is always case-sensitive; passing false with usePattern=true is rejected."
             },
             usePattern: {
               type: "boolean",
-              description: "Use Lua pattern matching instead of literal (default: false)"
+              description: 'Use case-sensitive Lua pattern matching instead of literal search (default: false). Supports top-level alternation: "a|b" matches a line containing "a" or "b". Note: Lua patterns are NOT PCRE \u2014 use %d/%a/%w classes and ".-" (not ".*?"); ^ $ ( ) . % + - * ? [ ] are magic.'
             },
             contextLines: {
               type: "number",
@@ -8477,7 +9359,7 @@ var init_definitions = __esm({
       {
         name: "manage_instance",
         category: "write",
-        description: 'Launch, close, inspect, and find revisions for Studio instances. Use action="list_place_versions" with place_id to retrieve version numbers through Open Cloud asset versions, then action="launch" with source="place_revision" and place_version to open an older revision. action="close" can close an MCP-managed instance or an explicitly connected edit instance by instance_id. action="launch" source="published_place" opens the latest published place and is blocked if that place_id is already connected; source="place_revision" is allowed because Studio opens explicit past revisions as anonymous local copies. Requires ROBLOX_OPEN_CLOUD_API_KEY with asset:read for list_place_versions.',
+        description: 'Launch, close, inspect, and find revisions for Studio instances. Use action="launch" with source="baseplate" for a blank place, or source="local_file" with local_place_file for a local place; neither uses place_id. Use action="list_place_versions" with place_id to retrieve version numbers through Open Cloud asset versions, then action="launch" with source="place_revision", place_id, and place_version to open an older revision. action="close" can close an MCP-managed instance or an explicitly connected edit instance by instance_id. action="launch" source="published_place" opens the latest published place and is blocked if that place_id is already connected; source="place_revision" is allowed because Studio opens explicit past revisions as anonymous local copies. Requires ROBLOX_OPEN_CLOUD_API_KEY with asset:read for list_place_versions.',
         inputSchema: {
           type: "object",
           properties: {
@@ -8489,7 +9371,7 @@ var init_definitions = __esm({
             source: {
               type: "string",
               enum: ["baseplate", "local_file", "published_place", "place_revision"],
-              description: 'Required for action="launch". published_place opens the latest place; place_revision opens a specific older version as an anonymous local copy.'
+              description: 'Required for action="launch". baseplate/local_file do not use place_id; published_place opens the latest place; place_revision opens a specific older version as an anonymous local copy.'
             },
             local_place_file: {
               type: "string",
@@ -8497,11 +9379,7 @@ var init_definitions = __esm({
             },
             place_id: {
               type: "number",
-              description: 'Required for source="published_place", source="place_revision", and action="list_place_versions".'
-            },
-            universe_id: {
-              type: "number",
-              description: "Optional for published_place/place_revision launches; derived from place_id when omitted."
+              description: 'Only used for source="published_place", source="place_revision", and action="list_place_versions". Do not pass for source="baseplate" or source="local_file".'
             },
             place_version: {
               type: "number",
@@ -8838,7 +9716,7 @@ var init_definitions = __esm({
       {
         name: "multiplayer_playtest",
         category: "write",
-        description: 'Start, inspect, add players to, remove a client from, or end a StudioTestService multiplayer playtest. Use action="start" with numPlayers, action="status", action="add_players" with numPlayers, action="leave_client" with target="client-N", or action="end". Returns brief lifecycle status only; read script output with get_runtime_logs.',
+        description: 'Start or inspect a StudioTestService multiplayer playtest. Use action="start" with numPlayers and force=true only when you accept that MCP cannot stop it and you must manually close the multiplayer test windows afterward. action="status" inspects state, action="add_players" adds players, and action="leave_client" removes one client. action="end" is disabled for now and returns the StudioTestService:EndTest broken-API reason. Returns brief lifecycle status only; read script output with get_runtime_logs.',
         inputSchema: {
           type: "object",
           properties: {
@@ -8859,11 +9737,15 @@ var init_definitions = __esm({
               description: 'For action="start": JSON-compatible table passed to StudioTestService:GetTestArgs() on server and clients.'
             },
             value: {
-              description: 'For action="end": JSON-compatible value returned to the edit-side ExecuteMultiplayerTestAsync call.'
+              description: 'Ignored while action="end" is disabled.'
+            },
+            force: {
+              type: "boolean",
+              description: 'Required for action="start". Pass true only if you understand StudioTestService:EndTest is broken in this flow and you will manually close the multiplayer test windows.'
             },
             timeout: {
               type: "number",
-              description: "Max seconds to wait for action completion. Defaults to 30."
+              description: "Max seconds to wait for start peer detection or action completion. Defaults to 30."
             },
             instance_id: {
               type: "string",
@@ -10098,6 +10980,31 @@ part(0,2,0,2,1,1,"b")`,
           },
           required: ["pattern", "replacement"]
         }
+      },
+      // === Documentation ===
+      {
+        name: "get_roblox_docs",
+        category: "read",
+        description: 'Fetch official Roblox engine API documentation as markdown from create.roblox.com. Call this BEFORE writing or editing code that uses an engine class, enum, datatype, or Luau library you are not fully certain about (e.g. ProximityPrompt, Enum.KeyCode, CFrame, TweenService) \u2014 the page includes the description, properties, methods, events, and code samples. Results are cached, so repeat lookups are cheap. Very large pages are truncated with a section index; pass section (e.g. "Properties", "Methods", "Events") to read one section in full.',
+        inputSchema: {
+          type: "object",
+          properties: {
+            name: {
+              type: "string",
+              description: 'Exact PascalCase name of the class, enum, datatype, or library (e.g. "ProximityPrompt", "KeyCode", "CFrame", "table")'
+            },
+            doc_type: {
+              type: "string",
+              enum: ["classes", "enums", "datatypes", "libraries", "globals"],
+              description: "Documentation category (default: classes)"
+            },
+            section: {
+              type: "string",
+              description: 'Optional "##"-level section to return instead of the whole page (e.g. "Description", "Properties", "Methods", "Events", "Code Samples")'
+            }
+          },
+          required: ["name"]
+        }
       }
     ];
     DEPRECATED_TOOL_DEFINITIONS = [
@@ -10143,7 +11050,7 @@ part(0,2,0,2,1,1,"b")`,
       {
         name: "multiplayer_test_start",
         category: "write",
-        description: 'Deprecated. Use multiplayer_playtest with action="start" instead. Starts a StudioTestService multiplayer test.',
+        description: 'Deprecated. Use multiplayer_playtest with action="start" instead. Starts a StudioTestService multiplayer test only when force=true acknowledges that MCP cannot stop it and the test windows must be closed manually.',
         inputSchema: {
           type: "object",
           properties: {
@@ -10154,6 +11061,10 @@ part(0,2,0,2,1,1,"b")`,
             testArgs: {
               description: "JSON-compatible table passed to StudioTestService:GetTestArgs() on server and clients."
             },
+            force: {
+              type: "boolean",
+              description: "Required. Pass true only if you understand StudioTestService:EndTest is broken in this flow and you will manually close the multiplayer test windows."
+            },
             timeout: {
               type: "number",
               description: "Max seconds to wait for server + clients to register (default 30)."
@@ -10163,7 +11074,7 @@ part(0,2,0,2,1,1,"b")`,
               description: "Which connected Studio place to target. Required when multiple places are connected; omit when one. Use get_connected_instances to list available IDs."
             }
           },
-          required: ["numPlayers"]
+          required: ["numPlayers", "force"]
         }
       },
       {
@@ -10228,16 +11139,16 @@ part(0,2,0,2,1,1,"b")`,
       {
         name: "multiplayer_test_end",
         category: "write",
-        description: 'Deprecated. Use multiplayer_playtest with action="end" instead. Ends a running StudioTestService multiplayer test.',
+        description: "Deprecated. Multiplayer StudioTestService stop/end is disabled for now because StudioTestService:EndTest is broken in this flow. This tool returns a disabled error and does not call EndTest.",
         inputSchema: {
           type: "object",
           properties: {
             value: {
-              description: "JSON-compatible value returned to the edit-side ExecuteMultiplayerTestAsync call."
+              description: "Ignored while multiplayer stop/end is disabled."
             },
             timeout: {
               type: "number",
-              description: "Max seconds to wait for runtime peers to disconnect (default 30)."
+              description: "Ignored while multiplayer stop/end is disabled."
             },
             instance_id: {
               type: "string",
@@ -10253,15 +11164,15 @@ part(0,2,0,2,1,1,"b")`,
 });
 
 // ../core/dist/install-plugin-helpers.js
-import { existsSync as existsSync4, readFileSync as readFileSync4, unlinkSync } from "fs";
+import { existsSync as existsSync4, readFileSync as readFileSync5, unlinkSync } from "fs";
 import { execSync } from "child_process";
-import { join as join3 } from "path";
-import { homedir as homedir3 } from "os";
+import { join as join4 } from "path";
+import { homedir as homedir4 } from "os";
 function isWSL() {
   if (process.platform !== "linux")
     return false;
   try {
-    const v = readFileSync4("/proc/version", "utf8");
+    const v = readFileSync5("/proc/version", "utf8");
     return /microsoft|wsl/i.test(v);
   } catch {
     return false;
@@ -10279,7 +11190,7 @@ function getWindowsUserPluginsDir() {
     }).toString().trim();
     if (!linuxPath)
       return null;
-    return join3(linuxPath, "Roblox", "Plugins");
+    return join4(linuxPath, "Roblox", "Plugins");
   } catch {
     return null;
   }
@@ -10288,7 +11199,7 @@ function getPluginsFolder() {
   if (process.env.MCP_PLUGINS_DIR)
     return process.env.MCP_PLUGINS_DIR;
   if (process.platform === "win32") {
-    return join3(process.env.LOCALAPPDATA || join3(homedir3(), "AppData", "Local"), "Roblox", "Plugins");
+    return join4(process.env.LOCALAPPDATA || join4(homedir4(), "AppData", "Local"), "Roblox", "Plugins");
   }
   if (isWSL()) {
     const win = getWindowsUserPluginsDir();
@@ -10296,10 +11207,10 @@ function getPluginsFolder() {
       return win;
     console.warn("[install-plugin] WSL detected but could not resolve Windows %LOCALAPPDATA%. Falling back to ~/Documents/Roblox/Plugins/ - you will likely need to copy the rbxmx to /mnt/c/Users/<you>/AppData/Local/Roblox/Plugins/ manually. Set MCP_PLUGINS_DIR to skip detection.");
   }
-  return join3(homedir3(), "Documents", "Roblox", "Plugins");
+  return join4(homedir4(), "Documents", "Roblox", "Plugins");
 }
 function handleVariantConflict({ pluginsFolder, otherAssetName, replace, log = console.log, warn = console.warn }) {
-  const otherDest = join3(pluginsFolder, otherAssetName);
+  const otherDest = join4(pluginsFolder, otherAssetName);
   if (!existsSync4(otherDest))
     return;
   if (replace) {
@@ -10345,8 +11256,8 @@ __export(install_plugin_exports, {
   installBundledPlugin: () => installBundledPlugin,
   installPlugin: () => installPlugin
 });
-import { copyFileSync as copyFileSync2, createWriteStream, existsSync as existsSync5, mkdirSync as mkdirSync3, readFileSync as readFileSync5, unlinkSync as unlinkSync2 } from "fs";
-import { dirname as dirname3, join as join4 } from "path";
+import { copyFileSync as copyFileSync2, createWriteStream, existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync6, unlinkSync as unlinkSync2 } from "fs";
+import { dirname as dirname3, join as join5 } from "path";
 import { fileURLToPath } from "url";
 import { get } from "https";
 function httpsGet(url) {
@@ -10407,7 +11318,7 @@ function prepareInstall({
 }) {
   const pluginsFolder = getPluginsFolder();
   if (!existsSync5(pluginsFolder)) {
-    mkdirSync3(pluginsFolder, { recursive: true });
+    mkdirSync4(pluginsFolder, { recursive: true });
   }
   handleVariantConflict({
     pluginsFolder,
@@ -10421,21 +11332,21 @@ function prepareInstall({
 function bundledAssetPath() {
   const currentDir = dirname3(fileURLToPath(import.meta.url));
   const candidates = [
-    join4(currentDir, "..", "studio-plugin", ASSET_NAME),
-    join4(currentDir, "..", "..", "..", "studio-plugin", ASSET_NAME)
+    join5(currentDir, "..", "studio-plugin", ASSET_NAME),
+    join5(currentDir, "..", "..", "..", "studio-plugin", ASSET_NAME)
   ];
   return candidates.find((candidate) => existsSync5(candidate)) ?? null;
 }
 function packageVersion() {
   const currentDir = dirname3(fileURLToPath(import.meta.url));
-  const pkg = JSON.parse(readFileSync5(join4(currentDir, "..", "package.json"), "utf8"));
+  const pkg = JSON.parse(readFileSync6(join5(currentDir, "..", "package.json"), "utf8"));
   if (!pkg.version) {
     throw new Error("Package version not found");
   }
   return pkg.version;
 }
 function bundledPluginVersion(source) {
-  const match = readFileSync5(source, "utf8").match(/local CURRENT_VERSION = "([^"]+)"/);
+  const match = readFileSync6(source, "utf8").match(/local CURRENT_VERSION = "([^"]+)"/);
   return match ? match[1] : null;
 }
 function assertBundledPluginVersion(source) {
@@ -10449,8 +11360,8 @@ function assertBundledPluginVersion(source) {
 }
 function filesMatch(a, b) {
   if (!existsSync5(b)) return false;
-  const aBytes = readFileSync5(a);
-  const bBytes = readFileSync5(b);
+  const aBytes = readFileSync6(a);
+  const bBytes = readFileSync6(b);
   return aBytes.length === bBytes.length && aBytes.equals(bBytes);
 }
 async function installBundledPlugin(options = {}) {
@@ -10463,7 +11374,7 @@ async function installBundledPlugin(options = {}) {
   }
   assertBundledPluginVersion(source);
   const pluginsFolder = prepareInstall({ replaceVariant, log, warn });
-  const dest = join4(pluginsFolder, ASSET_NAME);
+  const dest = join5(pluginsFolder, ASSET_NAME);
   if (filesMatch(source, dest)) return;
   copyFileSync2(source, dest);
   log(`Installed ${ASSET_NAME} to ${dest}`);
@@ -10476,7 +11387,7 @@ async function installPlugin(options = {}) {
   const bundled = bundledAssetPath();
   if (bundled) {
     assertBundledPluginVersion(bundled);
-    const dest2 = join4(pluginsFolder, ASSET_NAME);
+    const dest2 = join5(pluginsFolder, ASSET_NAME);
     if (filesMatch(bundled, dest2)) {
       log(`${ASSET_NAME} already installed.`);
       return;
@@ -10491,7 +11402,7 @@ async function installPlugin(options = {}) {
   if (!asset) {
     throw new Error(`${ASSET_NAME} not found in release ${release.tag_name}`);
   }
-  const dest = join4(pluginsFolder, ASSET_NAME);
+  const dest = join5(pluginsFolder, ASSET_NAME);
   log(`Downloading ${ASSET_NAME} from ${release.tag_name}...`);
   await download(asset.browser_download_url, dest);
   log(`Installed to ${dest}`);