uloop-cli 0.68.2 → 0.69.0

package/dist/cli.bundle.cjs

@@ -795,7 +795,7 @@ ${itemIndentStr}`);
 var require_option = __commonJS({
   "node_modules/commander/lib/option.js"(exports2) {
     var { InvalidArgumentError: InvalidArgumentError2 } = require_error();
-    var Option2 = class {
+    var Option3 = class {
       /**
        * Initialize a new `Option` with the given `flags` and `description`.
        *
@@ -1099,7 +1099,7 @@ var require_option = __commonJS({
         );
       return { shortFlag, longFlag };
     }
-    exports2.Option = Option2;
+    exports2.Option = Option3;
     exports2.DualOptions = DualOptions;
   }
 });
@@ -1195,7 +1195,7 @@ var require_command = __commonJS({
     var { Argument: Argument2, humanReadableArgName } = require_argument();
     var { CommanderError: CommanderError2 } = require_error();
     var { Help: Help2, stripColor } = require_help();
-    var { Option: Option2, DualOptions } = require_option();
+    var { Option: Option3, DualOptions } = require_option();
     var { suggestSimilar } = require_suggestSimilar();
     var Command2 = class _Command extends EventEmitter {
       /**
@@ -1680,7 +1680,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @return {Option} new option
        */
       createOption(flags, description) {
-        return new Option2(flags, description);
+        return new Option3(flags, description);
       }
       /**
        * Wrap parseArgs to catch 'commander.invalidArgument'.
@@ -1805,7 +1805,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @private
        */
       _optionEx(config, flags, description, fn, defaultValue) {
-        if (typeof flags === "object" && flags instanceof Option2) {
+        if (typeof flags === "object" && flags instanceof Option3) {
           throw new Error(
             "To add an Option object use addOption() instead of option() or requiredOption()"
           );
@@ -3437,13 +3437,13 @@ var require_commander = __commonJS({
     var { Command: Command2 } = require_command();
     var { CommanderError: CommanderError2, InvalidArgumentError: InvalidArgumentError2 } = require_error();
     var { Help: Help2 } = require_help();
-    var { Option: Option2 } = require_option();
+    var { Option: Option3 } = require_option();
     exports2.program = new Command2();
     exports2.createCommand = (name) => new Command2(name);
-    exports2.createOption = (flags, description) => new Option2(flags, description);
+    exports2.createOption = (flags, description) => new Option3(flags, description);
     exports2.createArgument = (name, description) => new Argument2(name, description);
     exports2.Command = Command2;
-    exports2.Option = Option2;
+    exports2.Option = Option3;
     exports2.Argument = Argument2;
     exports2.Help = Help2;
     exports2.CommanderError = CommanderError2;
@@ -5384,7 +5384,7 @@ var require_semver2 = __commonJS({
 
 // src/cli.ts
 var import_fs8 = require("fs");
-var import_path9 = require("path");
+var import_path10 = require("path");
 var import_os2 = require("os");
 var import_child_process = require("child_process");
 
@@ -5408,7 +5408,7 @@ var {
 // src/execute-tool.ts
 var readline = __toESM(require("readline"), 1);
 var import_fs5 = require("fs");
-var import_path5 = require("path");
+var import_path6 = require("path");
 var semver = __toESM(require_semver2(), 1);
 
 // src/direct-unity-client.ts
@@ -5736,7 +5736,12 @@ function findUnityProjectInParentsWithoutUloop(startPath) {
 }
 
 // src/port-resolver.ts
-var DEFAULT_PORT = 8700;
+var UnityNotRunningError = class extends Error {
+  constructor(projectRoot) {
+    super("UNITY_NOT_RUNNING");
+    this.projectRoot = projectRoot;
+  }
+};
 function normalizePort(port) {
   if (typeof port !== "number") {
     return null;
@@ -5780,11 +5785,7 @@ async function resolveUnityPort(explicitPort, projectPath) {
   }
   if (projectPath !== void 0) {
     const resolved = validateProjectPath(projectPath);
-    const settingsPort2 = await readPortFromSettings(resolved);
-    if (settingsPort2 !== null) {
-      return settingsPort2;
-    }
-    return DEFAULT_PORT;
+    return await readPortFromSettingsOrThrow(resolved);
   }
   const projectRoot = findUnityProjectRoot();
   if (projectRoot === null) {
@@ -5792,39 +5793,98 @@ async function resolveUnityPort(explicitPort, projectPath) {
       "Unity project not found. Use --port or --project-path option to specify the target."
     );
   }
-  const settingsPort = await readPortFromSettings(projectRoot);
-  if (settingsPort !== null) {
-    return settingsPort;
-  }
-  return DEFAULT_PORT;
+  return await readPortFromSettingsOrThrow(projectRoot);
 }
-async function readPortFromSettings(projectRoot) {
+function createSettingsReadError(projectRoot) {
+  const settingsPath = (0, import_path2.join)(projectRoot, "UserSettings/UnityMcpSettings.json");
+  return new Error(
+    `Could not read Unity server port from settings.
+
+  Settings file: ${settingsPath}
+
+Run 'uloop launch -r' to restart Unity, or use --port to specify the port directly.`
+  );
+}
+async function readPortFromSettingsOrThrow(projectRoot) {
   const settingsPath = (0, import_path2.join)(projectRoot, "UserSettings/UnityMcpSettings.json");
   if (!(0, import_fs2.existsSync)(settingsPath)) {
-    return null;
+    throw createSettingsReadError(projectRoot);
   }
   let content;
   try {
     content = await (0, import_promises.readFile)(settingsPath, "utf-8");
   } catch {
-    return null;
+    throw createSettingsReadError(projectRoot);
   }
-  let settings;
+  let parsed;
   try {
-    settings = JSON.parse(content);
+    parsed = JSON.parse(content);
   } catch {
-    return null;
+    throw createSettingsReadError(projectRoot);
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    throw createSettingsReadError(projectRoot);
+  }
+  const settings = parsed;
+  if (settings.isServerRunning === false) {
+    throw new UnityNotRunningError(projectRoot);
+  }
+  const port = resolvePortFromUnitySettings(settings);
+  if (port === null) {
+    throw createSettingsReadError(projectRoot);
+  }
+  return port;
+}
+
+// src/project-validator.ts
+var import_node_assert = __toESM(require("node:assert"), 1);
+var import_promises2 = require("fs/promises");
+var import_path3 = require("path");
+var ProjectMismatchError = class extends Error {
+  constructor(expectedProjectRoot, connectedProjectRoot) {
+    super("PROJECT_MISMATCH");
+    this.expectedProjectRoot = expectedProjectRoot;
+    this.connectedProjectRoot = connectedProjectRoot;
+  }
+};
+var JSON_RPC_METHOD_NOT_FOUND = -32601;
+async function normalizePath(path) {
+  const resolved = await (0, import_promises2.realpath)(path);
+  return resolved.replace(/\/+$/, "");
+}
+async function validateConnectedProject(client, expectedProjectRoot) {
+  (0, import_node_assert.default)(client.isConnected(), "client must be connected before validation");
+  let response;
+  try {
+    response = await client.sendRequest("get-version", {});
+  } catch (error) {
+    if (error instanceof Error && (error.message.includes(`${JSON_RPC_METHOD_NOT_FOUND}`) || /method not found/i.test(error.message))) {
+      console.error(
+        "Warning: Could not verify project identity (get-version not available). Consider updating uLoopMCP package."
+      );
+      return;
+    }
+    throw error;
+  }
+  if (typeof response?.DataPath !== "string" || response.DataPath.length === 0) {
+    console.error("Warning: Could not verify project identity (invalid get-version response).");
+    return;
+  }
+  const connectedProjectRoot = (0, import_path3.dirname)(response.DataPath);
+  const normalizedExpected = await normalizePath(expectedProjectRoot);
+  const normalizedConnected = await normalizePath(connectedProjectRoot);
+  if (normalizedExpected !== normalizedConnected) {
+    throw new ProjectMismatchError(normalizedExpected, normalizedConnected);
   }
-  return resolvePortFromUnitySettings(settings);
 }
 
 // src/tool-cache.ts
 var import_fs3 = require("fs");
-var import_path3 = require("path");
+var import_path4 = require("path");
 
 // src/default-tools.json
 var default_tools_default = {
-  version: "0.68.2",
+  version: "0.69.0",
   tools: [
     {
       name: "compile",
@@ -6064,6 +6124,34 @@ var default_tools_default = {
         }
       }
     },
+    {
+      name: "get-unity-search-providers",
+      description: "Get detailed information about Unity Search providers including display names, descriptions, active status, and capabilities",
+      inputSchema: {
+        type: "object",
+        properties: {
+          ProviderId: {
+            type: "string",
+            description: "Specific provider ID to get details for (empty = all providers). Examples: 'asset', 'scene', 'menu', 'settings'"
+          },
+          ActiveOnly: {
+            type: "boolean",
+            description: "Whether to include only active providers",
+            default: false
+          },
+          SortByPriority: {
+            type: "boolean",
+            description: "Sort providers by priority (lower number = higher priority)",
+            default: true
+          },
+          IncludeDescriptions: {
+            type: "boolean",
+            description: "Include detailed descriptions for each provider",
+            default: true
+          }
+        }
+      }
+    },
     {
       name: "get-menu-items",
       description: "Retrieve Unity MenuItems",
@@ -6263,21 +6351,24 @@ var default_tools_default = {
 // src/tool-cache.ts
 var CACHE_DIR = ".uloop";
 var CACHE_FILE = "tools.json";
-function getCacheDir() {
+function getCacheDir(projectPath) {
+  if (projectPath !== void 0) {
+    return (0, import_path4.join)(projectPath, CACHE_DIR);
+  }
   const projectRoot = findUnityProjectRoot();
   if (projectRoot === null) {
-    return (0, import_path3.join)(process.cwd(), CACHE_DIR);
+    return (0, import_path4.join)(process.cwd(), CACHE_DIR);
   }
-  return (0, import_path3.join)(projectRoot, CACHE_DIR);
+  return (0, import_path4.join)(projectRoot, CACHE_DIR);
 }
-function getCachePath() {
-  return (0, import_path3.join)(getCacheDir(), CACHE_FILE);
+function getCachePath(projectPath) {
+  return (0, import_path4.join)(getCacheDir(projectPath), CACHE_FILE);
 }
 function getDefaultTools() {
   return default_tools_default;
 }
-function loadToolsCache() {
-  const cachePath = getCachePath();
+function loadToolsCache(projectPath) {
+  const cachePath = getCachePath(projectPath);
   if ((0, import_fs3.existsSync)(cachePath)) {
     try {
       const content = (0, import_fs3.readFileSync)(cachePath, "utf-8");
@@ -6303,6 +6394,10 @@ function hasCacheFile() {
 function getCacheFilePath() {
   return getCachePath();
 }
+function getDefaultToolNames() {
+  const defaultTools = getDefaultTools();
+  return new Set(defaultTools.tools.map((tool) => tool.name));
+}
 function getCachedServerVersion() {
   const cachePath = getCachePath();
   if (!(0, import_fs3.existsSync)(cachePath)) {
@@ -6318,7 +6413,7 @@ function getCachedServerVersion() {
 }
 
 // src/version.ts
-var VERSION = "0.68.2";
+var VERSION = "0.69.0";
 
 // src/spinner.ts
 var SPINNER_FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
@@ -6353,10 +6448,10 @@ function createSpinner(initialMessage) {
 }
 
 // src/compile-helpers.ts
-var import_node_assert = __toESM(require("node:assert"), 1);
+var import_node_assert2 = __toESM(require("node:assert"), 1);
 var import_fs4 = require("fs");
 var net2 = __toESM(require("net"), 1);
-var import_path4 = require("path");
+var import_path5 = require("path");
 var SAFE_REQUEST_ID_PATTERN = /^[a-zA-Z0-9_-]+$/;
 var COMPILE_FORCE_RECOMPILE_ARG_KEYS = [
   "ForceRecompile",
@@ -6416,22 +6511,22 @@ function ensureCompileRequestId(args) {
   return requestId;
 }
 function getCompileResultFilePath(projectRoot, requestId) {
-  (0, import_node_assert.default)(
+  (0, import_node_assert2.default)(
     SAFE_REQUEST_ID_PATTERN.test(requestId),
     `requestId contains unsafe characters: '${requestId}'`
   );
-  return (0, import_path4.join)(projectRoot, "Temp", "uLoopMCP", "compile-results", `${requestId}.json`);
+  return (0, import_path5.join)(projectRoot, "Temp", "uLoopMCP", "compile-results", `${requestId}.json`);
 }
 function isUnityBusyByLockFiles(projectRoot) {
-  const compilingLockPath = (0, import_path4.join)(projectRoot, "Temp", "compiling.lock");
+  const compilingLockPath = (0, import_path5.join)(projectRoot, "Temp", "compiling.lock");
   if ((0, import_fs4.existsSync)(compilingLockPath)) {
     return true;
   }
-  const domainReloadLockPath = (0, import_path4.join)(projectRoot, "Temp", "domainreload.lock");
+  const domainReloadLockPath = (0, import_path5.join)(projectRoot, "Temp", "domainreload.lock");
   if ((0, import_fs4.existsSync)(domainReloadLockPath)) {
     return true;
   }
-  const serverStartingLockPath = (0, import_path4.join)(projectRoot, "Temp", "serverstarting.lock");
+  const serverStartingLockPath = (0, import_path5.join)(projectRoot, "Temp", "serverstarting.lock");
   return (0, import_fs4.existsSync)(serverStartingLockPath);
 }
 function stripUtf8Bom(content) {
@@ -6641,15 +6736,15 @@ function checkUnityBusyState(projectPath) {
   if (projectRoot === null) {
     return;
   }
-  const compilingLock = (0, import_path5.join)(projectRoot, "Temp", "compiling.lock");
+  const compilingLock = (0, import_path6.join)(projectRoot, "Temp", "compiling.lock");
   if ((0, import_fs5.existsSync)(compilingLock)) {
     throw new Error("UNITY_COMPILING");
   }
-  const domainReloadLock = (0, import_path5.join)(projectRoot, "Temp", "domainreload.lock");
+  const domainReloadLock = (0, import_path6.join)(projectRoot, "Temp", "domainreload.lock");
   if ((0, import_fs5.existsSync)(domainReloadLock)) {
     throw new Error("UNITY_DOMAIN_RELOAD");
   }
-  const serverStartingLock = (0, import_path5.join)(projectRoot, "Temp", "serverstarting.lock");
+  const serverStartingLock = (0, import_path6.join)(projectRoot, "Temp", "serverstarting.lock");
   if ((0, import_fs5.existsSync)(serverStartingLock)) {
     throw new Error("UNITY_SERVER_STARTING");
   }
@@ -6672,12 +6767,16 @@ async function executeToolCommand(toolName, params, globalOptions) {
   let lastError;
   let immediateResult;
   const projectRoot = globalOptions.projectPath !== void 0 ? validateProjectPath(globalOptions.projectPath) : findUnityProjectRoot();
+  const shouldValidateProject = portNumber === void 0 && projectRoot !== null;
   let requestDispatched = false;
   for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
     checkUnityBusyState(globalOptions.projectPath);
     const client = new DirectUnityClient(port);
     try {
       await client.connect();
+      if (shouldValidateProject) {
+        await validateConnectedProject(client, projectRoot);
+      }
       spinner.update(`Executing ${toolName}...`);
       requestDispatched = true;
       const result = await client.sendRequest(toolName, params);
@@ -6789,6 +6888,8 @@ async function listAvailableTools(globalOptions) {
     portNumber = parsed;
   }
   const port = await resolveUnityPort(portNumber, globalOptions.projectPath);
+  const projectRoot = globalOptions.projectPath !== void 0 ? validateProjectPath(globalOptions.projectPath) : findUnityProjectRoot();
+  const shouldValidateProject = portNumber === void 0 && projectRoot !== null;
   const restoreStdin = suppressStdinEcho();
   const spinner = createSpinner("Connecting to Unity...");
   let lastError;
@@ -6797,6 +6898,9 @@ async function listAvailableTools(globalOptions) {
     const client = new DirectUnityClient(port);
     try {
       await client.connect();
+      if (shouldValidateProject) {
+        await validateConnectedProject(client, projectRoot);
+      }
       spinner.update("Fetching tool list...");
       const result = await client.sendRequest("get-tool-details", { IncludeDevelopmentOnly: false });
       if (!result.Tools || !Array.isArray(result.Tools)) {
@@ -6846,6 +6950,8 @@ async function syncTools(globalOptions) {
     portNumber = parsed;
   }
   const port = await resolveUnityPort(portNumber, globalOptions.projectPath);
+  const projectRoot = globalOptions.projectPath !== void 0 ? validateProjectPath(globalOptions.projectPath) : findUnityProjectRoot();
+  const shouldValidateProject = portNumber === void 0 && projectRoot !== null;
   const restoreStdin = suppressStdinEcho();
   const spinner = createSpinner("Connecting to Unity...");
   let lastError;
@@ -6854,6 +6960,9 @@ async function syncTools(globalOptions) {
     const client = new DirectUnityClient(port);
     try {
       await client.connect();
+      if (shouldValidateProject) {
+        await validateConnectedProject(client, projectRoot);
+      }
       spinner.update("Syncing tools...");
       const result = await client.sendRequest("get-tool-details", { IncludeDevelopmentOnly: false });
       spinner.stop();
@@ -6908,7 +7017,7 @@ function pascalToKebabCase(pascal) {
 
 // src/skills/skills-manager.ts
 var import_fs7 = require("fs");
-var import_path7 = require("path");
+var import_path8 = require("path");
 var import_os = require("os");
 
 // src/skills/deprecated-skills.ts
@@ -6916,20 +7025,20 @@ var DEPRECATED_SKILLS = [
   "uloop-capture-window",
   // renamed to uloop-screenshot in v0.54.0
   "uloop-get-provider-details"
-  // internal development-only tool, not for end users
+  // renamed to uloop-get-unity-search-providers
 ];
 
 // src/tool-settings-loader.ts
 var import_fs6 = require("fs");
-var import_path6 = require("path");
+var import_path7 = require("path");
 var ULOOP_DIR = ".uloop";
 var TOOL_SETTINGS_FILE = "settings.tools.json";
 function loadDisabledTools(projectPath) {
-  const projectRoot = projectPath !== void 0 ? (0, import_path6.resolve)(projectPath) : findUnityProjectRoot();
+  const projectRoot = projectPath !== void 0 ? (0, import_path7.resolve)(projectPath) : findUnityProjectRoot();
   if (projectRoot === null) {
     return [];
   }
-  const settingsPath = (0, import_path6.join)(projectRoot, ULOOP_DIR, TOOL_SETTINGS_FILE);
+  const settingsPath = (0, import_path7.join)(projectRoot, ULOOP_DIR, TOOL_SETTINGS_FILE);
   let content;
   try {
     content = (0, import_fs6.readFileSync)(settingsPath, "utf-8");
@@ -7004,7 +7113,7 @@ var SkillsPathConstants = class _SkillsPathConstants {
   ];
 };
 function getGlobalSkillsDir(target) {
-  return (0, import_path7.join)((0, import_os.homedir)(), target.projectDir, "skills");
+  return (0, import_path8.join)((0, import_os.homedir)(), target.projectDir, "skills");
 }
 function getProjectSkillsDir(target) {
   const status = getUnityProjectStatus();
@@ -7019,11 +7128,11 @@ function getProjectSkillsDir(target) {
 Please install uLoopMCP package first, then run this command again.`
     );
   }
-  return (0, import_path7.join)(status.path, target.projectDir, "skills");
+  return (0, import_path8.join)(status.path, target.projectDir, "skills");
 }
 function getSkillPath(skillDirName, target, global) {
   const baseDir = global ? getGlobalSkillsDir(target) : getProjectSkillsDir(target);
-  return (0, import_path7.join)(baseDir, skillDirName, target.skillFileName);
+  return (0, import_path8.join)(baseDir, skillDirName, target.skillFileName);
 }
 function isSkillInstalled(skill, target, global) {
   const skillPath = getSkillPath(skill.dirName, target, global);
@@ -7031,8 +7140,8 @@ function isSkillInstalled(skill, target, global) {
 }
 function isSkillOutdated(skill, target, global) {
   const baseDir = global ? getGlobalSkillsDir(target) : getProjectSkillsDir(target);
-  const skillDir = (0, import_path7.join)(baseDir, skill.dirName);
-  const skillPath = (0, import_path7.join)(skillDir, target.skillFileName);
+  const skillDir = (0, import_path8.join)(baseDir, skill.dirName);
+  const skillPath = (0, import_path8.join)(skillDir, target.skillFileName);
   if (!(0, import_fs7.existsSync)(skillPath)) {
     return false;
   }
@@ -7043,7 +7152,7 @@ function isSkillOutdated(skill, target, global) {
   if ("additionalFiles" in skill && skill.additionalFiles) {
     const additionalFiles = skill.additionalFiles;
     for (const [relativePath, expectedContent] of Object.entries(additionalFiles)) {
-      const filePath = (0, import_path7.join)(skillDir, relativePath);
+      const filePath = (0, import_path8.join)(skillDir, relativePath);
       if (!(0, import_fs7.existsSync)(filePath)) {
         return true;
       }
@@ -7119,11 +7228,11 @@ function scanEditorFolderForSkills(editorPath, skills, sourceType, warnLegacy =
     if (EXCLUDED_DIRS2.has(entry.name)) {
       continue;
     }
-    const fullPath = (0, import_path7.join)(editorPath, entry.name);
+    const fullPath = (0, import_path8.join)(editorPath, entry.name);
     if (entry.isDirectory()) {
-      const skillDir = (0, import_path7.join)(fullPath, SkillsPathConstants.SKILL_DIR);
-      const skillMdPath = (0, import_path7.join)(skillDir, SkillsPathConstants.SKILL_FILE);
-      const legacySkillMdPath = (0, import_path7.join)(fullPath, SkillsPathConstants.SKILL_FILE);
+      const skillDir = (0, import_path8.join)(fullPath, SkillsPathConstants.SKILL_DIR);
+      const skillMdPath = (0, import_path8.join)(skillDir, SkillsPathConstants.SKILL_FILE);
+      const legacySkillMdPath = (0, import_path8.join)(fullPath, SkillsPathConstants.SKILL_FILE);
       if (warnLegacy && !(0, import_fs7.existsSync)(skillMdPath) && (0, import_fs7.existsSync)(legacySkillMdPath)) {
         warnLegacySkillStructure(fullPath, legacySkillMdPath);
       }
@@ -7161,7 +7270,7 @@ function findEditorFolders(basePath, maxDepth = 2) {
       if (!entry.isDirectory() || EXCLUDED_DIRS2.has(entry.name)) {
         continue;
       }
-      const fullPath = (0, import_path7.join)(currentPath, entry.name);
+      const fullPath = (0, import_path8.join)(currentPath, entry.name);
       if (entry.name === "Editor") {
         editorFolders.push(fullPath);
       } else {
@@ -7180,9 +7289,9 @@ function collectProjectSkills(excludedRoots = []) {
   const skills = [];
   const seenNames = /* @__PURE__ */ new Set();
   const searchPaths = [
-    (0, import_path7.join)(projectRoot, SkillsPathConstants.ASSETS_DIR),
-    (0, import_path7.join)(projectRoot, SkillsPathConstants.PACKAGES_DIR),
-    (0, import_path7.join)(projectRoot, SkillsPathConstants.LIBRARY_DIR, SkillsPathConstants.PACKAGE_CACHE_DIR)
+    (0, import_path8.join)(projectRoot, SkillsPathConstants.ASSETS_DIR),
+    (0, import_path8.join)(projectRoot, SkillsPathConstants.PACKAGES_DIR),
+    (0, import_path8.join)(projectRoot, SkillsPathConstants.LIBRARY_DIR, SkillsPathConstants.PACKAGE_CACHE_DIR)
   ];
   for (const searchPath of searchPaths) {
     if (!(0, import_fs7.existsSync)(searchPath)) {
@@ -7216,22 +7325,22 @@ function getAllSkillStatuses(target, global) {
 }
 function installSkill(skill, target, global) {
   const baseDir = global ? getGlobalSkillsDir(target) : getProjectSkillsDir(target);
-  const skillDir = (0, import_path7.join)(baseDir, skill.dirName);
-  const skillPath = (0, import_path7.join)(skillDir, target.skillFileName);
+  const skillDir = (0, import_path8.join)(baseDir, skill.dirName);
+  const skillPath = (0, import_path8.join)(skillDir, target.skillFileName);
   (0, import_fs7.mkdirSync)(skillDir, { recursive: true });
   (0, import_fs7.writeFileSync)(skillPath, skill.content, "utf-8");
   if ("additionalFiles" in skill && skill.additionalFiles) {
     const additionalFiles = skill.additionalFiles;
     for (const [relativePath, content] of Object.entries(additionalFiles)) {
-      const fullPath = (0, import_path7.join)(skillDir, relativePath);
-      (0, import_fs7.mkdirSync)((0, import_path7.dirname)(fullPath), { recursive: true });
+      const fullPath = (0, import_path8.join)(skillDir, relativePath);
+      (0, import_fs7.mkdirSync)((0, import_path8.dirname)(fullPath), { recursive: true });
       (0, import_fs7.writeFileSync)(fullPath, content);
     }
   }
 }
 function uninstallSkill(skill, target, global) {
   const baseDir = global ? getGlobalSkillsDir(target) : getProjectSkillsDir(target);
-  const skillDir = (0, import_path7.join)(baseDir, skill.dirName);
+  const skillDir = (0, import_path8.join)(baseDir, skill.dirName);
   if (!(0, import_fs7.existsSync)(skillDir)) {
     return false;
   }
@@ -7249,7 +7358,7 @@ function installAllSkills(target, global) {
   };
   const baseDir = global ? getGlobalSkillsDir(target) : getProjectSkillsDir(target);
   for (const deprecatedName of DEPRECATED_SKILLS) {
-    const deprecatedDir = (0, import_path7.join)(baseDir, deprecatedName);
+    const deprecatedDir = (0, import_path8.join)(baseDir, deprecatedName);
     if ((0, import_fs7.existsSync)(deprecatedDir)) {
       (0, import_fs7.rmSync)(deprecatedDir, { recursive: true, force: true });
       result.deprecatedRemoved++;
@@ -7293,7 +7402,7 @@ function uninstallAllSkills(target, global) {
   const result = { removed: 0, notFound: 0 };
   const baseDir = global ? getGlobalSkillsDir(target) : getProjectSkillsDir(target);
   for (const deprecatedName of DEPRECATED_SKILLS) {
-    const deprecatedDir = (0, import_path7.join)(baseDir, deprecatedName);
+    const deprecatedDir = (0, import_path8.join)(baseDir, deprecatedName);
     if ((0, import_fs7.existsSync)(deprecatedDir)) {
       (0, import_fs7.rmSync)(deprecatedDir, { recursive: true, force: true });
       result.removed++;
@@ -7324,7 +7433,7 @@ function collectAllSkills() {
   return dedupeSkillsByName([packageSkills, cliOnlySkills, projectSkills]);
 }
 function collectPackageSkillsFromRoot(packageRoot) {
-  const mcpToolsRoot = (0, import_path7.join)(
+  const mcpToolsRoot = (0, import_path8.join)(
     packageRoot,
     SkillsPathConstants.EDITOR_DIR,
     SkillsPathConstants.API_DIR,
@@ -7338,7 +7447,7 @@ function collectPackageSkillsFromRoot(packageRoot) {
   return skills;
 }
 function collectCliOnlySkills() {
-  const cliOnlyRoot = (0, import_path7.resolve)(
+  const cliOnlyRoot = (0, import_path8.resolve)(
     __dirname,
     SkillsPathConstants.DIST_PARENT_DIR,
     SkillsPathConstants.SRC_DIR,
@@ -7370,7 +7479,7 @@ function collectSkillFolderFilesRecursive(baseDir, currentDir, additionalFiles)
     if (isExcludedFile(entry.name)) {
       continue;
     }
-    const fullPath = (0, import_path7.join)(currentDir, entry.name);
+    const fullPath = (0, import_path8.join)(currentDir, entry.name);
     const relativePath = fullPath.slice(baseDir.length + 1);
     if (entry.isDirectory()) {
       if (EXCLUDED_DIRS2.has(entry.name)) {
@@ -7409,13 +7518,13 @@ function dedupeSkillsByName(skillGroups) {
 }
 function resolvePackageRoot(projectRoot) {
   const candidates = [];
-  candidates.push((0, import_path7.join)(projectRoot, SkillsPathConstants.PACKAGES_DIR, SkillsPathConstants.SRC_DIR));
+  candidates.push((0, import_path8.join)(projectRoot, SkillsPathConstants.PACKAGES_DIR, SkillsPathConstants.SRC_DIR));
   const manifestPaths = resolveManifestPackagePaths(projectRoot);
   for (const manifestPath of manifestPaths) {
     candidates.push(manifestPath);
   }
   for (const packageName of SkillsPathConstants.PACKAGE_NAMES) {
-    candidates.push((0, import_path7.join)(projectRoot, SkillsPathConstants.PACKAGES_DIR, packageName));
+    candidates.push((0, import_path8.join)(projectRoot, SkillsPathConstants.PACKAGES_DIR, packageName));
   }
   const directRoot = resolveFirstPackageRoot(candidates);
   if (directRoot) {
@@ -7424,7 +7533,7 @@ function resolvePackageRoot(projectRoot) {
   return resolvePackageCacheRoot(projectRoot);
 }
 function resolveManifestPackagePaths(projectRoot) {
-  const manifestPath = (0, import_path7.join)(
+  const manifestPath = (0, import_path8.join)(
     projectRoot,
     SkillsPathConstants.PACKAGES_DIR,
     SkillsPathConstants.MANIFEST_FILE
@@ -7476,10 +7585,10 @@ function resolveDependencyPath(rawPath, projectRoot) {
   if (normalizedPath.startsWith("//")) {
     normalizedPath = normalizedPath.slice(2);
   }
-  if ((0, import_path7.isAbsolute)(normalizedPath)) {
+  if ((0, import_path8.isAbsolute)(normalizedPath)) {
     return normalizedPath;
   }
-  return (0, import_path7.resolve)(projectRoot, normalizedPath);
+  return (0, import_path8.resolve)(projectRoot, normalizedPath);
 }
 function resolveFirstPackageRoot(candidates) {
   for (const candidate of candidates) {
@@ -7491,7 +7600,7 @@ function resolveFirstPackageRoot(candidates) {
   return null;
 }
 function resolvePackageCacheRoot(projectRoot) {
-  const packageCacheDir = (0, import_path7.join)(
+  const packageCacheDir = (0, import_path8.join)(
     projectRoot,
     SkillsPathConstants.LIBRARY_DIR,
     SkillsPathConstants.PACKAGE_CACHE_DIR
@@ -7507,7 +7616,7 @@ function resolvePackageCacheRoot(projectRoot) {
     if (!isTargetPackageCacheDir(entry.name)) {
       continue;
     }
-    const candidate = (0, import_path7.join)(packageCacheDir, entry.name);
+    const candidate = (0, import_path8.join)(packageCacheDir, entry.name);
     const resolvedRoot = resolvePackageRootCandidate(candidate);
     if (resolvedRoot) {
       return resolvedRoot;
@@ -7519,7 +7628,7 @@ function resolvePackageRootCandidate(candidate) {
   if (!(0, import_fs7.existsSync)(candidate)) {
     return null;
   }
-  const directToolsPath = (0, import_path7.join)(
+  const directToolsPath = (0, import_path8.join)(
     candidate,
     SkillsPathConstants.EDITOR_DIR,
     SkillsPathConstants.API_DIR,
@@ -7528,8 +7637,8 @@ function resolvePackageRootCandidate(candidate) {
   if ((0, import_fs7.existsSync)(directToolsPath)) {
     return candidate;
   }
-  const nestedRoot = (0, import_path7.join)(candidate, SkillsPathConstants.PACKAGES_DIR, SkillsPathConstants.SRC_DIR);
-  const nestedToolsPath = (0, import_path7.join)(
+  const nestedRoot = (0, import_path8.join)(candidate, SkillsPathConstants.PACKAGES_DIR, SkillsPathConstants.SRC_DIR);
+  const nestedToolsPath = (0, import_path8.join)(
     nestedRoot,
     SkillsPathConstants.EDITOR_DIR,
     SkillsPathConstants.API_DIR,
@@ -7561,12 +7670,12 @@ function isUnderExcludedRoots(targetPath, excludedRoots) {
   return false;
 }
 function isPathUnder(childPath, parentPath) {
-  const resolvedChild = (0, import_path7.resolve)(childPath);
-  const resolvedParent = (0, import_path7.resolve)(parentPath);
+  const resolvedChild = (0, import_path8.resolve)(childPath);
+  const resolvedParent = (0, import_path8.resolve)(parentPath);
   if (resolvedChild === resolvedParent) {
     return true;
   }
-  return resolvedChild.startsWith(resolvedParent + import_path7.sep);
+  return resolvedChild.startsWith(resolvedParent + import_path8.sep);
 }
 
 // src/skills/target-config.ts
@@ -7751,20 +7860,20 @@ Uninstalling uloop skills (${location})...`);
 }
 
 // src/commands/launch.ts
-var import_path8 = require("path");
+var import_path9 = require("path");
 
 // node_modules/launch-unity/dist/lib.js
 var import_node_child_process = require("node:child_process");
 var import_node_fs2 = require("node:fs");
-var import_promises3 = require("node:fs/promises");
+var import_promises4 = require("node:fs/promises");
 var import_node_path2 = require("node:path");
 var import_node_util = require("node:util");
 
 // node_modules/launch-unity/dist/unityHub.js
-var import_promises2 = require("node:fs/promises");
+var import_promises3 = require("node:fs/promises");
 var import_node_fs = require("node:fs");
 var import_node_path = require("node:path");
-var import_node_assert2 = __toESM(require("node:assert"), 1);
+var import_node_assert3 = __toESM(require("node:assert"), 1);
 var resolveUnityHubProjectFiles = () => {
   if (process.platform === "darwin") {
     const home = process.env.HOME;
@@ -7791,7 +7900,7 @@ var removeTrailingSeparators = (target) => {
   }
   return trimmed;
 };
-var normalizePath = (target) => {
+var normalizePath2 = (target) => {
   const resolvedPath = (0, import_node_path.resolve)(target);
   return removeTrailingSeparators(resolvedPath);
 };
@@ -7799,14 +7908,14 @@ var resolvePathWithActualCase = (target) => {
   try {
     return removeTrailingSeparators(import_node_fs.realpathSync.native(target));
   } catch {
-    return normalizePath(target);
+    return normalizePath2(target);
   }
 };
 var toComparablePath = (value) => {
   return value.replace(/\\/g, "/").toLocaleLowerCase();
 };
 var pathsEqual = (left, right) => {
-  return toComparablePath(normalizePath(left)) === toComparablePath(normalizePath(right));
+  return toComparablePath(normalizePath2(left)) === toComparablePath(normalizePath2(right));
 };
 var safeParseProjectsJson = (content) => {
   try {
@@ -7831,7 +7940,7 @@ var ensureProjectEntryAndUpdate = async (projectPath, version, when, setFavorite
   }
   for (const path of candidates) {
     logDebug(`Trying Unity Hub file: ${path}`);
-    const content = await (0, import_promises2.readFile)(path, "utf8").catch(() => void 0);
+    const content = await (0, import_promises3.readFile)(path, "utf8").catch(() => void 0);
     if (!content) {
       logDebug("Read failed or empty content, skipping.");
       continue;
@@ -7866,7 +7975,7 @@ var ensureProjectEntryAndUpdate = async (projectPath, version, when, setFavorite
       }
     };
     try {
-      await (0, import_promises2.writeFile)(path, JSON.stringify(updatedJson, void 0, 2), "utf8");
+      await (0, import_promises3.writeFile)(path, JSON.stringify(updatedJson, void 0, 2), "utf8");
       logDebug("Write succeeded.");
     } catch (error) {
       logDebug(`Write failed: ${error instanceof Error ? error.message : String(error)}`);
@@ -7883,7 +7992,7 @@ var updateLastModifiedIfExists = async (projectPath, when) => {
     let content;
     let json;
     try {
-      content = await (0, import_promises2.readFile)(path, "utf8");
+      content = await (0, import_promises3.readFile)(path, "utf8");
     } catch {
       continue;
     }
@@ -7911,7 +8020,7 @@ var updateLastModifiedIfExists = async (projectPath, when) => {
       lastModified: when.getTime()
     };
     try {
-      await (0, import_promises2.writeFile)(path, JSON.stringify(json, void 0, 2), "utf8");
+      await (0, import_promises3.writeFile)(path, JSON.stringify(json, void 0, 2), "utf8");
     } catch {
     }
     return;
@@ -7935,7 +8044,7 @@ var resolveUnityHubProjectsInfoFile = () => {
   return void 0;
 };
 var parseCliArgs = (cliArgsString) => {
-  (0, import_node_assert2.default)(cliArgsString !== null && cliArgsString !== void 0, "cliArgsString must not be null");
+  (0, import_node_assert3.default)(cliArgsString !== null && cliArgsString !== void 0, "cliArgsString must not be null");
   const trimmed = cliArgsString.trim();
   if (trimmed.length === 0) {
     return [];
@@ -7991,7 +8100,7 @@ var groupCliArgs = (args) => {
   return groups;
 };
 var getProjectCliArgs = async (projectPath) => {
-  (0, import_node_assert2.default)(projectPath !== null && projectPath !== void 0, "projectPath must not be null");
+  (0, import_node_assert3.default)(projectPath !== null && projectPath !== void 0, "projectPath must not be null");
   const infoFilePath = resolveUnityHubProjectsInfoFile();
   if (!infoFilePath) {
     logDebug("projectsInfo.json path could not be resolved.");
@@ -8000,7 +8109,7 @@ var getProjectCliArgs = async (projectPath) => {
   logDebug(`Reading projectsInfo.json: ${infoFilePath}`);
   let content;
   try {
-    content = await (0, import_promises2.readFile)(infoFilePath, "utf8");
+    content = await (0, import_promises3.readFile)(infoFilePath, "utf8");
   } catch {
     logDebug("projectsInfo.json not found or not readable.");
     return [];
@@ -8012,7 +8121,7 @@ var getProjectCliArgs = async (projectPath) => {
     logDebug("projectsInfo.json parse failed.");
     return [];
   }
-  const normalizedProjectPath = normalizePath(projectPath);
+  const normalizedProjectPath = normalizePath2(projectPath);
   const projectKey = Object.keys(json).find((key) => pathsEqual(key, normalizedProjectPath));
   if (!projectKey) {
     logDebug(`No entry found for project: ${normalizedProjectPath}`);
@@ -8091,7 +8200,7 @@ var removeTrailingSeparators2 = (target) => {
   }
   return trimmed;
 };
-var normalizePath2 = (target) => {
+var normalizePath3 = (target) => {
   const resolvedPath = (0, import_node_path2.resolve)(target);
   const trimmed = removeTrailingSeparators2(resolvedPath);
   return trimmed;
@@ -8100,7 +8209,7 @@ var toComparablePath2 = (value) => {
   return value.replace(/\\/g, "/").toLocaleLowerCase();
 };
 var pathsEqual2 = (left, right) => {
-  return toComparablePath2(normalizePath2(left)) === toComparablePath2(normalizePath2(right));
+  return toComparablePath2(normalizePath3(left)) === toComparablePath2(normalizePath3(right));
 };
 function extractProjectPath(command) {
   const match = command.match(PROJECT_PATH_PATTERN);
@@ -8161,7 +8270,7 @@ async function listUnityProcessesMac() {
     }
     processes.push({
       pid: pidValue,
-      projectPath: normalizePath2(projectArgument)
+      projectPath: normalizePath3(projectArgument)
     });
   }
   return processes;
@@ -8209,7 +8318,7 @@ async function listUnityProcessesWindows() {
     }
     processes.push({
       pid: pidValue,
-      projectPath: normalizePath2(projectArgument)
+      projectPath: normalizePath3(projectArgument)
     });
   }
   return processes;
@@ -8224,7 +8333,7 @@ async function listUnityProcesses() {
   return [];
 }
 async function findRunningUnityProcess(projectPath) {
-  const normalizedTarget = normalizePath2(projectPath);
+  const normalizedTarget = normalizePath3(projectPath);
   const processes = await listUnityProcesses();
   return processes.find((candidate) => pathsEqual2(candidate.projectPath, normalizedTarget));
 }
@@ -8325,14 +8434,14 @@ async function handleStaleLockfile(projectPath) {
   console.log(`UnityLockfile found without active Unity process: ${lockfilePath}`);
   console.log("Assuming previous crash. Cleaning Temp directory and continuing launch.");
   try {
-    await (0, import_promises3.rm)(tempDirectoryPath, { recursive: true, force: true });
+    await (0, import_promises4.rm)(tempDirectoryPath, { recursive: true, force: true });
     console.log("Deleted Temp directory.");
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     console.warn(`Failed to delete Temp directory: ${message}`);
   }
   try {
-    await (0, import_promises3.rm)(lockfilePath, { force: true });
+    await (0, import_promises4.rm)(lockfilePath, { force: true });
     console.log("Deleted UnityLockfile.");
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -8347,7 +8456,7 @@ async function deleteRecoveryDirectory(projectPath) {
   }
   console.log(`Deleting recovery directory: ${recoveryPath}`);
   try {
-    await (0, import_promises3.rm)(recoveryPath, { recursive: true, force: true });
+    await (0, import_promises4.rm)(recoveryPath, { recursive: true, force: true });
     console.log("Deleted recovery directory.");
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -8502,7 +8611,7 @@ function findUnityProjectBfs(rootDir, maxDepth) {
     rootCanonical = rootDir;
   }
   queue.push({ dir: rootCanonical, depth: 0 });
-  const visited = /* @__PURE__ */ new Set([toComparablePath2(normalizePath2(rootCanonical))]);
+  const visited = /* @__PURE__ */ new Set([toComparablePath2(normalizePath3(rootCanonical))]);
   while (queue.length > 0) {
     const current = queue.shift();
     if (!current) {
@@ -8510,7 +8619,7 @@ function findUnityProjectBfs(rootDir, maxDepth) {
     }
     const { dir, depth } = current;
     if (isUnityProjectRoot(dir)) {
-      return normalizePath2(dir);
+      return normalizePath3(dir);
     }
     const canDescend = maxDepth === -1 || depth < maxDepth;
     if (!canDescend) {
@@ -8531,7 +8640,7 @@ function findUnityProjectBfs(rootDir, maxDepth) {
       } catch {
         continue;
       }
-      const key = toComparablePath2(normalizePath2(childCanonical));
+      const key = toComparablePath2(normalizePath3(childCanonical));
       if (visited.has(key)) {
         continue;
       }
@@ -8689,7 +8798,7 @@ function parseMaxDepth(value) {
 async function runLaunchCommand(projectPath, options) {
   const maxDepth = parseMaxDepth(options.maxDepth);
   await orchestrateLaunch({
-    projectPath: projectPath ? (0, import_path8.resolve)(projectPath) : void 0,
+    projectPath: projectPath ? (0, import_path9.resolve)(projectPath) : void 0,
     searchRoot: process.cwd(),
     searchMaxDepth: maxDepth,
     platform: options.platform,
@@ -8703,8 +8812,12 @@ async function runLaunchCommand(projectPath, options) {
 }
 
 // src/commands/focus-window.ts
-function registerFocusWindowCommand(program3) {
-  program3.command("focus-window").description("Bring Unity Editor window to front using OS-level commands").option("--project-path <path>", "Unity project path").action(async (options) => {
+function registerFocusWindowCommand(program3, helpGroup) {
+  const cmd = program3.command("focus-window").description("Bring Unity Editor window to front using OS-level commands").option("--project-path <path>", "Unity project path");
+  if (helpGroup !== void 0) {
+    cmd.helpGroup(helpGroup);
+  }
+  cmd.action(async (options) => {
     let projectRoot;
     if (options.projectPath !== void 0) {
       try {
@@ -8765,6 +8878,14 @@ function registerFocusWindowCommand(program3) {
 var FOCUS_WINDOW_COMMAND = "focus-window";
 var LAUNCH_COMMAND = "launch";
 var UPDATE_COMMAND = "update";
+var HELP_GROUP_BUILTIN_TOOLS = "Built-in Tools:";
+var HELP_GROUP_THIRD_PARTY_TOOLS = "Third-party Tools:";
+var HELP_GROUP_CLI_COMMANDS = "CLI Commands:";
+var HELP_GROUP_ORDER = [
+  HELP_GROUP_CLI_COMMANDS,
+  HELP_GROUP_BUILTIN_TOOLS,
+  HELP_GROUP_THIRD_PARTY_TOOLS
+];
 var NO_SYNC_FLAGS = ["-v", "--version", "-h", "--help"];
 var BUILTIN_COMMANDS = [
   "list",
@@ -8777,9 +8898,44 @@ var BUILTIN_COMMANDS = [
   FOCUS_WINDOW_COMMAND
 ];
 var program2 = new Command();
-program2.name("uloop").description("Unity MCP CLI - Direct communication with Unity Editor").version(VERSION, "-v, --version", "Output the version number").showHelpAfterError("(run with -h for available options)").configureHelp({ sortSubcommands: true });
+program2.name("uloop").description("Unity MCP CLI - Direct communication with Unity Editor").version(VERSION, "-v, --version", "Output the version number").showHelpAfterError("(run with -h for available options)").configureHelp({
+  sortSubcommands: true,
+  // commander.js default groupItems determines group display order by registration order,
+  // but CLI commands are registered at module level (before tools), so the default order
+  // would be wrong. We re-implement to enforce HELP_GROUP_ORDER.
+  groupItems(unsortedItems, visibleItems, getGroup) {
+    const groupMap = /* @__PURE__ */ new Map();
+    for (const item of unsortedItems) {
+      const group = getGroup(item);
+      if (!groupMap.has(group)) {
+        groupMap.set(group, []);
+      }
+    }
+    for (const item of visibleItems) {
+      const group = getGroup(item);
+      if (!groupMap.has(group)) {
+        groupMap.set(group, []);
+      }
+      groupMap.get(group).push(item);
+    }
+    const ordered = /* @__PURE__ */ new Map();
+    for (const key of HELP_GROUP_ORDER) {
+      const items = groupMap.get(key);
+      if (items !== void 0) {
+        ordered.set(key, items);
+        groupMap.delete(key);
+      }
+    }
+    for (const [key, value] of groupMap) {
+      ordered.set(key, value);
+    }
+    return ordered;
+  }
+});
 program2.option("--list-commands", "List all command names (for shell completion)");
 program2.option("--list-options <cmd>", "List options for a command (for shell completion)");
+program2.commandsGroup(HELP_GROUP_CLI_COMMANDS);
+program2.helpCommand(true);
 program2.command("list").description("List all available tools from Unity").option("-p, --port <port>", "Unity TCP port").option("--project-path <path>", "Unity project path").action(async (options) => {
   await runWithErrorHandling(() => listAvailableTools(extractGlobalOptions(options)));
 });
@@ -8800,11 +8956,12 @@ program2.command("fix").description("Clean up stale lock files that may prevent
 });
 registerSkillsCommand(program2);
 registerLaunchCommand(program2);
-function registerToolCommand(tool) {
+function registerToolCommand(tool, helpGroup) {
   if (BUILTIN_COMMANDS.includes(tool.name)) {
     return;
   }
-  const cmd = program2.command(tool.name).description(tool.description);
+  const firstLine = tool.description.split("\n")[0];
+  const cmd = program2.command(tool.name).description(firstLine).helpGroup(helpGroup);
   const properties = tool.inputSchema.properties;
   for (const [propName, propInfo] of Object.entries(properties)) {
     const optionStr = generateOptionString(propName, propInfo);
@@ -8923,6 +9080,9 @@ function convertValue(value, propInfo) {
   }
   return value;
 }
+function getToolHelpGroup(toolName, defaultToolNames) {
+  return defaultToolNames.has(toolName) ? HELP_GROUP_BUILTIN_TOOLS : HELP_GROUP_THIRD_PARTY_TOOLS;
+}
 function extractGlobalOptions(options) {
   return {
     port: options["port"],
@@ -8970,6 +9130,26 @@ async function runWithErrorHandling(fn) {
   try {
     await fn();
   } catch (error) {
+    if (error instanceof UnityNotRunningError) {
+      console.error("\x1B[31mError: Unity Editor for this project is not running.\x1B[0m");
+      console.error("");
+      console.error(`  Project: ${error.projectRoot}`);
+      console.error("");
+      console.error("Start the Unity Editor for this project and try again.");
+      process.exit(1);
+    }
+    if (error instanceof ProjectMismatchError) {
+      console.error("\x1B[31mError: Unity Editor for this project is not running.\x1B[0m");
+      console.error("");
+      console.error(`  Project:      ${error.expectedProjectRoot}`);
+      console.error(`  Connected to: ${error.connectedProjectRoot}`);
+      console.error("");
+      console.error("Another Unity instance was found, but it belongs to a different project.");
+      console.error(
+        "Start the Unity Editor for this project, or use --port to specify the target."
+      );
+      process.exit(1);
+    }
     const message = error instanceof Error ? error.message : String(error);
     if (message === "UNITY_COMPILING") {
       console.error("\x1B[33m\u23F3 Unity is compiling scripts.\x1B[0m");
@@ -9014,7 +9194,7 @@ async function runWithErrorHandling(fn) {
 }
 function detectShell() {
   const shell = process.env["SHELL"] || "";
-  const shellName = (0, import_path9.basename)(shell).replace(/\.exe$/i, "");
+  const shellName = (0, import_path10.basename)(shell).replace(/\.exe$/i, "");
   if (shellName === "zsh") {
     return "zsh";
   }
@@ -9029,12 +9209,12 @@ function detectShell() {
 function getShellConfigPath(shell) {
   const home = (0, import_os2.homedir)();
   if (shell === "zsh") {
-    return (0, import_path9.join)(home, ".zshrc");
+    return (0, import_path10.join)(home, ".zshrc");
   }
   if (shell === "powershell") {
-    return (0, import_path9.join)(home, "Documents", "WindowsPowerShell", "Microsoft.PowerShell_profile.ps1");
+    return (0, import_path10.join)(home, "Documents", "WindowsPowerShell", "Microsoft.PowerShell_profile.ps1");
   }
-  return (0, import_path9.join)(home, ".bashrc");
+  return (0, import_path10.join)(home, ".bashrc");
 }
 function getCompletionScript(shell) {
   if (shell === "bash") {
@@ -9171,10 +9351,10 @@ function cleanupLockFiles(projectPath) {
     console.error("Could not find Unity project root.");
     process.exit(1);
   }
-  const tempDir = (0, import_path9.join)(projectRoot, "Temp");
+  const tempDir = (0, import_path10.join)(projectRoot, "Temp");
   let cleaned = 0;
   for (const lockFile of LOCK_FILES) {
-    const lockPath = (0, import_path9.join)(tempDir, lockFile);
+    const lockPath = (0, import_path10.join)(tempDir, lockFile);
     if ((0, import_fs8.existsSync)(lockPath)) {
       (0, import_fs8.unlinkSync)(lockPath);
       console.log(`Removed: ${lockFile}`);
@@ -9211,7 +9391,7 @@ function handleCompletion(install, shellOverride) {
     return;
   }
   const configPath = getShellConfigPath(shell);
-  const configDir = (0, import_path9.dirname)(configPath);
+  const configDir = (0, import_path10.dirname)(configPath);
   if (!(0, import_fs8.existsSync)(configDir)) {
     (0, import_fs8.mkdirSync)(configDir, { recursive: true });
   }
@@ -9305,6 +9485,20 @@ function shouldSkipAutoSync(cmdName, args) {
   }
   return args.some((arg) => NO_SYNC_FLAGS.includes(arg));
 }
+var OPTIONS_WITH_VALUE = /* @__PURE__ */ new Set(["--port", "-p", "--project-path"]);
+function findCommandName(args) {
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith("-")) {
+      if (OPTIONS_WITH_VALUE.has(arg)) {
+        i++;
+      }
+      continue;
+    }
+    return arg;
+  }
+  return void 0;
+}
 function extractSyncGlobalOptions(args) {
   const options = {};
   for (let i = 0; i < args.length; i++) {
@@ -9339,20 +9533,21 @@ async function main() {
     return;
   }
   const args = process.argv.slice(2);
-  const cmdName = args.find((arg) => !arg.startsWith("-"));
   const syncGlobalOptions = extractSyncGlobalOptions(args);
+  const cmdName = findCommandName(args);
   const NO_PROJECT_COMMANDS = [UPDATE_COMMAND, "completion"];
   const skipProjectDetection = cmdName === void 0 || NO_PROJECT_COMMANDS.includes(cmdName);
   if (skipProjectDetection) {
-    const defaultTools = getDefaultTools();
+    const defaultToolNames2 = getDefaultToolNames();
     const isTopLevelHelp = cmdName === void 0 && (args.includes("-h") || args.includes("--help"));
     const shouldFilter = syncGlobalOptions.projectPath !== void 0 || isTopLevelHelp;
-    const tools = shouldFilter ? filterEnabledTools(defaultTools.tools, syncGlobalOptions.projectPath) : defaultTools.tools;
+    const sourceTools = shouldFilter ? loadToolsCache(syncGlobalOptions.projectPath).tools : getDefaultTools().tools;
+    const tools = shouldFilter ? filterEnabledTools(sourceTools, syncGlobalOptions.projectPath) : sourceTools;
     if (!shouldFilter || isToolEnabled(FOCUS_WINDOW_COMMAND, syncGlobalOptions.projectPath)) {
-      registerFocusWindowCommand(program2);
+      registerFocusWindowCommand(program2, HELP_GROUP_BUILTIN_TOOLS);
     }
     for (const tool of tools) {
-      registerToolCommand(tool);
+      registerToolCommand(tool, getToolHelpGroup(tool.name, defaultToolNames2));
     }
     program2.parse();
     return;
@@ -9381,11 +9576,12 @@ async function main() {
   }
   const toolsCache = loadToolsCache();
   const projectPath = syncGlobalOptions.projectPath;
+  const defaultToolNames = getDefaultToolNames();
   if (isToolEnabled(FOCUS_WINDOW_COMMAND, projectPath)) {
-    registerFocusWindowCommand(program2);
+    registerFocusWindowCommand(program2, HELP_GROUP_BUILTIN_TOOLS);
   }
   for (const tool of filterEnabledTools(toolsCache.tools, projectPath)) {
-    registerToolCommand(tool);
+    registerToolCommand(tool, getToolHelpGroup(tool.name, defaultToolNames));
   }
   if (cmdName && !commandExists(cmdName, projectPath)) {
     if (!isToolEnabled(cmdName, projectPath)) {
@@ -9398,7 +9594,7 @@ async function main() {
       const newCache = loadToolsCache();
       const tool = filterEnabledTools(newCache.tools, projectPath).find((t) => t.name === cmdName);
       if (tool) {
-        registerToolCommand(tool);
+        registerToolCommand(tool, getToolHelpGroup(tool.name, defaultToolNames));
         console.log(`\x1B[32m\u2713 Found '${cmdName}' after sync.\x1B[0m
 `);
       } else {