@muggleai/works 4.3.0 → 4.5.0

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
 
@@ -133,7 +117,7 @@ The user MUST explicitly tell you which use case(s) to use.
 1. Ask the user to describe the use case in plain English
 2. Call `muggle-remote-use-case-create-from-prompts`:
    - `projectId`: The project ID
-   - `prompts`: Array of `{ instruction: "..." }` with the user's description
+   - `instructions`: A plain array of strings, one per use case — e.g. `["<user's description>"]`
 3. Present the created use case and confirm it's correct
 
 ## Step 6: Select Test Case (User Must Choose)
@@ -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.
@@ -309,73 +279,62 @@ open "https://www.muggle-ai.com/muggleTestV0/dashboard/projects/{projectId}/runs
 Tell the user:
 > "I've opened the Muggle AI dashboard in your browser — you can see the test results, step-by-step screenshots, and action scripts there."
 
-## Step 9: Post E2E Acceptance Results to PR
+## Step 9: Offer to Post Visual Walkthrough to PR
 
-After reporting results, check if there's an open PR for the current branch and attach the E2E acceptance summary.
+After reporting results, ask the user if they want to attach a **visual walkthrough** — a markdown block with per-test-case dashboard links and step-by-step screenshots — to the current branch's open PR. The rendering and posting workflow lives in the shared `muggle-pr-visual-walkthrough` skill; this step gathers the required input and hands off.
 
-### 9a: Find the PR
+### 9a: Gather per-step screenshots (required input for the shared skill)
 
-```bash
-gh pr view --json number,url,title 2>/dev/null
-```
+The shared skill takes an **`E2eReport` JSON** that includes per-step screenshot URLs. You already have `projectId`, `testCaseId`, `runId`, `viewUrl`, and `status` from earlier steps — you still need the step-level data.
 
-- 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
+For each published run from Step 7A:
 
-### 9b: Build the E2E acceptance comment body
+1. Call `muggle-remote-test-script-get` with the `testScriptId` returned by `muggle-local-publish-test-script`.
+2. Extract from the response: `steps[].operation.action` (description) and `steps[].operation.screenshotUrl` (cloud URL).
+3. Build a `steps` array: `[{ stepIndex: 0, action: "...", screenshotUrl: "..." }, ...]`.
+4. If the run failed, also capture `failureStepIndex`, `error`, and the local `artifactsDir` from `muggle-local-run-result-get`.
 
-Construct a markdown comment with the full E2E acceptance breakdown. The format links each test case to its detail page on the Muggle AI dashboard, so PR reviewers can click through to see step-by-step screenshots and action scripts.
+Assemble the report:
 
-```markdown
-## 🧪 Muggle AI — E2E Acceptance Results
-
-**X passed / Y failed** | [View all on Muggle AI](https://www.muggle-ai.com/muggleTestV0/dashboard/projects/{projectId}/runs)
+```json
+{
+  "projectId": "<projectId>",
+  "tests": [
+    {
+      "name": "<test case title>",
+      "testCaseId": "<id>",
+      "testScriptId": "<id>",
+      "runId": "<id>",
+      "viewUrl": "<publish response viewUrl>",
+      "status": "passed",
+      "steps": [{ "stepIndex": 0, "action": "...", "screenshotUrl": "..." }]
+    }
+  ]
+}
+```
 
-| Test Case | Status | Details |
-|-----------|--------|---------|
-| [Login with valid creds](https://www.muggle-ai.com/muggleTestV0/dashboard/projects/{projectId}/scripts?modal=script-details&testCaseId={testCaseId}) | ✅ PASSED | 8 steps, 12.3s |
-| [Login with invalid creds](https://www.muggle-ai.com/muggleTestV0/dashboard/projects/{projectId}/scripts?modal=script-details&testCaseId={testCaseId}) | ✅ PASSED | 6 steps, 9.1s |
-| [Checkout flow](https://www.muggle-ai.com/muggleTestV0/dashboard/projects/{projectId}/scripts?modal=script-details&testCaseId={testCaseId}) | ❌ FAILED | Step 7: "Click checkout button" — element not found |
+See the shared skill for the full schema (including the failed-test shape with `failureStepIndex` and `error`).
 
-<details>
-<summary>Failed test details</summary>
+### 9b: Ask the user
 
-### Checkout flow
-- **Failed at**: Step 7 — "Click checkout button"
-- **Error**: Element not found
-- **Local artifacts**: `~/.muggle-ai/sessions/{runId}/`
-- **Screenshots**: `~/.muggle-ai/sessions/{runId}/screenshots/`
+Use `AskQuestion`:
 
-</details>
+> "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."
 
----
-*Generated by [Muggle AI](https://www.muggle-ai.com) — change-driven E2E acceptance testing*
-```
+- Option 1: "Yes, post to PR"
+- Option 2: "Skip"
 
-### 9c: Post to the PR
-
-If PR already exists — add as a comment:
-```bash
-gh pr comment {pr-number} --body "$(cat <<'EOF'
-{the E2E acceptance comment body from 9b}
-EOF
-)"
-```
+### 9c: Invoke the shared skill in Mode A
 
-If creating a new PR — include the E2E acceptance section in the PR body alongside the usual summary/changes sections.
+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:
 
-### 9d: Confirm to user
+1. Call `muggle build-pr-section` to render the markdown block (fit-vs-overflow automatic)
+2. Find the PR via `gh pr view`
+3. Post `body` as a `gh pr comment`
+4. Post the overflow `comment` as a second comment (only if the CLI emitted one)
+5. Confirm the PR URL to the user
 
-> "E2E acceptance results posted to PR #{number}. Reviewers can click the test case links to see step-by-step screenshots on the Muggle AI dashboard."
+This skill always uses **Mode A** (post to an existing PR); `muggle-do` is the only caller that uses Mode B. Do not attempt to render the walkthrough markdown yourself — delegate to the shared skill.
 
 ## Tool Reference
 
@@ -397,20 +356,21 @@ If creating a new PR — include the E2E acceptance section in the PR body along
 | Results | `muggle-local-run-result-get` | Local |
 | Results | `muggle-remote-wf-get-ts-gen-latest-run` | Remote |
 | Publish | `muggle-local-publish-test-script` | Local |
+| Per-step screenshots (for walkthrough) | `muggle-remote-test-script-get` | Both |
 | Browser | `open` (shell command) | Both |
-| PR | `gh pr view`, `gh pr comment`, `gh pr create` | Both |
+| PR walkthrough | `muggle-pr-visual-walkthrough` (shared skill) | Both |
 
 ## 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
 - **Always publish before opening browser** — the dashboard needs the published data to show results
-- **Use correct dashboard URL format** — `modal=script-details` (not `modal=details`)
-- **Always check for PR before posting** — don't create a PR comment if there's no PR (ask user first)
+- **Delegate PR posting to `muggle-pr-visual-walkthrough`** — never inline the walkthrough markdown or call `gh pr comment` directly from this skill; ask the user and hand off
 - **Can be invoked at any state** — if the user already has a project or use cases set up, skip to the relevant step rather than re-doing everything

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.  
-  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`.
+- **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` 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`.
+  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
 
@@ -110,10 +126,61 @@ Only then call local execute tools with `approveElectronAppLaunch: true`.
 - `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.
 
+### 9. Offer to post a visual walkthrough to the PR
+
+After reporting results, gather the required input and hand off to the shared **`muggle-pr-visual-walkthrough`** skill, which renders the walkthrough via `muggle build-pr-section` and posts it to the current branch's open PR.
+
+#### 9a: Gather per-step screenshots
+
+The shared skill takes an **`E2eReport` JSON** that includes per-step screenshot URLs. After step 7 has called `muggle-local-publish-test-script` and you have the `testScriptId`:
+
+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 8.
+
+Assemble the `E2eReport`:
+
+```json
+{
+  "projectId": "<projectId from step 2>",
+  "tests": [
+    {
+      "name": "<test case title>",
+      "testCaseId": "<id>",
+      "testScriptId": "<id from publish>",
+      "runId": "<runId from execute>",
+      "viewUrl": "<viewUrl from publish>",
+      "status": "passed",
+      "steps": [{ "stepIndex": 0, "action": "...", "screenshotUrl": "..." }]
+    }
+  ]
+}
+```
+
+See the `muggle-pr-visual-walkthrough` skill for the full schema including the failed-test shape.
+
+#### 9b: 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"
+
+#### 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` 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.
+
+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-pr-visual-walkthrough`.
+
 ## 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.
+- PR posting is always optional and always delegated to the `muggle-pr-visual-walkthrough` skill — never inline the walkthrough markdown or call `gh pr comment` directly from this skill.