@muggleai/works 4.9.2 → 4.10.0

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

@@ -0,0 +1,11 @@
+# `autoDetectChanges`
+
+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`
+
+**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/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` → `Forcing a fresh login`

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

@@ -0,0 +1,11 @@
+# `autoPublishLocalResults`
+
+Upload local run artifacts to the Muggle cloud, or keep them local.
+
+**Picker 1** — header `Share results?`, question `"Upload these results to the Muggle 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/autoSelectProject.md

@@ -0,0 +1,17 @@
+# `autoSelectProject`
+
+Reuse the cached project for this repo (`<cwd>/.muggle-ai/last-project.json`),
+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/checkForUpdates.md

@@ -0,0 +1,11 @@
+# `checkForUpdates`
+
+Check npm for a newer Muggle 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`
+
+**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'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 — no auto-open`

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

@@ -0,0 +1,30 @@
+# `postPRVisualWalkthrough`
+
+Post a visual walkthrough of test results to a PR.
+
+**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.
+
+## 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)**
+- `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`

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

@@ -0,0 +1,11 @@
+# `showElectronBrowser`
+
+Show the Electron 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, surface 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`
+
+**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, surface 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`
+
+**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-status/SKILL.md

@@ -9,20 +9,11 @@ Run a full health check and report results.
 
 ## Preferences
 
-User preferences are available in the session context (injected at session start). Look for the line starting with `Muggle Preferences` — it contains key=value pairs like `autoLogin=ask showElectronBrowser=always ...`.
+Gates run per `preference-gates/README.md`.
 
-If no preferences line is present, treat all preferences as `"ask"`.
-
-When you reach a decision gated by a preference:
-- **`always`** → proceed without asking the user
-- **`never`** → skip without asking the user  
-- **`ask`** → ask the user, then offer: "Want me to remember this choice for future sessions?" If yes, call `muggle-local-preferences-set` with the key, their chosen value, and scope `global`.
-
-This skill uses these preferences:
-
-| Preference | Decision it gates |
-|------------|------------------|
-| `checkForUpdates` | Check for newer Muggle version |
+| Preference | Step | Decision it gates |
+|------------|------|-------------------|
+| `checkForUpdates` | Check 4 | Check for newer Muggle version |
 
 ## Checks
 
@@ -32,7 +23,11 @@ This skill uses these preferences:
 
 3. **Authentication** — call `muggle-remote-auth-status`. Report whether credentials are valid and when they expire.
 
-4. **CLI version** — 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.
+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`.
+
+   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.
 
 ## Output
 

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

@@ -34,25 +34,17 @@ Every test case verifies exactly **one** user-observable behavior. Never bundle
 
 ## Preferences
 
-User preferences are available in the session context (injected at session start). Look for the line starting with `Muggle Preferences` — it contains key=value pairs like `autoLogin=ask showElectronBrowser=always ...`.
-
-If no preferences line is present, treat all preferences as `"ask"`.
-
-When you reach a decision gated by a preference:
-- **`always`** → proceed without asking the user
-- **`never`** → skip without asking the user  
-- **`ask`** → ask the user, then offer: "Want me to remember this choice for future sessions?" If yes, call `muggle-local-preferences-set` with the key, their chosen value, and scope `global`.
-
-This skill uses these preferences:
-
-| Preference | Decision it gates |
-|------------|------------------|
-| `autoLogin` | Reuse saved credentials when auth is required |
-| `autoSelectProject` | Reuse last-used Muggle project for this repo |
-| `autoDetectChanges` | Scan local git changes and map to affected test cases |
-| `defaultExecutionMode` | Default to local or remote test execution |
-| `autoPublishLocalResults` | Upload local results to Muggle cloud after run |
-| `postPRVisualWalkthrough` | Post visual walkthrough to PR after results are available |
+Gates run per `preference-gates/README.md`.
+
+| Preference | Step | Decision it gates |
+|------------|------|-------------------|
+| `autoLogin` | 3 | Reuse saved credentials when auth is required |
+| `autoSelectProject` | 4 | Reuse last-used Muggle project for this repo |
+| `autoDetectChanges` | 2 | Scan local git changes and map to affected test cases |
+| `defaultExecutionMode` | 1 | Default to local or remote test execution |
+| `autoPublishLocalResults` | 7A | Upload local results to Muggle cloud after run |
+| `showElectronBrowser` | 7A | Show the Electron browser window during local test execution (vs. run headless) |
+| `postPRVisualWalkthrough` | 9 | Post visual walkthrough to PR after results are available |
 
 ## Step 1: Confirm Scope of Work (Always First)
 
@@ -72,19 +64,23 @@ Signs the user wants this: mentions "localhost", "local", "my machine", "dev ser
 
 Signs the user wants this: mentions "preview", "staging", "deployed", "preview URL", "test on preview", "test the deployment", or provides a non-localhost URL.
 
-### Confirming
+### Confirming (gated by `defaultExecutionMode`)
+
+Gate `defaultExecutionMode` (per `preference-gates/README.md`). Uses `local`/`remote`/`ask`.
+- `local` → proceed in Local mode.
+- `remote` → proceed in Remote mode.
+- `ask` + intent clear → skip Picker 1, confirm one-shot then skip Picker 2.
+- `ask` + ambiguous → run Picker 1 from gate file.
 
-If the user's intent is clear, state back what you understood and use `AskQuestion` to confirm:
-- Option 1: "Yes, proceed"
-- Option 2: "Switch to [the other mode]"
+Only proceed after selection.
 
-If ambiguous, use `AskQuestion` to let the user choose:
-- Option 1: "On my computer — test your localhost dev server in a browser on your machine"
-- Option 2: "In the cloud — test remotely targeting your deployed preview/staging URL"
+## Step 2: Detect Local Changes (gated by `autoDetectChanges`)
 
-Only proceed after the user selects an option.
+Gate `autoDetectChanges` (per `preference-gates/README.md`):
+- Pro-action: run the scan and proceed to analysis below.
+- Skip-action: ask "What would you like to test?" then jump to Step 3.
 
-## Step 2: Detect Local Changes
+### Analysis (when scan is enabled)
 
 Analyze the working directory to understand what changed.
 
@@ -104,36 +100,35 @@ If no changes detected (clean tree), tell the user and ask what they want to tes
 ## Step 3: Authenticate
 
 1. Call `muggle-remote-auth-status`
-2. If **authenticated and not expired** → print the logged-in email and ask via `AskQuestion`:
-   > "You're logged in as **{email}**. Continue with this account?"
-   - Option 1: "Yes, continue"
-   - Option 2: "No, switch account"
-   If the user picks "switch account", call `muggle-remote-auth-login` with `forceNewSession: true`, then `muggle-remote-auth-poll`.
+2. If **authenticated and not expired** → gate `autoLogin` (per `preference-gates/README.md`):
+   - Pro-action: reuse saved session.
+   - Skip-action: `muggle-remote-auth-login` with `forceNewSession: true`, then `muggle-remote-auth-poll`.
 3. If **not authenticated or expired** → call `muggle-remote-auth-login`
 4. If login pending → call `muggle-remote-auth-poll`
 
 If auth fails repeatedly, suggest: `muggle logout && muggle login` from terminal.
 
-## Step 4: Select Project (User Must Choose)
+## Step 4: Select Project (gated by `autoSelectProject`)
 
 A **project** is where all your test results, use cases, and test scripts are grouped on the Muggle AI dashboard. Pick the project that matches what you're working on.
 
-1. Call `muggle-remote-project-list`
-2. Use `AskQuestion` to present all projects as clickable options. Include the project URL in each label so the user can identify the right one. Always include a "Create new project" option at the end.
+The per-repo cache lives at `<cwd>/.muggle-ai/last-project.json` (managed via the `muggle-local-last-project-get` / `muggle-local-last-project-set` MCP tools). Look for the `Muggle Last Project: id=… url=… name="…"` line in session context — if present, that's this repo's cached pick.
 
-   Example labels:
-   - "MUGGLE AI STAGING 1 — https://staging.muggle-ai.com/"
-   - "Tanka Testing — https://www.tanka.ai"
-   - "Create new project"
+Gate `autoSelectProject` (per `preference-gates/README.md`). Cache: `Muggle Last Project` session line.
+- `always` + cache → use cached `projectId`, skip to Step 5. No cache → fall through to `ask`.
+- `never` → full project list; skip Picker 2.
+- `ask` → project list picker (see gate file for spec + Picker 2 override). Skip Picker 2 if "Create new project".
 
-   Prompt: "Pick the project to group this test run into:"
+### Logic
 
-3. **Wait for the user to explicitly choose** — do NOT auto-select based on repo name or URL matching
+1. Resolve the chosen project per the gate above.
+2. Call `muggle-remote-project-list` only when the gate doesn't already give a `projectId` from the cache.
+3. **Wait for the user to explicitly choose** when presenting the picker — do NOT auto-select based on repo name or URL matching.
 4. **If user chooses "Create new project"**:
    - Ask for `projectName`, `description`, and the production/preview URL
    - Call `muggle-remote-project-create`
 
-Store the `projectId` only after user confirms.
+Store the `projectId` only after user confirms (or after silent reuse from the cache).
 
 ## Step 5: Select Use Case (Best-Effort Shortlist)
 
@@ -216,7 +211,11 @@ Try to auto-detect the dev server URL by checking running terminals or common po
 
 If nothing detected, ask as free text: "Your local app should be running. What's the URL? (e.g., http://localhost:3000)"
 
-**No separate approval or visibility question.** The user picking Local mode in Step 1 *is* the approval — do not ask "ready to launch Electron?" before every run. The Electron browser defaults to visible; if the user wants headless, they will say so, otherwise let it run visible.
+### Pre-flight visibility (gated by `showElectronBrowser`)
+
+Gate `showElectronBrowser` (per `preference-gates/README.md`). Resolve once; apply same `showUi` to every test case.
+- Pro-action: omit `showUi` (defaults visible).
+- Skip-action: pass `showUi: false`.
 
 ### Fetch test case details (in parallel)
 
@@ -240,7 +239,7 @@ Execution itself **must** be sequential because there is only one local Electron
 1. Call `muggle-local-execute-test-generation`:
    - `testCase`: Full test case object from the parallel fetch above
    - `localUrl`: User's local URL from the pre-flight question
-   - `showUi`: omit (default visible) unless the user explicitly asked for headless, then pass `false`
+   - `showUi`: from the `showElectronBrowser` resolution — omit (default visible) for `always`, pass `false` for `never`
    - `freshSession`: `true` if the test case requires a clean browser state (see above), omit otherwise
 2. Store the returned `runId`
 
@@ -250,7 +249,13 @@ If a generation fails, log it and continue to the next. Do not abort the batch.
 
 For every `runId`, issue all `muggle-local-run-result-get` calls in parallel. Extract: status, duration, step count, `artifactsDir`.
 
-### Publish each run to cloud (in parallel)
+### Publish each run to cloud (gated by `autoPublishLocalResults`)
+
+Gate `autoPublishLocalResults` (per `preference-gates/README.md`):
+- Pro-action: proceed to publish logic below.
+- Skip-action: skip to report summary; tell user Steps 8/9 and per-step screenshots are unavailable without publishing.
+
+### Publish logic (when publishing is enabled)
 
 For every completed run, issue all `muggle-local-publish-test-script` calls in parallel (single message, multiple tool calls):
 - `runId`: The local run ID
@@ -377,18 +382,15 @@ Assemble the report:
 
 See the shared skill for the full schema (including the failed-test shape with `failureStepIndex` and `error`).
 
-### 9b: Ask the user
-
-Use `AskQuestion`:
-
-> "Post a visual walkthrough of these results to the PR? Reviewers can click each test case to see step-by-step screenshots on the Muggle AI dashboard."
+### 9b: Detect the PR, then apply the `postPRVisualWalkthrough` gate
 
-- Option 1: "Yes, post to PR"
-- Option 2: "Skip"
+Run `gh pr view --json number,title,url 2>/dev/null` first (mandatory — gate uses the result). Then gate `postPRVisualWalkthrough` (per `preference-gates/README.md` + gate file for two-case Picker 1):
+- **Case A (PR found)** — `always` → proceed to 9c; `never`/skip → stop.
+- **Case B (no PR)** — always run Picker 1 regardless of saved value; "Create a PR and post" → create PR then proceed to 9c; "Skip" → stop.
 
 ### 9c: Invoke the shared skill in Mode A
 
-If the user chooses "Yes, post to PR", invoke the `muggle-pr-visual-walkthrough` skill via the `Skill` tool. With the `E2eReport` already in context, the skill will:
+If 9b resolved to "post" (either via `postPRVisualWalkthrough = always` or the user picking "Yes, post to PR"), invoke the `muggle-pr-visual-walkthrough` skill via the `Skill` tool. With the `E2eReport` already in context, the skill will:
 
 1. Call `muggle build-pr-section` to render the markdown block (fit-vs-overflow automatic)
 2. Find the PR via `gh pr view`
@@ -434,7 +436,6 @@ This skill always uses **Mode A** (post to an existing PR); `muggle-do` is the o
 - **One atomic behavior per test case** — every test case verifies exactly one user-observable behavior. Never bundle signup/login/navigation/bootstrap/teardown into a test case body. Ordering and dependencies are Muggle's service responsibility, not the skill's.
 - **Never consolidate the generator's output** — if `muggle-remote-test-case-generate-from-prompt` returns N micro-tests, accept all N; never merge them into fewer test cases, even if "the plan" says 4 UC / 4 TC.
 - **Never skip the generate→review cycle** — always present generated test cases to the user before calling `muggle-remote-test-case-create`, even when you're confident. "I'll skip the review and create directly" is always wrong.
-- **Never ask for Electron launch approval before each run** — the user picking Local mode is the approval. Don't prompt "Ready to launch Electron?" before execution; just run.
 - **Never silently drop test cases** — log failures and continue, then report them
 - **Never guess the URL** — always ask the user for localhost or preview URL
 - **Always publish before opening browser** — the dashboard needs the published data to show results

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

@@ -24,39 +24,35 @@ The local URL only changes where the browser opens; it does not change the remot
 
 ## Preferences
 
-User preferences are available in the session context (injected at session start). Look for the line starting with `Muggle Preferences` — it contains key=value pairs like `autoLogin=ask showElectronBrowser=always ...`.
+Gates run per `preference-gates/README.md`.
 
-If no preferences line is present, treat all preferences as `"ask"`.
-
-When you reach a decision gated by a preference:
-- **`always`** → proceed without asking the user
-- **`never`** → skip without asking the user  
-- **`ask`** → ask the user, then offer: "Want me to remember this choice for future sessions?" If yes, call `muggle-local-preferences-set` with the key, their chosen value, and scope `global`.
-
-This skill uses these preferences:
-
-| Preference | Decision it gates |
-|------------|------------------|
-| `autoLogin` | Reuse saved credentials when auth is required |
-| `autoSelectProject` | Reuse last-used Muggle project for this repo |
-| `showElectronBrowser` | Show Electron browser window during local E2E tests |
-| `openTestResultsAfterRun` | Open results page on Muggle dashboard after run |
+| Preference | Step | Decision it gates |
+|------------|------|-------------------|
+| `autoLogin` | 1 | Reuse saved credentials when auth is required |
+| `autoSelectProject` | 2 | Reuse last-used Muggle project for this repo |
+| `showElectronBrowser` | 7 | Show Electron browser window during local E2E tests |
+| `openTestResultsAfterRun` | 8 | Open results page on Muggle dashboard after run |
+| `postPRVisualWalkthrough` | 10 | Post visual walkthrough to PR after results |
 
 ## Workflow
 
-### 1. Auth
+### 1. Auth (gated by `autoLogin`)
 
 - `muggle-remote-auth-status`
-- If **authenticated**: print the logged-in email and ask via `AskQuestion`:
-  > "You're logged in as **{email}**. Continue with this account?"
-  - Option 1: "Yes, continue"
-  - Option 2: "No, switch account"
-  If the user picks "switch account", call `muggle-remote-auth-login` with `forceNewSession: true` then `muggle-remote-auth-poll`.
-- If **not signed in or expired**: call `muggle-remote-auth-login` then `muggle-remote-auth-poll`.
-  Do not skip or assume auth.
+- If **authenticated**: gate `autoLogin` (per `preference-gates/README.md`):
+  - Pro-action: proceed with saved session.
+  - Skip-action: `muggle-remote-auth-login` with `forceNewSession: true`, then `muggle-remote-auth-poll`.
+- If **not signed in or expired**: call `muggle-remote-auth-login` then `muggle-remote-auth-poll`. Do not skip or assume auth.
 
 ### 2. Targets (user must confirm)
 
+The per-repo project cache lives at `<cwd>/.muggle-ai/last-project.json` (via the `muggle-local-last-project-get` / `muggle-local-last-project-set` MCP tools). Look for `Muggle Last Project: id=… url=… name="…"` in session context.
+
+Gate `autoSelectProject` (per `preference-gates/README.md`). Cache: `Muggle Last Project` session line.
+- `always` + cache → use cached `projectId`, skip to use case selection. No cache → fall through to `ask`.
+- `never` → full project list; skip Picker 2.
+- `ask` → project list picker (see gate file for spec + Picker 2 override). Skip Picker 2 if "Create new project".
+
 Ask the user to pick **project**, **use case**, and **test case** (do not infer).
 
 - `muggle-remote-project-list`
@@ -153,14 +149,20 @@ The MCP client often uses a **default wait of 300000 ms (5 minutes)** for `muggl
 - **`Electron execution timed out after 300000ms`:** Orchestration wait too short — see **`timeoutMs`** above.
 - **Exit code 26** (and messages like **LLM failed to generate / replay action script**): Often corresponds to a completed exploration whose **outcome was goal not achievable** (`goal_not_achievable`, summary with `halt`) — e.g. verifying "view script after a successful run" when **no run or script exists yet** in the UI. Use `muggle-local-run-result-get` and read the **summary / structured summary**; do not assume an Electron crash. **Fix:** choose a **project that already has** completed runs and scripts, or **change the test case** so preconditions match what localhost can satisfy (e.g. include steps to create and run a test first, or assert only empty-state UI when no runs exist).
 
-### 7. Execute (no approval prompt)
+### 7. Execute (no approval prompt; `showUi` gated by `showElectronBrowser`)
+
+Call `muggle-local-execute-test-generation` or `muggle-local-execute-replay` directly. **Do not** ask the user to re-approve the Electron launch — the user choosing this skill in the first place is the approval.
 
-Call `muggle-local-execute-test-generation` or `muggle-local-execute-replay` directly. **Do not** ask the user to re-approve the Electron launch — the user choosing this skill in the first place is the approval. The browser defaults to visible; only pass `showUi: false` if the user explicitly asked for headless.
+Gate `showElectronBrowser` (per `preference-gates/README.md`). Reuse choice within a session.
+- Pro-action: omit `showUi`.
+- Skip-action: pass `showUi: false`.
 
-### 8. After successful generation only
+### 8. After successful generation only (open `viewUrl` gated by `openTestResultsAfterRun`)
 
 - `muggle-local-publish-test-script`
-- Open returned `viewUrl` for the user (`open "<viewUrl>"` on macOS or OS equivalent).
+- Gate `openTestResultsAfterRun` (per `preference-gates/README.md`):
+  - Pro-action: open `viewUrl` automatically (`open "<viewUrl>"` on macOS or OS equivalent).
+  - Skip-action: print the URL only.
 
 ### 9. Report
 
@@ -204,18 +206,15 @@ Assemble the `E2eReport`:
 
 See the `muggle:muggle-pr-visual-walkthrough` skill for the full schema including the failed-test shape.
 
-#### 10b: Ask the user
-
-Use `AskQuestion`:
-
-> "Post a visual walkthrough of this run to the PR? Reviewers can click the test case to see step-by-step screenshots on the Muggle AI dashboard."
+#### 10b: Detect the PR, then apply the `postPRVisualWalkthrough` gate
 
-- Option 1: "Yes, post to PR"
-- Option 2: "Skip"
+Run `gh pr view --json number,title,url 2>/dev/null` first (mandatory). Then gate `postPRVisualWalkthrough` (per `preference-gates/README.md` + gate file):
+- **Case A (PR found)** — `always` → proceed to 10c; `never`/skip → stop.
+- **Case B (no PR)** — always run Picker 1 regardless of saved value; "Create a PR and post" → create PR then proceed to 10c; "Skip" → stop.
 
 #### 10c: Invoke the shared skill in Mode A
 
-If the user chooses "Yes, post to PR", invoke the `muggle:muggle-pr-visual-walkthrough` skill via the `Skill` tool. With the `E2eReport` in context, the skill renders the markdown block via the CLI, finds the PR via `gh pr view`, posts `body` as a comment, posts the overflow `comment` only if the CLI emitted one, and confirms the PR URL to the user.
+Invoke the `muggle:muggle-pr-visual-walkthrough` skill via the `Skill` tool. With the `E2eReport` in context, the skill renders the markdown block via the CLI, posts `body` as a comment to the PR, posts the overflow `comment` only if the CLI emitted one, and confirms the PR URL to the user.
 
 Always use **Mode A** (post to existing PR) from this skill. Never hand-write the walkthrough markdown or call `gh pr comment` directly — delegate to `muggle:muggle-pr-visual-walkthrough`.