@muggleai/works 4.10.0 → 4.10.1

package/plugin/skills/muggle-pr-visual-walkthrough/SKILL.md

@@ -1,19 +1,22 @@
 ---
 name: muggle-pr-visual-walkthrough
-description: Renders and posts a visual walkthrough of Muggle AI E2E acceptance test results to a PR — per-test-case dashboard links, step-by-step screenshots, and pass/fail summary — using the `muggle build-pr-section` CLI for deterministic formatting with automatic fit-vs-overflow. Use at the end of any Muggle test run (local or remote) to give PR reviewers clickable visual evidence that user flows work. Triggers on 'post results to PR', 'attach walkthrough to PR', 'share E2E screenshots on the PR', 'add visual walkthrough to PR'.
+description: Renders and posts a visual walkthrough of Muggle AI E2E acceptance test results to a PR — per-test-case dashboard links, step-by-step screenshots, and pass/fail summary — using the `muggle build-pr-section` CLI for deterministic formatting with automatic fit-vs-overflow. Use at the end of any Muggle Test test run (local or remote) to give PR reviewers clickable visual evidence that user flows work. Triggers on 'post results to PR', 'attach walkthrough to PR', 'share E2E screenshots on the PR', 'add visual walkthrough to PR'.
 ---
 
-# Muggle PR Visual Walkthrough
+# Muggle Test PR Visual Walkthrough
+
+> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-pr-visual-walkthrough"`.
 
 Renders a visual walkthrough of Muggle AI E2E acceptance test results and posts it to a PR. Each test case is linked to its detail page on the Muggle AI dashboard, so PR reviewers can click through to see step-by-step screenshots and action scripts — not just a pass/fail flag.
 
-This is the **canonical PR-walkthrough workflow** shared across every Muggle entry point:
+This is the **canonical PR-walkthrough workflow** shared across every Muggle Test entry point:
 
 | Caller | Mode | When to invoke |
 | :--- | :--- | :--- |
-| `muggle-test` | **Mode A** (post to existing PR) | After publishing results, user opts in via `AskQuestion` |
-| `muggle-test-feature-local` | **Mode A** (post to existing PR) | After publishing the run, user opts in via `AskQuestion` |
+| `muggle-test` | **Mode A** (post to existing PR) | After publishing results, user opts in via `AskUserQuestion` |
+| `muggle-test-feature-local` | **Mode A** (post to existing PR) | After publishing the run, user opts in via `AskUserQuestion` |
 | `muggle-do` / `open-prs.md` | **Mode B** (render-only for embedding) | During PR creation — caller embeds `body` in `gh pr create` and posts `comment` as follow-up |
+| `muggle-test` Mode C / `acceptance-tester` agent | **Mode C** (embed in verdict comment) | Inside a open-PR sweep orchestrator — caller folds the rendered body into a single per-PR verdict comment instead of posting separately |
 
 Rendering is always done by `muggle build-pr-section`, a battle-tested CLI that handles deterministic markdown layout, per-step screenshots, and automatic fit-vs-overflow (oversized content spills into a follow-up comment). Never hand-write the walkthrough markdown.
 
@@ -64,42 +67,48 @@ Every caller must build an `E2eReport` JSON object and have it in conversation c
       "failureStepIndex": 2,
       "error": "Element not found: Click checkout button",
       "artifactsDir": "/Users/.../~/.muggle-ai/sessions/<runId>"
+    },
+    {
+      "name": "Clear search input restores full list",
+      "description": "Verify clearing the search input restores all options.",
+      "useCaseName": "Filter Dropdowns",
+      "testCaseId": "<UUID>",
+      "runId": "<UUID>",
+      "viewUrl": "https://www.muggle-ai.com/...",
+      "status": "inconclusive",
+      "steps": [],
+      "reason": "No replayable script exists yet — needs first generation run."
     }
   ]
 }
 ```
 
-Required fields per test: `name`, `testCaseId`, `runId`, `viewUrl`, `status`, `steps[]` with `{stepIndex, action, screenshotUrl}`. Failed tests additionally require `failureStepIndex` and `error`.
+Required fields per test: `name`, `testCaseId`, `runId`, `viewUrl`, `status`, `steps[]` with `{stepIndex, action, screenshotUrl}`.
 
-**Optional but recommended** per test:
-- `description` — a one-line summary of what the test case verifies. Shown in the collapsible header for each test and helps reviewers understand the test without expanding it. Pull from the test case's `title`/`description` via `muggle-remote-test-case-get`.
-- `useCaseName` — the parent use case title. When present on any test, the overview list is grouped by use case; otherwise it is rendered as a flat list. Pull from `muggle-remote-use-case-get` using the test case's parent use-case id.
-- `testScriptId` and `artifactsDir` are also optional.
-
-If any required field is missing, stop and tell the caller exactly what's missing. Never fabricate data.
+- **Failed** tests additionally require `failureStepIndex` and `error`.
+- **Inconclusive** tests additionally require `reason` (one short sentence on why the result is neither pass nor fail). `steps[]` may be empty — that's fine. Inconclusive is for runs that couldn't be classified pass/fail (no replayable script, environment precondition unmet, infra error blocked execution, agent stalled before reaching the assertion). **Never silently drop these — always emit them as `inconclusive`.** The CLI counts them in the overview and renders an `⚠️` row with the dashboard link so reviewers can click through. If you find yourself wanting to skip a test or hand-write a comment because the schema "doesn't fit," that is the schema fitting — use `inconclusive`.
 
-## Step 1: Gather the `E2eReport`
+### Verdict
 
-How to assemble the JSON depends on which caller you are:
+The renderer computes a verdict from the tests and emits a `**Verdict:** ✅ PASS | ❌ FAIL | ⚠️ INCONCLUSIVE` line at the top of the overview. The policy is strict:
 
-### From `muggle-test` / `muggle-test-feature-local` (local mode)
+- Any failed test → **FAIL** (regardless of how many passed or are inconclusive).
+- No failures but any inconclusive → **INCONCLUSIVE**.
+- All passed → **PASS**.
+- Empty report → no verdict line.
 
-After `muggle-local-publish-test-script` returns `{testScriptId, viewUrl, ...}` for each run:
+You do not compute or render the verdict yourself — the CLI does. Never write a "Verdict: PASS" line into a hand-edited summary; it will conflict with the CLI's computed verdict.
 
-1. Call `muggle-remote-test-script-get` with `testScriptId` to fetch the published script.
-2. Extract `steps[]` — for each step, build `{stepIndex: <index>, action: operation.action, screenshotUrl: operation.screenshotUrl}`.
-3. Determine `status` from the local run result (`muggle-local-run-result-get`).
-4. For failures, read `failureStepIndex`, `error`, and `artifactsDir` from the run result.
-5. Assemble the `E2eReport` with `projectId` from the test run.
-6. 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. a test case you just created or selected, or a use case you confirmed); only call `muggle-remote-test-case-get` / `muggle-remote-use-case-get` for anything you don't already have.
-
-### From `muggle-do` (`open-prs.md`)
+**Optional but recommended** per test:
+- `description` — a one-line summary of what the test case verifies. Shown in the collapsible header for each test and helps reviewers understand the test without expanding it. Pull from the test case's `title`/`description` via `muggle-remote-test-case-get`.
+- `useCaseName` — the parent use case title. When present on any test, the overview list is grouped by use case; otherwise it is rendered as a flat list. Pull from `muggle-remote-use-case-get` using the test case's parent use-case id.
+- `testScriptId` and `artifactsDir` are also optional.
 
-The `e2e-acceptance.md` stage already produces an `E2eReport` with the exact shape above — that is the report's native output format. Pass it through unchanged.
+If any required field is missing, stop and tell the caller exactly what's missing. Never fabricate data.
 
-### Direct invocation (user asked to post existing results)
+## Step 1: Assemble the `E2eReport`
 
-The caller must have already executed tests and published them. If the `E2eReport` is not in context, stop and tell the user to run `muggle-test` or `muggle-test-feature-local` first.
+Read `plugin/skills/muggle-pr-visual-walkthrough/e2e-report-assembly.md` for the full assembly guide.
 
 ## Step 2: Render via `muggle build-pr-section`
 
@@ -126,7 +135,7 @@ gh pr view --json number,url,title 2>/dev/null
 ```
 
 - **PR exists** → continue to 3A.2
-- **No PR exists** → use `AskQuestion`:
+- **No PR exists** → use `AskUserQuestion`:
   - "Create a new PR with the visual walkthrough in the body"
   - "Skip posting"
   - If the user chooses to create a new PR, switch to Mode B and return the rendered `body`/`comment` to the caller for embedding in `gh pr create`. Do not create the PR directly from this skill unless the caller has no better way to do it.
@@ -134,20 +143,16 @@ gh pr view --json number,url,title 2>/dev/null
 
 ### 3A.2: Post the body as a PR comment
 
+Extract the `body` field with `jq -r` (not `sed`) so JSON escape sequences are properly decoded, then pipe to `--body-file -`:
+
 ```bash
-gh pr comment <pr-number> --body "$(cat <<'EOF'
-<contents of body field from CLI output>
-EOF
-)"
+jq -r '.body' /tmp/muggle-pr-section.json | gh pr comment <pr-number> --body-file -
 ```
 
 ### 3A.3: Post the overflow comment only if the CLI emitted one
 
 ```bash
-gh pr comment <pr-number> --body "$(cat <<'EOF'
-<contents of comment field from CLI output>
-EOF
-)"
+jq -r '.comment' /tmp/muggle-pr-section.json | gh pr comment <pr-number> --body-file -
 ```
 
 **Skip this step entirely if `comment` is `null`** — do not post a placeholder. The CLI decides fit-vs-overflow; never post the overflow comment speculatively.
@@ -169,16 +174,35 @@ Instead of posting, **return** the CLI output to the caller's context so they ca
 3. **Post `comment` as a follow-up only if the CLI emitted one:**
 
    ```bash
-   gh pr comment <new-pr-number> --body "$(cat <<'EOF'
-   <contents of comment field>
-   EOF
-   )"
+   jq -r '.comment' /tmp/muggle-pr-section.json | gh pr comment <new-pr-number> --body-file -
    ```
 
    Skip if `comment` is `null`.
 
 In Mode B, this skill does not call `gh pr comment` or `gh pr create` itself — the caller owns PR creation because it also owns branch pushing, title building (including `[E2E FAILING]` prefix on failures), and multi-repo orchestration.
 
+## Step 3 — Mode C: Embed mode for open-PR sweep orchestrators
+
+Used when invoked as a sub-step of a open-PR sweep orchestrator (see `plugin/skills/muggle-test/SKILL.md` Mode C) rather than as a top-level user invocation. The orchestrator's `acceptance-tester` subagent (see `plugin/agents/acceptance-tester.md`) composes a **single per-PR verdict comment** and folds the walkthrough into it — posting separately would create 2–3 disparate comments per test cycle and clutter the PR.
+
+### 3C.1: Detect embed mode
+
+The caller passes `mode: "embed"` as a skill argument. Default behavior (no `mode` passed, or `mode: "post"`) is Mode A — unchanged.
+
+### 3C.2: Render but do not post
+
+Run `muggle build-pr-section` exactly as in Step 2. Then, **instead of calling `gh pr comment`**:
+
+1. **Return** the CLI output (`{ body, comment }`) to the caller as this skill's result.
+2. Do **not** find a PR, do **not** post a standalone comment, do **not** prompt the user.
+3. If `comment` is non-null (overflow case), return it alongside `body` — the orchestrator decides how to handle overflow (typically: inline `body` in the verdict comment, post `comment` as a follow-up).
+
+### 3C.3: Hand off
+
+The orchestrator (`acceptance-tester`) concatenates the returned `body` into its verdict comment template alongside the verdict summary, change-list, and any other sections it owns, then posts a single `gh pr comment` itself. This skill's job ends at returning the rendered markdown.
+
+In Mode C, the same fit-vs-overflow contract from Step 2 applies — never modify the CLI's output, never fabricate fields, never post anything. The caller owns posting.
+
 ## Tool Reference
 
 | Phase | Tool |
@@ -188,14 +212,15 @@ In Mode B, this skill does not call `gh pr comment` or `gh pr create` itself —
 | Find existing PR (Mode A) | `gh pr view` |
 | Post comment(s) (Mode A) | `gh pr comment` |
 | Create new PR (Mode B, caller handles) | `gh pr create` |
-| User confirmation (Mode A no-PR branch) | `AskQuestion` |
+| User confirmation (Mode A no-PR branch) | `AskUserQuestion` |
 
 ## Guardrails
 
-- **Never hand-write the walkthrough markdown** — always call `muggle build-pr-section`. The CLI is the single source of truth for formatting.
+- **Never hand-write the walkthrough markdown** — always call `muggle build-pr-section`. The CLI is the single source of truth for formatting. If a test outcome doesn't fit `passed | failed`, that's what `inconclusive` is for — never fall back to a hand-written summary, a custom table, a "Verdict: PASS" header, a `Tested on:`/`Project:` footer, or any other freeform text. The CLI already emits per-test-case dashboard links (no project-level link), uses `https://www.muggle-ai.com/...` URLs (never the test target's `localhost` URL), and computes the verdict — anything you would manually add is wrong by construction.
 - **Never modify the CLI's output** — post `body` and (if present) `comment` verbatim. Any reformatting defeats the fit-vs-overflow budget math.
 - **Never invent report fields** — if `projectId`, a per-test `viewUrl`, or per-step `screenshotUrl` is missing, stop and report what's missing. Do not fabricate URLs or fill in placeholders.
 - **Never post the overflow comment when `comment` is `null`** — the CLI decides fit-vs-overflow.
 - **Never create a PR without confirmation in Mode A** — if no PR exists, ask the user or switch to Mode B and hand back to the caller.
 - **Don't run tests** — this skill only renders and posts existing results. If the `E2eReport` is not in context, redirect the caller to `muggle-test`, `muggle-test-feature-local`, or `muggle-do`.
-- **Mode A vs Mode B is chosen by the caller, not the user** — `muggle-test` always uses Mode A; `muggle-do` always uses Mode B. Don't ask the user which mode to use.
+- **Mode is chosen by the caller, not the user** — `muggle-test` top-level uses Mode A; `muggle-do` uses Mode B; open-PR sweep orchestrators (`muggle-test` Mode C / `acceptance-tester`) pass `mode: "embed"` for Mode C. Don't ask the user which mode to use.
+- **Never post in Mode C** — when `mode: "embed"` is passed, return the rendered body to the caller and stop. The orchestrator owns the single verdict comment.

package/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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})`