@extension.dev/mcp 4.8.0 → 5.1.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "extension-mcp",
       "source": "./",
       "description": "MCP tools for browser extension development: scaffold from 60+ templates, run the dev server with HMR, inspect the live DOM and logs, and publish store-ready builds for Chrome, Edge, and Firefox.",
-      "version": "4.8.0",
+      "version": "5.1.0",
       "category": "development",
       "author": {
         "name": "Cezar Augusto"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "extension-mcp",
   "description": "MCP tools for browser extension development: scaffold from 60+ templates, run the dev server with HMR, inspect the live DOM and logs, and publish store-ready builds for Chrome, Edge, and Firefox. Ships /extension, /extension-add, /extension-debug, and /extension-publish commands.",
-  "version": "4.8.0",
+  "version": "5.1.0",
   "author": {
     "name": "Cezar Augusto",
     "email": "boss@cezaraugusto.net",

package/CHANGELOG.md

@@ -1,5 +1,183 @@
 # Changelog
 
+## 5.1.0
+
+The engine closed its entire open bug range (Extension.js 61-73) in the
+4.0.14 canary line. This release re-aligns the MCP with the fixed engine,
+finishes the MCP-side half of those bugs, and continues the
+report-failure-not-false-success program that 5.0.0 started. 5.0.0 was never
+published to npm; installing 5.1.0 picks up both.
+
+### Fixed
+
+- **Sessions now genuinely survive the MCP process.** `detached: true` alone
+  never did it: the child held pipes to the MCP, so when the MCP exited the
+  next compile log line killed the dev server with EPIPE. Launch tools
+  (`extension_dev`/`start`/`preview`) now stream the child's output to a
+  session log file (returned as `logPath`) instead of pipes. A detached
+  session outlives the MCP and a fresh MCP process rediscovers it through
+  `ready.json` and can stop it. Pinned by a detach-contract test.
+- **`extension_preview` no longer reports `launched` for a process that died
+  in seconds.** It health-checks the child like `dev`/`start` (the MCP half of
+  engine bug 72), and all three launch tools read the engine's new
+  `browser_exited` stamp, so a browser that dies after launch (for example a
+  rejected add-on) returns `status:"browser-exited"` instead of success.
+- **`extension_doctor` names a dead browser.** A `browser_exited` ready
+  contract now produces a runtime-errors failure that says the browser died,
+  with the matching remedy, instead of the generic "fix the build error"
+  wording that pointed at a build that was fine.
+- **`extension_create` verifies the scaffold.** A resolved create over a
+  partial tree (an interrupted template download) returned `nextSteps`
+  pointing at a project that could not compile. It now checks the manifest
+  exists and returns `status:"incomplete"` when it does not.
+- **`extension_manifest_validate` is per-target honest.** `chromium:`/
+  `firefox:` prefixed keys resolve per target, `edge` joins the default
+  matrix, `manifest_version` must be 2 or 3, a `default_locale` without its
+  `_locales` catalog blocks, and a missing 128px store icon warns
+  (`extension_inspect` reports `has128Icon`).
+- **Stale state stops being served as live.** `extension_logs` stamps
+  `stale:true` when the producing session is dead or from a different run;
+  `extension_wait` returns `runtimeErrors` alongside ready instead of a bare
+  green over a crashing worker; `extension_build` reports
+  `productionDivergence` when the production manifest lost permissions or
+  resources relative to source.
+- **`extension_open`'s `asTab` fallback fires on the user-gesture wall**, and
+  `extension_storage` set without a `key` answers in MCP vocabulary rather
+  than CLI flags.
+
+### Added
+
+- **Structured bundler warnings on `extension_build`.** The engine now
+  persists its build summary to `dist/extension-js/<browser>/
+  build-summary.json` (the transport half of engine bug 73), and the tool
+  returns it as `buildWarnings` (with `buildWarningsTruncated` naming the
+  true count when the engine capped the list). Older engines simply omit the
+  field; nothing is scraped from stdout.
+- **Popup-faithful headless rendering.** A popup rendered as a tab is now
+  sized like the real popup: the document's content size is measured over
+  CDP, clamped to Chrome's 25x25-800x600 popup bounds, and the window is
+  resized to it (reported as `renderedAsTab.popupBounds`). If the browser
+  does not verifiably honor the resize, the tool keeps saying "no popup
+  sizing" instead of implying fidelity. Note headless-new is one such
+  browser: it accepts `Browser.setWindowBounds` and changes nothing, so
+  headless sessions get the honest fallback, not a resized window. The
+  measurement also leaves `body`'s authored width alone; only the root takes
+  the temporary fit-content override, so a popup that sizes itself through
+  `body { width }` measures at its real width.
+- **CI typechecks the tests.** `pnpm typecheck` covers `src/` and the test
+  tsconfig, wired into the CI matrix, so type drift between tools and their
+  tests cannot accumulate silently again.
+
+### Changed
+
+- **Tool prose caught up with the fixed engine.** `extension_eval` and
+  `extension_dom_inspect` now advertise the surface contexts
+  (`popup`/`options`/`sidebar`/`devtools`) and override pages
+  (`newtab`/`history`/`bookmarks`) the engine's relay serves, needing no tab
+  id. The "content eval is known-broken" guard is version-honest: on
+  Extension.js >= 4.0.14 a null is the expression's real result, and the note
+  says so instead of condemning a repaired path. Firefox hints name every
+  working route.
+
+A pass focused on a single question: when something has gone wrong, does the
+tool say so? Five tools were reporting success over a failure. All five now
+verify before they claim anything.
+
+### Breaking
+
+- **`extension_build` refuses a broken build.** It runs the
+  `extension_manifest_validate` checks as a preflight and returns
+  `status:"blocked"` on build-blocking errors instead of shelling out to a build
+  it knows is broken. Pass `skipValidation: true` for the old behavior. It also
+  returns `success:false` with `status:"incomplete"` when the bundler exits 0 but
+  a declared entrypoint never reached `dist/`, because the browser refuses to
+  load that artifact. Non-blocking findings ride along as `manifestWarnings`.
+- **Browser resolution defaults to `chrome`, not `chromium`.** A dead session
+  used to fall through to a blind default, so every call after a dev server
+  exited silently retargeted a browser the caller never ran. A dead session now
+  resolves to its own browser with `source:"stale"`.
+- **`extension_open` renames `tab` to `target`.** The value is a CDP target id,
+  not a `chrome.tabs` id, and the old name invited callers to pass it straight
+  into tools that need a numeric tab id.
+
+### Fixed
+
+- **`extension_doctor` no longer reports `healthy:true` over a crashing
+  extension.** Its runtime-error check read the wrong field, so every error row
+  in `logs.ndjson` collapsed to an empty string and was skipped. It now reads the
+  engine's `messageParts` payload, with an `errorName`/`stack` fallback, and
+  collapses a throw that repeats on every event.
+- **`extension_dev` and `extension_start` no longer report `status:"started"`
+  for a server that already exited.** Both health-check the child process and
+  return `status:"exited"` with the exit code, signal, and the child's own output
+  as evidence.
+- **`extension_open` no longer reports success for a navigation that failed.**
+  Navigating to a `chrome-extension://` origin is cross process and swaps the
+  render frame, so the pre-navigation session reported a stale error URL on
+  success and success on failure. It now confirms against a fresh target list.
+  This affected the `url` navigation path shipped in 4.9.0, not only the new
+  surface rendering.
+- **`extension_open` targets the right extension.** A dev session also loads
+  Extension.js's own manager extension, and taking the first extension target
+  navigated against the wrong origin. The id is now derived from the dist path
+  the session actually loaded.
+
+### Added
+
+- **Headless surface rendering.** `extension_open` accepts `asTab` for
+  `popup`/`options`/`sidebar`, rendering the surface document in a real tab so it
+  can be inspected where no window exists to host a popup. It is applied
+  automatically when a headless session refuses to open the surface, with a note
+  saying what was substituted.
+- **Tab targeting by url.** `extension_eval` and `extension_dom_inspect` take a
+  `url` and otherwise default to the active tab, and `extension_dom_inspect`
+  gains `listTabs` for discovery. The engine gained this in 4.0.13; the tool
+  descriptions had been telling callers a numeric tab id was required.
+- **Friendlier arguments.** `timeoutMs`, `lines`, `tabId`, `href` and
+  `browserName` fold onto their canonical names, `withConsole` accepts `true`,
+  and the input validator understands union types.
+- **`extension_create` matches your package manager.** Hints and the engine
+  warning now use bun, pnpm or yarn when that is what the scaffold used, and the
+  warning reads the pin the scaffold actually wrote.
+
+## 4.9.0
+
+A second pass from the persona swarm, closing the gaps 4.8.0 left and the top
+new blockers it surfaced.
+
+- **Honest `extension_manifest_validate`.** It now scans the project source for
+  permission-gated `chrome.*`/`browser.*` calls and flags any the manifest does
+  not declare, an API used without its permission is `undefined` at runtime and
+  crashes the context, the exact case where validate used to report `valid:true`.
+  The headline is now honest (`valid:false` + `buildBlocking:true` on any error),
+  and it accepts singular `browser` as an alias for `browsers`.
+- **`extension_open` can navigate a tab.** Pass a `url` (Chromium, via CDP) to
+  drive a content-script test page, a `webNavigation` target, or the popup as a
+  page (`chrome-extension://<id>/popup.html`), the loop the surface-only open
+  could not do. `target` is accepted as an alias for `surface`.
+- **`extension_stop` actually reaps the session.** It now terminates the dev CLI
+  and both browser families (gecko profile + chromium `--load-extension`, under
+  the project's dist) and refuses to report `stopped:true` while any survive.
+- **`extension_wait` won't lie about a dead session.** A `ready.json` whose pid
+  is dead now returns `status:"stale"` instead of `ready`, so you don't walk into
+  a reload/eval that fails with a misleading control-channel error.
+- **Dropped-channel errors name the real cause.** A `1006` / "no control channel"
+  now detects an exited dev server (stale ready.json + dead pid) and says so,
+  instead of asking "is the session started with allowControl?" when it was.
+- **`extension_doctor`** surfaces recent error-level logs as a `runtime-errors`
+  check (so a background throwing on every event isn't `healthy:true`), keeps the
+  project-local engine version in project mode, and flags when that engine
+  differs from a pinned `EXTENSION_MCP_CLI_VERSION`.
+- **`extension_build`** lists declared entrypoints in its success output, so a
+  content script no longer reads as "didn't build".
+- **`extension_create`** forces non-interactive git (`GIT_TERMINAL_PROMPT=0`) so a
+  credential prompt can't hang the template download, retries once on a transient
+  network/timeout failure (cleaning the partial dir first), reports a download
+  failure as such instead of "choose a valid template name", and warns when the
+  scaffold's `extension@latest` pin will win over your pinned CLI.
+- Eval/inspect error guidance now speaks MCP JSON args (`context`, `tab`, `url`)
+  instead of CLI flags.
+
 ## 4.8.0
 
 Dev-session ergonomics hardened from a 30-persona agent walk of the toolchain.
@@ -146,12 +324,12 @@ that removed nearly all friction a real MCP client hit.
   --browser=chromium --allow-control` `` becomes `extension_dev with
   { browser: "chromium", allowControl: true }`, and stray
   `--allow-control` / `--allow-eval` / `--browser=<x>` mentions become
-  their tool-argument names. Result data is never touched — only
+  their tool-argument names. Result data is never touched, only
   error/hint prose. Tool descriptions now name `allowControl` /
   `allowEval` directly, so agents no longer discover the gates by
   fuzzing the schema.
 - The no-channel error now names the session that IS running ("Active
-  session browser(s) for this project: chrome — pass that as `browser`"),
+  session browser(s) for this project: chrome, pass that as `browser`"),
   so an agent retargets instead of spawning a second, conflicting
   session. Same for the `extension_logs` follow miss.
 - `extension_list_extensions` / `extension_source_inspect` accept
@@ -187,7 +365,7 @@ Session lifecycle + determinism release. Tool count 27 -> 28.
 - CLI spawns are deterministic: dev/start/preview and the act tools now
   prefer the project's own `node_modules/.bin/extension`, falling back to
   `npx extension@<pinned>` where the pin derives from the vendored
-  `extension-develop` version — never a floating `latest`.
+  `extension-develop` version, never a floating `latest`.
 - Session registry keys are path-normalized, so a stop with an absolute
   path matches a session registered with a relative one.
 - Tests: registry suite now asserts against the exported `tools` array
@@ -262,9 +440,9 @@ this release graduates that line to stable and becomes `latest`.
   @extension.dev/skill pairing.
 - MIT license shipped; repository moved to extensiondev/mcp.
 
-# @extension.dev/mcp — Changelog
+# @extension.dev/mcp, Changelog
 
-## Unreleased — agent-bridge tools
+## 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
@@ -274,32 +452,32 @@ a recent **`extension` CLI that ships the bridge verbs** (`logs`, `eval`,
 
 > ⚠️ **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
+> 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
+- **`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
+- **`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
+- **`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
+- **`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
+- **`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.
 
-## Unreleased — login (auth tools)
+## Unreleased, login (auth tools)
 
 Adds the missing `login` flow so `extension_publish` no longer requires the user
 to mint and export `EXTENSION_DEV_TOKEN` by hand. Auth stays auth-AWARE: the
@@ -307,13 +485,13 @@ token lives in a local credentials file, never in the MCP process state or logs.
 
 New tools (25 total):
 
-- **`extension_login`** — GitHub **device-code** flow (no local server; works
+- **`extension_login`**, GitHub **device-code** flow (no local server; works
   headless). Two-phase: call with `project` (`<workspace>/<project>`) to get a
   code + URL, call again with the returned `deviceCode` to finish. On success it
   writes a project-scoped token to the credentials file. Never returns the token.
-- **`extension_whoami`** — report the stored workspace/project and token expiry
+- **`extension_whoami`**, report the stored workspace/project and token expiry
   without revealing the token.
-- **`extension_logout`** — delete the local credentials file.
+- **`extension_logout`**, delete the local credentials file.
 
 Token resolution for publish is now `EXTENSION_DEV_TOKEN` env **>** the
 credentials file (expired file tokens are ignored).
@@ -323,8 +501,8 @@ Credentials file (versioned, `0600`): `$XDG_CONFIG_HOME/extension-dev/auth.json`
 
 Platform endpoints this depends on (in `apps/www.extension.dev`):
 
-- `GET /api/cli/login/config` — public GitHub OAuth client id + scope.
-- `POST /api/cli/login/exchange` — trades a GitHub **user** token for a
+- `GET /api/cli/login/config`, public GitHub OAuth client id + scope.
+- `POST /api/cli/login/exchange`, trades a GitHub **user** token for a
   project-scoped access token after checking workspace membership. Modeled on
   `/api/oidc/exchange`; tokens are recorded so they stay revocable.
 

package/README.md

@@ -41,7 +41,7 @@ Built on [Extension.js](https://extension.js.org), the open-source cross-browser
 claude mcp add extension-dev npx @extension.dev/mcp
 ```
 
-Or install it as a plugin — the MCP server plus the `/extension`, `/extension-add`, `/extension-debug`, and `/extension-publish` commands in one step:
+Or install it as a plugin, the MCP server plus the `/extension`, `/extension-add`, `/extension-debug`, and `/extension-publish` commands in one step:
 
 ```
 /plugin marketplace add extensiondev/mcp
@@ -123,11 +123,11 @@ cp node_modules/@extension.dev/mcp/claude/commands/*.md ~/my-extension/.claude/c
 | platform | `extension_release_promote` | Promote a build to a release channel, headless |
 | platform | `extension_deploy` | Submit to the Chrome, Firefox, and Edge stores through extension.dev |
 
-Browser-launching tools (`dev`, `start`, `preview`) shell out to the `extension` CLI — the project's own `node_modules/.bin/extension` when present, otherwise `npx extension@<pinned>` at the version this package is verified against; everything else runs in-process.
+Browser-launching tools (`dev`, `start`, `preview`) shell out to the `extension` CLI, the project's own `node_modules/.bin/extension` when present, otherwise `npx extension@<pinned>` at the version this package is verified against; everything else runs in-process.
 
 ## From preview to store
 
-The platform tools connect agents to [extension.dev](https://extension.dev): `extension_login` runs a GitHub device-code flow and stores a project-scoped token locally (never returned to the agent), `extension_publish` turns a build into a shareable preview URL, and `extension_release_promote` promotes a tested build to a release channel from CI or an agent session, no browser required. `extension_deploy` submits a built extension to the Chrome Web Store, Edge Add-ons, and Firefox AMO through extension.dev, which holds your store credentials and dispatches the release from your project's mirror CI — it defaults to a dry run and store credentials are never tool arguments.
+The platform tools connect agents to [extension.dev](https://extension.dev): `extension_login` runs a GitHub device-code flow and stores a project-scoped token locally (never returned to the agent), `extension_publish` turns a build into a shareable preview URL, and `extension_release_promote` promotes a tested build to a release channel from CI or an agent session, no browser required. `extension_deploy` submits a built extension to the Chrome Web Store, Edge Add-ons, and Firefox AMO through extension.dev, which holds your store credentials and dispatches the release from your project's mirror CI, it defaults to a dry run and store credentials are never tool arguments.
 
 ## The extension.dev stack
 

package/claude/ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # 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.
+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
 
@@ -154,7 +154,7 @@ MCP server calls extensionCreate() → same go-git-it flow as CLI
 
 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.
+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.
 

package/claude/CLAUDE.md

@@ -1,4 +1,4 @@
-# extension.dev — Claude Code Instructions
+# 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.
 
@@ -23,11 +23,11 @@ The extension.dev platform ships 60+ templates in the [examples](https://github.
 
 | 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`         | —                |
+| Content script | `content`    | `content-react`  | `content-vue` | `content-svelte` | n/a              |
+| Sidebar        | `sidebar`    | `sidebar-shadcn` | n/a           |, | `sidebar-claude` |
+| Action popup   | `action`     | n/a              |, | n/a              | `action-chatgpt` |
+| New tab        | `new`        | `new-react`      | `new-vue`     | `new-svelte`     | n/a              |
+| Full framework | `javascript` | `react`          | `vue`         | `svelte`         | n/a              |
 
 **When recommending a template:**
 
@@ -56,7 +56,7 @@ A typical extension.dev project:
 ```
 my-extension/
   src/
-    manifest.json          # Required — the source of truth
+    manifest.json          # Required: the source of truth
     background.ts          # Service worker (Chromium) / background script (Firefox)
     content/               # Content scripts
       scripts.tsx
@@ -151,16 +151,16 @@ export default {
 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.
+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
+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
+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:
 
@@ -234,11 +234,11 @@ npm run dev -- --logs info --log-url "example.com"
 
 ### Triggering events without clicking (requires `--allow-control`)
 
-- `extension open action` — fire the toolbar action (opens its popup, or replays `chrome.action.onClicked`).
-- `extension open command --name <cmd>` — replay a `chrome.commands.onCommand` keyboard shortcut.
-- `extension_list_extensions` (MCP tool; no CLI verb) — list extensions with a live context in the browser (Chromium, read-only).
+- `extension open action`, fire the toolbar action (opens its popup, or replays `chrome.action.onClicked`).
+- `extension open command --name <cmd>`, replay a `chrome.commands.onCommand` keyboard shortcut.
+- `extension_list_extensions` (MCP tool; no CLI verb), list extensions with a live context in the browser (Chromium, read-only).
 
-These replay your captured listeners, so they work on Chrome and Firefox — but carry **no user gesture**, so `activeTab` is not granted (the result reports `gesture: false`, plus a `warning` when the manifest declares `activeTab`). If you need a genuine-gesture click (activeTab granted), use [chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp)'s `trigger_extension_action` (Chromium only) alongside this server.
+These replay your captured listeners, so they work on Chrome and Firefox, but carry **no user gesture**, so `activeTab` is not granted (the result reports `gesture: false`, plus a `warning` when the manifest declares `activeTab`). If you need a genuine-gesture click (activeTab granted), use [chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp)'s `trigger_extension_action` (Chromium only) alongside this server.
 
 ## Contributing templates to the examples repo
 

package/claude/README.md

@@ -1,4 +1,4 @@
-# extension.dev — Claude Code Integration
+# 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.
 
@@ -11,10 +11,10 @@ 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
+    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
@@ -61,9 +61,9 @@ Claude Code will automatically pick up the instructions and know how to:
 
 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
+- **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.
 

package/claude/commands/extension-add.md

@@ -7,8 +7,8 @@ Add a new feature surface to the current extension project. The user said: $ARGU
 
 ## Parse arguments
 
-- First argument: feature type — one of: `sidebar`, `popup`, `content-script`, `background`, `newtab`, `options`, `devtools`
-- Second argument (optional): framework — one of: `react`, `vue`, `svelte`, `preact`, `vanilla`. Default: detect from existing project, fall back to `react`
+- First argument: feature type, one of: `sidebar`, `popup`, `content-script`, `background`, `newtab`, `options`, `devtools`
+- Second argument (optional): framework, one of: `react`, `vue`, `svelte`, `preact`, `vanilla`. Default: detect from existing project, fall back to `react`
 
 ## Steps
 
@@ -18,7 +18,7 @@ Add a new feature surface to the current extension project. The user said: $ARGU
    - Detect the framework from existing dependencies in `package.json`
 
 2. **Get the reference pattern**
-   If MCP tool `extension_add_feature` is available, use it — it returns the exact manifest additions, files to create, and reference template.
+   If MCP tool `extension_add_feature` is available, use it. It returns the exact manifest additions, files to create, and reference template.
 
    If MCP tool `extension_get_template_source` is available, read the reference template source to get real implementation patterns.
 
@@ -37,17 +37,17 @@ Add a new feature surface to the current extension project. The user said: $ARGU
 
 4. **Create the files**
    For HTML-based features (sidebar, popup, newtab, options, devtools):
-   - `src/<feature>/index.html` — HTML entry with script tag
-   - `src/<feature>/scripts.tsx` — Framework mount point (or `.ts` for vanilla)
-   - `src/<feature>/styles.css` — Stylesheet
-   - `src/<feature>/<Feature>App.tsx` — Main component (non-vanilla only)
+   - `src/<feature>/index.html`, HTML entry with script tag
+   - `src/<feature>/scripts.tsx`, Framework mount point (or `.ts` for vanilla)
+   - `src/<feature>/styles.css`, Stylesheet
+   - `src/<feature>/<Feature>App.tsx`, Main component (non-vanilla only)
 
    For content scripts:
-   - `src/content/scripts.ts` — Entry point
-   - `src/content/styles.css` — Injected styles
+   - `src/content/scripts.ts`, Entry point
+   - `src/content/styles.css`, Injected styles
 
    For background:
-   - `src/background.ts` — Service worker / background script
+   - `src/background.ts`, Service worker / background script
 
 5. **Handle sidebar specifically**
    If adding a sidebar, also create/update `src/background.ts`:

package/claude/commands/extension-debug.md

@@ -1,5 +1,5 @@
 ---
-description: Debug a running extension — inspect DOM, console, content script injection
+description: Debug a running extension, inspect DOM, console, content script injection
 argument-hint: "[url] [selectors...]"
 ---
 
@@ -25,8 +25,8 @@ Debug the currently running extension dev session. The user said: $ARGUMENTS
 
 3. **Exercise event handlers (when the bug is in an action / command / shortcut)**
    If the session was started with `--allow-control`, fire the events a user would, without clicking:
-   - `extension_open` with `surface: "action"` — triggers the toolbar action (opens its popup, or replays `chrome.action.onClicked`).
-   - `extension_open` with `surface: "command"` and `name: "<cmd>"` — replays a `chrome.commands.onCommand` keyboard shortcut.
+   - `extension_open` with `surface: "action"`, triggers the toolbar action (opens its popup, or replays `chrome.action.onClicked`).
+   - `extension_open` with `surface: "command"` and `name: "<cmd>"`, replays a `chrome.commands.onCommand` keyboard shortcut.
    - Then re-inspect or read `extension_logs` to see what the handler did.
 
    **Caveat:** replay carries no user gesture, so `activeTab` is NOT granted. If the handler depends on `activeTab` (e.g. `chrome.scripting.executeScript` on the active tab, `captureVisibleTab`), the result includes `gesture: false` and a `warning`, and behavior differs from a real click. For a genuine-gesture click (activeTab granted), use chrome-devtools-mcp's `trigger_extension_action` (Chromium only) alongside this server.
@@ -37,16 +37,16 @@ Debug the currently running extension dev session. The user said: $ARGUMENTS
    Based on what you find, check for:
    - **"It didn't load"**: Check extension root count. If 0, content scripts may not be injecting. Check manifest `content_scripts` matches patterns and the target URL.
    - **Console errors**: Report top errors. Common ones:
-     - `Uncaught TypeError` — likely a missing import or wrong module format
-     - `Content Security Policy` — extension CSP blocking inline scripts
-     - `chrome.runtime.lastError` — API permission missing
+     - `Uncaught TypeError`, likely a missing import or wrong module format
+     - `Content Security Policy`, extension CSP blocking inline scripts
+     - `chrome.runtime.lastError`, API permission missing
    - **Wrong page**: Check if the content script `matches` pattern in manifest covers the target URL
-   - **Shadow DOM empty**: Extension root exists but shadow content is empty — likely a CSS or framework mounting issue
+   - **Shadow DOM empty**: Extension root exists but shadow content is empty, likely a CSS or framework mounting issue
 
 5. **Suggest fixes** based on the diagnosis
 
 ## Examples
 
-- `/extension-debug` — inspect the default page target
-- `/extension-debug https://example.com` — inspect a specific URL
-- `/extension-debug https://example.com #my-root .sidebar` — inspect URL and probe selectors
+- `/extension-debug`, inspect the default page target
+- `/extension-debug https://example.com`, inspect a specific URL
+- `/extension-debug https://example.com #my-root .sidebar`, inspect URL and probe selectors

package/claude/commands/extension.md

@@ -9,27 +9,27 @@ You are helping build a browser extension with the extension.dev platform. The u
 
 Parse the user's intent from `$ARGUMENTS` and execute the matching action:
 
-### "create <name>" or "new <name>" — Scaffold a new extension
+### "create <name>" or "new <name>", Scaffold a new extension
 
 1. If MCP tool `extension_list_templates` is available, use it to find the best template matching the user's description (check for surface type, framework, and keywords)
 2. If not, check the template catalog: `curl -sL https://github.com/extension-js/examples/releases/download/nightly/templates-meta.json | jq '.templates[] | {slug, description, uiFramework, surfaces}'`
 3. Run `npx extension@latest create <name> --template=<best-match>`
 4. Report what was created and suggest `npm run dev`
 
-### "dev" or "run" — Start development
+### "dev" or "run", Start development
 
 1. Run `npm run dev` (or `npx extension dev`) in the project root
 2. Tell the user the browser will open with their extension loaded
-3. Mention HMR is active — changes will hot-reload
+3. Mention HMR is active, changes will hot-reload
 
-### "build" — Build for production
+### "build", Build for production
 
 1. Run `npm run build` (or `npx extension build`)
 2. After success, report the output in `dist/chrome/`
 3. If the user mentions "firefox" or "both", also build with `--browser=firefox`
 4. If they mention "zip" or "store", add `--zip`
 
-### "add <feature>" — Add a feature surface
+### "add <feature>", Add a feature surface
 
 1. If MCP tool `extension_add_feature` is available, use it to get the manifest additions and file list
 2. Otherwise, determine what's needed from the feature type:
@@ -40,14 +40,14 @@ Parse the user's intent from `$ARGUMENTS` and execute the matching action:
    - **background**: `background.service_worker` (Chromium) + `background.scripts` (Firefox)
 3. Create the files and update `src/manifest.json`
 
-### "debug" or "inspect" — Debug a running extension
+### "debug" or "inspect", Debug a running extension
 
 1. If MCP tool `extension_source_inspect` is available, use it with `include: ["html", "console", "extension_roots"]`
 2. If there's a URL mentioned, pass it as the target
 3. If there are CSS selectors mentioned, pass them as `probe`
 4. Report: injected HTML, console errors, extension root state
 
-### "validate" — Check manifest for issues
+### "validate", Check manifest for issues
 
 1. If MCP tool `extension_manifest_validate` is available, use it
 2. Otherwise, read `src/manifest.json` and check:
@@ -56,7 +56,7 @@ Parse the user's intent from `$ARGUMENTS` and execute the matching action:
    - Permissions: `sidePanel` present if `side_panel` is declared
    - Background: `service_worker` (Chromium) and `scripts` (Firefox) both present
 
-### "template <query>" — Search for a template
+### "template <query>", Search for a template
 
 1. If MCP tool `extension_list_templates` is available, use it with the query
 2. Otherwise, search the catalog JSON

package/claude/examples/add-sidebar.md

@@ -6,7 +6,7 @@
 
 ## How Claude should approach this
 
-1. **Update manifest.json** — add side panel config for both browsers:
+1. **Update manifest.json**, add side panel config for both browsers:
 
    ```json
    {
@@ -47,7 +47,7 @@
    }
    ```
 
-4. **Create the sidebar UI** — `src/sidebar/index.html`, `src/sidebar/scripts.tsx`, `src/sidebar/styles.css`
+4. **Create the sidebar UI**, `src/sidebar/index.html`, `src/sidebar/scripts.tsx`, `src/sidebar/styles.css`
 
 5. **Test both browsers:**
    ```bash