@muggleai/works 4.8.4 → 4.9.1

package/dist/{chunk-44I5ROCB.js → chunk-4KQZLF56.js}

@@ -28,6 +28,13 @@ var __export = (target, all) => {
 // packages/mcps/src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  DEFAULT_PREFERENCES: () => DEFAULT_PREFERENCES,
+  PREFERENCES_FILE_NAME: () => PREFERENCES_FILE_NAME,
+  PREFERENCES_PROJECT_DIR_NAME: () => PREFERENCES_PROJECT_DIR_NAME,
+  PREFERENCES_SCHEMA: () => PREFERENCES_SCHEMA,
+  PREFERENCES_VERSION: () => PREFERENCES_VERSION,
+  PreferenceKey: () => PreferenceKey,
+  PreferenceValue: () => PreferenceValue,
   buildElectronAppChecksumsUrl: () => buildElectronAppChecksumsUrl,
   buildElectronAppReleaseAssetUrl: () => buildElectronAppReleaseAssetUrl,
   buildElectronAppReleaseTag: () => buildElectronAppReleaseTag,
@@ -37,6 +44,7 @@ __export(src_exports, {
   deleteApiKeyData: () => deleteApiKeyData,
   deleteCredentials: () => deleteCredentials,
   e2e: () => e2e_exports2,
+  formatPreferencesOneLiner: () => formatPreferencesOneLiner,
   getApiKey: () => getApiKey,
   getApiKeyFilePath: () => getApiKeyFilePath,
   getAuthService: () => getAuthService,
@@ -60,6 +68,7 @@ __export(src_exports, {
   getValidCredentials: () => getValidCredentials,
   hasApiKey: () => hasApiKey,
   isElectronAppInstalled: () => isElectronAppInstalled,
+  isFirstRun: () => isFirstRun,
   loadApiKeyData: () => loadApiKeyData,
   loadCredentials: () => loadCredentials,
   localQa: () => local_exports2,
@@ -69,14 +78,20 @@ __export(src_exports, {
   performLogout: () => performLogout,
   pollDeviceCode: () => pollDeviceCode,
   qa: () => e2e_exports2,
+  readGlobalPreferences: () => readGlobalPreferences,
+  readProjectPreferences: () => readProjectPreferences,
   resetConfig: () => resetConfig,
   resetLogger: () => resetLogger,
+  resetPreference: () => resetPreference,
+  resolvePreferences: () => resolvePreferences,
   saveApiKey: () => saveApiKey,
   saveApiKeyData: () => saveApiKeyData,
   saveCredentials: () => saveCredentials,
   startDeviceCodeFlow: () => startDeviceCodeFlow,
   toolRequiresAuth: () => toolRequiresAuth,
-  verifyFileChecksum: () => verifyFileChecksum
+  validatePreference: () => validatePreference,
+  verifyFileChecksum: () => verifyFileChecksum,
+  writePreferences: () => writePreferences
 });
 var DATA_DIR_NAME = ".muggle-ai";
 function getDataDir() {
@@ -3466,17 +3481,17 @@ var PromptServiceClient = class {
    * @param path - Path to validate.
    * @throws GatewayError if path is not allowed.
    */
-  validatePath(path10) {
-    const isAllowed = ALLOWED_UPSTREAM_PREFIXES.some((prefix) => path10.startsWith(prefix));
+  validatePath(path11) {
+    const isAllowed = ALLOWED_UPSTREAM_PREFIXES.some((prefix) => path11.startsWith(prefix));
     if (!isAllowed) {
       const logger6 = getLogger();
       logger6.error("Path not in allowlist", {
-        path: path10,
+        path: path11,
         allowedPrefixes: ALLOWED_UPSTREAM_PREFIXES
       });
       throw new GatewayError({
         code: "FORBIDDEN" /* FORBIDDEN */,
-        message: `Path '${path10}' is not allowed`
+        message: `Path '${path11}' is not allowed`
       });
     }
   }
@@ -5268,6 +5283,173 @@ var CleanupSessionsInputSchema = z.object({
 });
 var EmptyInputSchema2 = z.object({});
 
+// packages/mcps/src/shared/preferences-types.ts
+var PreferenceKey = /* @__PURE__ */ ((PreferenceKey2) => {
+  PreferenceKey2["AutoLogin"] = "autoLogin";
+  PreferenceKey2["AutoSelectProject"] = "autoSelectProject";
+  PreferenceKey2["ShowElectronBrowser"] = "showElectronBrowser";
+  PreferenceKey2["OpenTestResultsAfterRun"] = "openTestResultsAfterRun";
+  PreferenceKey2["DefaultExecutionMode"] = "defaultExecutionMode";
+  PreferenceKey2["AutoPublishLocalResults"] = "autoPublishLocalResults";
+  PreferenceKey2["SuggestRelatedUseCases"] = "suggestRelatedUseCases";
+  PreferenceKey2["SuggestRelatedTestCases"] = "suggestRelatedTestCases";
+  PreferenceKey2["AutoDetectChanges"] = "autoDetectChanges";
+  PreferenceKey2["PostPRVisualWalkthrough"] = "postPRVisualWalkthrough";
+  PreferenceKey2["CheckForUpdates"] = "checkForUpdates";
+  PreferenceKey2["VerboseOutput"] = "verboseOutput";
+  return PreferenceKey2;
+})(PreferenceKey || {});
+var PreferenceValue = /* @__PURE__ */ ((PreferenceValue2) => {
+  PreferenceValue2["Always"] = "always";
+  PreferenceValue2["Ask"] = "ask";
+  PreferenceValue2["Never"] = "never";
+  return PreferenceValue2;
+})(PreferenceValue || {});
+
+// packages/mcps/src/mcp/local/contracts/preferences-schemas.ts
+var preferenceKeyValues = Object.values(PreferenceKey);
+var preferenceValueValues = Object.values(PreferenceValue);
+var PreferencesSetInputSchema = z.object({
+  key: z.enum(preferenceKeyValues).describe("The preference key to set."),
+  value: z.enum(preferenceValueValues).describe("The value: always, ask, or never."),
+  scope: z.enum(["global", "project"]).default("global").describe("Write to global (~/.muggle-ai/) or project (.muggle-ai/) preferences."),
+  cwd: z.string().optional().describe("Project root directory. Required when scope is 'project'.")
+});
+
+// packages/mcps/src/shared/preferences-constants.ts
+var PREFERENCES_FILE_NAME = "preferences.json";
+var PREFERENCES_PROJECT_DIR_NAME = ".muggle-ai";
+var PREFERENCES_VERSION = 1;
+var DEFAULT_PREFERENCES = {
+  ["autoLogin" /* AutoLogin */]: "ask" /* Ask */,
+  ["autoSelectProject" /* AutoSelectProject */]: "ask" /* Ask */,
+  ["showElectronBrowser" /* ShowElectronBrowser */]: "ask" /* Ask */,
+  ["openTestResultsAfterRun" /* OpenTestResultsAfterRun */]: "ask" /* Ask */,
+  ["defaultExecutionMode" /* DefaultExecutionMode */]: "ask" /* Ask */,
+  ["autoPublishLocalResults" /* AutoPublishLocalResults */]: "ask" /* Ask */,
+  ["suggestRelatedUseCases" /* SuggestRelatedUseCases */]: "ask" /* Ask */,
+  ["suggestRelatedTestCases" /* SuggestRelatedTestCases */]: "ask" /* Ask */,
+  ["autoDetectChanges" /* AutoDetectChanges */]: "ask" /* Ask */,
+  ["postPRVisualWalkthrough" /* PostPRVisualWalkthrough */]: "ask" /* Ask */,
+  ["checkForUpdates" /* CheckForUpdates */]: "ask" /* Ask */,
+  ["verboseOutput" /* VerboseOutput */]: "ask" /* Ask */
+};
+var PREFERENCES_SCHEMA = {
+  ["autoLogin" /* AutoLogin */]: {
+    description: "When a tool requires auth and saved credentials exist, reuse them without prompting"
+  },
+  ["autoSelectProject" /* AutoSelectProject */]: {
+    description: "When a skill needs a Muggle project and one was used previously in this repo, reuse it without prompting"
+  },
+  ["showElectronBrowser" /* ShowElectronBrowser */]: {
+    description: "When running local E2E tests, show the Electron browser window"
+  },
+  ["openTestResultsAfterRun" /* OpenTestResultsAfterRun */]: {
+    description: "After a local E2E test run completes, open the per-run results page on Muggle dashboard"
+  },
+  ["defaultExecutionMode" /* DefaultExecutionMode */]: {
+    description: "When a skill supports both local and remote test execution, which to default to"
+  },
+  ["autoPublishLocalResults" /* AutoPublishLocalResults */]: {
+    description: "After a local E2E test run completes, upload results to Muggle cloud for team visibility"
+  },
+  ["suggestRelatedUseCases" /* SuggestRelatedUseCases */]: {
+    description: "After creating or running a use case, suggest related use cases to add"
+  },
+  ["suggestRelatedTestCases" /* SuggestRelatedTestCases */]: {
+    description: "After creating or running a test case, suggest related test cases to add"
+  },
+  ["autoDetectChanges" /* AutoDetectChanges */]: {
+    description: "When running muggle-test, scan local git changes and map to affected test cases"
+  },
+  ["postPRVisualWalkthrough" /* PostPRVisualWalkthrough */]: {
+    description: "After test results are available, post visual walkthrough comment with screenshots to the PR"
+  },
+  ["checkForUpdates" /* CheckForUpdates */]: {
+    description: "At session start, check if a newer Muggle version is available and notify"
+  },
+  ["verboseOutput" /* VerboseOutput */]: {
+    description: "Show detailed progress logs during skill and tool execution"
+  }
+};
+
+// packages/mcps/src/shared/preferences.ts
+function isFirstRun(dataDirOverride) {
+  const filePath = path2.join(dataDirOverride ?? getDataDir(), PREFERENCES_FILE_NAME);
+  return !fs5.existsSync(filePath);
+}
+function readPreferencesFile(filePath) {
+  try {
+    if (!fs5.existsSync(filePath)) {
+      return {};
+    }
+    const raw = JSON.parse(fs5.readFileSync(filePath, "utf-8"));
+    return raw.preferences ?? {};
+  } catch (error) {
+    getLogger().warn("Failed to read preferences file", {
+      path: filePath,
+      error: error instanceof Error ? error.message : String(error)
+    });
+    return {};
+  }
+}
+function readGlobalPreferences(dataDirOverride) {
+  const filePath = path2.join(dataDirOverride ?? getDataDir(), PREFERENCES_FILE_NAME);
+  const partial = readPreferencesFile(filePath);
+  return { ...DEFAULT_PREFERENCES, ...partial };
+}
+function readProjectPreferences(cwd) {
+  const filePath = path2.join(cwd, PREFERENCES_PROJECT_DIR_NAME, PREFERENCES_FILE_NAME);
+  return readPreferencesFile(filePath);
+}
+function resolvePreferences(dataDirOverride, cwd) {
+  const global = readGlobalPreferences(dataDirOverride);
+  if (!cwd) {
+    return global;
+  }
+  const project = readProjectPreferences(cwd);
+  return { ...global, ...project };
+}
+function writePreferences(prefs, scope, dataDirOverride, cwd) {
+  const dir = scope === "project" && cwd ? path2.join(cwd, PREFERENCES_PROJECT_DIR_NAME) : dataDirOverride ?? getDataDir();
+  fs5.mkdirSync(dir, { recursive: true });
+  const filePath = path2.join(dir, PREFERENCES_FILE_NAME);
+  const existing = readPreferencesFile(filePath);
+  const merged = { ...existing, ...prefs };
+  const file = {
+    version: PREFERENCES_VERSION,
+    preferences: merged
+  };
+  fs5.writeFileSync(filePath, `${JSON.stringify(file, null, 2)}
+`, "utf-8");
+}
+function resetPreference(key, scope, dataDirOverride, cwd) {
+  const dir = scope === "project" && cwd ? path2.join(cwd, PREFERENCES_PROJECT_DIR_NAME) : dataDirOverride ?? getDataDir();
+  const filePath = path2.join(dir, PREFERENCES_FILE_NAME);
+  if (!fs5.existsSync(filePath)) {
+    return;
+  }
+  if (!key) {
+    const file2 = { version: PREFERENCES_VERSION, preferences: {} };
+    fs5.writeFileSync(filePath, `${JSON.stringify(file2, null, 2)}
+`, "utf-8");
+    return;
+  }
+  const existing = readPreferencesFile(filePath);
+  delete existing[key];
+  const file = { version: PREFERENCES_VERSION, preferences: existing };
+  fs5.writeFileSync(filePath, `${JSON.stringify(file, null, 2)}
+`, "utf-8");
+}
+function validatePreference(key, value) {
+  const validKeys = Object.values(PreferenceKey);
+  const validValues = Object.values(PreferenceValue);
+  return validKeys.includes(key) && validValues.includes(value);
+}
+function formatPreferencesOneLiner(prefs) {
+  return Object.entries(prefs).map(([key, value]) => `${key}=${value}`).join(" ");
+}
+
 // packages/mcps/src/mcp/tools/local/tool-registry.ts
 function createChildLogger2(correlationId) {
   const logger6 = getLogger();
@@ -5709,6 +5891,33 @@ var publishTestScriptTool = {
     }
   }
 };
+var preferencesSetTool = {
+  name: "muggle-local-preferences-set",
+  description: "Set a Muggle AI user preference. Preferences control automation behavior (auto-login, show browser, suggest test cases, etc.). Values: 'always' (proceed without asking), 'ask' (prompt each time), 'never' (skip without asking). Scope: 'global' writes to ~/.muggle-ai/preferences.json, 'project' writes to .muggle-ai/preferences.json in the repo root.",
+  inputSchema: PreferencesSetInputSchema,
+  execute: async (ctx) => {
+    const logger6 = createChildLogger2(ctx.correlationId);
+    logger6.info("Executing muggle-local-preferences-set");
+    const input = PreferencesSetInputSchema.parse(ctx.input);
+    writePreferences(
+      { [input.key]: input.value },
+      input.scope,
+      void 0,
+      input.cwd
+    );
+    const resolved = resolvePreferences(void 0, input.cwd);
+    const oneLiner = formatPreferencesOneLiner(resolved);
+    const content = [
+      `**${input.key}** set to **${input.value}** (${input.scope}).`,
+      "",
+      `Preferences file: ~/.muggle-ai/${PREFERENCES_FILE_NAME}`,
+      "",
+      "Current resolved preferences:",
+      `\`${oneLiner}\``
+    ].join("\n");
+    return { content, isError: false };
+  }
+};
 var allLocalQaTools = [
   // Status tools
   checkStatusTool,
@@ -5724,7 +5933,9 @@ var allLocalQaTools = [
   executeReplayTool,
   cancelExecutionTool,
   // Publishing tools
-  publishTestScriptTool
+  publishTestScriptTool,
+  // Preferences tools
+  preferencesSetTool
 ];
 var toolMap = new Map(
   allLocalQaTools.map((tool) => [tool.name, tool])
@@ -5871,6 +6082,7 @@ __export(local_exports2, {
   LocalWorkflowFileEntityType: () => LocalWorkflowFileEntityType,
   LocalWorkflowRunStatus: () => LocalWorkflowRunStatus,
   MuggleEntityIdSchema: () => MuggleEntityIdSchema,
+  PreferencesSetInputSchema: () => PreferencesSetInputSchema,
   PublishTestScriptInputSchema: () => PublishTestScriptInputSchema,
   RunResultGetInputSchema: () => RunResultGetInputSchema,
   RunResultListInputSchema: () => RunResultListInputSchema,
@@ -5939,4 +6151,4 @@ var plugins_exports = {};
 // packages/mcps/src/mcp/agents/index.ts
 var agents_exports = {};
 
-export { __export, __require, buildElectronAppChecksumsUrl, buildElectronAppReleaseAssetUrl, buildElectronAppReleaseTag, calculateFileChecksum, createApiKeyWithToken, createChildLogger, deleteApiKeyData, deleteCredentials, e2e_exports2 as e2e_exports, getApiKey, getApiKeyFilePath, getAuthService, getBundledElectronAppVersion, getCallerCredentials, getCallerCredentialsAsync, getChecksumForPlatform, getConfig, getCredentialsFilePath, getDataDir2 as getDataDir, getDownloadBaseUrl, getElectronAppChecksums, getElectronAppDir, getElectronAppVersion, getElectronAppVersionSource, getLocalQaTools, getLogger, getPlatformKey, getQaTools, getValidApiKeyData, getValidCredentials, hasApiKey, isElectronAppInstalled, loadApiKeyData, loadCredentials, local_exports2 as local_exports, mcp_exports, openBrowserUrl, performLogin, performLogout, pollDeviceCode, resetConfig, resetLogger, saveApiKey, saveApiKeyData, saveCredentials, src_exports, startDeviceCodeFlow, toolRequiresAuth, verifyFileChecksum };
+export { DEFAULT_PREFERENCES, PREFERENCES_FILE_NAME, PREFERENCES_PROJECT_DIR_NAME, PREFERENCES_SCHEMA, PREFERENCES_VERSION, PreferenceKey, PreferenceValue, __export, __require, buildElectronAppChecksumsUrl, buildElectronAppReleaseAssetUrl, buildElectronAppReleaseTag, calculateFileChecksum, createApiKeyWithToken, createChildLogger, deleteApiKeyData, deleteCredentials, e2e_exports2 as e2e_exports, formatPreferencesOneLiner, getApiKey, getApiKeyFilePath, getAuthService, getBundledElectronAppVersion, getCallerCredentials, getCallerCredentialsAsync, getChecksumForPlatform, getConfig, getCredentialsFilePath, getDataDir2 as getDataDir, getDownloadBaseUrl, getElectronAppChecksums, getElectronAppDir, getElectronAppVersion, getElectronAppVersionSource, getLocalQaTools, getLogger, getPlatformKey, getQaTools, getValidApiKeyData, getValidCredentials, hasApiKey, isElectronAppInstalled, isFirstRun, loadApiKeyData, loadCredentials, local_exports2 as local_exports, mcp_exports, openBrowserUrl, performLogin, performLogout, pollDeviceCode, readGlobalPreferences, readProjectPreferences, resetConfig, resetLogger, resetPreference, resolvePreferences, saveApiKey, saveApiKeyData, saveCredentials, src_exports, startDeviceCodeFlow, toolRequiresAuth, validatePreference, verifyFileChecksum, writePreferences };

package/dist/{chunk-OMLNCNSZ.js → chunk-6N7OIBAS.js}

@@ -1,4 +1,4 @@
-import { __export, getLogger, getConfig, createChildLogger, buildElectronAppReleaseAssetUrl, getAuthService, hasApiKey, getElectronAppVersion, getElectronAppDir, getPlatformKey, isElectronAppInstalled, getElectronAppChecksums, getChecksumForPlatform, verifyFileChecksum, calculateFileChecksum, getQaTools, getLocalQaTools, performLogout, performLogin, toolRequiresAuth, getCallerCredentials, getDataDir, getBundledElectronAppVersion, getElectronAppVersionSource, getCredentialsFilePath, buildElectronAppChecksumsUrl, __require } from './chunk-44I5ROCB.js';
+import { __export, getLogger, getConfig, createChildLogger, buildElectronAppReleaseAssetUrl, getAuthService, hasApiKey, getElectronAppVersion, getElectronAppDir, getPlatformKey, isFirstRun, writePreferences, DEFAULT_PREFERENCES, getDataDir, PREFERENCES_FILE_NAME, isElectronAppInstalled, getElectronAppChecksums, getChecksumForPlatform, verifyFileChecksum, calculateFileChecksum, getQaTools, getLocalQaTools, performLogout, performLogin, toolRequiresAuth, getCallerCredentials, getBundledElectronAppVersion, getElectronAppVersionSource, getCredentialsFilePath, buildElectronAppChecksumsUrl, __require } from './chunk-4KQZLF56.js';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { v4 } from 'uuid';
@@ -686,7 +686,7 @@ async function resolveGsScreenshotUrls(report, opts) {
     if (gsUrls.length === 0) {
       return report;
     }
-    const mcps = await import('./src-ZRUONWKV.js');
+    const mcps = await import('./src-7GB7WIFT.js');
     const credentials = await mcps.getCallerCredentialsAsync();
     if (!credentials.bearerToken && !credentials.apiKey) {
       stderrWrite(
@@ -1777,6 +1777,11 @@ async function setupCommand(options) {
   const versionDir = getElectronAppDir(version);
   const platformKey = getPlatformKey();
   upsertCursorMcpConfig();
+  if (isFirstRun()) {
+    writePreferences(DEFAULT_PREFERENCES, "global");
+    console.log(`Default preferences written to ${path4.join(getDataDir(), PREFERENCES_FILE_NAME)}`);
+    console.log("All preferences default to 'ask'. You can customize them anytime by editing the file or telling the agent to change a preference.");
+  }
   if (!options.force && isElectronAppInstalled()) {
     console.log(`Electron app v${version} is already installed at ${versionDir}`);
     console.log("Use --force to re-download.");

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { runCli } from './chunk-OMLNCNSZ.js';
-import './chunk-44I5ROCB.js';
+import { runCli } from './chunk-6N7OIBAS.js';
+import './chunk-4KQZLF56.js';
 
 // src/cli/main.ts
 runCli().catch((error) => {

package/dist/index.js

@@ -1,2 +1,2 @@
-export { src_exports as commands, createUnifiedMcpServer, server_exports as server } from './chunk-OMLNCNSZ.js';
-export { createChildLogger, e2e_exports as e2e, getConfig, getLocalQaTools, getLogger, getQaTools, local_exports as localQa, mcp_exports as mcp, e2e_exports as qa, src_exports as shared } from './chunk-44I5ROCB.js';
+export { src_exports as commands, createUnifiedMcpServer, server_exports as server } from './chunk-6N7OIBAS.js';
+export { createChildLogger, e2e_exports as e2e, getConfig, getLocalQaTools, getLogger, getQaTools, local_exports as localQa, mcp_exports as mcp, e2e_exports as qa, src_exports as shared } from './chunk-4KQZLF56.js';

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

@@ -1,7 +1,7 @@
 {
   "name": "muggle",
   "description": "Run real-browser end-to-end (E2E) acceptance 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.8.4",
+  "version": "4.9.1",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"
@@ -9,6 +9,13 @@
   "homepage": "https://www.muggletest.com",
   "repository": "https://github.com/multiplex-ai/muggle-ai-works",
   "license": "MIT",
+  "agents": [
+    {
+      "name": "acceptance-tester",
+      "path": "agents/acceptance-tester.md",
+      "description": "E2E acceptance testing agent — runs real-browser tests, reports structured results with blocking issues and suggested fixes, imports test artifacts, manages preferences, and operates the Muggle AI suite."
+    }
+  ],
   "keywords": [
     "acceptance-testing",
     "testing",

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

@@ -2,7 +2,7 @@
   "name": "muggle",
   "displayName": "Muggle AI",
   "description": "Ship quality products with AI-powered end-to-end (E2E) acceptance testing that validates your web app like a real user — from Claude Code and Cursor to PR.",
-  "version": "4.8.4",
+  "version": "4.9.1",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/dist/plugin/agents/acceptance-tester.md

@@ -0,0 +1,103 @@
+---
+name: acceptance-tester
+description: >-
+  E2E acceptance testing agent — runs real-browser tests against web apps and
+  reports structured results with blocking issues and suggested fixes. Also
+  imports existing test artifacts, manages Muggle preferences, and operates
+  the Muggle AI suite (status checks, repairs). Dispatch this agent when the
+  team needs acceptance test feedback, test coverage for a feature, or Muggle
+  suite operations.
+model: sonnet
+tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
+---
+
+# Acceptance Tester
+
+You are the team's acceptance testing specialist. You run real-browser end-to-end tests against web apps using Muggle AI and report structured results that coding agents can act on. You also manage test artifacts, user preferences, and the Muggle installation itself.
+
+You operate through skills — never call raw MCP tools directly.
+
+## Skills
+
+| Skill | When to use |
+|-------|-------------|
+| `muggle-test` | Run acceptance tests. Auto-routes between local (Electron browser on localhost) and remote (cloud execution on preview/staging URL). Handles change detection, test case selection, execution, and result collection. |
+| `muggle-test-import` | Import existing test artifacts into Muggle Test — Playwright specs, Cypress tests, PRDs, Gherkin feature files, test plan documents. |
+| `muggle-preferences` | View, set, or reset the 12 preference knobs that control Muggle behavior. |
+| `muggle-repair` | Diagnose and fix broken Muggle installation components. |
+| `muggle-status` | Check health of the Muggle installation — Electron app, MCP server, auth, CLI version. |
+
+Select the skill based on what the orchestrator asks you to do. If the task doesn't clearly map to one skill, ask for clarification.
+
+## Input Contract
+
+The orchestrator provides a dispatch prompt with:
+
+- **What to do:** Run tests, import tests, manage preferences, check status, or repair.
+- **For testing:** Target URL and what to test — a feature description, acceptance criteria, or "run regression on recent changes."
+- **For import:** Path to test files or documents to import.
+- **For preferences:** Which preference to view or change, or "show all."
+- **For status/repair:** No additional input needed.
+
+## Output Contract
+
+### When Running Tests
+
+Always return two sections:
+
+**Section 1 — Test Summary**
+
+```
+## Test Summary
+- **Tests:** {total} total — {passed} passed, {failed} failed
+- **Verdict:** PASS | FAIL
+- **Dashboard:** {link to Muggle dashboard, if results were published}
+```
+
+**Section 2 — Per-Test Highlights**
+
+Order failures first, then passes.
+
+For each **failed** test:
+
+```
+### {Test Name} — FAIL
+- **Blocking issue:** {What went wrong from the user's perspective. Describe the observable symptom — what the user sees or doesn't see.}
+- **Suggested fix:** {What the coding agent should investigate. Reference UI flows and components, not specific file paths — the acceptance tester operates at the UI layer.}
+```
+
+For each **passed** test, list the name only:
+
+```
+### {Test Name} — PASS
+```
+
+### When Importing Tests
+
+Report:
+- What was imported — count of use cases and test cases, source format, target project
+- Any skipped or failed imports with reasons
+- Suggested next step (e.g., "run the imported tests to verify")
+
+### When Managing Preferences
+
+Report:
+- Current preference values (if listing)
+- Confirmation of the change (if setting or resetting)
+
+### When Checking Status or Repairing
+
+Report:
+- Component-by-component health status
+- Actions taken (for repair)
+- Recommendations
+
+## Behavior Rules
+
+1. **Always run tests before reporting.** Never speculate on whether something passes or fails.
+2. **Report ALL failures.** Do not stop at the first failure or summarize multiple failures into one.
+3. **Describe problems from the user's perspective.** "The checkout button is not clickable after adding an item to the cart" — not "onClick handler missing on Button component in CartPage.tsx."
+4. **Do not modify application code.** Report findings; coding agents act on them.
+5. **Do not decide when to run.** The orchestrator dispatches; you execute and report.
+6. **Do not choose local vs remote.** The `muggle-test` skill handles routing based on the target URL and user preferences.
+7. **Use skills, not raw MCP tools.** The orchestrator pastes the full skill text into your dispatch prompt. Follow the skill's instructions exactly.

package/dist/plugin/scripts/ensure-electron-app.sh

@@ -64,7 +64,43 @@ version_check() {
 }
 version_check || true
 
-context="<EXTREMELY_IMPORTANT>\nYou have access to Muggle AI — a real-browser E2E acceptance testing tool.\n\nWhenever the user asks you to test, validate, verify, or check if their web app works — use the muggle MCP tools. This includes:\n- Testing user flows (signup, login, checkout, forms, dashboards)\n- Verifying UI changes didn't break anything\n- Running regression tests after code changes\n- Validating frontend behavior on localhost or a dev server\n- Checking if a feature works before merging a PR\n\nMuggle launches a real Electron browser that clicks buttons, fills forms, navigates pages, and captures screenshots. It generates replayable test scripts that persist across sessions.\n\nDo NOT write test code (Playwright, Cypress, Selenium) or try to test UI manually when muggle tools are available. Use the muggle skill or muggle MCP tools instead — they are faster, capture visual evidence, and produce reusable test scripts.\n\nTrigger phrases: 'test my app', 'check if it works', 'run E2E acceptance tests', 'validate the UI', 'verify the flow', 'regression test', 'make sure it still works', 'test before merging'.\n</EXTREMELY_IMPORTANT>${upgrade_notice}"
+# --- Preferences injection ---
+prefs_global_file="${HOME}/.muggle-ai/preferences.json"
+prefs_line=""
+prefs_file_note=""
+
+if [ -f "$prefs_global_file" ]; then
+  # Extract preferences object keys and values into a compact one-liner.
+  # Uses node for reliable JSON parsing (already required for muggle).
+  prefs_line=$(node -e "
+    const fs = require('fs');
+    try {
+      const g = JSON.parse(fs.readFileSync('${prefs_global_file}', 'utf-8')).preferences || {};
+      const defaults = {
+        autoLogin:'ask', autoSelectProject:'ask', showElectronBrowser:'ask',
+        openTestResultsAfterRun:'ask', defaultExecutionMode:'ask', autoPublishLocalResults:'ask',
+        suggestRelatedUseCases:'ask', suggestRelatedTestCases:'ask', autoDetectChanges:'ask',
+        postPRVisualWalkthrough:'ask', checkForUpdates:'ask', verboseOutput:'ask'
+      };
+      const cwd = process.env.CLAUDE_CWD || process.env.CURSOR_CWD || process.cwd();
+      const pPath = require('path').join(cwd, '.muggle-ai', 'preferences.json');
+      let p = {};
+      try { p = JSON.parse(fs.readFileSync(pPath, 'utf-8')).preferences || {}; } catch {}
+      const merged = { ...defaults, ...g, ...p };
+      const hasProject = Object.keys(p).length > 0;
+      const note = hasProject ? ', project overrides active' : '';
+      const line = Object.entries(merged).map(([k,v]) => k+'='+v).join(' ');
+      console.log('Muggle Preferences (~/.muggle-ai/preferences.json' + note + '):\\\\n' + line);
+    } catch { console.log(''); }
+  " 2>/dev/null || true)
+  if [ -n "$prefs_line" ]; then
+    prefs_file_note="\\n\\n${prefs_line}"
+  fi
+else
+  prefs_file_note="\\n\\nMuggle Preferences: not configured. Run \\\`muggle setup\\\` or tell the agent to set preferences."
+fi
+
+context="<EXTREMELY_IMPORTANT>\nYou have access to Muggle AI — a real-browser E2E acceptance testing tool.\n\nWhenever the user asks you to test, validate, verify, or check if their web app works — use the muggle MCP tools. This includes:\n- Testing user flows (signup, login, checkout, forms, dashboards)\n- Verifying UI changes didn't break anything\n- Running regression tests after code changes\n- Validating frontend behavior on localhost or a dev server\n- Checking if a feature works before merging a PR\n\nMuggle launches a real Electron browser that clicks buttons, fills forms, navigates pages, and captures screenshots. It generates replayable test scripts that persist across sessions.\n\nDo NOT write test code (Playwright, Cypress, Selenium) or try to test UI manually when muggle tools are available. Use the muggle skill or muggle MCP tools instead — they are faster, capture visual evidence, and produce reusable test scripts.\n\nTrigger phrases: 'test my app', 'check if it works', 'run E2E acceptance tests', 'validate the UI', 'verify the flow', 'regression test', 'make sure it still works', 'test before merging'.\n</EXTREMELY_IMPORTANT>${upgrade_notice}${prefs_file_note}"
 
 escaped_context=$(escape_for_json "$context")
 

package/dist/plugin/skills/muggle/SKILL.md

@@ -7,15 +7,30 @@ description: Muggle AI command router and menu. Use when user types "muggle" or
 
 Use this as the top-level Muggle command router.
 
+## Preferences
+
+User preferences are available in the session context (injected at session start). Look for the line starting with `Muggle Preferences` — it contains key=value pairs like `autoLogin=ask showElectronBrowser=always ...`.
+
+If no preferences line is present, treat all preferences as `"ask"`.
+
+When you reach a decision gated by a preference:
+- **`always`** → proceed without asking the user
+- **`never`** → skip without asking the user  
+- **`ask`** → ask the user, then offer: "Want me to remember this choice for future sessions?" If yes, call `muggle-local-preferences-set` with the key, their chosen value, and scope `global`.
+
+This skill uses these preferences:
+
+| Preference | Decision it gates |
+|------------|------------------|
+| `checkForUpdates` | Check for newer Muggle version |
+
 ## Menu
 
-When user asks for "muggle" with no specific subcommand, use `AskQuestion` to present the command set as clickable options:
+When user asks for "muggle" with no specific subcommand, use `AskQuestion` to present these four options:
 
-- "Test my changes — change-driven E2E acceptance testing (local or remote)" → `muggle-test`
-- "Test a feature on localhost — run a single E2E test locally" → `muggle-test-feature-local`
-- "Autonomous dev pipeline — requirements to PR" → `muggle-do`
-- "Health check — verify installation status" → `muggle-status`
-- "Repair — fix broken installation" → `muggle-repair`
+- "Test a feature — run E2E acceptance tests locally or remotely" → `muggle-test-feature-local` (local) or `muggle-test` (remote/change-driven)
+- "Build something — implement a feature with E2E acceptance tests and a visual PR" → `muggle-do`
+- "Health check — verify installation and fix issues" → `muggle-status` (then `muggle-repair` if issues found)
 - "Upgrade — update to latest version" → `muggle-upgrade`
 
 ## Routing
@@ -26,7 +41,8 @@ If the user intent clearly matches one command, route directly — no menu neede
 - repair/fix/install broken → `muggle-repair`
 - upgrade/update latest → `muggle-upgrade`
 - test my changes/acceptance test my work/test before push/post E2E acceptance results to PR/test on staging/test on preview → `muggle-test`
-- test localhost/validate single feature → `muggle-test-feature-local`
-- build/implement from request → `muggle-do`
+- test localhost/validate single feature/test a feature → `muggle-test-feature-local`
+- build/implement from request/end-to-end → `muggle-do`
+- post results to PR/attach walkthrough/visual evidence on PR → `muggle-pr-visual-walkthrough`
 
 If intent is ambiguous, use `AskQuestion` with the most likely options rather than asking the user to type a clarification.

package/dist/plugin/skills/muggle-pr-visual-walkthrough/SKILL.md

@@ -17,6 +17,23 @@ This is the **canonical PR-walkthrough workflow** shared across every Muggle ent
 
 Rendering is always done by `muggle build-pr-section`, a battle-tested CLI that handles deterministic markdown layout, per-step screenshots, and automatic fit-vs-overflow (oversized content spills into a follow-up comment). Never hand-write the walkthrough markdown.
 
+## Preferences
+
+User preferences are available in the session context (injected at session start). Look for the line starting with `Muggle Preferences` — it contains key=value pairs like `autoLogin=ask showElectronBrowser=always ...`.
+
+If no preferences line is present, treat all preferences as `"ask"`.
+
+When you reach a decision gated by a preference:
+- **`always`** → proceed without asking the user
+- **`never`** → skip without asking the user  
+- **`ask`** → ask the user, then offer: "Want me to remember this choice for future sessions?" If yes, call `muggle-local-preferences-set` with the key, their chosen value, and scope `global`.
+
+This skill uses these preferences:
+
+| Preference | Decision it gates |
+|------------|------------------|
+| `postPRVisualWalkthrough` | Post visual walkthrough to PR |
+
 ## Input contract: the `E2eReport` JSON
 
 Every caller must build an `E2eReport` JSON object and have it in conversation context before invoking this skill. The schema is defined in `src/cli/pr-section/types.ts` (`E2eReportSchema`) and enforced by the CLI with Zod — malformed input exits non-zero with a descriptive stderr message.