@extension.dev/mcp 3.17.0-canary.1779905934.1151df3

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# @extension.dev/mcp — Changelog
+
+## Unreleased — agent-bridge tools
+
+Adds the MCP client surface for the Extension.js **agent bridge** (dev-time
+observe + act + inspect). All new tools shell out to the `extension` CLI verbs
+(lockstep invariant: the CLI is the single source of behavior), so they require
+a recent **`extension` CLI that ships the bridge verbs** (`logs`, `eval`,
+`storage`, `reload`, `open`, `inspect`, `publish`).
+
+> ⚠️ **Release order:** publish this package ONLY after the `extension` /
+> `extension-develop` suite that ships those verbs is on npm. The published CLI
+> at the time of writing (`3.17.0`) does NOT have them — publishing this package
+> before the suite would ship tools that fail with "unknown command". Bump the
+> version + `extension-*` deps to that suite release, then publish.
+
+New tools (22 total):
+
+- **`extension_logs`** — read/stream logs from every extension context
+  (background, content, popup/options/sidebar/devtools); filters
+  `level`/`context`/`url`/`tab`/`since`, bounded `follow` window.
+- **`extension_eval`** — evaluate an expression in a context (requires the dev
+  session started with `--allow-eval`; MV3 service worker is CSP-gated).
+- **`extension_storage`** — read/write `chrome.storage` (requires `--allow-control`).
+- **`extension_reload`** — reload the extension or a tab (`--allow-control`).
+- **`extension_open`** — open popup/options/sidebar (`--allow-control`).
+- **`extension_dom_inspect`** — CDP-free DOM snapshot of content/page or an open
+  surface (popup/options/sidebar/devtools); `withConsole` merges recent logs.
+- **`extension_publish`** — publish to extension.dev and return a shareable URL
+  (auth-gated; requires `EXTENSION_DEV_TOKEN`).
+- **`extension_source_inspect`** gains **`deepDom`** — pierce CLOSED shadow roots
+  via CDP (Chromium only).
+
+Internal: `lib/act` (CLI shell-out helper), `lib/exec.runExtensionCli` (capture),
+`lib/cdp.getClosedShadowRoots`. Test infra aligned to the workspace vitest
+catalog.

package/README.md

@@ -0,0 +1,101 @@
+# @extension.dev/mcp
+
+MCP server for building, debugging, and publishing cross-browser extensions. Exposes 15 tools that let AI assistants scaffold, develop, build, inspect, and debug extensions using the [extension.dev](https://extension.dev) platform and template catalog.
+
+## What's in this package
+
+```
+@extension.dev/mcp
+  src/              MCP server source (15 tools across 3 tiers)
+  claude/           Claude Code integration (CLAUDE.md, slash commands, rules)
+  bin/              CLI entrypoint
+```
+
+**MCP server** — programmatic bridge between AI assistants and the extension.dev platform. Imports from published npm packages:
+
+- `extension-create` — project scaffolding
+- `extension-develop` — build/dev/preview
+- `extension-install` — managed browser binaries
+
+**Claude Code integration** — drop-in instructions, slash commands, and rules for Claude Code:
+
+- `claude/CLAUDE.md` — project-level instructions for any extension project
+- `claude/commands/` — slash commands (`/extension`, `/extension-add`, `/extension-debug`, `/extension-publish`)
+- `claude/rules/` — rules for extension development, cross-browser compat, and MCP tools
+
+Browser-launching tools (`dev`, `start`, `preview`) shell out to the `extension` CLI since they require the full browser launcher infrastructure.
+
+## Setup
+
+### Claude Code
+
+```bash
+claude mcp add extension-dev npx @extension.dev/mcp
+```
+
+### Claude Desktop / .mcp.json
+
+```json
+{
+  "mcpServers": {
+    "extension-dev": {
+      "command": "npx",
+      "args": ["@extension.dev/mcp"]
+    }
+  }
+}
+```
+
+### Claude Code integration (manual)
+
+Copy the Claude Code rules and commands into any extension project:
+
+```bash
+# Rules (how Claude understands your project)
+cp node_modules/@extension.dev/mcp/claude/CLAUDE.md ~/my-extension/.claude/CLAUDE.md
+
+# Slash commands
+mkdir -p ~/my-extension/.claude/commands
+cp node_modules/@extension.dev/mcp/claude/commands/*.md ~/my-extension/.claude/commands/
+```
+
+## Tools
+
+| Tier | Tool                            | Integration                     | Description                       |
+| ---- | ------------------------------- | ------------------------------- | --------------------------------- |
+| 1    | `extension_create`              | `extensionCreate()`             | Scaffold from a template          |
+| 1    | `extension_list_templates`      | native                          | Browse 60+ templates              |
+| 1    | `extension_build`               | `extensionBuild()`              | Build for production              |
+| 1    | `extension_dev`                 | CLI spawn                       | Dev server with HMR               |
+| 1    | `extension_start`               | CLI spawn                       | Build + preview                   |
+| 1    | `extension_preview`             | CLI spawn                       | Preview production build          |
+| 2    | `extension_get_template_source` | native                          | Read template source files        |
+| 2    | `extension_manifest_validate`   | native                          | Cross-browser manifest validation |
+| 2    | `extension_inspect`             | native                          | Build output analysis             |
+| 2    | `extension_source_inspect`      | CDP WebSocket                   | Live DOM inspection               |
+| 2    | `extension_wait`                | native                          | Poll ready.json contract          |
+| 2    | `extension_add_feature`         | native                          | Add sidebar/popup/content script  |
+| 3    | `extension_install_browser`     | `extensionInstall()`            | Install managed browser           |
+| 3    | `extension_list_browsers`       | `getManagedBrowsersCacheRoot()` | List managed browsers             |
+| 3    | `extension_detect_browsers`     | native                          | System browser detection          |
+
+## Development
+
+```bash
+pnpm install
+pnpm compile    # Build with rslib
+pnpm test       # Run tests
+pnpm start      # Start MCP server
+```
+
+### Publishing
+
+```bash
+NPM_TOKEN=<token> pnpm publish
+```
+
+Uses `prepublishOnly` to run tests and compile before publishing.
+
+## License
+
+MIT

package/bin/extension-mcp.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import {startServer} from '../dist/module.cjs'
+startServer()

package/claude/ARCHITECTURE.md

@@ -0,0 +1,161 @@
+# How the pieces connect
+
+This document explains how the three Claude integration layers — the template, the Claude Code rules, and the MCP tools — connect through the [examples](https://github.com/extension-js/examples) repo.
+
+## The examples repo is the backbone
+
+```
+examples repo (GitHub)
+         │
+         ├── examples/<slug>/           60+ extension templates
+         │     ├── src/manifest.json    Source of truth per template
+         │     ├── template.meta.json   Curated metadata (tags, difficulty, useCases, AI fields)
+         │     └── ...
+         │
+         ├── templates-meta.json        Auto-generated registry (all templates, structured)
+         │     Generated by: scripts/generate-templates-meta.mjs
+         │     Published as: GitHub release asset (nightly tag)
+         │     Contains: slug, surfaces, framework, permissions, files, downloads, integrity
+         │
+         ├── public/<slug>/             Staged sources + pre-built distributions
+         │     ├── src/                 Committed source for website consumption
+         │     └── dist/<browser>/      Pre-built .zip and .xpi files
+         │
+         └── artifacts/                 Build pipeline output
+               └── <slug>.<browser>.zip  Distributable archives
+```
+
+## Three integration layers
+
+### Layer 1: sidebar-claude template
+
+**Location:** `examples/sidebar-claude/`
+**Role in ecosystem:** An example in the examples repo, discoverable like any other template.
+
+```
+User: "Build me a Claude chatbot extension"
+  │
+  ▼
+npx extension create my-bot --template=sidebar-claude
+  │
+  ▼
+Resolves → https://github.com/extension-js/examples/tree/main/examples/sidebar-claude
+  │
+  ▼
+go-git-it clones → copies to ./my-bot/ → installs deps → done
+```
+
+**How it integrates with the examples pipeline:**
+
+- `generate-templates-meta.mjs` auto-discovers it by scanning `examples/sidebar-claude/src/manifest.json`
+- Auto-detects: `uiContext: ["sidebar", "background"]`, `uiFramework: "react"`, `surfaces: ["sidebar", "background"]`
+- Curated `template.meta.json` adds: featured flag, tags (ai, claude), difficulty, useCases, firstSteps
+- CI builds it for Chrome/Edge/Firefox, packages as `.zip`, publishes in nightly release
+- `templates-meta.json` includes download URLs with SHA256 integrity
+
+### Layer 2: Claude Code rules (CLAUDE.md)
+
+**Location:** `claude/CLAUDE.md`
+**Role in ecosystem:** Teaches Claude Code about the extension.dev platform and the template catalog.
+
+```
+Developer copies CLAUDE.md into their project
+  │
+  ▼
+Claude Code reads it at conversation start
+  │
+  ▼
+Claude now knows:
+  ├── Template catalog exists at templates-meta.json
+  ├── Template URL pattern: https://github.com/extension-js/examples/tree/main/examples/<slug>
+  ├── How to recommend templates by surface/framework
+  ├── manifest.json cross-browser format
+  ├── extension.dev commands and gotchas
+  └── How to read example source to learn patterns
+```
+
+**How it integrates with the examples repo:**
+
+- References `templates-meta.json` as the source of truth for template discovery
+- Documents the GitHub URL resolution pattern that `extension create` uses
+- Provides the `curl` command to fetch and query the catalog
+- Documents the nightly release download URL pattern for pre-built distributions
+- Teaches how to contribute new templates (template.meta.json format, generator script)
+
+### Layer 3: MCP tools
+
+**Location:** `claude/rules/mcp-tools.md` (design doc)
+**Role in ecosystem:** Programmatic bridge between Claude and the extension.dev platform, sourced from the examples repo.
+
+```
+Claude (via MCP) calls extension_list_templates({ surface: "sidebar", tags: ["ai"] })
+  │
+  ▼
+MCP server fetches templates-meta.json (cached, 1hr TTL)
+  │
+  ▼
+Returns: [{ slug: "sidebar-claude", ... }, { slug: "sidebar-transformers-js", ... }]
+  │
+  ▼
+Claude calls extension_get_template_source({ slug: "sidebar-claude", files: ["src/manifest.json", "src/lib/claude.ts"] })
+  │
+  ▼
+MCP server fetches from https://raw.githubusercontent.com/extension-js/examples/main/examples/sidebar-claude/<file>
+  │
+  ▼
+Claude reads the source, understands the pattern, adapts it for the user
+  │
+  ▼
+Claude calls extension_create({ projectName: "my-bot", template: "sidebar-claude" })
+  │
+  ▼
+MCP server calls extensionCreate() → same go-git-it flow as CLI
+```
+
+**How it integrates with the examples repo:**
+
+- `extension_list_templates` → reads `templates-meta.json` release asset
+- `extension_get_template_source` → reads raw files from the examples repo
+- `extension_create` → clones from the examples repo (same as CLI)
+- `extension_add_feature` → sources codegen patterns from example templates
+- `extension_manifest_validate` → cross-references against known-good manifests in the catalog
+
+## Data flow
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                    examples repo                          │
+│                                                          │
+│  examples/<slug>/     ──── generate-templates-meta.mjs   │
+│       │                         │                        │
+│       │                         ▼                        │
+│       │              templates-meta.json                 │
+│       │                    │         │                   │
+│       │                    │         │                   │
+└───────┼────────────────────┼─────────┼───────────────────┘
+        │                    │         │
+        │                    │         │
+   ┌────▼────┐    ┌──────────▼───┐  ┌──▼──────────────┐
+   │ Layer 1  │    │   Layer 2    │  │    Layer 3       │
+   │ Template │    │  CLAUDE.md   │  │   MCP Server     │
+   │          │    │              │  │                  │
+   │ sidebar- │    │ References   │  │ list_templates   │
+   │ claude   │    │ catalog &    │  │ get_source       │
+   │          │    │ URL patterns │  │ create           │
+   │ Lives in │    │              │  │ add_feature      │
+   │ examples │    │ Teaches      │  │ validate         │
+   │ repo     │    │ humans how   │  │                  │
+   │          │    │ to use it    │  │ Reads from repo  │
+   └──────────┘    └──────────────┘  │ programmatically │
+                                     └──────────────────┘
+```
+
+## Why this architecture works
+
+1. **Single source of truth.** `templates-meta.json` is generated from the actual examples. No manual sync needed. Add a template to `examples/`, run `pnpm run generate`, and all three layers pick it up.
+
+2. **The examples repo is the knowledge base.** The MCP server doesn't hard-code extension patterns — it reads them from examples. This means new patterns (like `sidebar-claude`) are immediately available to Claude without updating the MCP server.
+
+3. **Graceful degradation.** Users who don't use MCP still benefit from CLAUDE.md. Users who don't use Claude Code still benefit from the template. Each layer works independently.
+
+4. **No lock-in.** The CLAUDE.md works with any AI tool that reads project instructions. The MCP server follows the open MCP protocol. The template is a standard extension project.

package/claude/CLAUDE.md

@@ -0,0 +1,264 @@
+# extension.dev — Claude Code Instructions
+
+You are working on a browser extension project built with the [extension.dev](https://extension.dev) platform, a zero-config cross-browser extension framework.
+
+## Core concepts
+
+- **Only `manifest.json` is required.** The framework auto-detects your project structure from it.
+- **Cross-browser via prefixes.** Use `chromium:` and `firefox:` prefixes in manifest.json for browser-specific fields. The build system strips these at build time.
+- **Framework agnostic.** Vanilla JS/TS, React, Vue, Svelte, and Preact are auto-detected and configured.
+- **Rspack-powered.** Fast Rust-based bundler. You can customize via `extension.config.js`.
+
+## Template catalog
+
+The extension.dev platform ships 60+ templates in the [examples](https://github.com/extension-js/examples) repo. The canonical registry is `templates-meta.json` published as a GitHub release asset and committed to the repo.
+
+**How templates work:**
+
+- `npx extension@latest create my-ext --template=<slug>` fetches from `https://github.com/extension-js/examples/tree/main/examples/<slug>`
+- Template names are directory names under `examples/` in the repo
+- Each template has auto-detected metadata (framework, surfaces, permissions) + optional curated metadata in `template.meta.json`
+
+**Key templates by surface:**
+
+| Surface        | Vanilla      | React            | Vue           | Svelte           | AI               |
+| -------------- | ------------ | ---------------- | ------------- | ---------------- | ---------------- |
+| Content script | `content`    | `content-react`  | `content-vue` | `content-svelte` | —                |
+| Sidebar        | `sidebar`    | `sidebar-shadcn` | —             | —                | `sidebar-claude` |
+| Action popup   | `action`     | —                | —             | —                | `action-chatgpt` |
+| New tab        | `new`        | `new-react`      | `new-vue`     | `new-svelte`     | —                |
+| Full framework | `javascript` | `react`          | `vue`         | `svelte`         | —                |
+
+**When recommending a template:**
+
+1. Match the user's desired surface (sidebar, content script, popup, etc.)
+2. Match their framework preference
+3. Prefer `featured: true` templates for common use cases
+4. For AI-powered extensions, start from `sidebar-claude` or `action-chatgpt`
+
+**To browse all available templates:**
+
+```bash
+# The full catalog with metadata (framework, surfaces, permissions, etc.)
+curl -sL https://github.com/extension-js/examples/releases/download/nightly/templates-meta.json | jq '.templates[] | {slug, description, uiFramework, surfaces}'
+```
+
+**Pre-built distributions** are available for every template:
+
+```
+https://github.com/extension-js/examples/releases/download/nightly/<slug>.<browser>.zip
+```
+
+## Project structure
+
+A typical extension.dev project:
+
+```
+my-extension/
+  src/
+    manifest.json          # Required — the source of truth
+    background.ts          # Service worker (Chromium) / background script (Firefox)
+    content/               # Content scripts
+      scripts.tsx
+      styles.css
+    sidebar/               # Sidebar panel UI
+      index.html
+      scripts.tsx
+      styles.css
+    images/
+      icon.png
+  extension.config.js      # Optional build config
+  extension-env.d.ts       # Auto-generated types
+  package.json
+  tsconfig.json
+```
+
+## manifest.json cross-browser format
+
+The framework extends the standard manifest with browser prefixes:
+
+```json
+{
+  "chromium:manifest_version": 3,
+  "firefox:manifest_version": 2,
+  "name": "My Extension",
+  "chromium:action": { "default_title": "Click me" },
+  "firefox:browser_action": { "default_title": "Click me" },
+  "chromium:side_panel": { "default_path": "sidebar/index.html" },
+  "firefox:sidebar_action": { "default_panel": "sidebar/index.html" },
+  "background": {
+    "chromium:service_worker": "background.ts",
+    "firefox:scripts": ["background.ts"]
+  }
+}
+```
+
+**Rules:**
+
+- Fields without a prefix apply to all browsers
+- `chromium:` fields apply to Chrome, Edge, and Chromium-based browsers
+- `firefox:` fields apply to Firefox and Gecko-based browsers
+- `chromium:permissions` and `firefox:permissions` can differ
+
+## Commands
+
+```bash
+# Scaffold a new extension
+npx extension@latest create my-extension --template=react
+
+# Development with HMR
+npm run dev
+# or: npx extension dev
+
+# Build for production
+npm run build
+# or: npx extension build
+
+# Preview production build
+npm run preview
+# or: npx extension preview
+
+# Target a specific browser
+npm run dev -- --browser=firefox
+npm run build -- --browser=chrome,firefox
+
+# Zip for distribution
+npm run build -- --zip
+```
+
+## extension.config.js
+
+```javascript
+/** @type {import('extension').FileConfig} */
+export default {
+  browser: {
+    chrome: {
+      profile: "./dist/profile-chrome", // Persist browser profile
+      startingUrl: "https://example.com",
+    },
+  },
+  config: (rspackConfig) => {
+    // Mutate Rspack config here
+    return rspackConfig;
+  },
+};
+```
+
+## Important gotchas
+
+1. **world: "MAIN" is Chromium-only.** If your content script uses `"world": "MAIN"`, prefix it with `chromium:` and provide a Firefox fallback or skip.
+2. **Side panels vs sidebar actions.** Chromium uses `side_panel` + `sidePanel` permission. Firefox uses `sidebar_action` (no permission needed).
+3. **Service workers vs background scripts.** Chromium uses `service_worker` (single file). Firefox uses `scripts` (array).
+4. **Environment variables.** Use `EXTENSION_PUBLIC_*` prefix for variables accessible in extension code. `import.meta.env.EXTENSION_PUBLIC_BROWSER` gives the current browser.
+5. **Asset imports.** Import images/fonts directly in your code. The build system handles bundling.
+6. **CSS Modules.** Use `*.module.css` / `*.module.scss`. Never use the `?url` suffix for CSS module imports — it breaks class name hashing.
+
+## When creating new extensions
+
+1. Check if an existing template matches the use case (see template catalog above)
+2. If yes: `npx extension@latest create my-ext --template=<slug>`
+3. If no: start from `manifest.json` — define what the extension needs
+4. Add entry points referenced by the manifest (background, content scripts, UI pages)
+5. Install framework deps if needed (React, Vue, etc.) — the framework auto-detects them
+6. Run `npm run dev` — the dev server handles the rest
+
+**Learning from examples:** When building a feature you haven't done before, read the source of a relevant template from the examples repo. The source for any template is at:
+
+```
+https://github.com/extension-js/examples/tree/main/examples/<slug>/src
+```
+
+## When debugging
+
+### Source inspection (`--source`)
+
+The `--source` flag on `dev` gives live DOM inspection of a running extension:
+
+```bash
+# Basic: see injected HTML after content scripts run
+npm run dev -- --source https://example.com
+
+# Structured JSON output (best for programmatic use)
+npm run dev -- --source https://example.com --source-format json
+
+# Probe specific selectors
+npm run dev -- --source https://example.com --source-probe "#my-root,.sidebar"
+
+# Full inspection: DOM snapshots, console summary, diffs on rebuild
+npm run dev -- --source https://example.com --source-dom --source-console --source-diff
+```
+
+**Available --source sub-flags:**
+
+| Flag                         | Default   | Purpose                                           |
+| ---------------------------- | --------- | ------------------------------------------------- |
+| `--source [url]`             | —         | Open URL and print live HTML after injection      |
+| `--watch-source`             | true      | Re-print on rebuilds                              |
+| `--source-format`            | json      | Output format: `pretty`, `json`, `ndjson`         |
+| `--source-summary`           | auto      | Compact stats instead of full HTML                |
+| `--source-meta`              | auto      | Page metadata: readyState, viewport, frames       |
+| `--source-probe <selectors>` | —         | CSS selectors to query (comma-separated)          |
+| `--source-tree`              | off       | Extension root DOM tree: `off`, `root-only`       |
+| `--source-console`           | auto      | Console counts: error/warn/info/log/debug         |
+| `--source-dom`               | auto      | DOM snapshots and structural diffs                |
+| `--source-max-bytes`         | 256KB     | Truncate HTML output (0 = unlimited)              |
+| `--source-redact`            | safe      | Redact sensitive content: `off`, `safe`, `strict` |
+| `--source-include-shadow`    | open-only | Shadow DOM: `off`, `open-only`, `all`             |
+| `--source-diff`              | auto      | Include diff metadata on watch updates            |
+
+**Output event types** (in JSON/NDJSON format):
+
+- `page_html` — full injected HTML
+- `page_html_summary` — root/script/style/link counts
+- `page_meta` — readyState, viewport, frame count
+- `dom_snapshot` — structured tree (tag, id, classes, role, max 500 nodes)
+- `dom_diff` — added/removed/changed between rebuilds
+- `console_summary` — error/warn counts + top 5 unique messages
+- `selector_probe` — per-selector element counts and samples
+- `extension_root_tree` — extension root elements with reinject generations
+
+### Unified logging (`--logs`)
+
+Stream extension logs from all contexts to the terminal:
+
+```bash
+# All contexts at info level
+npm run dev -- --logs info
+
+# Only content scripts and background
+npm run dev -- --logs debug --log-context content,background
+
+# JSON format for programmatic consumption
+npm run dev -- --logs info --log-format json
+
+# Filter by URL pattern
+npm run dev -- --logs info --log-url "example.com"
+```
+
+### Other debugging tools
+
+- Use `--browser=firefox` to test cross-browser compatibility
+- Check `dist/<browser>/` for build output
+- Use `--wait` flag to check if dev session is ready (outputs ready.json contract)
+- Use `npm run start` to test production builds (builds first, then launches)
+
+## Contributing templates to the examples repo
+
+If you create a new extension pattern worth sharing:
+
+1. Place the example in `examples/<slug>/` following the standard layout
+2. Add `template.meta.json` with curated metadata:
+   ```json
+   {
+     "title": "Human-readable title",
+     "featured": false,
+     "tags": ["relevant", "tags"],
+     "difficulty": "beginner",
+     "timeToFirstSuccessMinutes": 3,
+     "useCases": ["What users would build with this"],
+     "firstSteps": ["Step 1", "Step 2"]
+   }
+   ```
+3. The `generate-templates-meta.mjs` script auto-detects: framework, surfaces, permissions, entry points, CSS tech, config files
+4. Run `pnpm run generate` to regenerate `templates-meta.json`
+5. The CI pipeline handles: build, test (Playwright), package, and nightly release

package/claude/README.md

@@ -0,0 +1,72 @@
+# extension.dev — Claude Code Integration
+
+Drop-in instructions, rules, and example prompts for building browser extensions with the [extension.dev](https://extension.dev) platform using Claude Code.
+
+**Looking for the MCP server?** See the root [`README.md`](../README.md).
+
+## What's here
+
+```
+claude/
+  CLAUDE.md               Drop-in Claude Code instructions for any extension project
+  ARCHITECTURE.md         How the template, CLAUDE.md, and MCP layers connect
+  commands/
+    extension.md          /extension — create, dev, build, add features, debug
+    extension-add.md      /extension-add — add sidebar, popup, content script, etc.
+    extension-debug.md    /extension-debug — live DOM/console inspection
+    extension-publish.md  /extension-publish — store submission prep
+  rules/
+    extension-dev.md      Core rules: project structure, manifest, commands
+    cross-browser.md      Cross-browser manifest field mapping
+    mcp-tools.md          Full MCP tool specification and design doc
+  examples/
+    create-extension.md   Example prompt: scaffold and customize an extension
+    add-sidebar.md        Example prompt: add a sidebar panel to an existing extension
+```
+
+## Quick start
+
+Copy `CLAUDE.md` and slash commands into any extension project:
+
+```bash
+# Rules (how Claude understands your project)
+cp node_modules/@extension.dev/mcp/claude/CLAUDE.md ~/my-extension/.claude/CLAUDE.md
+
+# Slash commands (what you can type)
+mkdir -p ~/my-extension/.claude/commands
+cp node_modules/@extension.dev/mcp/claude/commands/*.md ~/my-extension/.claude/commands/
+```
+
+### Slash commands
+
+| Command                                  | What it does                                           |
+| ---------------------------------------- | ------------------------------------------------------ |
+| `/extension create my-ext react sidebar` | Scaffold a new extension from templates                |
+| `/extension dev`                         | Start dev server with HMR                              |
+| `/extension build`                       | Build for production                                   |
+| `/extension-add sidebar react`           | Add a feature surface to existing project              |
+| `/extension-debug https://example.com`   | Inspect live DOM, console, content scripts             |
+| `/extension-publish both`                | Prepare zips and checklist for Chrome + Firefox stores |
+
+Claude Code will automatically pick up the instructions and know how to:
+
+- Browse the template catalog via `templates-meta.json`
+- Scaffold extensions with `npx extension create --template=<slug>`
+- Read example source from the catalog to learn patterns
+- Work with the `manifest.json` cross-browser format
+- Run dev/build/preview commands
+- Handle Chromium vs Firefox differences
+
+## How it connects to the examples repo
+
+The [examples repo](https://github.com/extension-js/examples) publishes `templates-meta.json` as a nightly release asset. This file is the single source of truth for:
+
+- **CLAUDE.md** — references it so Claude knows all available templates
+- **MCP tools** — `extension_list_templates` fetches and queries it at runtime
+- **`extension create`** — resolves template slugs to repo URLs via the same naming convention
+
+When a new template is added to the examples repo, all three layers pick it up automatically.
+
+## License
+
+MIT