@muggleai/works 4.9.2 → 4.10.1

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

@@ -5,7 +5,9 @@ description: Run a real-browser end-to-end (E2E) acceptance test against localho
 
 # Muggle Test Feature Local
 
-**Goal:** Run or generate an end-to-end test against a **local URL** using Muggle's Electron browser.
+> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-test-feature-local"`.
+
+**Goal:** Run or generate an end-to-end test against a **local URL** using Muggle Test's Electron browser.
 
 | Scope | MCP tools |
 | :---- | :-------- |
@@ -15,55 +17,69 @@ description: Run a real-browser end-to-end (E2E) acceptance test against localho
 
 The local URL only changes where the browser opens; it does not change the remote project or test definitions.
 
-## UX Guidelines — Minimize Typing
+## Branch hygiene
 
-**Every selection-based question MUST use the `AskQuestion` tool** (or the platform's equivalent structured selection tool). Never ask the user to "reply with a number" in a plain text message — always present clickable options.
+Three gates apply, each per the standard procedure in [`preference-gates/README.md`](../muggle-preferences/preference-gates/README.md):
 
-- **Selections** (project, use case, test case, script): Use `AskQuestion` with labeled options the user can click.
-- **Free-text inputs** (URLs, descriptions): Only use plain text prompts when there is no finite set of options. Even then, offer a detected/default value when possible.
+- `autoUseWorktree` at pre-flight (see [`_shared/use-worktrees.md`](../_shared/use-worktrees.md)).
+- `autoRebase` before Step 7 (Execute) when `behind > 0` (see [`_shared/rebase-before-e2e.md`](../_shared/rebase-before-e2e.md)).
+- `autoCleanup` after the PR is merged (see [`_shared/post-merge-cleanup.md`](../_shared/post-merge-cleanup.md)).
 
-## Preferences
+## Local environment prerequisites
 
-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 ...`.
+Before any workflow step, invoke [`muggle-test-prepare`](../muggle-test-prepare/SKILL.md). Halt on what it surfaces.
 
-If no preferences line is present, treat all preferences as `"ask"`.
+## UX Guidelines — Minimize Typing
 
-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`.
+**Every selection-based question MUST use the `AskUserQuestion` tool** (or the platform's equivalent structured selection tool). Never ask the user to "reply with a number" in a plain text message — always present clickable options.
 
-This skill uses these preferences:
+- **Selections** (project, use case, test case, script): Use `AskUserQuestion` with labeled options the user can click.
+- **Free-text inputs** (URLs, descriptions): Only use plain text prompts when there is no finite set of options. Even then, offer a detected/default value when possible.
 
-| 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 |
+## Preferences
+
+Gates run per `preference-gates/README.md`.
+
+| Preference | Step | Decision it gates |
+|------------|------|-------------------|
+| `autoLogin` | 1 | Reuse saved credentials when auth is required |
+| `autoSelectProject` | 2 | Reuse last-used Muggle Test project for this repo |
+| `autoSelectLocalHost` | 4 | Reuse last-used local dev server URL for this repo |
+| `autoUseWorktree` | 0 (pre-flight) | Isolate dev work in a worktree (see [`_shared/use-worktrees.md`](../_shared/use-worktrees.md)) |
+| `autoRebase` | 0 (pre-flight) | Rebase onto `origin/<default>` before Step 7 (Execute) (see [`_shared/rebase-before-e2e.md`](../_shared/rebase-before-e2e.md)) |
+| `showElectronBrowser` | 7 | Show Electron browser window during local E2E tests |
+| `openTestResultsAfterRun` | 8 | Open results page on Muggle Test dashboard after run |
+| `postPRVisualWalkthrough` | 10 | Post visual walkthrough to PR after results |
+| `autoCreatePR` | 10 (if no PR) | Auto-create the PR when posting the walkthrough has no PR to target |
+| `autoCleanup` | post-merge | Run cleanup after the PR for this work is merged (see [`_shared/post-merge-cleanup.md`](../_shared/post-merge-cleanup.md)) |
 
 ## 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`):
+  - `always` → proceed with saved session.
+  - `never` → `muggle-remote-auth-login` with `forceNewSession: true`, then `muggle-remote-auth-poll`.
+  - `ask` → run Picker 1 from `preference-gates/autoLogin.md` via `AskUserQuestion`; map the answer back to one of the actions above.
+- 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 Test Last Project: id=… url=… name="…"` in session context.
+
+Gate `autoSelectProject` (per `preference-gates/README.md`). Cache: `Muggle Test 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`
 - `muggle-remote-use-case-list` (with `projectId`)
 - `muggle-remote-test-case-list-by-use-case` (with `useCaseId`)
 
-**Selection UI (mandatory):** Every selection MUST use `AskQuestion` with clickable options. Never ask the user to "reply with the number" in plain text.
+**Selection UI (mandatory):** Every selection MUST use `AskUserQuestion` with clickable options. Never ask the user to "reply with the number" in plain text.
 
 **Project selection context:** A **project** groups all your test results, use cases, and test scripts on the Muggle AI dashboard. Include the project URL in each option label so the user can identify the right one.
 
@@ -73,18 +89,18 @@ Prompt for projects: "Pick the project to group this test into:"
 
 - Do **not** dump the full list by default.
 - Rank items by semantic relevance to the user's stated goal (title first, then description / user story / acceptance criteria).
-- Show only the **top 3-5** most relevant options via `AskQuestion`, plus these fixed tail options:
-  - **"Show full list"** — present the complete list in a new `AskQuestion` call. **Skip this option** if the API returned zero rows.
+- Show only the **top 3-5** most relevant options via `AskUserQuestion`, plus these fixed tail options:
+  - **"Show full list"** — present the complete list in a new `AskUserQuestion` call. **Skip this option** if the API returned zero rows.
   - **"Create new ..."** — never omitted. Label per step: "Create new project", "Create new use case", or "Create new test case".
 
 **Create new — tools and flow (use these MCP tools; preview before persist):**
 
 - **Project — Create new project:** Collect `projectName`, `description`, and `url` (may be the local app URL, e.g. `http://localhost:3999`). Call `muggle-remote-project-create`. Use the returned `projectId` and continue.
 - **Use case — Create new use case:** User provides a natural-language instruction (or you reuse their testing goal).
-  1. `muggle-remote-use-case-prompt-preview` with `projectId`, `instruction` — show preview; get confirmation via `AskQuestion`.
+  1. `muggle-remote-use-case-prompt-preview` with `projectId`, `instruction` — show preview; get confirmation via `AskUserQuestion`.
   2. `muggle-remote-use-case-create-from-prompts` with `projectId` and `instructions: ["<the user's natural-language instruction>"]` — persist. Use the created use case id and continue to test-case selection.
 - **Test case — Create new test case** (requires a chosen `useCaseId`): User provides an instruction describing what to test.
-  1. `muggle-remote-test-case-generate-from-prompt` with `projectId`, `useCaseId`, `instruction` — **preview only** (server test-case prompt preview); show the returned draft(s); get confirmation via `AskQuestion`.
+  1. `muggle-remote-test-case-generate-from-prompt` with `projectId`, `useCaseId`, `instruction` — **preview only** (server test-case prompt preview); show the returned draft(s); get confirmation via `AskUserQuestion`.
   2. Persist the accepted draft with `muggle-remote-test-case-create`, mapping preview fields into the required properties (`title`, `description`, `goal`, `expectedResult`, `url`, etc.). Then continue from **section 5** with that `testCaseId`.
 
 ### 3. Ensure Local Services Are Ready
@@ -98,13 +114,16 @@ Before detecting the local URL, verify that the services the user needs are actu
 
 This step is especially important when the user's app depends on sibling services (a backend API, an auth service, etc.) that may not be running yet. The prepare skill handles discovery, startup, and cleanup so this skill doesn't have to.
 
-### 4. Local URL
+**Compile-gate (do not skip)** — after `muggle-test-prepare` reports ready, run the two-stage readiness probe per [`_shared/dev-server-readiness.md`](../_shared/dev-server-readiness.md) before dispatching any test. Halt on any failure it surfaces; do not dispatch against a broken bundle.
+
+### 4. Local URL (gated by `autoSelectLocalHost`)
 
-Try to auto-detect the dev server URL by checking running terminals or common ports (e.g., `lsof -iTCP -sTCP:LISTEN -nP | grep -E ':(3000|3001|4200|5173|8080)'`). If a likely URL is found, present it as a clickable default via `AskQuestion`:
-- Option 1: "http://localhost:3000" (or whatever was detected)
-- Option 2: "Other — let me type a URL"
+Skill responsibilities (the rest is in `preference-gates/autoSelectLocalHost.md`):
+- **Read the cache**: `Muggle Test Last Host: <url>` session-context line, or `muggle-local-last-host-get`. Pass as `{lastHost}` substitution.
+- **Auto-detect a suggested URL**: `lsof -iTCP -sTCP:LISTEN -nP | grep -E ':(3000|3001|4200|5173|8080)'`. Pass as `{suggestedHost}`.
+- **Save the cache**: call `muggle-local-last-host-set` after the user picks (the gate file requires this on every pick).
 
-If nothing detected, ask as free text: "Your local app should be running. What's the URL? (e.g., http://localhost:3000)"
+Gate `autoSelectLocalHost` per `preference-gates/README.md` + `preference-gates/autoSelectLocalHost.md`.
 
 Remind them: local URL is only the execution target, not tied to cloud project config.
 
@@ -112,7 +131,7 @@ Remind them: local URL is only the execution target, not tied to cloud project c
 
 `muggle-remote-test-script-list` with `testCaseId`.
 
-- **If any replayable/succeeded scripts exist:** use `AskQuestion` to present them as clickable options. Show: name, created/updated, step count per option. Include **"Generate new script"** as the last option.
+- **If any replayable/succeeded scripts exist:** use `AskUserQuestion` to present them as clickable options. Show: name, created/updated, step count per option. Include **"Generate new script"** as the last option.
 - **If none:** go straight to generation (no need to ask replay vs generate).
 
 ### 6. Load data for the chosen path
@@ -153,71 +172,58 @@ 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. The browser defaults to visible; only pass `showUi: false` if the user explicitly asked for headless.
+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.
 
-### 8. After successful generation only
+Gate `showElectronBrowser` (per `preference-gates/README.md`). Reuse choice within a session.
+- `always` → omit `showUi`.
+- `never` → pass `showUi: false`.
+- `ask` → run Picker 1 from `preference-gates/showElectronBrowser.md` via `AskUserQuestion`; map the answer back to one of the actions above.
+
+### 8. Upload run to cloud (every completed run; open `viewUrl` gated by `openTestResultsAfterRun`)
+
+Upload pass-or-fail. Failed runs still need cloud-hosted screenshots and per-step actions for the PR walkthrough — without them reviewers see only a generic "failed" link. The `status` field in the upload payload tells the backend whether to promote the run's action script as the test case's canonical replay script (passed → promote; failed → record only).
 
 - `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`):
+  - `always` → open `viewUrl` automatically (`open "<viewUrl>"` on macOS or OS equivalent).
+  - `never` → print the URL only.
+  - `ask` → run Picker 1 from `preference-gates/openTestResultsAfterRun.md` via `AskUserQuestion`; map the answer back to one of the actions above.
+
+If publish rejects with `has no generated actionScript steps to publish` (true zero-step runs — Electron never produced an action), fall back to `muggle-remote-local-run-upload` directly with whatever data exists (`summaryStep`, `errorMessage`, empty `actionScript`). This still gets the failure summary and any goal-not-achievable verdict onto the dashboard so reviewers can see why the run failed. Capture the returned `actionScriptId` and `viewUrl` from this fallback path the same way you would from publish.
 
 ### 9. Report
 
 - `muggle-local-run-result-get` with the run id from execute.
 - Include: status, duration, pass/fail summary, per-step summary, artifact/screenshot paths, errors if failed, and script view URL when publishing ran.
 
-### 10. Offer to post a visual walkthrough to the PR
-
-After reporting results, gather the required input and hand off to the shared **`muggle:muggle-pr-visual-walkthrough`** skill, which renders the walkthrough via `muggle build-pr-section` and posts it to the current branch's open PR.
-
-#### 10a: Gather per-step screenshots
+### 9a. Route failures through the failure-mode handler
 
-The shared skill takes an **`E2eReport` JSON** that includes per-step screenshot URLs. After step 8 has called `muggle-local-publish-test-script` and you have the `testScriptId`:
+If the run's status is `failed` or any non-passing terminal state, follow [`_shared/failure-mode-handling.md`](../_shared/failure-mode-handling.md):
 
-1. Call `muggle-remote-test-script-get` with the `testScriptId`.
-2. Extract per step: `steps[].operation.action` and `steps[].operation.screenshotUrl`.
-3. Build the `steps` array: `[{ stepIndex: 0, action: "...", screenshotUrl: "..." }, ...]`.
-4. If the run failed, capture `failureStepIndex`, `error`, and the local `artifactsDir` from the run result in step 9.
-5. Populate `description` (test case title/description) and `useCaseName` (parent use case title) on the report entry — optional but strongly recommended; they drive the grouped overview and the per-test collapsible headers. Prefer values already in your conversation context from earlier steps (e.g. the test case you just created or selected, or the use case you confirmed); only call `muggle-remote-test-case-get` / `muggle-remote-use-case-get` for anything you don't already have.
+- **Replay-mode run failed** (the user picked an existing script in Step 5) → section B (buckets: `infra` / `stale-script` / `product-defect`).
+- **Regen-mode run failed** (the user picked "Generate new script" or no script existed) → section C (buckets: `transient` / `infra` / `agent-course` / `product-uxux`).
 
-Assemble the `E2eReport`:
+Steps:
+1. Read the run via `muggle-local-run-result-get` and extract signals per the heuristics in the shared doc.
+2. Emit `replay-failure-classified` or `regen-failure-classified` via `muggle-local-telemetry-event-emit` **before** asking the user.
+3. Present the recommended action via `AskUserQuestion` with the alternatives the shared doc lists for that bucket.
+4. After the user picks, emit the matching `*-resolved` event with `userAction`.
 
-```json
-{
-  "projectId": "<projectId from step 2 (Targets)>",
-  "tests": [
-    {
-      "name": "<test case title>",
-      "description": "<one-line description of what this test verifies (optional but recommended)>",
-      "useCaseName": "<parent use case title (optional but recommended)>",
-      "testCaseId": "<id>",
-      "testScriptId": "<id from publish>",
-      "runId": "<runId from execute>",
-      "viewUrl": "<viewUrl from publish>",
-      "status": "passed",
-      "steps": [{ "stepIndex": 0, "action": "...", "screenshotUrl": "..." }]
-    }
-  ]
-}
-```
+If the user picks `muggle-feedback` from any bucket's options, invoke the `muggle-feedback` skill via the `Skill` tool, passing the just-finished `runId` so the submit flow opens with this run preloaded.
 
-See the `muggle:muggle-pr-visual-walkthrough` skill for the full schema including the failed-test shape.
+Skip silently when the run passed cleanly — failure-mode events are by definition about failures.
 
-#### 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."
-
-- Option 1: "Yes, post to PR"
-- Option 2: "Skip"
-
-#### 10c: Invoke the shared skill in Mode A
+### 10. Offer to post a visual walkthrough to the PR
 
-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.
+After reporting results:
 
-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`.
+1. Fire [`postPRVisualWalkthrough`](../muggle-preferences/preference-gates/postPRVisualWalkthrough.md). On skip → end.
+2. `gh pr view --json number,title,url 2>/dev/null` — find the PR.
+3. If no PR: fire [`autoCreatePR`](../muggle-preferences/preference-gates/autoCreatePR.md). On skip → end.
+4. Assemble the `E2eReport` — see [`../muggle-pr-visual-walkthrough/e2e-report-assembly.md`](../muggle-pr-visual-walkthrough/e2e-report-assembly.md).
+5. Invoke [`../muggle-pr-visual-walkthrough/SKILL.md`](../muggle-pr-visual-walkthrough/SKILL.md) Mode A with the `E2eReport`.
 
 ## Non-negotiables
 
@@ -226,6 +232,6 @@ Always use **Mode A** (post to existing PR) from this skill. Never hand-write th
 - If replayable scripts exist, do not default to generation without user choice.
 - No hiding failures: surface errors and artifact paths.
 - Replay: never hand-built or simplified `actionScript` — only from `muggle-remote-action-script-get`.
-- Use `AskQuestion` for every selection — project, use case, test case, script. Never ask the user to type a number.
+- Use `AskUserQuestion` for every selection — project, use case, test case, script. Never ask the user to type a number.
 - Project, use case, and test case selection lists must always include "Create new ...". Include "Show full list" whenever the API returned at least one row for that step; omit "Show full list" when the list is empty (offer "Create new ..." only). For creates, use preview tools (`muggle-remote-use-case-prompt-preview`, `muggle-remote-test-case-generate-from-prompt`) before persisting.
 - PR posting is always optional and always delegated to the `muggle:muggle-pr-visual-walkthrough` skill — never inline the walkthrough markdown or call `gh pr comment` directly from this skill.

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

@@ -4,39 +4,32 @@ description: >
   Bring existing tests and test artifacts INTO Muggle Test — from Playwright, Cypress, PRDs,
   Gherkin feature files, test plan docs, Notion exports, or any source.
   TRIGGER when: user wants to import/migrate/load/upload/add/convert existing test files or
-  test docs into Muggle — e.g. "import my playwright tests", "migrate from cypress to muggle",
+  test docs into Muggle Test — e.g. "import my playwright tests", "migrate from cypress to muggle",
   "upload my PRD to muggle", "add my e2e specs to our muggle project", "load these test cases
   into muggle", "turn this feature file into muggle test cases", "create muggle test cases from
   my PRD", "track my specs in muggle", or any .spec.ts/.cy.js/.feature/.md file + muggle.
-  DO NOT TRIGGER when: user wants to run/replay Muggle scripts, scan a site, generate new
+  DO NOT TRIGGER when: user wants to run/replay Muggle Test scripts, scan a site, generate new
   tests from scratch, or check existing test results.
 ---
 
 # Muggle Test Import
 
+> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-test-import"`.
+
 This skill migrates existing test artifacts into Muggle Test. It reads your source files,
 structures them into use cases and test cases, gets your approval, then creates everything
-in a Muggle project via the API.
+in a Muggle Test project via the API.
 
 ## 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`.
+Gates run per `preference-gates/README.md`.
 
-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 |
-| `suggestRelatedUseCases` | Suggest related use cases after import |
-| `suggestRelatedTestCases` | Suggest related test cases after import |
+| Preference | Step | Decision it gates |
+|------------|------|-------------------|
+| `autoLogin` | 4 | Reuse saved credentials when auth is required |
+| `autoSelectProject` | 5 | Reuse last-used Muggle Test project for this repo |
+| `suggestRelatedUseCases` | 8a | Suggest related use cases after import |
+| `suggestRelatedTestCases` | 8b | Suggest related test cases after import |
 
 ## Concepts
 
@@ -70,7 +63,7 @@ The extraction strategy depends on the file type. Choose the right path before r
 
 ### Path A — PRD / design documents (preferred for document sources)
 
-Muggle has a native PRD processing workflow that extracts use cases more accurately than
+Muggle Test has a native PRD processing workflow that extracts use cases more accurately than
 manual parsing. Use this path for `.md`, `.txt`, `.pdf`, or any prose document.
 
 After authentication and project selection (Steps 4–5), come back and:
@@ -134,26 +127,26 @@ Found 3 use cases with 8 test cases:
    ✦ [HIGH]   Checkout fails with invalid payment info
 ```
 
-Use `AskQuestion` to confirm:
+Use `AskUserQuestion` to confirm:
 - "Looks good — proceed with import"
 - "I want to make changes first"
 
 If the user wants changes, incorporate feedback, then ask again. Only proceed after explicit approval.
 
-> For Path A (native PRD upload): present the use case/test case list that Muggle extracted
+> For Path A (native PRD upload): present the use case/test case list that Muggle Test extracted
 > after the processing workflow completes, and ask the user to confirm before adding any
 > extra test cases manually.
 
 ---
 
-## Step 4 — Authenticate
+## Step 4 — Authenticate (gated by `autoLogin`)
 
 Call `muggle-remote-auth-status` first.
 
-If **already authenticated** → print the logged-in email and ask via `AskQuestion`:
-> "You're logged in as **{email}**. Continue with this account?"
-- Option 1: "Yes, continue" → skip to Step 5.
-- Option 2: "No, switch account" → call `muggle-remote-auth-login` with `forceNewSession: true`, then `muggle-remote-auth-poll`.
+If **already authenticated** → gate `autoLogin` (per `preference-gates/README.md`):
+- `always` → skip to Step 5.
+- `never` → `muggle-remote-auth-login` with `forceNewSession: true`, then `muggle-remote-auth-poll`.
+- `ask` → run Picker 1 from `preference-gates/autoLogin.md` via `AskUserQuestion`; map the answer back to one of the actions above.
 
 If **not authenticated**:
 1. Tell the user a browser window is about to open.
@@ -163,14 +156,23 @@ If **not authenticated**:
 
 ---
 
-## Step 5 — Pick or create a project
+## Step 5 — Pick or create a project (gated by `autoSelectProject`)
 
 A **project** is where all your imported use cases, test cases, and future test results are grouped on the Muggle AI dashboard.
 
-1. Call `muggle-remote-project-list`
-2. Use `AskQuestion` to present all projects as clickable options. Include the project URL in each label. Always include a "Create new project" option at the end.
+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 Test Last Project: id=… url=… name="…"` in session context.
+
+Gate `autoSelectProject` (per `preference-gates/README.md`). Cache: `Muggle Test Last Project` session line.
+- `always` + cache → use cached `projectId`, skip to Step 6. 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 import into:"
+### Logic
+
+1. Call `muggle-remote-project-list` (only when not satisfied by the `always` cache).
+2. Use `AskUserQuestion` to present all projects as clickable options. Include the project URL in each label. Always include a "Create new project" option at the end.
+
+   Prompt: `"Pick the project to import into:"`
 
 3. **If creating a new project**, propose values based on what you learned from the source files:
    - **Name**: infer the app name from filenames, URLs, or document headings (e.g., "Acme App")
@@ -185,12 +187,12 @@ A **project** is where all your imported use cases, test cases, and future test
 
 Import in two passes using bulk-preview. Show progress to the user as you go.
 
-Both passes use Muggle's async bulk-preview MCP tools, which route prompts through OpenAI's
+Both passes use Muggle Test's async bulk-preview MCP tools, which route prompts through OpenAI's
 Batch API for roughly ~50% of normal LLM cost. The flow is always: **submit → poll → persist**.
 
 ### Path A — Native PRD upload (for document files)
 
-If the source is a PRD or design document, use Muggle's built-in processing pipeline:
+If the source is a PRD or design document, use Muggle Test's built-in processing pipeline:
 
 1. Read the file and base64-encode its content:
    ```bash
@@ -274,7 +276,7 @@ Failed items:
 
 Proceed with the <N> successful items, or cancel to review?
 ```
-Use `AskQuestion` with options "Proceed with successful items" / "Cancel import". Only continue
+Use `AskUserQuestion` with options "Proceed with successful items" / "Cancel import". Only continue
 if the user chooses to proceed.
 
 If you need to abort an in-flight job, call `muggle-remote-bulk-preview-job-cancel` — the
@@ -366,7 +368,7 @@ When all imports are done, print a clean summary. Include:
 - A link to the project overview
 - If any items failed during preview (partial status), list them so the user can retry
 
-Construct view URLs using the Muggle dashboard URL pattern:
+Construct view URLs using the Muggle Test dashboard URL pattern:
 - Project test cases: `https://www.muggle-ai.com/muggleTestV0/dashboard/projects/<projectId>/testcases`
 - Use case within project: `https://www.muggle-ai.com/muggleTestV0/dashboard/projects/<projectId>/testcases?useCaseId=<useCaseId>`
 
@@ -392,3 +394,40 @@ Imported: 3 use cases · 8 test cases
 
 Next step: run /muggle:do to generate executable browser test scripts for these test cases.
 ```
+
+### Step 8 — Optional follow-up suggestions
+
+Two preferences gate optional follow-ups: `suggestRelatedUseCases` and `suggestRelatedTestCases`. Both are independent — handle each in turn.
+
+#### 8a — Related use cases (gated by `suggestRelatedUseCases`)
+
+The query is: "from the use cases already in this project, which ones are *not* in the import set but look related to it?" — surface them so the user can decide whether their import missed something the project already tracks.
+
+Gate `suggestRelatedUseCases` (per `preference-gates/README.md`):
+- `always` → run the query below.
+- `never` → skip.
+- `ask` → run Picker 1 from `preference-gates/suggestRelatedUseCases.md` via `AskUserQuestion`; map the answer back to one of the actions above.
+
+When running the query:
+1. Call `muggle-remote-use-case-list` for the project.
+2. Filter out any use case whose `useCaseId` is in the set you just imported in Step 6 (Pass 1).
+3. Rank the remainder by semantic relevance to the imported titles/descriptions (substring overlap, shared keywords — best-effort, no LLM call needed).
+4. Present the top 3-5 via `AskUserQuestion` with `allow_multiple: true`. Label each with `<title> — <one-line description>`.
+5. For any the user selects, prompt to add follow-up test cases (treat each as a Pass 2 invocation: `muggle-remote-test-case-bulk-preview-submit` → poll → persist via `muggle-remote-test-case-create`).
+6. If the filtered list is empty (the import covers everything in the project), say so and skip.
+
+#### 8b — Related test cases (gated by `suggestRelatedTestCases`)
+
+For each use case the user just created, surface other test cases already attached that the import didn't add — same idea, scoped to a single use case.
+
+Gate `suggestRelatedTestCases` (per `preference-gates/README.md`):
+- `always` → run the query below.
+- `never` → skip.
+- `ask` → run Picker 1 from `preference-gates/suggestRelatedTestCases.md` via `AskUserQuestion`; map the answer back to one of the actions above.
+
+When running the query, for each use case in the import:
+1. Call `muggle-remote-test-case-list-by-use-case` with that `useCaseId`.
+2. Filter out any test case you just created in Pass 2 of Step 6.
+3. Present the remainder via `AskUserQuestion` with `allow_multiple: true`, labeled `[<priority>] <title> — <goal>`.
+4. For any the user selects: nothing to create (they already exist) — just confirm to the user that those tests are now part of their Muggle Test project alongside the imported ones.
+5. If a use case has no extra test cases, skip it silently.