@muggleai/works 2.0.2 → 3.1.0

package/README.md

@@ -1,37 +1,27 @@
-# muggle-ai-works
+# *muggle-ai-works*
 
-**Ship quality products, not just code.** AI-powered QA that validates your app's user experience — from Claude Code and Cursor to PR.
+**Ship quality products with AI-powered QA that validates your app's user experience — from Claude Code and Cursor to PR.**
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![npm](https://img.shields.io/npm/v/@muggleai/works)]()
-[![MCP Tools](https://img.shields.io/badge/MCP_tools-70+-green)]()
-[![Node](https://img.shields.io/badge/node-22+-orange)]()
+One install gives your AI coding assistant the power to vision-based 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 ability to QA your app like a real user would — clicking through flows, catching broken experiences, and opening PRs with results.
+*[License: MIT](LICENSE)
+[npm]()
+[MCP Tools]()
+[Node*]()
 
-Part of the **Muggle AI** open-source ecosystem:
-
-| Package | Purpose | Install |
-|---------|---------|---------|
-| **muggle-ai-works** (this repo) | QA testing MCP server + autonomous dev pipeline | `npm install @muggleai/works` |
-| **[muggle-ai-teams](https://github.com/multiplex-ai/muggle-ai-teams)** | Agent orchestration, workflow, skills, rules | `npm install @muggleai/teams` |
-
-muggle-ai-works handles *QA verification* (test generation, browser replay, cloud results). muggle-ai-teams handles *how work gets done* (design → implement → review → deliver). Together, they form a complete AI-assisted development workflow with built-in quality assurance.
+*Powered by [MuggleTest](https://www.muggletest.com) — the [AI-powered QA testing platform](https://www.muggletest.com).*
 
 ---
 
-## How Is This Different?
+## Why muggle-ai-works?
+
+Your AI assistant writes code fast. But does the feature actually work? Does the login flow break on mobile? Does the checkout still render after that refactor?
 
-Most AI coding tools help you *write* code. muggle-ai-works helps you *test* it — automatically, using AI-driven browser automation.
+muggle-ai-works closes the gap between "code complete" and "actually works."
 
-| | **muggle-ai-works** | **Playwright MCP** | **Manual QA** |
-|---|---|---|---|
-| **Test creation** | Natural language → test cases | Write code manually | Write test plans manually |
-| **Test execution** | AI-driven browser (Electron app) | Scripted browser automation | Human clicks through flows |
-| **Localhost testing** | Built-in URL rewriting | Manual config | Manual |
-| **Cloud sync** | Automatic (projects, cases, scripts, results) | None | Spreadsheets |
-| **Integration** | MCP tools for any AI assistant | Playwright API | None |
-| **Learning curve** | Describe what to test in English | Learn Playwright API | Train QA team |
+- **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: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.
+- **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.
 
 ---
 
@@ -39,37 +29,56 @@ Most AI coding tools help you *write* code. muggle-ai-works helps you *test* it
 
 ### 1. Install
 
-```bash
-npm install @muggleai/works
+In Claude Code, run:
+
 ```
+/plugin marketplace add https://github.com/multiplex-ai/muggle-ai-works
+/plugin install muggleai@muggle-works
+```
+
+This installs the Muggle AI plugin with:
 
-This automatically:
-1. Downloads the QA engine (Electron app) for browser automation
-2. Registers the MCP server in `~/.cursor/mcp.json`
-3. Installs skills (`/muggle-do`, `/test-feature-local`) to `~/.claude/`
+- `/muggle:do` — autonomous dev pipeline (requirements to PR)
+- `/muggle:test-feature-local` — local quick QA testing
+- `/muggle:status` — health check for muggle-works plugins (Electron app, MCP server, and auth)
+- `/muggle:repair` — diagnose and fix broken installation
+- `/muggle:upgrade` — update to the latest version
+- MCP server with 70+ tools (auto-started)
+- Electron QA engine provisioning (via session hook)
 
 ### 2. Verify
 
-```bash
-muggle --version
-muggle doctor
+```
+/muggle:status
 ```
 
-### 3. Start testing
+This checks Electron QA engine, MCP server health, and authentication. If anything is broken, run `/muggle:repair`.
 
-In Claude Code or Cursor, just ask:
+### 3. Start building features
 
-> "Test my login flow on localhost:3000"
+Describe what you want to build:
 
-Your AI assistant will authenticate, find or create test cases, launch the browser, record/replay tests, and show you results with screenshots.
+```
+/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.
+
+### 4. Test a feature locally
+
+Already have code running on localhost? Test it directly:
+
+```
+/muggle:test-feature-local
+```
+
+Describe what to test in plain English. The AI finds or creates test cases, launches a real browser, and reports results with screenshots.
 
-## How It Works
+---
 
-### Design principle: "Create remotely, execute locally"
+## How does it work?
 
-All entity management (projects, use cases, test cases) lives in the **cloud** via `muggle-remote-*` tools. Local execution (`muggle-local-*`) is stateless — it receives everything it needs as input and just runs tests.
+muggle-ai-works separates test management from test execution. All entity management (projects, use cases, test cases) lives in the cloud via `muggle-remote-*` tools. Local execution (`muggle-local-*`) is stateless — it receives what it needs and runs the test.
 
 ### Entity model
 
@@ -81,7 +90,7 @@ Project (e.g., "My App")
                  └── Run Result (pass/fail + screenshots)
 ```
 
-### Test execution flow
+Test execution flow
 
 ```
 Your AI assistant describes what to test
@@ -109,12 +118,12 @@ muggle-local-publish-test-script uploads to cloud
 
 ## Three Ways to Use It
 
-### 1. `/test-feature-local` — Test a feature on localhost
+### 1. `/muggle:test-feature-local` — Test a feature on localhost
 
-Interactive workflow: pick a project → pick a use case → pick a test case → run against localhost.
+Describe what to test in English. The AI finds the right project and test cases, launches a real browser, and reports results with screenshots.
 
 ```
-> /test-feature-local
+> /muggle:test-feature-local
 
 "Test my login changes on localhost:3999"
 
@@ -128,12 +137,12 @@ Interactive workflow: pick a project → pick a use case → pick a test case
 7. Publish to cloud? (y)
 ```
 
-### 2. `/muggle-do` — Autonomous dev pipeline
+### 2. `/muggle:do` — Autonomous dev pipeline
 
-Full development cycle: requirements → code → unit tests → QA → PR creation.
+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.
 
 ```
-> /muggle-do "Add a logout button to the header"
+> /muggle:do "Add a logout button to the header"
 
 REQUIREMENTS  → Goal: Add logout button. Criteria: visible, functional, redirects.
 IMPACT        → frontend repo, src/components/Header.tsx
@@ -145,15 +154,14 @@ OPEN_PRS      → PR #42 opened
 DONE          → 1 iteration, all green
 ```
 
-Features:
 - Session-based with crash recovery (`.muggle-do/sessions/`)
-- Auto-triage: analyzes failures, jumps back to fix (max 3 iterations)
+- Auto-triage: analyzes failures and loops back to fix (max 3 iterations)
 - Multi-repo support via `muggle-repos.json`
-- Creates PRs with QA results in description
+- PRs include QA results and screenshots in the description
 
-### 3. Direct MCP tool calls — Build your own workflow
+### 3. Direct MCP tool calls — Build your own QA workflow
 
-Use any of the 70+ MCP tools directly from your AI assistant:
+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.
 
 ```
 "Create a project called My App with URL https://myapp.com"
@@ -164,193 +172,172 @@ Use any of the 70+ MCP tools directly from your AI assistant:
 
 ---
 
-## Integration with muggle-ai-teams
+## What MCP tools are included?
 
-When both packages are installed, muggle-ai-teams automatically integrates QA into its workflow:
+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.
 
-| Workflow Step | What Happens |
-|--------------|-------------|
-| **Step 1F** (Plan) | QA test instructions written per implementation slice |
-| **Step 2** (Execute) | Per-slice QA via muggle-ai-works before each commit |
-| **Step 3** (Verify) | Full regression sweep replaying all project scripts |
-| **Step 5** (Push) | QA results published to cloud, linked in PR description |
+Authentication (muggle-remote-auth-*)
 
-Frontend slices get browser QA. Backend-only slices are verified by unit tests (browser QA skipped with documented reasoning).
 
-Install both: `npm install @muggleai/works @muggleai/teams`
+| Tool                        | Purpose                      |
+| --------------------------- | ---------------------------- |
+| `muggle-remote-auth-status` | Check authentication status  |
+| `muggle-remote-auth-login`  | Start device-code login flow |
+| `muggle-remote-auth-poll`   | Poll for login completion    |
+| `muggle-remote-auth-logout` | Clear credentials            |
 
----
 
-## Available MCP Tools (70+)
+Project Management (muggle-remote-project-*)
 
-### Authentication (`muggle-remote-auth-*`)
 
-| Tool | Purpose |
-|------|---------|
-| `muggle-remote-auth-status` | Check authentication status |
-| `muggle-remote-auth-login` | Start device-code login flow |
-| `muggle-remote-auth-poll` | Poll for login completion |
-| `muggle-remote-auth-logout` | Clear credentials |
+| Tool                           | Purpose             |
+| ------------------------------ | ------------------- |
+| `muggle-remote-project-create` | Create QA project   |
+| `muggle-remote-project-list`   | List all projects   |
+| `muggle-remote-project-get`    | Get project details |
+| `muggle-remote-project-update` | Update project      |
+| `muggle-remote-project-delete` | Delete project      |
 
-### Project Management (`muggle-remote-project-*`)
 
-| Tool | Purpose |
-|------|---------|
-| `muggle-remote-project-create` | Create QA project |
-| `muggle-remote-project-list` | List all projects |
-| `muggle-remote-project-get` | Get project details |
-| `muggle-remote-project-update` | Update project |
-| `muggle-remote-project-delete` | Delete project |
+Use Cases (muggle-remote-use-case-*)
 
-### Use Cases (`muggle-remote-use-case-*`)
 
-| Tool | Purpose |
-|------|---------|
-| `muggle-remote-use-case-list` | List use cases |
+| Tool                                         | Purpose                      |
+| -------------------------------------------- | ---------------------------- |
+| `muggle-remote-use-case-list`                | List use cases               |
 | `muggle-remote-use-case-create-from-prompts` | Create from natural language |
-| `muggle-remote-use-case-prompt-preview` | Preview before creating |
-| `muggle-remote-use-case-update-from-prompt` | Regenerate from new prompt |
-
-### Test Cases (`muggle-remote-test-case-*`)
-
-| Tool | Purpose |
-|------|---------|
-| `muggle-remote-test-case-list` | List all test cases |
-| `muggle-remote-test-case-list-by-use-case` | List by use case |
-| `muggle-remote-test-case-get` | Get test case details |
-| `muggle-remote-test-case-create` | Create test case |
-| `muggle-remote-test-case-generate-from-prompt` | Generate from prompt |
-
-### Test Scripts & Workflows (`muggle-remote-workflow-*`)
-
-| Tool | Purpose |
-|------|---------|
-| `muggle-remote-test-script-list` | List test scripts |
-| `muggle-remote-test-script-get` | Get script details |
-| `muggle-remote-workflow-start-website-scan` | Scan site for use cases |
-| `muggle-remote-workflow-start-test-case-detection` | Generate test cases |
-| `muggle-remote-workflow-start-test-script-generation` | Generate scripts |
-| `muggle-remote-workflow-start-test-script-replay` | Replay single script |
-| `muggle-remote-workflow-start-test-script-replay-bulk` | Batch replay |
-
-### Local Execution (`muggle-local-*`)
-
-| Tool | Purpose |
-|------|---------|
-| `muggle-local-check-status` | Check local QA engine 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 |
-
-### Reports & Analytics (`muggle-remote-report-*`)
-
-| Tool | Purpose |
-|------|---------|
-| `muggle-remote-report-stats-summary-get` | Report statistics |
-| `muggle-remote-report-cost-query` | Query cost/usage |
-| `muggle-remote-report-final-generate` | Generate final report (PDF/HTML/Markdown) |
-| `muggle-remote-project-test-results-summary-get` | Test results summary |
-
-Also available: PRD processing (`muggle-remote-prd-*`), secrets management (`muggle-remote-secret-*`), wallet/billing (`muggle-remote-wallet-*`), and scheduling recommendations (`muggle-remote-recommend-*`).
+| `muggle-remote-use-case-prompt-preview`      | Preview before creating      |
+| `muggle-remote-use-case-update-from-prompt`  | Regenerate from new prompt   |
 
----
 
-## CLI Commands
+Test Cases (muggle-remote-test-case-*)
 
-```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
 
-# Setup & Diagnostics
-muggle setup              # Download/update QA engine
-muggle setup --force      # Force re-download
-muggle doctor             # Diagnose installation issues
+| Tool                                           | Purpose               |
+| ---------------------------------------------- | --------------------- |
+| `muggle-remote-test-case-list`                 | List all test cases   |
+| `muggle-remote-test-case-list-by-use-case`     | List by use case      |
+| `muggle-remote-test-case-get`                  | Get test case details |
+| `muggle-remote-test-case-create`               | Create test case      |
+| `muggle-remote-test-case-generate-from-prompt` | Generate from prompt  |
 
-# Authentication
-muggle login              # Manually trigger login
-muggle logout             # Clear credentials
-muggle status             # Show auth status
 
-# Info
-muggle --version          # Show version
-muggle --help             # Show help
-```
+Test Scripts and Workflows (muggle-remote-workflow-*)
 
----
 
-## Authentication
+| Tool                                                   | Purpose                 |
+| ------------------------------------------------------ | ----------------------- |
+| `muggle-remote-test-script-list`                       | List test scripts       |
+| `muggle-remote-test-script-get`                        | Get script details      |
+| `muggle-remote-workflow-start-website-scan`            | Scan site for use cases |
+| `muggle-remote-workflow-start-test-case-detection`     | Generate test cases     |
+| `muggle-remote-workflow-start-test-script-generation`  | Generate scripts        |
+| `muggle-remote-workflow-start-test-script-replay`      | Replay single script    |
+| `muggle-remote-workflow-start-test-script-replay-bulk` | Batch replay            |
 
-Authentication happens automatically when you first use a tool that requires it:
 
-1. A browser window opens with a verification code
-2. You log in with your Muggle AI account
-3. The tool call continues with your credentials
+Local Execution (muggle-local-*)
 
-Credentials are stored in `~/.muggle-ai/` and persist across sessions.
 
-### Handling expired tokens
+| Tool                                   | Purpose                            |
+| -------------------------------------- | ---------------------------------- |
+| `muggle-local-check-status`            | Check local QA engine 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            |
 
-1. **Check status**: `muggle status` or `muggle-remote-auth-status`
-2. **Re-authenticate**: `muggle login` or `muggle-remote-auth-login`
-3. **If "unauthorized_client"**: Check `MUGGLE_MCP_PROMPT_SERVICE_TARGET` environment variable (see Troubleshooting)
 
----
+Reports and Analytics (muggle-remote-report-*)
 
-## Data Directory
 
-```
-~/.muggle-ai/
-├── auth.json             # OAuth tokens
-├── credentials.json      # API key for service calls
-├── projects/             # Local project cache
-├── sessions/             # QA sessions
-│   └── {runId}/
-│       ├── action-script.json    # Recorded browser steps
-│       ├── results.md            # Step-by-step report
-│       └── screenshots/          # Per-step images
-└── electron-app/         # Downloaded QA engine
-    └── {version}/
-```
+| Tool                                             | Purpose                                   |
+| ------------------------------------------------ | ----------------------------------------- |
+| `muggle-remote-report-stats-summary-get`         | Report statistics                         |
+| `muggle-remote-report-cost-query`                | Query cost/usage                          |
+| `muggle-remote-report-final-generate`            | Generate final report (PDF/HTML/Markdown) |
+| `muggle-remote-project-test-results-summary-get` | Test results summary                      |
+
+
+Administration (PRD, secrets, billing, scheduling)
+
+
+| Category           | Tools                                                                |
+| ------------------ | -------------------------------------------------------------------- |
+| PRD processing     | `muggle-remote-prd-`* — upload and process product requirements docs |
+| Secrets management | `muggle-remote-secret-`* — store credentials for test environments   |
+| Wallet and billing | `muggle-remote-wallet-`* — manage credits and payment methods        |
+| Scheduling         | `muggle-remote-recommend-*` — get CI/CD and schedule recommendations |
+
 
 ---
 
-## Platform Compatibility
+## 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.
+
+
+| Workflow Step | What Happens                                            |
+| ------------- | ------------------------------------------------------- |
+| **Plan**      | QA test instructions written per implementation slice   |
+| **Build**     | Per-slice QA 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 |
+
+
+Frontend slices get browser QA. Backend-only slices are verified by unit tests (browser QA skipped with documented reasoning).
+
+Install both: `npm install @muggleai/works @muggleai/teams`
+
+**Muggle AI open-source ecosystem:**
+
+
+| Package                                                                | Purpose                                         | Install                                 |
+| ---------------------------------------------------------------------- | ----------------------------------------------- | --------------------------------------- |
+| **muggle-ai-works** (this repo)                                        | QA 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`           |
 
-| Platform | MCP Tools | /muggle-do | /test-feature-local |
-|----------|-----------|-----------|-------------------|
-| **Claude Code** | Yes | Yes | Yes |
-| **Cursor** | Yes (via MCP) | No (needs Agent tool) | No (needs Skill tool) |
-| **Others** | Via MCP if supported | No | No |
 
-The MCP server (`muggle serve`) works with any MCP-compatible client. The distributed skills (`/muggle-do`, `/test-feature-local`) require Claude Code's Agent and Skill tools.
+Want the full platform experience? [MuggleTest](https://www.muggletest.com) gives you everything out of the box — no setup, no configuration.
 
 ---
 
-## Configuration
+## CLI Reference
 
-### MCP client config
+```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
 
-**Cursor** (`~/.cursor/mcp.json`) — auto-configured on install:
+# Setup and Diagnostics
+muggle setup              # Download/update QA engine
+muggle setup --force      # Force re-download
+muggle doctor             # Diagnose installation issues
 
-```json
-{
-  "mcpServers": {
-    "muggle": {
-      "command": "muggle",
-      "args": ["serve"]
-    }
-  }
-}
+# Authentication
+muggle login              # Manually trigger login
+muggle logout             # Clear credentials
+muggle status             # Show auth status
+
+# Info
+muggle --version          # Show version
+muggle --help             # Show help
 ```
 
-### Environment targeting
+---
+
+## Setup and Configuration
+
+Authentication happens automatically when you first use a tool that requires it: a browser window opens with a verification code, you log in with your Muggle AI account, and the tool call continues. Credentials persist across sessions in `~/.muggle-ai/`.
 
-Set `MUGGLE_MCP_PROMPT_SERVICE_TARGET` to switch between production and dev:
+MCP client configuration examples
+
+When installed as a plugin, MCP server configuration is shipped by the plugin (`plugin/.mcp.json`) and does not require manual user-level file copy.
+
+**Environment targeting** — set `MUGGLE_MCP_PROMPT_SERVICE_TARGET` to switch between production and dev:
 
 ```json
 {
@@ -366,9 +353,7 @@ Set `MUGGLE_MCP_PROMPT_SERVICE_TARGET` to switch between production and dev:
 }
 ```
 
-### Multi-repo config for /muggle-do
-
-Create `muggle-repos.json` in your working directory:
+**Multi-repo config for /muggle:do** — create `muggle-repos.json` in your working directory:
 
 ```json
 [
@@ -377,50 +362,41 @@ Create `muggle-repos.json` in your working directory:
 ]
 ```
 
----
-
-## Development
+Data directory structure (~/.muggle-ai/)
 
-```bash
-# Install dependencies
-pnpm install
-
-# Build
-pnpm run build
-
-# Dev mode (watch)
-pnpm run dev
+```
+~/.muggle-ai/
+├── auth.json             # OAuth tokens
+├── credentials.json      # API key for service calls
+├── projects/             # Local project cache
+├── sessions/             # QA sessions
+│   └── {runId}/
+│       ├── action-script.json    # Recorded browser steps
+│       ├── results.md            # Step-by-step report
+│       └── screenshots/          # Per-step images
+└── electron-app/         # Downloaded QA engine
+    └── {version}/
+```
 
-# Test
-pnpm test
-pnpm run test:watch
+---
 
-# Lint
-pnpm run lint          # Auto-fix
-pnpm run lint:check    # Check only
+## What AI clients does it work with?
 
-# Typecheck
-pnpm run typecheck
-```
+Full support for Claude Code. MCP tools work with Cursor and any MCP-compatible client. Plugin skills require Claude Code plugin support.
 
-### CI/CD
+Platform compatibility table
 
-| Workflow | Trigger | Description |
-|----------|---------|-------------|
-| `ci.yml` | Push/PR to `master` | Lint, test, build on multiple platforms |
-| `publish-works.yml` | Tag `v*` or manual | Verify, audit, smoke-install, publish to npm |
 
-### Publishing
+| Platform        | MCP Tools            | Plugin skills (/muggle:*)                             |
+| --------------- | -------------------- | ----------------------------------------------------- |
+| **Claude Code** | Yes                  | Yes (do, test-feature-local, status, repair, upgrade) |
+| **Cursor**      | Yes (via MCP)        | No (needs plugin support)                             |
+| **Others**      | Via MCP if supported | No                                                    |
 
-```bash
-# Update version in package.json
-git tag v2.0.1 && git push --tags
-# publish-works.yml handles the rest
-```
 
 ---
 
-## Troubleshooting
+Troubleshooting
 
 ### "unauthorized_client" during login
 
@@ -447,11 +423,72 @@ muggle login            # Fresh login
 
 ## About
 
-Built by the team behind **[MuggleTest](https://www.muggletest.com)** — an AI-powered QA testing platform that makes software testing accessible to everyone, no coding required.
+Built by the team behind [MuggleTest](https://www.muggletest.com) — [AI-powered QA testing](https://www.muggletest.com) for teams who ship fast.
 
-**Muggle AI open-source ecosystem:**
-- **[muggle-ai-works](https://github.com/multiplex-ai/muggle-ai-works)** — QA testing MCP server + autonomous dev pipeline (this repo)
-- **[muggle-ai-teams](https://github.com/multiplex-ai/muggle-ai-teams)** — Agent orchestration, workflow, skills, and rules
+Repository structure
+
+```
+muggle-ai-works/
+├── plugin/                  # Claude Code plugin (source of truth)
+│   ├── .claude-plugin/      #   Plugin manifest (plugin.json)
+│   ├── skills/              #   Skill definitions
+│   │   ├── do/              #     /muggle:do — autonomous dev pipeline
+│   │   ├── test-feature-local/  # /muggle:test-feature-local
+│   │   ├── status/          #     /muggle:status
+│   │   ├── repair/          #     /muggle:repair
+│   │   └── upgrade/         #     /muggle:upgrade
+│   ├── hooks/               #   Session hooks (hooks.json)
+│   ├── scripts/             #   Hook scripts (ensure-electron-app.sh)
+│   ├── .mcp.json            #   MCP server config
+│   └── README.md            #   Plugin install and usage docs
+│
+├── src/                     # Application source
+│   ├── cli/                 #   CLI commands (serve, setup, doctor, login, etc.)
+│   └── server/              #   MCP server (tool registration, stdio transport)
+│
+├── packages/                # Workspace packages
+│   ├── mcps/                #   Core MCP runtime — tool registries, schemas, services
+│   ├── commands/            #   CLI command contracts and registration
+│   └── workflows/           #   Workflow contracts and tests
+│
+├── scripts/                 # Build and release
+│   ├── build-plugin.mjs     #   Assembles dist/plugin/ from plugin/ source
+│   ├── verify-plugin-marketplace.mjs  # Validates plugin/marketplace consistency
+│   └── postinstall.mjs      #   npm postinstall (Electron app download)
+│
+├── bin/                     # CLI entrypoint (muggle.js → dist/cli.js)
+├── dist/                    # Build output (gitignored)
+├── .claude-plugin/          # Marketplace catalog (marketplace.json)
+└── docs/                    # Internal design docs and plans
+```
+
+Development commands
+
+```bash
+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 dev              # Dev mode (watch)
+pnpm test                 # Run tests
+pnpm run lint             # Lint (auto-fix)
+pnpm run lint:check       # Lint (check only)
+pnpm run typecheck        # TypeScript type check
+```
+
+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                 |
+
+
+```bash
+git tag v<version> && git push --tags
+# publish-works.yml handles the rest
+```
 
 ---
 
@@ -459,6 +496,4 @@ Built by the team behind **[MuggleTest](https://www.muggletest.com)** — an AI-
 
 [MIT](LICENSE) — Use it, fork it, make it yours.
 
----
-
-If this helps your development workflow, consider giving it a star. It helps others find it.
+If this helps your development workflow, consider giving it a star. It helps others find it.