@muggleai/works 4.3.0 → 4.4.0

package/plugin/skills/do/open-prs.md

@@ -27,90 +27,96 @@ For each repo with changes:
    - `## Goal` — the requirements goal
    - `## Acceptance Criteria` — bulleted list (omit section if empty)
    - `## Changes` — summary of what changed in this repo
-   - `## E2E Acceptance Results` — summary table (see format below)
+   - E2E acceptance evidence block from `muggle build-pr-section` (see "Rendering the E2E acceptance results block" below)
 4. **Create the PR** using `gh pr create --title "..." --body "..." --head <branch>` in the repo directory.
 5. **Capture the PR URL** and extract the PR number.
-6. **Post E2E acceptance evidence comment** with screenshots (see format below).
-
-## E2E acceptance results section format (PR body)
-
-```markdown
-## E2E Acceptance Results
-
-**X passed / Y failed**
-
-| Test Case | Status | Details |
-|-----------|--------|---------|
-| [Name]({viewUrl}) | ✅ PASSED | — |
-| [Name]({viewUrl}) | ❌ FAILED | {error} |
+6. **Post the overflow comment only if `muggle build-pr-section` emitted one** (see "Rendering the E2E acceptance results block" below). In the common case, no comment is posted.
+
+## Rendering the E2E acceptance results block
+
+Do **not** hand-write the `## E2E Acceptance Results` markdown. Use the `muggle build-pr-section` CLI, which renders a deterministic block and decides whether the evidence fits in the PR description or needs to spill into an overflow comment.
+
+### Step A: Build the report JSON
+
+Assemble the e2e-acceptance report you collected in `e2e-acceptance.md` into a JSON object with this shape:
+
+```json
+{
+  "projectId": "<project UUID>",
+  "tests": [
+    {
+      "name": "<test case name>",
+      "testCaseId": "<UUID>",
+      "testScriptId": "<UUID or omitted>",
+      "runId": "<UUID>",
+      "viewUrl": "<muggle-ai.com run URL>",
+      "status": "passed",
+      "steps": [
+        { "stepIndex": 0, "action": "<action>", "screenshotUrl": "<URL>" }
+      ]
+    },
+    {
+      "name": "<test case name>",
+      "testCaseId": "<UUID>",
+      "runId": "<UUID>",
+      "viewUrl": "<muggle-ai.com run URL>",
+      "status": "failed",
+      "failureStepIndex": 2,
+      "error": "<error message>",
+      "artifactsDir": "<path, optional>",
+      "steps": [
+        { "stepIndex": 0, "action": "<action>", "screenshotUrl": "<URL>" }
+      ]
+    }
+  ]
+}
 ```
 
-## E2E acceptance evidence comment format
+### Step B: Render the evidence block
 
-After creating the PR, post a comment with embedded screenshots:
+Pipe the JSON into `muggle build-pr-section`. It writes `{ "body": "...", "comment": "..." | null }` to stdout:
 
 ```bash
-gh pr comment <PR#> --body "$(cat <<'EOF'
-## 🧪 E2E acceptance evidence
-
-**X passed / Y failed**
-
-| Test Case | Status | Summary |
-|-----------|--------|---------|
-| [Login Flow]({viewUrl}) | ✅ PASSED | <a href="{lastStepScreenshotUrl}"><img src="{lastStepScreenshotUrl}" width="120"></a> |
-| [Checkout]({viewUrl}) | ❌ FAILED | <a href="{failureStepScreenshotUrl}"><img src="{failureStepScreenshotUrl}" width="120"></a> |
-
-<details>
-<summary>📸 <strong>Login Flow</strong> — 5 steps</summary>
-
-| # | Action | Screenshot |
-|---|--------|------------|
-| 1 | Navigate to `/login` | <a href="{screenshotUrl}"><img src="{screenshotUrl}" width="200"></a> |
-| 2 | Enter username | <a href="{screenshotUrl}"><img src="{screenshotUrl}" width="200"></a> |
-| 3 | Click "Sign In" | <a href="{screenshotUrl}"><img src="{screenshotUrl}" width="200"></a> |
+echo "$REPORT_JSON" | muggle build-pr-section > /tmp/muggle-pr-section.json
+```
 
-</details>
+The command exits nonzero on malformed input and writes a descriptive error to stderr — do not swallow that error, surface it to the user.
 
-<details>
-<summary>📸 <strong>Checkout</strong> — 4 steps (failed at step 3)</summary>
+### Step C: Build the PR body
 
-| # | Action | Screenshot |
-|---|--------|------------|
-| 1 | Add item to cart | <a href="{screenshotUrl}"><img src="{screenshotUrl}" width="200"></a> |
-| 2 | View cart | <a href="{screenshotUrl}"><img src="{screenshotUrl}" width="200"></a> |
-| 3 ⚠️ | Click confirm — **Element not found** | <a href="{screenshotUrl}"><img src="{screenshotUrl}" width="200"></a> |
+Build the PR body by concatenating, in order:
 
-</details>
-EOF
-)"
-```
+- `## Goal` — the requirements goal
+- `## Acceptance Criteria` — bulleted list (omit section if empty)
+- `## Changes` — summary of what changed in this repo
+- The `body` field from the CLI output (already contains its own `## E2E Acceptance Results` header)
 
-### Comment Building Rules
+### Step D: Create the PR, then post the overflow comment only if present
 
-1. **Summary table:**
-   - Show thumbnail (120px) of **last step** for passed tests
-   - Show thumbnail of **failure step** for failed tests
-   - Thumbnail links to full-size image
+1. Create the PR with `gh pr create --title "..." --body "..." --head <branch>`.
+2. Capture the PR URL and extract the PR number.
+3. If the CLI output's `comment` field is `null`, **do not post a comment** — everything is already in the PR description.
+4. If the CLI output's `comment` field is a non-null string, post it as a follow-up comment:
 
-2. **Collapsible details per test case:**
-   - Show all steps with 200px thumbnails
-   - Mark failure step with ⚠️ and inline error message
-   - Include step count in summary line
+   ```bash
+   gh pr comment <PR#> --body "$(cat <<'EOF'
+   <comment field contents>
+   EOF
+   )"
+   ```
 
-3. **HTML for thumbnails:**
-   - Use `<a href="{url}"><img src="{url}" width="N"></a>` for clickable thumbnails
-   - 120px width in summary table, 200px in details
+### Notes on fit vs. overflow
 
-4. **All tests get screenshots:**
-   - Passing tests show proof of success
-   - Failing tests highlight the failure point
+- **The common case is fit**: the full evidence (summary, per-test rows, collapsible failure details) lives in the PR description, no comment is posted.
+- **The overflow case** is triggered automatically when the full inline body would exceed the CLI's budget. In that case the PR description contains the summary, the per-test rows, and a pointer line; the full step-by-step failure details live in the follow-up comment.
+- You do not make the fit-vs-overflow decision — the CLI does. Never post the comment speculatively.
 
 ## Output
 
 **PRs Created:**
 - (repo name): (PR URL)
 
-**E2E acceptance evidence comments posted:**
+**E2E acceptance overflow comments posted:** (only include repos where an overflow comment was actually posted)
 - (repo name): comment posted to PR #(number)
 
 **Errors:** (any repos where PR creation or comment posting failed, with the error message)

package/plugin/skills/muggle/SKILL.md

@@ -9,24 +9,24 @@ Use this as the top-level Muggle command router.
 
 ## Menu
 
-When user asks for "muggle" with no specific subcommand, show this command set:
+When user asks for "muggle" with no specific subcommand, use `AskQuestion` to present the command set as clickable options:
 
-- `/muggle:muggle-do` — autonomous dev pipeline
-- `/muggle:muggle-test` — change-driven E2E acceptance testing (local or remote, with PR posting)
-- `/muggle:muggle-test-feature-local` — local feature E2E acceptance testing
-- `/muggle:muggle-status` — health check
-- `/muggle:muggle-repair` — repair broken installation
-- `/muggle:muggle-upgrade` — upgrade local installation
+- "Test my changes — change-driven E2E acceptance testing (local or remote)" → `muggle-test`
+- "Test a feature on localhost — run a single E2E test locally" → `muggle-test-feature-local`
+- "Autonomous dev pipeline — requirements to PR" → `muggle-do`
+- "Health check — verify installation status" → `muggle-status`
+- "Repair — fix broken installation" → `muggle-repair`
+- "Upgrade — update to latest version" → `muggle-upgrade`
 
 ## Routing
 
-If the user intent clearly matches one command, route to that command behavior:
+If the user intent clearly matches one command, route directly — no menu needed:
 
-- status/health/check -> `muggle-status`
-- repair/fix/install broken -> `muggle-repair`
-- upgrade/update latest -> `muggle-upgrade`
-- test my changes/acceptance test my work/test before push/post E2E acceptance results to PR/test on staging/test on preview -> `muggle-test`
-- test localhost/validate single feature -> `muggle-test-feature-local`
-- build/implement from request -> `muggle-do`
+- status/health/check → `muggle-status`
+- repair/fix/install broken → `muggle-repair`
+- upgrade/update latest → `muggle-upgrade`
+- test my changes/acceptance test my work/test before push/post E2E acceptance results to PR/test on staging/test on preview → `muggle-test`
+- test localhost/validate single feature → `muggle-test-feature-local`
+- build/implement from request → `muggle-do`
 
-If intent is ambiguous, ask one concise clarification question.
+If intent is ambiguous, use `AskQuestion` with the most likely options rather than asking the user to type a clarification.

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

@@ -7,6 +7,15 @@ description: "Run change-driven E2E acceptance testing using Muggle AI — detec
 
 A router skill that detects code changes, resolves impacted test cases, executes them locally or remotely, publishes results to the Muggle AI dashboard, and posts E2E acceptance summaries to the PR. The user can invoke this at any moment, in any state.
 
+## UX Guidelines — Minimize Typing
+
+**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.
+
+- **Selections** (project, use case, test case, mode, approval): Use `AskQuestion` with labeled options the user can click.
+- **Multi-select** (use cases, test cases): Use `AskQuestion` with `allow_multiple: true`.
+- **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.
+- **Batch related questions**: If two questions are independent, present them together in a single `AskQuestion` call rather than asking sequentially.
+
 ## Step 1: Confirm Scope of Work (Always First)
 
 Parse the user's query and explicitly confirm their expectation. There are exactly two modes:
@@ -27,23 +36,13 @@ Signs the user wants this: mentions "preview", "staging", "deployed", "preview U
 
 ### Confirming
 
-If the user's intent is clear, state back what you understood and ask for confirmation:
-```
-I'll run [local/remote] test generation. Confirm?
-──────────────────────────────────────────────────────────────
-1. Yes, proceed
-2. No, switch to [the other mode]
-──────────────────────────────────────────────────────────────
-```
+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]"
 
-If ambiguous, ask the user to choose:
-```
-How do you want to run the test?
-──────────────────────────────────────────────────────────────
-1. Local — launch browser on your machine against localhost
-2. Remote — Muggle cloud tests against a preview/staging URL
-──────────────────────────────────────────────────────────────
-```
+If ambiguous, use `AskQuestion` to let the user choose:
+- Option 1: "Local — launch browser on your machine against localhost"
+- Option 2: "Remote — Muggle cloud tests against a preview/staging URL"
 
 Only proceed after the user selects an option.
 
@@ -75,26 +74,21 @@ If auth fails repeatedly, suggest: `muggle logout && muggle login` from terminal
 
 ## Step 4: Select Project (User Must Choose)
 
+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. Present **all** projects as a numbered 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.
 
-```
-Available Muggle Projects:
-──────────────────────────────────────────────────────────────
-1. MUGGLE AI STAGING 1       https://staging.muggle-ai.com/
-2. Tanka Testing             https://www.tanka.ai
-3. Staging muggleTestV0      https://staging.muggle-ai.com/muggleTestV0
-4. [Create new project]
-──────────────────────────────────────────────────────────────
-```
+   Example labels:
+   - "MUGGLE AI STAGING 1 — https://staging.muggle-ai.com/"
+   - "Tanka Testing — https://www.tanka.ai"
+   - "Create new project"
 
-> "Which project should I use? Reply with the number."
+   Prompt: "Pick the project to group this test run into:"
 
 3. **Wait for the user to explicitly choose** — do NOT auto-select based on repo name or URL matching
 4. **If user chooses "Create new project"**:
-   - Ask for `projectName`
-   - Ask for `description`
-   - Ask for the production/preview URL
+   - Ask for `projectName`, `description`, and the production/preview URL
    - Call `muggle-remote-project-create`
 
 Store the `projectId` only after user confirms.
@@ -104,21 +98,11 @@ Store the `projectId` only after user confirms.
 ### 5a: List existing use cases
 Call `muggle-remote-use-case-list` with the project ID.
 
-### 5b: Present ALL use cases as a numbered list for user selection
+### 5b: Present ALL use cases for user selection
 
-```
-Available Use Cases for [Project Name]:
-──────────────────────────────────────────────────────────────────────────
-1. Sign up for Muggle Test account
-2. Access existing account via login
-3. Manually Add a Use Case
-4. View Generated Test Script After Test Run
-5. Generate comprehensive UX testing reports
-6. [Create new use case]
-──────────────────────────────────────────────────────────────────────────
-```
+Use `AskQuestion` with `allow_multiple: true` to present all use cases as clickable options. Always include a "Create new use case" option at the end.
 
-> "Which use case do you want to test? Reply with the number (or multiple numbers separated by commas)."
+Prompt: "Which use case(s) do you want to test?"
 
 ### 5c: Wait for explicit user selection
 
@@ -143,19 +127,11 @@ For the selected use case(s):
 ### 6a: List existing test cases
 Call `muggle-remote-test-case-list-by-use-case` with each use case ID.
 
-### 6b: Present ALL test cases as a numbered list for user selection
+### 6b: Present ALL test cases for user selection
 
-```
-Available Test Cases for "[Use Case Name]":
-──────────────────────────────────────────────────────────────────────────
-1. E2E: Login with valid credentials
-2. E2E: Login with invalid password
-3. E2E: Login with expired session
-4. [Generate new test case]
-──────────────────────────────────────────────────────────────────────────
-```
+Use `AskQuestion` with `allow_multiple: true` to present all test cases as clickable options. Always include a "Generate new test case" option at the end.
 
-> "Which test case(s) do you want to run? Reply with the number (or multiple numbers separated by commas)."
+Prompt: "Which test case(s) do you want to run?"
 
 ### 6c: Wait for explicit user selection
 
@@ -170,40 +146,34 @@ Available Test Cases for "[Use Case Name]":
 
 ### 6e: Confirm final selection
 
-> "You selected [N] test case(s): [list titles]. Ready to proceed?"
+Use `AskQuestion` to confirm: "You selected [N] test case(s): [list titles]. Ready to proceed?"
+- Option 1: "Yes, run them"
+- Option 2: "No, let me re-select"
 
 Wait for user confirmation before moving to execution.
 
 ## Step 7A: Execute — Local Mode
 
-### Three separate questions (ask one at a time, wait for answer before next)
+### Pre-flight questions (batch where possible)
 
 **Question 1 — Local URL:**
-> "Your local app should be running. What's the URL? (e.g., http://localhost:3000)"
 
-Wait for user to provide URL before asking question 2.
+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"
 
-**Question 2 — Electron launch approval:**
-```
-I'll launch the Muggle Electron browser to run [N] test case(s).
-──────────────────────────────────────────────────────────────
-1. Yes, launch it
-2. No, cancel
-──────────────────────────────────────────────────────────────
-```
+If nothing detected, ask as free text: "Your local app should be running. What's the URL? (e.g., http://localhost:3000)"
 
-Wait for "1" before asking question 3. If "2", stop and ask what they want to do instead.
+**Question 2 — Electron launch + window visibility (ask together):**
 
-**Question 3 — Window visibility:**
-```
-How should the browser window appear?
-──────────────────────────────────────────────────────────────
-1. Visible (watch the browser as it runs)
-2. Headless (run in background)
-──────────────────────────────────────────────────────────────
-```
+After getting the URL, use a single `AskQuestion` call with two questions:
+
+1. "Ready to launch the Muggle Electron browser for [N] test case(s)?"
+   - "Yes, launch it (visible — I want to watch)"
+   - "Yes, launch it (headless — run in background)"
+   - "No, cancel"
 
-Wait for answer (1 or 2) before proceeding.
+If user cancels, stop and ask what they want to do instead.
 
 ### Run sequentially
 
@@ -213,8 +183,8 @@ For each test case:
 2. Call `muggle-local-execute-test-generation`:
    - `testCase`: Full test case object from step 1
    - `localUrl`: User's local URL (from Question 1)
-   - `approveElectronAppLaunch`: `true` (only if user said "yes" in Question 2)
-   - `showUi`: `true` if user chose "visible", `false` if "headless" (from Question 3)
+   - `approveElectronAppLaunch`: `true` (only if user approved in Question 2)
+   - `showUi`: `true` if user chose "visible", `false` if "headless" (from Question 2)
 3. Store the returned `runId`
 
 If a generation fails, log it and continue to the next. Do not abort the batch.
@@ -320,16 +290,9 @@ gh pr view --json number,url,title 2>/dev/null
 ```
 
 - If a PR exists → post results as a comment
-- If no PR exists → ask:
-```
-No open PR found for this branch.
-──────────────────────────────────────────────────────────────
-1. Create PR with E2E acceptance results
-2. Skip posting to PR
-──────────────────────────────────────────────────────────────
-```
-  - If 1: create PR with E2E acceptance results in the body (use `gh pr create`)
-  - If 2: skip this step
+- If no PR exists → use `AskQuestion`:
+  - "Create PR with E2E acceptance results"
+  - "Skip posting to PR"
 
 ### 9b: Build the E2E acceptance comment body
 
@@ -403,10 +366,11 @@ If creating a new PR — include the E2E acceptance section in the PR body along
 ## Guardrails
 
 - **Always confirm intent first** — never assume local vs remote without asking
-- **User MUST select project** — present numbered list, wait for explicit choice, never auto-select
-- **User MUST select use case(s)** — present numbered list, wait for explicit choice, never auto-select based on git changes or heuristics
-- **User MUST select test case(s)** — present numbered list, wait for explicit choice, never auto-select
-- **Ask three separate questions for local mode** — (1) URL as text input, (2) Electron approval as numbered choice, (3) visibility as numbered choice — one at a time, wait for each answer
+- **User MUST select project** — present clickable options via `AskQuestion`, wait for explicit choice, never auto-select
+- **User MUST select use case(s)** — present clickable options via `AskQuestion`, wait for explicit choice, never auto-select based on git changes or heuristics
+- **User MUST select test case(s)** — present clickable options via `AskQuestion`, wait for explicit choice, never auto-select
+- **Use `AskQuestion` for every selection** — never ask the user to type a number; always present clickable options
+- **Batch related questions** — combine Electron approval + visibility into one question; auto-detect localhost URL when possible
 - **Never launch Electron without explicit user approval** (`approveElectronAppLaunch`)
 - **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

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

@@ -5,7 +5,7 @@ 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.
+**Goal:** Run or generate an end-to-end test against a **local URL** using Muggle's Electron browser.
 
 | Scope | MCP tools |
 | :---- | :-------- |
@@ -15,12 +15,19 @@ 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
+
+**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.
+
+- **Selections** (project, use case, test case, script, approval): 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.
+
 ## Workflow
 
 ### 1. Auth
 
 - `muggle-remote-auth-status`
-- If not signed in: `muggle-remote-auth-login` then `muggle-remote-auth-poll`  
+- If not signed in: `muggle-remote-auth-login` then `muggle-remote-auth-poll`
   Do not skip or assume auth.
 
 ### 2. Targets (user must confirm)
@@ -31,41 +38,45 @@ Ask the user to pick **project**, **use case**, and **test case** (do not infer)
 - `muggle-remote-use-case-list` (with `projectId`)
 - `muggle-remote-test-case-list-by-use-case` (with `useCaseId`)
 
-**Selection UI (mandatory):** After each list call, present choices as a **numbered list** (`1.` … `n.`). Keep each line minimal: number, short title, UUID. Ask the user to **reply with the number** or the UUID.
+**Selection UI (mandatory):** Every selection MUST use `AskQuestion` with clickable options. Never ask the user to "reply with the number" in plain text.
 
-**Fixed tail of each pick list (project, use case, test case):** After the relevance-ranked rows, end with the options below. **Create new …** is never omitted; **Show full list** is omitted when it would be pointless (see empty list).
+**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.
 
-1. **Show full list** — user sees every row from the API (then re-number the full list including the tails below again). **Skip this option** if the API returned **zero** rows for that step (e.g. no test cases yet for the chosen use case). There is nothing to expand.
-2. **Create new …** — user creates a new entity instead of picking an existing one. Label per step: **Create new project**, **Create new use case**, or **Create new test case**.
+Prompt for projects: "Pick the project to group this test into:"
 
 **Relevance-first filtering (mandatory for project, use case, and test case lists):**
 
 - 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, then **Show full list** (unless the API list is empty — see above), then **Create new …** as above.
-- If the user picks **Show full list**, then present the complete numbered list (still ending with **Create new …**; include **Show full list** again only when the full list has at least one row).
+- 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.
+  - **"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.  
+- **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`.
   2. `muggle-remote-use-case-create-from-prompts` with `projectId`, `prompts: [{ 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.  
-  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 **§4** with that `testCaseId`.
+- **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`.
+  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 4** with that `testCaseId`.
 
 ### 3. Local URL
 
-- Use the URL the user gives. If none, ask; **do not guess**.
-- Remind them: local URL is only the execution target, not tied to cloud project config.
+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"
+
+If nothing detected, ask as free text: "Your local app should be running. What's the URL? (e.g., http://localhost:3000)"
+
+Remind them: local URL is only the execution target, not tied to cloud project config.
 
 ### 4. Existing scripts vs new generation
 
 `muggle-remote-test-script-list` with `testCaseId`.
 
-- **If any replayable/succeeded scripts exist:** list them in a **numbered** list and ask: replay one **or** generate new.  
-  Show: name, id, created/updated, step count. Include **`Generate new script`** as the **last** numbered option (e.g. last number) so it is selectable by number too.
+- **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 none:** go straight to generation (no need to ask replay vs generate).
 
 ### 5. Load data for the chosen path
@@ -77,8 +88,8 @@ Ask the user to pick **project**, **use case**, and **test case** (do not infer)
 
 **Replay**
 
-1. `muggle-remote-test-script-get` → note `actionScriptId`
-2. `muggle-remote-action-script-get` with that id → full `actionScript`  
+1. `muggle-remote-test-script-get` — note `actionScriptId`
+2. `muggle-remote-action-script-get` with that id — full `actionScript`
    **Use the API response as-is.** Do not edit, shorten, or rebuild `actionScript`; replay needs full `label` paths for element lookup.
 3. `muggle-local-execute-replay` (after approval in step 6) with `testScript`, `actionScript`, `localUrl`, `approveElectronAppLaunch: true` (optional: `showUi: true`, **`timeoutMs`** — see below)
 
@@ -88,17 +99,22 @@ The MCP client often uses a **default wait of 300000 ms (5 minutes)** for `muggl
 
 - **Always pass `timeoutMs`** for flows that may be long — for example **`600000` (10 min)** or **`900000` (15 min)** — unless the user explicitly wants a short cap.
 - If the tool reports **`Electron execution timed out after 300000ms`** (or similar) **but** Electron logs show the run still progressing (steps, screenshots, LLM calls), treat it as **orchestration timeout**, not an Electron app defect: **increase `timeoutMs` and retry** (after user re-approves if your policy requires it).
-- **Test case design:** Preconditions like “a test run has already completed” on an **empty account** can force many steps (sign-up, new project, crawl). Prefer an account/project that **already has** the needed state, or narrow the test goal so generation does not try to create a full project from scratch unless that is intentional.
+- **Test case design:** Preconditions like "a test run has already completed" on an **empty account** can force many steps (sign-up, new project, crawl). Prefer an account/project that **already has** the needed state, or narrow the test goal so generation does not try to create a full project from scratch unless that is intentional.
 
 ### Interpreting `failed` / non-zero Electron exit
 
 - **`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).
+- **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).
 
 ### 6. Approval before any local execution
 
-Get **explicit** OK to launch Electron. State: replay vs generation, test case name, URL.  
-Only then call local execute tools with `approveElectronAppLaunch: true`.
+Use `AskQuestion` to get explicit approval before launching Electron. State: replay vs generation, test case name, URL.
+
+- "Yes, launch Electron (visible — I want to watch)"
+- "Yes, launch Electron (headless — run in background)"
+- "No, cancel"
+
+Only call local execute tools with `approveElectronAppLaunch: true` after the user selects a "Yes" option. Map visible to `showUi: true`, headless to `showUi: false`.
 
 ### 7. After successful generation only
 
@@ -112,8 +128,9 @@ Only then call local execute tools with `approveElectronAppLaunch: true`.
 
 ## Non-negotiables
 
-- No silent auth skip; no launching Electron without approval.
+- No silent auth skip; no launching Electron without approval via `AskQuestion`.
 - 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`.
-- 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.
+- Use `AskQuestion` for every selection — project, use case, test case, script, and approval. 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.