@muggleai/works 4.10.0 → 4.10.1

package/dist/plugin/skills/muggle-pr-visual-walkthrough/e2e-report-assembly.md

@@ -0,0 +1,86 @@
+# E2eReport Assembly Guide
+
+Include **all** runs — passed, failed, **and inconclusive**. Never drop a run. Always best-effort to upload so the dashboard has a record reviewers can open from the PR — even when the local run produced zero action steps.
+
+## Picking a status
+
+| Status | Use when | Required extras |
+|---|---|---|
+| `passed` | Run completed and the assertion held. | — |
+| `failed` | Run completed and the assertion failed, or the product itself broke before the assertion could be made (server error, 500, broken page). | `failureStepIndex`, `error` |
+| `inconclusive` | Run could not yield a pass/fail signal for reasons **outside the product**: no replayable script existed, environment precondition unmet, infra/Electron error, agent stalled on a cookie banner or login wall, missing secrets, agent went off-course. | `reason` (one short sentence; `steps[]` may be empty) |
+
+If a test should be inconclusive but you don't have a real `runId` / `viewUrl` (e.g., generation never ran), use the same project-level dashboard fallback as the "last-resort" failed branch below: emit a stub run via `muggle-remote-local-run-upload` if at all possible; otherwise synthesize a UUID-shaped runId and use `https://www.muggle-ai.com/muggleTestV0/dashboard/projects/{projectId}/runs` as `viewUrl`. The schema requires both fields — but a working dashboard link is better than nothing.
+
+## Uploaded run (passed or failed; the common path)
+
+Every run that completed locally — pass or fail, with or without action steps — should reach the cloud via Step 8 of the caller skill. The upload response carries `actionScriptId` and `viewUrl`; `testScriptId` is **only present for passing runs and replays** (failed generations skip the test script wrapper to avoid clobbering the canonical replay target).
+
+Fetch step screenshots in parallel — pick the right tool per upload:
+
+- **`testScriptId` present** → `muggle-remote-test-script-get` with that id.
+- **`testScriptId` missing** (failed generation, or zero-step fallback via `muggle-remote-local-run-upload`) → `muggle-remote-action-script-get` with `actionScriptId` from the upload response. Same `steps[]` + `summaryStep` shape; just one less hop.
+
+For each result:
+
+1. Build `steps[]`: `[{ stepIndex: <index>, action: steps[i].operation.action, screenshotUrl: steps[i].operation.screenshotUrl }, ...]`. Empty array is fine — zero-step runs still render the failure summary header in the walkthrough.
+2. `viewUrl` — from upload response (deep-links to the specific run via `actionScriptId`).
+3. `status` — from `muggle-local-run-result-get`.
+4. If failed: also capture `failureStepIndex`, `error`, `artifactsDir` from the run result.
+
+## Last-resort: upload genuinely failed
+
+Reach this branch only when **both** `muggle-local-publish-test-script` AND the `muggle-remote-local-run-upload` fallback errored (network failure, auth issue, etc.) — not for ordinary zero-step runs, which the fallback handles. Don't drop the run; render a stub entry so reviewers still see something happened.
+
+1. `steps: []`.
+2. `viewUrl`: `https://www.muggle-ai.com/muggleTestV0/dashboard/projects/{projectId}/runs` (generic dashboard).
+3. `status: "failed"`, `failureStepIndex: 0`, `error` from run result.
+4. `testCaseId` — from execution step selection. `runId` — from `muggle-local-execute-test-generation` (always present even on failure).
+
+On every entry: `description` (test case title/description — drives the collapsible header) and `useCaseName` (parent use case title — when present, the overview groups by use case) are optional but recommended. Prefer values already in context; only call `muggle-remote-test-case-get` / `muggle-remote-use-case-get` if missing.
+
+If called from `muggle-do`: `e2e-acceptance.md` already produces this shape — pass it through unchanged.
+
+## Shape
+
+```json
+{
+  "projectId": "<projectId>",
+  "tests": [
+    {
+      "name": "<test case title>",
+      "description": "<one-line description (recommended)>",
+      "useCaseName": "<parent use case title (recommended)>",
+      "testCaseId": "<testCaseId from execution step>",
+      "testScriptId": "<testScriptId from publish>",
+      "runId": "<runId from muggle-local-execute-test-generation>",
+      "viewUrl": "<viewUrl from publish>",
+      "status": "passed",
+      "steps": [{ "stepIndex": 0, "action": "...", "screenshotUrl": "..." }]
+    },
+    {
+      "name": "<failed test case title>",
+      "description": "<one-line description (recommended)>",
+      "useCaseName": "<parent use case title (recommended)>",
+      "testCaseId": "<testCaseId from execution step>",
+      "runId": "<runId from muggle-local-execute-test-generation>",
+      "viewUrl": "<viewUrl from upload response, deep-linked via actionScriptId>",
+      "status": "failed",
+      "steps": [],
+      "failureStepIndex": 0,
+      "error": "<error message from run result>"
+    },
+    {
+      "name": "<inconclusive test case title>",
+      "description": "<one-line description (recommended)>",
+      "useCaseName": "<parent use case title (recommended)>",
+      "testCaseId": "<testCaseId from execution step>",
+      "runId": "<runId from execute, or synthesized UUID if no run started>",
+      "viewUrl": "<viewUrl from upload response, or project-level fallback URL>",
+      "status": "inconclusive",
+      "steps": [],
+      "reason": "<one short sentence: why neither pass nor fail applies>"
+    }
+  ]
+}
+```

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

@@ -2,122 +2,30 @@
 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
+  Use when user asks to see preferences, change a setting, configure Muggle Test
   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 setup'.
 ---
 
-# Muggle Preferences
+# Muggle Test Preferences
 
-View, set, or reset the preference knobs that control Muggle AI behavior.
+> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-preferences"`.
 
-## Operations
+Pick the operation, then read its op file for the procedure.
 
-Parse the user's request to decide which operation to run:
+| Intent | Op file |
+|---|---|
+| `/muggle-preferences <key>` or "change my `<key>` preference" | `ops/change-one.md` |
+| User names key + value (e.g. "set autoLogin to always") | `ops/set.md` |
+| "show preferences" / no args | `ops/list.md` |
+| "configure muggle" / "muggle setup" / change without naming a key | `ops/configure.md` |
+| "reset preferences" | `ops/reset.md` |
 
-- **List** — show current values. Default when no change is requested.
-- **Change one** — re-run the gate's picker for a single key. Use this when the user invokes `/muggle-preferences <key>` or says "change my <key> preference".
-- **Configure** — interactive picker covering all keys at once. Default when the user wants to change preferences but hasn't named a specific one (e.g. "muggle setup", "configure muggle", "change my preferences").
-- **Set** — direct set when the user names a key+value (e.g. "set autoLogin to always").
-- **Reset** — restore preferences to default (`ask`).
+## Shared context (all ops)
 
-Per-key files live in `preference-gates/` — one `<key>.md` per key, plus `README.md` for the contract (`always`/`never`/`ask`, Picker 2 template, silent footer, re-prompt rule). The full key list = `ls preference-gates/*.md` minus `README.md`.
-
-## Reading current values
-
-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).
-
-## List
-
-Render a `Preference | Value | Description` table titled `Muggle AI — Preferences`.
-- Keys: every `preference-gates/<key>.md` (excluding `README.md`).
-- Values: from session context (default `ask`).
-- Description: each gate file's first paragraph.
-
-Footer:
-```
-Values: always · ask · never (defaultExecutionMode: local/remote/ask)
-Scope:  global (~/.muggle-ai/) or project (.muggle-ai/ in repo root)
-```
-
-## Change one (single-key picker)
-
-Use this when the user invokes `/muggle-preferences <key>` or says "change my <key> preference" / "show me the <key> options". Behavior:
-
-1. Check that `preference-gates/<key>.md` exists. If not, list `preference-gates/*.md` and ask.
-2. Open it, run **Picker 1 only**.
-3. Call `muggle-local-preferences-set` with the mapped value, `scope: "global"`. **Skip Picker 2** (user explicitly asked to change).
-4. Confirm: `Set <key> to <value>.`
-
-This is the entry point that silent-mode footers point at, so its UX must mirror the per-key gate exactly — same question, same options, same mappings.
-
-## Configure (interactive picker)
-
-Use this whenever the user wants to change preferences without naming a specific key. The flow runs in a single `AskUserQuestion` call so the user can toggle preferences with the keyboard instead of typing key names.
-
-### Step 1 — show current state
-
-Print the preference table from the **List** section so the user sees what's set today.
-
-### Step 2 — tell the user how to drive the picker
-
-Print this instruction block verbatim before calling `AskUserQuestion`:
-
-```
-How to use this picker:
-  ↑/↓        move between options
-  space      toggle a preference (selected = set to `always`)
-  tab        move to the next question
-  enter      confirm
-
-Anything you don't toggle keeps its current value. After this picker
-you can tell me which (if any) should instead be set to `never`.
-```
-
-### Step 3 — call AskUserQuestion
-
-Group keys into categories below (only place this UX grouping lives — not in the gate dir). For each option: label = key name, description = first paragraph of `preference-gates/<key>.md`.
-
-- `multiSelect: true`, `header: "Auth & session"` — `autoLogin`, `autoSelectProject`, `checkForUpdates`, `verboseOutput`
-- `multiSelect: true`, `header: "Test run"` — `showElectronBrowser`, `openTestResultsAfterRun`, `autoPublishLocalResults`, `autoDetectChanges`
-- `multiSelect: true`, `header: "Suggestions & PR"` — `suggestRelatedUseCases`, `suggestRelatedTestCases`, `postPRVisualWalkthrough`
-- `multiSelect: false`, `header: "Default mode"` — `defaultExecutionMode`. Options: `Local — run on my computer` (`local`), `Remote — run in the Muggle cloud` (`remote`), `Ask each time` (don't change).
-- `multiSelect: false`, `header: "Scope"` — final scope question. Options: `Global (all repos)` (~/.muggle-ai/), `This project only` (.muggle-ai/ in repo).
-
-For the multi-select questions: text = `Which of these should auto-proceed (set to "always")?`; selected = `always`.
-
-`AskUserQuestion` accepts up to 4 questions per call — split into two calls if needed (categories first, scope second).
-
-### Step 4 — apply selections
-
-For each toggled key (multi-select questions): `muggle-local-preferences-set` with `value: "always"`. For `defaultExecutionMode`: only set if user picked Local/Remote (skip "Ask each time"). Pass `scope` from the scope question; pass `cwd` when scope is `project`.
-
-### Step 5 — offer the `never` follow-up
-
-Ask: `Want any of these set to "never" (auto-skip without asking)? Name them, e.g. "never on autoPublishLocalResults", or say "no".`. For named keys, call `muggle-local-preferences-set` with `value: "never"`, same scope.
-
-### Step 6 — confirm
-
-Print a one-liner summary: `Set autoLogin=always, openTestResultsAfterRun=always (global).`
-
-## Set (direct)
-
-When the user names both key and value (e.g. "set autoLogin to always", "make showElectronBrowser never for this project"):
-
-1. Parse `key` and `value` from the user's message.
-2. Validate `key`: `preference-gates/<key>.md` must exist. If not, list `preference-gates/*.md` and ask.
-3. Validate `value`: must be `always`/`never`/`ask` for all keys; `defaultExecutionMode` accepts `local`/`remote`/`ask` instead.
-4. Scope defaults to `global`. If user says "for this project" / "just this repo", use `project` and pass `cwd`.
-5. Call `muggle-local-preferences-set`.
-6. Confirm: `Set {key} to {value} ({scope}).`
-
-## Reset
-
-- Specific key: `muggle-local-preferences-set` with `value: "ask"` for that key.
-- All preferences: same call for every `preference-gates/<key>.md`.
-
-Confirm what was reset.
+- **Current values**: session-context line `Muggle Test Preferences key=value …`. Default `ask`.
+- **Per-key files**: `preference-gates/<key>.md`. Key list = `ls preference-gates/*.md` minus `README.md`.
+- **Allowed values**: `always`/`never`/`ask` (or `local`/`remote`/`ask` for `defaultExecutionMode`).
+- **Scope**: `global` default; `project` if user says "for this project" / "just this repo" (pass `cwd`).

package/dist/plugin/skills/muggle-preferences/ops/change-one.md

@@ -0,0 +1,10 @@
+# Change one — `/muggle-preferences <key>`
+
+1. Verify `preference-gates/<key>.md` exists. If not, list `preference-gates/*.md` and ask.
+2. Read it. Run **Picker 1** with the options defined in the gate file, plus an additional `Ask me each time` (sub: `Prompt me at decision time.`) → `ask`.
+3. `muggle-local-preferences-set` with the mapped value, `scope: "global"`.
+4. Confirm: `Set <key> to <value>.`
+
+Skip Picker 2 — user explicitly asked to change.
+
+**Gates whose Picker 1 isn't a static yes/no** (e.g. `autoSelectProject`, where the picker is the project list rendered by the calling skill): present a generic 3-option picker using the gate's silent-action wording for the `always`/`never` labels, plus `Ask me each time` → `ask`.

package/dist/plugin/skills/muggle-preferences/ops/configure.md

@@ -0,0 +1,49 @@
+# Configure (interactive picker)
+
+Use whenever the user wants to change preferences without naming a specific key. Drives selections through `AskUserQuestion` so they toggle with the keyboard instead of typing key names.
+
+## Step 1 — show current state
+
+Print the preference table per `ops/list.md` so the user sees what's set today.
+
+## Step 2 — usage instructions
+
+Print verbatim before calling `AskUserQuestion`:
+
+```
+How to use this picker:
+  ↑/↓        move between options
+  space      toggle a preference (selected = set to `always`)
+  tab        move to the next question
+  enter      confirm
+
+Anything you don't toggle keeps its current value. After this picker
+you can tell me which (if any) should instead be set to `never`.
+```
+
+## Step 3 — call AskUserQuestion
+
+For each option: label = key name, description = first paragraph of `preference-gates/<key>.md`. Multi-select question text = `Which of these should auto-proceed (set to "always")?`; selected = `always`.
+
+- `multiSelect: true`, `header: "Auth & session"` — `autoLogin`, `autoSelectProject`, `checkForUpdates`, `verboseOutput`
+- `multiSelect: true`, `header: "Test setup"` — `autoSelectLocalHost`, `autoDetectChanges`
+- `multiSelect: true`, `header: "Test run"` — `showElectronBrowser`, `openTestResultsAfterRun`, `autoPublishLocalResults`
+- `multiSelect: true`, `header: "Suggestions & PR"` — `suggestRelatedUseCases`, `suggestRelatedTestCases`, `postPRVisualWalkthrough`, `autoCreatePR`
+- `multiSelect: true`, `header: "Branch hygiene"` — `autoUseWorktree`, `autoRebase`, `autoCleanup`
+- `multiSelect: false`, `header: "E2E acceptance"` — `autoE2ETest`. Options: `Always run Stage 6 at the end` (`always` — default), `Ask each cycle` (`ask`). No `never` option.
+- `multiSelect: false`, `header: "Default mode"` — `defaultExecutionMode`. Options: `Local — run on my computer` (`local`), `Remote — run in the Muggle Test cloud` (`remote`), `Ask each time` (don't change).
+- `multiSelect: false`, `header: "Scope"` — final scope question. Options: `Global (all repos)` (~/.muggle-ai/), `This project only` (.muggle-ai/ in repo).
+
+`AskUserQuestion` accepts up to 4 questions per call — split into two calls if needed (categories first, scope second).
+
+## Step 4 — apply selections
+
+For each toggled key (multi-select questions): `muggle-local-preferences-set` with `value: "always"`. For `defaultExecutionMode`: only set if user picked Local/Remote (skip "Ask each time"). Pass `scope` from the scope question; pass `cwd` when scope is `project`.
+
+## Step 5 — `never` follow-up
+
+Ask: `Want any of these set to "never" (auto-skip without asking)? Name them, e.g. "never on autoPublishLocalResults", or say "no".`. For named keys, call `muggle-local-preferences-set` with `value: "never"`, same scope.
+
+## Step 6 — confirm
+
+One-liner summary: `Set autoLogin=always, openTestResultsAfterRun=always (global).`

package/dist/plugin/skills/muggle-preferences/ops/list.md

@@ -0,0 +1,9 @@
+# List
+
+1. Read each `preference-gates/<key>.md` (skip `README.md`). First paragraph of each = description.
+2. Render `Preference | Value | Description` table titled `Muggle AI — Preferences`. Values from session context.
+3. Footer:
+   ```
+   Values: always · ask · never (defaultExecutionMode: local/remote/ask)
+   Scope:  global (~/.muggle-ai/) or project (.muggle-ai/ in repo root)
+   ```

package/dist/plugin/skills/muggle-preferences/ops/reset.md

@@ -0,0 +1,6 @@
+# Reset
+
+- **Specific key**: `muggle-local-preferences-set` with `value: "ask"` for that key.
+- **All preferences**: same call for every `preference-gates/<key>.md`.
+
+Confirm what was reset.

package/dist/plugin/skills/muggle-preferences/ops/set.md

@@ -0,0 +1,10 @@
+# Set — direct (key + value)
+
+Trigger: user names both key and value (e.g. "set autoLogin to always", "make showElectronBrowser never for this project").
+
+1. Parse `key` and `value`.
+2. Verify `preference-gates/<key>.md` exists. If not, list `preference-gates/*.md` and ask.
+3. Validate `value` per Shared context.
+4. Resolve scope per Shared context.
+5. `muggle-local-preferences-set`.
+6. Confirm: `Set {key} to {value} ({scope}).`

package/dist/plugin/skills/muggle-preferences/preference-gates/README.md

@@ -10,7 +10,7 @@ which uses `local` / `remote` / `ask`).
 
 ## Resolution
 
-`SessionStart` injects a `Muggle Preferences` line (`key=value` pairs) from
+`SessionStart` injects a `Muggle Test Preferences` line (`key=value` pairs) from
 `~/.muggle-ai/preferences.json` (global) overlaid by
 `<repo>/.muggle-ai/preferences.json` (project). Absent → treat as `ask`.
 

package/dist/plugin/skills/muggle-preferences/preference-gates/autoCleanup.md

@@ -0,0 +1,11 @@
+# `autoCleanup`
+
+After a PR is merged, run the full cleanup sequence (worktree, branch, artifacts, `clean_gone`) — or skip. `always` runs all steps with no per-step prompts. Substitute `{branch}`.
+
+**Picker 1** — header `Cleanup after merge`, question `"PR for {branch} is merged — run cleanup now?"`
+- `Run cleanup` — `Remove worktree, delete branch local+remote, clear local artifacts, prune [gone] branches.` → `always`
+- `Skip cleanup` — `Leave everything in place.` → `never`
+
+**Silent action**
+- `always` → `Running post-merge cleanup for {branch}`
+- `never` → `Skipping post-merge cleanup for {branch}`

package/dist/plugin/skills/muggle-preferences/preference-gates/autoCreatePR.md

@@ -0,0 +1,13 @@
+# `autoCreatePR`
+
+Controls whether the cycle pushes the working branch to remote and opens a pull request after local commits land, or stops at "commits made locally". Fires when the agent has buildable commits and no PR exists yet for the branch. Substitute `{branch}`.
+
+**Picker 1** — header `Open PR?`, question `"Push '{branch}' and open a pull request?"`
+- `Open the PR` — `Push branch and run gh pr create.` → `always`
+- `Ask me next time` — `Decide per cycle.` → `ask`
+- `Skip — I'll open it myself` — `Stop after the local commits.` → `never`
+
+**Silent action**
+- `always` → `Opening PR for {branch}`
+- `ask` → `Asking about PR creation`
+- `never` → `Skipping PR creation`

package/dist/plugin/skills/muggle-preferences/preference-gates/autoDetectChanges.md

@@ -2,9 +2,9 @@
 
 Scan local git changes to scope the test run, or skip the scan.
 
-**Picker 1** — header `Local git scan`, question `"Scan git changes to scope what to test?"`
-- `Yes, scan changes` — `Test cases that match recent diffs get prioritized.` → `always`
-- `No, I'll specify` — `Skip the scan — I'll tell you what to test.` → `never`
+**Picker 1** — header `Scan changes?`, question `"Scan git changes to scope what to test?"`
+- `Scan changes` — `Test cases that match recent diffs get prioritized.` → `always`
+- `Skip scan` — `Skip — you'll tell me what to test.` → `never`
 
 **Silent action**
 - `always` → `Scanning git changes to scope the run`

package/dist/plugin/skills/muggle-preferences/preference-gates/autoE2ETest.md

@@ -0,0 +1,11 @@
+# `autoE2ETest`
+
+Run Stage 6 (E2E acceptance) at the end of every `/muggle-do` cycle, or fold the decision into pre-flight each time. Default `always` — running E2E every cycle is the point of `muggle-do`, so `never` is not offered.
+
+**Picker 1** — header `Run E2E acceptance?`, question `"Run Stage 6 every cycle, or decide each time?"`
+- `Always run` — `Run Stage 6 every cycle; no further prompts.` → `always`
+- `Decide each cycle` — `Surface the question in pre-flight each run.` → `ask`
+
+**Silent action**
+- `always` → `Running Stage 6`
+- `ask` → `Asking each cycle whether to run Stage 6`

package/dist/plugin/skills/muggle-preferences/preference-gates/autoLogin.md

@@ -8,4 +8,4 @@ Reuse the saved session, or force a fresh login. Substitute `{email}`.
 
 **Silent action**
 - `always` → `Continuing as {email}`
-- `never` → `Forcing a fresh login`
+- `never` → `Logging in fresh`

package/dist/plugin/skills/muggle-preferences/preference-gates/autoPublishLocalResults.md

@@ -1,8 +1,8 @@
 # `autoPublishLocalResults`
 
-Upload local run artifacts to the Muggle cloud, or keep them local.
+Upload local run artifacts to the Muggle Test cloud, or keep them local.
 
-**Picker 1** — header `Share results?`, question `"Upload these results to the Muggle dashboard?"`
+**Picker 1** — header `Share results?`, question `"Upload these results to the Muggle Test dashboard?"`
 - `Upload them` — `Needed for the dashboard view, PR walkthrough, and team visibility.` → `always`
 - `Keep local-only` — `Stay on this machine — no dashboard view or PR walkthrough.` → `never`
 

package/dist/plugin/skills/muggle-preferences/preference-gates/autoRebase.md

@@ -0,0 +1,11 @@
+# `autoRebase`
+
+Rebase onto `origin/{default}` before dev servers / E2E, or run as-is. Substitute `{behind}` and `{default}`.
+
+**Picker 1** — header `Rebase first`, question `"Branch is {behind} commits behind origin/{default} — rebase first?"`
+- `Rebase first` — `Pull in default-branch changes so the run reflects the merged main line.` → `always`
+- `Run as-is` — `Skip the rebase.` → `never`
+
+**Silent action**
+- `always` → `Rebasing onto origin/{default} ({behind} behind)`
+- `never` → `Running as-is ({behind} behind origin/{default})`

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