@muggleai/works 4.9.2 → 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,81 +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'.
+  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 determine which operation to perform:
+| 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** — 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
+## Shared context (all ops)
 
-## 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.
+- **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

@@ -0,0 +1,58 @@
+# Preference Gates — Contract
+
+One file per key in this directory — `ls preference-gates/*.md` is the
+authoritative key list. Skills load this contract + only the gates they
+actually fire.
+
+Default allowed values: `always` / `never` / `ask`. Per-key overrides
+are noted in their own file (currently only `defaultExecutionMode`,
+which uses `local` / `remote` / `ask`).
+
+## Resolution
+
+`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`.
+
+## Gate behavior
+
+- `always` → take the pro-action, then print silent footer.
+- `never` → take the skip-action, then print silent footer.
+- `ask` (or absent) → run Picker 1 (per-key file) → Picker 2 (below).
+
+`defaultExecutionMode` uses `local`/`remote` instead of `always`/`never`.
+
+## Silent footer (whenever pickers are skipped)
+
+The user must always be told **what happened**, **why it was silent**, and
+**how to change it**. Two lines:
+
+```
+✓ <silent action from per-key file>
+  (Skipped the prompt — `<key>` is set to `<value>`. Change: `/muggle-preferences <key>`.)
+```
+
+Concrete example (gate `autoLogin = always`):
+
+```
+✓ Continuing as foo@bar.com
+  (Skipped the prompt — `autoLogin` is set to `always`. Change: `/muggle-preferences autoLogin`.)
+```
+
+## Picker 2 — shared template
+
+Header `Remember this choice?`. Question: `"Always <restate Picker 1 choice in
+plain language> from now on, without asking?"`. Never put the raw key or
+`=` in the user-visible text.
+
+- `Yes, always` (sub: `You can change this later in muggle preferences.`) → `muggle-local-preferences-set` with the value Picker 1 mapped to, `scope: "global"`.
+- `Just this once` (sub: `I'll ask again next time.`) → don't save.
+
+A few keys override this template (their per-key file says how).
+
+**Saved value MUST match the Picker 1 choice.** Saving the opposite of
+what the user picked is a bug.
+
+## `/muggle-preferences <key>` (re-prompt)
+
+Run Picker 1 only, save immediately, skip Picker 2.

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

@@ -0,0 +1,11 @@
+# `autoDetectChanges`
+
+Scan local git changes to scope the test run, or skip the scan.
+
+**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`
+- `never` → `Skipping git scan — please tell me what to test`

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

@@ -0,0 +1,11 @@
+# `autoLogin`
+
+Reuse the saved session, or force a fresh login. Substitute `{email}`.
+
+**Picker 1** — header `You're already logged in`, question `"Continue as {email}, or sign in with a different account?"`
+- `Continue as me` — `Reuse this session for the rest of this run.` → `always`
+- `Switch account` — `Sign out and log in fresh.` → `never`
+
+**Silent action**
+- `always` → `Continuing as {email}`
+- `never` → `Logging in fresh`

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

@@ -0,0 +1,11 @@
+# `autoPublishLocalResults`
+
+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 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`
+
+**Silent action**
+- `always` → `Uploading to the dashboard`
+- `never` → `Keeping results local`

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

@@ -0,0 +1,16 @@
+# `autoSelectProject`
+
+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).
+
+**Picker 2 — overrides shared template.** Fires only after picking an
+*existing* project; skip if user picked "Create new project".
+- Header `Reuse this project next time?`, question `"Always reuse {projectName} for this repo from now on, without asking?"`
+- `Yes, always` (sub: `You can change this later in muggle preferences.`) → call BOTH `muggle-local-preferences-set` (`autoSelectProject=always`, global) AND `muggle-local-last-project-set` (`cwd`, `projectId`, `projectUrl`, `projectName`).
+- `Just this once` (sub: `I'll ask again next time.`) → don't save.
+
+**Silent action**
+- `always` (cached used) → `Using saved project {projectName}`
+- `never` (full list) → no footer; the picker is the visible step.

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

@@ -0,0 +1,11 @@
+# `checkForUpdates`
+
+Check npm for a newer Muggle Test version at session start.
+
+**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`
+- `never` → `Skipped update check`

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

@@ -0,0 +1,15 @@
+# `defaultExecutionMode` (`local` / `remote` / `ask`)
+
+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 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
+skip Picker 2.
+
+**Silent action**
+- `local` → `Running on your computer`
+- `remote` → `Running in the cloud`

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

@@ -0,0 +1,11 @@
+# `openTestResultsAfterRun`
+
+Auto-open the dashboard after a run, or just print the URL.
+
+**Picker 1** — header `After the run`, question `"Open the test results in your browser when this finishes?"`
+- `Open the dashboard` — `See screenshots, step details, and pass/fail at a glance.` → `always`
+- `Just print the link` — `Skip auto-open — I'll just hand you the URL.` → `never`
+
+**Silent action**
+- `always` → `Opening results on the dashboard`
+- `never` → `Just printing the link`

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

@@ -0,0 +1,13 @@
+# `postPRVisualWalkthrough`
+
+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}`.
+
+**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`
+
+**Silent action**
+- `always` → `Posting walkthrough to PR #{prNumber}`
+- `ask` → `Asking about PR walkthrough`
+- `never` → `Skipping PR walkthrough`

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

@@ -0,0 +1,11 @@
+# `showElectronBrowser`
+
+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`)
+- `Run hidden` — `Skip watching — let it run in the background while you do other things.` → `never` (pass `showUi: false`)
+
+**Silent action**
+- `always` → `Showing the browser`
+- `never` → `Running hidden`

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

@@ -0,0 +1,11 @@
+# `suggestRelatedTestCases`
+
+After creating/running a test case, show related ones already attached to the use case.
+
+**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`
+- `never` → `Skipping test case suggestions`

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

@@ -0,0 +1,11 @@
+# `suggestRelatedUseCases`
+
+After creating/running a use case, show related ones already in the project.
+
+**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`
+- `never` → `Skipping use case suggestions`

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

@@ -0,0 +1,8 @@
+# `verboseOutput`
+
+Show detailed progress logs during execution.
+
+**Not gated.** This is a UX-only knob — no Picker 1, no silent footer.
+Skills read the saved value from session context and adjust their log
+verbosity. The `muggle-preferences` skill exposes it through Configure
+and Set so users can change it.

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.