@muggleai/works 4.9.2 → 4.10.1

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

@@ -0,0 +1,134 @@
+---
+name: muggle-do-task
+description: Run a browser automation task on a website using natural language. Finds or creates the Muggle Test project, use case, test case, and script, then executes locally via the electron app. Use when the user wants to perform an action on a website (post, fill a form, click through a flow) rather than implement a code change.
+---
+
+# Muggle Test Task Runner
+
+> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-do-task"`.
+
+Runs a browser automation task described in plain English. Finds or creates the necessary Muggle Test entities automatically, then executes locally with mutation-driven step prediction.
+
+## Step 1 — Parse the prompt
+
+From `$ARGUMENTS`, extract:
+
+- **`domain`** — the target website domain (e.g., `x.com`, `amazon.com`, `localhost:3000`). Normalize: strip `www.`, strip `https://`, lowercase. Result: bare domain with no scheme, no trailing slash.
+- **`useCaseName`** — the core action being performed, stripped of variable content (e.g., `"Publish a post"`, `"Add to cart"`, `"Submit a form"`).
+- **`mutations`** — variable parameters as a `string[]` (JSON array of strings). Each string is either:
+  - A plain-English instruction describing what varies this run (e.g., `"The post content should be 'Hello world'"`)
+  - A local file path for uploads (e.g., `"Attach the image at C:\\Users\\stan4\\Pictures\\photo.jpg"`)
+  
+  Examples: `["The post content should be 'Hello world'"]`, `["Attach the image at C:\\Users\\stan4\\photo.jpg", "Caption should be 'My photo'"]`
+- **`localUrl`** — the full URL to test against (e.g., `https://x.com`, `http://localhost:3000`). For external sites, use `https://<domain>`. For local dev servers, use the port the user's app is running on.
+
+If the prompt is ambiguous and you cannot confidently extract these, ask one clarifying question before proceeding.
+
+## Step 2 — Find or create Project
+
+Load and call `muggle-remote-project-list`. Find a project whose URL contains `domain` (case-insensitive substring match).
+
+**If found:** use it. Tell the user: `Found project: <name>`.
+
+**If not found:** call `muggle-remote-project-create` with:
+- `projectName`: `<domain>`
+- `description`: `E2E acceptance testing project for <domain>`
+- `url`: `https://<domain>`
+
+Tell the user: `Created project: <name>`.
+
+## Step 3 — Find or create Use Case
+
+Load and call `muggle-remote-use-case-list` filtered by `projectId`. Fuzzy-match against `useCaseName`:
+- Case-insensitive
+- Strip punctuation
+- Match if either string is a substring of the other
+
+If multiple candidates, pick the closest and tell the user which was selected.
+
+**If not found:** call `muggle-remote-use-case-create-from-prompts` with:
+- `projectId`: from Step 2
+- `instructions`: `["<original prompt>"]`
+
+Use the first result. Capture its `id` as `useCaseId`. If the result is empty or the call fails, stop and tell the user: "Could not create use case — try rephrasing the task description."
+
+Tell the user: `Created use case: <title>`.
+
+## Step 4 — Find or create Test Case
+
+Load and call `muggle-remote-test-case-list-by-use-case` with `useCaseId`. Filter for test cases where `status` equals `ACTIVE`.
+
+**If not found:** call `muggle-remote-test-case-create` with:
+- `projectId`: from Step 2
+- `useCaseId`: from Step 3
+- `title`: `<useCaseName>`
+- `description`: `Test case for: <original prompt>`
+- `goal`: `Successfully complete: <useCaseName>`
+- `expectedResult`: `The action completes without error`
+- `url`: `https://<domain>`
+
+Tell the user: `Created test case: <id>`.
+
+## Step 5 — Find active Test Script
+
+Load and call `muggle-remote-test-script-list` with:
+- `projectId`: from Step 2
+- `testCaseId`: from Step 4
+
+Tell the user which mutations will be applied: `Mutations: <mutations[]>` (or "no mutations" if empty).
+
+Filter for scripts where `status` equals `ACTIVE` or `PUBLISHED`. If all returned scripts have another status (`DRAFT`, `GENERATION_PENDING`, `FAILED`), treat as "no active script" and proceed to Phase 1.
+
+---
+
+### Phase 1 — No active script: generate locally
+
+1. Load and call `muggle-remote-test-case-get` with the test case ID from Step 4. This returns the full test case object needed by the local execution tool.
+
+2. Load and call `muggle-local-execute-test-generation` with:
+   - `testCase`: the full object from step 1 above
+   - `localUrl`: from Step 1
+   - `mutations`: the `mutations[]` array from Step 1 (omit if empty)
+
+3. Tell the user:
+> Script generation is running in the Muggle Test window. Once complete, run `/muggle-do "<original prompt>"` again to execute the task.
+
+Do not proceed further.
+
+---
+
+### Phase 2 — Active script found: replay with mutations
+
+## Step 6 — Fetch Action Script
+
+1. Load and call `muggle-remote-test-script-get` with the script ID from Step 5. Extract `actionScriptId`. If `actionScriptId` is missing or null, stop and tell the user: "The script record is incomplete — it may still be generating. Try again in a moment."
+
+2. Load and call `muggle-remote-action-script-get` with `actionScriptId`.
+
+Tell the user: `Executing task...`
+
+## Step 7 — Execute locally
+
+Load and call `muggle-local-execute-replay` with:
+- `testScript`: the full object from Step 6 (from `muggle-remote-test-script-get`)
+- `actionScript`: the content from Step 6 (from `muggle-remote-action-script-get`)
+- `localUrl`: from Step 1
+- `mutations`: the `mutations[]` array from Step 1 (omit if empty)
+
+Tell the user:
+> Running **[useCaseName]** on [domain]. Watch the Muggle Test window — it will execute the task with your parameters applied.
+
+## Step 8 — Route failures through the failure-mode handler
+
+If Phase 1 generation or Phase 2 replay returns `failed` or any non-passing terminal state, follow [`_shared/failure-mode-handling.md`](../_shared/failure-mode-handling.md):
+
+- **Phase 1 (generation) failure** → section C (buckets: `transient` / `infra` / `agent-course` / `product-uxux`).
+- **Phase 2 (replay) failure** → section B (buckets: `infra` / `stale-script` / `product-defect`).
+
+Steps:
+1. Read the run via `muggle-local-run-result-get` and extract signals per the heuristics in the shared doc.
+2. Emit `regen-failure-classified` or `replay-failure-classified` via `muggle-local-telemetry-event-emit` **before** asking the user.
+3. Present the recommended action via `AskUserQuestion` with the alternatives the shared doc lists for that bucket.
+4. After the user picks, emit the matching `*-resolved` event with `userAction`.
+
+If the user picks `muggle-feedback` from any bucket's options, invoke the `muggle-feedback` skill via the `Skill` tool with the `runId`. Skip silently on clean success.

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

@@ -0,0 +1,38 @@
+---
+name: muggle-feedback
+description: Capture feedback on a generated Muggle Test action script — either step-level or whole-script — and submit it so the system can analyze it and regenerate affected scripts. Use when the user has just run a Muggle Test (local or remote) and wants to flag what went wrong, when they paste a Muggle dashboard URL with a test script or run, or when they want to view or delete previously submitted feedback. Triggers on: '/muggle-feedback', 'give feedback on this run', 'the test was wrong', 'step N didn't work', 'the script clicked the wrong button', 'flag this run', 'the summary is wrong', 'show my feedback', 'list feedback', 'delete that feedback'. Skill auto-detects the run context from a recent local run, a remote run, or a Muggle dashboard URL in the prompt.
+---
+
+# Muggle Test Feedback
+
+> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-feedback"`.
+
+Capture user feedback on what a generated Muggle Test action script did wrong. The server uses each feedback row to find similar test cases via LLM and regenerate their scripts in the background.
+
+## Routing
+
+Pick the operation, then read its op file for the procedure.
+
+| Intent | Op file |
+|---|---|
+| "give feedback on this run" / "the test was wrong" / "step N didn't work" / a Muggle dashboard URL in the prompt / chained from another skill | [`ops/submit.md`](ops/submit.md) |
+| "show my feedback" / "list feedback for this project" / "what feedback have I filed" | [`ops/list.md`](ops/list.md) |
+| "delete that feedback" / "remove feedback for X" | [`ops/delete.md`](ops/delete.md) |
+
+If intent is ambiguous, use `AskUserQuestion` once with options **Submit / List / Delete** — never ask the user to type a clarification in plain text.
+
+## Constraints (all ops)
+
+- **Feedback attaches to a cloud action-script id.** A local run that has not yet been uploaded to the cloud has no such id. Submit must upload the run first if needed.
+- **Feedback target is one of two shapes:**
+  - **Whole script** — `target.targetType = "actionScript"`, `target.targetId = <actionScriptId>`.
+  - **One specific step** — `target.targetType = "step"`, `target.targetId = "<actionScriptId>:<stepIndex>"` where `stepIndex` is **0-based** on the wire even though steps are shown to the user 1-based.
+- **Project scope.** All ops scope to the user's last-used project (`muggle-local-last-project-get`). If unset, ask once and persist via `muggle-local-last-project-set` so subsequent ops in this session reuse it.
+- **`feedbackText` must be non-empty.** Re-prompt the user if they leave it blank.
+
+## Non-negotiables (all ops)
+
+- Use `AskUserQuestion` for every selection (project, test case, run, target type, confirm). Never ask the user to "reply with a number" in plain text.
+- Convert step numbers between 1-based (rendered to user) and 0-based (wire format) at the boundary. Never expose 0-based indices to the user.
+- One MCP submit/delete call per feedback piece — never batch into a single call.
+- Surface the `feedbackAnalysisWorkflowRuntimeId` returned by submit so the user knows regeneration is running. Do not poll it from this skill.

package/plugin/skills/muggle-feedback/ops/delete.md

@@ -0,0 +1,49 @@
+# Delete feedback
+
+Soft-delete a feedback entry. Always confirm with the user before deleting — this is a write the user cannot undo from this skill.
+
+## 1. Identify the feedback
+
+Three paths:
+
+- **Explicit id** — user named the feedback id (e.g. "delete feedback `abcd-1234-...`"). Use it.
+- **Recently shown id** — the user is referring to a row from a list rendered earlier in the conversation. Resolve from that context.
+- **No id given** — run [`list.md`](list.md) first to surface entries; offer "Delete one" as the next-action; the user picks.
+
+## 2. Show what will be deleted
+
+Print:
+
+```
+Feedback: <id>
+Target:   <Whole script | Step N>
+Test case: <title>
+Created:  <human-readable>
+Text:
+  <full feedbackText, indented>
+```
+
+## 3. Confirm
+
+`AskUserQuestion`:
+
+> "Delete this feedback?"
+> - **Delete** — proceed
+> - **Cancel** — abort
+
+If the user cancels, print "Cancelled — feedback kept." and stop.
+
+## 4. Soft-delete
+
+`muggle-remote-user-feedback-delete` with the feedback id.
+
+## 5. Report
+
+On success: `✓ Deleted feedback <id>.`
+
+On failure: print the error verbatim. If the error is "not found", inform the user the entry was likely already deleted and continue gracefully.
+
+## Non-negotiables
+
+- Never delete without an explicit confirm step, even if the user said "delete X" in their original prompt — the confirm shows what they're actually deleting.
+- One delete call per invocation. No bulk delete in v1.

package/plugin/skills/muggle-feedback/ops/list.md

@@ -0,0 +1,65 @@
+# List feedback
+
+Show feedback the user has filed. The user usually wants feedback on a specific test case (or test script, or use case) — not the whole project — so the skill picks a scope first.
+
+## 1. Scope to a project
+
+Read `muggle-local-last-project-get`. If set, use it.
+
+If unset: `muggle-remote-project-list` and pick via `AskUserQuestion` (top 5 by recency, plus "Show full list"). Persist with `muggle-local-last-project-set`.
+
+## 2. Pick a narrowing scope
+
+Ask once via `AskUserQuestion` — the list tool accepts at most one narrowing filter:
+
+> "What feedback do you want to see?"
+> - **A specific test case** (most common)
+> - **A specific test script**
+> - **A specific use case**
+> - **All in this project**
+
+If the user came from a chained skill or from a recent run, default to the matching narrowing scope and skip this question.
+
+## 3. Resolve the filter id
+
+- **Test case** → `muggle-remote-test-case-list` with `projectId`, `AskUserQuestion`. Pass picked id as `testCaseId`.
+- **Test script** → first pick a test case (as above), then `muggle-remote-test-script-list` with `testCaseId`, `AskUserQuestion`. Pass as `testScriptId`.
+- **Use case** → `muggle-remote-use-case-list` with `projectId`, `AskUserQuestion`. Pass as `useCaseId`.
+- **All in project** → no narrowing param.
+
+Use relevance-first filtering on each picker: top 3-5 most relevant to the user's stated goal, plus "Show full list".
+
+## 4. Fetch
+
+`muggle-remote-user-feedback-list` with `projectId` and at most one of `actionScriptId` / `testScriptId` / `testCaseId` / `useCaseId`.
+
+If the response has zero entries, print "No feedback yet for `<scope description>`." and offer `AskUserQuestion` with **Submit new feedback / Done**.
+
+## 5. Render
+
+Markdown table sorted by `createdAt` (newest first):
+
+| # | Target | Test case | Excerpt | Created | Id |
+|---|---|---|---|---|---|
+
+- **Target** — "Whole script" or "Step N" (convert wire 0-based index to 1-based for display).
+- **Test case** — when the scope is `testCaseId` or `testScriptId`, all rows share the same test case (use the title from the picker). When the scope is `useCaseId` or project-wide, resolve per row by fetching `muggle-remote-test-script-list` once for each unique `actionScriptId` (cache in-memory) — or skip and show "Test case: …" if there are >20 unique scripts.
+- **Excerpt** — first 80 chars of `feedbackText`, single line.
+- **Created** — human-readable, e.g. `2 days ago`.
+- **Id** — feedback id, truncated to first 8 chars in the table; full id shown in the detail view.
+
+## 6. Offer next action
+
+`AskUserQuestion`:
+
+> "What next?"
+> - **View detail** — pick an entry, print full `feedbackText`, full ids, target, dashboard link if available.
+> - **Delete one** — hand off to [`delete.md`](delete.md).
+> - **Submit new feedback** — hand off to [`submit.md`](submit.md).
+> - **Done**
+
+## Non-negotiables
+
+- One narrowing filter only — never set more than one of `actionScriptId` / `testScriptId` / `testCaseId` / `useCaseId` in the same call.
+- Convert wire 0-based step indices to 1-based when rendering to the user.
+- Don't fetch test-case names per row eagerly past ~20 unique action scripts — make it opt-in.

package/plugin/skills/muggle-feedback/ops/submit.md

@@ -0,0 +1,117 @@
+# Submit feedback
+
+Resolve the action script being commented on, render it for review, collect feedback against one or more steps and/or the whole script, then submit each piece as its own server-side row.
+
+## 1. Resolve the action script (the "anchor")
+
+Pick the first applicable path. Stop at the first that yields an `actionScriptId`.
+
+### 1a. Dashboard URL in user's prompt
+
+A Muggle dashboard URL looks like `https://app.muggle-ai.com/muggleTestV0/dashboard/projects/<projectId>/...`. Scan the user's recent message for any `https://app.muggle-ai.com/...` URL.
+
+- Extract any UUID-shaped path segments. If `/projects/<uuid>` is present, capture as `projectId`. If `/test-scripts/<uuid>` is present, capture as `testScriptId`.
+- If a `testScriptId` was captured: call `muggle-remote-test-script-get` to get the script and read `actionScriptId` off it. Done — proceed to step 2.
+- If only a `projectId` was captured: use it as the project for path 1c and continue to picker.
+- If parsing yields nothing actionable: fall through to 1b.
+
+### 1b. Recent local run (chained or just-finished)
+
+If this skill was invoked by another skill (`muggle-test`, `muggle-test-feature-local`) the caller MUST pass the just-finished `runId` as context. If you have a `runId`:
+
+1. `muggle-local-run-result-get` with the `runId`.
+2. The result includes the test case context. If the run was already published (`muggle-local-publish-test-script` was called), the resulting `testScriptId` gives you the cloud `actionScriptId` via `muggle-remote-test-script-get`.
+3. **If the run was NOT published**, upload it first via `muggle-remote-local-run-upload` (passing the `runId`'s test case context and `actionScript` payload). Use the returned cloud `actionScriptId`.
+
+If no `runId` was passed but the user is plausibly continuing from a recent test:
+
+1. `muggle-local-list-sessions` and pick sessions completed in the last 10 minutes for the current project.
+2. If exactly one fresh session exists, offer it as the default via `AskUserQuestion` ("Feedback on the run from <X> minutes ago?" with **Yes / Pick a different run**).
+3. If multiple, present the top 3 via `AskUserQuestion` (most recent first).
+4. Once picked, follow the publish-or-upload path above.
+
+If neither chained nor recent fits, fall through to 1c.
+
+### 1c. Picker (project → test case → run)
+
+1. **Project.** Read `muggle-local-last-project-get`. If set, use it. Else `muggle-remote-project-list` with `AskUserQuestion` (top 5 by recency, plus "Show full list"). Persist the pick with `muggle-local-last-project-set`.
+2. **Test case.** `muggle-remote-test-case-list` with `projectId`, then `AskUserQuestion`. Top 5 by recency plus "Show full list". Rank by relevance if the user mentioned anything specific.
+3. **Run / script.** `muggle-remote-test-script-list` with `testCaseId`. Show via `AskUserQuestion` with: name + status + updatedAt. Top 5 by recency.
+4. `muggle-remote-test-script-get` on the picked one → note `actionScriptId`.
+
+## 2. Render the script for review
+
+Always render before asking for feedback — the user must see the steps to reference them by index.
+
+`muggle-remote-action-script-get` with the resolved `actionScriptId`.
+
+Print:
+
+- **Header** — project name, test case title, script name, status, run url (if available). For remote, include the dashboard link.
+- **Steps** — numbered list, **1-based**, in order:
+  - `Step <n>: <action label> on <element text or id> — <briefExplanation>`
+  - If `screenshotPath` is present (local) or `screenshotUrl` (remote), append `[screenshot: <path>]` so the user can open it manually.
+- **Summary** — print `summary` from the action script if present, else "No summary recorded".
+
+## 3. Collect feedback (batch)
+
+Use `AskUserQuestion` to scope which targets:
+
+> "Where is the problem?"
+> - One specific step
+> - Multiple steps
+> - The whole script's outcome / summary
+> - Multiple steps **and** the whole outcome
+
+For each chosen target, prompt for the feedback paragraph in plain text. Keep prompts specific:
+
+- For a step: "What should step `<n>` have done instead?"
+- For the whole script: "What's wrong with the overall outcome?"
+
+Validate each paragraph is non-empty (re-prompt if blank). Build an in-memory list of feedback pieces:
+
+```
+[
+  { kind: "step", stepNumber: 3, text: "..." },
+  { kind: "step", stepNumber: 7, text: "..." },
+  { kind: "actionScript",            text: "..." },
+]
+```
+
+Before submitting, re-confirm the full set with the user via `AskUserQuestion`:
+
+> "Submit these <N> feedback entries?" — **Submit / Edit / Cancel**.
+
+## 4. Submit
+
+For each piece, call `muggle-remote-user-feedback-create` once. Map fields:
+
+| Piece kind | `target.targetType` | `target.targetId` |
+|---|---|---|
+| Step `n` (1-based) | `"step"` | `` `${actionScriptId}:${n - 1}` `` (convert to 0-based) |
+| Whole script | `"actionScript"` | `actionScriptId` |
+
+Always pass `projectId` and `feedbackText`. Capture each response — note `feedback.id` and `feedbackAnalysisWorkflowRuntimeId` (may be undefined).
+
+If a single create call fails, log the error, continue with the rest, and report the failure at the end. Do not abort the batch.
+
+## 5. Report
+
+Print one line per submitted feedback in this shape:
+
+```
+✓ feedback <id> — <target description> [analysis runtime: <id>]
+```
+
+End with a one-line note:
+
+> "Regeneration runs in the background. Re-run this test case later to use the updated script."
+
+If any pieces failed, list them under a `Failed:` header with the error.
+
+## Non-negotiables
+
+- Always render the script (step 2) before collecting feedback.
+- One create call per feedback piece — never concatenate paragraphs across targets.
+- Convert step numbers from 1-based (UI) to 0-based (wire) at submit time.
+- If the user came from a non-uploaded local run, do the upload silently before submit; do not ask for permission for the upload itself.

package/plugin/skills/muggle-pr-visual-walkthrough/SKILL.md

@@ -1,38 +1,34 @@
 ---
 name: muggle-pr-visual-walkthrough
-description: Renders and posts a visual walkthrough of Muggle AI E2E acceptance test results to a PR — per-test-case dashboard links, step-by-step screenshots, and pass/fail summary — using the `muggle build-pr-section` CLI for deterministic formatting with automatic fit-vs-overflow. Use at the end of any Muggle test run (local or remote) to give PR reviewers clickable visual evidence that user flows work. Triggers on 'post results to PR', 'attach walkthrough to PR', 'share E2E screenshots on the PR', 'add visual walkthrough to PR'.
+description: Renders and posts a visual walkthrough of Muggle AI E2E acceptance test results to a PR — per-test-case dashboard links, step-by-step screenshots, and pass/fail summary — using the `muggle build-pr-section` CLI for deterministic formatting with automatic fit-vs-overflow. Use at the end of any Muggle Test test run (local or remote) to give PR reviewers clickable visual evidence that user flows work. Triggers on 'post results to PR', 'attach walkthrough to PR', 'share E2E screenshots on the PR', 'add visual walkthrough to PR'.
 ---
 
-# Muggle PR Visual Walkthrough
+# Muggle Test PR Visual Walkthrough
+
+> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-pr-visual-walkthrough"`.
 
 Renders a visual walkthrough of Muggle AI E2E acceptance test results and posts it to a PR. Each test case is linked to its detail page on the Muggle AI dashboard, so PR reviewers can click through to see step-by-step screenshots and action scripts — not just a pass/fail flag.
 
-This is the **canonical PR-walkthrough workflow** shared across every Muggle entry point:
+This is the **canonical PR-walkthrough workflow** shared across every Muggle Test entry point:
 
 | Caller | Mode | When to invoke |
 | :--- | :--- | :--- |
-| `muggle-test` | **Mode A** (post to existing PR) | After publishing results, user opts in via `AskQuestion` |
-| `muggle-test-feature-local` | **Mode A** (post to existing PR) | After publishing the run, user opts in via `AskQuestion` |
+| `muggle-test` | **Mode A** (post to existing PR) | After publishing results, user opts in via `AskUserQuestion` |
+| `muggle-test-feature-local` | **Mode A** (post to existing PR) | After publishing the run, user opts in via `AskUserQuestion` |
 | `muggle-do` / `open-prs.md` | **Mode B** (render-only for embedding) | During PR creation — caller embeds `body` in `gh pr create` and posts `comment` as follow-up |
+| `muggle-test` Mode C / `acceptance-tester` agent | **Mode C** (embed in verdict comment) | Inside a open-PR sweep orchestrator — caller folds the rendered body into a single per-PR verdict comment instead of posting separately |
 
 Rendering is always done by `muggle build-pr-section`, a battle-tested CLI that handles deterministic markdown layout, per-step screenshots, and automatic fit-vs-overflow (oversized content spills into a follow-up comment). Never hand-write the walkthrough markdown.
 
 ## Preferences
 
-User preferences are available in the session context (injected at session start). Look for the line starting with `Muggle Preferences` — it contains key=value pairs like `autoLogin=ask showElectronBrowser=always ...`.
-
-If no preferences line is present, treat all preferences as `"ask"`.
+This skill is invoked by callers (`muggle-test`, `muggle-test-feature-local`, `muggle-do`) **after** the caller has already consulted the `postPRVisualWalkthrough` gate and decided to post. Therefore **the gating happens upstream, not in this skill** — by the time this skill runs, the user has already approved posting (either via the saved gate value or by explicit pick).
 
-When you reach a decision gated by a preference:
-- **`always`** → proceed without asking the user
-- **`never`** → skip without asking the user  
-- **`ask`** → ask the user, then offer: "Want me to remember this choice for future sessions?" If yes, call `muggle-local-preferences-set` with the key, their chosen value, and scope `global`.
+| Preference | Where it's gated | Decision it gates |
+|------------|------------------|-------------------|
+| `postPRVisualWalkthrough` | Caller skill (e.g. `muggle-test` Step 9, `muggle-test-feature-local` Step 10) | Post visual walkthrough to PR |
 
-This skill uses these preferences:
-
-| Preference | Decision it gates |
-|------------|------------------|
-| `postPRVisualWalkthrough` | Post visual walkthrough to PR |
+Per-key gate definitions live in `plugin/skills/muggle-preferences/preference-gates/`. This skill only renders and posts.
 
 ## Input contract: the `E2eReport` JSON
 
@@ -71,42 +67,48 @@ Every caller must build an `E2eReport` JSON object and have it in conversation c
       "failureStepIndex": 2,
       "error": "Element not found: Click checkout button",
       "artifactsDir": "/Users/.../~/.muggle-ai/sessions/<runId>"
+    },
+    {
+      "name": "Clear search input restores full list",
+      "description": "Verify clearing the search input restores all options.",
+      "useCaseName": "Filter Dropdowns",
+      "testCaseId": "<UUID>",
+      "runId": "<UUID>",
+      "viewUrl": "https://www.muggle-ai.com/...",
+      "status": "inconclusive",
+      "steps": [],
+      "reason": "No replayable script exists yet — needs first generation run."
     }
   ]
 }
 ```
 
-Required fields per test: `name`, `testCaseId`, `runId`, `viewUrl`, `status`, `steps[]` with `{stepIndex, action, screenshotUrl}`. Failed tests additionally require `failureStepIndex` and `error`.
+Required fields per test: `name`, `testCaseId`, `runId`, `viewUrl`, `status`, `steps[]` with `{stepIndex, action, screenshotUrl}`.
 
-**Optional but recommended** per test:
-- `description` — a one-line summary of what the test case verifies. Shown in the collapsible header for each test and helps reviewers understand the test without expanding it. Pull from the test case's `title`/`description` via `muggle-remote-test-case-get`.
-- `useCaseName` — the parent use case title. When present on any test, the overview list is grouped by use case; otherwise it is rendered as a flat list. Pull from `muggle-remote-use-case-get` using the test case's parent use-case id.
-- `testScriptId` and `artifactsDir` are also optional.
+- **Failed** tests additionally require `failureStepIndex` and `error`.
+- **Inconclusive** tests additionally require `reason` (one short sentence on why the result is neither pass nor fail). `steps[]` may be empty — that's fine. Inconclusive is for runs that couldn't be classified pass/fail (no replayable script, environment precondition unmet, infra error blocked execution, agent stalled before reaching the assertion). **Never silently drop these — always emit them as `inconclusive`.** The CLI counts them in the overview and renders an `⚠️` row with the dashboard link so reviewers can click through. If you find yourself wanting to skip a test or hand-write a comment because the schema "doesn't fit," that is the schema fitting — use `inconclusive`.
 
-If any required field is missing, stop and tell the caller exactly what's missing. Never fabricate data.
-
-## Step 1: Gather the `E2eReport`
+### Verdict
 
-How to assemble the JSON depends on which caller you are:
+The renderer computes a verdict from the tests and emits a `**Verdict:** ✅ PASS | ❌ FAIL | ⚠️ INCONCLUSIVE` line at the top of the overview. The policy is strict:
 
-### From `muggle-test` / `muggle-test-feature-local` (local mode)
+- Any failed test → **FAIL** (regardless of how many passed or are inconclusive).
+- No failures but any inconclusive → **INCONCLUSIVE**.
+- All passed → **PASS**.
+- Empty report → no verdict line.
 
-After `muggle-local-publish-test-script` returns `{testScriptId, viewUrl, ...}` for each run:
+You do not compute or render the verdict yourself — the CLI does. Never write a "Verdict: PASS" line into a hand-edited summary; it will conflict with the CLI's computed verdict.
 
-1. Call `muggle-remote-test-script-get` with `testScriptId` to fetch the published script.
-2. Extract `steps[]` — for each step, build `{stepIndex: <index>, action: operation.action, screenshotUrl: operation.screenshotUrl}`.
-3. Determine `status` from the local run result (`muggle-local-run-result-get`).
-4. For failures, read `failureStepIndex`, `error`, and `artifactsDir` from the run result.
-5. Assemble the `E2eReport` with `projectId` from the test run.
-6. Populate `description` (test case title/description) and `useCaseName` (parent use case title) on each report entry — optional but strongly recommended; they drive the grouped overview and the per-test collapsible headers. Prefer values already in your conversation context from earlier steps (e.g. a test case you just created or selected, or a use case you confirmed); only call `muggle-remote-test-case-get` / `muggle-remote-use-case-get` for anything you don't already have.
-
-### From `muggle-do` (`open-prs.md`)
+**Optional but recommended** per test:
+- `description` — a one-line summary of what the test case verifies. Shown in the collapsible header for each test and helps reviewers understand the test without expanding it. Pull from the test case's `title`/`description` via `muggle-remote-test-case-get`.
+- `useCaseName` — the parent use case title. When present on any test, the overview list is grouped by use case; otherwise it is rendered as a flat list. Pull from `muggle-remote-use-case-get` using the test case's parent use-case id.
+- `testScriptId` and `artifactsDir` are also optional.
 
-The `e2e-acceptance.md` stage already produces an `E2eReport` with the exact shape above — that is the report's native output format. Pass it through unchanged.
+If any required field is missing, stop and tell the caller exactly what's missing. Never fabricate data.
 
-### Direct invocation (user asked to post existing results)
+## Step 1: Assemble the `E2eReport`
 
-The caller must have already executed tests and published them. If the `E2eReport` is not in context, stop and tell the user to run `muggle-test` or `muggle-test-feature-local` first.
+Read `plugin/skills/muggle-pr-visual-walkthrough/e2e-report-assembly.md` for the full assembly guide.
 
 ## Step 2: Render via `muggle build-pr-section`
 
@@ -133,7 +135,7 @@ gh pr view --json number,url,title 2>/dev/null
 ```
 
 - **PR exists** → continue to 3A.2
-- **No PR exists** → use `AskQuestion`:
+- **No PR exists** → use `AskUserQuestion`:
   - "Create a new PR with the visual walkthrough in the body"
   - "Skip posting"
   - If the user chooses to create a new PR, switch to Mode B and return the rendered `body`/`comment` to the caller for embedding in `gh pr create`. Do not create the PR directly from this skill unless the caller has no better way to do it.
@@ -141,20 +143,16 @@ gh pr view --json number,url,title 2>/dev/null
 
 ### 3A.2: Post the body as a PR comment
 
+Extract the `body` field with `jq -r` (not `sed`) so JSON escape sequences are properly decoded, then pipe to `--body-file -`:
+
 ```bash
-gh pr comment <pr-number> --body "$(cat <<'EOF'
-<contents of body field from CLI output>
-EOF
-)"
+jq -r '.body' /tmp/muggle-pr-section.json | gh pr comment <pr-number> --body-file -
 ```
 
 ### 3A.3: Post the overflow comment only if the CLI emitted one
 
 ```bash
-gh pr comment <pr-number> --body "$(cat <<'EOF'
-<contents of comment field from CLI output>
-EOF
-)"
+jq -r '.comment' /tmp/muggle-pr-section.json | gh pr comment <pr-number> --body-file -
 ```
 
 **Skip this step entirely if `comment` is `null`** — do not post a placeholder. The CLI decides fit-vs-overflow; never post the overflow comment speculatively.
@@ -176,16 +174,35 @@ Instead of posting, **return** the CLI output to the caller's context so they ca
 3. **Post `comment` as a follow-up only if the CLI emitted one:**
 
    ```bash
-   gh pr comment <new-pr-number> --body "$(cat <<'EOF'
-   <contents of comment field>
-   EOF
-   )"
+   jq -r '.comment' /tmp/muggle-pr-section.json | gh pr comment <new-pr-number> --body-file -
    ```
 
    Skip if `comment` is `null`.
 
 In Mode B, this skill does not call `gh pr comment` or `gh pr create` itself — the caller owns PR creation because it also owns branch pushing, title building (including `[E2E FAILING]` prefix on failures), and multi-repo orchestration.
 
+## Step 3 — Mode C: Embed mode for open-PR sweep orchestrators
+
+Used when invoked as a sub-step of a open-PR sweep orchestrator (see `plugin/skills/muggle-test/SKILL.md` Mode C) rather than as a top-level user invocation. The orchestrator's `acceptance-tester` subagent (see `plugin/agents/acceptance-tester.md`) composes a **single per-PR verdict comment** and folds the walkthrough into it — posting separately would create 2–3 disparate comments per test cycle and clutter the PR.
+
+### 3C.1: Detect embed mode
+
+The caller passes `mode: "embed"` as a skill argument. Default behavior (no `mode` passed, or `mode: "post"`) is Mode A — unchanged.
+
+### 3C.2: Render but do not post
+
+Run `muggle build-pr-section` exactly as in Step 2. Then, **instead of calling `gh pr comment`**:
+
+1. **Return** the CLI output (`{ body, comment }`) to the caller as this skill's result.
+2. Do **not** find a PR, do **not** post a standalone comment, do **not** prompt the user.
+3. If `comment` is non-null (overflow case), return it alongside `body` — the orchestrator decides how to handle overflow (typically: inline `body` in the verdict comment, post `comment` as a follow-up).
+
+### 3C.3: Hand off
+
+The orchestrator (`acceptance-tester`) concatenates the returned `body` into its verdict comment template alongside the verdict summary, change-list, and any other sections it owns, then posts a single `gh pr comment` itself. This skill's job ends at returning the rendered markdown.
+
+In Mode C, the same fit-vs-overflow contract from Step 2 applies — never modify the CLI's output, never fabricate fields, never post anything. The caller owns posting.
+
 ## Tool Reference
 
 | Phase | Tool |
@@ -195,14 +212,15 @@ In Mode B, this skill does not call `gh pr comment` or `gh pr create` itself —
 | Find existing PR (Mode A) | `gh pr view` |
 | Post comment(s) (Mode A) | `gh pr comment` |
 | Create new PR (Mode B, caller handles) | `gh pr create` |
-| User confirmation (Mode A no-PR branch) | `AskQuestion` |
+| User confirmation (Mode A no-PR branch) | `AskUserQuestion` |
 
 ## Guardrails
 
-- **Never hand-write the walkthrough markdown** — always call `muggle build-pr-section`. The CLI is the single source of truth for formatting.
+- **Never hand-write the walkthrough markdown** — always call `muggle build-pr-section`. The CLI is the single source of truth for formatting. If a test outcome doesn't fit `passed | failed`, that's what `inconclusive` is for — never fall back to a hand-written summary, a custom table, a "Verdict: PASS" header, a `Tested on:`/`Project:` footer, or any other freeform text. The CLI already emits per-test-case dashboard links (no project-level link), uses `https://www.muggle-ai.com/...` URLs (never the test target's `localhost` URL), and computes the verdict — anything you would manually add is wrong by construction.
 - **Never modify the CLI's output** — post `body` and (if present) `comment` verbatim. Any reformatting defeats the fit-vs-overflow budget math.
 - **Never invent report fields** — if `projectId`, a per-test `viewUrl`, or per-step `screenshotUrl` is missing, stop and report what's missing. Do not fabricate URLs or fill in placeholders.
 - **Never post the overflow comment when `comment` is `null`** — the CLI decides fit-vs-overflow.
 - **Never create a PR without confirmation in Mode A** — if no PR exists, ask the user or switch to Mode B and hand back to the caller.
 - **Don't run tests** — this skill only renders and posts existing results. If the `E2eReport` is not in context, redirect the caller to `muggle-test`, `muggle-test-feature-local`, or `muggle-do`.
-- **Mode A vs Mode B is chosen by the caller, not the user** — `muggle-test` always uses Mode A; `muggle-do` always uses Mode B. Don't ask the user which mode to use.
+- **Mode is chosen by the caller, not the user** — `muggle-test` top-level uses Mode A; `muggle-do` uses Mode B; open-PR sweep orchestrators (`muggle-test` Mode C / `acceptance-tester`) pass `mode: "embed"` for Mode C. Don't ask the user which mode to use.
+- **Never post in Mode C** — when `mode: "embed"` is passed, return the rendered body to the caller and stop. The orchestrator owns the single verdict comment.