@muggleai/works 4.8.4 → 4.9.1

package/dist/release-manifest.json

@@ -1,7 +1,7 @@
 {
-  "release": "4.8.4",
-  "buildId": "run-24-1",
-  "commitSha": "1ece6c6d97e2a4c8a56177baaf77c78e00ef2fe5",
-  "buildTime": "2026-04-16T21:42:52Z",
+  "release": "4.9.1",
+  "buildId": "run-26-1",
+  "commitSha": "cffcf26eaf2b00b3b1e55dcd509db7b9d8854a0d",
+  "buildTime": "2026-04-19T08:47:53Z",
   "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.4",
+    "version": "4.9.1",
     "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",

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.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/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/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

@@ -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/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`.

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.

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

@@ -22,6 +22,26 @@ The local URL only changes where the browser opens; it does not change the remot
 - **Selections** (project, use case, test case, script): Use `AskQuestion` with labeled options the user can click.
 - **Free-text inputs** (URLs, descriptions): Only use plain text prompts when there is no finite set of options. Even then, offer a detected/default value when possible.
 
+## 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 |
+| `showElectronBrowser` | Show Electron browser window during local E2E tests |
+| `openTestResultsAfterRun` | Open results page on Muggle dashboard after run |
+
 ## Workflow
 
 ### 1. Auth
@@ -65,9 +85,20 @@ Prompt for projects: "Pick the project to group this test into:"
   2. `muggle-remote-use-case-create-from-prompts` with `projectId` and `instructions: ["<the user's natural-language instruction>"]` — persist. Use the created use case id and continue to test-case selection.
 - **Test case — Create new test case** (requires a chosen `useCaseId`): User provides an instruction describing what to test.
   1. `muggle-remote-test-case-generate-from-prompt` with `projectId`, `useCaseId`, `instruction` — **preview only** (server test-case prompt preview); show the returned draft(s); get confirmation via `AskQuestion`.
-  2. Persist the accepted draft with `muggle-remote-test-case-create`, mapping preview fields into the required properties (`title`, `description`, `goal`, `expectedResult`, `url`, etc.). Then continue from **section 4** with that `testCaseId`.
+  2. Persist the accepted draft with `muggle-remote-test-case-create`, mapping preview fields into the required properties (`title`, `description`, `goal`, `expectedResult`, `url`, etc.). Then continue from **section 5** with that `testCaseId`.
+
+### 3. Ensure Local Services Are Ready
+
+Before detecting the local URL, verify that the services the user needs are actually running. Use the `muggle:muggle-test-prepare` integration contract:
+
+1. Check if `/tmp/muggle-test-prepare.json` exists.
+2. If it exists, verify tracked PIDs are alive with `kill -0`.
+3. If all live → services are ready, proceed to Step 4 (Local URL).
+4. If the file is missing or has stale PIDs → invoke the `muggle:muggle-test-prepare` skill via the `Skill` tool to get services started. Once it completes, proceed to Step 4.
+
+This step is especially important when the user's app depends on sibling services (a backend API, an auth service, etc.) that may not be running yet. The prepare skill handles discovery, startup, and cleanup so this skill doesn't have to.
 
-### 3. Local URL
+### 4. Local URL
 
 Try to auto-detect the dev server URL by checking running terminals or common ports (e.g., `lsof -iTCP -sTCP:LISTEN -nP | grep -E ':(3000|3001|4200|5173|8080)'`). If a likely URL is found, present it as a clickable default via `AskQuestion`:
 - Option 1: "http://localhost:3000" (or whatever was detected)
@@ -77,14 +108,14 @@ If nothing detected, ask as free text: "Your local app should be running. What's
 
 Remind them: local URL is only the execution target, not tied to cloud project config.
 
-### 4. Existing scripts vs new generation
+### 5. Existing scripts vs new generation
 
 `muggle-remote-test-script-list` with `testCaseId`.
 
 - **If any replayable/succeeded scripts exist:** use `AskQuestion` to present them as clickable options. Show: name, created/updated, step count per option. Include **"Generate new script"** as the last option.
 - **If none:** go straight to generation (no need to ask replay vs generate).
 
-### 5. Load data for the chosen path
+### 6. Load data for the chosen path
 
 **Determine `freshSession`**
 
@@ -122,39 +153,39 @@ The MCP client often uses a **default wait of 300000 ms (5 minutes)** for `muggl
 - **`Electron execution timed out after 300000ms`:** Orchestration wait too short — see **`timeoutMs`** above.
 - **Exit code 26** (and messages like **LLM failed to generate / replay action script**): Often corresponds to a completed exploration whose **outcome was goal not achievable** (`goal_not_achievable`, summary with `halt`) — e.g. verifying "view script after a successful run" when **no run or script exists yet** in the UI. Use `muggle-local-run-result-get` and read the **summary / structured summary**; do not assume an Electron crash. **Fix:** choose a **project that already has** completed runs and scripts, or **change the test case** so preconditions match what localhost can satisfy (e.g. include steps to create and run a test first, or assert only empty-state UI when no runs exist).
 
-### 6. Execute (no approval prompt)
+### 7. Execute (no approval prompt)
 
 Call `muggle-local-execute-test-generation` or `muggle-local-execute-replay` directly. **Do not** ask the user to re-approve the Electron launch — the user choosing this skill in the first place is the approval. The browser defaults to visible; only pass `showUi: false` if the user explicitly asked for headless.
 
-### 7. After successful generation only
+### 8. After successful generation only
 
 - `muggle-local-publish-test-script`
 - Open returned `viewUrl` for the user (`open "<viewUrl>"` on macOS or OS equivalent).
 
-### 8. Report
+### 9. Report
 
 - `muggle-local-run-result-get` with the run id from execute.
 - Include: status, duration, pass/fail summary, per-step summary, artifact/screenshot paths, errors if failed, and script view URL when publishing ran.
 
-### 9. Offer to post a visual walkthrough to the PR
+### 10. Offer to post a visual walkthrough to the PR
 
-After reporting results, gather the required input and hand off to the shared **`muggle-pr-visual-walkthrough`** skill, which renders the walkthrough via `muggle build-pr-section` and posts it to the current branch's open PR.
+After reporting results, gather the required input and hand off to the shared **`muggle:muggle-pr-visual-walkthrough`** skill, which renders the walkthrough via `muggle build-pr-section` and posts it to the current branch's open PR.
 
-#### 9a: Gather per-step screenshots
+#### 10a: Gather per-step screenshots
 
-The shared skill takes an **`E2eReport` JSON** that includes per-step screenshot URLs. After step 7 has called `muggle-local-publish-test-script` and you have the `testScriptId`:
+The shared skill takes an **`E2eReport` JSON** that includes per-step screenshot URLs. After step 8 has called `muggle-local-publish-test-script` and you have the `testScriptId`:
 
 1. Call `muggle-remote-test-script-get` with the `testScriptId`.
 2. Extract per step: `steps[].operation.action` and `steps[].operation.screenshotUrl`.
 3. Build the `steps` array: `[{ stepIndex: 0, action: "...", screenshotUrl: "..." }, ...]`.
-4. If the run failed, capture `failureStepIndex`, `error`, and the local `artifactsDir` from the run result in step 8.
+4. If the run failed, capture `failureStepIndex`, `error`, and the local `artifactsDir` from the run result in step 9.
 5. Populate `description` (test case title/description) and `useCaseName` (parent use case title) on the report entry — optional but strongly recommended; they drive the grouped overview and the per-test collapsible headers. Prefer values already in your conversation context from earlier steps (e.g. the test case you just created or selected, or the use case you confirmed); only call `muggle-remote-test-case-get` / `muggle-remote-use-case-get` for anything you don't already have.
 
 Assemble the `E2eReport`:
 
 ```json
 {
-  "projectId": "<projectId from step 2>",
+  "projectId": "<projectId from step 2 (Targets)>",
   "tests": [
     {
       "name": "<test case title>",
@@ -171,9 +202,9 @@ Assemble the `E2eReport`:
 }
 ```
 
-See the `muggle-pr-visual-walkthrough` skill for the full schema including the failed-test shape.
+See the `muggle:muggle-pr-visual-walkthrough` skill for the full schema including the failed-test shape.
 
-#### 9b: Ask the user
+#### 10b: Ask the user
 
 Use `AskQuestion`:
 
@@ -182,11 +213,11 @@ Use `AskQuestion`:
 - Option 1: "Yes, post to PR"
 - Option 2: "Skip"
 
-#### 9c: Invoke the shared skill in Mode A
+#### 10c: Invoke the shared skill in Mode A
 
-If the user chooses "Yes, post to PR", invoke the `muggle-pr-visual-walkthrough` skill via the `Skill` tool. With the `E2eReport` in context, the skill renders the markdown block via the CLI, finds the PR via `gh pr view`, posts `body` as a comment, posts the overflow `comment` only if the CLI emitted one, and confirms the PR URL to the user.
+If the user chooses "Yes, post to PR", invoke the `muggle:muggle-pr-visual-walkthrough` skill via the `Skill` tool. With the `E2eReport` in context, the skill renders the markdown block via the CLI, finds the PR via `gh pr view`, posts `body` as a comment, posts the overflow `comment` only if the CLI emitted one, and confirms the PR URL to the user.
 
-Always use **Mode A** (post to existing PR) from this skill. Never hand-write the walkthrough markdown or call `gh pr comment` directly — delegate to `muggle-pr-visual-walkthrough`.
+Always use **Mode A** (post to existing PR) from this skill. Never hand-write the walkthrough markdown or call `gh pr comment` directly — delegate to `muggle:muggle-pr-visual-walkthrough`.
 
 ## Non-negotiables
 
@@ -197,4 +228,4 @@ Always use **Mode A** (post to existing PR) from this skill. Never hand-write th
 - Replay: never hand-built or simplified `actionScript` — only from `muggle-remote-action-script-get`.
 - Use `AskQuestion` for every selection — project, use case, test case, script. Never ask the user to type a number.
 - Project, use case, and test case selection lists must always include "Create new ...". Include "Show full list" whenever the API returned at least one row for that step; omit "Show full list" when the list is empty (offer "Create new ..." only). For creates, use preview tools (`muggle-remote-use-case-prompt-preview`, `muggle-remote-test-case-generate-from-prompt`) before persisting.
-- PR posting is always optional and always delegated to the `muggle-pr-visual-walkthrough` skill — never inline the walkthrough markdown or call `gh pr comment` directly from this skill.
+- PR posting is always optional and always delegated to the `muggle:muggle-pr-visual-walkthrough` skill — never inline the walkthrough markdown or call `gh pr comment` directly from this skill.

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

@@ -18,6 +18,26 @@ This skill migrates existing test artifacts into Muggle Test. It reads your sour
 structures them into use cases and test cases, gets your approval, then creates everything
 in a Muggle project via the API.
 
+## 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 |
+| `suggestRelatedUseCases` | Suggest related use cases after import |
+| `suggestRelatedTestCases` | Suggest related test cases after import |
+
 ## Concepts
 
 - **Use case**: A high-level feature or user workflow (e.g., "User Registration", "Checkout Flow")