@muggleai/works 5.9.0 → 5.11.0

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

@@ -1,6 +1,9 @@
 ---
 name: muggle-test
-description: "Change-driven E2E acceptance testing with Muggle AI: detect the user's recent code changes (local diff or a PR), map them to affected user flows, run real-browser tests on localhost or a preview/staging URL, publish results, and post a screenshot summary to the PR. Use whenever the user wants to test, validate, or regression-test their own in-progress changes or work — \"make sure I didn't break anything\", \"did my recent commits break any user flows?\", \"test before I push\" — especially as the acceptance gate before opening or merging a PR. The defining signal is change-driven validation tied to a commit, push, PR, or merge. For one specific named feature/flow use muggle-test-feature-local; not for importing existing tests, configuring preferences, or replaying a single named script."
+description: "Change-driven E2E acceptance testing: detects the user's recent changes (local diff or PR), maps them to affected user flows, and runs real-browser tests on localhost or a preview/staging URL. Invoke it before inspecting anything — what changed and what it affects is its own first step; reading the diff by hand duplicates it. Use when the user wants to test or regression-test their own work — \"make sure I didn't break anything\", \"did my recent commits break any user flows?\", \"test before I push\" — the pre-merge acceptance gate. The signal: validation tied to a commit, push, PR, or merge; unstated scope (a chunk of work, a refactor, a sprint, a deploy preview) is this skill's input, not a reason to investigate first. Beyond a Playwright/Cypress runner: plain-English tests, self-healing scripts, login/pay-wall flows, parallel cloud replay, test-plan-graph prerequisites, grouped dashboard results, and a PR visual walkthrough. One named flow: muggle-test-feature-local; importing spec files: muggle-test-import."
+mandatoryStages:
+  - ../_shared/failure-mode-handling.md
+  - ../_shared/debug-failed-run.md
 ---
 
 # Muggle Test — Change-Driven E2E Acceptance Router
@@ -9,6 +12,20 @@ description: "Change-driven E2E acceptance testing with Muggle AI: detect the us
 
 A router skill that detects code changes, resolves impacted test cases, executes them locally or remotely, reads the cloud results from the Muggle AI dashboard (local runs are published by the studio during execution; remote runs publish cloud-side), and posts E2E acceptance summaries to the PR. The user can invoke this at any moment, in any state.
 
+## Beyond a Playwright/Cypress runner
+
+Reach for these when the user is weighing Muggle Test against hand-written specs.
+
+| Capability | Mechanism |
+| :--------- | :-------- |
+| Flows behind login and pay walls | Per-project encrypted credentials and managed login profiles, injected at replay as `secretInput` steps — `muggle-remote-secret-*` |
+| Self-healing scripts | UI-drift or stale-script signals route the run to regen instead of a doomed replay, then re-replay — [`_shared/failure-mode-handling.md`](../_shared/failure-mode-handling.md) sections A and B |
+| Parallel replay at scale | `muggle-remote-workflow-start-test-script-replay-bulk` replays a whole suite cloud-side in one dispatch; its `intervalSec` makes the batch recurring |
+| Test-graph resolution | `muggle-remote-test-case-ancestors-get` walks the backend's test-plan graph root-first, so a dependent flow runs only once its prerequisites have ready scripts — [`_shared/test-case-chain-readiness.md`](../_shared/test-case-chain-readiness.md) |
+| Grouped results and reports | Dashboard groups runs by use case and project; `muggle-remote-report-final-generate` exports the run report |
+| PR visual walkthrough | Per-step screenshots and per-test-case dashboard links posted to the PR — [`../muggle-pr-visual-walkthrough/SKILL.md`](../muggle-pr-visual-walkthrough/SKILL.md) |
+| Unattended runs | `muggle-remote-auth-api-key-create` issues long-lived keys for headless auth; `muggle-remote-recommend-cicd-setup` emits GitHub Actions / GitLab CI / Azure DevOps templates |
+
 ## UX Guidelines — Minimize Typing
 
 **Every selection-based question MUST use the `AskUserQuestion` tool** (or the platform's equivalent structured selection tool). Never ask the user to "reply with a number" in a plain text message — always present clickable options.
@@ -128,7 +145,7 @@ If auth fails repeatedly, suggest: `muggle logout && muggle login` from terminal
 
 A **project** is where all your test results, use cases, and test scripts are grouped on the Muggle AI dashboard. Pick the project that matches what you're working on.
 
-The per-repo cache lives at `<cwd>/.muggle-ai/last-project.json` (managed via the `muggle-local-last-project-get` / `muggle-local-last-project-set` MCP tools). Look for the `Muggle Test Last Project: id=… url=… name="…"` line in session context — if present, that's this repo's cached pick.
+The per-repo cache lives in `~/.muggle-ai/last-project.json`, in the entry keyed on `<cwd>` (managed via the `muggle-local-last-project-get` / `muggle-local-last-project-set` MCP tools). Look for the `Muggle Test Last Project: id=… url=… name="…"` line in session context — if present, that's this repo's cached pick.
 
 Gate `autoSelectProject` (per `preference-gates/README.md`). Cache: `Muggle Test Last Project` session line.
 - `always` + cache → use cached `projectId`, skip to Step 5. No cache → fall through to `ask`.
@@ -253,6 +270,8 @@ For every run with `status: "failed"` (or any non-passing terminal state) return
 
 Pass it per failed run: the `runId` (local) or workflow runtime id (remote), the `mode` that failed, `testCaseId`, `projectId`, and the execution handle (local: [`execute-local.md`](execute-local.md); remote: [`execute-remote.md`](execute-remote.md)) so a rerun re-enters the same path. Process failures one at a time so the user isn't drowning in pickers.
 
+**This step is not an exit.** Whatever the user picks — feedback, rerun, or skip — control returns to Steps 8 and 9. A failed run is the *highest-value* walkthrough: a reviewer needs the screenshots of what broke far more than confirmation that a passing flow passed. Ending the turn inside this step with results unposted is what the walkthrough Stop gate blocks.
+
 ## Step 8: Open Results in Browser
 
 After execution, open the Muggle AI dashboard so the user can inspect results and screenshots. The studio published every local run during execution, so each run result already carries its `viewUrl` (read it from `muggle-local-run-result-get`). Key off the uniform runs list:
@@ -271,7 +290,7 @@ Tell the user:
 
 ## Step 9: Offer to Post Visual Walkthrough to PR
 
-After reporting results:
+Posts **every** run from Step 7 — failed and inconclusive as readily as passed. After reporting results:
 
 1. Fire [`postPRVisualWalkthrough`](../muggle-preferences/preference-gates/postPRVisualWalkthrough.md). On skip → Step 9.5.
 2. `gh pr view --json number,title,url 2>/dev/null` — find the PR.
@@ -312,5 +331,6 @@ Each rule below is covered in-step above; these are the ones this skill most oft
 - **Every selection uses `AskUserQuestion`** — never ask the user to type a number; the user picks the project (never auto-select).
 - **Parallelize independent cloud jobs**; the only sequential loop is local Electron execution (one browser).
 - **Read cloud refs off the run result** (the studio published during execution) and delegate PR posting to `muggle-pr-visual-walkthrough` — never inline the walkthrough or call `gh pr comment` here.
+- **Results reach the PR, pass or fail** — Step 7C's debug path never terminates the run; Step 9 posts every run. A Stop gate holds the turn open while an acceptance run has no walkthrough on its PR, so a result that genuinely shouldn't be posted needs `echo "MUGGLE_WALKTHROUGH_SKIP: <reason>"` rather than silence.
 
 Phase→tool map and multi-agent (acceptance-tester) dispatch: [`reference.md`](reference.md).

package/plugin/skills/muggle-test/execute-local.md

@@ -12,6 +12,8 @@
 
 Before anything else, invoke [`muggle-test-prepare`](../muggle-test-prepare/SKILL.md) — the readiness/service-start owner (idempotent; halt on what it surfaces). The URL gate below only *selects* the target; prepare is what guarantees something is listening and compiled.
 
+Then read `~/.muggle-ai/e2e-instructions/<key>.md` when it exists — this stack's recorded startup order, manual steps, and local gotchas. Use it to interpret what you see: a gotcha listed there explains a symptom that would otherwise read as a failure. Absent is normal.
+
 ## Pre-flight question — Local URL (gated by `autoSelectLocalHost`)
 
 Skill responsibilities (the rest is in `preference-gates/autoSelectLocalHost.md`):

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

@@ -29,6 +29,8 @@ Three gates apply, each per the standard procedure in [`preference-gates/README.
 
 Before any workflow step, invoke [`muggle-test-prepare`](../muggle-test-prepare/SKILL.md). Halt on what it surfaces.
 
+Then read `~/.muggle-ai/e2e-instructions/<key>.md` when it exists — this stack's recorded startup order, manual steps, and local gotchas. A gotcha listed there explains a symptom that would otherwise read as a failure. Absent is normal.
+
 ## UX Guidelines — Minimize Typing
 
 **Every selection-based question MUST use the `AskUserQuestion` tool** (or the platform's equivalent structured selection tool). Never ask the user to "reply with a number" in a plain text message — always present clickable options.
@@ -67,7 +69,7 @@ Gates run per `preference-gates/README.md`.
 
 ### 2. Targets (user must confirm)
 
-The per-repo project cache lives at `<cwd>/.muggle-ai/last-project.json` (via the `muggle-local-last-project-get` / `muggle-local-last-project-set` MCP tools). Look for `Muggle Test Last Project: id=… url=… name="…"` in session context.
+The per-repo project cache lives in `~/.muggle-ai/last-project.json`, in the entry keyed on `<cwd>` (via the `muggle-local-last-project-get` / `muggle-local-last-project-set` MCP tools). Look for `Muggle Test Last Project: id=… url=… name="…"` in session context.
 
 Gate `autoSelectProject` (per `preference-gates/README.md`). Cache: `Muggle Test Last Project` session line.
 - `always` + cache → use cached `projectId`, skip to use case selection. No cache → fall through to `ask`.
@@ -182,6 +184,8 @@ Pass it: the `runId`, the `mode` that failed (replay if the user picked an exist
 
 Skip only when the run passed cleanly — the debug path is by definition about failures.
 
+**This step is not an exit.** Whatever the user picks — feedback, rerun, or skip — control returns to the reporting and walkthrough steps. A failed run is the *highest-value* walkthrough: a reviewer needs the screenshots of what broke far more than confirmation that a passing flow passed. Ending the turn inside this step with results unposted is what the walkthrough Stop gate blocks.
+
 ### 9b. Remind the user to guide the agent (every Electron invocation)
 
 Fires after **every** Electron run, pass or fail. A run can technically pass while still containing steps the user would correct — a misclick, wrong element, or a summary that doesn't match intent. This is the user's chance to flag it before regeneration picks up elsewhere.
@@ -220,6 +224,7 @@ The `/mprfollowup` shortcut starts the same watcher manually at any time.
 ## Non-negotiables
 
 - No silent auth skip.
+- **Results reach the PR, pass or fail** — the debug path never terminates the run, and the walkthrough covers every run. A Stop gate holds the turn open while an acceptance run has no walkthrough on its PR, so a result that genuinely shouldn't be posted needs `echo "MUGGLE_WALKTHROUGH_SKIP: <reason>"` rather than silence.
 - **Never prompt for Electron launch approval** before execution — invoking this skill is the approval. Just run.
 - **Never diagnose a failed run from `execute`'s response stdout tail.** Always call `muggle-local-run-result-get` first; classify only from its structured fields and (when present) the artifacts it names. The execute tail is an excerpt and routinely truncates the failure cause.
 - Satisfy the prerequisite chain (Step 4a) before generating or replaying the target. Read it from `muggle-remote-test-case-ancestors-get` — never infer parents from `precondition` text. Generate any not-ready ancestor test-generation-only, root-first.

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

@@ -151,7 +151,7 @@ If **not authenticated**:
 
 A **project** is where all your imported use cases, test cases, and future test results are grouped on the Muggle AI dashboard.
 
-The per-repo project cache lives at `<cwd>/.muggle-ai/last-project.json` (via the `muggle-local-last-project-get` / `muggle-local-last-project-set` MCP tools). Look for `Muggle Test Last Project: id=… url=… name="…"` in session context.
+The per-repo project cache lives in `~/.muggle-ai/last-project.json`, in the entry keyed on `<cwd>` (via the `muggle-local-last-project-get` / `muggle-local-last-project-set` MCP tools). Look for `Muggle Test Last Project: id=… url=… name="…"` in session context.
 
 Gate `autoSelectProject` (per `preference-gates/README.md`). Cache: `Muggle Test Last Project` session line.
 - `always` + cache → use cached `projectId`, skip to Step 6. No cache → fall through to `ask`.

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

@@ -18,8 +18,8 @@ The skill runs in two phases because a dispatched agent has no channel back to t
 
 This skill touches the user's local machine — processes, ports, directories outside the current repo. Every action is explicit and confirmed.
 
-- **Folder names are public.** You may list directory names in a parent folder to discover sibling services.
-- **File contents are private until confirmed.** Never read files inside a directory the user hasn't explicitly identified as a service to start. Once confirmed, you may inspect only top-level project indicator files (`package.json`, `Makefile`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `docker-compose.yml`) to determine the start command.
+- **Reading is granted, never assumed.** [derive-service-graph](./steps/derive-service-graph.md) asks first: scan a folder the user names, to a depth they set, or skip the scan and take their list of paths and services instead. The granted scope is recorded with the recipe so later runs reuse the permission rather than re-asking; widening it needs a fresh ask.
+- **Outside the granted scope, names only.** You may list directory names to offer them as candidates, but never read inside one the user hasn't named. Once they name it, its top-level indicator files (`package.json`, `Makefile`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `docker-compose.yml`) are readable to determine the start command.
 - **Never traverse upward more than one level** from the current working directory to list folders.
 
 ## PID Tracking
@@ -48,7 +48,11 @@ All launched processes are tracked in `/tmp/muggle-test-prepare.json`:
 
 `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)).
 
-This file is **ephemeral runtime state**, not the saved recipe. The durable plan lives at `<repo>/.muggle-ai/prepare-plan.json` (or the parent-dir-keyed entry in `~/.muggle-ai/prepare-plans.json`) and is consulted in [reuse-plan](./steps/reuse-plan.md) before any other stage. The two files never merge. The `test-prepare-runner` agent writes this file during execution; the triage below and Cleanup read it.
+This file is **ephemeral runtime state**, not the saved recipe. The durable plan lives in `~/.muggle-ai/prepare-plans.json`, under the entry keyed on this stack, and is consulted in [reuse-plan](./steps/reuse-plan.md) before any other stage. The two files never merge. The `test-prepare-runner` agent writes this file during execution; the triage below and Cleanup read it.
+
+The prose companion to the plan is `~/.muggle-ai/e2e-instructions/<key>.md`, written by [e2e-instructions](./steps/e2e-instructions.md), holding startup order, manual steps, and local gotchas. The plan remains the single source of truth for each service's start command; the markdown never restates one.
+
+**Everything this skill saves is machine-local, user-level data and lives under the Muggle home directory — never inside the user's project.** A project directory is shared, versioned, and cloned onto machines set up differently; a local run recipe is none of those things. Both files are keyed on the same stack identity, so they stay in lockstep.
 
 **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"
@@ -64,26 +68,34 @@ Gates run per [`preference-gates/README.md`](../muggle-preferences/preference-ga
 | Preference | Gates |
 |------------|-------|
 | `autoRebase` | [rebase-check](./steps/rebase-check.md) — rebase onto `origin/<default>` before starting dev servers |
-| `reusePreparePlan` | [reuse-plan](./steps/reuse-plan.md) — reuse the saved prepare plan for this stack, or rediscover |
+| `reusePreparePlan` | [reuse-plan](./steps/reuse-plan.md) — reuse the saved prepare plan for this stack, or rediscover; also [e2e-instructions](./steps/e2e-instructions.md), which goes stale for the same reason |
 | `autoSelectLocalHost` | [check-running](./steps/check-running.md) — reuse the recorded dev-server URL silently, or confirm it each run |
 
 ## Workflow
 
-**Decide (in-session).** Run these stages in order; read each detail file when you reach it:
+**The skill learns once, then replays.** [replay-or-learn](./steps/replay-or-learn.md) decides which, and owns what each mode may do.
+
+A **replay** executes the saved recipe and asks nothing. A **learning run** works through the Decide stages below, then the execute phase, then a single gate — [confirm-recipe](./steps/confirm-recipe.md) — which is the only thing that persists anything.
 
-| # | Stage | Summary |
-|:--|:------|:--------|
-| 0 | [reuse-plan](./steps/reuse-plan.md) | Reuse saved prepare plan (gated); on reuse, skip straight to dispatch |
-| 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 |
+Decide stages, in order; read each detail file when you reach it:
 
-The Decide phase's output is the **resolved prepare plan**: `services[]` (name, dir, start command, expected port, `external` flag, approval granted), `testingScope`, `excludedServices[]`, the recorded dev-server URL, and resolved gate outcomes.
+| Stage | Summary |
+|:------|:--------|
+| [replay-or-learn](./steps/replay-or-learn.md) | Replay the saved recipe, or learn a new one |
+| [derive-service-graph](./steps/derive-service-graph.md) | Derive services from workspace manifests |
+| [rebase-check](./steps/rebase-check.md) | Rebase onto default branch |
+| [scope](./steps/scope.md) | Frontend / backend / full stack |
+| [viability-check](./steps/viability-check.md) | Exclude services that can't run locally |
+| [identify-services](./steps/identify-services.md) | Confirm the derived graph; fill the gaps |
+| [e2e-instructions](./steps/e2e-instructions.md) | Startup order, manual steps, local gotchas |
+
+The Decide phase's output is the **resolved prepare plan**: `services[]` (name, dir, start command, expected port, `external` flag, approval granted), `testingScope`, `excludedServices[]`, the recorded dev-server URL, the E2E run instructions, and resolved gate outcomes.
 
 **Execute (agent).** Dispatch the `test-prepare-runner` agent (subagent type `muggle:test-prepare-runner`; bare `test-prepare-runner` where the plugin namespace is absent), synchronously, passing the resolved plan; it returns `READY` / `DEGRADED` plus the readiness table. The agent's own definition lists its stage files; in a harness with no agent/subagent facility, run the execute-phase stages ([check-running](./steps/check-running.md) through [readiness-report](./steps/readiness-report.md)) inline instead.
 
-Relay the readiness table to the user or calling skill verbatim. A `needs-input:` line from the agent names an unresolved decision — resolve it here (asking the user if needed) and re-dispatch; the agent never asks.
+Relay the readiness table to the user or calling skill verbatim. A `needs-input:` line from the agent names an unresolved decision — resolve it here (asking the user if needed) and re-dispatch; the agent never asks. That path is also how a problem hit mid-preparation reaches the user when it can't be resolved autonomously, per [record-resolution](./steps/record-resolution.md).
+
+The agent also returns the problems it hit and what cleared them. On a learning run those feed [confirm-recipe](./steps/confirm-recipe.md); on a replay they are already in the recipe and are applied without asking.
 
 ## Cleanup
 
@@ -114,12 +126,13 @@ After a test run, the caller can re-invoke for cleanup or leave services running
 
 ## Guardrails
 
-- **Never invent or default a host/port** — the dev-server URL is a recorded value, not a guess. Resolve it from `<repo>/.muggle-ai/last-host.json` (the [`autoSelectLocalHost`](../muggle-preferences/preference-gates/autoSelectLocalHost.md) cache) before probing ports; a framework default like `:3000` is never a fallback. See [check-running](./steps/check-running.md).
+- **Never invent or default a host/port** — the dev-server URL is a recorded value, not a guess. Read it from the last-host cache via `muggle-local-last-host-get` (the [`autoSelectLocalHost`](../muggle-preferences/preference-gates/autoSelectLocalHost.md) cache) before probing ports; a framework default like `:3000` is never a fallback. The cache's own storage location belongs to that tool — don't restate it here. See [check-running](./steps/check-running.md).
 - **No silent auto-selection without a gate** — when no preference authorizes a silent choice (host, restart, kill), confirm with the user. A gate set to `always` is the only license to skip the question; absent that, ask.
 - **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** — approvals are granted in Decide and travel in the plan; the agent starts nothing outside it.
 - **Never read file contents outside confirmed directories** — folder names are discoverable; file contents require explicit user selection.
+- **Never write a credential into the E2E run instructions** — plaintext notes are not a secret store, and this is the file a user pastes when asking why their stack won't start. Record the env-var or secret name, never its value.
 - **Never leave orphan processes untracked** — every background PID goes into the tracking file.
 - **Never kill a process the user started independently** — `external: true` survives cleanup.
 - **Never assume start commands** — verify via indicator file; confirm with user.

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

@@ -4,7 +4,7 @@
 
 The dev-server URL the tests will hit is a **recorded value, not a guess** — resolve it before probing anything.
 
-1. Read the cached host with `muggle-local-last-host-get`. It reads `<cwd>/.muggle-ai/last-host.json`; a worktree usually has **no cache of its own**, so when the worktree returns nothing, pass the **main** working-tree root as `cwd` — `git rev-parse --git-common-dir`, then its parent directory.
+1. Read the cached host with `muggle-local-last-host-get`. It reads the entry keyed on `<cwd>` in `~/.muggle-ai/last-host.json`; a worktree usually has **no cache of its own**, so when the worktree returns nothing, pass the **main** working-tree root as `cwd` — `git rev-parse --git-common-dir`, then its parent directory.
 2. Apply the [`autoSelectLocalHost`](../../muggle-preferences/preference-gates/autoSelectLocalHost.md) gate (read its value from the `Muggle Test Preferences` session-context line; absent → `ask`):
    - `always` **and** a cache exists → use it silently: `Using saved local URL {lastHost}`.
    - otherwise (`ask` / `never`, or no cache) → **confirm before using any host.** Run the gate's Picker 1 with `{lastHost}` (cached URL, omitted when absent) and `{suggestedHost}` (a port you actually detect listening). Never auto-pick, and never fall back to a framework default like `:3000`; if nothing is cached or detected, ask the user to type the URL.

package/plugin/skills/muggle-test-prepare/steps/confirm-recipe.md

@@ -0,0 +1,56 @@
+# Confirm the recipe
+
+The one gate of a learning run. Everything the run discovered is held until here, so the user makes a single decision instead of approving facts one at a time.
+
+Needs a verified-ready environment — a recipe for a preparation that did not work is worth nothing.
+
+## Show what was done
+
+Summarise the actual run, not the plan that preceded it:
+
+```
+Prepared your environment. Here's what it took:
+
+  Services started, in order
+    1. api        pnpm --filter api dev        :8080
+    2. worker     pnpm --filter worker dev     —
+    3. ui         pnpm dev                     :3999
+
+  Manual steps
+    • pnpm db:migrate — run once before the api comes up
+
+  Problems hit, and what fixed them
+    • ui — HTTP 500 on /dashboard while api was still booting
+      → started api first and waited for its ready signal
+    • worker — exited immediately, missing .env.local
+      → copied .env.example, you filled in QUEUE_URL
+
+  Not running locally
+    • payment-gateway — needs production certificates
+
+Remember this as your prepare recipe, so future runs just do it?
+```
+
+`AskUserQuestion`:
+
+- `Remember it` — `Future E2E runs prepare this way without asking.`
+- `Don't remember` — `Prepare from scratch again next time.`
+
+## On accept
+
+Write both halves of the recipe together, so they cannot drift:
+
+- The machine-readable service graph to `~/.muggle-ai/prepare-plans.json`, keyed on the stack, per [readiness-report](./readiness-report.md).
+- The prose — startup order, manual steps, gotchas, and the recorded resolutions from [record-resolution](./record-resolution.md) — to `~/.muggle-ai/e2e-instructions/<key>.md`, per [e2e-instructions](./e2e-instructions.md).
+
+## On decline
+
+Write nothing. The next run learns again. Do not ask a second time in the same run, and do not record the refusal as a preference — the user is declining this recipe, not the idea of recipes.
+
+## Hard block
+
+The only thing that lets a replay deviate: **a failure the recipe's recorded resolutions do not cover, which autonomous attempts cannot clear.**
+
+Anything the recipe already handles is not a hard block, however loudly it fails. Neither is a transient that clears on retry. The bar is deliberately high, because every re-prompt undoes the learning.
+
+On a hard block: resolve it with the user, then offer to update the recipe with the new resolution — the same accept/decline, scoped to the one addition. Otherwise the recipe changes only when the user asks for it.

package/plugin/skills/muggle-test-prepare/steps/derive-service-graph.md

@@ -0,0 +1,51 @@
+# Derive the service graph
+
+Derive the service graph from what the workspace declares, so the interview only covers what a scan cannot know. Reading manifests beats interrogating the user about their own repo layout.
+
+Applies only to a [learning run](./replay-or-learn.md). A replay never scans.
+
+## Ask before reading anything
+
+Nothing is read until the user says where. `AskUserQuestion`:
+
+> "To work out your services, I can scan the code — or you can just tell me. Which?"
+
+- `Scan <cwd>` — `Read manifests here, 2 levels deep, to find services and their start commands.`
+- `Scan a different folder` — `Name the folder and how deep to look.`
+- `I'll list them` — `Give me the service paths yourself; I won't read anything you haven't named.`
+
+The default depth is **2 levels**, which reaches `packages/*` and `services/*` without walking a whole disk. The user may set it higher or lower when naming the folder.
+
+`I'll list them` skips the scan entirely: take the paths and service names from the user and continue to the interview with those as the graph. Read only the top-level indicator files of the paths they named, and only to determine the start command.
+
+Record the granted scope — folder and depth — with the recipe, so a later run reuses the same permission rather than asking again. Widening it needs a fresh ask.
+
+## Read, in this order
+
+Within the granted scope only:
+
+1. **Workspace manifests** — `pnpm-workspace.yaml`, the `workspaces` field of a root `package.json`, `turbo.json`, `lerna.json`, `nx.json`, `Cargo.toml` `[workspace]`, `go.work`. These name the members directly, so a monorepo needs no guessing.
+2. **Compose and process files** — `docker-compose.yml`, `Procfile`, `Makefile`, `Tiltfile`, `skaffold.yaml`. These carry service names, ports, and often the dependency order outright (`depends_on`).
+3. **Per-service manifests** for each member found — `package.json` scripts (`dev`, `start`, `serve`), `Cargo.toml`, `go.mod`, `pyproject.toml`. This is where the start command comes from.
+4. **Port declarations** — `.env.example`, `vite.config.*`, `next.config.*`, a `PORT` in the start script. Never a framework default: an undeclared port is unknown, not `:3000`.
+
+## Emit
+
+A proposed service graph — for each: name, directory, start command with its source, expected port with its source, and whether the scan believes it is required for the declared scope.
+
+Plus what the scan **could not** determine. That list is the interview's agenda; everything else is already settled.
+
+Show the user what was found before asking anything else. A scan they can see is a scan they can correct.
+
+## What a scan cannot know
+
+State these as unknowns rather than guessing, because each is a judgement about intent rather than a fact in a file:
+
+- Which services this user actually needs running for the tests they care about.
+- Which cannot run locally at all (a payment gateway needing production certificates).
+- Startup ordering that no `depends_on` declares but which the app requires anyway.
+- Anything that has to happen by hand before a service is usable.
+
+## Boundaries
+
+Read only inside the folder the user granted, to the depth they set. A directory outside that scope may have its name listed to offer it as a candidate; its contents stay unread until the user names it.

package/plugin/skills/muggle-test-prepare/steps/e2e-instructions.md

@@ -0,0 +1,111 @@
+# E2E run instructions
+
+Capture what `prepare-plan.json` cannot express: the order services must come up in, steps that aren't a single command, and the local gotchas that make a healthy stack look broken. Persisted under `~/.muggle-ai/e2e-instructions/` and reused on later runs.
+
+Needs the resolved service list from [identify-services](./identify-services.md): startup order and per-service gotchas are unanswerable until the service set is known.
+
+## Scope boundary
+
+`prepare-plan.json` owns the per-service start command. Never restate a command here; reference the plan. This file holds only what the plan has no field for:
+
+| Belongs here | Belongs in `prepare-plan.json` |
+|:-------------|:-------------------------------|
+| Order and dependencies between services | Each service's `name`, `dir`, `command`, `port` |
+| Steps that aren't one command (a migration to run first, a tunnel to open, a container to bring up by hand) | — |
+| Gotchas — slow first build, a port that isn't the framework default, a rate limit, a warning that is safe to ignore | — |
+
+## Resolve the saved file
+
+This is machine-local, user-level data. It lives under the Muggle home directory and never inside the user's project — a project directory is shared, versioned, and cloned by people whose machines are set up differently, and none of that is true of a local run recipe.
+
+One file per stack:
+
+```
+~/.muggle-ai/e2e-instructions/<key>.md
+```
+
+`<key>` is the absolute path of the working directory's parent — the same stack identity the global prepare plan keys its entries on — reduced to a filename-safe token by replacing every path separator, and any drive-letter colon, with `-`. Derive it from the resolved absolute path rather than assuming a separator character; they differ per platform.
+
+Missing → no saved instructions; run the capture below.
+
+## Gate `reusePreparePlan`
+
+Same gate as [reuse-plan](./reuse-plan.md) — this content goes stale for the same reason the service plan does, so one answer governs both. Only fires when a saved file was loaded.
+
+- `always` → reuse silently. Print `Reusing saved E2E run instructions`.
+- `never` → discard and run the capture.
+- `ask` → print the saved file, then Picker 1 from the gate contract. Reuse on `Reuse this plan`, capture on `Rediscover from scratch`.
+
+On the [reuse-plan](./reuse-plan.md) short-circuit path this stage is skipped along with the rest of the Decide phase; the saved file is loaded there and carried forward unchanged.
+
+## Capture
+
+Print the resolved service list first so the user answers against concrete names, then ask one `AskUserQuestion`, multi-select:
+
+> "Anything Muggle should know about running these locally?"
+
+- `Startup order matters` — `One service must be up before another, or something fails.`
+- `Manual steps` — `Something has to happen that isn't one of the start commands.`
+- `Known gotchas` — `Behaviour that looks like a failure but isn't, or a trap to avoid.`
+- `Nothing special` — `They start independently and just work.`
+
+`Nothing special` (or no selection) → write the sentinel from [Sentinel](#sentinel) and return. Do not re-ask on later runs; the sentinel is a recorded answer, not an empty file.
+
+Otherwise ask once more, free-text, naming only the selected categories. One turn — never a question per category.
+
+## Written format
+
+Fixed headings. Omit a section the user had nothing for; never emit an empty one.
+
+```markdown
+# E2E run instructions
+
+<!-- Managed by muggle-test-prepare. Hand-edits are preserved — re-run the skill to revise. -->
+
+**Updated:** 2026-08-04T12:00:00Z
+
+## Startup order
+
+api → worker → ui. The UI 500s on /dashboard when api isn't listening yet.
+
+## Manual steps
+
+Run `pnpm db:migrate` once after a fresh clone; the dev servers don't migrate on boot.
+
+## Local gotchas
+
+- First build after a clean install takes ~4 min. It is not hung.
+- UI is on :3999, not the Next.js default :3000.
+- Auth0 dev tenant rate-limits past ~20 logins/hour.
+
+## Resolutions
+
+Observed by prepare runs. Each is a signal that occurred and the fix that cleared it, applied automatically when the same signal recurs.
+
+- **ui** — HTTP 500 on `/dashboard` while api was still booting
+  → start api first and wait for its ready signal *(user-directed, 2026-08-04)*
+- **worker** — exited immediately, `.env.local` absent
+  → copy `.env.example`, user supplies `QUEUE_URL` *(user-directed, 2026-08-04)*
+```
+
+The sections above the Resolutions heading are the user's own words and are never rewritten by a run. Resolutions are what the machine observed, kept separate so the user can tell which is which and delete either with confidence.
+
+### Sentinel
+
+```markdown
+# E2E run instructions
+
+<!-- Managed by muggle-test-prepare. Hand-edits are preserved — re-run the skill to revise. -->
+
+**Updated:** 2026-08-04T12:00:00Z
+
+Nothing special — services start independently.
+```
+
+## Secrets
+
+Never write a credential value. A password, token, API key, or connection string with embedded credentials belongs in a secret store or an env file — not in plaintext notes. Living outside the project keeps this file out of version control, but it is still readable on disk and is exactly the kind of file a user pastes into an issue when asking why their stack won't come up.
+
+Record a **pointer** instead: the env-var name, or the name of the Muggle secret. `Set LOCAL_TEST_PASSWORD before running` is fine; the password is not.
+
+If the user's free text contains something that looks like a credential, drop it, write the pointer form, and say so in one line.

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

@@ -1,8 +1,10 @@
 # Identify required services & startup mode
 
-> Skipped when [reuse-plan](./reuse-plan.md) short-circuits — a reused plan supplies the service list and startup mode.
+> Skipped entirely on a replay run — the recipe supplies the service list and startup mode. See [replay-or-learn](./replay-or-learn.md).
 
-List folder names in the **parent directory** of the current working directory:
+**Start from the scan.** [derive-service-graph](./derive-service-graph.md) has already derived services, directories, start commands and ports from the workspace's own manifests. Present that graph for confirmation and ask only about what the scan listed as undetermined — which services this user actually needs, what can't run locally, ordering no manifest declares, and steps that happen by hand. Re-asking something the scan established wastes the scan.
+
+When the scan found nothing (no workspace manifests, an unfamiliar layout), fall back to listing folder names in the **parent directory** of the current working directory:
 
 ```bash
 ls -d "$(dirname "$PWD")"/*/ | xargs -I{} basename {}

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

@@ -27,7 +27,9 @@ Cleanup: say "stop services" or re-invoke this skill.
 
 ## Save the plan
 
-If this run came through discovery (i.e. Stage 0 [reuse-plan](./reuse-plan.md) did **not** short-circuit), persist the plan so the next run can skip the questions.
+Only on a learning run, and only once the user has accepted the gate in [confirm-recipe](./confirm-recipe.md). Nothing is persisted before that — a recipe the user didn't agree to is a recipe they'll have to undo, and a recipe for a preparation that failed is worse than none.
+
+A replay run writes nothing here; it already has the recipe.
 
 Build the JSON from the in-memory tracking file, dropping runtime fields:
 
@@ -41,10 +43,7 @@ jq '{
 }' /tmp/muggle-test-prepare.json
 ```
 
-Resolve the write location:
-
-- If `git rev-parse --show-toplevel` succeeds (call the result `$REPO`) → write `$REPO/.muggle-ai/prepare-plan.json`. Create `$REPO/.muggle-ai/` if missing.
-- Else → upsert the entry under key `$(dirname "$PWD")` (absolute) in `~/.muggle-ai/prepare-plans.json`. Create the file as `{}` if missing.
+Upsert it under the stack's key — the absolute path of the working directory's parent — in `~/.muggle-ai/prepare-plans.json`, creating the file as `{}` if missing. The plan is machine-local, user-level data: it never goes inside the user's project, and resolving it requires no version-control tool.
 
 Then print, once:
 
@@ -54,3 +53,11 @@ Then print, once:
 ```
 
 If this run short-circuited via [reuse-plan](./reuse-plan.md), don't rewrite — but **do** refresh `updated` and any `command` that was re-derived during validation. Skip the announcement on the refresh path.
+
+## Save the E2E run instructions
+
+The instructions arrive resolved in the dispatch prompt — captured while the user was present, in [e2e-instructions](./e2e-instructions.md). Write them verbatim, in that stage's format, to the location it resolves: `~/.muggle-ai/e2e-instructions/<key>.md`. Create the directory if missing. This file is machine-local and never goes inside the user's project.
+
+Nothing resolved in the plan → write nothing. An absent file is a stage that has not run yet; an empty one would read as "nothing to say" and suppress the question forever.
+
+Never write a credential value here — pointers only, per that stage's Secrets rule.

package/plugin/skills/muggle-test-prepare/steps/record-resolution.md

@@ -0,0 +1,32 @@
+# Recording a resolution
+
+How a problem hit during preparation becomes something the next run already knows. Referenced by [start-services](./start-services.md), [smoke-test](./smoke-test.md), and [fresh-install](./fresh-install.md) — every stage that can fail.
+
+## On a replay: consult before attempting
+
+When a step fails and the recipe holds a resolution for the same signal, apply that resolution first. A problem solved before is solved the same way again, silently. Re-deriving a fix the user already sat through is the failure this whole mechanism exists to prevent.
+
+Only when no recorded resolution matches, or the recorded one does not clear it, does the failure become a [hard block](./confirm-recipe.md#hard-block).
+
+## Resolving
+
+1. **Attempt autonomously** where the fix is known and safe — a clean restart, a fresh install, waiting out a slow boot that is still making progress.
+2. **Escalate** when it is not. During execution that means returning `needs-input:` naming the service and the concrete signal; the dispatching skill resolves it with the user and re-dispatches. Never guess at a fix that could destroy state.
+
+## What to record
+
+Per resolved problem, three things and nothing else:
+
+- The **signal** — the concrete observation, not a paraphrase. An HTTP status, a matched log line, an exit code.
+- The **service** it occurred on.
+- The **resolution** that actually cleared it, and whether it was autonomous or user-directed.
+
+A problem that was never cleared is not a resolution. Record it as an exclusion with its reason instead, so the next run does not retry something known to be hopeless.
+
+## What not to record
+
+- A transient that cleared on retry with no intervention. Nothing was learned; it was a blip.
+- A signal already recorded for the same service with the same resolution. Update the existing entry rather than appending a duplicate.
+- Anything containing a credential. Record the pointer form per [e2e-instructions](./e2e-instructions.md#secrets).
+
+Resolutions accumulate through the run and are written **only** when the user accepts the gate in [confirm-recipe](./confirm-recipe.md). Nothing is persisted mid-run.

package/plugin/skills/muggle-test-prepare/steps/replay-or-learn.md

@@ -0,0 +1,20 @@
+# Replay or learn
+
+One decision, made before anything else: does a prepare recipe already exist for this stack?
+
+Resolve the recipe location per [confirm-recipe](./confirm-recipe.md).
+
+- **Recipe exists** → **replay run**. Skip straight to the execute phase and run it. No scan, no interview, no questions. The whole point of having learned is not to ask again.
+- **No recipe** → **learning run**. Run the Decide stages in order, then the single gate at the end.
+
+A recipe the user declined to save is the same as no recipe: the next run learns again. Declining is not a permanent no, it just means nothing was written.
+
+## What a replay is allowed to do
+
+Execute the recorded steps, in the recorded order, using the recorded commands. When a step fails, consult the recipe's recorded resolutions **first** — a problem solved before is solved the same way again, without asking.
+
+Only a [hard block](./confirm-recipe.md#hard-block) permits a replay to deviate or prompt.
+
+## Reuse gate
+
+`reusePreparePlan` still governs whether a found recipe is used at all. `never` forces a learning run even when a recipe exists — the escape hatch for a stack that has been re-architected.

package/plugin/skills/muggle-test-prepare/steps/reuse-plan.md

@@ -1,17 +1,20 @@
-# Stage 0 — reuse saved plan (or fall through)
+# Resolving the saved plan
 
-A previously saved **prepare plan** is the durable recipe for this stack. Distinct from the ephemeral `/tmp/muggle-test-prepare.json` tracker — that file holds live PIDs/logs and is rebuilt every run.
+How [replay-or-learn](./replay-or-learn.md) finds the machine-readable half of the recipe. A previously saved **prepare plan** is the durable recipe for this stack, paired with the prose half in `~/.muggle-ai/e2e-instructions/<key>.md`. Distinct from the ephemeral `/tmp/muggle-test-prepare.json` tracker — that file holds live PIDs/logs and is rebuilt every run.
+
+Finding a plan means this is a **replay run**: execute it, ask nothing. Finding none means a **learning run**.
 
 ## Resolve
 
 In order; first hit wins.
 
-1. **Project plan.** If `git rev-parse --show-toplevel` succeeds (call the result `$REPO`) and `$REPO/.muggle-ai/prepare-plan.json` exists → load it.
-2. **Global plan.** Else if `~/.muggle-ai/prepare-plans.json` exists, read the entry keyed by `$(dirname "$PWD")` (absolute path). If present → load that entry's value.
-3. **No plan found** → exit this step; the workflow continues at [rebase-check](./rebase-check.md).
+1. **Saved plan.** If `~/.muggle-ai/prepare-plans.json` exists, read the entry keyed on this stack — the absolute path of the working directory's parent. If present → load that entry's value. The plan is machine-local and is never read from, or written to, the user's project.
+2. **No plan found** → exit this step; the workflow continues at [rebase-check](./rebase-check.md).
 
 A loaded plan is a JSON object with `version`, `updated`, `testing_scope`, `excluded_services`, `services`. Reject and treat as "no plan" if `version != 1` or `services` is empty.
 
+Load the prose companion per [e2e-instructions](./e2e-instructions.md) — `~/.muggle-ai/e2e-instructions/<key>.md`, keyed on the same stack identity as the global plan entry. It is independent of the plan: a missing companion is not a missing plan, and vice versa.
+
 ## Gate `reusePreparePlan`
 
 Per [`muggle-preferences/preference-gates/README.md`](../../muggle-preferences/preference-gates/README.md). Read the current value from the `Muggle Test Preferences` session-context line; absent → `ask`.
@@ -37,7 +40,7 @@ Per [`muggle-preferences/preference-gates/README.md`](../../muggle-preferences/p
    - The indicator file that produced `command` still exists in `dir` (e.g. `package.json` for an `npm`/`node` command; see the indicator table in [start-commands](./start-commands.md)) → keep. Else re-derive **just that one entry** by running the indicator-detection from [start-commands](./start-commands.md) against `dir`, and replace its `command`. Log `"Re-derived <name>: <old> → <new>"`.
 2. **All entries dropped** → discard the plan; continue at [rebase-check](./rebase-check.md). Otherwise proceed with surviving + re-derived entries.
 3. **Hydrate** `/tmp/muggle-test-prepare.json` with the surviving entries (no PIDs yet, `testing_scope` from the plan, `excluded_services` from the plan).
-4. **Short-circuit** to [check-running](./check-running.md). The skipped stages are [scope](./scope.md), [viability-check](./viability-check.md), [identify-services](./identify-services.md), [start-commands](./start-commands.md) — the reused plan supplies their answers. The remaining stages run normally: [env-file](./env-file.md), [fresh-install](./fresh-install.md), [start-services](./start-services.md) (only for entries not already listening), [smoke-test](./smoke-test.md), [readiness-report](./readiness-report.md).
+4. **Short-circuit** to [check-running](./check-running.md). The skipped stages are [scope](./scope.md), [viability-check](./viability-check.md), [identify-services](./identify-services.md), [start-commands](./start-commands.md), [e2e-instructions](./e2e-instructions.md) — the reused plan and its companion supply their answers. Carry the loaded instructions forward unchanged; the user is not re-asked. When the companion is absent, run [e2e-instructions](./e2e-instructions.md) once to capture it, then continue the short-circuit. The remaining stages run normally: [env-file](./env-file.md), [fresh-install](./fresh-install.md), [start-services](./start-services.md) (only for entries not already listening), [smoke-test](./smoke-test.md), [readiness-report](./readiness-report.md).
 
 ## Rediscover path
 

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

@@ -12,7 +12,9 @@ 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`:
+**Consult the recipe first.** When a recorded resolution matches this signal on this service, apply it without asking, per [record-resolution](./record-resolution.md). The user already answered this question once.
+
+Otherwise 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?"
 
@@ -23,4 +25,6 @@ On failure, show the concrete signal (HTTP code, sniff hit, or log line) and `As
 
 Loop per service until pass or skip. Cap at **3 iterations** — then force a manual-intervention pause.
 
+Whatever cleared the failure is a resolution: capture the signal, the service, and the fix per [record-resolution](./record-resolution.md), so the next run applies it silently instead of asking again. A service skipped instead of fixed is recorded as an exclusion with its reason, not as a resolution.
+
 For `external: true`, only Options 3 and 4 apply.