@muggleai/works 4.8.3 → 4.9.0

package/dist/plugin/skills/muggle-test-regenerate-missing/SKILL.md

@@ -9,6 +9,24 @@ A bulk maintenance skill for Muggle AI projects. It finds every test case in a p
 
 Execution is **remote only** — Muggle's cloud generates the scripts in parallel against the project URL. The user's machine is not involved beyond making API calls.
 
+## 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 |
+|------------|------------------|
+| `autoLogin` | Reuse saved credentials when auth is required |
+| `autoSelectProject` | Reuse last-used Muggle project for this repo |
+
 ## Concept: what counts as "no active script"
 
 In the Muggle data model, a test case carries a status that reflects whether it has a usable script attached:

package/dist/release-manifest.json

@@ -1,7 +1,7 @@
 {
-  "release": "4.8.3",
-  "buildId": "run-23-1",
-  "commitSha": "db2ab1ae29f982b0a12db6dbd2a334cc8016f016",
-  "buildTime": "2026-04-14T23:24:16Z",
+  "release": "4.9.0",
+  "buildId": "run-25-1",
+  "commitSha": "5562e835de433b7edc6cfe4b2087cb9a3ad6a696",
+  "buildTime": "2026-04-19T08:20:59Z",
   "serviceName": "muggle-ai-works-mcp"
 }

package/dist/src-7GB7WIFT.js

@@ -0,0 +1 @@
+export { DEFAULT_PREFERENCES, PREFERENCES_FILE_NAME, PREFERENCES_PROJECT_DIR_NAME, PREFERENCES_SCHEMA, PREFERENCES_VERSION, PreferenceKey, PreferenceValue, buildElectronAppChecksumsUrl, buildElectronAppReleaseAssetUrl, buildElectronAppReleaseTag, calculateFileChecksum, createApiKeyWithToken, createChildLogger, deleteApiKeyData, deleteCredentials, e2e_exports as e2e, formatPreferencesOneLiner, getApiKey, getApiKeyFilePath, getAuthService, getBundledElectronAppVersion, getCallerCredentials, getCallerCredentialsAsync, getChecksumForPlatform, getConfig, getCredentialsFilePath, getDataDir, getDownloadBaseUrl, getElectronAppChecksums, getElectronAppDir, getElectronAppVersion, getElectronAppVersionSource, getLocalQaTools, getLogger, getPlatformKey, getQaTools, getValidApiKeyData, getValidCredentials, hasApiKey, isElectronAppInstalled, isFirstRun, loadApiKeyData, loadCredentials, local_exports as localQa, mcp_exports as mcp, openBrowserUrl, performLogin, performLogout, pollDeviceCode, e2e_exports as qa, readGlobalPreferences, readProjectPreferences, resetConfig, resetLogger, resetPreference, resolvePreferences, saveApiKey, saveApiKeyData, saveCredentials, startDeviceCodeFlow, toolRequiresAuth, validatePreference, verifyFileChecksum, writePreferences } from './chunk-4KQZLF56.js';

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@muggleai/works",
     "mcpName": "io.github.multiplex-ai/muggle",
-    "version": "4.8.3",
+    "version": "4.9.0",
     "description": "Ship quality products with AI-powered E2E acceptance testing that validates your web app like a real user — from Claude Code and Cursor to PR.",
     "type": "module",
     "main": "dist/index.js",
@@ -41,14 +41,14 @@
         "test:watch": "vitest"
     },
     "muggleConfig": {
-        "electronAppVersion": "1.0.60",
+        "electronAppVersion": "1.0.61",
         "downloadBaseUrl": "https://github.com/multiplex-ai/muggle-ai-works/releases/download",
         "runtimeTargetDefault": "production",
         "checksums": {
-            "darwin-arm64": "a1e084b32ebc28fa823bcc9161959bd3618f0c5e45f41f946b5efa9192b8b15b",
-            "darwin-x64": "0605176a152b12149015b500b5d04dfaec06a5f3ed4d615d5442437cbaa2ba3a",
-            "win32-x64": "f6c9a243894720420229d37ff8915827e56c5aa2f21dd887a0f476d952698ad8",
-            "linux-x64": "4404163f56b664c1d8c040435ef981d1ff6583e2ba2e4b38ea4375afecd1c204"
+            "darwin-arm64": "987d2957052adb3b1db9deef4febcf4e0c7649ee17aa5cf2822a048c29c28ee8",
+            "darwin-x64": "a713179a51c149a97958fa1c3411789161780c2267b083c0b974e59a8159d82a",
+            "win32-x64": "bc4ddf090239a77f34a34bc42c4849ae1e0a0e797052affe4346b0733e8ea216",
+            "linux-x64": "f64357e258a28eb080df65dd84439fcc72a840c3de5de8f51cba92184dcacdad"
         }
     },
     "dependencies": {

package/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.3",
+  "version": "4.9.0",
   "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/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.3",
+  "version": "4.9.0",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/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/plugin/scripts/ensure-electron-app.sh

@@ -23,7 +23,84 @@ escape_for_json() {
     printf '%s' "$s"
 }
 
-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>"
+# --- Version check (best-effort, 3-day cache) ---
+# Writes "installed|latest" to a cache file. On a cache hit we skip the npm
+# round-trip entirely. Any failure leaves upgrade_notice empty and we stay silent.
+upgrade_notice=""
+version_check() {
+    local cache_dir="${HOME}/.cache/muggle"
+    local cache_file="${cache_dir}/version-check"
+    local ttl=$((3 * 24 * 60 * 60))
+    local now installed latest cached mtime age
+    now=$(date +%s)
+
+    if [ -f "$cache_file" ]; then
+        mtime=$(stat -f %m "$cache_file" 2>/dev/null || stat -c %Y "$cache_file" 2>/dev/null || echo 0)
+        age=$((now - mtime))
+        if [ "$age" -lt "$ttl" ]; then
+            cached=$(cat "$cache_file" 2>/dev/null || true)
+            installed="${cached%%|*}"
+            latest="${cached##*|}"
+        fi
+    fi
+
+    if [ -z "${installed:-}" ] || [ -z "${latest:-}" ]; then
+        installed=$(muggle --version 2>/dev/null | tr -d '[:space:]' || true)
+        latest=$(npm view @muggleai/works version 2>/dev/null | tr -d '[:space:]' || true)
+        if [ -n "$installed" ] && [ -n "$latest" ]; then
+            mkdir -p "$cache_dir" 2>/dev/null || true
+            printf '%s|%s' "$installed" "$latest" > "$cache_file" 2>/dev/null || true
+        fi
+    fi
+
+    if [ -n "${installed:-}" ] && [ -n "${latest:-}" ] && [ "$installed" != "$latest" ]; then
+        # Only nudge when latest is strictly greater (sort -V puts latest last).
+        local newest
+        newest=$(printf '%s\n%s\n' "$installed" "$latest" | sort -V | tail -n1)
+        if [ "$newest" = "$latest" ]; then
+            upgrade_notice="\n\nA newer @muggleai/works is available (${installed} → ${latest}). Tell the user to run \`/muggle:muggle-upgrade\` to update."
+        fi
+    fi
+}
+version_check || true
+
+# --- 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/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/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.

package/plugin/skills/muggle-preferences/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: muggle-preferences
+description: >-
+  View, set, or reset Muggle AI preferences that control testing behavior.
+  Use when user asks to see preferences, change a setting, configure Muggle
+  defaults, or manage muggle config. Triggers on: 'muggle preferences',
+  'show muggle settings', 'change muggle preference', 'set autoLogin to
+  always', 'muggle config', 'reset muggle preferences', 'show my muggle
+  settings', 'configure muggle'.
+---
+
+# Muggle Preferences
+
+View, set, or reset the preference knobs that control Muggle AI behavior.
+
+## Operations
+
+Parse the user's request to determine which operation to perform:
+
+- **List** — user wants to see current values (default when no specific change requested)
+- **Set** — user wants to change a specific preference
+- **Reset** — user wants to restore a preference (or all preferences) to defaults
+
+## List
+
+1. Read preferences from session context. 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"` (the default).
+
+2. Present all 12 preferences in a table:
+
+```
+Muggle AI — Preferences
+
+| Preference               | Value  | Description                                              |
+|--------------------------|--------|----------------------------------------------------------|
+| autoLogin                | ask    | Reuse saved credentials without prompting                |
+| autoSelectProject        | ask    | Reuse last-used project for this repo                    |
+| showElectronBrowser      | ask    | Show browser window during local tests                   |
+| openTestResultsAfterRun  | ask    | Open results page on dashboard after local test          |
+| defaultExecutionMode     | ask    | Default to local or remote test execution                |
+| autoPublishLocalResults  | ask    | Upload local results to Muggle cloud                     |
+| suggestRelatedUseCases   | ask    | Suggest related use cases after creating/running one     |
+| suggestRelatedTestCases  | ask    | Suggest related test cases after creating/running one    |
+| autoDetectChanges        | ask    | Scan local git changes and map to affected test cases    |
+| postPRVisualWalkthrough  | ask    | Post visual walkthrough with screenshots to PR           |
+| checkForUpdates          | ask    | Check for newer Muggle version at session start          |
+| verboseOutput            | ask    | Show detailed progress logs during execution             |
+
+Values: always (proceed without asking) · ask (prompt each time) · never (skip without asking)
+Scope:  global (~/.muggle-ai/) or project (.muggle-ai/ in repo root)
+```
+
+## Set
+
+1. Parse the requested key and value from the user's message.
+
+2. Validate the key is one of: `autoLogin`, `autoSelectProject`, `showElectronBrowser`, `openTestResultsAfterRun`, `defaultExecutionMode`, `autoPublishLocalResults`, `suggestRelatedUseCases`, `suggestRelatedTestCases`, `autoDetectChanges`, `postPRVisualWalkthrough`, `checkForUpdates`, `verboseOutput`.
+
+   If the key is ambiguous or not recognized, show the full list and ask the user to clarify.
+
+3. Validate the value is one of: `always`, `ask`, `never`.
+
+4. Determine scope:
+   - Default to `global`.
+   - If the user says "for this project", "project-level", or "just this repo", use `project` scope and pass `cwd` as the current working directory.
+
+5. Call `muggle-local-preferences-set` with:
+   - `key`: The preference key
+   - `value`: The chosen value
+   - `scope`: `"global"` or `"project"`
+   - `cwd`: Current working directory (required when scope is `"project"`)
+
+6. Confirm: `Set {key} to {value} ({scope}).`
+
+## Reset
+
+1. If the user asks to reset a **specific key**: call `muggle-local-preferences-set` with `value: "ask"` for that key.
+
+2. If the user asks to reset **all preferences**: call `muggle-local-preferences-set` for each of the 12 keys with `value: "ask"`.
+
+3. Confirm what was reset.

package/plugin/skills/muggle-status/SKILL.md

@@ -7,6 +7,23 @@ description: Check health of the Muggle AI installation. Use when user types mug
 
 Run a full health check and report results.
 
+## 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 |
+
 ## Checks
 
 1. **Electron app** — read `~/.muggle-ai/electron-app/` to find the installed version directory. Read `.install-metadata.json` to get version and checksum. Verify the binary exists at the expected path. On macOS, check code signing with `spctl --assess --verbose`.
@@ -15,6 +32,8 @@ Run a full health check and report results.
 
 3. **Authentication** — call `muggle-remote-auth-status`. Report whether credentials are valid and when they expire.
 
+4. **CLI version** — capture installed (`muggle --version`) and latest (`npm view @muggleai/works version`). Compare with `sort -V`; flag as out-of-date only when latest is strictly greater.
+
 ## Output
 
 ```
@@ -23,8 +42,9 @@ Muggle AI — Status
 Electron app   [pass/fail]  version, binary status
 MCP server     [pass/fail]  responsive, auth state
 Authentication [pass/fail]  user, expiry
+CLI version    [pass/warn]  installed → latest
 
 [All systems operational / Issues found — run /muggle:muggle-repair to fix.]
 ```
 
-Use pass/fail indicators for each check. If any check fails, tell the user to run `/muggle:muggle-repair`.
+Use pass/fail indicators for each check. If any check fails, tell the user to run `/muggle:muggle-repair`. If the CLI version check warns (installed < latest), tell the user to run `/muggle:muggle-upgrade`.

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

@@ -32,6 +32,28 @@ Every test case verifies exactly **one** user-observable behavior. Never bundle
 
 **Never skip the generate→review cycle.** Even when you are 100% confident about the right shape, always present the generated test cases to the user before calling `muggle-remote-test-case-create`. "I'll skip the generate→review cycle and create directly" is a sign you're about to get it wrong.
 
+## 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 |
+|------------|------------------|
+| `autoLogin` | Reuse saved credentials when auth is required |
+| `autoSelectProject` | Reuse last-used Muggle project for this repo |
+| `autoDetectChanges` | Scan local git changes and map to affected test cases |
+| `defaultExecutionMode` | Default to local or remote test execution |
+| `autoPublishLocalResults` | Upload local results to Muggle cloud after run |
+| `postPRVisualWalkthrough` | Post visual walkthrough to PR after results are available |
+
 ## Step 1: Confirm Scope of Work (Always First)
 
 Parse the user's query and explicitly confirm their expectation. There are exactly two modes:
@@ -418,3 +440,7 @@ This skill always uses **Mode A** (post to an existing PR); `muggle-do` is the o
 - **Always publish before opening browser** — the dashboard needs the published data to show results
 - **Delegate PR posting to `muggle-pr-visual-walkthrough`** — never inline the walkthrough markdown or call `gh pr comment` directly from this skill; ask the user and hand off
 - **Can be invoked at any state** — if the user already has a project or use cases set up, skip to the relevant step rather than re-doing everything
+
+## Agent Dispatch
+
+When used in a multi-agent team (e.g., muggle-ai-teams), this skill is available through the **acceptance-tester** agent at `plugin/agents/acceptance-tester.md`. Orchestrators can dispatch it via `Agent()` instead of invoking this skill directly. The agent wraps this skill and four others (muggle-test-import, muggle-preferences, muggle-repair, muggle-status) and returns structured test results with blocking issues and suggested fixes for coding agents to act on.