@extension.dev/mcp 10.10.8 → 10.10.10

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "extension-mcp",
       "source": "./",
       "description": "MCP tools for browser extension development: scaffold from 50+ templates, run the dev server with HMR, inspect the live DOM and logs, and publish store-ready builds for Chrome, Edge, and Firefox.",
-      "version": "10.10.8",
+      "version": "10.10.10",
       "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 50+ 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": "10.10.8",
+  "version": "10.10.10",
   "author": {
     "name": "Cezar Augusto",
     "email": "hello@extension.dev",

package/CHANGELOG.md

@@ -1,5 +1,137 @@
 # Changelog
 
+## 10.10.10
+
+Every sentence the server says is now backed by something it read
+(BUGS_TO_FIX_MCP.md entries 45 to 112, two audits of 2026-10-05: a claims
+census of about 2,030 sentences and a fixture sweep against the pinned
+engine and the platform).
+
+- Success is read, never assumed. Promote, submit, publish, project and
+  workspace create, logout and uninstall read the platform's or the
+  library's own answer and say `promoted-partially`, `submit-unconfirmed`,
+  `publish-unconfirmed`, `create-unconfirmed`, `not-installed` and the like
+  when it falls short. A failed read is reported as unreadable, never as an
+  empty list, across eval, open, the tab polls, session markers and
+  carriers.
+- One resolver returns the token and the project it belongs to. An
+  unnamed call sends `EXTENSION_DEV_TOKEN` and takes its project from the
+  token's own claims, never from whichever stored login is active; a named
+  project sends its stored login first, the private registry grant
+  included.
+- `extension_manifest_validate` judges each browser through the engine's
+  own prefix filter, checks every requested browser's references, refuses
+  an unknown target, and blocks only where the engine or the browser
+  refuses (a `service_worker` the engine rewrites for Firefox is a
+  warning).
+- `extension_build` reads `zip_artifacts`, refuses a stale dist, reports a
+  timeout as `build-timeout`, uses the engine's own bundle-id rule, and
+  writes `firefox-based` builds where the engine does (`dist/gecko-based`).
+- `extension_inspect` names the document it read after navigating, counts
+  uncaught exceptions as console errors, reports a section that threw as
+  `failedSections` instead of an empty value, and marks every cap.
+- `extension_open` checks popup, options and sidebar against the manifest
+  before asking the engine, says when an open could not be confirmed, and
+  never counts a tab it rendered itself as the window.
+- `extension_storage` reads a set back; `context` is gone, since the engine
+  runs every storage call in the background.
+- `extension_assert` counts only the extension's own log lines, reads the
+  guest's id from the contract, compares storage values structurally, and
+  does not credit a background the dev build injected.
+- `extension_stop` with `all` leaves sessions owned by another running
+  server alone unless `includeOtherServers` is true; stop and auth are
+  marked destructive.
+- `extension_dev` reports the control channel from `ready.json`, and a boot
+  error that is not a compile error answers `boot-failed`.
+- The tool reference `claude/rules/mcp-tools.md` is generated from the
+  schemas, and a test validates every example call in the docs against
+  them.
+- Requires Node 22.12 or later, the floor of the engine this package runs
+  in-process.
+- The release workflow publishes to npm before it pushes the version
+  commit and tag, so a failed publish no longer strands a tag.
+
+## 10.10.9
+
+- One approval now covers several projects in one workspace
+  (BUGS_TO_FIX_MCP.md entry 27). Onboarding ten projects used to cost
+  twenty visits to extension.dev/device, one to create each project and
+  one to sign in to it, and the ten tokens then expired together and cost
+  ten more. This release is the client half and waits on the platform
+  deploy that accepts a list. The platform advertises the capability as
+  `batchOnboarding` in its login config; against a platform that does
+  not, both inputs below refuse the list before a device code is spent
+  and name the one-project call to use instead.
+- `extension_project_create` takes `projects`, a list of
+  `{ project, repo }` entries in one workspace, in place of `project` and
+  `repo`. The approval page lists every name. Each project is created by
+  its own request and its 7-day token is stored as that project's login,
+  so no `extension_auth` call follows. An entry may carry its own
+  `displayName`, `description`, `installCommand`, `buildCommand`,
+  `outputDirectory`, `browsers` and `outputDirectories`; the same inputs
+  at the top level are the default for entries that leave them out.
+- The answer has one row per project: created and logged in, created
+  with no token (the hint names the batch login to run), refused with the
+  platform's own code, unconfirmed when a request got no answer, or not
+  attempted. A refusal about one project (a name taken, a reserved slug)
+  does not stop the list. A refusal about the approval (an expired grant,
+  the hourly limit, the plan's project limit, a missing GitHub App
+  installation) stops it, and every project not reached still gets a row
+  saying so.
+- A list takes a few calls: creating a project is slow, so while
+  projects remain the answer is `status: "creating"` with the same
+  `deviceCode` to call again. The provisioning grant is held in the
+  server's memory for its 15 minutes and is never written to disk or
+  returned; if the server restarts mid-list the projects already created
+  stay created and the rest need a new approval.
+- One approval creates at most 10 projects, because the platform creates
+  at most 10 per hour for one approving account; the next 10 can start
+  in a new call once that limit allows. The cap is read from the
+  platform's login config (`createProjectsPerApproval`), with 10 as the
+  fallback when the platform states no usable number. A longer create
+  list is refused before any approval is asked for, with that reason; it
+  is never split silently.
+- `extension_auth` with `action: "login"` takes `projects`, a list of up
+  to 20 `<workspace>/<project>` names of existing projects in one
+  workspace (the platform's `loginProjectsPerApproval`), in place of
+  `project`. One approval stores one token per
+  project, which is also how a set of logins that expire together is
+  renewed. One missing project refuses the whole list and stores
+  nothing. The call that completes a batch login can take up to a
+  minute.
+- Both lists are checked before a device code is spent, by the
+  platform's own rules: one workspace, 1 to 20 names, no name twice, and
+  each project by its exact slug (lowercase letters and digits joined by
+  single dashes, at most 48 characters). The refusal names the entry.
+- A batch login or create does not change which login is the default.
+  A single login still does.
+- A server started with `--project` refuses a list that names any other
+  project, the same refusal a single call gets, and takes a list of the
+  pinned project alone. A list on `logout` or `status` is refused rather
+  than ignored.
+- `extension_project_create` no longer lists `project` and `repo` as
+  required in its schema, since a list replaces them. A call with
+  neither form is still refused, by the tool.
+- `extension_publish` with `project` now describes the project it was
+  called for (BUGS_TO_FIX_MCP.md entry 44). The token was already picked
+  by `project`, but `registryUrl`, and the build index behind a missing
+  `buildSha`, `version` or `builtAt`, came from the most recent login, so
+  with several logins stored a publish for one project could return
+  another project's registry address and fill its build details from
+  another project's builds. The same slip is fixed in
+  `extension_release_promote` (the builds page, the channel list and the
+  public URLs it returns) and in the `extension_submit` dry run (the
+  console page it names). `extension_shares` and `extension_preview_web`
+  were checked and did not have it.
+- A private project's registry data is read with the login stored for
+  that project. It used to be asked with the most recent login, which
+  gave up on a mismatch and reported the builds as missing.
+- `extension_release_status` reads a `project` given as
+  `<workspace>/<project>`, the form every other tool takes. It used to
+  join the pair to the active login's workspace and ask the registry for
+  an address that names no project, which is also what a server started
+  with `--project` sent on every call.
+
 ## 10.10.8
 
 - On Firefox, `extension_eval` now reads an extension whose content
@@ -33,7 +165,7 @@
   of an extension whose policy forbids eval. Use `context: "page"` or
   `extension_dom_snapshot` there.
 
-- `extension_submit` and `extension_store_status` link to the console's
+- `extension_submit` and `extension_release_status` (include: ["stores"]) link to the console's
   Submissions tab at `/<workspace>/<project>/submissions`, where the page
   moved; the old `/stores` address still redirects. `@extension.dev/urls`
   moves to `^0.8.2`, which carries the new paths.

package/README.md

@@ -29,7 +29,7 @@ These tools give agents eyes on the live browser, so they debug from evidence in
 - **Run** the dev server with HMR in Chrome, Edge, Firefox, Brave, Opera, Vivaldi, Yandex, Waterfox, LibreWolf, Zen, Floorp, or any Chromium- or Gecko-based binary, plus Safari on macOS (no HMR yet), no build config
 - **See** the live DOM, unified logs from every extension context, `chrome.storage` contents, and the loaded-extension list
 - **Act**: evaluate code in any context, trigger the action button and commands, reload the extension, replay events
-- **Ship**: validate the manifest cross-browser, build for production, publish a shareable preview, and promote builds to release channels headlessly
+- **Ship**: validate the manifest cross-browser, build for production, publish a shareable preview, and promote builds to release channels (a stable promotion asks for a human approval first)
 
 Built on [Extension.js](https://extension.js.org), the open-source cross-browser extension framework.
 
@@ -146,8 +146,8 @@ npx @extension.dev/mcp login --project <workspace>/<project>
 
 Two flags (or environment variables) narrow the server before an agent sees it:
 
-- `--features=local` exposes only the tools that work on this machine (create, run, inspect, build), which also cuts the tool list by about 40%. `--features=platform` exposes only the extension.dev account, share, release and store tools. Both are on by default. Env: `EXTENSION_DEV_FEATURES`.
-- `--no-ship` keeps everything that stays on this machine and refuses every call that reaches other people: `extension_publish`, `extension_release_promote`, `extension_submit` with `dryRun: false`, `extension_preview_web` with `share: true`, and a share revoke. Dry runs and share listing still work. Env: `EXTENSION_DEV_NO_SHIP=1`.
+- `--features=local` exposes the tools that work on this machine (create, run, inspect, build, plus docs search), which leaves 23 of the 32 tools (the 9 platform tools are off). `--features=platform` exposes only the extension.dev account, share, release and store tools. Both are on by default. Env: `EXTENSION_DEV_FEATURES`.
+- `--no-ship` refuses the calls that put something in front of other people: `extension_publish`, `extension_release_promote`, `extension_submit` with `dryRun: false`, `extension_preview_web` with `share: true`, and a share revoke. Dry runs, share listing, login and project or workspace creation still work. Env: `EXTENSION_DEV_NO_SHIP=1`.
 
 A refused call answers `E_TOOL_DISABLED` with the flag to change.
 
@@ -217,17 +217,17 @@ cp node_modules/@extension.dev/mcp/claude/commands/*.md ~/my-extension/.claude/c
 | act | `extension_reload` | Reload extension or tab |
 | act | `extension_open` | Open a surface (popup, options, sidebar, devtools panel, override pages) / trigger `action`, `command` |
 | browsers | `extension_browsers` | Detect, list, install, and uninstall browsers |
-| platform | `extension_auth` | Device login at extension.dev, plus login status and logout |
+| platform | `extension_auth` | Device login at extension.dev for one project or a list of them, plus login status and logout |
 | platform | `extension_workspace_create` | Create an extension.dev workspace, headless, via device approval; the approver becomes its owner |
-| platform | `extension_project_create` | Create the extension.dev project for a built extension, headless, via device approval |
+| platform | `extension_project_create` | Create the extension.dev project for a built extension, or several under one approval, headless, via device approval |
 | platform | `extension_preview_web` | Render a build in the web emulator, and share it as a link |
 | platform | `extension_shares` | List every link you have shared, and revoke one permanently |
-| platform | `extension_publish` | Publish a shareable preview to extension.dev |
+| platform | `extension_publish` | Mint a shareable link for a build extension.dev already holds (nothing is uploaded) |
 | platform | `extension_release_promote` | Promote a build to a release channel, headless |
-| platform | `extension_submit` | Submit for store review: Chrome, Firefox and Edge, through extension.dev |
+| platform | `extension_submit` | Submit for store review: Chrome, Firefox, Edge and Safari, through extension.dev |
 | platform | `extension_release_status` | Read release channels, recent builds, and store submission and review state |
 
-Browser-launching tools (`dev`, `start`) 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`) 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; build, doctor, eval, storage, reload, open, dom_snapshot and assert spawn that CLI too, and the rest runs in-process.
 
 ## Asserting instead of guessing
 
@@ -286,8 +286,8 @@ and `extension_open` with `url` cannot open one on Safari: the bridge
 navigates through a background eval, and Safari's MV3 background CSP blocks
 eval, which also blocks `extension_eval` in `background`. Open the page in
 Safari by hand, then read it. Safari has no CDP or RDP, so
-`extension_inspect` has no Safari path and `surface-rendered` answers
-inconclusive, pointing at `extension_dom_snapshot` with a `context`.
+`extension_inspect` has no Safari path; `surface-rendered` reads the
+surface through the relay there and can pass or fail.
 
 Safari 27 and Safari Technology Preview 247 also ship Apple's own MCP server
 inside `safaridriver` (enable Safari > Settings > Developer > "Allow remote
@@ -314,6 +314,8 @@ That is a different job from shipping. Use `share` for the build you are holding
 
 The platform tools connect agents to [extension.dev](https://extension.dev): `extension_auth` runs extension.dev's own device flow (you approve the code at [extension.dev/device](https://extension.dev/device), and GitHub is federated server-side, so no GitHub token ever reaches your machine) and stores a project-scoped token locally (never returned to the agent), `extension_publish` turns a build your project has already published into a shareable URL, and `extension_release_promote` promotes a tested build to a release channel from CI or an agent session, no browser required. `extension_submit` 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. Safari and the App Store are one paid lane on the platform, so a free workspace is refused there and the other three stores are unaffected. The two verbs are not interchangeable: `extension_publish` pushes to the extension.dev platform, `extension_submit` sends the build into a store's review queue, which is irreversible. After a real submission, `extension_release_status` reads the recorded outcome, per-store credential health, and review state from the project's public registry, so agents and CI can answer "was it approved?" without a console visit. Access tokens live at most 7 days; CI pipelines re-mint them from the console's Access tokens page.
 
+Onboarding several extensions at once costs one approval, not two per project. `extension_project_create` takes `projects`, a list of `{ project, repo }` entries in one workspace, in place of `project` and `repo`: the approval page at extension.dev/device lists every name, each project is created by its own request, and each one's 7-day token is stored as that project's login. `extension_auth` with `action: "login"` takes `projects`, a list of `<workspace>/<project>` names of existing projects, and stores one token per project, which is also how logins that expire together are renewed. Both lists are checked before a device code is spent: one workspace, 1 to 20 names, each by its exact slug (lowercase letters and digits joined by single dashes, at most 48 characters), none twice. A create list is capped at 10, because the platform creates at most 10 projects per hour for one approving account; a longer one is refused with that reason rather than split, and the next 10 can start in a new call once that limit allows. The platform states both caps, and that it takes a list at all, in its login config; a list sent to a platform that does not advertise it is refused before a device code is spent. Creating takes a few calls: while projects remain the answer is `status: "creating"` with the same `deviceCode` to call again, and the answer always carries one row per project, so a refusal on one never hides the others. A server pinned with `--project` refuses a list that names any other project.
+
 ## The extension.dev stack
 
 | Package | Use it to |

package/claude/ARCHITECTURE.md

@@ -14,7 +14,7 @@ examples repo (GitHub)
          │
          ├── templates-meta.json        Auto-generated registry (all templates, structured)
          │     Generated by: scripts/generate-templates-meta.mjs
-         │     Published as: GitHub release asset (nightly tag)
+         │     Published at media.extension.land/templates/latest.json, with a pinned examples commit as fallback
          │     Contains: slug, surfaces, framework, permissions, files, downloads, integrity
          │     File paths are repo-relative: examples/<slug>/...
          │
@@ -24,19 +24,19 @@ examples repo (GitHub)
 
 ## Three integration layers
 
-### Layer 1: sidebar-claude template
+### Layer 1: ai-claude template
 
-**Location:** `examples/sidebar-claude/`
+**Location:** `examples/ai-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
+npx extension create my-bot --template=ai-claude
   │
   ▼
-Resolves → https://github.com/extension-js/examples/tree/main/examples/sidebar-claude
+Resolves → https://github.com/extension-js/examples/tree/main/examples/ai-claude
   │
   ▼
 go-git-it clones → copies to ./my-bot/ → installs deps → done
@@ -44,10 +44,10 @@ 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`
+- `generate-templates-meta.mjs` auto-discovers it by scanning `examples/ai-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
+- CI builds it for Chrome/Edge/Firefox, packages as `.zip`, publishes it to media.extension.land
 - `templates-meta.json` includes download URLs with SHA256 integrity
 
 ### Layer 2: Claude Code rules (CLAUDE.md)
@@ -76,7 +76,7 @@ Claude now knows:
 - 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
+- Documents the download URL pattern for pre-built distributions
 - Teaches how to contribute new templates (template.meta.json format, generator script)
 
 ### Layer 3: MCP tools
@@ -91,19 +91,19 @@ Claude (via MCP) calls extension_templates({ surface: "sidebar", tags: ["ai"] })
 MCP server fetches templates-meta.json (cached, 1hr TTL)
   │
   ▼
-Returns: [{ slug: "sidebar-claude", ... }, { slug: "sidebar-transformers-js", ... }]
+Returns: [{ slug: "ai-claude", ... }, { slug: "transformers-js", ... }]
   │
   ▼
-Claude calls extension_templates({ action: "source", slug: "sidebar-claude", files: ["src/manifest.json", "src/lib/claude.ts"] })
+Claude calls extension_templates({ action: "source", slug: "ai-claude", files: ["src/manifest.json", "src/lib/client.ts"] })
   │
   ▼
-MCP server fetches from https://raw.githubusercontent.com/extension-js/examples/main/examples/sidebar-claude/<file>
+MCP server fetches the file at the pinned examples commit
   │
   ▼
 Claude reads the source, understands the pattern, adapts it for the user
   │
   ▼
-Claude calls extension_create({ projectName: "my-bot", template: "sidebar-claude" })
+Claude calls extension_create({ projectName: "my-bot", template: "ai-claude" })
   │
   ▼
 MCP server calls extensionCreate() → same go-git-it flow as CLI
@@ -151,7 +151,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 `ai-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

@@ -41,7 +41,7 @@ The extension.dev platform ships 50+ templates in the [examples](https://github.
 
 ```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}'
+curl -sL https://media.extension.land/templates/latest.json | jq '.templates[] | {slug, description, uiFramework, surfaces}'
 ```
 
 **Pre-built distributions** are available for every template:
@@ -121,7 +121,8 @@ npm run preview
 
 # Target a specific browser
 npm run dev -- --browser=firefox
-npm run build -- --browser=chrome,firefox
+npm run build -- --browser=chrome
+npm run build -- --browser=firefox
 
 # Zip for distribution
 npm run build -- --zip
@@ -200,13 +201,13 @@ The `extension_dom_snapshot` MCP tool wraps this verb one-to-one.
 
 **Debugging protocol (Chromium CDP): `extension_inspect` MCP tool.** Connects directly to the running session's debug port. Use it when the bridge is not enough: closed shadow roots (`deepDom`), selector probes, DOM snapshots, console summaries, or navigating the tab to a URL before inspecting. Returns structured events:
 
-- `page_html` - full injected HTML (after content scripts run)
-- `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)
-- `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
+- `html` - full injected HTML (after content scripts run), with `htmlTruncated` when cut
+- `summary` - root/script/style/link counts
+- `meta` - readyState, viewport, frame count
+- `domSnapshot` - structured tree (tag, id, classes, role; `domSnapshotTruncated` names the cap)
+- `console` - error/warn counts + top unique messages
+- `probes` - per-selector element counts and samples
+- `extensionRoots` - extension root elements with reinject generations
 
 ### Unified logging (`--logs`)
 
@@ -229,7 +230,7 @@ npm run dev -- --logs info --log-url "example.com"
 ### Other debugging tools
 
 - Use `--browser=firefox` to test cross-browser compatibility
-- **Safari (macOS).** On Extension.js 4.1.28 or newer, `--browser=safari` builds the app, opens it, and after you enable the extension in Safari > Settings > Extensions it reloads on every save through the extension's bridge and streams background and content lines into the session log. Start it with `allowEval: true` and the bridge tools work: `extension_storage`, `extension_reload`, `extension_open` for surfaces, `extension_dom_snapshot` by tab id, `extension_logs`, and the assertions except `surface-rendered`. `extension_eval` in `content` or `page` needs a tab already open at the url, which you open in Safari by hand: `extension_open` with `url` and `extension_eval` in `background` are blocked by Safari's MV3 background CSP, and the engine says so. Safari has no CDP or RDP, so `extension_inspect` has no Safari path. Apple's Safari MCP server (`claude mcp add safari-mcp -- "/usr/bin/safaridriver" --mcp`, Safari 27+, after enabling Safari > Settings > Developer > "Allow remote automation and external agents") reads a page in its own isolated window with no extension-aware tool, and runs beside a dev session, since this server opens no automation session of its own.
+- **Safari (macOS).** On Extension.js 4.1.28 or newer, `--browser=safari` builds the app, opens it, and after you enable the extension in Safari > Settings > Extensions it reloads on every save through the extension's bridge and streams background and content lines into the session log. Start it with `allowEval: true` and the bridge tools work: `extension_storage`, `extension_reload`, `extension_open` for surfaces, `extension_dom_snapshot` by tab id, `extension_logs`, and the assertions (`surface-rendered` reads the surface through the relay there). `extension_eval` in `content` or `page` needs a tab already open at the url, which you open in Safari by hand: `extension_open` with `url` and `extension_eval` in `background` are blocked by Safari's MV3 background CSP, and the engine says so. Safari has no CDP or RDP, so `extension_inspect` has no Safari path. Apple's Safari MCP server (`claude mcp add safari-mcp -- "/usr/bin/safaridriver" --mcp`, Safari 27+, after enabling Safari > Settings > Developer > "Allow remote automation and external agents") reads a page in its own isolated window with no extension-aware tool, and runs beside a dev session, since this server opens no automation session of its own.
 - 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)

package/claude/README.md

@@ -12,13 +12,13 @@ claude/
   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-add.md      /extension-add: plan a sidebar, popup, content script, etc. (the tool writes no files)
     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
+    mcp-tools.md          MCP tool reference, generated from the server's schemas (pnpm docs:tools)
   examples/
     create-extension.md   Example prompt: scaffold and customize an extension
     add-sidebar.md        Example prompt: add a sidebar panel to an existing extension
@@ -59,7 +59,7 @@ Claude Code will automatically pick up the instructions and know how to:
 
 ## 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:
+The template catalog (`templates-meta.json`) is read from `media.extension.land/templates/latest.json` first and from a pinned commit of the [examples repo](https://github.com/extension-js/examples) as the fallback, with a bundled snapshot when neither answers. It is the single source of truth for:
 
 - **CLAUDE.md**, references it so Claude knows all available templates
 - **MCP tools**, `extension_templates` fetches and queries it at runtime
@@ -69,4 +69,4 @@ When a new template is added to the examples repo, all three layers pick it up a
 
 ## License
 
-MIT
+Apache-2.0

package/claude/commands/extension-debug.md

@@ -33,7 +33,7 @@ Debug the currently running extension dev session. The user said: $ARGUMENTS
 
    To see what else is loaded in the browser (Chromium): `extension_list_extensions`.
 
-   **Safari sessions** (Extension.js 4.1.28+) have no CDP, but the bridge works once the extension is enabled in Safari: `extension_logs`, `extension_storage`, `extension_reload`, `extension_open` for surfaces, `extension_dom_snapshot` by tab id, and the assertions except `surface-rendered`. `extension_eval` in `content` or `page` needs a tab the user already opened at the url; `extension_open` with `url` and `extension_eval` in `background` are blocked by Safari's MV3 background CSP. `extension_inspect` has no Safari path. Apple's `safari-mcp` can read a page in its own window beside the dev session; neither it nor this server can open the popup or background page, which stay Web Inspector, attended.
+   **Safari sessions** (Extension.js 4.1.28+) have no CDP, but the bridge works once the extension is enabled in Safari: `extension_logs`, `extension_storage`, `extension_reload`, `extension_open` for surfaces, `extension_dom_snapshot` by tab id, and the assertions (`surface-rendered` reads the surface through the relay there). `extension_eval` in `content` or `page` needs a tab the user already opened at the url; `extension_open` with `url` and `extension_eval` in `background` are blocked by Safari's MV3 background CSP. `extension_inspect` has no Safari path. Apple's `safari-mcp` can read a page in its own window beside the dev session; neither it nor this server can open the popup or background page, which stay Web Inspector, attended.
 
 4. **Diagnose common issues**
    Based on what you find, check for:

package/claude/commands/extension-publish.md

@@ -22,7 +22,7 @@ Default to `chrome` and `firefox`. `all` means chrome, firefox, edge and safari.
    - Firefox: a missing `browser_specific_settings.gecko.data_collection_permissions` declaration, which AMO now requires for new add-ons and updates
    - a bundle over 10 MB, source maps in the production build, missing 128px icon
 
-4. **Pick the build to submit.** Store review runs from a build on extension.dev, not from local files. Call `extension_release_status` with `include: "releases"` to find the sha. If the user has not shipped this version yet, say so and offer `extension_publish` first.
+4. **Pick the build to submit.** Store review runs from a build on extension.dev, not from local files. Call `extension_release_status` with `include: ["releases"]` to find the sha. If no build of this version is listed, say so: a build comes from a push to the project's repository (the platform builds it), not from `extension_publish`, which only shares a build that already exists.
 
 5. **Rehearse.** Call `extension_submit` with the browsers and `buildSha`, leaving `dryRun` at its default (`true`). Show the per-store credential rows. A store whose credentials are not healthy is fixed in the extension.dev console (the response names the page); drop it from `browsers` or stop.
 

package/claude/commands/extension.md

@@ -12,7 +12,7 @@ Parse the user's intent from `$ARGUMENTS` and execute the matching action:
 ### "create <name>" or "new <name>", Scaffold a new extension
 
 1. If MCP tool `extension_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}'`
+2. If not, check the template catalog: `curl -sL https://media.extension.land/templates/latest.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`
 

package/claude/rules/cross-browser.md

@@ -70,8 +70,8 @@ Older Firefox ignores the `chromium:world` field and runs in the default isolate
 ## API differences
 
 - Chromium: use `chrome.*` namespace for Chrome-specific APIs (sidePanel, etc.)
-- Firefox: use `browser.*` namespace (auto-polyfilled by the framework)
-- For cross-browser code: use `browser.*` when possible, the polyfill maps it to `chrome.*` on Chromium
+- Firefox: `browser.*` is native; `chrome.*` also works there for most APIs
+- For cross-browser code: the polyfill that maps `browser.*` to `chrome.*` on Chromium is on for `extension_dev` and `extension_start` by default and OFF for `extension_build` (pass `polyfill: true` to the build, or write `chrome.*` and check `typeof browser` yourself)
 
 ## Testing across browsers
 
@@ -82,5 +82,6 @@ npm run dev -- --browser=firefox
 npm run dev -- --browser=edge
 
 # Build for multiple browsers
-npm run build -- --browser=chrome,firefox
+npm run build -- --browser=chrome
+npm run build -- --browser=firefox
 ```