@muggleai/works 4.7.0 → 4.8.0

package/README.md

@@ -554,12 +554,7 @@ CI/CD and publishing
 | `verify-end-user-upgrade.yml` | Weekly + manual | Existing-user upgrade validation (cleanup + re-download + health checks) |
 | `publish-works-to-npm.yml` | Tag `v*` or manual  | Verify (including release checksums), audit, smoke-install, publish to npm |
 
-
-```bash
-git tag v<version> && git push --tags
-# publish-works-to-npm.yml handles the rest
-```
-
+**Publishing `@muggleai/works`:** use the repo-level skill **`plugin/skills/muggle-works-npm-release/SKILL.md`** (bump + `pnpm run sync:versions`, local verify, `chore(release)` PR, merge, then `workflow_dispatch` with an explicit `version`). Do not rely on tagging alone while `package.json` / marketplace manifests on `master` are still old — CI can publish a version that does not match the checked-in manifests. Tag `v*` push remains a valid workflow trigger when it matches the merged release commit.
 
 Release tag strategy
 

package/dist/{chunk-SMRMPHDD.js → chunk-2ZDLQAO4.js}

@@ -1,4 +1,4 @@
-import { __export, getLogger, getConfig, createChildLogger, buildElectronAppReleaseAssetUrl, getAuthService, hasApiKey, getElectronAppVersion, getElectronAppDir, getPlatformKey, isElectronAppInstalled, getElectronAppChecksums, getChecksumForPlatform, verifyFileChecksum, calculateFileChecksum, getQaTools, getLocalQaTools, performLogout, performLogin, toolRequiresAuth, getCallerCredentials, getDataDir, getBundledElectronAppVersion, getElectronAppVersionSource, getCredentialsFilePath, buildElectronAppChecksumsUrl, __require } from './chunk-HDEZDEM6.js';
+import { __export, getLogger, getConfig, createChildLogger, buildElectronAppReleaseAssetUrl, getAuthService, hasApiKey, getElectronAppVersion, getElectronAppDir, getPlatformKey, isElectronAppInstalled, getElectronAppChecksums, getChecksumForPlatform, verifyFileChecksum, calculateFileChecksum, getQaTools, getLocalQaTools, performLogout, performLogin, toolRequiresAuth, getCallerCredentials, getDataDir, getBundledElectronAppVersion, getElectronAppVersionSource, getCredentialsFilePath, buildElectronAppChecksumsUrl, __require } from './chunk-OUI734ME.js';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { v4 } from 'uuid';
@@ -686,7 +686,7 @@ async function resolveGsScreenshotUrls(report, opts) {
     if (gsUrls.length === 0) {
       return report;
     }
-    const mcps = await import('./src-TX2KXI26.js');
+    const mcps = await import('./src-2IDMKEJ5.js');
     const credentials = await mcps.getCallerCredentialsAsync();
     if (!credentials.bearerToken && !credentials.apiKey) {
       stderrWrite(

package/dist/{chunk-HDEZDEM6.js → chunk-OUI734ME.js}

@@ -2407,9 +2407,11 @@ ${executionResult.stderr}`;
           `Generated script does not contain a valid 'steps' array. File: ${generatedScriptPath}`
         );
       }
+      const generatedSummaryStep = generatedScript.summaryStep;
       storage.updateTestScript(localTestScript.id, {
         status: "generated",
-        actionScript: generatedSteps
+        actionScript: generatedSteps,
+        summaryStep: generatedSummaryStep
       });
       const artifactsDir = await moveResultsToArtifacts({
         runId,
@@ -5629,6 +5631,7 @@ var publishTestScriptTool = {
               uploadedAt
             },
             actionScript: testScript.actionScript,
+            summaryStep: testScript.summaryStep,
             status: runResult.status === "passed" ? "passed" : "failed",
             executionTimeMs: runResult.executionTimeMs,
             errorMessage: runResult.errorMessage

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { runCli } from './chunk-SMRMPHDD.js';
-import './chunk-HDEZDEM6.js';
+import { runCli } from './chunk-2ZDLQAO4.js';
+import './chunk-OUI734ME.js';
 
 // src/cli/main.ts
 runCli().catch((error) => {

package/dist/index.js

@@ -1,2 +1,2 @@
-export { src_exports as commands, createUnifiedMcpServer, server_exports as server } from './chunk-SMRMPHDD.js';
-export { createChildLogger, e2e_exports as e2e, getConfig, getLocalQaTools, getLogger, getQaTools, local_exports as localQa, mcp_exports as mcp, e2e_exports as qa, src_exports as shared } from './chunk-HDEZDEM6.js';
+export { src_exports as commands, createUnifiedMcpServer, server_exports as server } from './chunk-2ZDLQAO4.js';
+export { createChildLogger, e2e_exports as e2e, getConfig, getLocalQaTools, getLogger, getQaTools, local_exports as localQa, mcp_exports as mcp, e2e_exports as qa, src_exports as shared } from './chunk-OUI734ME.js';

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

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

package/dist/plugin/skills/muggle-works-npm-release/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: muggle-works-npm-release
+description: >-
+  Cut @muggleai/works release: AskQuestion (major/minor/patch), sync master, stop if
+  nothing ships, semver baseline + Electron from GitHub, confirm plan, bump
+  package.json + sync:versions, full local verify, chore(release) PR, merge via gh,
+  dispatch publish-works-to-npm.yml—no local npm publish.
+---
+
+# Muggle Works — npm release (single playbook)
+
+Repo: **`multiplex-ai/muggle-ai-works`**. Workflow: **`.github/workflows/publish-works-to-npm.yml`** (“Publish Works to npm”). **Never** run local **`npm publish`** (OIDC trusted publishing in CI).
+
+---
+
+## Phase 1 — Ask bump type (do this first)
+
+**Stop until the user answers.**
+
+**Prefer `AskQuestion`** with exactly these three options: **major**, **minor**, **patch** (fix). If the environment has no structured question tool, ask the same in plain text:
+
+> Is this release a **major**, **minor**, or **patch** (fix)?
+
+You may **recommend** a bump from commit subjects (e.g. `feat!` / breaking → major, `feat` → minor, `fix` / `chore` → patch) but **do not** choose for them. **Do not** edit files yet.
+
+---
+
+## Phase 2 — Sync, surface state, empty-release gate
+
+Run from **`muggle-ai-works`**:
+
+```bash
+git checkout master && git pull --ff-only && git fetch --tags
+```
+
+Show what is shipping:
+
+```bash
+node -e 'console.log("master package.json:", require("./package.json").version)'
+npm view @muggleai/works version 2>&1 | sed 's/^/npm latest: /'
+```
+
+**Commits since the last release commit** (stop if there is nothing to ship):
+
+```bash
+LAST_RELEASE_SHA=$(git log --grep='chore(release)' --format='%H' -1)
+git log --oneline "$LAST_RELEASE_SHA..HEAD"
+```
+
+- If the log is **empty**, tell the user there is **nothing to ship** and **stop** (no branch, no bump, no PR).
+- If non-empty, present commits as a short table (subject; PR number from title/body if present).
+
+---
+
+## Phase 3 — Version baseline, Electron, print summary, confirm
+
+### npm version (`nextNpmVersion`)
+
+1. **`npm view @muggleai/works version`** — last published on npm.
+2. Root **`package.json` → `version`** on current **`master`** checkout.
+3. **Baseline** = **semver-higher** of those two (never target below repo or npm).
+4. Apply the user’s **major / minor / patch** to that baseline → **`nextNpmVersion`** (semver-correct).
+
+### Electron (`muggleConfig`)
+
+1. Read **`package.json` → `muggleConfig.electronAppVersion`**.
+2. **Latest desktop on GitHub:**  
+   `https://api.github.com/repos/multiplex-ai/muggle-ai-works/releases?per_page=30`  
+   → newest **`tag_name`** matching **`electron-app-v*`** → strip prefix → **`latestElectronVersion`** (semver only).
+
+### Print (always)
+
+| Item | Value |
+| :--- | :---- |
+| Last **@muggleai/works** on npm | … |
+| **Baseline** for bump | … |
+| **`nextNpmVersion`** (to publish) | … |
+| Current **`electronAppVersion`** | … |
+| Latest **`electron-app-v…`** on GitHub | … |
+
+### Electron bump decision
+
+If **`latestElectronVersion`** ≠ current **`electronAppVersion`**, ask: **bump** Electron + all four **`muggleConfig.checksums`** to **`latestElectronVersion`**, or **keep** current.
+
+If bumping, checksums from:
+
+`https://github.com/multiplex-ai/muggle-ai-works/releases/download/electron-app-vVERSION/checksums.txt`
+
+Map zip artifacts → **`darwin-arm64`**, **`darwin-x64`**, **`win32-x64`**, **`linux-x64`** (same mapping rules as today).
+
+**Stop again:** user must **confirm** the full plan (**`nextNpmVersion`** + Electron choice). If they cancel, **do not** branch, merge, or dispatch CI.
+
+---
+
+## Phase 4 — After explicit confirmation only
+
+### 1. Branch and bump
+
+```bash
+git checkout -b "chore/release-<VERSION>"
+npm version "<VERSION>" --no-git-tag-version
+```
+
+Replace **`<VERSION>`** with **`nextNpmVersion`** (dots in the branch name are fine, e.g. `chore/release-4.8.0`).
+
+- If Electron bump agreed: set **`muggleConfig.electronAppVersion`** and all four **`muggleConfig.checksums`** in **`package.json`**.
+
+### 2. Propagate versions (do not hand-edit manifests)
+
+```bash
+pnpm run sync:versions
+```
+
+Never hand-edit **`.claude-plugin/marketplace.json`**, **`.cursor-plugin/marketplace.json`**, **`plugin/.claude-plugin/plugin.json`**, **`plugin/.cursor-plugin/plugin.json`**, or **`server.json`** — **`sync-versions`** (and **`build`**) owns them.
+
+If you changed Electron after the first sync, run **`pnpm run sync:versions`** again.
+
+### 3. Full local verify (before push)
+
+```bash
+pnpm run lint:check && pnpm run typecheck && pnpm test && pnpm run build && pnpm run verify:plugin && pnpm run verify:contracts && pnpm run verify:electron-release-checksums
+```
+
+- **`pnpm run build`** is required before **`verify:plugin`** — the verifier reads the **built** plugin under **`dist/plugin/`**, not source under **`plugin/`**.
+- If **anything** fails, **stop** and surface the error; **do not** push a broken release.
+
+### 4. Commit (**`chore(release)`**)
+
+Stage version-touched files (at minimum **`package.json`** plus whatever **`sync:versions`** changed — typically the marketplace/plugin **`server.json`** paths above).
+
+**Subject:** `chore(release): @muggleai/works <VERSION>`
+
+**Body:** one bullet per shipping PR / theme, note **Electron** bump or unchanged, and any coordinated follow-ups in sibling repos (e.g. teaching-service, UI). Use a **heredoc** for `git commit` so newlines are preserved.
+
+### 5. PR, merge, update local **`master`**
+
+```bash
+git push -u origin HEAD
+gh pr create --repo multiplex-ai/muggle-ai-works --base master --head <branch> \
+  --title "chore(release): @muggleai/works <VERSION>" \
+  --body "<PR body: version delta, bump rationale, shipping list, Electron status, manifests touched by sync:versions, short test plan checklist>"
+```
+
+**Merge:** when the human has approved the release in this session, run **`gh pr merge`** (squash is fine unless the repo prefers merge commits), then:
+
+```bash
+git checkout master && git pull --ff-only
+node -e 'console.log("master now:", require("./package.json").version)'
+```
+
+Confirm **`package.json`** on **`master`** matches **`nextNpmVersion`** before publishing.
+
+---
+
+## Phase 5 — Trigger publish (CI only)
+
+Prefer **explicit version** (not “auto bump”):
+
+```bash
+gh workflow run publish-works-to-npm.yml --repo multiplex-ai/muggle-ai-works --ref master \
+  --field "version=<VERSION>" --field "bump=patch"
+```
+
+The `bump=patch` field is a harmless placeholder when `version` is set; the workflow prefers the explicit `version` input.
+
+**Or** **`git tag "v<VERSION>"`** && **`git push origin "v<VERSION>"`** only if that tag **does not** already exist on the remote; if the tag exists, use **`workflow_dispatch`** with **`version`**.
+
+Watch the run and confirm jobs succeed:
+
+```bash
+gh run list --repo multiplex-ai/muggle-ai-works --workflow=publish-works-to-npm.yml --limit 1
+gh run watch <RUN_ID> --repo multiplex-ai/muggle-ai-works --exit-status
+```
+
+Verify the registry:
+
+```bash
+npm view @muggleai/works version
+```
+
+Give the user the **Actions run URL**. If npm lags, wait ~60s and retry.
+
+---
+
+## Rules
+
+- **No local `npm publish`.**
+- **Phase 1:** use **`AskQuestion`** for major / minor / patch when available (see Phase 1).
+- Phases 1–3: keep chat concise; Phase 4–5 can be terse status lines.
+- If the user cancels after Phase 3, **do not** merge or dispatch CI.
+- **Tag vs npm:** **`v*`** tags are for the **npm** package; **`electron-app-v*`** is separate — **`electronAppVersion`** can move independently of **`version`**.
+
+---
+
+## Notes (troubleshooting)
+
+- Workflow **`name:`** / filename is tied to npm **Trusted Publishing** — see the comment block at the top of **`publish-works-to-npm.yml`** if auth fails.
+- If commits land on **`master`** between opening the PR and merging, re-check **`git log`** vs the last **`chore(release)`** before merging; rebasing the release branch may be needed so **`master`** still matches what you intend to ship.

package/dist/release-manifest.json

@@ -1,7 +1,7 @@
 {
-  "release": "4.7.0",
-  "buildId": "run-18-1",
-  "commitSha": "2497ce3c3bd536d511c5f1a8d6621e691fd8f5e3",
-  "buildTime": "2026-04-11T06:11:05Z",
+  "release": "4.8.0",
+  "buildId": "run-19-1",
+  "commitSha": "970c730d39e45df17c9f9498ddcad410beafb8fb",
+  "buildTime": "2026-04-12T05:58:39Z",
   "serviceName": "muggle-ai-works-mcp"
 }

package/dist/{src-TX2KXI26.js → src-2IDMKEJ5.js}

@@ -1 +1 @@
-export { buildElectronAppChecksumsUrl, buildElectronAppReleaseAssetUrl, buildElectronAppReleaseTag, calculateFileChecksum, createApiKeyWithToken, createChildLogger, deleteApiKeyData, deleteCredentials, e2e_exports as e2e, getApiKey, getApiKeyFilePath, getAuthService, getBundledElectronAppVersion, getCallerCredentials, getCallerCredentialsAsync, getChecksumForPlatform, getConfig, getCredentialsFilePath, getDataDir, getDownloadBaseUrl, getElectronAppChecksums, getElectronAppDir, getElectronAppVersion, getElectronAppVersionSource, getLocalQaTools, getLogger, getPlatformKey, getQaTools, getValidApiKeyData, getValidCredentials, hasApiKey, isElectronAppInstalled, loadApiKeyData, loadCredentials, local_exports as localQa, mcp_exports as mcp, openBrowserUrl, performLogin, performLogout, pollDeviceCode, e2e_exports as qa, resetConfig, resetLogger, saveApiKey, saveApiKeyData, saveCredentials, startDeviceCodeFlow, toolRequiresAuth, verifyFileChecksum } from './chunk-HDEZDEM6.js';
+export { buildElectronAppChecksumsUrl, buildElectronAppReleaseAssetUrl, buildElectronAppReleaseTag, calculateFileChecksum, createApiKeyWithToken, createChildLogger, deleteApiKeyData, deleteCredentials, e2e_exports as e2e, getApiKey, getApiKeyFilePath, getAuthService, getBundledElectronAppVersion, getCallerCredentials, getCallerCredentialsAsync, getChecksumForPlatform, getConfig, getCredentialsFilePath, getDataDir, getDownloadBaseUrl, getElectronAppChecksums, getElectronAppDir, getElectronAppVersion, getElectronAppVersionSource, getLocalQaTools, getLogger, getPlatformKey, getQaTools, getValidApiKeyData, getValidCredentials, hasApiKey, isElectronAppInstalled, loadApiKeyData, loadCredentials, local_exports as localQa, mcp_exports as mcp, openBrowserUrl, performLogin, performLogout, pollDeviceCode, e2e_exports as qa, resetConfig, resetLogger, saveApiKey, saveApiKeyData, saveCredentials, startDeviceCodeFlow, toolRequiresAuth, verifyFileChecksum } from './chunk-OUI734ME.js';

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@muggleai/works",
     "mcpName": "io.github.multiplex-ai/muggle",
-    "version": "4.7.0",
+    "version": "4.8.0",
     "description": "Ship quality products with AI-powered E2E acceptance testing that validates your web app like a real user — from Claude Code and Cursor to PR.",
     "type": "module",
     "main": "dist/index.js",
@@ -41,14 +41,14 @@
         "test:watch": "vitest"
     },
     "muggleConfig": {
-        "electronAppVersion": "1.0.51",
+        "electronAppVersion": "1.0.55",
         "downloadBaseUrl": "https://github.com/multiplex-ai/muggle-ai-works/releases/download",
         "runtimeTargetDefault": "production",
         "checksums": {
-            "darwin-arm64": "6be5d2ff37541d9933e065f94f04348d7e4be63f01896b334a108a755a79f770",
-            "darwin-x64": "5c381e68829a330eecb8bd6edb9e5fba820e995acafe7fe78474fd7c43174f40",
-            "win32-x64": "2c101c467f75e8d60482aad16ad3c1a1e8edecac9ae58cdf7f1ad74cdf1141f7",
-            "linux-x64": "efeed3f2caf1cd301e8cc503a8ebae1f604ce73f7325c43202dee1c8a858a8a8"
+            "darwin-arm64": "b489ecb3273d8c15727ab80430468099a41e58417ef0f853de435f13aff0d903",
+            "darwin-x64": "38a34f45a23a9b53e3383c1f016363a294a28c3abdc454da35a34f1b03ddc191",
+            "win32-x64": "795495f9ddaab676e60f0140651c04f8d375adbadd3258a387bc7c82581c6d76",
+            "linux-x64": "2005101c8b23bce055c2d059e0a123f2b795779fd88df3658fdd1b74f4684599"
         }
     },
     "dependencies": {

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

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

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

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

package/plugin/skills/muggle-works-npm-release/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: muggle-works-npm-release
+description: >-
+  Cut @muggleai/works release: AskQuestion (major/minor/patch), sync master, stop if
+  nothing ships, semver baseline + Electron from GitHub, confirm plan, bump
+  package.json + sync:versions, full local verify, chore(release) PR, merge via gh,
+  dispatch publish-works-to-npm.yml—no local npm publish.
+---
+
+# Muggle Works — npm release (single playbook)
+
+Repo: **`multiplex-ai/muggle-ai-works`**. Workflow: **`.github/workflows/publish-works-to-npm.yml`** (“Publish Works to npm”). **Never** run local **`npm publish`** (OIDC trusted publishing in CI).
+
+---
+
+## Phase 1 — Ask bump type (do this first)
+
+**Stop until the user answers.**
+
+**Prefer `AskQuestion`** with exactly these three options: **major**, **minor**, **patch** (fix). If the environment has no structured question tool, ask the same in plain text:
+
+> Is this release a **major**, **minor**, or **patch** (fix)?
+
+You may **recommend** a bump from commit subjects (e.g. `feat!` / breaking → major, `feat` → minor, `fix` / `chore` → patch) but **do not** choose for them. **Do not** edit files yet.
+
+---
+
+## Phase 2 — Sync, surface state, empty-release gate
+
+Run from **`muggle-ai-works`**:
+
+```bash
+git checkout master && git pull --ff-only && git fetch --tags
+```
+
+Show what is shipping:
+
+```bash
+node -e 'console.log("master package.json:", require("./package.json").version)'
+npm view @muggleai/works version 2>&1 | sed 's/^/npm latest: /'
+```
+
+**Commits since the last release commit** (stop if there is nothing to ship):
+
+```bash
+LAST_RELEASE_SHA=$(git log --grep='chore(release)' --format='%H' -1)
+git log --oneline "$LAST_RELEASE_SHA..HEAD"
+```
+
+- If the log is **empty**, tell the user there is **nothing to ship** and **stop** (no branch, no bump, no PR).
+- If non-empty, present commits as a short table (subject; PR number from title/body if present).
+
+---
+
+## Phase 3 — Version baseline, Electron, print summary, confirm
+
+### npm version (`nextNpmVersion`)
+
+1. **`npm view @muggleai/works version`** — last published on npm.
+2. Root **`package.json` → `version`** on current **`master`** checkout.
+3. **Baseline** = **semver-higher** of those two (never target below repo or npm).
+4. Apply the user’s **major / minor / patch** to that baseline → **`nextNpmVersion`** (semver-correct).
+
+### Electron (`muggleConfig`)
+
+1. Read **`package.json` → `muggleConfig.electronAppVersion`**.
+2. **Latest desktop on GitHub:**  
+   `https://api.github.com/repos/multiplex-ai/muggle-ai-works/releases?per_page=30`  
+   → newest **`tag_name`** matching **`electron-app-v*`** → strip prefix → **`latestElectronVersion`** (semver only).
+
+### Print (always)
+
+| Item | Value |
+| :--- | :---- |
+| Last **@muggleai/works** on npm | … |
+| **Baseline** for bump | … |
+| **`nextNpmVersion`** (to publish) | … |
+| Current **`electronAppVersion`** | … |
+| Latest **`electron-app-v…`** on GitHub | … |
+
+### Electron bump decision
+
+If **`latestElectronVersion`** ≠ current **`electronAppVersion`**, ask: **bump** Electron + all four **`muggleConfig.checksums`** to **`latestElectronVersion`**, or **keep** current.
+
+If bumping, checksums from:
+
+`https://github.com/multiplex-ai/muggle-ai-works/releases/download/electron-app-vVERSION/checksums.txt`
+
+Map zip artifacts → **`darwin-arm64`**, **`darwin-x64`**, **`win32-x64`**, **`linux-x64`** (same mapping rules as today).
+
+**Stop again:** user must **confirm** the full plan (**`nextNpmVersion`** + Electron choice). If they cancel, **do not** branch, merge, or dispatch CI.
+
+---
+
+## Phase 4 — After explicit confirmation only
+
+### 1. Branch and bump
+
+```bash
+git checkout -b "chore/release-<VERSION>"
+npm version "<VERSION>" --no-git-tag-version
+```
+
+Replace **`<VERSION>`** with **`nextNpmVersion`** (dots in the branch name are fine, e.g. `chore/release-4.8.0`).
+
+- If Electron bump agreed: set **`muggleConfig.electronAppVersion`** and all four **`muggleConfig.checksums`** in **`package.json`**.
+
+### 2. Propagate versions (do not hand-edit manifests)
+
+```bash
+pnpm run sync:versions
+```
+
+Never hand-edit **`.claude-plugin/marketplace.json`**, **`.cursor-plugin/marketplace.json`**, **`plugin/.claude-plugin/plugin.json`**, **`plugin/.cursor-plugin/plugin.json`**, or **`server.json`** — **`sync-versions`** (and **`build`**) owns them.
+
+If you changed Electron after the first sync, run **`pnpm run sync:versions`** again.
+
+### 3. Full local verify (before push)
+
+```bash
+pnpm run lint:check && pnpm run typecheck && pnpm test && pnpm run build && pnpm run verify:plugin && pnpm run verify:contracts && pnpm run verify:electron-release-checksums
+```
+
+- **`pnpm run build`** is required before **`verify:plugin`** — the verifier reads the **built** plugin under **`dist/plugin/`**, not source under **`plugin/`**.
+- If **anything** fails, **stop** and surface the error; **do not** push a broken release.
+
+### 4. Commit (**`chore(release)`**)
+
+Stage version-touched files (at minimum **`package.json`** plus whatever **`sync:versions`** changed — typically the marketplace/plugin **`server.json`** paths above).
+
+**Subject:** `chore(release): @muggleai/works <VERSION>`
+
+**Body:** one bullet per shipping PR / theme, note **Electron** bump or unchanged, and any coordinated follow-ups in sibling repos (e.g. teaching-service, UI). Use a **heredoc** for `git commit` so newlines are preserved.
+
+### 5. PR, merge, update local **`master`**
+
+```bash
+git push -u origin HEAD
+gh pr create --repo multiplex-ai/muggle-ai-works --base master --head <branch> \
+  --title "chore(release): @muggleai/works <VERSION>" \
+  --body "<PR body: version delta, bump rationale, shipping list, Electron status, manifests touched by sync:versions, short test plan checklist>"
+```
+
+**Merge:** when the human has approved the release in this session, run **`gh pr merge`** (squash is fine unless the repo prefers merge commits), then:
+
+```bash
+git checkout master && git pull --ff-only
+node -e 'console.log("master now:", require("./package.json").version)'
+```
+
+Confirm **`package.json`** on **`master`** matches **`nextNpmVersion`** before publishing.
+
+---
+
+## Phase 5 — Trigger publish (CI only)
+
+Prefer **explicit version** (not “auto bump”):
+
+```bash
+gh workflow run publish-works-to-npm.yml --repo multiplex-ai/muggle-ai-works --ref master \
+  --field "version=<VERSION>" --field "bump=patch"
+```
+
+The `bump=patch` field is a harmless placeholder when `version` is set; the workflow prefers the explicit `version` input.
+
+**Or** **`git tag "v<VERSION>"`** && **`git push origin "v<VERSION>"`** only if that tag **does not** already exist on the remote; if the tag exists, use **`workflow_dispatch`** with **`version`**.
+
+Watch the run and confirm jobs succeed:
+
+```bash
+gh run list --repo multiplex-ai/muggle-ai-works --workflow=publish-works-to-npm.yml --limit 1
+gh run watch <RUN_ID> --repo multiplex-ai/muggle-ai-works --exit-status
+```
+
+Verify the registry:
+
+```bash
+npm view @muggleai/works version
+```
+
+Give the user the **Actions run URL**. If npm lags, wait ~60s and retry.
+
+---
+
+## Rules
+
+- **No local `npm publish`.**
+- **Phase 1:** use **`AskQuestion`** for major / minor / patch when available (see Phase 1).
+- Phases 1–3: keep chat concise; Phase 4–5 can be terse status lines.
+- If the user cancels after Phase 3, **do not** merge or dispatch CI.
+- **Tag vs npm:** **`v*`** tags are for the **npm** package; **`electron-app-v*`** is separate — **`electronAppVersion`** can move independently of **`version`**.
+
+---
+
+## Notes (troubleshooting)
+
+- Workflow **`name:`** / filename is tied to npm **Trusted Publishing** — see the comment block at the top of **`publish-works-to-npm.yml`** if auth fails.
+- If commits land on **`master`** between opening the PR and merging, re-check **`git log`** vs the last **`chore(release)`** before merging; rebasing the release branch may be needed so **`master`** still matches what you intend to ship.