@muggleai/works 5.0.4 → 5.1.0

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

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

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

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

package/dist/plugin/scripts/ensure-electron-app.sh

@@ -104,7 +104,7 @@ if [ -f "$prefs_global_file" ]; then
       const defaults = {
         autoLogin:'ask', autoSelectProject:'ask', autoSelectLocalHost:'ask',
         showElectronBrowser:'ask', openTestResultsAfterRun:'ask',
-        defaultExecutionMode:'ask', autoPublishLocalResults:'ask',
+        defaultExecutionMode:'ask',
         suggestRelatedUseCases:'ask', suggestRelatedTestCases:'ask', autoDetectChanges:'ask',
         postPRVisualWalkthrough:'ask', autoCreatePR:'ask',
         checkForUpdates:'ask', verboseOutput:'ask',

package/dist/plugin/scripts/guardrails.mjs

@@ -27,14 +27,16 @@ function markPrHandled(sessionId2, prUrl, dirOverride) {
 
 // src/guardrails/prOpened.ts
 var PR_URL = /https:\/\/github\.com\/[^/\s]+\/[^/\s]+\/pull\/\d+/;
+var MR_URL = /https?:\/\/[^/\s]+\/[^\s]+\/-\/merge_requests\/\d+/;
 var CREATE_CMD = /\bgh\s+pr\s+(create|ready)\b/;
+var MR_CREATE_CMD = /\bglab\s+mr\s+create\b|\bglab\s+mr\s+update\b.*--ready\b/;
 function detectPrOpened(input2) {
   if (input2.tool_name !== "Bash") return null;
   const cmd = input2.tool_input?.command ?? "";
-  if (!CREATE_CMD.test(cmd)) return null;
+  if (!CREATE_CMD.test(cmd) && !MR_CREATE_CMD.test(cmd)) return null;
   const out = `${input2.tool_response?.stdout ?? ""}
 ${input2.tool_response?.output ?? ""}`;
-  const m = out.match(PR_URL);
+  const m = out.match(PR_URL) ?? out.match(MR_URL);
   return m ? m[0] : null;
 }
 

package/dist/plugin/skills/_shared/dev-loop/publish.md

@@ -1,13 +1,9 @@
-# Dev Loop — Publish & Screenshots
+# Dev Loop — Cloud Refs & Screenshots
 
-## Publish
+## Cloud refs
 
-After every completed run — pass or fail — publish: failed runs still need cloud-hosted screenshots and per-step actions for the walkthrough, and the upload `status` tells the backend whether to promote the action script as the canonical replay script (pass → promote; fail → record only).
-
-`muggle-local-publish-test-script` with `runId` and `cloudTestCaseId`. Retain `testScriptId`, `actionScriptId`, `viewUrl`. Batch publishes in parallel.
-
-If publish rejects with `has no generated actionScript steps to publish` (a true zero-step run), fall back to `muggle-remote-local-run-upload` with whatever exists (`summaryStep`, `errorMessage`, empty `actionScript`); capture `actionScriptId` and `viewUrl` the same way.
+The studio publishes every completed run — pass or fail — to the cloud during execution. There is no publish step to run. The run result already carries the cloud identifiers: read `viewUrl`, `cloudTestScriptId`, and `cloudActionScriptId` from `muggle-local-run-result-get` for the run. (`cloudTestScriptId` is absent for a failed generation — the backend records the action script and `viewUrl` but no test script.)
 
 ## Screenshots
 
-Per published script, `muggle-remote-test-script-get` with the `testScriptId` from publish → per step `operation.screenshotUrl` and `operation.action`. Retain `{ stepIndex, action, screenshotUrl }`. Batch in parallel. These feed the `E2eReport` consumed by [`../../muggle-pr-visual-walkthrough/SKILL.md`](../../muggle-pr-visual-walkthrough/SKILL.md) — the dev loop does not post to the PR.
+Per run, `muggle-remote-test-script-get` with the `cloudTestScriptId` from the run result → per step `operation.screenshotUrl` and `operation.action`. Retain `{ stepIndex, action, screenshotUrl }`. Batch in parallel. These feed the `E2eReport` consumed by [`../../muggle-pr-visual-walkthrough/SKILL.md`](../../muggle-pr-visual-walkthrough/SKILL.md) — the dev loop does not post to the PR.

package/dist/plugin/skills/_shared/pr-followup-helpers/allow-list.md

@@ -2,7 +2,7 @@
 
 The address-reviews flow only acts on reviews submitted by users in the **allow-list** = (requested reviewers ∪ CODEOWNERS ∪ {PR author}) − bots. Re-resolve every invocation — never cache across cycles.
 
-The PR author is implicitly a valid reviewer: in single-account workflows, the human running the agent and the PR's author are the same identity, and the agent must honor their reviews. Self-loop is prevented at the watcher's filter layer rather than here: `POST /pulls/<n>/comments/<id>/replies` does create an implicit review under the loop user's identity, and the watcher drops it via the loop-echo clause in [`../github-cli-recipes/submitted-reviews.md`](../github-cli-recipes/submitted-reviews.md) — matched by the loop signature ([`loop-signature.md`](loop-signature.md)), so the author's *genuine* reviews and thread replies still get through. Including the PR author in this allow-list is therefore safe.
+The PR author is implicitly a valid reviewer: in single-account workflows, the human running the agent and the PR's author are the same identity, and the agent must honor their reviews. Self-loop is prevented at the watcher's filter layer rather than here: `POST /pulls/<n>/comments/<id>/replies` does create an implicit review under the loop user's identity, and the watcher drops it via the loop-echo clause in [`../vcs/github/submitted-reviews.md`](../vcs/github/submitted-reviews.md) — matched by the loop signature ([`loop-signature.md`](loop-signature.md)), so the author's *genuine* reviews and thread replies still get through. Including the PR author in this allow-list is therefore safe.
 
 ## Step 1: requested reviewers
 

package/dist/plugin/skills/_shared/pr-followup-helpers/echo-skip.md

@@ -5,6 +5,6 @@ When `/muggle-do` posts a threaded reply to a review comment, GitHub surfaces th
 Under the thread-state dispatch trigger this is **intrinsic** — there is no "advance past the echo" step to get wrong:
 
 - **Line-comment threads.** A thread is actionable only when its newest comment lacks the loop marker `<!-- muggle-do:bot -->` (see [`loop-signature.md`](loop-signature.md)). After the loop replies, the newest comment is the loop's own and carries the marker, so the thread drops out of the actionable set on its own.
-- **Body-only reviews.** A loop reply always carries a line comment, so it is never body-only; the body-only check (no line comments, `id > lastBodyReviewId` — see [`../github-cli-recipes/submitted-reviews.md`](../github-cli-recipes/submitted-reviews.md)) excludes echoes structurally.
+- **Body-only reviews.** A loop reply always carries a line comment, so it is never body-only; the body-only check (no line comments, `id > lastBodyReviewId` — see [`../vcs/github/submitted-reviews.md`](../vcs/github/submitted-reviews.md)) excludes echoes structurally.
 
 Classify by the marker, never by `author.login` — under a shared account the loop posts as the PR author, so the login cannot tell echo from human.

package/dist/plugin/skills/_shared/resolve-e2e-validation-context.md

@@ -53,4 +53,4 @@ Write to `state.md` under a `## Pre-flight answers` block:
 - `Auth status: <ok | re-authed | N/A>`
 - `Working tree: <path>` — the verified checkout the cycle runs against
 
-Missing any required field is a seeding bug: escalate with the session path and halt. Never silently skip E2E.
+Once the strategy is `local-e2e`, missing any of its required fields (`Local URL`, `Muggle Test project`) is a seeding bug — escalate with the session path and halt; don't silently downgrade a chosen `local-e2e` to a skip. But `unit-only` and `skip` are valid first-class strategies for a PR with no testable surface — they need none of those fields, and a session seeded with no block at all is itself a clean skip.

package/dist/plugin/skills/_shared/test-case-chain-readiness.md

@@ -19,8 +19,7 @@ Run once the target `testCaseId` is chosen and the local URL + services are conf
    - Not ready → **generate its script only (never replay):**
      1. `muggle-remote-test-case-get` for the ancestor.
      2. Determine `freshSession` for that ancestor from its own content — same rules as Step 6.
-     3. `muggle-local-execute-test-generation` with the ancestor test case, `localUrl`, `cwd`, and a long `timeoutMs` (see Step 6's timeout guidance). Do **not** call `muggle-local-execute-replay`.
-     4. `muggle-local-publish-test-script` (`runId`, `cloudTestCaseId` = ancestor) so the generated script is promoted as that ancestor's canonical replay script — it now reads as ready for any case downstream.
+     3. `muggle-local-execute-test-generation` with the ancestor test case, `localUrl`, `cwd`, and a long `timeoutMs` (see Step 6's timeout guidance). Do **not** call `muggle-local-execute-replay`. The studio publishes the generated run during execution, promoting its script as that ancestor's canonical replay script — it now reads as ready for any case downstream (confirm via `muggle-local-run-result-get` carrying a `cloudActionScriptId`).
 
 3. **All ancestors ready** → continue to Step 5 for the target test case.
 

package/dist/plugin/skills/_shared/vcs/CLAUDE.md

@@ -0,0 +1,9 @@
+# VCS provider recipes
+
+Provider-agnostic seam for the watcher and dev-cycle skills. A caller resolves one provider token via [`detect-vcs.md`](detect-vcs.md) — `github` (`gh`) or `gitlab` (`glab`) — then loads the matching provider's recipe for each agnostic step. The two recipe sets mirror each other call-for-call; callers branch on the token, never fork procedure.
+
+## Index
+
+- [`detect-vcs.md`](detect-vcs.md) — resolve `github` | `gitlab` from a URL argument or the origin remote.
+- [`github.md`](github.md) — `gh` / `git` recipe TOC; per-recipe files in [`github/`](github/).
+- [`gitlab.md`](gitlab.md) — `glab` / `git` recipe TOC; per-recipe files in [`gitlab/`](gitlab/).

package/dist/plugin/skills/_shared/vcs/detect-vcs.md

@@ -0,0 +1,28 @@
+# Detect VCS provider
+
+Resolve a single provider token — `github` or `gitlab` — before a caller picks its recipe set. GitHub uses `gh`; GitLab uses `glab`. Auth errors from either surface verbatim.
+
+## Resolution order
+
+1. **From a URL argument**, if one was passed:
+   - `github.com/<owner>/<repo>/pull/<n>` → `github`.
+   - `<host>/<group>/<project>/-/merge_requests/<iid>` → `gitlab`. The `/-/merge_requests/` segment is the tell, on any host.
+
+2. **From the repo**, when no URL — parse the origin remote:
+
+   ```bash
+   git remote get-url origin
+   ```
+
+   - Host `github.com` → `github`.
+   - Host `gitlab.com`, **or** any other host where `glab auth status` succeeds → `gitlab`.
+
+## GitLab wrinkles
+
+- **Nested namespaces.** The path between host and `/-/` can be `group/subgroup/project`, any depth. Do not assume two segments — split on `/-/`, the project path is everything before it.
+- **The `/-/` segment** separates the project path from the resource (`/-/merge_requests/<iid>`). GitHub has no equivalent; its `/pull/<n>` sits directly under `<owner>/<repo>`.
+- **Self-hosted hosts.** GitLab is not just `gitlab.com` — `git.acme.com`, `gitlab.internal`, etc. Resolve the host from the remote and confirm it against `glab`'s configured host (`GITLAB_HOST`, or `glab auth status`'s active host). A remote host that matches `glab`'s host → `gitlab`, even when unknown to this doc.
+
+## Output
+
+The bare token `github` or `gitlab` — nothing else.

package/{plugin/skills/_shared/github-cli-recipes → dist/plugin/skills/_shared/vcs/github}/unresolved-threads.md

@@ -28,7 +28,7 @@ query($owner: String!, $name: String!, $number: Int!) {
 }'
 ```
 
-Filter client-side to `isResolved == false`. Walk each thread's comments in `createdAt` order and classify by the loop marker (see [`../pr-followup-helpers/loop-signature.md`](../pr-followup-helpers/loop-signature.md)), not by `author.login` — the login is ambiguous under a shared account:
+Filter client-side to `isResolved == false`. Walk each thread's comments in `createdAt` order and classify by the loop marker (see [`../../pr-followup-helpers/loop-signature.md`](../../pr-followup-helpers/loop-signature.md)), not by `author.login` — the login is ambiguous under a shared account:
 
 - **Addressed, awaiting resolve** — the **newest** comment carries the loop marker `<!-- muggle-do:bot -->`. The loop has replied and nothing newer is waiting. → resolve-reminder.
 - **Unaddressed human comment** — the newest comment lacks the marker and is newer than the thread's newest loop-marked comment (or the thread has no loop comment yet). → actionable: the round should address it. The **watcher's dispatch trigger** additionally requires `isOutdated == false` — a thread whose anchored line has since changed is skipped, since re-surfacing a stale anchor risks answering a concern the change already mooted. The resolve-reminder stage ignores `isOutdated`.

package/{plugin/skills/_shared/github-cli-recipes → dist/plugin/skills/_shared/vcs/github}/verify-working-tree.md

@@ -14,4 +14,4 @@ Accept any remote URL form for `<owner>/<repo>` (with or without trailing `.git`
 - `git@github.com:<owner>/<repo>`
 - `ssh://git@github.com/<owner>/<repo>`
 
-Any mismatch → bootstrap aborts using the wrong-checkout template in [`../../muggle-pr-followup/output-templates/bootstrap.md`](../../muggle-pr-followup/output-templates/bootstrap.md).
+Any mismatch → bootstrap aborts using the wrong-checkout template in [`../../../muggle-pr-followup/output-templates/bootstrap.md`](../../../muggle-pr-followup/output-templates/bootstrap.md).

package/dist/plugin/skills/_shared/vcs/github.md

@@ -0,0 +1,21 @@
+# GitHub CLI Recipes
+
+Reusable `gh` / `git` snippets used by `muggle-pr-followup` (watcher + bootstrap) and `/muggle-do` (address-reviews + open-prs). Each recipe is one file — load only what you need.
+
+Skills assume a working `gh auth status`. Auth errors surface verbatim from `gh`.
+
+## Index
+
+| Recipe | Use case |
+| :----- | :------- |
+| [`pr-metadata`](github/pr-metadata.md) | Snapshot PR state, head SHA, branch, conflict + `behind_by` out-of-date detection — watcher + bootstrap. |
+| [`submitted-reviews`](github/submitted-reviews.md) | Fetch a review by id / watcher's body-only-review check. |
+| [`pr-checks`](github/pr-checks.md) | Check-run rollup for the head SHA — watcher's CI poll. |
+| [`line-comments-for-review`](github/line-comments-for-review.md) | Pull a review's line comments — `/muggle-do` per-comment routing. |
+| [`unresolved-threads`](github/unresolved-threads.md) | GraphQL unresolved-thread state — watcher's dispatch trigger + resolve-reminder. |
+| [`reply-line-comment`](github/reply-line-comment.md) | POST a threaded reply on a line comment. |
+| [`top-level-comment`](github/top-level-comment.md) | POST a top-level PR comment — resolve-reminder + overflow. |
+| [`push-to-branch`](github/push-to-branch.md) | Push + capture new SHA after address-reviews work. |
+| [`verify-working-tree`](github/verify-working-tree.md) | Three checks bootstrap runs before seeding state. |
+| [`pr-edit`](github/pr-edit.md) | Refresh title or body when address-reviews mode flips state. |
+| [`loop-user-identity`](github/loop-user-identity.md) | Resolve the GitHub login of the loop user. |

package/dist/plugin/skills/_shared/vcs/gitlab/loop-user-identity.md

@@ -0,0 +1,9 @@
+# Identify the loop user
+
+The GitLab identity that owns the authenticated `glab` token. Resolve-reminder thread classification and reply attribution need this.
+
+```bash
+glab api user --jq '.username'
+```
+
+Cache in `state.md` under `Loop user:`; re-resolve only when missing.

package/dist/plugin/skills/_shared/vcs/gitlab/mr-create.md

@@ -0,0 +1,11 @@
+# Open a merge request
+
+For `open-prs`. Push the branch first (see [`../github/push-to-branch.md`](../github/push-to-branch.md)), then open the MR.
+
+```bash
+glab mr create -R <group>/<project> \
+  --source-branch <branch> --target-branch <base> \
+  --title "<title>" --description "$(cat <file>)"
+```
+
+`glab` prints the created MR's URL on success — capture stdout and store the URL for handoff (the watcher seeds from it, the user gets the link).

package/dist/plugin/skills/_shared/vcs/gitlab/mr-discussions.md

@@ -0,0 +1,18 @@
+# MR discussions
+
+Incoming feedback for the watcher's poll and the address-reviews fetch. GitLab has **no review envelope** — there is no submitted-review object grouping a summary body with line comments. Feedback arrives as individual notes, each belonging to a discussion (a thread). This recipe is the `submitted-reviews` analogue.
+
+```bash
+glab api projects/:id/merge_requests/:iid/discussions --paginate
+```
+
+Each discussion has `id` and a `notes[]` array; each note has `id`, `author.username`, `body`, `created_at`, `system` (a `true` flag marks GitLab's own activity entries — skip them).
+
+Common filter:
+
+- `system == false` (skip "added 2 commits", "changed the description", etc.)
+- `author.username` in the resolved allow-list
+
+Cursor: track the highest note/discussion `id` seen in `last_seen`; a note whose `id` exceeds it is new this tick. (GitLab ids are monotonic, so id ordering is reliable where `created_at` ties.)
+
+Loop-echo skip: a note the loop itself posted carries the `<!-- muggle-do:bot -->` marker in its `body`. Classify by that marker per note, never by `author.username` alone — under a shared account the login is ambiguous. A marked note is the loop's own and must never re-trigger a cycle; an unmarked note from an allow-listed author is actionable.

package/dist/plugin/skills/_shared/vcs/gitlab/mr-edit.md

@@ -0,0 +1,8 @@
+# Refresh the MR title or description
+
+For `open-prs/update.md` when E2E state flips (passing↔failing) or validation strategy changes. GitLab calls the body the **description**.
+
+```bash
+glab mr update <iid> -R <group>/<project> --title "<new-title>"
+glab mr update <iid> -R <group>/<project> --description "$(cat <file>)"
+```

package/dist/plugin/skills/_shared/vcs/gitlab/mr-metadata.md

@@ -0,0 +1,22 @@
+# MR metadata snapshot
+
+Fetch the fields the watcher and bootstrap need.
+
+```bash
+glab mr view <iid> -R <group>/<project> -F json
+```
+
+- `state` is one of `opened`, `merged`, `closed`, `locked` (lowercase — unlike GitHub's uppercase).
+- `sha` is the current head SHA — store as `head_sha` in `prs.json`.
+- `source_branch` is the branch — must match the working tree's branch in bootstrap. `target_branch` is the base.
+- conflict comes from `detailed_merge_status`, not a `mergeable` + `mergeStateStatus` pair. The watcher's **conflict** signal is `detailed_merge_status == "broken_status"` or `"conflict"`. `"checking"`/`"unchecked"` means GitLab is still computing — treat as not-conflicting this tick.
+
+## Behind-by (out-of-date detection)
+
+`detailed_merge_status == "need_rebase"` reports a behind branch only when the project enforces "fast-forward merge"; otherwise it stays `mergeable` while behind. Detect out-of-date straight from commit ancestry instead — independent of merge-method config:
+
+```bash
+glab api projects/:id/repository/compare?from=<target_branch>&to=<head_sha> --jq '.commits | length'
+```
+
+GitLab's compare lists only the commits `to` is ahead by, so flip the direction: compare `from=<head_sha>&to=<target_branch>` and a non-empty `.commits` ⇒ the base has commits the head lacks ⇒ out of date. Empty ⇒ current with base.

package/dist/plugin/skills/_shared/vcs/gitlab/mr-note.md

@@ -0,0 +1,7 @@
+# Top-level MR note
+
+For the resolve-reminder stage and any non-threaded notice.
+
+```bash
+glab mr note <iid> -R <group>/<project> -m "<text>"
+```

package/dist/plugin/skills/_shared/vcs/gitlab/mr-pipeline.md

@@ -0,0 +1,27 @@
+# MR pipeline rollup
+
+Fetch the CI state for an MR's head — what the watcher polls to detect red CI. GitLab runs **one** pipeline of jobs per commit, not independent check-runs, so the rollup is over that pipeline's jobs.
+
+```bash
+glab ci status -R <group>/<project> -b <source_branch>
+```
+
+Or straight from the API for the latest pipeline and its jobs:
+
+```bash
+glab api projects/:id/merge_requests/:iid/pipelines --jq '.[0].id'
+glab api projects/:id/pipelines/<pipeline-id>/jobs --paginate
+```
+
+Each job:
+
+- `name` — the job's name (e.g. `lint`, `test`, `build`).
+- `status` — one of `success` / `failed` / `running` / `pending` / `created` / `canceled` / `skipped` / `manual`.
+
+Classify for the watcher:
+
+- **red** — any job `failed`. Candidate for fix-ci.
+- **pending** — no job `failed`, but any job `running` / `pending` / `created`. Pipeline hasn't settled → idle.
+- **green** — every job `success` / `skipped` / `manual` / `canceled`, or no jobs at all.
+
+The fix-ci dispatch carries the `name`s of the `failed` jobs.

package/dist/plugin/skills/_shared/vcs/gitlab/reply-discussion.md

@@ -0,0 +1,9 @@
+# Reply to a discussion (threaded)
+
+Used by `/muggle-do` per-comment inline replies. A threaded reply is a new note appended to an existing discussion.
+
+```bash
+glab api --method POST \
+  projects/:id/merge_requests/:iid/discussions/<discussion-id>/notes \
+  -f body="<reply-text>"
+```

package/dist/plugin/skills/_shared/vcs/gitlab/resolve-discussion.md

@@ -0,0 +1,10 @@
+# Resolve a discussion thread
+
+Mark a thread resolved once the loop's reply has addressed it — the resolve-reminder stage's action.
+
+```bash
+glab api --method PUT \
+  "projects/:id/merge_requests/:iid/discussions/<discussion-id>?resolved=true"
+```
+
+Resolves every resolvable note in the thread at once. Only resolvable (diff/line) threads accept this; a non-resolvable discussion returns an error.

package/dist/plugin/skills/_shared/vcs/gitlab/unresolved-discussions.md

@@ -0,0 +1,18 @@
+# Unresolved discussions
+
+For the watcher's dispatch trigger and the resolve-reminder stage. REST exposes resolution directly — no GraphQL needed, unlike GitHub.
+
+```bash
+glab api projects/:id/merge_requests/:iid/discussions --paginate \
+  --jq '[.[] | select(.notes[0].resolvable == true) | select(any(.notes[]; .resolved == false))]'
+```
+
+A discussion is resolvable when its notes carry `resolvable == true` (diff/line threads are; the MR description and system notes are not). A thread is **unresolved** when any of its notes has `resolved == false`.
+
+Walk each unresolved thread's `notes[]` in `created_at` order and classify by the loop marker (see [`../../pr-followup-helpers/loop-signature.md`](../../pr-followup-helpers/loop-signature.md)), not by `author.username` — the login is ambiguous under a shared account:
+
+- **Addressed, awaiting resolve** — the **newest** note carries `<!-- muggle-do:bot -->`. The loop has replied and nothing newer waits. → resolve-reminder.
+- **Unaddressed human comment** — the newest note lacks the marker and is newer than the thread's newest loop-marked note (or the thread has none yet). → actionable: the round should address it.
+- **Not addressed** — indeterminate (e.g. no notes).
+
+Each thread carries its `id` (the `discussion_id`) — the watcher collects this from an actionable thread to build its dispatch list and to target the resolve call later.

package/dist/plugin/skills/_shared/vcs/gitlab.md

@@ -0,0 +1,24 @@
+# GitLab CLI Recipes
+
+Reusable `glab` / `git` snippets used by `muggle-pr-followup` (watcher + bootstrap) and `/muggle-do` (address-reviews + open-prs), mirroring the `gh` set for GitLab merge requests. Each recipe is one file — load only what you need.
+
+Skills assume a working `glab auth status`. Auth errors surface verbatim from `glab`.
+
+The project ref `:id` is `<group>/<project>` — URL-encode it for `glab api` (`mygroup/myproj` → `mygroup%2Fmyproj`). `:iid` is the MR's per-project internal id (the `!123` number), not the global id.
+
+## Index
+
+| Recipe | Use case |
+| :----- | :------- |
+| [`mr-metadata`](gitlab/mr-metadata.md) | Snapshot MR state, head SHA, branch, conflict + out-of-date detection — watcher + bootstrap. |
+| [`mr-pipeline`](gitlab/mr-pipeline.md) | Pipeline-job rollup for the head SHA — watcher's CI poll. |
+| [`mr-discussions`](gitlab/mr-discussions.md) | Fetch incoming notes/discussions — watcher's feedback poll. |
+| [`unresolved-discussions`](gitlab/unresolved-discussions.md) | Unresolved-discussion state — watcher's dispatch trigger + resolve-reminder. |
+| [`reply-discussion`](gitlab/reply-discussion.md) | POST a threaded reply on a discussion. |
+| [`mr-note`](gitlab/mr-note.md) | POST a top-level MR note — resolve-reminder + overflow. |
+| [`resolve-discussion`](gitlab/resolve-discussion.md) | Mark a discussion thread resolved. |
+| [`mr-edit`](gitlab/mr-edit.md) | Refresh title or description when address-reviews mode flips state. |
+| [`mr-create`](gitlab/mr-create.md) | Open an MR + capture its URL for handoff. |
+| [`loop-user-identity`](gitlab/loop-user-identity.md) | Resolve the GitLab username of the loop user. |
+| [`push-to-branch`](github/push-to-branch.md) | Push + capture new SHA after address-reviews work (provider-agnostic). |
+| [`verify-working-tree`](github/verify-working-tree.md) | Three checks bootstrap runs before seeding state (provider-agnostic). |

package/dist/plugin/skills/do/address-reviews.md

@@ -33,17 +33,21 @@ Before assembling work, rebase onto the latest default branch so the cycle addre
 
 ### Step 1 — Assemble the work set
 
-Two sources, combined into one batch (dedupe by comment id):
+Resolve the provider per [`../_shared/vcs/detect-vcs.md`](../_shared/vcs/detect-vcs.md), then assemble.
+
+**`github`** — two sources, combined into one batch (dedupe by comment id):
 
 **(a) The dispatched reviews.** For each review id in the input:
 
-- Fetch reviews per [`../_shared/github-cli-recipes/submitted-reviews.md`](../_shared/github-cli-recipes/submitted-reviews.md) (no watermark; filter to the specific id).
-- Fetch its line comments per [`../_shared/github-cli-recipes/line-comments-for-review.md`](../_shared/github-cli-recipes/line-comments-for-review.md).
+- Fetch reviews per [`../_shared/vcs/github/submitted-reviews.md`](../_shared/vcs/github/submitted-reviews.md) (no watermark; filter to the specific id).
+- Fetch its line comments per [`../_shared/vcs/github/line-comments-for-review.md`](../_shared/vcs/github/line-comments-for-review.md).
 
-**(b) Unaddressed comments on every unresolved thread.** Fetch unresolved threads per [`../_shared/github-cli-recipes/unresolved-threads.md`](../_shared/github-cli-recipes/unresolved-threads.md). For each thread classified **unaddressed human comment** — newest comment lacks the loop marker `<!-- muggle-do:bot -->` ([`loop-signature.md`](../_shared/pr-followup-helpers/loop-signature.md)) and post-dates the loop's last marked reply — add it to the batch — unresolved thread state, not any review-id watermark, is the authority here. This is how a human thread follow-up (a marker-less reply) gets addressed. **Exclude** comments whose review id is in `last_seen.escalated_review_ids` — paused awaiting the user, not re-work.
+**(b) Unaddressed comments on every unresolved thread.** Fetch unresolved threads per [`../_shared/vcs/github/unresolved-threads.md`](../_shared/vcs/github/unresolved-threads.md). For each thread classified **unaddressed human comment** — newest comment lacks the loop marker `<!-- muggle-do:bot -->` ([`loop-signature.md`](../_shared/pr-followup-helpers/loop-signature.md)) and post-dates the loop's last marked reply — add it to the batch — unresolved thread state, not any review-id watermark, is the authority here. This is how a human thread follow-up (a marker-less reply) gets addressed. **Exclude** comments whose review id is in `last_seen.escalated_review_ids` — paused awaiting the user, not re-work.
 
 Group (a) and (b) into one combined batch.
 
+**`gitlab`** — single source (no review-id watermark; discussion state is the sole authority). Fetch unresolved discussions per [`../_shared/vcs/gitlab/unresolved-discussions.md`](../_shared/vcs/gitlab/unresolved-discussions.md) (drop to [`../_shared/vcs/gitlab/mr-discussions.md`](../_shared/vcs/gitlab/mr-discussions.md) for raw notes where classification needs them). The input ids are discussion ids; the batch is every discussion classified **unaddressed human comment** — newest note lacks the marker and post-dates the loop's last marked note. **Exclude** discussions whose id is in `last_seen.escalated_review_ids`. A discussion is the unit of work in place of GitHub's review + line-comment pair.
+
 ### Step 2 — Classify each review
 
 Apply the classify rule in [`../_shared/pr-followup-helpers/classify.md`](../_shared/pr-followup-helpers/classify.md). Two outcomes per review:
@@ -93,7 +97,7 @@ Invoke [`open-prs/update.md`](open-prs/update.md) (pass the PR URL + slug + exis
 
 #### 4f. Post per-comment inline replies
 
-Invoke [`per-comment-replies.md`](per-comment-replies.md) with the actionable reviews and the new SHA. One reply per comment, in its own thread, describing what was done for it.
+Invoke [`per-comment-replies.md`](per-comment-replies.md) with the actionable reviews (`gitlab`: discussions) and the new SHA. One reply per comment, in its own thread, describing what was done for it; on `gitlab` the same step also resolves each fully-addressed discussion.
 
 (The resolve-reminder runs once per round in Step 5.5 below — not only after a push — so a round that pushed nothing still nudges addressed-but-unresolved threads.)
 
@@ -109,7 +113,7 @@ Invoke [`resolve-reminder.md`](resolve-reminder.md) once, regardless of whether
 
 ### Step 6 — Respawn the watcher
 
-Refresh PR state per [`../_shared/github-cli-recipes/pr-metadata.md`](../_shared/github-cli-recipes/pr-metadata.md). If the PR is now merged or closed:
+Refresh PR state with the provider resolved in Step 1 — `github` per [`../_shared/vcs/github/pr-metadata.md`](../_shared/vcs/github/pr-metadata.md), `gitlab` per [`../_shared/vcs/gitlab/mr-metadata.md`](../_shared/vcs/gitlab/mr-metadata.md) (`state == merged`/`closed`, lowercase). If the PR is now merged or closed:
 
 1. Write `result.md` per [`../muggle-pr-followup/state-schemas.md`](../muggle-pr-followup/state-schemas.md#resultmd).
 2. Do **not** respawn the watcher.

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

@@ -27,7 +27,7 @@ For local runs, the tool boundaries are:
 | Scope | MCP tools |
 | :---- | :-------- |
 | Cloud (projects, cases, scripts, auth) | `muggle-remote-*` |
-| Local (Electron run, publish, results) | `muggle-local-*` |
+| Local (Electron run, results — the studio publishes during the run) | `muggle-local-*` |
 
 This keeps execution deterministic: local runs do not depend on cloud replay execution availability.
 
@@ -96,9 +96,9 @@ Based on the changed files and the requirements goal, determine which test cases
 - Test cases that cover areas potentially affected by the changes
 - When in doubt, include the test case (better to over-test than miss a regression)
 
-### Step 4: Run the dev loop, publish, gather screenshots
+### Step 4: Run the dev loop, gather screenshots
 
-For each relevant test case, run the shared loop in [`../_shared/dev-loop/run.md`](../_shared/dev-loop/run.md): `muggle-remote-test-script-list` by `testCaseId` to pick [replay vs regen](../_shared/dev-loop/run.md), [execute with `timeoutMs`](../_shared/dev-loop/timeouts.md), [fetch the result](../_shared/dev-loop/failures.md) and [interpret failures](../_shared/dev-loop/failures.md), [publish](../_shared/dev-loop/publish.md), and gather [per-step screenshots](../_shared/dev-loop/publish.md).
+For each relevant test case, run the shared loop in [`../_shared/dev-loop/run.md`](../_shared/dev-loop/run.md): `muggle-remote-test-script-list` by `testCaseId` to pick [replay vs regen](../_shared/dev-loop/run.md), [execute with `timeoutMs`](../_shared/dev-loop/timeouts.md), [fetch the result](../_shared/dev-loop/failures.md) and [interpret failures](../_shared/dev-loop/failures.md), then read the studio-published [cloud refs and per-step screenshots](../_shared/dev-loop/publish.md) off the run result.
 
 Inputs to the loop: `mode` from the script-exists check, `localUrl`/project from Step 1.7, `cwd` = the working tree recorded in `state.md`.
 
@@ -161,5 +161,5 @@ Failed runs use the same evidence + diagnosis assembly as the interactive debug
 - Replay/timeout/result discipline per [`../_shared/dev-loop/run.md`](../_shared/dev-loop/run.md) — never hand-build `actionScript`, always pass `timeoutMs`, read structured run-result fields.
 - No hiding failures: surface errors, exit codes, and artifact paths.
 - In `local-e2e` mode, every relevant test case must be executed — generate a new script if none exists (no skips).
-- Always publish after execution to ensure screenshots are cloud-accessible for PR comments.
+- The studio publishes every run during execution, so screenshots are cloud-accessible for PR comments — read the refs off the run result, never re-publish.
 - **Never drop a test case from the report because it "couldn't run cleanly."** A test that didn't reach its assertion is `inconclusive`, not absent. Dropping it produces misleading verdicts and pushes downstream PR-comment renderers to hand-write the comment — which is the failure mode this stage exists to prevent.

package/dist/plugin/skills/do/fix-ci.md

@@ -10,7 +10,7 @@ Resolve red CI on a PR's head — lint/format, typecheck, and failing unit tests
 
 ## Input
 
-`$ARGUMENTS` carries a `github.com/.../pull/<n>` URL, `slug=<slug>`, and the failing check names (no review ids). Parse all three.
+`$ARGUMENTS` carries a PR/MR URL (`github.com/.../pull/<n>` or `<host>/<group>/<project>/-/merge_requests/<iid>`), `slug=<slug>`, and the failing check names (no review ids). Parse all three. The names are GitHub check-runs or — when the URL resolves `gitlab` per [`../_shared/vcs/detect-vcs.md`](../_shared/vcs/detect-vcs.md) — the failed pipeline-job names the watcher read off [`../_shared/vcs/gitlab/mr-pipeline.md`](../_shared/vcs/gitlab/mr-pipeline.md); the fix cycle below is identical for either.
 
 ## Inputs from disk
 

package/dist/plugin/skills/do/input-routing.md

@@ -1,10 +1,10 @@
 # Input routing
 
-How `/muggle-do` resolves `$ARGUMENTS` to a mode. Modes 1–4 are programmatic — dispatched by the watcher — so never ask on those. Inspect in order:
+How `/muggle-do` resolves `$ARGUMENTS` to a mode. Modes 1–4 are programmatic — dispatched by the watcher — so never ask on those. A change-URL in modes 1–3 is either a GitHub PR (`github.com/.../pull/<n>`) or a GitLab MR (`<host>/.../-/merge_requests/<iid>`); provider is resolved via [`../_shared/vcs/detect-vcs.md`](../_shared/vcs/detect-vcs.md). Inspect in order:
 
-1. **Address-reviews** — a `github.com/.../pull/<n>` URL **and** one or more review ids (integers ≥ 100000000) → [`address-reviews.md`](address-reviews.md).
-2. **Fix-CI** — a `github.com/.../pull/<n>` URL **and** a `fix ci` / `fix-ci` directive with failing check names (no review ids) → [`fix-ci.md`](fix-ci.md).
-3. **Rebase** — a `github.com/.../pull/<n>` URL **and** a `rebase` directive (or legacy `resolve conflicts` / `resolve-conflicts`; no review ids, no check names) → [`resolve-conflicts.md`](resolve-conflicts.md). Rebases the branch onto its base whether it's merely behind or actually conflicting.
+1. **Address-reviews** — a PR/MR URL **and** an address-reviews directive carrying review/discussion ids → [`address-reviews.md`](address-reviews.md). On GitHub these ids are integers ≥ 100000000; that magnitude is GitHub-specific lore, **not** a portable test. Under GitLab, tell this apart from other directives by the directive keyword plus the presence of discussion ids, never by id size.
+2. **Fix-CI** — a PR/MR URL **and** a `fix ci` / `fix-ci` directive with failing check names (no review/discussion ids) → [`fix-ci.md`](fix-ci.md).
+3. **Rebase** — a PR/MR URL **and** a `rebase` directive (or legacy `resolve conflicts` / `resolve-conflicts`; no review/discussion ids, no check names) → [`resolve-conflicts.md`](resolve-conflicts.md). Rebases the branch onto its base whether it's merely behind or actually conflicting.
 4. **Post-merge cleanup** — a `cleanup` token and `slug=<slug>` (no PR URL, no review ids), optionally `state=<merged|closed>` (default `merged`) → [`cleanup.md`](cleanup.md).
 5. **Empty / `help` / `menu` / `?`** → menu + session selector.
 6. **Task automation** (perform an action on a website) → `muggle:muggle-browser-task`.

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

@@ -1,6 +1,6 @@
 # Open PR — forward mode
 
-Forward pipeline's Stage 7. Invoked by `/muggle-do` after stages 1–6 of a fresh feature. Creates the PR via `gh pr create`, seeds session state, dispatches the first watcher.
+Forward pipeline's Stage 7. Invoked by `/muggle-do` after stages 1–6 of a fresh feature. Opens the change — a PR on GitHub (`gh pr create`) or an MR on GitLab (`glab mr create`), provider resolved in Step 4 — then seeds session state and dispatches the first watcher.
 
 ## Turn preamble
 
@@ -30,11 +30,13 @@ Forward pipeline's Stage 7. Invoked by `/muggle-do` after stages 1–6 of a fres
    - `## Acceptance Criteria` — bulleted; omit if empty.
    - `## Changes` — summary of what changed in this repo.
    - `## Validation` — one line: link to E2E report, `unit-only`, or `skip — <reason>`.
-   - **If an E2E report exists,** invoke [`../../muggle-pr-visual-walkthrough/SKILL.md`](../../muggle-pr-visual-walkthrough/SKILL.md) Mode B to render the walkthrough block. Embed the returned `body` verbatim. If no report, skip this block entirely.
+   - **Walkthrough block** — only when an E2E report exists. Fire [`postPRVisualWalkthrough`](../../muggle-preferences/preference-gates/postPRVisualWalkthrough.md); on skip, omit this block. Otherwise invoke [`../../muggle-pr-visual-walkthrough/SKILL.md`](../../muggle-pr-visual-walkthrough/SKILL.md) Mode B and embed the returned `body` verbatim. No report → skip the block.
 
-4. **Create:** `gh pr create --title "..." --body "..." --head <branch>`. Capture the PR URL and number.
+4. **Create:** resolve the provider per [`../../_shared/vcs/detect-vcs.md`](../../_shared/vcs/detect-vcs.md).
+   - `github` → `gh pr create --title "..." --body "..." --head <branch>`. Capture the PR URL and number.
+   - `gitlab` → open the change via [`../../_shared/vcs/gitlab/mr-create.md`](../../_shared/vcs/gitlab/mr-create.md): `glab mr create --source-branch <branch> --target-branch <base> --title "..." --description "..."`. Capture the MR URL and iid.
 
-5. **Overflow comment:** if the walkthrough skill returned a non-null `comment`, post it once per [`../../_shared/github-cli-recipes/top-level-comment.md`](../../_shared/github-cli-recipes/top-level-comment.md). Never post when `comment` is `null`.
+5. **Overflow comment:** if the walkthrough skill returned a non-null `comment`, post it once using the provider resolved in Step 4 — `github` per [`../../_shared/vcs/github/top-level-comment.md`](../../_shared/vcs/github/top-level-comment.md), `gitlab` per [`../../_shared/vcs/gitlab/mr-note.md`](../../_shared/vcs/gitlab/mr-note.md). Never post when `comment` is `null`.
 
 ## Stage 8 handoff
 

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

@@ -20,21 +20,23 @@ Does **not** create a PR, seed session state, or dispatch a watcher (`/muggle-do
 
 Skip `autoCreatePR` (it gates creation, not update). The PR's title is left intact unless state changed in Step 3.
 
-1. **Push:** per [`../../_shared/github-cli-recipes/push-to-branch.md`](../../_shared/github-cli-recipes/push-to-branch.md). Capture the new SHA.
+Resolve the provider once per [`../../_shared/vcs/detect-vcs.md`](../../_shared/vcs/detect-vcs.md). Wherever Steps 3–4 below edit title/description: `github` uses `gh pr edit` per [`../../_shared/vcs/github/pr-edit.md`](../../_shared/vcs/github/pr-edit.md); `gitlab` uses `glab mr update --title --description` per [`../../_shared/vcs/gitlab/mr-edit.md`](../../_shared/vcs/gitlab/mr-edit.md).
+
+1. **Push:** per [`../../_shared/vcs/github/push-to-branch.md`](../../_shared/vcs/github/push-to-branch.md). Capture the new SHA.
 
 2. **Append new SHA** to `last_seen.json[<key>].pushed_shas` (the resolve-reminder stage uses this to recognize threads addressed by the loop). Set `last_seen.last_pushed_sha` to the new SHA too.
 
 3. **Refresh title if state changed.** Compare the new state against the current PR title prefix:
-   - E2E now passing, current title has `[E2E FAILING]` → strip the prefix per [`../../_shared/github-cli-recipes/pr-edit.md`](../../_shared/github-cli-recipes/pr-edit.md).
+   - E2E now passing, current title has `[E2E FAILING]` → strip the prefix per [`../../_shared/vcs/github/pr-edit.md`](../../_shared/vcs/github/pr-edit.md).
    - E2E now failing, current title has no `[E2E FAILING]` → add the prefix.
    - Validation now ran (was unit-only/skip, now has E2E report) → strip `[UNVERIFIED]` or `[UNIT-ONLY]`.
    - Otherwise → no title change.
 
-4. **Refresh body when validation outcome changed** — only when the `## Validation` section's content differs from what's in the body. Use the `--body-file` form in [`../../_shared/github-cli-recipes/pr-edit.md`](../../_shared/github-cli-recipes/pr-edit.md). Preserve `## Goal` and `## Acceptance Criteria` verbatim.
+4. **Refresh body when validation outcome changed** — only when the `## Validation` section's content differs from what's in the body. Use the `--body-file` form in [`../../_shared/vcs/github/pr-edit.md`](../../_shared/vcs/github/pr-edit.md). Preserve `## Goal` and `## Acceptance Criteria` verbatim.
 
-5. **Visual walkthrough comment** — if an E2E report exists, invoke [`../../muggle-pr-visual-walkthrough/SKILL.md`](../../muggle-pr-visual-walkthrough/SKILL.md) Mode A. Always a fresh comment per cycle; do not edit prior walkthrough comments.
+5. **Visual walkthrough comment** — only when an E2E report exists. Fire [`postPRVisualWalkthrough`](../../muggle-preferences/preference-gates/postPRVisualWalkthrough.md) (PR number from `prs.json`); on skip, record `skipped (gate)` and continue. Otherwise invoke [`../../muggle-pr-visual-walkthrough/SKILL.md`](../../muggle-pr-visual-walkthrough/SKILL.md) Mode A — a fresh comment per cycle; do not edit prior walkthrough comments.
 
-6. **Overflow comment** — same rule as forward mode: post when the walkthrough skill returns non-null `comment`, via [`../../_shared/github-cli-recipes/top-level-comment.md`](../../_shared/github-cli-recipes/top-level-comment.md).
+6. **Overflow comment** — same rule as forward mode: post when the walkthrough skill returns non-null `comment`, via [`../../_shared/vcs/github/top-level-comment.md`](../../_shared/vcs/github/top-level-comment.md).
 
 ## Handoff
 
@@ -50,5 +52,5 @@ Return control to `/muggle-do`'s address-reviews orchestrator. The orchestrator
 **PR updated:** URL (new SHA: `<short-sha>`)
 **Title refreshed:** yes | no
 **Body refreshed:** yes | no
-**Walkthrough comment:** posted | skipped (no report)
+**Walkthrough comment:** posted | skipped (no report) | skipped (gate)
 **Overflow comment:** posted | skipped