@muggleai/works 4.2.1 → 4.3.0

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

@@ -0,0 +1,416 @@
+---
+name: muggle-test
+description: "Run change-driven E2E acceptance testing using Muggle AI — detects local code changes, maps them to use cases, and generates test scripts either locally (real browser on localhost) or remotely (cloud execution on a preview/staging URL). Publishes results to Muggle dashboard, opens them in the browser, and posts E2E acceptance summaries with screenshots to the PR. Use this skill whenever the user wants to test their changes, run E2E acceptance tests on recent work, validate what they've been working on, or check if their code changes broke anything. Triggers on: 'test my changes', 'run tests on my changes', 'acceptance test my work', 'check my changes', 'validate my changes', 'test before I push', 'make sure my changes work', 'regression test my changes', 'test on preview', 'test on staging'. This is the go-to skill for change-driven E2E acceptance testing — it handles everything from change detection to test execution to result reporting."
+---
+
+# Muggle Test — Change-Driven E2E Acceptance Router
+
+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.
+
+## Step 1: Confirm Scope of Work (Always First)
+
+Parse the user's query and explicitly confirm their expectation. There are exactly two modes:
+
+### Mode A: Local Test Generation
+> Test impacted use cases/test cases against **localhost** using the Electron browser.
+>
+> Execution tool: `muggle-local-execute-test-generation`
+
+Signs the user wants this: mentions "localhost", "local", "my machine", "dev server", "my changes locally", or just "test my changes" in a repo context.
+
+### Mode B: Remote Test Generation
+> Ask Muggle's cloud to generate test scripts against a **preview/staging URL**.
+>
+> Execution tool: `muggle-remote-workflow-start-test-script-generation`
+
+Signs the user wants this: mentions "preview", "staging", "deployed", "preview URL", "test on preview", "test the deployment", or provides a non-localhost URL.
+
+### 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 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
+──────────────────────────────────────────────────────────────
+```
+
+Only proceed after the user selects an option.
+
+## Step 2: Detect Local Changes
+
+Analyze the working directory to understand what changed.
+
+1. Run `git status` and `git diff --stat` for an overview
+2. Run `git diff` (or `git diff --cached` if staged) to read actual diffs
+3. Identify impacted feature areas:
+   - Changed UI components, pages, routes
+   - Modified API endpoints or data flows
+   - Updated form fields, validation, user interactions
+4. Produce a concise **change summary** — a list of impacted features
+
+Present:
+> "Here's what changed: [list]. I'll scope E2E acceptance testing to these areas."
+
+If no changes detected (clean tree), tell the user and ask what they want to test.
+
+## Step 3: Authenticate
+
+1. Call `muggle-remote-auth-status`
+2. If authenticated and not expired → proceed
+3. If not authenticated or expired → call `muggle-remote-auth-login`
+4. If login pending → call `muggle-remote-auth-poll`
+
+If auth fails repeatedly, suggest: `muggle logout && muggle login` from terminal.
+
+## Step 4: Select Project (User Must Choose)
+
+1. Call `muggle-remote-project-list`
+2. Present **all** projects as a numbered list:
+
+```
+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]
+──────────────────────────────────────────────────────────────
+```
+
+> "Which project should I use? Reply with the number."
+
+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
+   - Call `muggle-remote-project-create`
+
+Store the `projectId` only after user confirms.
+
+## Step 5: Select Use Case (User Must Choose)
+
+### 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
+
+```
+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]
+──────────────────────────────────────────────────────────────────────────
+```
+
+> "Which use case do you want to test? Reply with the number (or multiple numbers separated by commas)."
+
+### 5c: Wait for explicit user selection
+
+**CRITICAL: Do NOT auto-select use cases** based on:
+- Git changes analysis
+- Use case title/description matching
+- Any heuristic or inference
+
+The user MUST explicitly tell you which use case(s) to use.
+
+### 5d: If user chooses "Create new use case"
+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
+3. Present the created use case and confirm it's correct
+
+## Step 6: Select Test Case (User Must Choose)
+
+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
+
+```
+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]
+──────────────────────────────────────────────────────────────────────────
+```
+
+> "Which test case(s) do you want to run? Reply with the number (or multiple numbers separated by commas)."
+
+### 6c: Wait for explicit user selection
+
+**CRITICAL: Do NOT auto-select test cases** — the user MUST explicitly choose which test case(s) to execute.
+
+### 6d: If user chooses "Generate new test case"
+1. Ask the user to describe what they want to test in plain English
+2. Call `muggle-remote-test-case-generate-from-prompt`:
+   - `projectId`, `useCaseId`, `instruction` (the user's description)
+3. Present the generated test case(s) for review
+4. Call `muggle-remote-test-case-create` to save the ones the user approves
+
+### 6e: Confirm final selection
+
+> "You selected [N] test case(s): [list titles]. Ready to proceed?"
+
+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)
+
+**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.
+
+**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
+──────────────────────────────────────────────────────────────
+```
+
+Wait for "1" before asking question 3. If "2", stop and ask what they want to do instead.
+
+**Question 3 — Window visibility:**
+```
+How should the browser window appear?
+──────────────────────────────────────────────────────────────
+1. Visible (watch the browser as it runs)
+2. Headless (run in background)
+──────────────────────────────────────────────────────────────
+```
+
+Wait for answer (1 or 2) before proceeding.
+
+### Run sequentially
+
+For each test case:
+
+1. Call `muggle-remote-test-case-get` to fetch full details
+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)
+3. Store the returned `runId`
+
+If a generation fails, log it and continue to the next. Do not abort the batch.
+
+### Collect results
+
+For each `runId`, call `muggle-local-run-result-get`. Extract: status, duration, step count, `artifactsDir`.
+
+### Publish each run to cloud
+
+For each completed run, call `muggle-local-publish-test-script`:
+- `runId`: The local run ID
+- `cloudTestCaseId`: The cloud test case ID
+
+This returns:
+- `viewUrl`: Direct link to view this test run on the Muggle AI dashboard
+- `testScriptId`, `actionScriptId`, `workflowRuntimeId`
+
+Store every `viewUrl` — these are used in the next steps.
+
+### Report summary
+
+```
+Test Case                  Status    Duration   Steps   View on Muggle
+─────────────────────────────────────────────────────────────────────────
+Login with valid creds     PASSED    12.3s      8       https://www.muggle-ai.com/...
+Login with invalid creds   PASSED    9.1s       6       https://www.muggle-ai.com/...
+Checkout flow              FAILED    15.7s      12      https://www.muggle-ai.com/...
+─────────────────────────────────────────────────────────────────────────
+Total: 3 tests | 2 passed | 1 failed | 37.1s
+```
+
+For failures: show which step failed, the local screenshot path, and a suggestion.
+
+## Step 7B: Execute — Remote Mode
+
+### Ask for target URL
+
+> "What's the preview/staging URL to test against?"
+
+### Trigger remote workflows
+
+For each test case:
+
+1. Call `muggle-remote-test-case-get` to fetch full details
+2. Call `muggle-remote-workflow-start-test-script-generation`:
+   - `projectId`: The project ID
+   - `useCaseId`: The use case ID
+   - `testCaseId`: The test case ID
+   - `name`: `"muggle-test: {test case title}"`
+   - `url`: The preview/staging URL
+   - `goal`: From the test case
+   - `precondition`: From the test case (use `"None"` if empty)
+   - `instructions`: From the test case
+   - `expectedResult`: From the test case
+3. Store the returned workflow runtime ID
+
+### Monitor and report
+
+For each workflow, call `muggle-remote-wf-get-ts-gen-latest-run` with the runtime ID.
+
+```
+Test Case                  Workflow Status   Runtime ID
+────────────────────────────────────────────────────────
+Login with valid creds     RUNNING           rt-abc123
+Login with invalid creds   COMPLETED         rt-def456
+Checkout flow              QUEUED            rt-ghi789
+```
+
+## Step 8: Open Results in Browser
+
+After execution and publishing are complete, open the Muggle AI dashboard so the user can visually inspect results and screenshots.
+
+### Mode A (Local) — open each published viewUrl
+
+For each published run's `viewUrl`:
+```bash
+open "https://www.muggle-ai.com/muggleTestV0/dashboard/projects/{projectId}/scripts?modal=script-details&testCaseId={testCaseId}"
+```
+
+If there are many runs (>3), open just the project-level runs page instead of individual tabs:
+```bash
+open "https://www.muggle-ai.com/muggleTestV0/dashboard/projects/{projectId}/runs"
+```
+
+### Mode B (Remote) — open the project runs page
+
+```bash
+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
+
+After reporting results, check if there's an open PR for the current branch and attach the E2E acceptance summary.
+
+### 9a: Find the PR
+
+```bash
+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
+
+### 9b: Build the E2E acceptance comment body
+
+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.
+
+```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)
+
+| 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 |
+
+<details>
+<summary>Failed test details</summary>
+
+### 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/`
+
+</details>
+
+---
+*Generated by [Muggle AI](https://www.muggle-ai.com) — change-driven E2E acceptance testing*
+```
+
+### 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
+)"
+```
+
+If creating a new PR — include the E2E acceptance section in the PR body alongside the usual summary/changes sections.
+
+### 9d: Confirm to 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."
+
+## Tool Reference
+
+| Phase | Tool | Mode |
+|:------|:-----|:-----|
+| Auth | `muggle-remote-auth-status` | Both |
+| Auth | `muggle-remote-auth-login` | Both |
+| Auth | `muggle-remote-auth-poll` | Both |
+| Project | `muggle-remote-project-list` | Both |
+| Project | `muggle-remote-project-create` | Both |
+| Use Case | `muggle-remote-use-case-list` | Both |
+| Use Case | `muggle-remote-use-case-create-from-prompts` | Both |
+| Test Case | `muggle-remote-test-case-list-by-use-case` | Both |
+| Test Case | `muggle-remote-test-case-generate-from-prompt` | Both |
+| Test Case | `muggle-remote-test-case-create` | Both |
+| Test Case | `muggle-remote-test-case-get` | Both |
+| Execute | `muggle-local-execute-test-generation` | Local |
+| Execute | `muggle-remote-workflow-start-test-script-generation` | Remote |
+| Results | `muggle-local-run-result-get` | Local |
+| Results | `muggle-remote-wf-get-ts-gen-latest-run` | Remote |
+| Publish | `muggle-local-publish-test-script` | Local |
+| Browser | `open` (shell command) | Both |
+| PR | `gh pr view`, `gh pr comment`, `gh pr create` | 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
+- **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)
+- **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

@@ -1,122 +1,119 @@
 ---
 name: muggle-test-feature-local
-description: Run a real-browser QA test against localhost to verify a feature works correctly — signup flows, checkout, form validation, UI interactions, or any user-facing behavior. Launches a browser that executes test steps and captures screenshots. Use this skill whenever the user asks to test, QA, validate, or verify their web app, UI changes, user flows, or frontend behavior on localhost or a dev server — even if they don't mention 'muggle' or 'QA' explicitly.
+description: Run a real-browser end-to-end (E2E) acceptance test against localhost to verify a feature works correctly — signup flows, checkout, form validation, UI interactions, or any user-facing behavior. Launches a browser that executes test steps and captures screenshots. Use this skill whenever the user asks to test, validate, or verify their web app, UI changes, user flows, or frontend behavior on localhost or a dev server — even if they don't mention 'muggle' or 'E2E' explicitly.
 ---
 
 # Muggle Test Feature Local
 
-Run end-to-end feature testing from UI against a local URL:
+**Goal:** Run or generate an end-to-end test against a **local URL** using Muggle’s Electron browser.
 
-- Cloud management: `muggle-remote-*`
-- Local execution and artifacts: `muggle-local-*`
+| Scope | MCP tools |
+| :---- | :-------- |
+| Cloud (projects, cases, scripts, auth) | `muggle-remote-*` |
+| Local (Electron run, publish, results) | `muggle-local-*` |
+| Create new entities (preview / create) | `muggle-remote-project-create`, `muggle-remote-use-case-prompt-preview`, `muggle-remote-use-case-create-from-prompts`, `muggle-remote-test-case-generate-from-prompt`, `muggle-remote-test-case-create` |
+
+The local URL only changes where the browser opens; it does not change the remote project or test definitions.
 
 ## Workflow
 
 ### 1. Auth
 
 - `muggle-remote-auth-status`
-- If needed: `muggle-remote-auth-login` + `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)
 
-### 2. Select project, use case, and test case
+Ask the user to pick **project**, **use case**, and **test case** (do not infer).
 
-- Explicitly ask user to select each target to proceed.
 - `muggle-remote-project-list`
-- `muggle-remote-use-case-list`
-- `muggle-remote-test-case-list-by-use-case`
+- `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.
+
+**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).
+
+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**.
+
+**Relevance-first filtering (mandatory for project, use case, and test case lists):**
 
-### 3. Resolve local URL
+- 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).
 
-- Use the URL provided by the user.
-- If missing, ask explicitly (do not guess).
-- Inform user the local URL does not affect the project's remote test.
+**Create new — tools and flow (use these MCP tools; preview before persist):**
 
-### 4. Check for existing scripts and ask user to choose
+- **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`.
 
-Check BOTH cloud and local scripts to determine what's available:
+### 3. Local URL
 
-1. **Check cloud scripts:** `muggle-remote-test-script-list` filtered by projectId
-2. **Check local scripts:** `muggle-local-test-script-list` filtered by projectId
+- 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.
 
-**Decision logic:**
+### 4. Existing scripts vs new generation
 
-| Cloud Script | Local Script (status: published/generated) | Action |
-|--------------|---------------------------------------------|--------|
-| Exists + ACTIVE | Exists | Ask user: "Replay existing script" or "Regenerate from scratch"? |
-| Exists + ACTIVE | Not found | Sync from cloud first, then ask user |
-| Not found | Exists | Ask user: "Replay local script" or "Regenerate"? |
-| Not found | Not found | Default to generation (no need to ask) |
+`muggle-remote-test-script-list` with `testCaseId`.
 
-**When asking user, show:**
-- Script name and ID
-- When it was created/updated
-- Number of steps
-- Last run status if available
+- **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 none:** go straight to generation (no need to ask replay vs generate).
 
-### 5. Prepare for execution
+### 5. Load data for the chosen path
 
-**For Replay:**
+**Generate**
 
-Local scripts contain the complete `actionScript` with element labels required for replay. Remote scripts only contain metadata.
+1. `muggle-remote-test-case-get`
+2. `muggle-local-execute-test-generation` (after approval in step 6) with that test case + `localUrl` + `approveElectronAppLaunch: true` (optional: `showUi: true`, **`timeoutMs`** — see below)
 
-1. Use `muggle-local-test-script-get` with `testScriptId` to fetch the FULL script including actionScript
-2. The returned script includes all steps with `operation.label` paths needed for element location
-3. Pass this complete script to `muggle-local-execute-replay`
+**Replay**
 
-**IMPORTANT:** Do NOT manually construct or simplify the actionScript. The electron app requires the complete script with all `label` paths intact to locate page elements during replay.
+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)
 
-**For Generation:**
+### Local execution timeout (`timeoutMs`)
 
-1. `muggle-remote-test-case-get` to fetch test case details
-2. `muggle-local-execute-test-generation` with the test case
+The MCP client often uses a **default wait of 300000 ms (5 minutes)** for `muggle-local-execute-test-generation` and `muggle-local-execute-replay`. **Exploratory script generation** (Auth0 login, dashboards, multi-step wizards, many LLM iterations) routinely **runs longer than 5 minutes** while Electron is still healthy.
 
-### 6. Approval requirement
+- **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.
 
-- Before execution, get explicit user approval for launching Electron app.
-- Show what will be executed (replay vs generation, test case name, URL).
-- Only then set `approveElectronAppLaunch: true`.
+### Interpreting `failed` / non-zero Electron exit
 
-### 7. Execute
+- **`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).
 
-**Replay:**
-```
-muggle-local-execute-replay with:
-- testScript: (full script from muggle-local-test-script-get)
-- localUrl: user-provided localhost URL
-- approveElectronAppLaunch: true
-- showUi: true (optional, lets user watch)
-```
+### 6. Approval before any local execution
 
-**Generation:**
-```
-muggle-local-execute-test-generation with:
-- testCase: (from muggle-remote-test-case-get)
-- localUrl: user-provided localhost URL
-- approveElectronAppLaunch: true
-- showUi: true (optional)
-```
+Get **explicit** OK to launch Electron. State: replay vs generation, test case name, URL.  
+Only then call local execute tools with `approveElectronAppLaunch: true`.
 
-### 8. Publish generation results (generation only)
+### 7. After successful generation only
 
-- Use `muggle-local-publish-test-script` after successful generation.
-- This uploads the script to cloud so it can be replayed later.
-- Return the remote URL for user to view the result.
+- `muggle-local-publish-test-script`
+- Open returned `viewUrl` for the user (`open "<viewUrl>"` on macOS or OS equivalent).
 
-### 9. Report results
+### 8. Report
 
-- `muggle-local-run-result-get` with returned runId.
-- Report:
-  - status (passed/failed)
-  - duration
-  - pass/fail summary
-  - steps summary (which steps passed/failed)
-  - artifacts path (screenshots location)
-  - script detail view URL
+- `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.
 
-## Guardrails
+## Non-negotiables
 
-- Do not silently skip auth.
-- Do not silently skip asking user when a replayable script exists.
-- Do not launch Electron without explicit approval.
-- Do not hide failing run details; include error and artifacts path.
-- Do not simplify or reconstruct actionScript for replay; use the complete script from `muggle-local-test-script-get`.
-- Always check local scripts before defaulting to generation.
+- No silent auth skip; no launching Electron without approval.
+- 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.