@muggleai/works 4.0.1 → 4.1.0

package/README.md

@@ -375,8 +375,8 @@ Data directory structure (~/.muggle-ai/)
 
 ```
 ~/.muggle-ai/
-├── auth.json             # OAuth tokens
-├── credentials.json      # API key for service calls
+├── oauth-session.json    # OAuth tokens (short-lived, auto-refresh)
+├── api-key.json          # Long-lived API key for service calls
 ├── projects/             # Local project cache
 ├── sessions/             # QA sessions
 │   └── {runId}/
@@ -424,7 +424,7 @@ muggle doctor           # Diagnose
 
 ```bash
 muggle logout           # Clear all credentials
-rm ~/.muggle-ai/auth.json ~/.muggle-ai/credentials.json
+rm ~/.muggle-ai/oauth-session.json ~/.muggle-ai/api-key.json
 muggle login            # Fresh login
 ```
 

package/dist/{chunk-AJKZXT7B.js → chunk-PV76IWEX.js}

@@ -1,5 +1,5 @@
 import * as fs3 from 'fs';
-import { readFileSync, existsSync, rmSync, mkdirSync, createWriteStream, readdirSync, statSync, writeFileSync } from 'fs';
+import { readFileSync, existsSync, rmSync, mkdirSync, readdirSync, createWriteStream, writeFileSync, statSync } from 'fs';
 import * as os3 from 'os';
 import { platform, arch, homedir } from 'os';
 import * as path2 from 'path';
@@ -7,7 +7,7 @@ import { dirname, resolve, join } from 'path';
 import { fileURLToPath } from 'url';
 import winston from 'winston';
 import axios, { AxiosError } from 'axios';
-import { spawn, exec } from 'child_process';
+import { spawn, exec, execFile } from 'child_process';
 import * as fs5 from 'fs/promises';
 import { z, ZodError } from 'zod';
 import * as crypto from 'crypto';
@@ -39,12 +39,12 @@ var DEFAULT_PROMPT_SERVICE_PRODUCTION_URL = "https://promptservice.muggle-ai.com
 var DEFAULT_PROMPT_SERVICE_DEV_URL = "http://localhost:5050";
 var DEFAULT_WEB_SERVICE_URL = "http://localhost:3001";
 var ELECTRON_APP_DIR = "electron-app";
-var CREDENTIALS_FILE = "credentials.json";
+var API_KEY_FILE = "api-key.json";
 var DEFAULT_AUTH0_PRODUCTION_DOMAIN = "login.muggle-ai.com";
 var DEFAULT_AUTH0_PRODUCTION_CLIENT_ID = "UgG5UjoyLksxMciWWKqVpwfWrJ4rFvtT";
 var DEFAULT_AUTH0_PRODUCTION_AUDIENCE = "https://muggleai.us.auth0.com/api/v2/";
 var DEFAULT_AUTH0_DEV_DOMAIN = "dev-po4mxmz0rd8a0w8w.us.auth0.com";
-var DEFAULT_AUTH0_DEV_CLIENT_ID = "hihMM2cxb40yHaZMH2MMXwO2ZRJQ3MxA";
+var DEFAULT_AUTH0_DEV_CLIENT_ID = "GBvkMdTbCI80XJXnJ90MmbEvXwcWGUtw";
 var DEFAULT_AUTH0_DEV_AUDIENCE = "https://dev-po4mxmz0rd8a0w8w.us.auth0.com/api/v2/";
 var DEFAULT_AUTH0_SCOPE = "openid profile email offline_access";
 var configInstance = null;
@@ -130,8 +130,7 @@ function getDataDir2() {
 }
 function getDownloadedElectronAppPath() {
   const platformName = os3.platform();
-  const config = getMuggleConfig();
-  const version = config.electronAppVersion;
+  const version = getElectronAppVersion();
   const baseDir = path2.join(getDataDir2(), ELECTRON_APP_DIR, version);
   let binaryPath;
   switch (platformName) {
@@ -240,10 +239,10 @@ function getDefaultAuth0Domain() {
 }
 function getDefaultAuth0ClientId() {
   const runtimeTarget = getPromptServiceRuntimeTarget();
-  if (runtimeTarget === "dev") {
-    return DEFAULT_AUTH0_DEV_CLIENT_ID;
+  if (runtimeTarget === "production") {
+    return DEFAULT_AUTH0_PRODUCTION_CLIENT_ID;
   }
-  return DEFAULT_AUTH0_PRODUCTION_CLIENT_ID;
+  return DEFAULT_AUTH0_DEV_CLIENT_ID;
 }
 function getDefaultAuth0Audience() {
   const runtimeTarget = getPromptServiceRuntimeTarget();
@@ -285,8 +284,8 @@ function buildLocalQaConfig() {
     sessionsDir: path2.join(dataDir, "sessions"),
     projectsDir: path2.join(dataDir, "projects"),
     tempDir: path2.join(dataDir, "temp"),
-    credentialsFilePath: path2.join(dataDir, CREDENTIALS_FILE),
-    authFilePath: path2.join(dataDir, "auth.json"),
+    apiKeyFilePath: path2.join(dataDir, API_KEY_FILE),
+    oauthSessionFilePath: path2.join(dataDir, "oauth-session.json"),
     electronAppPath: resolveElectronAppPathOrNull(),
     webServicePath: resolveWebServicePath(),
     webServicePidFile: path2.join(dataDir, "web-service.pid"),
@@ -611,8 +610,8 @@ var TestResultStatus = /* @__PURE__ */ ((TestResultStatus2) => {
 // packages/mcps/src/mcp/local/services/auth-service.ts
 var DEFAULT_LOGIN_WAIT_TIMEOUT_MS = 12e4;
 var AuthService = class {
-  /** Path to the auth file. */
-  authFilePath;
+  /** Path to the OAuth session file. */
+  oauthSessionFilePath;
   /** Path to the pending device code file. */
   pendingDeviceCodePath;
   /**
@@ -620,9 +619,9 @@ var AuthService = class {
    */
   constructor() {
     const config = getConfig();
-    this.authFilePath = config.localQa.authFilePath;
+    this.oauthSessionFilePath = config.localQa.oauthSessionFilePath;
     this.pendingDeviceCodePath = path2.join(
-      path2.dirname(config.localQa.authFilePath),
+      path2.dirname(config.localQa.oauthSessionFilePath),
       "pending-device-code.json"
     );
   }
@@ -932,11 +931,11 @@ var AuthService = class {
       email,
       userId
     };
-    const dir = path2.dirname(this.authFilePath);
+    const dir = path2.dirname(this.oauthSessionFilePath);
     if (!fs3.existsSync(dir)) {
       fs3.mkdirSync(dir, { recursive: true });
     }
-    fs3.writeFileSync(this.authFilePath, JSON.stringify(storedAuth, null, 2), {
+    fs3.writeFileSync(this.oauthSessionFilePath, JSON.stringify(storedAuth, null, 2), {
       encoding: "utf-8",
       mode: 384
     });
@@ -947,11 +946,11 @@ var AuthService = class {
    */
   loadStoredAuth() {
     const logger14 = getLogger();
-    if (!fs3.existsSync(this.authFilePath)) {
+    if (!fs3.existsSync(this.oauthSessionFilePath)) {
       return null;
     }
     try {
-      const content = fs3.readFileSync(this.authFilePath, "utf-8");
+      const content = fs3.readFileSync(this.oauthSessionFilePath, "utf-8");
       return JSON.parse(content);
     } catch (error) {
       logger14.error("Failed to load stored auth", {
@@ -1035,11 +1034,11 @@ var AuthService = class {
         email: storedAuth.email,
         userId: storedAuth.userId
       };
-      const dir = path2.dirname(this.authFilePath);
+      const dir = path2.dirname(this.oauthSessionFilePath);
       if (!fs3.existsSync(dir)) {
         fs3.mkdirSync(dir, { recursive: true });
       }
-      fs3.writeFileSync(this.authFilePath, JSON.stringify(updatedAuth, null, 2), {
+      fs3.writeFileSync(this.oauthSessionFilePath, JSON.stringify(updatedAuth, null, 2), {
         encoding: "utf-8",
         mode: 384
       });
@@ -1091,12 +1090,12 @@ var AuthService = class {
    */
   logout() {
     const logger14 = getLogger();
-    if (!fs3.existsSync(this.authFilePath)) {
+    if (!fs3.existsSync(this.oauthSessionFilePath)) {
       logger14.debug("No auth to clear");
       return false;
     }
     try {
-      fs3.unlinkSync(this.authFilePath);
+      fs3.unlinkSync(this.oauthSessionFilePath);
       logger14.info("Auth cleared successfully");
       return true;
     } catch (error) {
@@ -1865,9 +1864,24 @@ function getElectronAppPathOrThrow() {
   const config = getConfig();
   const electronAppPath = config.localQa.electronAppPath;
   if (!electronAppPath || electronAppPath.trim() === "") {
-    throw new Error(
-      "Electron app binary not found. Run 'muggle setup' or set ELECTRON_APP_PATH."
-    );
+    const version = getElectronAppVersion();
+    const versionDir = getElectronAppDir(version);
+    const envPath = process.env.ELECTRON_APP_PATH;
+    const errorLines = [
+      "Electron app binary not found.",
+      "",
+      `  Expected version: ${version}`,
+      `  Checked directory: ${versionDir}`
+    ];
+    if (envPath) {
+      errorLines.push(`  ELECTRON_APP_PATH: ${envPath} (not found or invalid)`);
+    } else {
+      errorLines.push("  ELECTRON_APP_PATH: (not set)");
+    }
+    errorLines.push("");
+    errorLines.push("To fix this, run: muggle setup");
+    errorLines.push("Or set ELECTRON_APP_PATH to the path of the MuggleAI executable.");
+    throw new Error(errorLines.join("\n"));
   }
   return electronAppPath;
 }
@@ -2366,9 +2380,9 @@ function listActiveExecutions() {
     status: process2.status
   }));
 }
-var CREDENTIALS_FILE2 = "credentials.json";
-function getCredentialsFilePath() {
-  return path2.join(getDataDir(), CREDENTIALS_FILE2);
+var API_KEY_FILE2 = "api-key.json";
+function getApiKeyFilePath() {
+  return path2.join(getDataDir(), API_KEY_FILE2);
 }
 function ensureDataDir() {
   const dataDir = getDataDir();
@@ -2376,95 +2390,85 @@ function ensureDataDir() {
     fs3.mkdirSync(dataDir, { recursive: true });
   }
 }
-function loadCredentials() {
+function loadApiKeyData() {
   const logger14 = getLogger();
-  const credentialsPath = getCredentialsFilePath();
+  const apiKeyPath = getApiKeyFilePath();
   try {
-    if (!fs3.existsSync(credentialsPath)) {
-      logger14.debug("No credentials file found", { path: credentialsPath });
+    if (!fs3.existsSync(apiKeyPath)) {
+      logger14.debug("No API key file found", { path: apiKeyPath });
       return null;
     }
-    const content = fs3.readFileSync(credentialsPath, "utf-8");
-    const credentials = JSON.parse(content);
-    if (!credentials.accessToken || !credentials.expiresAt) {
-      logger14.warn("Invalid credentials file - missing required fields");
-      return null;
-    }
-    return credentials;
+    const content = fs3.readFileSync(apiKeyPath, "utf-8");
+    const data = JSON.parse(content);
+    return data;
   } catch (error) {
-    logger14.warn("Failed to load credentials", {
+    logger14.warn("Failed to load API key data", {
       error: error instanceof Error ? error.message : String(error)
     });
     return null;
   }
 }
-function saveCredentials(credentials) {
+function saveApiKeyData(data) {
   const logger14 = getLogger();
-  const credentialsPath = getCredentialsFilePath();
+  const apiKeyPath = getApiKeyFilePath();
   try {
     ensureDataDir();
-    const content = JSON.stringify(credentials, null, 2);
-    fs3.writeFileSync(credentialsPath, content, { mode: 384 });
-    logger14.info("Credentials saved", { path: credentialsPath });
+    const content = JSON.stringify(data, null, 2);
+    fs3.writeFileSync(apiKeyPath, content, { mode: 384 });
+    logger14.info("API key saved", { path: apiKeyPath });
   } catch (error) {
-    logger14.error("Failed to save credentials", {
+    logger14.error("Failed to save API key", {
       error: error instanceof Error ? error.message : String(error)
     });
     throw error;
   }
 }
-function deleteCredentials() {
+function deleteApiKeyData() {
   const logger14 = getLogger();
-  const credentialsPath = getCredentialsFilePath();
+  const apiKeyPath = getApiKeyFilePath();
   try {
-    if (fs3.existsSync(credentialsPath)) {
-      fs3.unlinkSync(credentialsPath);
-      logger14.info("Credentials deleted", { path: credentialsPath });
+    if (fs3.existsSync(apiKeyPath)) {
+      fs3.unlinkSync(apiKeyPath);
+      logger14.info("API key deleted", { path: apiKeyPath });
     }
   } catch (error) {
-    logger14.warn("Failed to delete credentials", {
+    logger14.warn("Failed to delete API key", {
       error: error instanceof Error ? error.message : String(error)
     });
   }
 }
-function isCredentialsExpired(credentials) {
-  const expiresAt = new Date(credentials.expiresAt);
-  const now = /* @__PURE__ */ new Date();
-  const bufferMs = 5 * 60 * 1e3;
-  return now.getTime() >= expiresAt.getTime() - bufferMs;
-}
-function getValidCredentials() {
-  const credentials = loadCredentials();
-  if (!credentials) {
+function getValidApiKeyData() {
+  const data = loadApiKeyData();
+  if (!data) {
     return null;
   }
-  if (credentials.apiKey) {
-    return credentials;
+  if (data.apiKey) {
+    return data;
   }
   return null;
 }
 function hasApiKey() {
-  const credentials = loadCredentials();
-  return !!credentials?.apiKey;
+  const data = loadApiKeyData();
+  return !!data?.apiKey;
 }
 function getApiKey() {
-  const credentials = loadCredentials();
-  return credentials?.apiKey ?? null;
+  const data = loadApiKeyData();
+  return data?.apiKey ?? null;
 }
 function saveApiKey(params) {
   const logger14 = getLogger();
-  const credentialsPath = getCredentialsFilePath();
+  const apiKeyPath = getApiKeyFilePath();
   try {
     ensureDataDir();
-    const credentials = {
+    const data = {
       accessToken: "",
       expiresAt: "",
       apiKey: params.apiKey,
       apiKeyId: params.apiKeyId
     };
-    const content = JSON.stringify(credentials, null, 2);
-    fs3.writeFileSync(credentialsPath, content, { mode: 384 });
-    logger14.info("API key saved", { path: credentialsPath });
+    const content = JSON.stringify(data, null, 2);
+    fs3.writeFileSync(apiKeyPath, content, { mode: 384 });
+    logger14.info("API key saved", { path: apiKeyPath });
   } catch (error) {
     logger14.error("Failed to save API key", {
       error: error instanceof Error ? error.message : String(error)
@@ -2472,6 +2476,11 @@ function saveApiKey(params) {
     throw error;
   }
 }
+var loadCredentials = loadApiKeyData;
+var saveCredentials = saveApiKeyData;
+var deleteCredentials = deleteApiKeyData;
+var getValidCredentials = getValidApiKeyData;
+var getCredentialsFilePath = getApiKeyFilePath;
 
 // packages/mcps/src/shared/auth.ts
 var logger4 = getLogger();
@@ -2680,7 +2689,7 @@ async function performLogin(keyName, keyExpiry = "90d", timeoutMs = 12e4) {
         );
         credentials.apiKey = apiKeyResult.key;
         credentials.apiKeyId = apiKeyResult.id;
-        saveCredentials(credentials);
+        saveApiKeyData(credentials);
       }
       return {
         success: true,
@@ -2717,13 +2726,13 @@ async function performLogin(keyName, keyExpiry = "90d", timeoutMs = 12e4) {
 function performLogout() {
   const authService = getAuthService();
   authService.logout();
-  deleteCredentials();
+  deleteApiKeyData();
   logger4.info("[Auth] Logged out successfully");
 }
 function getCallerCredentials() {
-  const credentials = getValidCredentials();
-  if (credentials?.apiKey) {
-    return { apiKey: credentials.apiKey };
+  const apiKeyData = getValidApiKeyData();
+  if (apiKeyData?.apiKey) {
+    return { apiKey: apiKeyData.apiKey };
   }
   const authService = getAuthService();
   const accessToken = authService.getAccessToken();
@@ -2733,9 +2742,9 @@ function getCallerCredentials() {
   return {};
 }
 async function getCallerCredentialsAsync() {
-  const credentials = getValidCredentials();
-  if (credentials?.apiKey) {
-    return { apiKey: credentials.apiKey };
+  const apiKeyData = getValidApiKeyData();
+  if (apiKeyData?.apiKey) {
+    return { apiKey: apiKeyData.apiKey };
   }
   const authService = getAuthService();
   const accessToken = await authService.getValidAccessToken();
@@ -3159,17 +3168,17 @@ var PromptServiceClient = class {
    * @param path - Path to validate.
    * @throws GatewayError if path is not allowed.
    */
-  validatePath(path13) {
-    const isAllowed = ALLOWED_UPSTREAM_PREFIXES.some((prefix) => path13.startsWith(prefix));
+  validatePath(path15) {
+    const isAllowed = ALLOWED_UPSTREAM_PREFIXES.some((prefix) => path15.startsWith(prefix));
     if (!isAllowed) {
       const logger14 = getLogger();
       logger14.error("Path not in allowlist", {
-        path: path13,
+        path: path15,
         allowedPrefixes: ALLOWED_UPSTREAM_PREFIXES
       });
       throw new GatewayError({
         code: "FORBIDDEN" /* FORBIDDEN */,
-        message: `Path '${path13}' is not allowed`
+        message: `Path '${path15}' is not allowed`
       });
     }
   }
@@ -5452,8 +5461,10 @@ __export(src_exports, {
   calculateFileChecksum: () => calculateFileChecksum,
   createApiKeyWithToken: () => createApiKeyWithToken,
   createChildLogger: () => createChildLogger,
+  deleteApiKeyData: () => deleteApiKeyData,
   deleteCredentials: () => deleteCredentials,
   getApiKey: () => getApiKey,
+  getApiKeyFilePath: () => getApiKeyFilePath,
   getAuthService: () => getAuthService,
   getBundledElectronAppVersion: () => getBundledElectronAppVersion,
   getCallerCredentials: () => getCallerCredentials,
@@ -5471,10 +5482,11 @@ __export(src_exports, {
   getLogger: () => getLogger,
   getPlatformKey: () => getPlatformKey,
   getQaTools: () => getQaTools,
+  getValidApiKeyData: () => getValidApiKeyData,
   getValidCredentials: () => getValidCredentials,
   hasApiKey: () => hasApiKey,
-  isCredentialsExpired: () => isCredentialsExpired,
   isElectronAppInstalled: () => isElectronAppInstalled,
+  loadApiKeyData: () => loadApiKeyData,
   loadCredentials: () => loadCredentials,
   localQa: () => local_exports2,
   mcp: () => mcp_exports,
@@ -5486,6 +5498,7 @@ __export(src_exports, {
   resetConfig: () => resetConfig,
   resetLogger: () => resetLogger,
   saveApiKey: () => saveApiKey,
+  saveApiKeyData: () => saveApiKeyData,
   saveCredentials: () => saveCredentials,
   startDeviceCodeFlow: () => startDeviceCodeFlow,
   toolRequiresAuth: () => toolRequiresAuth,
@@ -5796,8 +5809,8 @@ function createUnifiedMcpServer(options) {
           errors: error.issues
         });
         const issueMessages = error.issues.slice(0, 3).map((issue) => {
-          const path13 = issue.path.join(".");
-          return path13 ? `'${path13}': ${issue.message}` : issue.message;
+          const path15 = issue.path.join(".");
+          return path15 ? `'${path15}': ${issue.message}` : issue.message;
         });
         return {
           content: [
@@ -6065,6 +6078,72 @@ var logger8 = getLogger();
 function getCursorMcpConfigPath() {
   return join(homedir(), ".cursor", "mcp.json");
 }
+function getExpectedExecutablePath(versionDir) {
+  const os4 = platform();
+  switch (os4) {
+    case "darwin":
+      return path2.join(versionDir, "MuggleAI.app", "Contents", "MacOS", "MuggleAI");
+    case "win32":
+      return path2.join(versionDir, "MuggleAI.exe");
+    case "linux":
+      return path2.join(versionDir, "MuggleAI");
+    default:
+      throw new Error(`Unsupported platform: ${os4}`);
+  }
+}
+function verifyElectronAppInstallation() {
+  const version = getElectronAppVersion();
+  const versionDir = getElectronAppDir(version);
+  const executablePath = getExpectedExecutablePath(versionDir);
+  const metadataPath = path2.join(versionDir, ".install-metadata.json");
+  const result = {
+    valid: false,
+    versionDir,
+    executablePath,
+    executableExists: false,
+    executableIsFile: false,
+    metadataExists: false,
+    hasPartialArchive: false
+  };
+  if (!fs3.existsSync(versionDir)) {
+    result.errorDetail = "Version directory does not exist";
+    return result;
+  }
+  const archivePatterns = ["MuggleAI-darwin", "MuggleAI-win32", "MuggleAI-linux"];
+  try {
+    const files = fs3.readdirSync(versionDir);
+    for (const file of files) {
+      if (archivePatterns.some((pattern) => file.startsWith(pattern)) && (file.endsWith(".zip") || file.endsWith(".tar.gz"))) {
+        result.hasPartialArchive = true;
+        break;
+      }
+    }
+  } catch {
+  }
+  result.executableExists = fs3.existsSync(executablePath);
+  if (!result.executableExists) {
+    if (result.hasPartialArchive) {
+      result.errorDetail = "Download incomplete: archive found but not extracted";
+    } else {
+      result.errorDetail = "Executable not found at expected path";
+    }
+    return result;
+  }
+  try {
+    const stats = fs3.statSync(executablePath);
+    result.executableIsFile = stats.isFile();
+    if (!result.executableIsFile) {
+      result.errorDetail = "Executable path exists but is not a file";
+      return result;
+    }
+  } catch {
+    result.errorDetail = "Cannot stat executable (broken symlink?)";
+    return result;
+  }
+  result.metadataExists = fs3.existsSync(metadataPath);
+  result.valid = true;
+  return result;
+}
 function validateCursorMcpConfig() {
   const cursorMcpConfigPath = getCursorMcpConfigPath();
   if (!existsSync(cursorMcpConfigPath)) {
@@ -6140,12 +6219,13 @@ function runDiagnostics() {
     description: existsSync(dataDir) ? `Found at ${dataDir}` : `Not found at ${dataDir}`,
     suggestion: "Run 'muggle login' to create the data directory"
   });
-  const electronInstalled = isElectronAppInstalled();
   const electronVersion = getElectronAppVersion();
   const bundledVersion = getBundledElectronAppVersion();
   const versionSource = getElectronAppVersionSource();
+  const installVerification = verifyElectronAppInstallation();
   let electronDescription;
-  if (electronInstalled) {
+  let electronSuggestion;
+  if (installVerification.valid) {
     electronDescription = `Installed (v${electronVersion})`;
     switch (versionSource) {
       case "env":
@@ -6155,16 +6235,30 @@ function runDiagnostics() {
         electronDescription += ` [overridden from bundled v${bundledVersion}]`;
         break;
     }
+    if (!installVerification.metadataExists) {
+      electronDescription += " [missing metadata]";
+    }
   } else {
     electronDescription = `Not installed (expected v${electronVersion})`;
+    if (installVerification.errorDetail) {
+      electronDescription += `
+  \u2514\u2500 ${installVerification.errorDetail}`;
+      electronDescription += `
+  \u2514\u2500 Checked: ${installVerification.versionDir}`;
+    }
+    if (installVerification.hasPartialArchive) {
+      electronSuggestion = "Run 'muggle setup --force' to re-download and extract";
+    } else {
+      electronSuggestion = "Run 'muggle setup' to download the Electron app";
+    }
   }
   results.push({
     name: "Electron App",
-    passed: electronInstalled,
+    passed: installVerification.valid,
     description: electronDescription,
-    suggestion: "Run 'muggle setup' to download the Electron app"
+    suggestion: electronSuggestion
   });
-  if (electronInstalled) {
+  if (installVerification.valid) {
     results.push({
       name: "Electron App Updates",
       passed: true,
@@ -6266,8 +6360,8 @@ ${title}`, COLORS.bold + COLORS.cyan);
 function cmd(cmd2) {
   return colorize(cmd2, COLORS.green);
 }
-function path11(path13) {
-  return colorize(path13, COLORS.yellow);
+function path12(path15) {
+  return colorize(path15, COLORS.yellow);
 }
 function getHelpGuidance() {
   const lines = [
@@ -6282,14 +6376,14 @@ function getHelpGuidance() {
     "  assistants with tools to perform automated QA testing of web applications.",
     "",
     "  It supports both:",
-    `    ${colorize("\u2022", COLORS.green)} Cloud QA - Test remote production/staging sites`,
+    `    ${colorize("\u2022", COLORS.green)} Cloud QA - Test remote production/staging sites with a public URL`,
     `    ${colorize("\u2022", COLORS.green)} Local QA - Test localhost development servers`,
     "",
     header("Setup Instructions"),
     "",
     `  ${colorize("Step 1:", COLORS.bold)} Configure your MCP client`,
     "",
-    `    For ${colorize("Cursor", COLORS.bold)}, edit ${path11("~/.cursor/mcp.json")}:`,
+    `    For ${colorize("Cursor", COLORS.bold)}, edit ${path12("~/.cursor/mcp.json")}:`,
     "",
     `    ${colorize("{", COLORS.dim)}`,
     `      ${colorize('"mcpServers"', COLORS.yellow)}: {`,
@@ -6308,7 +6402,6 @@ function getHelpGuidance() {
     header("CLI Commands"),
     "",
     `  ${colorize("Server Commands:", COLORS.bold)}`,
-    `    ${cmd("muggle")}                  Start MCP server (default)`,
     `    ${cmd("muggle serve")}            Start MCP server with all tools`,
     `    ${cmd("muggle serve --qa")}       Start with Cloud QA tools only`,
     `    ${cmd("muggle serve --local")}    Start with Local QA tools only`,
@@ -6344,7 +6437,7 @@ function getHelpGuidance() {
     `    2. ${colorize("Log in", COLORS.bold)} with your Muggle AI account`,
     `    3. ${colorize("The tool call continues", COLORS.bold)} with your credentials`,
     "",
-    `  Credentials are stored in ${path11("~/.muggle-ai/credentials.json")}`,
+    `  API keys are stored in ${path12("~/.muggle-ai/api-key.json")}`,
     "",
     header("Available MCP Tools"),
     "",
@@ -6359,12 +6452,12 @@ function getHelpGuidance() {
     "",
     header("Data Directory"),
     "",
-    `  All data is stored in ${path11("~/.muggle-ai/")}:`,
+    `  All data is stored in ${path12("~/.muggle-ai/")}:`,
     "",
-    `    ${path11("credentials.json")}    Auth credentials (auto-generated)`,
-    `    ${path11("projects/")}            Local test projects`,
-    `    ${path11("sessions/")}            Test execution sessions`,
-    `    ${path11("electron-app/")}        Downloaded Electron app binaries`,
+    `    ${path12("api-key.json")}         Long-lived API key (auto-generated)`,
+    `    ${path12("projects/")}            Local test projects`,
+    `    ${path12("sessions/")}            Test execution sessions`,
+    `    ${path12("electron-app/")}        Downloaded Electron app binaries`,
     "",
     header("Troubleshooting"),
     "",
@@ -6499,6 +6592,9 @@ async function serveCommand(options) {
   }
 }
 var logger11 = getLogger();
+var MAX_RETRY_ATTEMPTS = 3;
+var RETRY_BASE_DELAY_MS = 2e3;
+var INSTALL_METADATA_FILE_NAME = ".install-metadata.json";
 function getBinaryName() {
   const os4 = platform();
   const architecture = arch();
@@ -6515,21 +6611,47 @@ function getBinaryName() {
       throw new Error(`Unsupported platform: ${os4}`);
   }
 }
+function getExpectedExecutablePath2(versionDir) {
+  const os4 = platform();
+  switch (os4) {
+    case "darwin":
+      return path2.join(versionDir, "MuggleAI.app", "Contents", "MacOS", "MuggleAI");
+    case "win32":
+      return path2.join(versionDir, "MuggleAI.exe");
+    case "linux":
+      return path2.join(versionDir, "MuggleAI");
+    default:
+      throw new Error(`Unsupported platform: ${os4}`);
+  }
+}
 async function extractZip(zipPath, destDir) {
   return new Promise((resolve4, reject) => {
-    const cmd2 = platform() === "win32" ? `powershell -command "Expand-Archive -Path '${zipPath}' -DestinationPath '${destDir}' -Force"` : `unzip -o "${zipPath}" -d "${destDir}"`;
-    exec(cmd2, (error) => {
-      if (error) {
-        reject(error);
-      } else {
-        resolve4();
-      }
-    });
+    if (platform() === "win32") {
+      execFile(
+        "powershell",
+        ["-command", `Expand-Archive -Path '${zipPath}' -DestinationPath '${destDir}' -Force`],
+        (error) => {
+          if (error) {
+            reject(error);
+          } else {
+            resolve4();
+          }
+        }
+      );
+    } else {
+      execFile("unzip", ["-o", zipPath, "-d", destDir], (error) => {
+        if (error) {
+          reject(error);
+        } else {
+          resolve4();
+        }
+      });
+    }
   });
 }
 async function extractTarGz(tarPath, destDir) {
   return new Promise((resolve4, reject) => {
-    exec(`tar -xzf "${tarPath}" -C "${destDir}"`, (error) => {
+    execFile("tar", ["-xzf", tarPath, "-C", destDir], (error) => {
       if (error) {
         reject(error);
       } else {
@@ -6538,10 +6660,66 @@ async function extractTarGz(tarPath, destDir) {
     });
   });
 }
+function sleep2(ms) {
+  return new Promise((resolve4) => setTimeout(resolve4, ms));
+}
+async function downloadWithRetry(downloadUrl, destPath) {
+  let lastError = null;
+  for (let attempt = 1; attempt <= MAX_RETRY_ATTEMPTS; attempt++) {
+    try {
+      if (attempt > 1) {
+        const delayMs = RETRY_BASE_DELAY_MS * Math.pow(2, attempt - 2);
+        console.log(`Retry attempt ${attempt}/${MAX_RETRY_ATTEMPTS} after ${delayMs}ms delay...`);
+        await sleep2(delayMs);
+      }
+      const response = await fetch(downloadUrl);
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+      if (!response.body) {
+        throw new Error("No response body received");
+      }
+      const fileStream = createWriteStream(destPath);
+      await pipeline(response.body, fileStream);
+      return true;
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+      console.error(`Download attempt ${attempt} failed: ${lastError.message}`);
+      if (existsSync(destPath)) {
+        rmSync(destPath, { force: true });
+      }
+    }
+  }
+  if (lastError) {
+    throw new Error(`Download failed after ${MAX_RETRY_ATTEMPTS} attempts: ${lastError.message}`);
+  }
+  return false;
+}
+function writeInstallMetadata(params) {
+  const metadata = {
+    version: params.version,
+    binaryName: params.binaryName,
+    platformKey: params.platformKey,
+    executableChecksum: params.executableChecksum,
+    expectedArchiveChecksum: params.expectedArchiveChecksum,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  writeFileSync(params.metadataPath, `${JSON.stringify(metadata, null, 2)}
+`, "utf-8");
+}
+function cleanupFailedInstall(versionDir) {
+  if (existsSync(versionDir)) {
+    try {
+      rmSync(versionDir, { recursive: true, force: true });
+    } catch {
+    }
+  }
+}
 async function setupCommand(options) {
   const version = getElectronAppVersion();
   const baseUrl = getDownloadBaseUrl();
   const versionDir = getElectronAppDir(version);
+  const platformKey = getPlatformKey();
   if (!options.force && isElectronAppInstalled()) {
     console.log(`Electron app v${version} is already installed at ${versionDir}`);
     console.log("Use --force to re-download.");
@@ -6556,22 +6734,14 @@ async function setupCommand(options) {
       rmSync(versionDir, { recursive: true, force: true });
     }
     mkdirSync(versionDir, { recursive: true });
-    const response = await fetch(downloadUrl);
-    if (!response.ok) {
-      throw new Error(`Download failed: ${response.status} ${response.statusText}`);
-    }
-    const tempFile = `${versionDir}/${binaryName}`;
-    const fileStream = createWriteStream(tempFile);
-    if (!response.body) {
-      throw new Error("No response body");
-    }
-    await pipeline(response.body, fileStream);
+    const tempFile = path2.join(versionDir, binaryName);
+    await downloadWithRetry(downloadUrl, tempFile);
     console.log("Download complete, verifying checksum...");
     const checksums = getElectronAppChecksums();
     const expectedChecksum = getChecksumForPlatform(checksums);
     const checksumResult = await verifyFileChecksum(tempFile, expectedChecksum);
     if (!checksumResult.valid && expectedChecksum) {
-      rmSync(versionDir, { recursive: true, force: true });
+      cleanupFailedInstall(versionDir);
       throw new Error(
         `Checksum verification failed!
 Expected: ${checksumResult.expected}
@@ -6590,6 +6760,25 @@ The downloaded file may be corrupted or tampered with.`
     } else if (binaryName.endsWith(".tar.gz")) {
       await extractTarGz(tempFile, versionDir);
     }
+    const executablePath = getExpectedExecutablePath2(versionDir);
+    if (!existsSync(executablePath)) {
+      cleanupFailedInstall(versionDir);
+      throw new Error(
+        `Extraction failed: executable not found at expected path.
+Expected: ${executablePath}
+The archive may be corrupted or in an unexpected format.`
+      );
+    }
+    const executableChecksum = await calculateFileChecksum(executablePath);
+    const metadataPath = path2.join(versionDir, INSTALL_METADATA_FILE_NAME);
+    writeInstallMetadata({
+      metadataPath,
+      version,
+      binaryName,
+      platformKey,
+      executableChecksum,
+      expectedArchiveChecksum: expectedChecksum
+    });
     rmSync(tempFile, { force: true });
     console.log(`Electron app installed to ${versionDir}`);
     logger11.info("Setup complete", { version, path: versionDir });
@@ -6602,6 +6791,7 @@ The downloaded file may be corrupted or tampered with.`
 }
 var logger12 = getLogger();
 var GITHUB_RELEASES_API = "https://api.github.com/repos/multiplex-ai/muggle-ai-works/releases";
+var INSTALL_METADATA_FILE_NAME2 = ".install-metadata.json";
 var VERSION_OVERRIDE_FILE2 = "electron-app-version-override.json";
 function getBinaryName2() {
   const os4 = platform();
@@ -6704,21 +6894,59 @@ function compareVersions2(a, b) {
   }
   return 0;
 }
+function getExpectedExecutablePath3(versionDir) {
+  const os4 = platform();
+  switch (os4) {
+    case "darwin":
+      return path2.join(versionDir, "MuggleAI.app", "Contents", "MacOS", "MuggleAI");
+    case "win32":
+      return path2.join(versionDir, "MuggleAI.exe");
+    case "linux":
+      return path2.join(versionDir, "MuggleAI");
+    default:
+      throw new Error(`Unsupported platform: ${os4}`);
+  }
+}
+function writeInstallMetadata2(params) {
+  const metadata = {
+    version: params.version,
+    binaryName: params.binaryName,
+    platformKey: params.platformKey,
+    executableChecksum: params.executableChecksum,
+    expectedArchiveChecksum: params.expectedArchiveChecksum,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  writeFileSync(params.metadataPath, `${JSON.stringify(metadata, null, 2)}
+`, "utf-8");
+}
 async function extractZip2(zipPath, destDir) {
   return new Promise((resolve4, reject) => {
-    const cmd2 = platform() === "win32" ? `powershell -command "Expand-Archive -Path '${zipPath}' -DestinationPath '${destDir}' -Force"` : `unzip -o "${zipPath}" -d "${destDir}"`;
-    exec(cmd2, (error) => {
-      if (error) {
-        reject(error);
-      } else {
-        resolve4();
-      }
-    });
+    if (platform() === "win32") {
+      execFile(
+        "powershell",
+        ["-command", `Expand-Archive -Path '${zipPath}' -DestinationPath '${destDir}' -Force`],
+        (error) => {
+          if (error) {
+            reject(error);
+          } else {
+            resolve4();
+          }
+        }
+      );
+    } else {
+      execFile("unzip", ["-o", zipPath, "-d", destDir], (error) => {
+        if (error) {
+          reject(error);
+        } else {
+          resolve4();
+        }
+      });
+    }
   });
 }
 async function extractTarGz2(tarPath, destDir) {
   return new Promise((resolve4, reject) => {
-    exec(`tar -xzf "${tarPath}" -C "${destDir}"`, (error) => {
+    execFile("tar", ["-xzf", tarPath, "-C", destDir], (error) => {
       if (error) {
         reject(error);
       } else {
@@ -6776,6 +7004,7 @@ async function fetchChecksumFromRelease(version) {
 async function downloadAndInstall(version, downloadUrl, checksum) {
   const versionDir = getElectronAppDir(version);
   const binaryName = getBinaryName2();
+  const platformKey = getPlatformKey();
   console.log(`Downloading Muggle Test Electron app v${version}...`);
   console.log(`URL: ${downloadUrl}`);
   if (existsSync(versionDir)) {
@@ -6818,6 +7047,25 @@ The downloaded file may be corrupted or tampered with.`
   } else if (binaryName.endsWith(".tar.gz")) {
     await extractTarGz2(tempFile, versionDir);
   }
+  const executablePath = getExpectedExecutablePath3(versionDir);
+  if (!existsSync(executablePath)) {
+    rmSync(versionDir, { recursive: true, force: true });
+    throw new Error(
+      `Extraction failed: executable not found at expected path.
+Expected: ${executablePath}
+The archive may be corrupted or in an unexpected format.`
+    );
+  }
+  const executableChecksum = await calculateFileChecksum(executablePath);
+  const metadataPath = path2.join(versionDir, INSTALL_METADATA_FILE_NAME2);
+  writeInstallMetadata2({
+    metadataPath,
+    version,
+    binaryName,
+    platformKey,
+    executableChecksum,
+    expectedArchiveChecksum: expectedChecksum || ""
+  });
   rmSync(tempFile, { force: true });
   saveVersionOverride(version);
   console.log(`Electron app v${version} installed to ${versionDir}`);
@@ -6900,7 +7148,11 @@ function createProgram() {
   program.command("logout").description("Clear stored credentials").action(logoutCommand);
   program.command("status").description("Show authentication status").action(statusCommand);
   program.action(() => {
-    serveCommand({ });
+    helpCommand();
+  });
+  program.on("command:*", () => {
+    helpCommand();
+    process.exit(1);
   });
   return program;
 }

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { runCli } from './chunk-AJKZXT7B.js';
+import { runCli } from './chunk-PV76IWEX.js';
 
 // src/cli/main.ts
 runCli().catch((error) => {

package/dist/index.js

@@ -1 +1 @@
-export { src_exports2 as commands, createChildLogger, createUnifiedMcpServer, getConfig, getLocalQaTools, getLogger, getQaTools, local_exports as localQa, mcp_exports as mcp, qa_exports as qa, server_exports as server, src_exports as shared } from './chunk-AJKZXT7B.js';
+export { src_exports2 as commands, createChildLogger, createUnifiedMcpServer, getConfig, getLocalQaTools, getLogger, getQaTools, local_exports as localQa, mcp_exports as mcp, qa_exports as qa, server_exports as server, src_exports as shared } from './chunk-PV76IWEX.js';

package/dist/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "muggle",
   "description": "Run real-browser QA tests on your web app from any AI coding agent. Generate test scripts from plain English, replay them on localhost, capture screenshots, and validate user flows like signup, checkout, and dashboards. Works across Claude Code, Cursor, Codex, and Windsurf.",
-  "version": "4.0.1",
+  "version": "4.1.0",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/dist/plugin/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "muggle",
   "displayName": "Muggle AI",
   "description": "Ship quality products with AI-powered QA that validates your app's user experience — from Claude Code and Cursor to PR.",
-  "version": "4.0.1",
+  "version": "4.1.0",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/dist/plugin/skills/muggle-test-feature-local/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: muggle-test-feature-local
-description: Test a feature's user experience on localhost. Use when user types muggle test-feature-local, test my app, run QA, or validate UI changes.
+description: Run a real-browser QA test against localhost to verify a feature works correctly — signup flows, checkout, form validation, UI interactions, or any user-facing behavior. Launches a browser that executes test steps and captures screenshots. Use this skill whenever the user asks to test, QA, validate, or verify their web app, UI changes, user flows, or frontend behavior on localhost or a dev server — even if they don't mention 'muggle' or 'QA' explicitly.
 ---
 
 # Muggle Test Feature Local
@@ -12,54 +12,111 @@ Run end-to-end feature testing from UI against a local URL:
 
 ## Workflow
 
-1. **Auth**
-   - `muggle-remote-auth-status`
-   - If needed: `muggle-remote-auth-login` + `muggle-remote-auth-poll`
-
-2. **Select or create the project -> use case -> test case to use**
-   - Explictly ask user to select each target to proceed.
-   - `muggle-remote-project-list`
-   - `muggle-remote-use-case-list`
-   - `muggle-remote-test-case-list-by-use-case`
-
-3. **Resolve local URL**
-   - Use the URL provided by the user.
-   - If missing, ask explicitly (do not guess).
-   - Inform user the local URL does not affect the project's remote test.
-
-4. **Check script availability**
-   - `muggle-remote-test-script-list` filtered by testCaseId
-   - If script exists, recommend replay unless user-flow changes suggest regeneration.
-
-5. **Execute**
-   - Replay path:
-     - `muggle-remote-test-script-get`
-     - `muggle-local-execute-replay`
-   - Generation path:
-     - `muggle-remote-test-case-get`
-     - `muggle-local-execute-test-generation`
-
-6. **Approval requirement**
-   - Before execution, get explicit user approval for launching Electron app.
-   - Only then set `approveElectronAppLaunch: true`.
-
-7. **Publish local generation result to MuggleTest cloud records**
-   - Use `muggle-local-publish-test-script` after successful generation so user can see the full job details.
-   - Return the remote URL for user to view the result and script details.
-
-8. **Report results**
-   - `muggle-local-run-result-get` with returned runId.
-   - Report:
-     - status
-     - duration
-     - pass/fail summary
-     - steps summary
-     - artifacts path
-     - script detail view URL
+### 1. Auth
+
+- `muggle-remote-auth-status`
+- If needed: `muggle-remote-auth-login` + `muggle-remote-auth-poll`
+
+### 2. Select project, use case, and test case
+
+- Explicitly ask user to select each target to proceed.
+- `muggle-remote-project-list`
+- `muggle-remote-use-case-list`
+- `muggle-remote-test-case-list-by-use-case`
+
+### 3. Resolve local URL
+
+- Use the URL provided by the user.
+- If missing, ask explicitly (do not guess).
+- Inform user the local URL does not affect the project's remote test.
+
+### 4. Check for existing scripts and ask user to choose
+
+Check BOTH cloud and local scripts to determine what's available:
+
+1. **Check cloud scripts:** `muggle-remote-test-script-list` filtered by projectId
+2. **Check local scripts:** `muggle-local-test-script-list` filtered by projectId
+
+**Decision logic:**
+
+| Cloud Script | Local Script (status: published/generated) | Action |
+|--------------|---------------------------------------------|--------|
+| Exists + ACTIVE | Exists | Ask user: "Replay existing script" or "Regenerate from scratch"? |
+| Exists + ACTIVE | Not found | Sync from cloud first, then ask user |
+| Not found | Exists | Ask user: "Replay local script" or "Regenerate"? |
+| Not found | Not found | Default to generation (no need to ask) |
+
+**When asking user, show:**
+- Script name and ID
+- When it was created/updated
+- Number of steps
+- Last run status if available
+
+### 5. Prepare for execution
+
+**For Replay:**
+
+Local scripts contain the complete `actionScript` with element labels required for replay. Remote scripts only contain metadata.
+
+1. Use `muggle-local-test-script-get` with `testScriptId` to fetch the FULL script including actionScript
+2. The returned script includes all steps with `operation.label` paths needed for element location
+3. Pass this complete script to `muggle-local-execute-replay`
+
+**IMPORTANT:** Do NOT manually construct or simplify the actionScript. The electron app requires the complete script with all `label` paths intact to locate page elements during replay.
+
+**For Generation:**
+
+1. `muggle-remote-test-case-get` to fetch test case details
+2. `muggle-local-execute-test-generation` with the test case
+
+### 6. Approval requirement
+
+- Before execution, get explicit user approval for launching Electron app.
+- Show what will be executed (replay vs generation, test case name, URL).
+- Only then set `approveElectronAppLaunch: true`.
+
+### 7. Execute
+
+**Replay:**
+```
+muggle-local-execute-replay with:
+- testScript: (full script from muggle-local-test-script-get)
+- localUrl: user-provided localhost URL
+- approveElectronAppLaunch: true
+- showUi: true (optional, lets user watch)
+```
+
+**Generation:**
+```
+muggle-local-execute-test-generation with:
+- testCase: (from muggle-remote-test-case-get)
+- localUrl: user-provided localhost URL
+- approveElectronAppLaunch: true
+- showUi: true (optional)
+```
+
+### 8. Publish generation results (generation only)
+
+- Use `muggle-local-publish-test-script` after successful generation.
+- This uploads the script to cloud so it can be replayed later.
+- Return the remote URL for user to view the result.
+
+### 9. Report results
+
+- `muggle-local-run-result-get` with returned runId.
+- Report:
+  - status (passed/failed)
+  - duration
+  - pass/fail summary
+  - steps summary (which steps passed/failed)
+  - artifacts path (screenshots location)
+  - script detail view URL
 
 ## Guardrails
 
 - Do not silently skip auth.
-- Do not silently skip test execution when no script exists; generate one.
+- Do not silently skip asking user when a replayable script exists.
 - Do not launch Electron without explicit approval.
 - Do not hide failing run details; include error and artifacts path.
+- Do not simplify or reconstruct actionScript for replay; use the complete script from `muggle-local-test-script-get`.
+- Always check local scripts before defaulting to generation.

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@muggleai/works",
     "mcpName": "io.github.multiplex-ai/muggle",
-    "version": "4.0.1",
+    "version": "4.1.0",
     "description": "Ship quality products with AI-powered QA that validates your app's user experience — from Claude Code and Cursor to PR.",
     "type": "module",
     "main": "dist/index.js",

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "muggle",
   "description": "Run real-browser QA tests on your web app from any AI coding agent. Generate test scripts from plain English, replay them on localhost, capture screenshots, and validate user flows like signup, checkout, and dashboards. Works across Claude Code, Cursor, Codex, and Windsurf.",
-  "version": "4.0.1",
+  "version": "4.1.0",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/plugin/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "muggle",
   "displayName": "Muggle AI",
   "description": "Ship quality products with AI-powered QA that validates your app's user experience — from Claude Code and Cursor to PR.",
-  "version": "4.0.1",
+  "version": "4.1.0",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/plugin/skills/muggle-test-feature-local/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: muggle-test-feature-local
-description: Test a feature's user experience on localhost. Use when user types muggle test-feature-local, test my app, run QA, or validate UI changes.
+description: Run a real-browser QA test against localhost to verify a feature works correctly — signup flows, checkout, form validation, UI interactions, or any user-facing behavior. Launches a browser that executes test steps and captures screenshots. Use this skill whenever the user asks to test, QA, validate, or verify their web app, UI changes, user flows, or frontend behavior on localhost or a dev server — even if they don't mention 'muggle' or 'QA' explicitly.
 ---
 
 # Muggle Test Feature Local
@@ -12,54 +12,111 @@ Run end-to-end feature testing from UI against a local URL:
 
 ## Workflow
 
-1. **Auth**
-   - `muggle-remote-auth-status`
-   - If needed: `muggle-remote-auth-login` + `muggle-remote-auth-poll`
-
-2. **Select or create the project -> use case -> test case to use**
-   - Explictly ask user to select each target to proceed.
-   - `muggle-remote-project-list`
-   - `muggle-remote-use-case-list`
-   - `muggle-remote-test-case-list-by-use-case`
-
-3. **Resolve local URL**
-   - Use the URL provided by the user.
-   - If missing, ask explicitly (do not guess).
-   - Inform user the local URL does not affect the project's remote test.
-
-4. **Check script availability**
-   - `muggle-remote-test-script-list` filtered by testCaseId
-   - If script exists, recommend replay unless user-flow changes suggest regeneration.
-
-5. **Execute**
-   - Replay path:
-     - `muggle-remote-test-script-get`
-     - `muggle-local-execute-replay`
-   - Generation path:
-     - `muggle-remote-test-case-get`
-     - `muggle-local-execute-test-generation`
-
-6. **Approval requirement**
-   - Before execution, get explicit user approval for launching Electron app.
-   - Only then set `approveElectronAppLaunch: true`.
-
-7. **Publish local generation result to MuggleTest cloud records**
-   - Use `muggle-local-publish-test-script` after successful generation so user can see the full job details.
-   - Return the remote URL for user to view the result and script details.
-
-8. **Report results**
-   - `muggle-local-run-result-get` with returned runId.
-   - Report:
-     - status
-     - duration
-     - pass/fail summary
-     - steps summary
-     - artifacts path
-     - script detail view URL
+### 1. Auth
+
+- `muggle-remote-auth-status`
+- If needed: `muggle-remote-auth-login` + `muggle-remote-auth-poll`
+
+### 2. Select project, use case, and test case
+
+- Explicitly ask user to select each target to proceed.
+- `muggle-remote-project-list`
+- `muggle-remote-use-case-list`
+- `muggle-remote-test-case-list-by-use-case`
+
+### 3. Resolve local URL
+
+- Use the URL provided by the user.
+- If missing, ask explicitly (do not guess).
+- Inform user the local URL does not affect the project's remote test.
+
+### 4. Check for existing scripts and ask user to choose
+
+Check BOTH cloud and local scripts to determine what's available:
+
+1. **Check cloud scripts:** `muggle-remote-test-script-list` filtered by projectId
+2. **Check local scripts:** `muggle-local-test-script-list` filtered by projectId
+
+**Decision logic:**
+
+| Cloud Script | Local Script (status: published/generated) | Action |
+|--------------|---------------------------------------------|--------|
+| Exists + ACTIVE | Exists | Ask user: "Replay existing script" or "Regenerate from scratch"? |
+| Exists + ACTIVE | Not found | Sync from cloud first, then ask user |
+| Not found | Exists | Ask user: "Replay local script" or "Regenerate"? |
+| Not found | Not found | Default to generation (no need to ask) |
+
+**When asking user, show:**
+- Script name and ID
+- When it was created/updated
+- Number of steps
+- Last run status if available
+
+### 5. Prepare for execution
+
+**For Replay:**
+
+Local scripts contain the complete `actionScript` with element labels required for replay. Remote scripts only contain metadata.
+
+1. Use `muggle-local-test-script-get` with `testScriptId` to fetch the FULL script including actionScript
+2. The returned script includes all steps with `operation.label` paths needed for element location
+3. Pass this complete script to `muggle-local-execute-replay`
+
+**IMPORTANT:** Do NOT manually construct or simplify the actionScript. The electron app requires the complete script with all `label` paths intact to locate page elements during replay.
+
+**For Generation:**
+
+1. `muggle-remote-test-case-get` to fetch test case details
+2. `muggle-local-execute-test-generation` with the test case
+
+### 6. Approval requirement
+
+- Before execution, get explicit user approval for launching Electron app.
+- Show what will be executed (replay vs generation, test case name, URL).
+- Only then set `approveElectronAppLaunch: true`.
+
+### 7. Execute
+
+**Replay:**
+```
+muggle-local-execute-replay with:
+- testScript: (full script from muggle-local-test-script-get)
+- localUrl: user-provided localhost URL
+- approveElectronAppLaunch: true
+- showUi: true (optional, lets user watch)
+```
+
+**Generation:**
+```
+muggle-local-execute-test-generation with:
+- testCase: (from muggle-remote-test-case-get)
+- localUrl: user-provided localhost URL
+- approveElectronAppLaunch: true
+- showUi: true (optional)
+```
+
+### 8. Publish generation results (generation only)
+
+- Use `muggle-local-publish-test-script` after successful generation.
+- This uploads the script to cloud so it can be replayed later.
+- Return the remote URL for user to view the result.
+
+### 9. Report results
+
+- `muggle-local-run-result-get` with returned runId.
+- Report:
+  - status (passed/failed)
+  - duration
+  - pass/fail summary
+  - steps summary (which steps passed/failed)
+  - artifacts path (screenshots location)
+  - script detail view URL
 
 ## Guardrails
 
 - Do not silently skip auth.
-- Do not silently skip test execution when no script exists; generate one.
+- Do not silently skip asking user when a replayable script exists.
 - Do not launch Electron without explicit approval.
 - Do not hide failing run details; include error and artifacts path.
+- Do not simplify or reconstruct actionScript for replay; use the complete script from `muggle-local-test-script-get`.
+- Always check local scripts before defaulting to generation.