@muggleai/works 4.8.1 → 4.8.3

package/dist/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "muggle",
   "description": "Run real-browser end-to-end (E2E) acceptance tests on your web app from any AI coding agent. Generate test scripts from plain English, replay them on localhost, capture screenshots, and validate user flows like signup, checkout, and dashboards. Works across Claude Code, Cursor, Codex, and Windsurf.",
-  "version": "4.8.1",
+  "version": "4.8.3",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/dist/plugin/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "muggle",
   "displayName": "Muggle AI",
   "description": "Ship quality products with AI-powered end-to-end (E2E) acceptance testing that validates your web app like a real user — from Claude Code and Cursor to PR.",
-  "version": "4.8.1",
+  "version": "4.8.3",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/dist/plugin/skills/do/e2e-acceptance.md

@@ -1,7 +1,15 @@
-# E2E / acceptance agent
+# E2E / acceptance agent (Stage 6/7)
 
 You are running **end-to-end (E2E) acceptance** test cases against code changes using Muggle AI's local testing infrastructure. These tests simulate real users in a browser — they are not unit tests.
 
+## Turn preamble
+
+Start the turn with:
+
+```
+**Stage 6/7 — E2E acceptance** — running browser tests against the validation target from pre-flight.
+```
+
 ## Design
 
 E2E acceptance testing runs **locally** using the `test-feature-local` approach:
@@ -15,32 +23,35 @@ This guarantees E2E acceptance tests always run — no dependency on cloud repla
 
 ## Input
 
-You receive:
-- The Muggle project ID
+You receive everything from `state.md` already — pre-flight resolved it:
+
+- `localUrl` — the locally running dev server URL
+- `projectId` — the chosen Muggle project
+- The validation strategy (`local-e2e`, `staging-replay`, `unit-only`, `skip`)
+- Test-user credential status (existing / new / skip)
 - The list of changed repos, files, and a summary of changes
 - The requirements goal
-- `localUrl` per repo (from `muggle-repos.json`) — the locally running dev server URL
 
 ## Your Job
 
-### Step 0: Resolve Local URL
+### Step 0: Consume pre-flight (no user questions)
+
+Read `state.md`. If the validation strategy is `unit-only` or `skip`, **do not run this stage** — skip to stage 7 and record the skip reason. Otherwise use `localUrl` directly; **do not ask the user** for it.
+
+If `localUrl` or `projectId` is missing from `state.md`, that is a pre-flight bug. **Do not paper over it by asking the user** — escalate once with the session path and halt. The fix is to expand `pre-flight.md`, not to grow a new question here.
 
-Read `localUrl` for each repo from the context. If it is not provided, ask the user:
-> "E2E acceptance testing requires a running local server. What URL is the `<repo>` app running on? (e.g. `http://localhost:3000`)"
+### Step 0.5: Pre-flight verification probes
 
-**Do not skip E2E acceptance tests.** Wait for the user to provide the URL before proceeding.
+Before launching Electron, run these live checks and fail loudly if any fails:
 
-### Step 1: Check Authentication
+1. `curl -s -o /dev/null -w "%{http_code}" <localUrl>` — expect 2xx or 3xx. If the dev server isn't up, halt with the exact command the user needs to start it.
+2. If a backend URL is recorded, probe its health endpoint. A 5xx or unreachable backend means the dashboard will render in an error state and test results will be meaningless — halt.
+3. `muggle-remote-auth-status` — must be `authenticated`. If not, the pre-flight missed this; escalate.
+4. If test credentials were marked `existing`, confirm the Auth0 tenant in the repo's env matches the tenant the secrets were created under (recorded in `state.md`). Tenant mismatch → halt with "existing secrets target tenant X, local dev targets tenant Y — update pre-flight to collect new credentials."
 
-- `muggle-remote-auth-status`
-- If **authenticated**: print the logged-in email and ask via `AskQuestion`:
-  > "You're logged in as **{email}**. Continue with this account?"
-  - Option 1: "Yes, continue"
-  - Option 2: "No, switch account"
-  If the user picks "switch account", call `muggle-remote-auth-login` with `forceNewSession: true` then `muggle-remote-auth-poll`.
-- If **not signed in or expired**: `muggle-remote-auth-login` then `muggle-remote-auth-poll`
+### Step 1: Authentication already verified
 
-Do not skip or assume auth.
+Pre-flight handled auth. If `muggle-remote-auth-status` somehow shows expired here (session clock skew, etc.), re-auth silently via `muggle-remote-auth-login` + `muggle-remote-auth-poll` — but do not ask the user "continue with this account?" again.
 
 ### Step 2: Get Test Cases
 

package/dist/plugin/skills/do/impact-analysis.md

@@ -1,7 +1,15 @@
-# Impact Analysis Agent
+# Impact Analysis Agent (Stage 3/7)
 
 You are analyzing git repositories to determine which ones have actual code changes that need to go through the dev cycle pipeline.
 
+## Turn preamble
+
+Start the turn with:
+
+```
+**Stage 3/7 — Impact analysis** — diffing each affected repo against its default branch.
+```
+
 ## Input
 
 You receive:

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

@@ -1,7 +1,29 @@
-# PR Creation Agent
+# PR Creation Agent (Stage 7/7)
 
 You are creating pull requests for each repository that has changes after a successful dev cycle run.
 
+## Turn preamble
+
+Start the turn with:
+
+```
+**Stage 7/7 — Open PR** — rendering the visual walkthrough and pushing the PR.
+```
+
+## Non-negotiable: visual walkthrough is required
+
+**You MUST invoke `muggle-pr-visual-walkthrough` (Mode B) to render the E2E section of the PR body.** Hand-writing the PR body with a text summary and `gh pr create` is a stage failure — reviewers rely on the dashboard links and per-step screenshots the walkthrough produces.
+
+If the E2E stage was skipped (validation was `unit-only` or `skip`), you may omit the walkthrough section — but mark the PR title with `[UNVERIFIED]` or `[UNIT-ONLY]` accordingly, and record the reason in the PR body under `## Validation`.
+
+Before calling `gh pr create`, self-check:
+
+- [ ] `muggle-pr-visual-walkthrough` was invoked (or the skip reason is recorded).
+- [ ] The `body` returned by the skill is embedded verbatim in the PR body.
+- [ ] If `comment` is non-null, it will be posted as a follow-up after the PR is created.
+
+If you cannot check all three, **halt** — do not create the PR. Fix the upstream stage first.
+
 ## Input
 
 You receive:

package/dist/plugin/skills/do/pre-flight.md

@@ -0,0 +1,104 @@
+# Pre-flight Agent (Stage 1/7)
+
+You are running the **only user-facing stage** of the muggle-do dev cycle. Your job is to consolidate every ambiguity — task scope, repos, validation strategy, environment, credentials, PR target — into a **single turn** so the rest of the cycle can run unattended.
+
+**Non-negotiable:** Never split pre-flight across multiple turns. Detect what you can silently, then ask every remaining question at once. If you find yourself asking a follow-up, you failed — fold the follow-up back into this file so the next run covers it.
+
+## Turn preamble
+
+Start the turn with:
+
+```
+**Stage 1/7 — Pre-flight** — consolidating everything the cycle needs before going silent.
+```
+
+## Input
+
+You receive:
+
+- The user's task description (from `$ARGUMENTS`).
+- The list of configured repos (names + paths) from the Muggle config.
+- Any session directory that already exists (resumption case).
+
+## Silent detection (do this first — no user prompts)
+
+Before asking anything, gather every fact you can resolve without the user:
+
+1. **Candidate repo(s).** Match keywords in the task description against configured repo names. If one repo is an obvious match, propose it as the default; if two or three are plausible, list them.
+2. **Current branch and default branch** for each candidate repo. Run `git -C <repo> symbolic-ref refs/remotes/origin/HEAD --short` and `git -C <repo> branch --show-current`. If the current branch is the default, the pre-flight must collect a new branch name.
+3. **Running dev server.** Scan common dev ports — `lsof -iTCP -sTCP:LISTEN -nP | grep -E ':(3000|3001|3999|4200|5173|8080)'` — and hit `/` with `curl -s -o /dev/null -w "%{http_code}"` to confirm 2xx.
+4. **Running backend.** If the repo's `.env.local` (or equivalent) declares a backend URL (e.g. `REACT_APP_BACKEND_BASE_URL=http://localhost:5050`), probe the health endpoint; note up/down.
+5. **Muggle MCP auth.** Call `muggle-remote-auth-status`. If expired, you will ask to re-auth in the questionnaire.
+6. **Candidate Muggle projects.** Call `muggle-remote-project-list` and rank by semantic match against the task description and the repo's dev URL.
+7. **Existing test-user secrets.** For each candidate Muggle project, call `muggle-remote-secret-list` and note whether `managed_profile_email` / `managed_profile_password` exist.
+8. **Auth0 tenant in use for local dev.** Grep the repo's env file for `*AUTH0_DOMAIN*`; record the tenant. This tells the user whether the staging-tenant test user will work or not.
+
+## The consolidated questionnaire
+
+Present **one `AskQuestion`** (or the platform's structured-selection equivalent) that collects every remaining decision. Use detected values as defaults whenever possible. Questions to include, in this order:
+
+1. **Task scope clarification** — only if the task description is genuinely ambiguous. Offer 2–3 interpretations as options plus "Other — type a clarification." If the task is unambiguous, omit.
+2. **Repo(s) to modify** — pre-selected with the best silent match. "Confirm <repo>" / "Change repo" / "Multi-repo (list them)".
+3. **Branch name** — default: `users/<user>/<slug>` derived from the task. "Use default" / "Use different name (type)".
+4. **Validation strategy** — the single most important question. Options:
+   - **Local E2E** (Muggle Electron against a running localhost) — default if a dev server was detected.
+   - **Staging replay** — for changes already deployed to a preview URL.
+   - **Unit tests only** — skip E2E, acceptable for pure refactors or backend-only changes.
+   - **Skip validation** — explicit opt-out; the PR title gets `[UNVERIFIED]`.
+5. **Local URL** — only if validation is Local E2E. Default: the detected port. "Confirm `<detected>`" / "Type a different URL".
+6. **Backend reachable?** — only if validation is Local E2E and a backend URL is declared. If the health probe failed, ask "Start the backend now and I'll re-probe" / "Proceed anyway" / "Skip to unit tests only".
+7. **Muggle project** — pre-selected with the best silent match. "Use <top match>" / "Use a different existing project (list)" / "Create new".
+8. **Test-user credentials** — only if validation is Local E2E AND the Auth0 tenant in the repo differs from the tenant the managed secrets were created under. Options: "Reuse existing secrets (may fail if tenant mismatch — will surface failure)" / "Create new secrets for this tenant (provide email + password)" / "Switch to staging replay".
+9. **PR target branch** — default: the repo's default branch. "Use default" / "Target a different branch".
+10. **Re-auth Muggle MCP?** — only if auth was missing/expired. "Log in now" / "Abort".
+
+If fewer than two of the above need the user, still gather them in a single turn — never open a second round.
+
+## Output
+
+After the user answers, write **`state.md`** with every resolved value, verbatim, in this format:
+
+```markdown
+# Session state
+
+**Slug:** <slug>
+**Current stage:** 1/7 (pre-flight complete)
+**Last update:** <ISO-8601 timestamp>
+
+## Pre-flight answers
+
+- Task: <one-line goal>
+- Repos: <repo1>, <repo2>
+- Branch: <branch-name>
+- Validation: <strategy>
+- Local URL: <url or N/A>
+- Backend status: <up | down | N/A>
+- Muggle project: <name> (<uuid>)
+- Test credentials: <existing | new | skip>
+- PR target: <branch>
+- Auth status: <ok | re-authed | N/A>
+
+## Blockers
+<none | bulleted list>
+```
+
+Also initialize `iterations/001.md` with a header:
+
+```markdown
+# Iteration 001 — <ISO-8601 timestamp>
+
+### Stage 1/7 — Pre-flight (<timestamp>)
+
+<verbatim copy of pre-flight answers>
+```
+
+## Handoff
+
+Return control to the muggle-do driver with a one-line summary: `pre-flight complete, proceeding silently through stages 2–7`. Do not print the pre-flight answers again — they are in `state.md` and the iteration log.
+
+## Non-negotiables
+
+- Exactly **one** user turn. Zero follow-up questions inside this stage.
+- Silent detection **must** run before the questionnaire — never ask for a value you can detect.
+- Every detected value is a default, not a lock — the user can always override via "Type a different …".
+- Missing `state.md` or `iterations/001.md` at the end of this stage is a stage failure.

package/dist/plugin/skills/do/requirements.md

@@ -1,7 +1,17 @@
-# Requirements Analysis Agent
+# Requirements Analysis Agent (Stage 2/7)
 
 You are analyzing a user's task description to extract structured requirements for an autonomous development cycle.
 
+## Turn preamble
+
+Start the turn with:
+
+```
+**Stage 2/7 — Requirements** — extracting structured goals from the pre-flight-clarified task.
+```
+
+Pre-flight already resolved ambiguity via the consolidated questionnaire. **Do not ask the user any questions here** — infer silently and record assumptions in Notes.
+
 ## Input
 
 You receive:

package/dist/plugin/skills/do/unit-tests.md

@@ -1,7 +1,15 @@
-# Unit Test Runner Agent
+# Unit Test Runner Agent (Stage 5/7)
 
 You are running unit tests for each repository that has changes in the dev cycle pipeline.
 
+## Turn preamble
+
+Start the turn with:
+
+```
+**Stage 5/7 — Unit tests** — running each repo's test suite.
+```
+
 ## Input
 
 You receive:

package/dist/plugin/skills/do/validate-code.md

@@ -1,7 +1,15 @@
-# Code Validation Agent
+# Code Validation Agent (Stage 4/7)
 
 You are validating that each repository's git state is ready for the dev cycle pipeline.
 
+## Turn preamble
+
+Start the turn with:
+
+```
+**Stage 4/7 — Validate code** — checking branch and commit state for each repo with changes.
+```
+
 ## Input
 
 You receive:

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

@@ -6,9 +6,9 @@ disable-model-invocation: true
 
 # Muggle Do
 
-Muggle Do is the command for the Muggle AI development workflow.
+Muggle Do runs a battle-tested autonomous dev cycle: **pre-flight → requirements → impact analysis → validate code → unit tests → E2E acceptance → open PR**.
 
-It runs a battle-tested autonomous dev cycle: requirements -> impact analysis -> validate code -> coding -> unit tests -> E2E acceptance tests -> open PRs.
+The design goal is **fire and review**: the user answers one consolidated pre-flight questionnaire, then walks away. Every subsequent stage runs unattended until completion or a genuine blocker.
 
 For maintenance tasks, use the dedicated skills:
 
@@ -20,34 +20,78 @@ For maintenance tasks, use the dedicated skills:
 
 Treat `$ARGUMENTS` as the user command:
 
-- Empty / `help` / `menu` / `?` -> show menu and session selector.
-- Anything else -> treat as a new task description and start/resume a dev-cycle session.
+- Empty / `help` / `menu` / `?` → show menu and session selector.
+- Anything else → treat as a new task description and start/resume a dev-cycle session.
+
+## The seven stages
+
+| # | Stage | File | User-facing? |
+| :- | :---- | :--- | :----------- |
+| 1 | Pre-flight | [../do/pre-flight.md](../do/pre-flight.md) | **Yes — single consolidated turn** |
+| 2 | Requirements | [../do/requirements.md](../do/requirements.md) | No |
+| 3 | Impact analysis | [../do/impact-analysis.md](../do/impact-analysis.md) | No |
+| 4 | Validate code | [../do/validate-code.md](../do/validate-code.md) | No |
+| 5 | Unit tests | [../do/unit-tests.md](../do/unit-tests.md) | No |
+| 6 | E2E acceptance | [../do/e2e-acceptance.md](../do/e2e-acceptance.md) | No |
+| 7 | Open PR | [../do/open-prs.md](../do/open-prs.md) | No |
+
+**Stage 1 (pre-flight) is the ONLY stage that talks to the user.** Stages 2–7 run silently to completion. If a later stage hits a genuine blocker that the pre-flight didn't cover, escalate with a single terminal message — do not open a second round of questions.
+
+## Front-loading (stage 1 non-negotiable)
+
+All ambiguity — task scope, repo selection, validation strategy, localhost URL, backend health, Muggle project, test-user credentials, branch name, PR target — is resolved in a **single** pre-flight turn. See `pre-flight.md` for the exact questionnaire.
+
+**Red-flag behaviors (do not do):**
+
+- Asking a clarifying question mid-cycle because "I didn't think of that at pre-flight."
+- Starting a dev server mid-cycle and discovering the port is wrong.
+- Reaching the E2E stage before knowing how the user wants it validated.
+- Asking the user to "pick one" across multiple turns instead of one turn.
+
+If any of these happen, the pre-flight was incomplete — treat it as a skill bug, not a user bug, and expand `pre-flight.md` to cover the missed case after the run.
 
 ## Session model
 
-Use `.muggle-do/sessions/<slug>/` with these files:
+Every run writes to `.muggle-do/sessions/<slug>/`:
 
-- `state.md`
-- `requirements.md`
-- `iterations/<NNN>.md`
-- `result.md`
+- `state.md` — one-screen live status: current stage (N/7), last update timestamp, pre-flight answers verbatim, any blockers.
+- `iterations/<NNN>.md` — append-only log of stage transitions for iteration NNN: what ran, what was decided, what artifacts were produced.
+- `requirements.md` — frozen output of stage 2.
+- `result.md` — final summary written by stage 7 (PR URLs, E2E outcome, open issues).
 
-On each stage transition, update `state.md` and append stage output to the active iteration file.
+**On every stage transition, you MUST:**
 
-## Dev cycle agents
+1. Append a dated entry to the active `iterations/<NNN>.md`: `### Stage N/7 — <name> (<timestamp>)` followed by the stage's output.
+2. Rewrite `state.md` to reflect the new current stage and any relevant counters.
 
-Use the supporting files in the `../do/` directory as stage-specific instructions:
+If these files don't exist, create them — missing session files means the user lost visibility into the cycle, which is the exact failure mode this skill exists to prevent.
 
-- [requirements.md](../do/requirements.md)
-- [impact-analysis.md](../do/impact-analysis.md)
-- [validate-code.md](../do/validate-code.md)
-- [unit-tests.md](../do/unit-tests.md)
-- [e2e-acceptance.md](../do/e2e-acceptance.md)
-- [open-prs.md](../do/open-prs.md)
+## Turn preamble
+
+Each stage turn MUST begin with one line in this form before any other output:
+
+```
+**Stage N/7 — <stage name>** — <one-line intent>
+```
+
+This is how the user can tell, at a glance, what phase the cycle is in without parsing a long response.
 
 ## Guardrails
 
-- Do not skip unit tests before E2E acceptance tests.
-- Do not skip E2E acceptance tests due to missing scripts; generate when needed.
-- If the same stage fails 3 times in a row, escalate with details.
-- If total iterations reach 3 and E2E acceptance tests still fail, continue to PR creation with `[E2E FAILING]`.
+- **No mid-cycle user questions.** Anything not covered by pre-flight is a skill bug; escalate once, do not loop.
+- **Do not skip unit tests before E2E acceptance tests.**
+- **Do not skip E2E acceptance tests due to missing scripts** — generate when needed.
+- **Do not hand-write the E2E block of the PR body.** The `open-prs.md` stage MUST invoke `muggle-pr-visual-walkthrough` Mode B to render the screenshots-and-steps section. Hand-writing it loses the dashboard links the user relies on for review.
+- **If the same stage fails 3 times in a row, escalate with details.**
+- **If total iterations reach 3 and E2E acceptance tests still fail**, continue to PR creation with `[E2E FAILING]` in the title; the visual walkthrough section makes the failures reviewable.
+
+## Completion contract
+
+When stage 7 finishes, the final message to the user contains at minimum:
+
+- PR URL(s)
+- E2E status (passing / `[E2E FAILING]`)
+- Link to the run dashboard for each test case (via the walkthrough skill output)
+- Path to `result.md` for full details
+
+No other content. The user already read the walkthrough in the PR body — do not re-summarize it here.

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

@@ -5,17 +5,29 @@ description: Update Muggle AI to latest version. Use when user types muggle upgr
 
 # Muggle Upgrade
 
-Update all Muggle AI components to the latest published version.
+Update all Muggle AI components to the latest published version. This means **both** the `@muggleai/works` CLI on npm **and** the Electron runner the CLI manages.
 
 ## Steps
 
 1. Run `/muggle:muggle-status` checks to capture current versions.
-2. Run `muggle upgrade` to check GitHub releases for the latest electron-app version and download it.
-3. Report the upgrade results:
-   - Previous version vs new version for each component.
-   - Whether the upgrade succeeded or failed.
-4. Run `/muggle:muggle-status` again to confirm everything is healthy after upgrade.
+
+2. Capture CLI versions:
+   - Installed CLI: `muggle --version`
+   - Latest on npm: `npm view @muggleai/works version`
+   - Detect install location: `npm ls -g @muggleai/works --depth=0` (falls back to `pnpm ls -g @muggleai/works` if not found)
+
+3. **If installed CLI < latest on npm**, upgrade the CLI itself before touching Electron:
+   - npm global install: `npm install -g @muggleai/works@latest`
+   - pnpm global install: `pnpm add -g @muggleai/works@latest`
+   - If neither is detected, report the situation and ask the user how the CLI was installed before proceeding.
+
+4. Run `muggle upgrade` to pull the Electron runner version that the (now-latest) CLI expects.
+   - Note: `muggle upgrade` only manages the Electron runner — it does NOT upgrade the CLI npm package. That is why step 3 must run first.
+
+5. Run `/muggle:muggle-status` again to confirm everything is healthy after upgrade.
 
 ## Output
 
-Show a before/after version comparison. If the upgrade fails at any step, report the error and suggest running `/muggle:muggle-repair`.
+Show a before/after table for **CLI**, **Electron runner**, **MCP server**, and **Auth**. Call out any version that did not change so the user understands what shipped vs what was already current.
+
+If the upgrade fails at any step, report the error and suggest running `/muggle:muggle-repair`.

package/dist/release-manifest.json

@@ -1,7 +1,7 @@
 {
-  "release": "4.8.1",
-  "buildId": "run-20-1",
-  "commitSha": "8cd42b4b70c049e44510010003084227b04229a8",
-  "buildTime": "2026-04-14T21:44:51Z",
+  "release": "4.8.3",
+  "buildId": "run-23-1",
+  "commitSha": "db2ab1ae29f982b0a12db6dbd2a334cc8016f016",
+  "buildTime": "2026-04-14T23:24:16Z",
   "serviceName": "muggle-ai-works-mcp"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@muggleai/works",
     "mcpName": "io.github.multiplex-ai/muggle",
-    "version": "4.8.1",
+    "version": "4.8.3",
     "description": "Ship quality products with AI-powered E2E acceptance testing that validates your web app like a real user — from Claude Code and Cursor to PR.",
     "type": "module",
     "main": "dist/index.js",
@@ -41,14 +41,14 @@
         "test:watch": "vitest"
     },
     "muggleConfig": {
-        "electronAppVersion": "1.0.59",
+        "electronAppVersion": "1.0.60",
         "downloadBaseUrl": "https://github.com/multiplex-ai/muggle-ai-works/releases/download",
         "runtimeTargetDefault": "production",
         "checksums": {
-            "darwin-arm64": "c6da3f7f6b6875174a70a6c065554ed051ff99f731470e161ab71d9a9e568a87",
-            "darwin-x64": "ff93b24724fd415b99c40bcce2cc90a31e453a6408aad45a63480ff92606e7b0",
-            "win32-x64": "59bc67ea0a067fb4a204b87c73bf8cc387e705307f77ec96202822ff14b587fa",
-            "linux-x64": "714c93f586ac423377d9061924d2f703c175e3b541ef6ad22c96f6c20d3f4ea0"
+            "darwin-arm64": "a1e084b32ebc28fa823bcc9161959bd3618f0c5e45f41f946b5efa9192b8b15b",
+            "darwin-x64": "0605176a152b12149015b500b5d04dfaec06a5f3ed4d615d5442437cbaa2ba3a",
+            "win32-x64": "f6c9a243894720420229d37ff8915827e56c5aa2f21dd887a0f476d952698ad8",
+            "linux-x64": "4404163f56b664c1d8c040435ef981d1ff6583e2ba2e4b38ea4375afecd1c204"
         }
     },
     "dependencies": {

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "muggle",
   "description": "Run real-browser end-to-end (E2E) acceptance tests on your web app from any AI coding agent. Generate test scripts from plain English, replay them on localhost, capture screenshots, and validate user flows like signup, checkout, and dashboards. Works across Claude Code, Cursor, Codex, and Windsurf.",
-  "version": "4.8.1",
+  "version": "4.8.3",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/plugin/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "muggle",
   "displayName": "Muggle AI",
   "description": "Ship quality products with AI-powered end-to-end (E2E) acceptance testing that validates your web app like a real user — from Claude Code and Cursor to PR.",
-  "version": "4.8.1",
+  "version": "4.8.3",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/plugin/skills/do/e2e-acceptance.md

@@ -1,7 +1,15 @@
-# E2E / acceptance agent
+# E2E / acceptance agent (Stage 6/7)
 
 You are running **end-to-end (E2E) acceptance** test cases against code changes using Muggle AI's local testing infrastructure. These tests simulate real users in a browser — they are not unit tests.
 
+## Turn preamble
+
+Start the turn with:
+
+```
+**Stage 6/7 — E2E acceptance** — running browser tests against the validation target from pre-flight.
+```
+
 ## Design
 
 E2E acceptance testing runs **locally** using the `test-feature-local` approach:
@@ -15,32 +23,35 @@ This guarantees E2E acceptance tests always run — no dependency on cloud repla
 
 ## Input
 
-You receive:
-- The Muggle project ID
+You receive everything from `state.md` already — pre-flight resolved it:
+
+- `localUrl` — the locally running dev server URL
+- `projectId` — the chosen Muggle project
+- The validation strategy (`local-e2e`, `staging-replay`, `unit-only`, `skip`)
+- Test-user credential status (existing / new / skip)
 - The list of changed repos, files, and a summary of changes
 - The requirements goal
-- `localUrl` per repo (from `muggle-repos.json`) — the locally running dev server URL
 
 ## Your Job
 
-### Step 0: Resolve Local URL
+### Step 0: Consume pre-flight (no user questions)
+
+Read `state.md`. If the validation strategy is `unit-only` or `skip`, **do not run this stage** — skip to stage 7 and record the skip reason. Otherwise use `localUrl` directly; **do not ask the user** for it.
+
+If `localUrl` or `projectId` is missing from `state.md`, that is a pre-flight bug. **Do not paper over it by asking the user** — escalate once with the session path and halt. The fix is to expand `pre-flight.md`, not to grow a new question here.
 
-Read `localUrl` for each repo from the context. If it is not provided, ask the user:
-> "E2E acceptance testing requires a running local server. What URL is the `<repo>` app running on? (e.g. `http://localhost:3000`)"
+### Step 0.5: Pre-flight verification probes
 
-**Do not skip E2E acceptance tests.** Wait for the user to provide the URL before proceeding.
+Before launching Electron, run these live checks and fail loudly if any fails:
 
-### Step 1: Check Authentication
+1. `curl -s -o /dev/null -w "%{http_code}" <localUrl>` — expect 2xx or 3xx. If the dev server isn't up, halt with the exact command the user needs to start it.
+2. If a backend URL is recorded, probe its health endpoint. A 5xx or unreachable backend means the dashboard will render in an error state and test results will be meaningless — halt.
+3. `muggle-remote-auth-status` — must be `authenticated`. If not, the pre-flight missed this; escalate.
+4. If test credentials were marked `existing`, confirm the Auth0 tenant in the repo's env matches the tenant the secrets were created under (recorded in `state.md`). Tenant mismatch → halt with "existing secrets target tenant X, local dev targets tenant Y — update pre-flight to collect new credentials."
 
-- `muggle-remote-auth-status`
-- If **authenticated**: print the logged-in email and ask via `AskQuestion`:
-  > "You're logged in as **{email}**. Continue with this account?"
-  - Option 1: "Yes, continue"
-  - Option 2: "No, switch account"
-  If the user picks "switch account", call `muggle-remote-auth-login` with `forceNewSession: true` then `muggle-remote-auth-poll`.
-- If **not signed in or expired**: `muggle-remote-auth-login` then `muggle-remote-auth-poll`
+### Step 1: Authentication already verified
 
-Do not skip or assume auth.
+Pre-flight handled auth. If `muggle-remote-auth-status` somehow shows expired here (session clock skew, etc.), re-auth silently via `muggle-remote-auth-login` + `muggle-remote-auth-poll` — but do not ask the user "continue with this account?" again.
 
 ### Step 2: Get Test Cases
 

package/plugin/skills/do/impact-analysis.md

@@ -1,7 +1,15 @@
-# Impact Analysis Agent
+# Impact Analysis Agent (Stage 3/7)
 
 You are analyzing git repositories to determine which ones have actual code changes that need to go through the dev cycle pipeline.
 
+## Turn preamble
+
+Start the turn with:
+
+```
+**Stage 3/7 — Impact analysis** — diffing each affected repo against its default branch.
+```
+
 ## Input
 
 You receive:

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

@@ -1,7 +1,29 @@
-# PR Creation Agent
+# PR Creation Agent (Stage 7/7)
 
 You are creating pull requests for each repository that has changes after a successful dev cycle run.
 
+## Turn preamble
+
+Start the turn with:
+
+```
+**Stage 7/7 — Open PR** — rendering the visual walkthrough and pushing the PR.
+```
+
+## Non-negotiable: visual walkthrough is required
+
+**You MUST invoke `muggle-pr-visual-walkthrough` (Mode B) to render the E2E section of the PR body.** Hand-writing the PR body with a text summary and `gh pr create` is a stage failure — reviewers rely on the dashboard links and per-step screenshots the walkthrough produces.
+
+If the E2E stage was skipped (validation was `unit-only` or `skip`), you may omit the walkthrough section — but mark the PR title with `[UNVERIFIED]` or `[UNIT-ONLY]` accordingly, and record the reason in the PR body under `## Validation`.
+
+Before calling `gh pr create`, self-check:
+
+- [ ] `muggle-pr-visual-walkthrough` was invoked (or the skip reason is recorded).
+- [ ] The `body` returned by the skill is embedded verbatim in the PR body.
+- [ ] If `comment` is non-null, it will be posted as a follow-up after the PR is created.
+
+If you cannot check all three, **halt** — do not create the PR. Fix the upstream stage first.
+
 ## Input
 
 You receive:

package/plugin/skills/do/pre-flight.md

@@ -0,0 +1,104 @@
+# Pre-flight Agent (Stage 1/7)
+
+You are running the **only user-facing stage** of the muggle-do dev cycle. Your job is to consolidate every ambiguity — task scope, repos, validation strategy, environment, credentials, PR target — into a **single turn** so the rest of the cycle can run unattended.
+
+**Non-negotiable:** Never split pre-flight across multiple turns. Detect what you can silently, then ask every remaining question at once. If you find yourself asking a follow-up, you failed — fold the follow-up back into this file so the next run covers it.
+
+## Turn preamble
+
+Start the turn with:
+
+```
+**Stage 1/7 — Pre-flight** — consolidating everything the cycle needs before going silent.
+```
+
+## Input
+
+You receive:
+
+- The user's task description (from `$ARGUMENTS`).
+- The list of configured repos (names + paths) from the Muggle config.
+- Any session directory that already exists (resumption case).
+
+## Silent detection (do this first — no user prompts)
+
+Before asking anything, gather every fact you can resolve without the user:
+
+1. **Candidate repo(s).** Match keywords in the task description against configured repo names. If one repo is an obvious match, propose it as the default; if two or three are plausible, list them.
+2. **Current branch and default branch** for each candidate repo. Run `git -C <repo> symbolic-ref refs/remotes/origin/HEAD --short` and `git -C <repo> branch --show-current`. If the current branch is the default, the pre-flight must collect a new branch name.
+3. **Running dev server.** Scan common dev ports — `lsof -iTCP -sTCP:LISTEN -nP | grep -E ':(3000|3001|3999|4200|5173|8080)'` — and hit `/` with `curl -s -o /dev/null -w "%{http_code}"` to confirm 2xx.
+4. **Running backend.** If the repo's `.env.local` (or equivalent) declares a backend URL (e.g. `REACT_APP_BACKEND_BASE_URL=http://localhost:5050`), probe the health endpoint; note up/down.
+5. **Muggle MCP auth.** Call `muggle-remote-auth-status`. If expired, you will ask to re-auth in the questionnaire.
+6. **Candidate Muggle projects.** Call `muggle-remote-project-list` and rank by semantic match against the task description and the repo's dev URL.
+7. **Existing test-user secrets.** For each candidate Muggle project, call `muggle-remote-secret-list` and note whether `managed_profile_email` / `managed_profile_password` exist.
+8. **Auth0 tenant in use for local dev.** Grep the repo's env file for `*AUTH0_DOMAIN*`; record the tenant. This tells the user whether the staging-tenant test user will work or not.
+
+## The consolidated questionnaire
+
+Present **one `AskQuestion`** (or the platform's structured-selection equivalent) that collects every remaining decision. Use detected values as defaults whenever possible. Questions to include, in this order:
+
+1. **Task scope clarification** — only if the task description is genuinely ambiguous. Offer 2–3 interpretations as options plus "Other — type a clarification." If the task is unambiguous, omit.
+2. **Repo(s) to modify** — pre-selected with the best silent match. "Confirm <repo>" / "Change repo" / "Multi-repo (list them)".
+3. **Branch name** — default: `users/<user>/<slug>` derived from the task. "Use default" / "Use different name (type)".
+4. **Validation strategy** — the single most important question. Options:
+   - **Local E2E** (Muggle Electron against a running localhost) — default if a dev server was detected.
+   - **Staging replay** — for changes already deployed to a preview URL.
+   - **Unit tests only** — skip E2E, acceptable for pure refactors or backend-only changes.
+   - **Skip validation** — explicit opt-out; the PR title gets `[UNVERIFIED]`.
+5. **Local URL** — only if validation is Local E2E. Default: the detected port. "Confirm `<detected>`" / "Type a different URL".
+6. **Backend reachable?** — only if validation is Local E2E and a backend URL is declared. If the health probe failed, ask "Start the backend now and I'll re-probe" / "Proceed anyway" / "Skip to unit tests only".
+7. **Muggle project** — pre-selected with the best silent match. "Use <top match>" / "Use a different existing project (list)" / "Create new".
+8. **Test-user credentials** — only if validation is Local E2E AND the Auth0 tenant in the repo differs from the tenant the managed secrets were created under. Options: "Reuse existing secrets (may fail if tenant mismatch — will surface failure)" / "Create new secrets for this tenant (provide email + password)" / "Switch to staging replay".
+9. **PR target branch** — default: the repo's default branch. "Use default" / "Target a different branch".
+10. **Re-auth Muggle MCP?** — only if auth was missing/expired. "Log in now" / "Abort".
+
+If fewer than two of the above need the user, still gather them in a single turn — never open a second round.
+
+## Output
+
+After the user answers, write **`state.md`** with every resolved value, verbatim, in this format:
+
+```markdown
+# Session state
+
+**Slug:** <slug>
+**Current stage:** 1/7 (pre-flight complete)
+**Last update:** <ISO-8601 timestamp>
+
+## Pre-flight answers
+
+- Task: <one-line goal>
+- Repos: <repo1>, <repo2>
+- Branch: <branch-name>
+- Validation: <strategy>
+- Local URL: <url or N/A>
+- Backend status: <up | down | N/A>
+- Muggle project: <name> (<uuid>)
+- Test credentials: <existing | new | skip>
+- PR target: <branch>
+- Auth status: <ok | re-authed | N/A>
+
+## Blockers
+<none | bulleted list>
+```
+
+Also initialize `iterations/001.md` with a header:
+
+```markdown
+# Iteration 001 — <ISO-8601 timestamp>
+
+### Stage 1/7 — Pre-flight (<timestamp>)
+
+<verbatim copy of pre-flight answers>
+```
+
+## Handoff
+
+Return control to the muggle-do driver with a one-line summary: `pre-flight complete, proceeding silently through stages 2–7`. Do not print the pre-flight answers again — they are in `state.md` and the iteration log.
+
+## Non-negotiables
+
+- Exactly **one** user turn. Zero follow-up questions inside this stage.
+- Silent detection **must** run before the questionnaire — never ask for a value you can detect.
+- Every detected value is a default, not a lock — the user can always override via "Type a different …".
+- Missing `state.md` or `iterations/001.md` at the end of this stage is a stage failure.

package/plugin/skills/do/requirements.md

@@ -1,7 +1,17 @@
-# Requirements Analysis Agent
+# Requirements Analysis Agent (Stage 2/7)
 
 You are analyzing a user's task description to extract structured requirements for an autonomous development cycle.
 
+## Turn preamble
+
+Start the turn with:
+
+```
+**Stage 2/7 — Requirements** — extracting structured goals from the pre-flight-clarified task.
+```
+
+Pre-flight already resolved ambiguity via the consolidated questionnaire. **Do not ask the user any questions here** — infer silently and record assumptions in Notes.
+
 ## Input
 
 You receive:

package/plugin/skills/do/unit-tests.md

@@ -1,7 +1,15 @@
-# Unit Test Runner Agent
+# Unit Test Runner Agent (Stage 5/7)
 
 You are running unit tests for each repository that has changes in the dev cycle pipeline.
 
+## Turn preamble
+
+Start the turn with:
+
+```
+**Stage 5/7 — Unit tests** — running each repo's test suite.
+```
+
 ## Input
 
 You receive:

package/plugin/skills/do/validate-code.md

@@ -1,7 +1,15 @@
-# Code Validation Agent
+# Code Validation Agent (Stage 4/7)
 
 You are validating that each repository's git state is ready for the dev cycle pipeline.
 
+## Turn preamble
+
+Start the turn with:
+
+```
+**Stage 4/7 — Validate code** — checking branch and commit state for each repo with changes.
+```
+
 ## Input
 
 You receive:

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

@@ -6,9 +6,9 @@ disable-model-invocation: true
 
 # Muggle Do
 
-Muggle Do is the command for the Muggle AI development workflow.
+Muggle Do runs a battle-tested autonomous dev cycle: **pre-flight → requirements → impact analysis → validate code → unit tests → E2E acceptance → open PR**.
 
-It runs a battle-tested autonomous dev cycle: requirements -> impact analysis -> validate code -> coding -> unit tests -> E2E acceptance tests -> open PRs.
+The design goal is **fire and review**: the user answers one consolidated pre-flight questionnaire, then walks away. Every subsequent stage runs unattended until completion or a genuine blocker.
 
 For maintenance tasks, use the dedicated skills:
 
@@ -20,34 +20,78 @@ For maintenance tasks, use the dedicated skills:
 
 Treat `$ARGUMENTS` as the user command:
 
-- Empty / `help` / `menu` / `?` -> show menu and session selector.
-- Anything else -> treat as a new task description and start/resume a dev-cycle session.
+- Empty / `help` / `menu` / `?` → show menu and session selector.
+- Anything else → treat as a new task description and start/resume a dev-cycle session.
+
+## The seven stages
+
+| # | Stage | File | User-facing? |
+| :- | :---- | :--- | :----------- |
+| 1 | Pre-flight | [../do/pre-flight.md](../do/pre-flight.md) | **Yes — single consolidated turn** |
+| 2 | Requirements | [../do/requirements.md](../do/requirements.md) | No |
+| 3 | Impact analysis | [../do/impact-analysis.md](../do/impact-analysis.md) | No |
+| 4 | Validate code | [../do/validate-code.md](../do/validate-code.md) | No |
+| 5 | Unit tests | [../do/unit-tests.md](../do/unit-tests.md) | No |
+| 6 | E2E acceptance | [../do/e2e-acceptance.md](../do/e2e-acceptance.md) | No |
+| 7 | Open PR | [../do/open-prs.md](../do/open-prs.md) | No |
+
+**Stage 1 (pre-flight) is the ONLY stage that talks to the user.** Stages 2–7 run silently to completion. If a later stage hits a genuine blocker that the pre-flight didn't cover, escalate with a single terminal message — do not open a second round of questions.
+
+## Front-loading (stage 1 non-negotiable)
+
+All ambiguity — task scope, repo selection, validation strategy, localhost URL, backend health, Muggle project, test-user credentials, branch name, PR target — is resolved in a **single** pre-flight turn. See `pre-flight.md` for the exact questionnaire.
+
+**Red-flag behaviors (do not do):**
+
+- Asking a clarifying question mid-cycle because "I didn't think of that at pre-flight."
+- Starting a dev server mid-cycle and discovering the port is wrong.
+- Reaching the E2E stage before knowing how the user wants it validated.
+- Asking the user to "pick one" across multiple turns instead of one turn.
+
+If any of these happen, the pre-flight was incomplete — treat it as a skill bug, not a user bug, and expand `pre-flight.md` to cover the missed case after the run.
 
 ## Session model
 
-Use `.muggle-do/sessions/<slug>/` with these files:
+Every run writes to `.muggle-do/sessions/<slug>/`:
 
-- `state.md`
-- `requirements.md`
-- `iterations/<NNN>.md`
-- `result.md`
+- `state.md` — one-screen live status: current stage (N/7), last update timestamp, pre-flight answers verbatim, any blockers.
+- `iterations/<NNN>.md` — append-only log of stage transitions for iteration NNN: what ran, what was decided, what artifacts were produced.
+- `requirements.md` — frozen output of stage 2.
+- `result.md` — final summary written by stage 7 (PR URLs, E2E outcome, open issues).
 
-On each stage transition, update `state.md` and append stage output to the active iteration file.
+**On every stage transition, you MUST:**
 
-## Dev cycle agents
+1. Append a dated entry to the active `iterations/<NNN>.md`: `### Stage N/7 — <name> (<timestamp>)` followed by the stage's output.
+2. Rewrite `state.md` to reflect the new current stage and any relevant counters.
 
-Use the supporting files in the `../do/` directory as stage-specific instructions:
+If these files don't exist, create them — missing session files means the user lost visibility into the cycle, which is the exact failure mode this skill exists to prevent.
 
-- [requirements.md](../do/requirements.md)
-- [impact-analysis.md](../do/impact-analysis.md)
-- [validate-code.md](../do/validate-code.md)
-- [unit-tests.md](../do/unit-tests.md)
-- [e2e-acceptance.md](../do/e2e-acceptance.md)
-- [open-prs.md](../do/open-prs.md)
+## Turn preamble
+
+Each stage turn MUST begin with one line in this form before any other output:
+
+```
+**Stage N/7 — <stage name>** — <one-line intent>
+```
+
+This is how the user can tell, at a glance, what phase the cycle is in without parsing a long response.
 
 ## Guardrails
 
-- Do not skip unit tests before E2E acceptance tests.
-- Do not skip E2E acceptance tests due to missing scripts; generate when needed.
-- If the same stage fails 3 times in a row, escalate with details.
-- If total iterations reach 3 and E2E acceptance tests still fail, continue to PR creation with `[E2E FAILING]`.
+- **No mid-cycle user questions.** Anything not covered by pre-flight is a skill bug; escalate once, do not loop.
+- **Do not skip unit tests before E2E acceptance tests.**
+- **Do not skip E2E acceptance tests due to missing scripts** — generate when needed.
+- **Do not hand-write the E2E block of the PR body.** The `open-prs.md` stage MUST invoke `muggle-pr-visual-walkthrough` Mode B to render the screenshots-and-steps section. Hand-writing it loses the dashboard links the user relies on for review.
+- **If the same stage fails 3 times in a row, escalate with details.**
+- **If total iterations reach 3 and E2E acceptance tests still fail**, continue to PR creation with `[E2E FAILING]` in the title; the visual walkthrough section makes the failures reviewable.
+
+## Completion contract
+
+When stage 7 finishes, the final message to the user contains at minimum:
+
+- PR URL(s)
+- E2E status (passing / `[E2E FAILING]`)
+- Link to the run dashboard for each test case (via the walkthrough skill output)
+- Path to `result.md` for full details
+
+No other content. The user already read the walkthrough in the PR body — do not re-summarize it here.

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

@@ -5,17 +5,29 @@ description: Update Muggle AI to latest version. Use when user types muggle upgr
 
 # Muggle Upgrade
 
-Update all Muggle AI components to the latest published version.
+Update all Muggle AI components to the latest published version. This means **both** the `@muggleai/works` CLI on npm **and** the Electron runner the CLI manages.
 
 ## Steps
 
 1. Run `/muggle:muggle-status` checks to capture current versions.
-2. Run `muggle upgrade` to check GitHub releases for the latest electron-app version and download it.
-3. Report the upgrade results:
-   - Previous version vs new version for each component.
-   - Whether the upgrade succeeded or failed.
-4. Run `/muggle:muggle-status` again to confirm everything is healthy after upgrade.
+
+2. Capture CLI versions:
+   - Installed CLI: `muggle --version`
+   - Latest on npm: `npm view @muggleai/works version`
+   - Detect install location: `npm ls -g @muggleai/works --depth=0` (falls back to `pnpm ls -g @muggleai/works` if not found)
+
+3. **If installed CLI < latest on npm**, upgrade the CLI itself before touching Electron:
+   - npm global install: `npm install -g @muggleai/works@latest`
+   - pnpm global install: `pnpm add -g @muggleai/works@latest`
+   - If neither is detected, report the situation and ask the user how the CLI was installed before proceeding.
+
+4. Run `muggle upgrade` to pull the Electron runner version that the (now-latest) CLI expects.
+   - Note: `muggle upgrade` only manages the Electron runner — it does NOT upgrade the CLI npm package. That is why step 3 must run first.
+
+5. Run `/muggle:muggle-status` again to confirm everything is healthy after upgrade.
 
 ## Output
 
-Show a before/after version comparison. If the upgrade fails at any step, report the error and suggest running `/muggle:muggle-repair`.
+Show a before/after table for **CLI**, **Electron runner**, **MCP server**, and **Auth**. Call out any version that did not change so the user understands what shipped vs what was already current.
+
+If the upgrade fails at any step, report the error and suggest running `/muggle:muggle-repair`.