@muggleai/works 4.12.2 → 4.12.4

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

@@ -43,266 +43,52 @@ All launched processes are tracked in `/tmp/muggle-test-prepare.json`:
 }
 ```
 
-The `testing_scope` field records what the user is testing (from Step 1). The `excluded_services` field records services the user said can't run locally (from Step 2), so other skills understand what's intentionally absent vs. forgotten.
+`testing_scope` records what the user is testing (from [scope](./steps/scope.md)). `excluded_services` records services the user said can't run locally (from [viability-check](./steps/viability-check.md)).
 
-**On every invocation**, check this file first. If it exists with live PIDs (verify with `kill -0`), present the running services and ask:
-
-Use `AskUserQuestion`:
+**On every invocation**, check this file first. If it exists with live PIDs (verify with `kill -0`), `AskUserQuestion`:
 - Option 1: "Keep them running — skip to testing"
 - Option 2: "Tear down and start fresh"
 - Option 3: "Add more services to the running set"
 
-Prune any dead PIDs silently (the process crashed on its own — no point asking about it).
+Prune dead PIDs silently.
 
 ## Preferences
 
 Gates run per [`preference-gates/README.md`](../muggle-preferences/preference-gates/README.md).
 
-| Preference | Step | Decision it gates |
-|------------|------|-------------------|
-| `autoRebase` | 0 | Rebase onto `origin/<default>` before starting dev servers (see [`_shared/rebase-before-e2e.md`](../_shared/rebase-before-e2e.md)) |
+| Preference | Gates |
+|------------|-------|
+| `autoRebase` | [rebase-check](./steps/rebase-check.md) — rebase onto `origin/<default>` before starting dev servers |
 
 ## Workflow
 
-### Step 0: Rebase check (gated by `autoRebase`)
-
-Fire per [`_shared/rebase-before-e2e.md`](../_shared/rebase-before-e2e.md) when `behind > 0`. Otherwise skip silently.
-
-### Step 1: What Are You Testing?
-
-Before discovering services, understand the shape of the testing so you can scope correctly. Use `AskUserQuestion`:
-
-> "What are you testing locally?"
-
-- Option 1: "A frontend feature — I need the UI and its backend dependencies running"
-- Option 2: "A backend API — I just need the API server running"
-- Option 3: "The full stack — everything needs to be up"
-
-This scopes the rest of the workflow. If the user is testing a backend API, they probably don't need a frontend dev server. If they're testing a frontend feature, they need the frontend plus whatever backends it talks to. Keep this answer in mind when presenting service candidates in Step 3 — pre-check the ones that match and leave the rest unchecked.
-
-### Step 2: Viability Check
-
-Some services can't run on a developer's machine by design — they need production secrets, HSMs, specific certificates, or cloud-only infrastructure. Don't waste time trying to discover or start them.
-
-**If the user already volunteered this information** in their initial message (e.g., "the payment-gateway can't run locally"), acknowledge it and skip the question — don't re-ask what they already answered.
-
-Otherwise, use `AskUserQuestion`:
-
-> "Are there any services in your stack that **can't** run locally? (e.g., needs production secrets, specific certificates, or cloud-only infra)"
-
-- Option 1: "All my services can run locally"
-- Option 2: "Some can't — I'll tell you which"
-
-If the user picks option 2, collect the names. Acknowledge them and exclude from discovery.
-
-If an excluded service is a hard dependency for the app under test, **suggest testing in a preview/staging environment instead** — the user can merge first and use `/muggle-test` in remote mode, where everything is already up and running. Frame it as an alternative, not a dead end:
-
-> "Since **payment-gateway** can't run locally, you might get better coverage by merging and running `/muggle-test` against your preview environment — everything's wired up there. Want to continue with a partial local setup, or switch to remote testing?"
-
-- Option 1: "Continue locally — I'll work around the missing service"
-- Option 2: "Switch to remote — I'll merge and test on preview"
-
-If the user chooses remote, hand off to `/muggle-test` in remote mode and exit this skill.
-
-### Step 3: Identify Required Services & How to Start Them
-
-Figure out which services need to be running. Start by listing folder names in the **parent directory** of the current working directory — these are the most likely candidates.
-
-```bash
-ls -d "$(dirname "$PWD")"/*/ | xargs -I{} basename {}
-```
-
-Present folder names only (not contents) as candidates. Use `AskUserQuestion` with `multiSelect: true`:
-
-> "Which of these need to be running for your tests?"
-
-List each folder name as an option. Pre-check the ones that match the testing scope from Step 1 (e.g., if testing a frontend feature, pre-check the frontend and likely backends). Always include these fixed tail options:
-- "Just the current project (no other services needed)"
-- "None of these — I'll tell you what I need"
-
-If the user provides manual paths, verify they exist before continuing. If a path doesn't exist, report it and ask for correction.
-
-**Include the current working directory as a candidate** — the user might be editing the backend but also need the frontend (a sibling) started, or vice versa.
-
-**Immediately after the user selects services**, ask how they want to handle startup. This avoids making someone who prefers their own scripts wait through command detection before they get to say "I'll handle it."
-
-Use `AskUserQuestion`:
-
-> "How do you want to handle these?"
-
-- Option 1: "Check what's running, start what's missing for me"
-- Option 2: "I'll start them myself — just verify they're up when I'm done"
-
-If the user picks **option 2**: skip Steps 4-6. Wait for them to confirm they're ready, then go straight to Step 4 (Check What's Already Running) to verify everything is listening, and report readiness (Step 7).
-
-If the user picks **option 1**: proceed through Steps 4-7 as normal.
-
-### Step 4: Check What's Already Running
-
-Run port detection and (when the app declares a backend URL) backend-health probe per [`_shared/dev-server-readiness.md`](../_shared/dev-server-readiness.md). Cross-reference hits against the selected service directories. If a selected service appears to already be running (match by port or by the process's working directory), report it as ready:
-
-> "**backend-api** is already listening on port 3001 (PID 54321) — looks good."
-
-If **all** required services are already running, report readiness and skip straight to Step 7. No need to go through Steps 5-6.
-
-If some are running and some aren't, acknowledge the running ones and continue to Step 5 only for the missing services. Use `AskUserQuestion` for any already-running service the user might want restarted:
-- Option 1: "It's fine, keep it"
-- Option 2: "Restart it"
-
-For services that are already running and the user wants to keep, add them to the PID tracking file so cleanup can find them later, but mark them as `external: true` so cleanup knows not to kill them (the user started them independently).
-
-**Port already held** — when the user wants a port that is currently held by a process they did **not** select (typically a stale dev server from a sibling worktree). Surface the conflict via `AskUserQuestion`:
-
-> "Port 3999 is held by PID 87421 (you didn't select this process). How do you want to proceed?"
-
-- Option 1: "Use the next available port" (recommended — non-destructive)
-- Option 2: "Force-kill PID 87421 and claim port 3999"
-- Option 3: "Abort"
-
-**Option 1 — next available port:** probe `3999 + N` for `N = 1, 2, 3, ...` until `Test-NetConnection`/`lsof -i :<port>` returns nothing listening. Record the new port (and the env file edit, if `PORT=` is set in `.env.local` etc.) so downstream steps use it. The dev server may need a restart to pick up the new value.
-
-**Option 2 — force-kill (destructive):**
-- **Windows PowerShell:** `Get-NetTCPConnection -LocalPort <port> -ErrorAction SilentlyContinue | ForEach-Object { try { Stop-Process -Id $_.OwningProcess -Force -ErrorAction SilentlyContinue } catch { } }`
-- **POSIX:** `lsof -ti:<port> 2>/dev/null | xargs -r kill -9`
-
-Re-verify the port is free before continuing.
-
-### Step 4.5: Environment File Sanity
-
-The env file is **per-repo** — don't hardcode `.env.local`. Detect it: scan `package.json` `scripts/*` for `.env*` literals and known port vars (`PORT=`, `VITE_PORT=`); check framework config (`next.config.*`, `vite.config.*`).
-
-When a dependency on an env file exists:
-
-1. Check whether `<cwd>/<envfile>` exists. If yes, no-op.
-2. If absent, `git worktree list --porcelain` and check each sibling for the same filename.
-3. If found, surface via `AskUserQuestion`:
-
-   > "`<envfile>` is missing in this worktree but exists at `<sibling>/<envfile>`. Copy it before starting services?"
-
-   - Option 1: "Yes — copy from `<sibling>`"
-   - Option 2: "No — I'll provide it another way"
-
-4. If not found anywhere, report and ask how to proceed.
-
-Skip silently when no env file is referenced. The point is to catch the common worktree-bootstrap miss, not to mandate any specific file.
-
-### Step 5: Determine Start Commands
-
-For each required service that isn't already running, figure out how to start it. Propose the command so there's a shared understanding.
-
-Read **only** the indicator file that exists — don't read additional files.
-
-**Detection order:**
-
-| Indicator | Stack | Default command | What to check |
-|:----------|:------|:----------------|:--------------|
-| `package.json` | Node.js | `npm run dev` | Read `scripts` field: prefer `dev` > `start` > `serve` |
-| `Makefile` | Various | `make dev` | Just check existence; propose `make dev` or `make run` |
-| `Cargo.toml` | Rust | `cargo run` | Just check existence |
-| `go.mod` | Go | `go run .` | Just check existence |
-| `pyproject.toml` | Python | Check for framework | Read `[project.scripts]` or `[tool.poetry.scripts]` if present |
-| `requirements.txt` | Python | `python app.py` | Just check existence |
-| `docker-compose.yml` | Docker | `docker compose up` | Just check existence |
-
-If no indicator file is found, tell the user and ask them to provide the start command manually.
-
-**Present all proposed commands in a single summary:**
-
-```
-Service              Directory                          Command
-────────────────────────────────────────────────────────────────
-backend-api          ~/Github/backend-api               npm run dev
-auth-service         ~/Github/auth-service              go run .
-frontend             ~/Github/frontend                  npm run dev
-────────────────────────────────────────────────────────────────
-```
-
-Use `AskUserQuestion`:
-- Option 1: "Looks good, start them"
-- Option 2: "I need to edit some commands"
-
-If the user needs edits, collect corrections and re-present.
-
-### Step 5.5: Fresh-Worktree Install Probe
-
-Before launching `npm run dev` (or equivalent) in a Node service, check whether `node_modules/` is present and current. Stale or missing `node_modules/` causes silent runtime failures that look like the service is broken when actually the install is just missing.
-
-For each Node service the user selected:
-
-1. If `<service-dir>/node_modules/` is missing entirely → install is required.
-2. If `<service-dir>/package-lock.json` is newer than `<service-dir>/node_modules/.package-lock.json` → install is stale.
-3. Otherwise → install is current, no action needed.
-
-When install is required or stale, propose via `AskUserQuestion`:
-
-> "`<service-name>` needs a fresh `npm install` before starting (node_modules is missing/stale). Run `npm install --prefer-offline --no-audit --no-fund` now?"
-
-- Option 1: "Yes — install now"
-- Option 2: "No — skip; I know it's fine"
-
-**Never symlink `node_modules/` from a sibling worktree.** webpack's `resolve.symlinks: true` default rewrites paths to the shared real location; asset-identity tracking fails with `Can't handle conflicting asset info for sourceFilename`. Run a real per-worktree install.
-
-For non-Node services (Go, Rust, Python), skip this probe — their build systems handle dependency caching differently.
-
-### Step 6: Start Services
-
-For each service, launch in the background:
-
-```bash
-cd "<service-dir>" && nohup <command> > /tmp/muggle-prepare-<service-name>.log 2>&1 &
-echo $!
-```
-
-Capture the PID. Write all service entries to `/tmp/muggle-test-prepare.json`.
-
-**Startup verification** — first confirm the PID is alive (`kill -0 <pid> 2>/dev/null`), then run the two-stage readiness probe per [`_shared/dev-server-readiness.md`](../_shared/dev-server-readiness.md) against `/tmp/muggle-prepare-<service-name>.log`. Cap log-tail at 60s. Halt on whatever it surfaces; do not re-implement the ready-signal patterns here.
-
-If a service's PID dies immediately, read the last 20 lines of its log and show the user:
-
-> "**backend-api** exited right after starting. Here's the tail of its log:"
-
-Then ask how to proceed:
-- Option 1: "Skip it and continue with the others"
-- Option 2: "Let me fix it — I'll re-invoke later"
-
-**Port discovery** — if the port isn't known upfront, after the service starts, re-scan listening ports and try to identify which new port appeared. Record it in the tracking file if found. If not found within ~10 seconds, note the port as unknown — the service may take longer to boot.
-
-### Step 7: Report Readiness
-
-Whether you started the services or the user did, confirm that everything is listening:
-
-```
-Service              PID      Port     Status
-──────────────────────────────────────────────
-backend-api          12345    3001     Running
-auth-service         12346    8080     Running
-frontend             12347    3000     Running
-──────────────────────────────────────────────
-All 3 services verified. Ready for E2E testing.
-```
-
-If you launched the services, also show:
-```
-Logs: /tmp/muggle-prepare-*.log
-Cleanup: say "stop services" or re-invoke this skill.
-```
+Run the stages in this order. The sequence number is display-only — it lives only in this table for at-a-glance ordering; detail files and cross-references use slugs. Each row links to its detail file; read the file when you reach the stage.
+
+| # | Stage | Summary |
+|:--|:------|:--------|
+| 1 | [rebase-check](./steps/rebase-check.md) | Rebase onto default branch (gated) |
+| 2 | [scope](./steps/scope.md) | Frontend / backend / full stack |
+| 3 | [viability-check](./steps/viability-check.md) | Exclude services that can't run locally |
+| 4 | [identify-services](./steps/identify-services.md) | Pick required services + startup mode |
+| 5 | [check-running](./steps/check-running.md) | Detect what's already listening |
+| 6 | [env-file](./steps/env-file.md) | Env file present + correct |
+| 7 | [start-commands](./steps/start-commands.md) | Determine per-service start command |
+| 8 | [fresh-install](./steps/fresh-install.md) | Auto-install deps if missing/stale |
+| 9 | [start-services](./steps/start-services.md) | Launch + two-stage readiness |
+| 10 | [smoke-test](./steps/smoke-test.md) | HTTP + body sniff + log tail; clean-restart on fail |
+| 11 | [readiness-report](./steps/readiness-report.md) | Final ready table |
 
 ## Cleanup
 
-Cleanup is triggered when:
-- The user says "stop services", "tear down", "clean up", or "I'm done testing"
-- Another skill signals that a test run is complete
-- This skill is re-invoked and the user chooses "tear down and start fresh"
-
-**Cleanup steps:**
+Triggered when the user says "stop services", "tear down", "clean up", "I'm done testing", another skill signals run complete, or this skill is re-invoked with "tear down and start fresh".
 
 1. Read `/tmp/muggle-test-prepare.json`
-2. Skip any services marked `external: true` (the user started them independently)
-3. For each managed service, send `SIGTERM`: `kill <pid>`
-4. Wait ~2 seconds, verify with `kill -0`
-5. If still alive, `kill -9 <pid>`
-6. Remove log files: `rm -f /tmp/muggle-prepare-*.log`
-7. Remove the tracking file: `rm -f /tmp/muggle-test-prepare.json`
+2. Skip services marked `external: true`
+3. For each managed service: `kill <pid>` (SIGTERM)
+4. Wait ~2 s, verify with `kill -0`
+5. If still alive: `kill -9 <pid>`
+6. `rm -f /tmp/muggle-prepare-*.log`
+7. `rm -f /tmp/muggle-test-prepare.json`
 
 Report:
 
@@ -315,23 +101,21 @@ Stopped 3 services:
 
 ## Integration Contract (for other skills)
 
-When `muggle-test`, `muggle-do`, or `muggle-test-feature-local` want to check if services are ready:
-
-1. Check if `/tmp/muggle-test-prepare.json` exists
-2. Verify PIDs are alive with `kill -0`
-3. If all live → services are ready, proceed to test execution
-4. If missing or stale → invoke `muggle-test-prepare`
+`muggle-test-feature-local`, `muggle-do`, and local-mode `muggle-test` MUST invoke this skill before any workflow step. Idempotent — fast exit when healthy. Treat success as short-lived; re-invoke if more than a few minutes pass before testing. Never bypass on "the user knows their stack is up" — that assumption is why this skill exists.
 
-After a test run completes, the calling skill can invoke cleanup by re-invoking this skill with cleanup intent, or leave services running for the next run (the user chose lifecycle management, not clean-state resets).
+After a test run, the caller can re-invoke for cleanup or leave services running for the next run.
 
 ## Guardrails
 
-- **Verify first, offer to start second** — always check what's already running before proposing to start anything. If everything is up, just confirm readiness and move on.
-- **The user may prefer to start services themselves** — always offer that option. Some developers have their own startup scripts, tmux layouts, or docker-compose setups they'd rather use.
-- **Never start a process the user didn't approve** — every command is presented and confirmed before execution.
+- **Verify first, offer to start second** — check what's already running before proposing to start anything.
+- **The user may prefer to start services themselves** — always offer that option.
+- **Never start a process the user didn't approve.**
 - **Never read file contents outside confirmed directories** — folder names are discoverable; file contents require explicit user selection.
 - **Never leave orphan processes untracked** — every background PID goes into the tracking file.
-- **Never kill a process the user started independently** — services marked `external: true` survive cleanup.
-- **Never assume start commands** — always verify by checking project indicator files; always confirm with the user.
-- **Bail early on non-viable services** — don't attempt to start something the user said can't run locally.
-- **Idempotent** — if services are already tracked and alive, offer to keep them rather than double-starting.
+- **Never kill a process the user started independently** — `external: true` survives cleanup.
+- **Never assume start commands** — verify via indicator file; confirm with user.
+- **Bail early on non-viable services** — don't start what can't run locally.
+- **Idempotent** — already-tracked alive services are kept; [smoke-test](./steps/smoke-test.md) still runs against them.
+- **Port-listening is never enough** — smoke-test (HTTP + body sniff + log tail) is mandatory before the final report.
+- **Clean Restart is the recommended fix** — first option in the smoke-test diagnose-and-fix loop; lint/build/missing-deps issues need nuke-and-reinstall.
+- **Fresh install is automatic** — [fresh-install](./steps/fresh-install.md) notifies, doesn't ask.

package/dist/plugin/skills/muggle-test-prepare/steps/check-running.md

@@ -0,0 +1,31 @@
+# Check what's already running
+
+Run port detection and (when an app declares a backend URL) backend-health probe per [`../../_shared/dev-server-readiness.md`](../../_shared/dev-server-readiness.md). Cross-reference hits against selected service directories.
+
+> "**backend-api** is already listening on port 3001 (PID 54321) — looks good."
+
+If **all** required services are running, skip straight to [smoke-test](./smoke-test.md) — don't trust port-listening alone.
+
+If some are running, acknowledge and continue to [start-commands](./start-commands.md) only for the missing ones. For already-running services:
+- Option 1: "It's fine, keep it"
+- Option 2: "Restart it"
+
+Mark kept services as `external: true` in the tracking file so cleanup leaves them alone.
+
+## Port already held
+
+When the user wants a port held by a process they did **not** select (typically a stale dev server from a sibling worktree):
+
+> "Port 3999 is held by PID 87421 (you didn't select this process). How do you want to proceed?"
+
+- Option 1: "Use the next available port" (recommended — non-destructive)
+- Option 2: "Force-kill PID 87421 and claim port 3999"
+- Option 3: "Abort"
+
+**Option 1**: probe `3999 + N` for `N = 1, 2, …` until nothing listens. Record the new port and any env file edit (`PORT=` in `.env.local` etc.). Dev server may need restart to pick up.
+
+**Option 2 — force-kill (destructive):**
+- **Windows PowerShell:** `Get-NetTCPConnection -LocalPort <port> -ErrorAction SilentlyContinue | ForEach-Object { try { Stop-Process -Id $_.OwningProcess -Force -ErrorAction SilentlyContinue } catch { } }`
+- **POSIX:** `lsof -ti:<port> 2>/dev/null | xargs -r kill -9`
+
+Re-verify the port is free before continuing.

package/dist/plugin/skills/muggle-test-prepare/steps/env-file.md

@@ -0,0 +1,18 @@
+# Environment file sanity
+
+The env file is **per-repo** — don't hardcode `.env.local`. Detect by scanning `package.json` `scripts/*` for `.env*` literals and known port vars (`PORT=`, `VITE_PORT=`); check framework config (`next.config.*`, `vite.config.*`).
+
+When a dependency on an env file exists:
+
+1. Check `<cwd>/<envfile>` exists — if yes, no-op.
+2. If absent, `git worktree list --porcelain` and check each sibling for the same filename.
+3. If found:
+
+   > "`<envfile>` is missing in this worktree but exists at `<sibling>/<envfile>`. Copy it before starting services?"
+
+   - Option 1: "Yes — copy from `<sibling>`"
+   - Option 2: "No — I'll provide it another way"
+
+4. If not found anywhere, report and ask.
+
+Skip silently when no env file is referenced.

package/dist/plugin/skills/muggle-test-prepare/steps/fresh-install.md

@@ -0,0 +1,20 @@
+# Fresh install (clean-start default)
+
+Detect stack by indicator file, decide if install is missing/stale, run automatically (notify, don't ask). Only opt-out is aborting the skill.
+
+| Indicator | Stack | Stale check | Install command |
+|:----------|:------|:------------|:----------------|
+| `package.json` | Node | `node_modules/` missing OR `package-lock.json` newer than `node_modules/.package-lock.json` | `npm install --prefer-offline --no-audit --no-fund` |
+| `pyproject.toml` w/ `[tool.poetry]` | Poetry | `poetry.lock` newer than `.venv/pyvenv.cfg` (or `.venv/` missing) | `poetry install --no-interaction` |
+| `pyproject.toml` (PEP 621) + `uv.lock` | uv | `uv.lock` newer than `.venv/pyvenv.cfg` | `uv sync` |
+| `requirements.txt` | pip | `requirements.txt` newer than `.venv/pyvenv.cfg` (or `.venv/` missing) | `pip install -r requirements.txt` |
+| `Gemfile` | Bundler | `Gemfile.lock` newer than `vendor/bundle/` mtime | `bundle install` |
+| `composer.json` | Composer | `composer.lock` newer than `vendor/autoload.php` | `composer install --no-interaction` |
+| `pom.xml` | Maven | always (heavy — opt-in via `AskUserQuestion`) | `mvn -DskipTests install` |
+| `build.gradle*` | Gradle | always (heavy — opt-in via `AskUserQuestion`) | `gradle build -x test` |
+| `go.mod` | Go | skip — `go run`/`go build` handle deps |  |
+| `Cargo.toml` | Rust | skip — `cargo run`/`cargo build` handle deps |  |
+
+Notify one-liner: `Installing <service-name> (<stack>: <missing|stale>)…`.
+
+**Never symlink dep dirs** (`node_modules/`, `.venv/`, `vendor/bundle/`) from a sibling worktree — webpack rewrites paths via `resolve.symlinks: true` and Python/Ruby tooling has analogous issues. Run a real per-worktree install.

package/dist/plugin/skills/muggle-test-prepare/steps/identify-services.md

@@ -0,0 +1,28 @@
+# Identify required services & startup mode
+
+List folder names in the **parent directory** of the current working directory:
+
+```bash
+ls -d "$(dirname "$PWD")"/*/ | xargs -I{} basename {}
+```
+
+Present folder names only (not contents). `AskUserQuestion` with `multiSelect: true`:
+
+> "Which of these need to be running for your tests?"
+
+Pre-check the ones matching the testing scope from [scope](./scope.md). Always include:
+- "Just the current project (no other services needed)"
+- "None of these — I'll tell you what I need"
+
+Include the current working directory as a candidate. If the user provides manual paths, verify they exist.
+
+**Immediately after selection**, ask startup mode:
+
+> "How do you want to handle these?"
+
+- Option 1: "Check what's running, start what's missing for me"
+- Option 2: "I'll start them myself — just verify they're up when I'm done"
+
+**Option 2**: skip [start-commands](./start-commands.md), [fresh-install](./fresh-install.md), [start-services](./start-services.md). Wait for ready signal, then [check-running](./check-running.md), run [smoke-test](./smoke-test.md) against everything (the user-started case is exactly where the smoke test matters most), then [readiness-report](./readiness-report.md).
+
+**Option 1**: proceed through the normal flow.

package/dist/plugin/skills/muggle-test-prepare/steps/readiness-report.md

@@ -0,0 +1,26 @@
+# Final readiness report
+
+Only after every service passes [smoke-test](./smoke-test.md) or is skipped.
+
+```
+Service              PID      Port     Status         Smoke Test
+─────────────────────────────────────────────────────────────────
+backend-api          12345    3001     Running        ✓
+auth-service         12346    8080     Running        ✓
+frontend             12347    3000     Running        ✓
+─────────────────────────────────────────────────────────────────
+All services verified. Ready for E2E.
+```
+
+Surface skipped services so the caller knows the gap:
+
+```
+Skipped: payment-gateway — HTTP 500 on /
+```
+
+If you launched the services:
+
+```
+Logs: /tmp/muggle-prepare-*.log
+Cleanup: say "stop services" or re-invoke this skill.
+```

package/dist/plugin/skills/muggle-test-prepare/steps/rebase-check.md

@@ -0,0 +1,3 @@
+# Rebase check
+
+Gated by `autoRebase`. Fire per [`../../_shared/rebase-before-e2e.md`](../../_shared/rebase-before-e2e.md) when `behind > 0`. Otherwise skip silently.

package/dist/plugin/skills/muggle-test-prepare/steps/scope.md

@@ -0,0 +1,11 @@
+# Scope (what are you testing?)
+
+`AskUserQuestion`:
+
+> "What are you testing locally?"
+
+- Option 1: "A frontend feature — I need the UI and its backend dependencies running"
+- Option 2: "A backend API — I just need the API server running"
+- Option 3: "The full stack — everything needs to be up"
+
+Scopes the rest of the workflow. Record under `testing_scope` in the tracking file. Use it later to pre-check matching service candidates in [identify-services](./identify-services.md).

package/dist/plugin/skills/muggle-test-prepare/steps/smoke-test.md

@@ -0,0 +1,26 @@
+# Comprehensive smoke test
+
+Runs for **every** service in the tracking file, including `external: true`. Port-listening is not proof a service works — a stale dev server binds and returns 200 with a webpack error overlay.
+
+All three probes must pass:
+
+1. **HTTP** — `GET <serviceUrl>`, 3 s timeout, accept `2xx`/`3xx` (one redirect).
+2. **Body sniff** — match response body against broken-build markers in [`../../_shared/dev-server-readiness.md`](../../_shared/dev-server-readiness.md) → "Body sniff patterns".
+3. **Log tail** — scan last 200 lines of `/tmp/muggle-prepare-<service-name>.log` for failure patterns after the latest ready signal. Skip for `external: true` (no log).
+
+Use the primitives in `dev-server-readiness.md`. Don't re-implement.
+
+## Diagnose-and-fix loop
+
+On failure, show the concrete signal (HTTP code, sniff hit, or log line) and `AskUserQuestion`:
+
+> "**<service-name>** isn't healthy: `<signal>`. How do you want to proceed?"
+
+- Option 1: **Clean restart** (Recommended) — kill + [fresh-install](./fresh-install.md) + [start-services](./start-services.md) + re-run this step
+- Option 2: **Restart only** — kill + start-services + re-run this step
+- Option 3: **I'll fix it manually** — pause; re-run on user signal
+- Option 4: **Skip** — append to `excluded_services` with reason, continue
+
+Loop per service until pass or skip. Cap at **3 iterations** — then force a manual-intervention pause.
+
+For `external: true`, only Options 3 and 4 apply.

package/dist/plugin/skills/muggle-test-prepare/steps/start-commands.md

@@ -0,0 +1,29 @@
+# Determine start commands
+
+For each required service not already running, figure out how to start it. Read **only** the indicator file that exists.
+
+| Indicator | Stack | Default command | What to check |
+|:----------|:------|:----------------|:--------------|
+| `package.json` | Node.js | `npm run dev` | Read `scripts`: prefer `dev` > `start` > `serve` |
+| `Makefile` | Various | `make dev` | Existence; propose `make dev` or `make run` |
+| `Cargo.toml` | Rust | `cargo run` | Existence |
+| `go.mod` | Go | `go run .` | Existence |
+| `pyproject.toml` | Python | Check for framework | Read `[project.scripts]` or `[tool.poetry.scripts]` if present |
+| `requirements.txt` | Python | `python app.py` | Existence |
+| `docker-compose.yml` | Docker | `docker compose up` | Existence |
+
+If no indicator found, ask the user for the start command.
+
+Present all commands in a single summary:
+
+```
+Service              Directory                          Command
+────────────────────────────────────────────────────────────────
+backend-api          ~/Github/backend-api               npm run dev
+auth-service         ~/Github/auth-service              go run .
+frontend             ~/Github/frontend                  npm run dev
+────────────────────────────────────────────────────────────────
+```
+
+- Option 1: "Looks good, start them"
+- Option 2: "I need to edit some commands"

package/dist/plugin/skills/muggle-test-prepare/steps/start-services.md

@@ -0,0 +1,21 @@
+# Start services
+
+For each service, launch in the background:
+
+```bash
+cd "<service-dir>" && nohup <command> > /tmp/muggle-prepare-<service-name>.log 2>&1 &
+echo $!
+```
+
+Capture the PID. Write all service entries to `/tmp/muggle-test-prepare.json`.
+
+**Startup verification** — confirm PID alive (`kill -0 <pid> 2>/dev/null`), then run the two-stage readiness probe per [`../../_shared/dev-server-readiness.md`](../../_shared/dev-server-readiness.md) against the log. Cap log-tail at 60 s. Halt on whatever surfaces.
+
+If a PID dies immediately, show the last 20 log lines:
+
+> "**backend-api** exited right after starting. Here's the tail of its log:"
+
+- Option 1: "Skip it and continue with the others"
+- Option 2: "Let me fix it — I'll re-invoke later"
+
+**Port discovery** — if the port wasn't known upfront, re-scan listening ports after startup. Record in tracking file. If not found within ~10 s, mark port unknown.

package/dist/plugin/skills/muggle-test-prepare/steps/viability-check.md

@@ -0,0 +1,21 @@
+# Viability check
+
+Some services can't run on a developer's machine by design — production secrets, HSMs, specific certificates, cloud-only infra. Don't waste time trying to start them.
+
+If the user volunteered this in their initial message, acknowledge and skip the question. Otherwise:
+
+> "Are there any services in your stack that **can't** run locally? (e.g., needs production secrets, specific certificates, or cloud-only infra)"
+
+- Option 1: "All my services can run locally"
+- Option 2: "Some can't — I'll tell you which"
+
+If option 2, collect names and exclude from discovery.
+
+If an excluded service is a hard dependency for the app under test, suggest remote testing:
+
+> "Since **payment-gateway** can't run locally, you might get better coverage by merging and running `/muggle-test` against your preview environment. Want to continue with a partial local setup, or switch to remote testing?"
+
+- Option 1: "Continue locally — I'll work around the missing service"
+- Option 2: "Switch to remote — I'll merge and test on preview"
+
+If remote, hand off to `/muggle-test` in remote mode and exit.

package/dist/release-manifest.json

@@ -1,7 +1,7 @@
 {
-  "release": "4.12.2",
-  "buildId": "run-40-1",
-  "commitSha": "9039582dcc85172dff58bcebc185d8aaa495f947",
-  "buildTime": "2026-05-22T04:16:07Z",
+  "release": "4.12.4",
+  "buildId": "run-42-1",
+  "commitSha": "184a2b0b2eec344362e3ebb2a909684c4790f5d5",
+  "buildTime": "2026-05-22T23:47:18Z",
   "serviceName": "muggle-ai-works-mcp"
 }

package/dist/{src-ARTTHWNP.js → src-YR5UKLPC.js}

@@ -1 +1 @@
-export { DEFAULT_PREFERENCES, PREFERENCES_FILE_NAME, PREFERENCES_PROJECT_DIR_NAME, PREFERENCES_SCHEMA, PREFERENCES_VERSION, PREFERENCE_ALLOWED_VALUES, PreferenceKey, PreferenceValue, buildElectronAppChecksumsUrl, buildElectronAppReleaseAssetUrl, buildElectronAppReleaseTag, calculateFileChecksum, createApiKeyWithToken, createChildLogger, deleteApiKeyData, deleteCredentials, e2e_exports as e2e, formatPreferencesOneLiner, getApiKey, getApiKeyFilePath, getAuthService, getBundledElectronAppVersion, getCallerCredentials, getCallerCredentialsAsync, getChecksumForPlatform, getConfig, getCredentialsFilePath, getDataDir, getDownloadBaseUrl, getElectronAppChecksums, getElectronAppDir, getElectronAppVersion, getElectronAppVersionSource, getLocalQaTools, getLogger, getPlatformKey, getQaTools, getValidApiKeyData, getValidCredentials, hasApiKey, isElectronAppInstalled, isFirstRun, loadApiKeyData, loadCredentials, local_exports as localQa, mcp_exports as mcp, openBrowserUrl, performLogin, performLogout, pollDeviceCode, e2e_exports as qa, readGlobalPreferences, readProjectPreferences, resetConfig, resetLogger, resetPreference, resolveElectronAppPathOrNull, resolvePreferences, saveApiKey, saveApiKeyData, saveCredentials, startDeviceCodeFlow, toolRequiresAuth, validatePreference, verifyFileChecksum, writePreferences } from './chunk-I4VLYJ7M.js';
+export { DEFAULT_PREFERENCES, PREFERENCES_FILE_NAME, PREFERENCES_PROJECT_DIR_NAME, PREFERENCES_SCHEMA, PREFERENCES_VERSION, PREFERENCE_ALLOWED_VALUES, PreferenceKey, PreferenceValue, buildElectronAppChecksumsUrl, buildElectronAppReleaseAssetUrl, buildElectronAppReleaseTag, calculateFileChecksum, createApiKeyWithToken, createChildLogger, deleteApiKeyData, deleteCredentials, e2e_exports as e2e, formatPreferencesOneLiner, getApiKey, getApiKeyFilePath, getAuthService, getBundledElectronAppVersion, getCallerCredentials, getCallerCredentialsAsync, getChecksumForPlatform, getConfig, getCredentialsFilePath, getDataDir, getDownloadBaseUrl, getElectronAppChecksums, getElectronAppDir, getElectronAppVersion, getElectronAppVersionSource, getLocalQaTools, getLogger, getPlatformKey, getQaTools, getValidApiKeyData, getValidCredentials, hasApiKey, isElectronAppInstalled, isFirstRun, loadApiKeyData, loadCredentials, local_exports as localQa, mcp_exports as mcp, openBrowserUrl, performLogin, performLogout, pollDeviceCode, e2e_exports as qa, readGlobalPreferences, readProjectPreferences, resetConfig, resetLogger, resetPreference, resolveElectronAppPathOrNull, resolvePreferences, saveApiKey, saveApiKeyData, saveCredentials, startDeviceCodeFlow, toolRequiresAuth, validatePreference, verifyFileChecksum, writePreferences } from './chunk-CPF6AR2I.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@muggleai/works",
   "mcpName": "io.github.multiplex-ai/muggle",
-  "version": "4.12.2",
+  "version": "4.12.4",
   "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.93",
+    "electronAppVersion": "1.0.94",
     "downloadBaseUrl": "https://github.com/multiplex-ai/muggle-ai-works/releases/download",
     "runtimeTargetDefault": "production",
     "checksums": {
-      "darwin-arm64": "79edb82904ff247a3176d7f25e6aea879bde0befe9f50ae1c977f9de01e09278",
-      "darwin-x64": "2b13541aee90eec7cff3e0d92a963fa2508f91a195aee3774edd851f69a45442",
-      "linux-x64": "438d8c80602c6c9746a2b5a11c9236d11997827ca74376e0e0fef1952f38640c",
-      "win32-x64": "6ccac8d05d40ce6d6b976f3079cbc7ca4bb3714d3d5b67776a72cd9bbf324f53"
+      "darwin-arm64": "22731d8fac9b3ce7dc0490932a099fad0b7bab901e4efe3c2f8e44b4dd165bdb",
+      "darwin-x64": "0965f1a3f7b0db6a976650e26de024f0baea58102cf9acc93e8c69c6dfd8709f",
+      "linux-x64": "5280ae8ac73215f1c4f92d3b280eee0918341179485993493bd04f3f5a95b5b5",
+      "win32-x64": "a02bf08ba6f5463b1dad354824c6369738248e86ce5ef02644d2185fdc2d047f"
     }
   },
   "dependencies": {