@muggleai/works 4.2.1 → 4.3.0

package/README.md

@@ -1,15 +1,15 @@
 # *muggle-ai-works*
 
-**Run real-browser QA 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.**
+**Run real-browser 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.**
 
-One install gives your AI coding assistant the power to QA your app like a real user would: clicking through flows, catching broken experiences, and reporting results with screenshots and evidence.
+One install gives your AI coding assistant the power to exercise your app like a real user would: clicking through flows, catching broken experiences, and reporting results with screenshots and evidence.
 
 *[License: MIT](LICENSE)
 [npm]()
 [MCP Tools]()
 [Node*]()
 
-*Powered by [MuggleTest](https://www.muggletest.com) — the [AI-powered QA testing platform](https://www.muggletest.com).*
+*Powered by [MuggleTest](https://www.muggletest.com) — the [AI-powered E2E acceptance testing platform](https://www.muggletest.com).*
 
 ---
 
@@ -20,61 +20,92 @@ Your AI assistant writes code fast. But does the feature actually work? Does the
 muggle-ai-works closes the gap between "code complete" and "actually works."
 
 - **Catch UX regressions before your users do** — AI drives a real browser against your localhost across desktop and mobile resolutions, clicks through flows like a user would, and reports failures with step-by-step screenshots. No Playwright scripts to maintain.
-- **Go from requirement to merged PR in one command** — `/muggle:muggle-do` handles the full cycle: code the feature, run unit tests, QA the app in a real browser at multiple viewports, triage failures, and open a PR with evidence attached.
+- **Go from requirement to merged PR in one command** — `/muggle:muggle-do` handles the full cycle: code the feature, run unit tests, run E2E acceptance tests against the app in a real browser at multiple viewports, triage failures, and open a PR with evidence attached.
 - **70+ MCP tools for custom workflows** — manage projects, generate test cases from plain English, replay test scripts, batch-run regressions, and publish results to your team. Works in Claude Code, Cursor, and any MCP client.
 
 ---
 
 ## Quick Start
 
-### 1. Install
+### 1. Install (choose your client)
 
-In Claude Code, run:
+**Claude Code (full plugin experience)**
 
 ```
 /plugin marketplace add https://github.com/multiplex-ai/muggle-ai-works
 /plugin install muggleai@muggle-works
 ```
 
-If you install via npm instead:
-
-```bash
-npm install -g @muggleai/works
-```
-
-`npm install` updates the CLI and syncs `muggle-*` skills to `~/.cursor/skills/` for Cursor discovery. Claude slash commands are plugin-managed, so update those with `/plugin update muggleai@muggle-works`.
-
-This installs the Muggle AI plugin with:
+This installs:
 
 - `/muggle:muggle` — command router and menu
 - `/muggle:muggle-do` — autonomous dev pipeline (requirements to PR)
-- `/muggle:muggle-test-feature-local` — local quick QA testing
+- `/muggle:muggle-test` — change-driven E2E acceptance testing (local or remote, with PR posting)
+- `/muggle:muggle-test-feature-local` — local quick E2E acceptance testing
 - `/muggle:muggle-status` — health check for muggle-works plugins (Electron app, MCP server, and auth)
 - `/muggle:muggle-repair` — diagnose and fix broken installation
 - `/muggle:muggle-upgrade` — update to the latest version
 - MCP server with 70+ tools (auto-started)
-- Electron QA engine provisioning (via session hook)
+- Electron browser test runner provisioning (via session hook)
+
+**Cursor, Codex, Windsurf, and other MCP clients (MCP tools only)**
+
+```bash
+npm install -g @muggleai/works
+```
+
+Then configure your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "muggle": {
+      "command": "muggle",
+      "args": ["serve"],
+      "env": {
+        "MUGGLE_MCP_PROMPT_SERVICE_TARGET": "production"
+      }
+    }
+  }
+}
+```
+
+`npm install` also syncs `muggle-*` skills to `~/.cursor/skills/` for Cursor discovery. Claude slash commands are plugin-managed, so update those with `/plugin update muggleai@muggle-works`.
 
 ### 2. Verify
 
+**Claude Code**
+
 ```
 /muggle:muggle-status
 ```
 
-This checks Electron QA engine, MCP server health, and authentication. If anything is broken, run `/muggle:muggle-repair`.
+This checks Electron browser test runner, MCP server health, and authentication. If anything is broken, run `/muggle:muggle-repair`.
+
+**Cursor/Codex/Windsurf/other MCP clients**
+
+Run any `muggle-*` MCP tool from your client after adding the MCP server config above. Authentication starts automatically on first protected tool call.
 
 ### 3. Start building features
 
+**Claude Code**
+
 Describe what you want to build:
 
 ```
 /muggle:muggle-do "Add a logout button to the header"
 ```
 
-The AI handles the full cycle: code the feature, run unit tests, QA the app in a real browser, and open a PR with results.
+The AI handles the full cycle: code the feature, run unit tests, run E2E acceptance tests against the app in a real browser, and open a PR with results.
+
+**Cursor/Codex/Windsurf/other MCP clients**
+
+Use the direct MCP workflow section below to call `muggle-*` tools from your client.
 
 ### 4. Test a feature locally
 
+**Claude Code**
+
 Already have code running on localhost? Test it directly:
 
 ```
@@ -83,6 +114,10 @@ Already have code running on localhost? Test it directly:
 
 Describe what to test in plain English. The AI finds or creates test cases, launches a real browser, and reports results with screenshots.
 
+**Cursor/Codex/Windsurf/other MCP clients**
+
+Call local execution MCP tools directly (for example `muggle-local-execute-test-script-replay` or related `muggle-local-*` commands exposed by your client).
+
 ---
 
 ## How does it work?
@@ -108,7 +143,7 @@ Your AI assistant describes what to test
 muggle-remote-* tools create test cases in cloud
          │
          v
-muggle-local-execute-test-generation launches the QA engine
+muggle-local-execute-test-generation launches the browser test runner
          │
          v
 AI agent drives the browser step-by-step (click, type, navigate, assert)
@@ -120,7 +155,7 @@ Screenshots captured per step → action-script.json recorded
 Results: pass/fail with evidence at ~/.muggle-ai/sessions/{runId}/
          │
          v
-muggle-local-publish-test-script uploads to cloud
+muggle-local-publish-test-script uploads to cloud → returns viewUrl to open dashboard
 ```
 
 ---
@@ -140,7 +175,7 @@ Describe what to test in English. The AI finds the right project and test cases,
 2. Found project: "My App"
 3. Found use case: "User Login"
 4. Found 2 test cases — recommend replay (minor changes detected)
-5. Launching QA engine... (approve? y)
+5. Launching browser test runner... (approve? y)
 6. Results: 2/2 PASS
    Screenshots: ~/.muggle-ai/sessions/abc123/screenshots/
 7. Publish to cloud? (y)
@@ -148,7 +183,7 @@ Describe what to test in English. The AI finds the right project and test cases,
 
 ### 2. `/muggle:muggle-do` — Autonomous dev pipeline
 
-Full development cycle: requirements to PR in one command. The AI codes the feature, writes unit tests, runs QA against your running app, and opens a PR.
+Full development cycle: requirements to PR in one command. The AI codes the feature, writes unit tests, runs E2E acceptance tests against your running app, and opens a PR.
 
 ```
 > /muggle:muggle-do "Add a logout button to the header"
@@ -158,7 +193,7 @@ IMPACT        → frontend repo, src/components/Header.tsx
 VALIDATE      → Branch: feat/add-logout, 1 commit
 CODING        → (writes/fixes code)
 UNIT_TESTS    → 12/12 pass
-QA            → 3/3 test cases pass
+E2E acceptance → 3/3 test cases pass
 OPEN_PRS      → PR #42 opened
 DONE          → 1 iteration, all green
 ```
@@ -166,24 +201,24 @@ DONE          → 1 iteration, all green
 - Session-based with crash recovery (`.muggle-do/sessions/`)
 - Auto-triage: analyzes failures and loops back to fix (max 3 iterations)
 - Multi-repo support via `muggle-repos.json`
-- PRs include QA results and screenshots in the description
+- PRs include E2E acceptance results and screenshots in the description
 
-### 3. Direct MCP tool calls — Build your own QA workflow
+### 3. Direct MCP tool calls — Build your own E2E acceptance workflow
 
-Use any of the 70+ MCP tools directly from your AI assistant. This is the lowest-level option and the most flexible for building custom QA workflows.
+Use any of the 70+ MCP tools directly from your AI assistant. This is the lowest-level option and the most flexible for building custom E2E acceptance workflows.
 
 ```
 "Create a project called My App with URL https://myapp.com"
 "Generate test cases for the checkout flow"
 "Replay all test scripts against localhost:3000"
-"Show me the latest QA results"
+"Show me the latest E2E acceptance results"
 ```
 
 ---
 
 ## What MCP tools are included?
 
-muggle-ai-works provides 70+ MCP tools organized into 8 categories: authentication, project management, use cases, test cases, test scripts, local execution, reports, and administration. These tools power all AI testing automation workflows — from one-off browser checks to full QA automation pipelines.
+muggle-ai-works provides 70+ MCP tools organized into 8 categories: authentication, project management, use cases, test cases, test scripts, local execution, reports, and administration. These tools power all AI testing automation workflows — from one-off browser checks to full E2E acceptance automation pipelines.
 
 Authentication (muggle-remote-auth-*)
 
@@ -201,7 +236,7 @@ Project Management (muggle-remote-project-*)
 
 | Tool                           | Purpose             |
 | ------------------------------ | ------------------- |
-| `muggle-remote-project-create` | Create QA project   |
+| `muggle-remote-project-create` | Create E2E acceptance test project   |
 | `muggle-remote-project-list`   | List all projects   |
 | `muggle-remote-project-get`    | Get project details |
 | `muggle-remote-project-update` | Update project      |
@@ -250,13 +285,13 @@ Local Execution (muggle-local-*)
 
 | Tool                                   | Purpose                            |
 | -------------------------------------- | ---------------------------------- |
-| `muggle-local-check-status`            | Check local QA engine status       |
+| `muggle-local-check-status`            | Check local browser test runner status       |
 | `muggle-local-execute-test-generation` | Generate test script locally       |
 | `muggle-local-execute-replay`          | Replay existing script locally     |
 | `muggle-local-cancel-execution`        | Cancel active execution            |
 | `muggle-local-run-result-list`         | List run results                   |
 | `muggle-local-run-result-get`          | Get detailed results + screenshots |
-| `muggle-local-publish-test-script`     | Publish script to cloud            |
+| `muggle-local-publish-test-script`     | Publish script to cloud, returns `viewUrl` |
 
 
 Reports and Analytics (muggle-remote-report-*)
@@ -285,18 +320,18 @@ Administration (PRD, secrets, billing, scheduling)
 
 ## Works with muggle-ai-teams
 
-[muggle-ai-teams](https://github.com/multiplex-ai/muggle-ai-teams) is the companion package for agent orchestration, workflow steps, and delivery. When both packages are installed, muggle-ai-teams automatically integrates QA into the development workflow at each stage.
+[muggle-ai-teams](https://github.com/multiplex-ai/muggle-ai-teams) is the companion package for agent orchestration, workflow steps, and delivery. When both packages are installed, muggle-ai-teams automatically integrates E2E acceptance testing into the development workflow at each stage.
 
 
 | Workflow Step | What Happens                                            |
 | ------------- | ------------------------------------------------------- |
-| **Plan**      | QA test instructions written per implementation slice   |
-| **Build**     | Per-slice QA via muggle-ai-works before each commit     |
+| **Plan**      | E2E acceptance test instructions written per implementation slice   |
+| **Build**     | Per-slice E2E acceptance tests via muggle-ai-works before each commit     |
 | **Verify**    | Full regression sweep replaying all project scripts     |
-| **Ship**      | QA results published to cloud, linked in PR description |
+| **Ship**      | E2E results published to cloud, linked in PR description |
 
 
-Frontend slices get browser QA. Backend-only slices are verified by unit tests (browser QA skipped with documented reasoning).
+Frontend slices get browser E2E tests. Backend-only slices are verified by unit tests (browser E2E skipped with documented reasoning).
 
 Install both: `npm install @muggleai/works @muggleai/teams`
 
@@ -305,7 +340,7 @@ Install both: `npm install @muggleai/works @muggleai/teams`
 
 | Package                                                                | Purpose                                         | Install                                 |
 | ---------------------------------------------------------------------- | ----------------------------------------------- | --------------------------------------- |
-| **muggle-ai-works** (this repo)                                        | QA testing MCP server + autonomous dev pipeline | `/plugin install muggleai@muggle-works` |
+| **muggle-ai-works** (this repo)                                        | E2E acceptance testing MCP server + autonomous dev pipeline | `/plugin install muggleai@muggle-works` |
 | **[muggle-ai-teams](https://github.com/multiplex-ai/muggle-ai-teams)** | Agent orchestration, workflow, skills, rules    | `npm install @muggleai/teams`           |
 
 
@@ -318,11 +353,11 @@ Want the full platform experience? [MuggleTest](https://www.muggletest.com) give
 ```bash
 # Server (main command — starts MCP server for AI clients)
 muggle serve              # Start with all tools (default)
-muggle serve --qa         # Cloud QA tools only
-muggle serve --local      # Local QA tools only
+muggle serve --e2e        # Cloud E2E tools only (muggle-remote-*)
+muggle serve --local      # Local E2E tools only (muggle-local-*)
 
 # Setup and Diagnostics
-muggle setup              # Download/update QA engine
+muggle setup              # Download/update browser test runner
 muggle setup --force      # Force re-download
 muggle doctor             # Diagnose installation issues
 
@@ -378,12 +413,12 @@ Data directory structure (~/.muggle-ai/)
 ├── oauth-session.json    # OAuth tokens (short-lived, auto-refresh)
 ├── api-key.json          # Long-lived API key for service calls
 ├── projects/             # Local project cache
-├── sessions/             # QA sessions
+├── sessions/             # E2E test sessions
 │   └── {runId}/
 │       ├── action-script.json    # Recorded browser steps
 │       ├── results.md            # Step-by-step report
 │       └── screenshots/          # Per-step images
-└── electron-app/         # Downloaded QA engine
+└── electron-app/         # Downloaded browser test runner
     └── {version}/
 ```
 
@@ -391,7 +426,7 @@ Data directory structure (~/.muggle-ai/)
 
 ## What AI clients does it work with?
 
-Full support for Claude Code. MCP tools work with Cursor and any MCP-compatible client. Plugin skills require Claude Code plugin support.
+Full support for Claude Code. Cursor, Codex, Windsurf, and other MCP-compatible clients use the same MCP tools but do not support Claude plugin slash commands (`/muggle:*`).
 
 Platform compatibility table
 
@@ -413,7 +448,7 @@ Troubleshooting
 
 **Fix**: Set the correct `MUGGLE_MCP_PROMPT_SERVICE_TARGET` in your MCP config and restart your client.
 
-### QA engine not found
+### Browser test runner not found
 
 ```bash
 muggle setup --force    # Re-download
@@ -432,7 +467,7 @@ muggle login            # Fresh login
 
 ## About
 
-Built by the team behind [MuggleTest](https://www.muggletest.com) — [AI-powered QA testing](https://www.muggletest.com) for teams who ship fast.
+Built by the team behind [MuggleTest](https://www.muggletest.com) — [AI-powered E2E acceptance testing](https://www.muggletest.com) for teams who ship fast.
 
 Repository structure
 
@@ -464,8 +499,11 @@ muggle-ai-works/
 ├── scripts/                 # Build and release
 │   ├── build-plugin.mjs     #   Assembles dist/plugin/ from plugin/ source
 │   ├── verify-plugin-marketplace.mjs  # Validates plugin/marketplace consistency
+│   ├── verify-compatibility-contracts.mjs # Validates long-term surface contracts
+│   ├── verify-upgrade-experience.mjs  # Validates in-place upgrade behavior
 │   └── postinstall.mjs      #   npm postinstall (Electron app download)
 │
+├── config/compatibility/     # Contract baselines (CLI/MCP/plugin/skills)
 ├── bin/                     # CLI entrypoint (muggle.js → dist/cli.js)
 ├── dist/                    # Build output (gitignored)
 ├── .claude-plugin/          # Marketplace catalog (marketplace.json)
@@ -479,6 +517,9 @@ pnpm install              # Install dependencies
 pnpm run build            # Build (tsup + plugin artifact)
 pnpm run build:plugin     # Rebuild plugin artifact only
 pnpm run verify:plugin    # Validate plugin/marketplace metadata consistency
+pnpm run verify:contracts # Validate compatibility contracts (CLI/MCP/plugin/skills)
+pnpm run verify:electron-release-checksums # Ensure checksums.txt exists for bundled electron release
+pnpm run verify:upgrade-experience # Validate existing-user cleanup + re-download flow
 pnpm run dev              # Dev mode (watch)
 pnpm test                 # Run tests
 pnpm run lint             # Lint (auto-fix)
@@ -491,16 +532,25 @@ CI/CD and publishing
 
 | Workflow            | Trigger             | Description                                                  |
 | ------------------- | ------------------- | ------------------------------------------------------------ |
-| `ci.yml`            | Push/PR to `master` | Lint, test, build, plugin verification on multiple platforms |
-| `publish-works.yml` | Tag `v*` or manual  | Verify, audit, smoke-install, publish to npm                 |
+| `ci.yml`            | Push/PR to `master` | Lint, test, build, plugin + compatibility contract verification on multiple platforms |
+| `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.yml handles the rest
+# publish-works-to-npm.yml handles the rest
 ```
 
 
+Release tag strategy
+
+- `electron-app-vX.Y.Z` tags in `muggle-ai-works` are for public Electron app binary releases (consumed by `muggle setup`, `muggle upgrade`, and npm postinstall).
+- `vX.Y.Z` tags in `muggle-ai-works` are for npm publishing of `@muggleai/works` (`publish-works-to-npm.yml`).
+- `muggle-ai-teaching-service` builds Electron artifacts and publishes them into this public repo using `electron-app-vX.Y.Z`, so binaries are publicly downloadable.
+- The two version tracks are intentionally separate: runtime Electron artifact versions and npm package versions can move independently.
+
+
 Optimizing agent-facing descriptions
 
 
@@ -529,7 +579,7 @@ This is an **internal-only skill** (not published to customers). It covers:
 | Hook config | `plugin/hooks/hooks.json` |
 | Skill descriptions | `plugin/skills/*/SKILL.md` |
 | Tool descriptions (local) | `packages/mcps/src/mcp/tools/local/tool-registry.ts` |
-| Tool descriptions (cloud) | `packages/mcps/src/mcp/tools/qa/tool-registry.ts` |
+| Tool descriptions (cloud) | `packages/mcps/src/mcp/tools/e2e/tool-registry.ts` |
 | Plugin metadata | `plugin/.claude-plugin/plugin.json` |
 
 **Quick eval run:**