@muggleai/works 4.10.0 → 4.10.1

package/plugin/skills/muggle-preferences/preference-gates/autoSelectLocalHost.md

@@ -0,0 +1,19 @@
+# `autoSelectLocalHost`
+
+Reuse the saved local dev server URL for this repo, or pick one each run. Substitute `{lastHost}` (the URL used in the previous run for this repo — omit the option entirely when no cache exists) and `{suggestedHost}` (auto-detected from running ports, e.g. `http://localhost:3000`).
+
+Cache lives at `<cwd>/.muggle-ai/last-host.json`. The calling skill **always** updates the cache after the user picks/types a URL — independent of Picker 2 — so `Use {lastHost}` reflects the most recent run.
+
+**Picker 1** — header `Local server`, question `"Which local URL should the test target?"`
+- `Use {lastHost}` — `From your last run in this repo.` → reuse cached URL. *Skip this option when no cache exists.*
+- `Use {suggestedHost}` — `Detected from a port that's running.` → use the suggestion
+- `Type a URL` — `Paste any URL.` → calling skill prompts for free-text input
+
+**Picker 2 — overrides shared template.** Fires after the user picks a URL.
+- Header `Remember this URL?`, question `"Always use {chosenHost} for this repo from now on, without asking?"`
+- `Yes, always` (sub: `You can change this later in muggle preferences.`) → `muggle-local-preferences-set` (`autoSelectLocalHost=always`, global). The cache is already up to date.
+- `Just this once` (sub: `I'll ask again next time.`) → don't save the preference. The cache still updates.
+
+**Silent action**
+- `always` (cache used) → `Using saved local URL {lastHost}`
+- `never` → no footer; the picker is the visible step.

package/plugin/skills/muggle-preferences/preference-gates/autoSelectProject.md

@@ -1,7 +1,6 @@
 # `autoSelectProject`
 
-Reuse the cached project for this repo (`<cwd>/.muggle-ai/last-project.json`),
-or pick from the list. Substitute `{projectName}`.
+Reuse the saved project for this repo, or pick from the list. Substitute `{projectName}`.
 
 Picker 1 *is* the project list (rendered by the calling skill — format and
 tail options like "Show full list" / "Create new project" are skill-defined).

package/plugin/skills/muggle-preferences/preference-gates/autoUseWorktree.md

@@ -0,0 +1,11 @@
+# `autoUseWorktree`
+
+Create a worktree for the change, or work in the current checkout.
+
+**Picker 1** — header `Worktree`, question `"Create a git worktree for this change, or work in the current checkout?"`
+- `Create a worktree` — `Isolate the change so your current checkout stays untouched.` → `always`
+- `Use current checkout` — `Edit in place.` → `never`
+
+**Silent action**
+- `always` → `Creating a worktree for this change`
+- `never` → `Working in the current checkout`

package/plugin/skills/muggle-preferences/preference-gates/checkForUpdates.md

@@ -1,10 +1,10 @@
 # `checkForUpdates`
 
-Check npm for a newer Muggle version at session start.
+Check npm for a newer Muggle Test version at session start.
 
-**Picker 1** — header `Update check`, question `"Check npm for a newer Muggle version? Requires a network call."`
-- `Yes, check` — `Quick network call — flags if you're behind.` → `always`
-- `No, skip` — `Skip the check — saves a network call at session start.` → `never`
+**Picker 1** — header `Update check`, question `"Check for a newer Muggle Test version (one quick network call)?"`
+- `Check now` — `Flags if you're behind.` → `always`
+- `Skip check` — `Saves a network call at session start.` → `never`
 
 **Silent action**
 - `always` → `Checked for updates`

package/plugin/skills/muggle-preferences/preference-gates/defaultExecutionMode.md

@@ -4,7 +4,7 @@ Default place to run tests when the user's request is ambiguous.
 
 **Picker 1** — header `Where to run tests?`, question `"On your computer or in the cloud?"`
 - `On my computer` — `Real browser on localhost. Faster feedback while developing.` → `local`
-- `In the cloud` — `Muggle's cloud runs against a preview/staging URL.` → `remote`
+- `In the cloud` — `Muggle Test's cloud runs against a preview/staging URL.` → `remote`
 
 If the user's intent is already clear (e.g. "test on staging"), skip Picker 1
 — confirm with `"Yes, proceed in <mode>"` / `"Switch to <other mode>"` and

package/plugin/skills/muggle-preferences/preference-gates/openTestResultsAfterRun.md

@@ -8,4 +8,4 @@ Auto-open the dashboard after a run, or just print the URL.
 
 **Silent action**
 - `always` → `Opening results on the dashboard`
-- `never` → `Just printing the link — no auto-open`
+- `never` → `Just printing the link`

package/plugin/skills/muggle-preferences/preference-gates/postPRVisualWalkthrough.md

@@ -1,30 +1,13 @@
 # `postPRVisualWalkthrough`
 
-Post a visual walkthrough of test results to a PR.
+Preference gate. Controls whether the cycle posts the visual walkthrough comment (per-test-case dashboard links + step-by-step screenshots) to the PR after E2E results are available, or stops at "results ready". Fires once per E2E result set when a PR exists for the working branch (if it doesn't, callers fire [`autoCreatePR`](autoCreatePR.md) separately). Substitute `{prNumber}`.
 
-**PR detection (mandatory before any picker).** Run `gh pr view --json number,title,url 2>/dev/null` first. The result picks Case A or B.
-Substitute `{prNumber}`, `{prTitle}` into prompts.
+**Picker 1** — header `Post to PR`, question `"Post the visual walkthrough to PR #{prNumber}?"`
+- `Post to #{prNumber}` — `Comment with screenshots is added to the PR.` → `always`
+- `Ask me each time` — `Decide per run.` → `ask`
+- `Skip` — `Walkthrough is not posted.` → `never`
 
-## Case A — open PR found
-
-**Picker 1** — header `Share with the team`, question `"Post a visual walkthrough to PR #{prNumber} ({prTitle})?"`
-- `Yes, post to #{prNumber}` — `Reviewers see clickable per-test screenshots and dashboard links.` → `always`
-- `Skip` — `Keep it off the PR — you can post later from the dashboard.` → `never`
-
-**Silent action (Case A)**
+**Silent action**
 - `always` → `Posting walkthrough to PR #{prNumber}`
-- `never` → `Skipping PR walkthrough for #{prNumber}`
-
-## Case B — no open PR
-
-Situational fork — saved value is *not* updated from this picker.
-
-**Picker 1** — header `No PR yet`, question `"This branch has no open PR. Create one and post the walkthrough, or skip?"`
-- `Create a PR and post` — `I'll open a PR for this branch, then attach the walkthrough.` → run PR-creation flow (calling skill's responsibility), then post.
-- `Skip` — `Skip the walkthrough this time — you can post later from the dashboard.` → continue.
-
-**Picker 2** — skipped entirely.
-
-**Silent action (Case B)** — when saved gate is `always` or `never` but no PR exists:
-- `always` → fall through to Case B Picker 1 (don't auto-create silently). Print: `(`postPRVisualWalkthrough = always`, but this branch has no PR — asking what to do.)`
-- `never` → `Skipping PR walkthrough — no open PR for this branch`
+- `ask` → `Asking about PR walkthrough`
+- `never` → `Skipping PR walkthrough`

package/plugin/skills/muggle-preferences/preference-gates/showElectronBrowser.md

@@ -1,6 +1,6 @@
 # `showElectronBrowser`
 
-Show the Electron browser during local tests, or run hidden.
+Show the browser during local tests, or run hidden.
 
 **Picker 1** — header `Browser window`, question `"Show the test browser as it runs?"`
 - `Show it` — `Watch the test live — useful when something's failing.` → `always` (omit `showUi`)

package/plugin/skills/muggle-preferences/preference-gates/suggestRelatedTestCases.md

@@ -1,10 +1,10 @@
 # `suggestRelatedTestCases`
 
-After creating/running a test case, surface related ones already attached to the use case.
+After creating/running a test case, show related ones already attached to the use case.
 
-**Picker 1** — header `Related test cases`, question `"Surface related test cases already attached to this use case?"`
-- `Yes, suggest related` — `Catch test cases your import or change might have missed.` → `always`
-- `No, skip` — `Don't show suggestions — I'll ask if I want them later.` → `never`
+**Picker 1** — header `Related test cases`, question `"Show related test cases already attached to this use case?"`
+- `Show related` — `Catch test cases your import or change might have missed.` → `always`
+- `Skip` — `You can ask later if you want them.` → `never`
 
 **Silent action**
 - `always` → `Showing related test cases below`

package/plugin/skills/muggle-preferences/preference-gates/suggestRelatedUseCases.md

@@ -1,10 +1,10 @@
 # `suggestRelatedUseCases`
 
-After creating/running a use case, surface related ones already in the project.
+After creating/running a use case, show related ones already in the project.
 
-**Picker 1** — header `Related use cases`, question `"Surface related use cases already in this project?"`
-- `Yes, suggest related` — `Catch use cases your import or change might have missed.` → `always`
-- `No, skip` — `Don't show suggestions — I'll ask if I want them later.` → `never`
+**Picker 1** — header `Related use cases`, question `"Show related use cases already in this project?"`
+- `Show related` — `Catch use cases your import or change might have missed.` → `always`
+- `Skip` — `You can ask later if you want them.` → `never`
 
 **Silent action**
 - `always` → `Showing related use cases below`

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

@@ -1,9 +1,11 @@
 ---
 name: muggle-repair
-description: Diagnose and fix a broken Muggle AI installation. Use when user types muggle repair or asks to fix Muggle setup.
+description: Diagnose and fix a broken Muggle AI installation. Use when user types muggle repair or asks to fix Muggle Test setup.
 ---
 
-# Muggle Repair
+# Muggle Test Repair
+
+> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-repair"`.
 
 Automatically diagnose and fix broken components.
 

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

@@ -1,9 +1,11 @@
 ---
 name: muggle-status
-description: Check health of the Muggle AI installation. Use when user types muggle status, asks for Muggle health, MCP health, or auth validity.
+description: Check health of the Muggle AI installation. Use when user types muggle status, asks for Muggle Test health, MCP health, or auth validity.
 ---
 
-# Muggle Status
+# Muggle Test Status
+
+> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-status"`.
 
 Run a full health check and report results.
 
@@ -13,7 +15,7 @@ Gates run per `preference-gates/README.md`.
 
 | Preference | Step | Decision it gates |
 |------------|------|-------------------|
-| `checkForUpdates` | Check 4 | Check for newer Muggle version |
+| `checkForUpdates` | Check 4 | Check for newer Muggle Test version |
 
 ## Checks
 
@@ -24,8 +26,9 @@ Gates run per `preference-gates/README.md`.
 3. **Authentication** — call `muggle-remote-auth-status`. Report whether credentials are valid and when they expire.
 
 4. **CLI version** — gate `checkForUpdates` (per `preference-gates/README.md`):
-   - Pro-action: run the check below.
-   - Skip-action: render the row as `[skip]  check disabled by preference`.
+   - `always` → run the check below.
+   - `never` → render the row as `[skip]  check disabled by preference`.
+   - `ask` → run Picker 1 from `preference-gates/checkForUpdates.md` via `AskUserQuestion`; map the answer back to one of the actions above.
 
    When the check runs: 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.
 

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

@@ -1,27 +1,29 @@
 ---
 name: muggle-test
-description: "Run change-driven E2E acceptance testing using Muggle AI — detects local code changes, maps them to use cases, and generates test scripts either locally (real browser on localhost) or remotely (cloud execution on a preview/staging URL). Publishes results to Muggle dashboard, opens them in the browser, and posts E2E acceptance summaries with screenshots to the PR. Use this skill whenever the user wants to test their changes, run E2E acceptance tests on recent work, validate what they've been working on, or check if their code changes broke anything. Triggers on: 'test my changes', 'run tests on my changes', 'acceptance test my work', 'check my changes', 'validate my changes', 'test before I push', 'make sure my changes work', 'regression test my changes', 'test on preview', 'test on staging'. This is the go-to skill for change-driven E2E acceptance testing — it handles everything from change detection to test execution to result reporting."
+description: "Run change-driven E2E acceptance testing using Muggle AI — detects local code changes, maps them to use cases, and generates test scripts either locally (real browser on localhost) or remotely (cloud execution on a preview/staging URL). Publishes results to Muggle Test dashboard, opens them in the browser, and posts E2E acceptance summaries with screenshots to the PR. Use this skill whenever the user wants to test their changes, run E2E acceptance tests on recent work, validate what they've been working on, or check if their code changes broke anything. Triggers on: 'test my changes', 'run tests on my changes', 'acceptance test my work', 'check my changes', 'validate my changes', 'test before I push', 'make sure my changes work', 'regression test my changes', 'test on preview', 'test on staging'. This is the go-to skill for change-driven E2E acceptance testing — it handles everything from change detection to test execution to result reporting."
 ---
 
 # Muggle Test — Change-Driven E2E Acceptance Router
 
+> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-test"`.
+
 A router skill that detects code changes, resolves impacted test cases, executes them locally or remotely, publishes results to the Muggle AI dashboard, and posts E2E acceptance summaries to the PR. The user can invoke this at any moment, in any state.
 
 ## UX Guidelines — Minimize Typing
 
-**Every selection-based question MUST use the `AskQuestion` tool** (or the platform's equivalent structured selection tool). Never ask the user to "reply with a number" in a plain text message — always present clickable options.
+**Every selection-based question MUST use the `AskUserQuestion` tool** (or the platform's equivalent structured selection tool). Never ask the user to "reply with a number" in a plain text message — always present clickable options.
 
-- **Selections** (project, use case, test case, mode, approval): Use `AskQuestion` with labeled options the user can click.
-- **Multi-select** (use cases, test cases): Use `AskQuestion` with `allow_multiple: true`.
+- **Selections** (project, use case, test case, mode, approval): Use `AskUserQuestion` with labeled options the user can click.
+- **Multi-select** (use cases, test cases): Use `AskUserQuestion` with `allow_multiple: true`.
 - **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.
-- **Batch related questions**: If two questions are independent, present them together in a single `AskQuestion` call rather than asking sequentially.
+- **Batch related questions**: If two questions are independent, present them together in a single `AskUserQuestion` call rather than asking sequentially.
 - **Parallelize job-creation calls**: Whenever you're kicking off N independent cloud jobs — creating multiple use cases, generating/creating multiple test cases, fetching details for multiple test cases, starting multiple remote workflows, publishing multiple local runs, or fetching per-step screenshots for multiple runs — issue all N tool calls in a single message so they run in parallel. Never loop them sequentially unless there is a real ordering constraint (e.g. a single local Electron browser that can only run one test at a time).
 
 ## Test Case Design: One Atomic Behavior Per Test Case
 
 Every test case verifies exactly **one** user-observable behavior. Never bundle multiple concerns, sequential flows, or bootstrap/setup into a single test case — even if you think it would be "cleaner" or "more efficient."
 
-**Ordering, dependencies, and bootstrap are Muggle's service responsibility, not yours.** Muggle's cloud handles test case dependencies, prerequisite state, and execution ordering. Your job is to describe the *atomic behavior to verify* — never the flow that gets there.
+**Ordering, dependencies, and bootstrap are Muggle Test's service responsibility, not yours.** Muggle Test's cloud handles test case dependencies, prerequisite state, and execution ordering. Your job is to describe the *atomic behavior to verify* — never the flow that gets there.
 
 - ❌ Wrong: one test case that "signs up, logs in, navigates to the detail modal, verifies icon stacking, verifies tab order, verifies history format, and verifies reference layout."
 - ✅ Right: four separate test cases — one per verifiable behavior — each with instruction text like "Verify the detail modal shows stacked pair of icons per card" with **no** signup / login / navigation / setup language.
@@ -39,12 +41,14 @@ Gates run per `preference-gates/README.md`.
 | Preference | Step | Decision it gates |
 |------------|------|-------------------|
 | `autoLogin` | 3 | Reuse saved credentials when auth is required |
-| `autoSelectProject` | 4 | Reuse last-used Muggle project for this repo |
+| `autoSelectProject` | 4 | Reuse last-used Muggle Test project for this repo |
+| `autoSelectLocalHost` | 7A | Reuse last-used local dev server URL for this repo |
 | `autoDetectChanges` | 2 | Scan local git changes and map to affected test cases |
 | `defaultExecutionMode` | 1 | Default to local or remote test execution |
-| `autoPublishLocalResults` | 7A | Upload local results to Muggle cloud after run |
+| `autoPublishLocalResults` | 7A | Upload local results to Muggle Test cloud after run |
 | `showElectronBrowser` | 7A | Show the Electron browser window during local test execution (vs. run headless) |
 | `postPRVisualWalkthrough` | 9 | Post visual walkthrough to PR after results are available |
+| `autoCreatePR` | 9 (if no PR) | Auto-create the PR when posting the walkthrough has no PR to target |
 
 ## Step 1: Confirm Scope of Work (Always First)
 
@@ -58,7 +62,7 @@ Parse the user's query and explicitly confirm their expectation. There are exact
 Signs the user wants this: mentions "localhost", "local", "my machine", "dev server", "my changes locally", or just "test my changes" in a repo context.
 
 ### Mode B: Remote Test Generation
-> Ask Muggle's cloud to generate test scripts against a **preview/staging URL**.
+> Ask Muggle Test's cloud to generate test scripts against a **preview/staging URL**.
 >
 > Execution tool: `muggle-remote-workflow-start-test-script-generation`
 
@@ -77,8 +81,9 @@ Only proceed after selection.
 ## Step 2: Detect Local Changes (gated by `autoDetectChanges`)
 
 Gate `autoDetectChanges` (per `preference-gates/README.md`):
-- Pro-action: run the scan and proceed to analysis below.
-- Skip-action: ask "What would you like to test?" then jump to Step 3.
+- `always` → run the scan and proceed to analysis below.
+- `never` → ask "What would you like to test?" then jump to Step 3.
+- `ask` → run Picker 1 from `preference-gates/autoDetectChanges.md` via `AskUserQuestion`; map the answer back to one of the actions above.
 
 ### Analysis (when scan is enabled)
 
@@ -101,8 +106,9 @@ If no changes detected (clean tree), tell the user and ask what they want to tes
 
 1. Call `muggle-remote-auth-status`
 2. If **authenticated and not expired** → gate `autoLogin` (per `preference-gates/README.md`):
-   - Pro-action: reuse saved session.
-   - Skip-action: `muggle-remote-auth-login` with `forceNewSession: true`, then `muggle-remote-auth-poll`.
+   - `always` → reuse saved session.
+   - `never` → `muggle-remote-auth-login` with `forceNewSession: true`, then `muggle-remote-auth-poll`.
+   - `ask` → run Picker 1 from `preference-gates/autoLogin.md` via `AskUserQuestion`; map the answer back to one of the actions above.
 3. If **not authenticated or expired** → call `muggle-remote-auth-login`
 4. If login pending → call `muggle-remote-auth-poll`
 
@@ -112,9 +118,9 @@ If auth fails repeatedly, suggest: `muggle logout && muggle login` from terminal
 
 A **project** is where all your test results, use cases, and test scripts are grouped on the Muggle AI dashboard. Pick the project that matches what you're working on.
 
-The per-repo cache lives at `<cwd>/.muggle-ai/last-project.json` (managed via the `muggle-local-last-project-get` / `muggle-local-last-project-set` MCP tools). Look for the `Muggle Last Project: id=… url=… name="…"` line in session context — if present, that's this repo's cached pick.
+The per-repo cache lives at `<cwd>/.muggle-ai/last-project.json` (managed via the `muggle-local-last-project-get` / `muggle-local-last-project-set` MCP tools). Look for the `Muggle Test Last Project: id=… url=… name="…"` line in session context — if present, that's this repo's cached pick.
 
-Gate `autoSelectProject` (per `preference-gates/README.md`). Cache: `Muggle Last Project` session line.
+Gate `autoSelectProject` (per `preference-gates/README.md`). Cache: `Muggle Test Last Project` session line.
 - `always` + cache → use cached `projectId`, skip to Step 5. No cache → fall through to `ask`.
 - `never` → full project list; skip Picker 2.
 - `ask` → project list picker (see gate file for spec + Picker 2 override). Skip Picker 2 if "Create new project".
@@ -143,7 +149,7 @@ If nothing looks like a confident match, fall back to asking the user which use
 
 ### 5c: Present the shortlist for confirmation
 
-Use `AskQuestion` with `allow_multiple: true`:
+Use `AskUserQuestion` with `allow_multiple: true`:
 
 Prompt: "These use cases look most relevant to your changes — confirm which to test:"
 
@@ -152,7 +158,7 @@ Prompt: "These use cases look most relevant to your changes — confirm which to
 - Include "Create new use case" at the end
 
 ### 5d: If user picks "Pick a different use case"
-Re-present the full list from 5a via `AskQuestion` with `allow_multiple: true`, then continue.
+Re-present the full list from 5a via `AskUserQuestion` with `allow_multiple: true`, then continue.
 
 ### 5e: If user chooses "Create new use case"
 1. Ask the user to describe the use case(s) in plain English — they may want more than one
@@ -176,7 +182,7 @@ If nothing looks like a confident match, fall back to offering to run all test c
 
 ### 6c: Present the shortlist for confirmation
 
-Use `AskQuestion` with `allow_multiple: true`:
+Use `AskUserQuestion` with `allow_multiple: true`:
 
 Prompt: "These test cases look most relevant — confirm which to run:"
 
@@ -195,27 +201,46 @@ Prompt: "These test cases look most relevant — confirm which to run:"
 
 ### 6e: Confirm final selection
 
-Use `AskQuestion` to confirm: "You selected [N] test case(s): [list titles]. Ready to proceed?"
+Use `AskUserQuestion` to confirm: "You selected [N] test case(s): [list titles]. Ready to proceed?"
 - Option 1: "Yes, run them"
 - Option 2: "No, let me re-select"
 
 Wait for user confirmation before moving to execution.
 
+### 6f: Classify execution mode per test case (replay vs regen)
+
+For each selected test case, decide whether the run should be a **replay** of an existing script or a fresh **regen**, using the rules in [`_shared/failure-mode-handling.md`](../_shared/failure-mode-handling.md) section A. Inputs: the change summary from Step 2, the test case body, and the result of `muggle-remote-test-script-list` for that test case (last passing timestamp + whether any replayable script exists).
+
+Per test case, fire one `muggle-local-telemetry-event-emit` with `eventType: "pre-execution-classification"` capturing the picked mode, the rule that fired, and the matched changed-file paths.
+
+Then show the per-case decision in one `AskUserQuestion`:
+
+> "Here's how I plan to run each test case — replay reuses the saved script, regen rebuilds it from scratch:
+> - [REPLAY] Login with valid creds — selectors look unchanged
+> - [REGEN] Sign up with valid email — last passed > 30 days ago
+> - [REGEN] Add to cart — `app/cart/page.tsx` changed (UI/markup)"
+>
+> Options: "Looks good — proceed", "Override one or more", "Cancel"
+
+If the user picks "Override one or more", let them flip the mode for any test case via a second multi-select `AskUserQuestion`. Emit a follow-up `pre-execution-classification` event with `userAction` set whenever the user overrides.
+
 ## Step 7A: Execute — Local Mode
 
-### Pre-flight question — Local URL
+### Pre-flight question — Local URL (gated by `autoSelectLocalHost`)
 
-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)
-- Option 2: "Other — let me type a URL"
+Skill responsibilities (the rest is in `preference-gates/autoSelectLocalHost.md`):
+- **Read the cache**: `Muggle Test Last Host: <url>` session-context line, or `muggle-local-last-host-get`. Pass as `{lastHost}` substitution.
+- **Auto-detect a suggested URL**: `lsof -iTCP -sTCP:LISTEN -nP | grep -E ':(3000|3001|4200|5173|8080)'`. Pass as `{suggestedHost}`.
+- **Save the cache**: call `muggle-local-last-host-set` after the user picks (the gate file requires this on every pick).
 
-If nothing detected, ask as free text: "Your local app should be running. What's the URL? (e.g., http://localhost:3000)"
+Gate `autoSelectLocalHost` per `preference-gates/README.md` + `preference-gates/autoSelectLocalHost.md`.
 
 ### Pre-flight visibility (gated by `showElectronBrowser`)
 
 Gate `showElectronBrowser` (per `preference-gates/README.md`). Resolve once; apply same `showUi` to every test case.
-- Pro-action: omit `showUi` (defaults visible).
-- Skip-action: pass `showUi: false`.
+- `always` → omit `showUi` (defaults visible).
+- `never` → pass `showUi: false`.
+- `ask` → run Picker 1 from `preference-gates/showElectronBrowser.md` via `AskUserQuestion`; map the answer back to one of the actions above.
 
 ### Fetch test case details (in parallel)
 
@@ -234,16 +259,25 @@ If none of the above apply, omit `freshSession` (defaults to `false`, preserving
 
 ### Run sequentially (Electron constraint)
 
-Execution itself **must** be sequential because there is only one local Electron browser. For each test case, in order:
+Execution itself **must** be sequential because there is only one local Electron browser. For each test case, in the order chosen, branch on the mode picked in Step 6f:
 
+**Regen-mode test case:**
 1. Call `muggle-local-execute-test-generation`:
    - `testCase`: Full test case object from the parallel fetch above
    - `localUrl`: User's local URL from the pre-flight question
    - `showUi`: from the `showElectronBrowser` resolution — omit (default visible) for `always`, pass `false` for `never`
    - `freshSession`: `true` if the test case requires a clean browser state (see above), omit otherwise
-2. Store the returned `runId`
+2. Store the returned `runId` and tag the result `mode: "regen"`.
+
+**Replay-mode test case:**
+1. Fetch the action script: `muggle-remote-test-script-get` (latest replayable script id) → `muggle-remote-action-script-get` (full `actionScript` — use as-is, never edit). For batches, fan these calls out in parallel before the sequential execution loop begins.
+2. Call `muggle-local-execute-replay`:
+   - `testScript`: from `muggle-remote-test-script-get`
+   - `actionScript`: from `muggle-remote-action-script-get`
+   - `localUrl`, `showUi`, `freshSession`: same resolution as regen
+3. Store the returned `runId` and tag the result `mode: "replay"`.
 
-If a generation fails, log it and continue to the next. Do not abort the batch.
+If a run fails, log it and continue to the next — do not abort the batch. Failures are routed through Step 7C's post-failure handler after the batch completes.
 
 ### Collect results (in parallel)
 
@@ -252,8 +286,9 @@ For every `runId`, issue all `muggle-local-run-result-get` calls in parallel. Ex
 ### Publish each run to cloud (gated by `autoPublishLocalResults`)
 
 Gate `autoPublishLocalResults` (per `preference-gates/README.md`):
-- Pro-action: proceed to publish logic below.
-- Skip-action: skip to report summary; tell user Steps 8/9 and per-step screenshots are unavailable without publishing.
+- `always` → proceed to publish logic below.
+- `never` → skip to report summary; tell user Steps 8/9 and per-step screenshots are unavailable without publishing.
+- `ask` → run Picker 1 from `preference-gates/autoPublishLocalResults.md` via `AskUserQuestion`; map the answer back to one of the actions above.
 
 ### Publish logic (when publishing is enabled)
 
@@ -293,7 +328,9 @@ Issue all `muggle-remote-test-case-get` calls in parallel (single message, multi
 
 ### Trigger remote workflows (in parallel)
 
-Once details are in hand, issue all `muggle-remote-workflow-start-test-script-generation` calls in parallel — never loop them sequentially. For each test case:
+Branch each test case on the mode chosen in Step 6f, then issue **all** workflow-start calls in parallel — never loop them sequentially. Mix regen and replay starts in the same parallel batch.
+
+**Regen-mode test case** — `muggle-remote-workflow-start-test-script-generation`:
 
 - `projectId`: The project ID
 - `useCaseId`: The use case ID
@@ -305,7 +342,9 @@ Once details are in hand, issue all `muggle-remote-workflow-start-test-script-ge
 - `instructions`: From the test case
 - `expectedResult`: From the test case
 
-Store each returned workflow runtime ID.
+**Replay-mode test case** — `muggle-remote-workflow-start-test-script-replay` against the latest replayable script for that test case (resolve via `muggle-remote-test-script-list` if not already in hand from Step 6f). Tag results with `mode: "replay"` so Step 7C can route failures correctly.
+
+Store each returned workflow runtime ID along with its mode tag.
 
 ### Monitor and report (in parallel)
 
@@ -319,6 +358,21 @@ Login with invalid creds   COMPLETED         rt-def456
 Checkout flow              QUEUED            rt-ghi789
 ```
 
+## Step 7C: Route failures through the failure-mode handler
+
+For every run with `status: "failed"` (or any non-passing terminal state) from 7A or 7B, follow [`_shared/failure-mode-handling.md`](../_shared/failure-mode-handling.md):
+
+- **Replay-mode failures** — section B (buckets: `infra` / `stale-script` / `product-defect`).
+- **Regen-mode failures** — section C (buckets: `transient` / `infra` / `agent-course` / `product-uxux`).
+
+For each failed run:
+1. Read the run with `muggle-local-run-result-get` (local) or `muggle-remote-wf-get-ts-gen-latest-run` / `muggle-remote-wf-get-ts-replay-latest-run` (remote) and extract signals per the heuristics in the shared doc.
+2. Emit `replay-failure-classified` or `regen-failure-classified` via `muggle-local-telemetry-event-emit` **before** asking the user.
+3. Present the recommended action via `AskUserQuestion` along with the alternatives the shared doc lists for that bucket.
+4. After the user picks, emit the matching `*-resolved` event with `userAction` set to what they chose.
+
+Process failures one at a time so the user isn't drowning in pickers — but emit telemetry per failure regardless.
+
 ## Step 8: Open Results in Browser
 
 After execution and publishing are complete, open the Muggle AI dashboard so the user can visually inspect results and screenshots.
@@ -346,59 +400,25 @@ Tell the user:
 
 ## Step 9: Offer to Post Visual Walkthrough to PR
 
-After reporting results, ask the user if they want to attach a **visual walkthrough** — a markdown block with per-test-case dashboard links and step-by-step screenshots — to the current branch's open PR. The rendering and posting workflow lives in the shared `muggle-pr-visual-walkthrough` skill; this step gathers the required input and hands off.
-
-### 9a: Gather per-step screenshots (required input for the shared skill)
-
-The shared skill takes an **`E2eReport` JSON** that includes per-step screenshot URLs. You already have `projectId`, `testCaseId`, `runId`, `viewUrl`, and `status` from earlier steps — you still need the step-level data.
-
-For the published runs from Step 7A, issue **all** `muggle-remote-test-script-get` calls in parallel (single message, multiple tool calls) — one per `testScriptId` returned by `muggle-local-publish-test-script`. Then, for each response:
-
-1. Extract `steps[].operation.action` (description) and `steps[].operation.screenshotUrl` (cloud URL).
-2. Build a `steps` array: `[{ stepIndex: 0, action: "...", screenshotUrl: "..." }, ...]`.
-3. If the run failed, also capture `failureStepIndex`, `error`, and the local `artifactsDir` from `muggle-local-run-result-get`.
-4. Populate `description` (test case title/description) and `useCaseName` (parent use case title) on each 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 report:
-
-```json
-{
-  "projectId": "<projectId>",
-  "tests": [
-    {
-      "name": "<test case title>",
-      "description": "<one-line description of what this test verifies (optional but recommended)>",
-      "useCaseName": "<parent use case title (optional but recommended)>",
-      "testCaseId": "<id>",
-      "testScriptId": "<id>",
-      "runId": "<id>",
-      "viewUrl": "<publish response viewUrl>",
-      "status": "passed",
-      "steps": [{ "stepIndex": 0, "action": "...", "screenshotUrl": "..." }]
-    }
-  ]
-}
-```
-
-See the shared skill for the full schema (including the failed-test shape with `failureStepIndex` and `error`).
+After reporting results:
 
-### 9b: Detect the PR, then apply the `postPRVisualWalkthrough` gate
+1. Fire [`postPRVisualWalkthrough`](../muggle-preferences/preference-gates/postPRVisualWalkthrough.md). On skip → Step 10.
+2. `gh pr view --json number,title,url 2>/dev/null` — find the PR.
+3. If no PR: fire [`autoCreatePR`](../muggle-preferences/preference-gates/autoCreatePR.md). On skip → Step 10.
+4. Assemble the `E2eReport` — see [`../muggle-pr-visual-walkthrough/e2e-report-assembly.md`](../muggle-pr-visual-walkthrough/e2e-report-assembly.md). Include all runs from Step 7A (passed and failed).
+5. Invoke [`../muggle-pr-visual-walkthrough/SKILL.md`](../muggle-pr-visual-walkthrough/SKILL.md) Mode A with the `E2eReport`.
 
-Run `gh pr view --json number,title,url 2>/dev/null` first (mandatory — gate uses the result). Then gate `postPRVisualWalkthrough` (per `preference-gates/README.md` + gate file for two-case Picker 1):
-- **Case A (PR found)** — `always` → proceed to 9c; `never`/skip → stop.
-- **Case B (no PR)** — always run Picker 1 regardless of saved value; "Create a PR and post" → create PR then proceed to 9c; "Skip" → stop.
+## Step 10: Offer feedback on failures
 
-### 9c: Invoke the shared skill in Mode A
+After the report is complete, if **any** test in the run had a `failed` or unexpected status (or the user verbally flags something looked off), suggest the feedback skill:
 
-If 9b resolved to "post" (either via `postPRVisualWalkthrough = always` or the user picking "Yes, post to PR"), invoke the `muggle-pr-visual-walkthrough` skill via the `Skill` tool. With the `E2eReport` already in context, the skill will:
+> "Looks like `<N>` test(s) didn't go as expected. Want to leave feedback on what should've happened? It triggers regeneration on the affected scripts."
 
-1. Call `muggle build-pr-section` to render the markdown block (fit-vs-overflow automatic)
-2. Find the PR via `gh pr view`
-3. Post `body` as a `gh pr comment`
-4. Post the overflow `comment` as a second comment (only if the CLI emitted one)
-5. Confirm the PR URL to the user
+Use `AskUserQuestion`:
+- **Yes — give feedback** → invoke the `muggle-feedback` skill via the `Skill` tool. Pass the failed run's `runId` (local) or `testScriptId` (remote) as anchor context so the submit flow opens with the correct script already loaded.
+- **No — skip**
 
-This skill always uses **Mode A** (post to an existing PR); `muggle-do` is the only caller that uses Mode B. Do not attempt to render the walkthrough markdown yourself — delegate to the shared skill.
+This is a suggestion, not automatic invocation. Skip silently if every test passed cleanly.
 
 ## Tool Reference
 
@@ -415,10 +435,14 @@ This skill always uses **Mode A** (post to an existing PR); `muggle-do` is the o
 | Test Case | `muggle-remote-test-case-generate-from-prompt` | Both |
 | Test Case | `muggle-remote-test-case-create` | Both |
 | Test Case | `muggle-remote-test-case-get` | Both |
-| Execute | `muggle-local-execute-test-generation` | Local |
-| Execute | `muggle-remote-workflow-start-test-script-generation` | Remote |
+| Execute (regen) | `muggle-local-execute-test-generation` | Local |
+| Execute (replay) | `muggle-local-execute-replay` | Local |
+| Replay action script fetch | `muggle-remote-test-script-get`, `muggle-remote-action-script-get` | Local replay |
+| Execute (regen) | `muggle-remote-workflow-start-test-script-generation` | Remote |
+| Execute (replay) | `muggle-remote-workflow-start-test-script-replay` | Remote |
+| Failure-mode telemetry | `muggle-local-telemetry-event-emit` | Both |
 | Results | `muggle-local-run-result-get` | Local |
-| Results | `muggle-remote-wf-get-ts-gen-latest-run` | Remote |
+| Results | `muggle-remote-wf-get-ts-gen-latest-run`, `muggle-remote-wf-get-ts-replay-latest-run` | Remote |
 | Publish | `muggle-local-publish-test-script` | Local |
 | Per-step screenshots (for walkthrough) | `muggle-remote-test-script-get` | Both |
 | Browser | `open` (shell command) | Both |
@@ -427,13 +451,13 @@ This skill always uses **Mode A** (post to an existing PR); `muggle-do` is the o
 ## Guardrails
 
 - **Always confirm intent first** — never assume local vs remote without asking
-- **User MUST select project** — present clickable options via `AskQuestion`, wait for explicit choice, never auto-select
+- **User MUST select project** — present clickable options via `AskUserQuestion`, wait for explicit choice, never auto-select
 - **Best-effort shortlist use cases** — use the change summary to narrow the list to the most relevant 1–5 use cases and pre-check them; never dump every use case in the project on the user. Always leave an escape hatch to reveal the full list.
 - **Best-effort shortlist test cases** — same idea: pre-check the test cases most relevant to the change summary; never enumerate every test case attached to a use case. Always leave an escape hatch to reveal the full list.
-- **Use `AskQuestion` for every selection** — never ask the user to type a number; always present clickable options
+- **Use `AskUserQuestion` for every selection** — never ask the user to type a number; always present clickable options
 - **Auto-detect localhost URL when possible**; only fall back to free-text when nothing is listening on a common port
 - **Parallelize independent cloud jobs** — when creating N use cases, generating/creating N test cases, fetching N test case details, starting N remote workflows, polling N workflow runtimes, publishing N local runs, or fetching N per-step test scripts, issue all N calls in a single message so they fan out in parallel. The only tolerated sequential loop is local Electron execution (one browser, one test at a time). For use case creation specifically, use the native batch form of `muggle-remote-use-case-create-from-prompts` (all descriptions in one `instructions` array) instead of parallel calls.
-- **One atomic behavior per test case** — every test case verifies exactly one user-observable behavior. Never bundle signup/login/navigation/bootstrap/teardown into a test case body. Ordering and dependencies are Muggle's service responsibility, not the skill's.
+- **One atomic behavior per test case** — every test case verifies exactly one user-observable behavior. Never bundle signup/login/navigation/bootstrap/teardown into a test case body. Ordering and dependencies are Muggle Test's service responsibility, not the skill's.
 - **Never consolidate the generator's output** — if `muggle-remote-test-case-generate-from-prompt` returns N micro-tests, accept all N; never merge them into fewer test cases, even if "the plan" says 4 UC / 4 TC.
 - **Never skip the generate→review cycle** — always present generated test cases to the user before calling `muggle-remote-test-case-create`, even when you're confident. "I'll skip the review and create directly" is always wrong.
 - **Never silently drop test cases** — log failures and continue, then report them