@extension.dev/mcp 4.6.0 → 4.8.0

package/dist/module.js

@@ -2,17 +2,16 @@ import { __webpack_require__ } from "./rslib-runtime.js";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import node_fs, { existsSync, readdirSync, statSync } from "node:fs";
 import node_path, { join } from "node:path";
 import { extensionCreate } from "extension-create";
-import node_fs, { existsSync, readdirSync, statSync } from "node:fs";
 import node_os from "node:os";
-import { extensionBuild } from "extension-develop";
 import cross_spawn from "cross-spawn";
+import { execFile, execFileSync } from "node:child_process";
 import { filterKeysForThisBrowser } from "browser-extension-manifest-fields";
 import ws from "ws";
 import node_http from "node:http";
 import { extensionInstall, extensionUninstall, getManagedBrowsersCacheRoot } from "extension-install";
-import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 var add_feature_namespaceObject = {};
 __webpack_require__.r(add_feature_namespaceObject);
@@ -35,7 +34,6 @@ __webpack_require__.d(create_namespaceObject, {
 var deploy_namespaceObject = {};
 __webpack_require__.r(deploy_namespaceObject);
 __webpack_require__.d(deploy_namespaceObject, {
-    buildDeployArgs: ()=>buildDeployArgs,
     handler: ()=>deploy_handler,
     schema: ()=>deploy_schema
 });
@@ -201,7 +199,33 @@ __webpack_require__.d(whoami_namespaceObject, {
     handler: ()=>whoami_handler,
     schema: ()=>whoami_schema
 });
-var package_namespaceObject = JSON.parse('{"rE":"4.5.0","El":{"OP":"^4.0.11"}}');
+var package_namespaceObject = JSON.parse('{"rE":"4.7.0","El":{"OP":"^4.0.11"}}');
+function detectPackageManager(projectPath) {
+    const byLockfile = [
+        [
+            "bun.lock",
+            "bun"
+        ],
+        [
+            "bun.lockb",
+            "bun"
+        ],
+        [
+            "pnpm-lock.yaml",
+            "pnpm"
+        ],
+        [
+            "yarn.lock",
+            "yarn"
+        ],
+        [
+            "package-lock.json",
+            "npm"
+        ]
+    ];
+    for (const [lockfile, pm] of byLockfile)if (node_fs.existsSync(node_path.join(projectPath, lockfile))) return pm;
+    return "npm";
+}
 const create_schema = {
     name: "extension_create",
     description: "Create a new browser extension project from a template in the extension.dev template catalog. Use extension_list_templates to see available options.",
@@ -219,7 +243,7 @@ const create_schema = {
             template: {
                 type: "string",
                 default: "typescript",
-                description: "Template slug from the extension.dev template catalog (e.g. 'react', 'sidebar-claude', 'content-vue'). Use extension_list_templates to discover options."
+                description: "Template slug from the extension.dev template catalog (e.g. 'react', 'ai-claude', 'content-vue'). Use extension_list_templates to discover options."
             },
             install: {
                 type: "boolean",
@@ -235,30 +259,47 @@ const create_schema = {
 async function create_handler(args) {
     const start = Date.now();
     const projectInput = args.parentDir ? node_path.resolve(args.parentDir, args.projectName) : args.projectName;
+    const logLines = [];
+    const capture = (stream)=>(...parts)=>{
+            const line = parts.map((p)=>"string" == typeof p ? p : String(p)).join(" ").trim();
+            if (line) logLines.push("error" === stream ? `[error] ${line}` : line);
+        };
+    const logTail = (max = 20)=>logLines.slice(-max);
     try {
         const result = await extensionCreate(projectInput, {
             template: args.template ?? "typescript",
             install: args.install ?? true,
             logger: {
-                log: ()=>{},
-                error: ()=>{}
+                log: capture("log"),
+                error: capture("error")
             }
         });
+        const packageManager = result.depsInstalled ? detectPackageManager(result.projectPath) : "npm";
+        const runDev = `${packageManager} run dev`;
         return JSON.stringify({
             projectPath: result.projectPath,
             projectName: result.projectName,
             template: result.template,
             depsInstalled: result.depsInstalled,
+            packageManager: result.depsInstalled ? packageManager : null,
             duration: Date.now() - start,
-            nextSteps: [
+            nextSteps: result.depsInstalled ? [
                 `cd ${result.projectPath}`,
+                runDev
+            ] : [
+                `cd ${result.projectPath}`,
+                "npm install",
                 "npm run dev"
-            ]
+            ],
+            ...result.depsInstalled ? {} : {
+                warnings: logTail()
+            }
         });
     } catch (err) {
         return JSON.stringify({
             error: err instanceof Error ? err.message : String(err),
-            duration: Date.now() - start
+            duration: Date.now() - start,
+            log: logTail()
         });
     }
 }
@@ -299,8 +340,49 @@ async function listTemplates(filters) {
     if (filters?.tags?.length) templates = templates.filter((t)=>filters.tags.some((tag)=>t.tags?.includes(tag) || t.aiRecommendFor?.includes(tag)));
     if (filters?.featured) templates = templates.filter((t)=>t.featured);
     if (filters?.query) {
-        const q = filters.query.toLowerCase();
-        templates = templates.filter((t)=>t.slug.includes(q) || t.description.toLowerCase().includes(q) || t.tags?.some((tag)=>tag.includes(q)) || t.useCases?.some((uc)=>uc.toLowerCase().includes(q)) || t.aiPromptExamples?.some((ex)=>ex.toLowerCase().includes(q)));
+        const phrase = filters.query.toLowerCase().trim();
+        const STOP = new Set([
+            "the",
+            "a",
+            "an",
+            "and",
+            "or",
+            "for",
+            "with",
+            "that",
+            "this",
+            "to",
+            "of",
+            "on",
+            "in",
+            "into",
+            "your",
+            "my",
+            "me",
+            "it",
+            "is"
+        ]);
+        const tokens = phrase.split(/\s+/).filter((tok)=>tok.length >= 2 && !STOP.has(tok));
+        const bodyOf = (t)=>[
+                t.description,
+                ...t.tags ?? [],
+                ...t.useCases ?? [],
+                ...t.aiPromptExamples ?? []
+            ].join(" ").toLowerCase();
+        const scored = templates.map((t)=>{
+            const slug = t.slug.toLowerCase();
+            const body = bodyOf(t);
+            const hay = `${slug} ${body}`;
+            let score = 0;
+            if (phrase && hay.includes(phrase)) score += 100;
+            for (const tok of tokens)if (slug.includes(tok)) score += 3;
+            else if (body.includes(tok)) score += 1;
+            return {
+                t,
+                score
+            };
+        }).filter((entry)=>entry.score > 0).sort((a, b)=>b.score - a.score);
+        templates = scored.map((entry)=>entry.t);
     }
     return templates;
 }
@@ -310,7 +392,7 @@ async function getTemplateBySlug(slug) {
 }
 const list_templates_schema = {
     name: "extension_list_templates",
-    description: "List available extension templates from the extension.dev template catalog. Filter by surface, framework, or tags. Returns structured metadata from templates-meta.json.",
+    description: "List available extension templates from the extension.dev template catalog. Filter by surface, framework, or tags. Returns structured metadata from templates-meta.json. Note: 'framework' is the UI framework only (react/vue/svelte/preact/vanilla) - it is not the language. TypeScript and JavaScript templates live under slugs (e.g. 'typescript', 'content-typescript'); shadcn is a React variant ('sidebar-shadcn') and provider AIs are tagged 'ai' ('ai-chatgpt', 'ai-claude'). Reach those with query/tags/slug, not framework.",
     inputSchema: {
         type: "object",
         properties: {
@@ -319,13 +401,10 @@ const list_templates_schema = {
                 enum: [
                     "content",
                     "sidebar",
-                    "action",
                     "newtab",
-                    "devtools",
-                    "options",
                     "background"
                 ],
-                description: "Filter by extension surface type"
+                description: "Filter by extension surface type. For a popup/action starter use the 'action' slug (query:'action'), not a surface filter."
             },
             framework: {
                 type: "string",
@@ -336,7 +415,7 @@ const list_templates_schema = {
                     "preact",
                     ""
                 ],
-                description: "Filter by UI framework (empty string = vanilla JS)"
+                description: "Filter by UI framework only (empty string = vanilla JS). Not a language filter - for TypeScript/JavaScript use query or slug."
             },
             tags: {
                 type: "array",
@@ -351,7 +430,7 @@ const list_templates_schema = {
             },
             query: {
                 type: "string",
-                description: "Free-text search across slug, description, tags, and useCases"
+                description: "Keyword search across slug, description, tags, and useCases. Ranks by how many query words match, so a natural phrase works; single keywords are fine too."
             }
         }
     }
@@ -375,112 +454,6 @@ async function list_templates_handler(args) {
         templates: results
     });
 }
-const build_schema = {
-    name: "extension_build",
-    description: "Build a browser extension for production. Outputs to dist/<browser>/. Optionally creates .zip for store submission.",
-    inputSchema: {
-        type: "object",
-        properties: {
-            projectPath: {
-                type: "string",
-                description: "Path to the extension project root"
-            },
-            browser: {
-                type: "string",
-                enum: [
-                    "chrome",
-                    "chromium",
-                    "edge",
-                    "brave",
-                    "opera",
-                    "vivaldi",
-                    "yandex",
-                    "firefox",
-                    "waterfox",
-                    "librewolf",
-                    "safari",
-                    "chromium-based",
-                    "gecko-based",
-                    "firefox-based",
-                    "webkit-based"
-                ],
-                default: "chrome",
-                description: "Target browser"
-            },
-            zip: {
-                type: "boolean",
-                default: false,
-                description: "Create a .zip file for store distribution"
-            },
-            zipSource: {
-                type: "boolean",
-                default: false,
-                description: "Include source code zip (required by some stores)"
-            },
-            zipFilename: {
-                type: "string",
-                description: "Custom .zip file name (defaults to name and version)"
-            },
-            polyfill: {
-                type: "boolean",
-                default: false,
-                description: "Apply cross-browser polyfill"
-            },
-            silent: {
-                type: "boolean",
-                default: false,
-                description: "Suppress build output"
-            },
-            mode: {
-                type: "string",
-                enum: [
-                    "development",
-                    "production",
-                    "none"
-                ],
-                default: "production",
-                description: "Bundler mode override (also sets NODE_ENV)"
-            }
-        },
-        required: [
-            "projectPath"
-        ]
-    }
-};
-async function build_handler(args) {
-    const start = Date.now();
-    try {
-        const summary = await extensionBuild(args.projectPath, {
-            browser: args.browser ?? "chrome",
-            zip: args.zip ?? false,
-            zipSource: args.zipSource ?? false,
-            ...args.zipFilename ? {
-                zipFilename: args.zipFilename
-            } : {},
-            ...void 0 !== args.polyfill ? {
-                polyfill: args.polyfill
-            } : {},
-            ...void 0 !== args.silent ? {
-                silent: args.silent
-            } : {},
-            ...args.mode ? {
-                mode: args.mode
-            } : {},
-            exitOnError: false
-        });
-        return JSON.stringify({
-            success: true,
-            ...summary,
-            duration: Date.now() - start
-        });
-    } catch (err) {
-        return JSON.stringify({
-            error: err instanceof Error ? err.message : String(err),
-            duration: Date.now() - start,
-            hint: "Check that the project has a valid src/manifest.json and all dependencies are installed."
-        });
-    }
-}
 const PINNED_CLI_VERSION = String(package_namespaceObject.El.OP ?? "latest").replace(/^[\^~]/, "");
 function pinnedCliVersion() {
     const override = String(process.env.EXTENSION_MCP_CLI_VERSION || "").trim();
@@ -562,6 +535,126 @@ function spawnExtensionCli(args, options) {
     child.unref();
     return child;
 }
+const build_schema = {
+    name: "extension_build",
+    description: "Build a browser extension for production. Outputs to dist/<browser>/. Optionally creates .zip for store submission.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            projectPath: {
+                type: "string",
+                description: "Path to the extension project root"
+            },
+            browser: {
+                type: "string",
+                enum: [
+                    "chrome",
+                    "chromium",
+                    "edge",
+                    "brave",
+                    "opera",
+                    "vivaldi",
+                    "yandex",
+                    "firefox",
+                    "waterfox",
+                    "librewolf",
+                    "safari",
+                    "chromium-based",
+                    "gecko-based",
+                    "firefox-based",
+                    "webkit-based"
+                ],
+                default: "chrome",
+                description: "Target browser"
+            },
+            zip: {
+                type: "boolean",
+                default: false,
+                description: "Create a .zip file for store distribution"
+            },
+            zipSource: {
+                type: "boolean",
+                default: false,
+                description: "Include source code zip (required by some stores)"
+            },
+            zipFilename: {
+                type: "string",
+                description: "Custom .zip file name (defaults to name and version)"
+            },
+            polyfill: {
+                type: "boolean",
+                default: false,
+                description: "Apply cross-browser polyfill"
+            },
+            silent: {
+                type: "boolean",
+                default: false,
+                description: "Suppress build output"
+            },
+            mode: {
+                type: "string",
+                enum: [
+                    "development",
+                    "production",
+                    "none"
+                ],
+                default: "production",
+                description: "Bundler mode override (also sets NODE_ENV)"
+            }
+        },
+        required: [
+            "projectPath"
+        ]
+    }
+};
+async function build_handler(args) {
+    const start = Date.now();
+    const browser = args.browser ?? "chrome";
+    const cliArgs = [
+        "build",
+        args.projectPath,
+        "--browser",
+        browser
+    ];
+    if (args.zip) cliArgs.push("--zip");
+    if (args.zipSource) cliArgs.push("--zip-source");
+    if (args.zipFilename) cliArgs.push("--zip-filename", args.zipFilename);
+    if (args.polyfill) cliArgs.push("--polyfill");
+    if (args.silent) cliArgs.push("--silent");
+    if (args.mode) cliArgs.push("--mode", args.mode);
+    const { code, stdout, stderr } = await runExtensionCli(cliArgs, {
+        cwd: args.projectPath,
+        timeoutMs: 180000
+    });
+    const duration = Date.now() - start;
+    const out = (stdout ?? "").trim();
+    const lastLines = (text, n)=>text.split("\n").slice(-n).join("\n");
+    if (0 === code) {
+        const size = out.match(/Size:\s*([\d.]+\s*[kKmMgG]?B)/)?.[1];
+        const status = out.match(/Build Status:\s*(\w+)/)?.[1];
+        return JSON.stringify({
+            success: true,
+            browser,
+            ...size ? {
+                size
+            } : {},
+            ...status ? {
+                status
+            } : {},
+            zip: args.zip ?? false,
+            duration,
+            output: lastLines(out, 12)
+        });
+    }
+    const message = stderr.trim() || out || `extension build exited with code ${code}`;
+    return JSON.stringify({
+        success: false,
+        browser,
+        error: message.slice(0, 1200),
+        duration,
+        hint: "Check that the project has a valid src/manifest.json and its dependencies are installed (extension_dev auto-installs; build does not)."
+    });
+}
 const process_manager_sessions = new Map();
 function sessionKey(projectPath, browser) {
     return `${node_path.resolve(projectPath)}::${browser}`;
@@ -676,7 +769,7 @@ const dev_schema = {
             allowEval: {
                 type: "boolean",
                 default: false,
-                description: "Additionally enable extension_eval (runs code in a context; writes a 0600 session token)"
+                description: "Enable extension_eval (runs code in a context; writes a 0600 session token). Implies allowControl, so a single allowEval: true also unlocks storage/reload/open/dom_inspect — you do not need to pass both."
             }
         },
         required: [
@@ -686,6 +779,7 @@ const dev_schema = {
 };
 async function dev_handler(args) {
     const browser = args.browser ?? "chrome";
+    const allowControl = Boolean(args.allowControl || args.allowEval);
     const cliArgs = [
         "dev",
         args.projectPath,
@@ -696,7 +790,7 @@ async function dev_handler(args) {
     if (args.noBrowser) cliArgs.push("--no-browser");
     if (false === args.polyfill) cliArgs.push("--polyfill", "false");
     cliArgs.push(...launchFlagArgs(args));
-    if (args.allowControl) cliArgs.push("--allow-control");
+    if (allowControl) cliArgs.push("--allow-control");
     if (args.allowEval) cliArgs.push("--allow-eval");
     const child = spawnExtensionCli(cliArgs, {
         projectDir: args.projectPath
@@ -719,16 +813,34 @@ async function dev_handler(args) {
     await new Promise((resolve)=>setTimeout(resolve, 3000));
     child.stdout?.off("data", collector);
     child.stderr?.off("data", collector);
+    const controlVerbs = "storage, reload, open, dom_inspect";
+    const capabilities = {
+        allowControl,
+        allowEval: Boolean(args.allowEval),
+        unlocked: allowControl ? args.allowEval ? `${controlVerbs}, eval` : controlVerbs : "none (read-only: logs, source_inspect, wait, doctor)"
+    };
     return JSON.stringify({
         pid,
         browser,
         port: args.port ?? 8080,
         projectPath: args.projectPath,
         status: "started",
-        hint: "Use extension_wait to check when the extension is fully loaded, then extension_source_inspect to inspect the live state. When you are done, call extension_stop to shut down the dev server and browser.",
-        earlyOutput: earlyOutput.slice(0, 500)
+        capabilities,
+        hint: "Use extension_wait to check when the extension is fully loaded, then extension_source_inspect to inspect the live state. " + (allowControl ? `Control channel is ON: extension_${controlVerbs.split(", ").join("/extension_")}${args.allowEval ? "/extension_eval" : ""} will work against this session.` : "Control channel is OFF: extension_storage/reload/open/dom_inspect need allowControl: true, and extension_eval needs allowEval: true (which also implies allowControl). Restart extension_dev with the flag you need.") + " When you are done, call extension_stop to shut down the dev server and browser.",
+        earlyOutput: denoiseEarlyOutput(earlyOutput).slice(0, 500)
     });
 }
+function denoiseEarlyOutput(raw) {
+    const NOISE = [
+        /^npm warn Unknown project config/i,
+        /This will stop working in the next major version of npm/i,
+        /^npm warn config/i,
+        /V8: .*Invalid asm\.js/i,
+        /^\(node:\d+\) V8:/i,
+        /Use `node --trace-warnings/i
+    ];
+    return raw.split("\n").filter((line)=>!NOISE.some((re)=>re.test(line.trim()))).join("\n").replace(/\n{2,}/g, "\n").trimStart();
+}
 const start_schema = {
     name: "extension_start",
     description: "Build the extension for production and immediately preview it in a browser. Combines build + preview in one step. No hot reload.",
@@ -899,6 +1011,66 @@ async function preview_handler(args) {
         hint: "Call extension_stop when you are done to close the preview browser."
     });
 }
+function contractSightings(projectPath) {
+    const root = node_path.resolve(projectPath, "dist", "extension-js");
+    let dirs;
+    try {
+        dirs = node_fs.readdirSync(root);
+    } catch  {
+        return [];
+    }
+    const sightings = [];
+    for (const dir of dirs){
+        const readyPath = node_path.join(root, dir, "ready.json");
+        try {
+            const stat = node_fs.statSync(readyPath);
+            const contract = JSON.parse(node_fs.readFileSync(readyPath, "utf8"));
+            if (contract?.status !== "ready") continue;
+            sightings.push({
+                browser: dir,
+                mtimeMs: stat.mtimeMs,
+                pid: "number" == typeof contract.pid ? contract.pid : void 0
+            });
+        } catch  {}
+    }
+    return sightings;
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch  {
+        return false;
+    }
+}
+function knownSessionBrowsers(projectPath) {
+    const resolved = node_path.resolve(projectPath);
+    const browsers = [];
+    for (const session of listSessions())if (node_path.resolve(session.projectPath) === resolved) browsers.push(session.browser);
+    for (const sighting of contractSightings(projectPath))if (void 0 === sighting.pid || pidAlive(sighting.pid)) browsers.push(sighting.browser);
+    return Array.from(new Set(browsers));
+}
+function resolveSessionBrowser(projectPath, explicit, fallback = "chromium") {
+    if (explicit) return {
+        browser: explicit,
+        source: "explicit"
+    };
+    const resolved = node_path.resolve(projectPath);
+    const mine = listSessions().filter((s)=>node_path.resolve(s.projectPath) === resolved);
+    if (mine.length > 0) return {
+        browser: mine[mine.length - 1].browser,
+        source: "session"
+    };
+    const sightings = contractSightings(projectPath).filter((s)=>void 0 === s.pid || pidAlive(s.pid)).sort((a, b)=>b.mtimeMs - a.mtimeMs);
+    if (sightings.length > 0) return {
+        browser: sightings[0].browser,
+        source: "contract"
+    };
+    return {
+        browser: fallback,
+        source: "fallback"
+    };
+}
 const stop_schema = {
     name: "extension_stop",
     description: "Stop a running dev, start, or preview session: terminates the dev server and the browser it launched. Counterpart to extension_dev/extension_start. Call it when you are done verifying so sessions do not accumulate.",
@@ -911,8 +1083,7 @@ const stop_schema = {
             },
             browser: {
                 type: "string",
-                default: "chrome",
-                description: "Browser of the session to stop (matches the browser passed to extension_dev/extension_start)"
+                description: "Browser of the session to stop (matches the browser passed to extension_dev/extension_start). Defaults to the one live session for this project when omitted, instead of assuming chrome."
             },
             all: {
                 type: "boolean",
@@ -923,6 +1094,27 @@ const stop_schema = {
         required: []
     }
 };
+function profileProcessPids(projectPath, browser) {
+    const marker = node_path.resolve(projectPath, "dist", `extension-profile-${browser}`);
+    try {
+        const out = execFileSync("pgrep", [
+            "-f",
+            marker
+        ], {
+            encoding: "utf8"
+        });
+        return out.split("\n").map((s)=>parseInt(s.trim(), 10)).filter((n)=>Number.isInteger(n) && n > 0 && n !== process.pid);
+    } catch  {
+        return [];
+    }
+}
+function reapProfileProcesses(projectPath, browser) {
+    const pids = profileProcessPids(projectPath, browser);
+    for (const pid of pids)try {
+        process.kill(pid, "SIGKILL");
+    } catch  {}
+    return pids;
+}
 function isAlive(pid) {
     try {
         process.kill(pid, 0);
@@ -959,13 +1151,17 @@ function pidFromReadyContract(projectPath, browser) {
 async function stopOne(projectPath, browser) {
     const session = getSession(projectPath, browser);
     const pid = session?.pid ?? pidFromReadyContract(projectPath, browser);
-    if (null == pid) return {
-        projectPath,
-        browser,
-        pid: null,
-        stopped: false,
-        detail: "No known session for this project/browser (nothing registered in this server and no ready.json contract found)."
-    };
+    if (null == pid) {
+        const reaped = reapProfileProcesses(projectPath, browser);
+        return {
+            projectPath,
+            browser,
+            pid: null,
+            stopped: 0 !== reaped.length,
+            reaped,
+            detail: 0 === reaped.length ? "No known session for this project/browser (nothing registered in this server and no ready.json contract found)." : `No dev pid on record, but reaped ${reaped.length} orphaned browser process(es) from the profile dir.`
+        };
+    }
     let detail;
     if (isAlive(pid)) {
         signal(pid, "SIGTERM");
@@ -976,17 +1172,23 @@ async function stopOne(projectPath, browser) {
         }
         detail = isAlive(pid) ? "Sent SIGTERM and SIGKILL but the process still reports alive; it may be exiting." : "Terminated.";
     } else detail = "Process was already gone; cleaned up session records.";
+    const reaped = reapProfileProcesses(projectPath, browser);
     removeSession(projectPath, browser);
     try {
         node_fs.rmSync(readyJsonPath(projectPath, browser), {
             force: true
         });
     } catch  {}
+    const survivors = profileProcessPids(projectPath, browser);
+    const stopped = !isAlive(pid) && 0 === survivors.length;
+    if (survivors.length) detail += ` Warning: ${survivors.length} browser process(es) still alive after reap (pids ${survivors.join(", ")}).`;
+    else if (reaped.length) detail += ` Reaped ${reaped.length} browser process(es).`;
     return {
         projectPath,
         browser,
         pid,
-        stopped: !isAlive(pid),
+        stopped,
+        reaped,
         detail
     };
 }
@@ -1006,7 +1208,8 @@ async function stop_handler(args) {
     if (!args.projectPath) return JSON.stringify({
         error: "projectPath is required unless all=true. Pass the same projectPath used with extension_dev/extension_start."
     });
-    const outcome = await stopOne(args.projectPath, args.browser ?? "chrome");
+    const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
+    const outcome = await stopOne(args.projectPath, browser);
     return JSON.stringify(outcome);
 }
 const RAW_BASE = "https://raw.githubusercontent.com/extension-js/examples/main/examples";
@@ -1018,7 +1221,7 @@ const get_template_source_schema = {
         properties: {
             slug: {
                 type: "string",
-                description: "Template slug (e.g. 'sidebar-claude', 'content-react')"
+                description: "Template slug (e.g. 'ai-claude', 'content-react')"
             },
             files: {
                 type: "array",
@@ -1101,6 +1304,91 @@ function isChromiumFamily(browser) {
 function isGeckoFamily(browser) {
     return GECKO_FAMILY.has(browser);
 }
+const KNOWN_PERMISSIONS = new Set([
+    "activeTab",
+    "alarms",
+    "background",
+    "bookmarks",
+    "browsingData",
+    "certificateProvider",
+    "clipboardRead",
+    "clipboardWrite",
+    "contentSettings",
+    "contextMenus",
+    "cookies",
+    "debugger",
+    "declarativeContent",
+    "declarativeNetRequest",
+    "declarativeNetRequestWithHostAccess",
+    "declarativeNetRequestFeedback",
+    "desktopCapture",
+    "dns",
+    "documentScan",
+    "downloads",
+    "downloads.open",
+    "downloads.ui",
+    "enterprise.deviceAttributes",
+    "enterprise.hardwarePlatform",
+    "enterprise.networkingAttributes",
+    "enterprise.platformKeys",
+    "favicon",
+    "fileBrowserHandler",
+    "fileSystemProvider",
+    "fontSettings",
+    "gcm",
+    "geolocation",
+    "history",
+    "identity",
+    "identity.email",
+    "idle",
+    "loginState",
+    "management",
+    "nativeMessaging",
+    "notifications",
+    "offscreen",
+    "pageCapture",
+    "power",
+    "printerProvider",
+    "printing",
+    "printingMetrics",
+    "privacy",
+    "processes",
+    "proxy",
+    "readingList",
+    "runtime",
+    "scripting",
+    "search",
+    "sessions",
+    "sidePanel",
+    "storage",
+    "system.cpu",
+    "system.display",
+    "system.memory",
+    "system.storage",
+    "tabCapture",
+    "tabGroups",
+    "tabs",
+    "topSites",
+    "tts",
+    "ttsEngine",
+    "unlimitedStorage",
+    "vpnProvider",
+    "wallpaper",
+    "webAuthenticationProxy",
+    "webNavigation",
+    "webRequest",
+    "webRequestBlocking",
+    "webRequestAuthProvider",
+    "browserSettings",
+    "captivePortal",
+    "contextualIdentities",
+    "dns",
+    "menus",
+    "menus.overrideContext",
+    "pkcs11",
+    "theme",
+    "webRequestFilterResponse"
+]);
 const manifest_validate_schema = {
     name: "extension_manifest_validate",
     description: "Validate a manifest.json file for correctness across browsers. Reports missing fields, invalid permissions, and cross-browser compatibility issues.",
@@ -1109,7 +1397,11 @@ const manifest_validate_schema = {
         properties: {
             manifestPath: {
                 type: "string",
-                description: "Path to manifest.json"
+                description: "Path to manifest.json. Or pass projectPath and the manifest is located for you."
+            },
+            projectPath: {
+                type: "string",
+                description: "Path to the extension project root; manifest.json is resolved from it (root or src/). Accepted in place of manifestPath."
             },
             browsers: {
                 type: "array",
@@ -1123,11 +1415,64 @@ const manifest_validate_schema = {
                 description: "Browsers to validate against"
             }
         },
-        required: [
-            "manifestPath"
-        ]
+        required: []
     }
 };
+function collectPathRefs(m) {
+    const refs = [];
+    const push = (v)=>{
+        if ("string" == typeof v) refs.push(v);
+    };
+    const action = m.action || m.browser_action;
+    if (action) {
+        push(action.default_popup);
+        if ("string" == typeof action.default_icon) push(action.default_icon);
+        else if (action.default_icon) Object.values(action.default_icon).forEach(push);
+    }
+    const bg = m.background;
+    if (bg) {
+        push(bg.service_worker);
+        push(bg.page);
+        if (Array.isArray(bg.scripts)) bg.scripts.forEach(push);
+    }
+    if (m.icons) Object.values(m.icons).forEach(push);
+    const cs = m.content_scripts;
+    if (Array.isArray(cs)) for (const c of cs){
+        if (Array.isArray(c.js)) c.js.forEach(push);
+        if (Array.isArray(c.css)) c.css.forEach(push);
+    }
+    push(m.options_page);
+    const oui = m.options_ui;
+    if (oui) push(oui.page);
+    const sp = m.side_panel;
+    if (sp) push(sp.default_path);
+    const sa = m.sidebar_action;
+    if (sa) push(sa.default_panel);
+    const cuo = m.chrome_url_overrides;
+    if (cuo) Object.values(cuo).forEach(push);
+    return refs;
+}
+function fileResolvesSomewhere(ref, roots) {
+    if (!ref || ref.includes("*") || /^(https?:|data:)/i.test(ref)) return true;
+    const clean = ref.replace(/^\.?\//, "");
+    return roots.some((root)=>{
+        try {
+            return node_fs.existsSync(node_path.resolve(root, clean));
+        } catch  {
+            return false;
+        }
+    });
+}
+function findManifest(projectPath) {
+    for (const rel of [
+        "manifest.json",
+        node_path.join("src", "manifest.json")
+    ]){
+        const candidate = node_path.resolve(projectPath, rel);
+        if (node_fs.existsSync(candidate)) return candidate;
+    }
+    return null;
+}
 async function manifest_validate_handler(args) {
     const browsers = args.browsers ?? [
         "chrome",
@@ -1140,9 +1485,20 @@ async function manifest_validate_handler(args) {
         browserSupport: {},
         similarTemplates: []
     };
+    const manifestPath = args.manifestPath ?? (args.projectPath ? findManifest(args.projectPath) : null);
+    if (!manifestPath) return JSON.stringify({
+        valid: false,
+        errors: [
+            args.projectPath ? `No manifest.json found under ${args.projectPath} (looked in the root and src/).` : "Pass manifestPath (path to manifest.json) or projectPath (project root)."
+        ],
+        warnings: [],
+        browserSupport: {},
+        similarTemplates: []
+    });
+    const manifestDir = node_path.dirname(node_path.resolve(manifestPath));
     let manifest;
     try {
-        const raw = node_fs.readFileSync(node_path.resolve(args.manifestPath), "utf8");
+        const raw = node_fs.readFileSync(node_path.resolve(manifestPath), "utf8");
         manifest = JSON.parse(raw);
     } catch (err) {
         return JSON.stringify({
@@ -1158,7 +1514,22 @@ async function manifest_validate_handler(args) {
     if (!manifest.name) result.errors.push("Missing required field: name");
     if (!manifest.version) result.warnings.push("Missing field: version (required for store submission)");
     const chromiumManifest = filterKeysForThisBrowser(manifest, "chrome");
+    const roots = [
+        manifestDir,
+        node_path.join(manifestDir, "src"),
+        ..."src" === node_path.basename(manifestDir) ? [
+            node_path.dirname(manifestDir)
+        ] : []
+    ];
+    for (const ref of new Set(collectPathRefs(chromiumManifest)))if (!fileResolvesSomewhere(ref, roots)) result.warnings.push(`Referenced file "${ref}" was not found near the manifest — this is the kind of dangling reference extension_build fails on. Verify with extension_build.`);
     if (!chromiumManifest.manifest_version) result.errors.push('Missing manifest_version. Use "chromium:manifest_version": 3 and "firefox:manifest_version": 2 for cross-browser support.');
+    const declaredPerms = [
+        ...chromiumManifest.permissions ?? [],
+        ...chromiumManifest.optional_permissions ?? []
+    ].filter((p)=>"string" == typeof p);
+    for (const perm of declaredPerms)if (!(perm.includes("://") || perm.includes("*")) && "<all_urls>" !== perm) {
+        if (!KNOWN_PERMISSIONS.has(perm)) result.warnings.push(`Unrecognized permission "${perm}" — check for a typo (host/match patterns belong in host_permissions, not permissions).`);
+    }
     for (const browser of browsers){
         const isChromium = isChromiumFamily(browser);
         const isFirefox = isGeckoFamily(browser);
@@ -1196,9 +1567,15 @@ async function manifest_validate_handler(args) {
     if (chromiumManifest.action || manifest["firefox:browser_action"]) surfaces.push("action");
     if (chromiumManifest.chrome_url_overrides?.newtab) surfaces.push("newtab");
     if (chromiumManifest.background) surfaces.push("background");
-    if (surfaces.length) try {
+    const distinctive = surfaces.filter((s)=>"background" !== s);
+    const matchOn = distinctive.length ? distinctive : surfaces;
+    if (matchOn.length) try {
         const templates = await listTemplates();
-        result.similarTemplates = templates.filter((t)=>t.surfaces.some((s)=>surfaces.includes(s))).slice(0, 5).map((t)=>({
+        result.similarTemplates = templates.map((t)=>({
+                slug: t.slug,
+                surfaces: t.surfaces,
+                score: t.surfaces.filter((s)=>matchOn.includes(s)).length
+            })).filter((t)=>t.score > 0).sort((a, b)=>b.score - a.score).slice(0, 5).map((t)=>({
                 slug: t.slug,
                 surfaces: t.surfaces
             }));
@@ -1320,12 +1697,58 @@ async function inspect_handler(args) {
         byType[f.type].count++;
         byType[f.type].size += f.size;
     }
+    const sourcemapSize = byType.sourcemap?.size ?? 0;
+    const buildType = sourcemapSize > 0 ? "development" : "production";
+    const shippableSize = totalSize - sourcemapSize;
+    const sizeByPath = new Map(files.map((f)=>[
+            f.path,
+            f.size
+        ]));
+    const entrypoints = [];
+    const addEntry = (role, ref)=>{
+        if ("string" != typeof ref) return;
+        const size = sizeByPath.get(ref.replace(/^\.?\//, ""));
+        entrypoints.push({
+            role,
+            path: ref,
+            present: void 0 !== size,
+            ...void 0 !== size ? {
+                sizeFormatted: formatBytes(size)
+            } : {}
+        });
+    };
+    const bg = manifest.background;
+    if (bg?.service_worker) addEntry("background.service_worker", bg.service_worker);
+    if (Array.isArray(bg?.scripts)) bg.scripts.forEach((s)=>addEntry("background.scripts", s));
+    const actionField = manifest.action || manifest.browser_action;
+    if (actionField?.default_popup) addEntry("action.default_popup", actionField.default_popup);
+    const contentScripts = manifest.content_scripts;
+    if (Array.isArray(contentScripts)) contentScripts.forEach((c, i)=>{
+        if (Array.isArray(c.js)) c.js.forEach((j)=>addEntry(`content_scripts[${i}].js`, j));
+        if (Array.isArray(c.css)) c.css.forEach((s)=>addEntry(`content_scripts[${i}].css`, s));
+    });
+    const PROMO_RE = /(screenshot|promo|marquee|tile|banner|preview)[-_.]?\d*\.(png|jpe?g|webp|gif)$/i;
+    const sizeWarnings = [];
+    for (const f of files)if ("sourcemap" !== f.type) {
+        if (PROMO_RE.test(f.path)) sizeWarnings.push(`${f.path} (${formatBytes(f.size)}) looks like a store-listing promo image shipped inside the extension package — move it out of the bundled sources so it does not inflate the store zip.`);
+        else if ("image" === f.type && !f.path.includes("icon") && f.size > 51200 && shippableSize > 0 && f.size / shippableSize > 0.25) sizeWarnings.push(`${f.path} (${formatBytes(f.size)}) is ${Math.round(f.size / shippableSize * 100)}% of the shipped bundle — unusually large for a shipped asset.`);
+    }
     const result = {
         browser,
         distPath,
+        entrypoints,
+        ...sizeWarnings.length ? {
+            sizeWarnings
+        } : {},
+        buildType,
         totalSize,
         totalSizeFormatted: formatBytes(totalSize),
+        shippableSize,
+        shippableSizeFormatted: formatBytes(shippableSize),
         fileCount: files.length,
+        ..."development" === buildType ? {
+            note: `This dist contains ${formatBytes(sourcemapSize)} of sourcemaps and looks like a dev build; run extension_build for production sizes. shippableSize excludes sourcemaps.`
+        } : {},
         manifest: {
             name: manifest.name,
             version: manifest.version,
@@ -1356,6 +1779,7 @@ async function inspect_handler(args) {
             hasManifest: node_fs.existsSync(manifestPath),
             hasIcons: files.some((f)=>"image" === f.type && f.path.includes("icon")),
             noSourceMaps: !files.some((f)=>"sourcemap" === f.type),
+            noPromoAssets: !files.some((f)=>PROMO_RE.test(f.path)),
             under10MB: totalSize < 10485760
         }
     };
@@ -1770,13 +2194,16 @@ class CDPClient extends CDPConnection {
 }
 async function resolveCdpPort(projectPath, browser, options) {
     const waitMs = options?.waitMs ?? 20000;
+    const graceMs = options?.graceMs ?? 2500;
     const readyPath = node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json");
     const deadline = Date.now() + waitMs;
     let contractSeen = false;
+    let contractSeenAt = null;
     for(;;){
         try {
             const contract = JSON.parse(node_fs.readFileSync(readyPath, "utf8"));
             contractSeen = true;
+            if (null == contractSeenAt) contractSeenAt = Date.now();
             if ("number" == typeof contract.cdpPort) return {
                 port: contract.cdpPort,
                 source: "contract"
@@ -1784,7 +2211,8 @@ async function resolveCdpPort(projectPath, browser, options) {
         } catch  {
             if (!contractSeen) break;
         }
-        if (Date.now() >= deadline) break;
+        const effectiveDeadline = null != contractSeenAt ? Math.min(deadline, contractSeenAt + graceMs) : deadline;
+        if (Date.now() >= effectiveDeadline) break;
         await new Promise((resolve)=>setTimeout(resolve, 500));
     }
     if (!contractSeen && await isCdpEndpoint(9222)) return {
@@ -1812,66 +2240,6 @@ function isCdpEndpoint(port) {
         });
     });
 }
-function contractSightings(projectPath) {
-    const root = node_path.resolve(projectPath, "dist", "extension-js");
-    let dirs;
-    try {
-        dirs = node_fs.readdirSync(root);
-    } catch  {
-        return [];
-    }
-    const sightings = [];
-    for (const dir of dirs){
-        const readyPath = node_path.join(root, dir, "ready.json");
-        try {
-            const stat = node_fs.statSync(readyPath);
-            const contract = JSON.parse(node_fs.readFileSync(readyPath, "utf8"));
-            if (contract?.status !== "ready") continue;
-            sightings.push({
-                browser: dir,
-                mtimeMs: stat.mtimeMs,
-                pid: "number" == typeof contract.pid ? contract.pid : void 0
-            });
-        } catch  {}
-    }
-    return sightings;
-}
-function pidAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    } catch  {
-        return false;
-    }
-}
-function knownSessionBrowsers(projectPath) {
-    const resolved = node_path.resolve(projectPath);
-    const browsers = [];
-    for (const session of listSessions())if (node_path.resolve(session.projectPath) === resolved) browsers.push(session.browser);
-    for (const sighting of contractSightings(projectPath))if (void 0 === sighting.pid || pidAlive(sighting.pid)) browsers.push(sighting.browser);
-    return Array.from(new Set(browsers));
-}
-function resolveSessionBrowser(projectPath, explicit, fallback = "chromium") {
-    if (explicit) return {
-        browser: explicit,
-        source: "explicit"
-    };
-    const resolved = node_path.resolve(projectPath);
-    const mine = listSessions().filter((s)=>node_path.resolve(s.projectPath) === resolved);
-    if (mine.length > 0) return {
-        browser: mine[mine.length - 1].browser,
-        source: "session"
-    };
-    const sightings = contractSightings(projectPath).filter((s)=>void 0 === s.pid || pidAlive(s.pid)).sort((a, b)=>b.mtimeMs - a.mtimeMs);
-    if (sightings.length > 0) return {
-        browser: sightings[0].browser,
-        source: "contract"
-    };
-    return {
-        browser: fallback,
-        source: "fallback"
-    };
-}
 const source_inspect_schema = {
     name: "extension_source_inspect",
     description: "Inspect a running extension's live state via Chrome DevTools Protocol: full HTML (with shadow DOM), DOM structure, content script injection, console messages, and CSS selector queries. Requires an active dev or start session.",
@@ -1942,8 +2310,8 @@ async function source_inspect_handler(args) {
     ]);
     const maxBytes = args.maxBytes ?? 262144;
     if (!isChromiumFamily(browser)) return JSON.stringify({
-        error: `Source inspection for ${browser} uses RDP (Remote Debug Protocol). Currently only Chromium CDP is supported.`,
-        hint: 'Pass browser: "chrome" (against a Chromium-family dev session).'
+        error: `Source inspection reads the live DOM over Chrome DevTools Protocol, which ${browser} (Gecko) does not expose. This is a capability limit, not a missing session.`,
+        hint: `For the ${browser} session, read runtime state with extension_logs, or extension_eval (context: "content"/"page") which works against Firefox over the control channel. To get CDP DOM inspection, run a Chromium-family dev session (extension_dev with browser: "chrome") in parallel.`
     });
     const resolved = await resolveCdpPort(args.projectPath, browser);
     if (!resolved) return JSON.stringify({
@@ -1954,16 +2322,26 @@ async function source_inspect_handler(args) {
     const cdp = new CDPClient();
     try {
         const allTargets = await CDPClient.discoverTargets(cdpPort);
-        const pageTargets = allTargets.filter((t)=>"page" === t.type && !t.url.startsWith("chrome://") && !t.url.startsWith("devtools://"));
-        if (0 === pageTargets.length) return JSON.stringify({
-            cdpPort,
-            browser,
-            warning: "No inspectable page targets found. The extension may not have opened a page yet.",
-            allTargets: allTargets.map((t)=>({
-                    type: t.type,
-                    url: t.url?.slice(0, 100)
-                }))
-        });
+        const OVERRIDE_PAGES = [
+            "chrome://newtab/",
+            "chrome://new-tab-page/",
+            "chrome://bookmarks/",
+            "chrome://history/"
+        ];
+        const isOverridePage = (url)=>OVERRIDE_PAGES.some((p)=>url.startsWith(p));
+        const pageTargets = allTargets.filter((t)=>"page" === t.type && !t.url.startsWith("devtools://") && (!t.url.startsWith("chrome://") || isOverridePage(t.url)));
+        if (0 === pageTargets.length) {
+            const chromeOnly = allTargets.some((t)=>"page" === t.type && t.url.startsWith("chrome://"));
+            return JSON.stringify({
+                cdpPort,
+                browser,
+                warning: chromeOnly ? "No inspectable page targets found. Only internal chrome:// pages are open; open the extension's surface (or pass a url to navigate a tab) first." : "No inspectable page targets found. The extension may not have opened a page yet.",
+                allTargets: allTargets.map((t)=>({
+                        type: t.type,
+                        url: t.url?.slice(0, 100)
+                    }))
+            });
+        }
         const target = args.url ? pageTargets.find((t)=>t.url.includes(args.url)) ?? pageTargets[0] : pageTargets[0];
         const browserWsUrl = await CDPClient.discoverBrowserWsUrl(cdpPort);
         await cdp.connect(browserWsUrl);
@@ -2459,7 +2837,7 @@ function commonFlags(args) {
 }
 const eval_schema = {
     name: "extension_eval",
-    description: "Evaluate an expression in a running extension context (service worker, content script, popup, options, sidebar). Requires the dev session to be started with allowEval: true (extension_dev; writes a 0600 session token the CLI reads). Wraps `extension eval`.",
+    description: "Evaluate an expression in a running extension context. Requires the dev session to be started with allowEval: true (extension_dev; writes a 0600 session token the CLI reads). Chromium caveats: eval in the MV3 background/service_worker is blocked by CSP (use an MV2/Firefox build for that context), and context content/page/popup require a numeric `tab` id (a chrome.tabs id) — the `url` arg alone does not target a tab. To read a content-script DOM without a tab id, prefer extension_source_inspect (it auto-selects the active page and can navigate by url). Wraps `extension eval`.",
     inputSchema: {
         type: "object",
         properties: {
@@ -2487,11 +2865,11 @@ const eval_schema = {
             },
             url: {
                 type: "string",
-                description: "For content/page: document(s) to target"
+                description: "For content/page: filters which matching document(s) to target, but does NOT by itself select a tab — a numeric `tab` id is still required on Chromium."
             },
             tab: {
                 type: "number",
-                description: "For content/page: a specific tab id"
+                description: "Numeric chrome.tabs id. Required for context content/page/popup on Chromium (the `url` arg does not substitute for it)."
             },
             browser: {
                 type: "string",
@@ -2703,7 +3081,21 @@ async function open_handler(args) {
     if ("command" === args.surface && args.name) cli.push("--name", args.name);
     cli.push("--browser", browser);
     if (null != args.timeout) cli.push("--timeout", String(args.timeout));
-    return runActVerb(cli, args.projectPath, args.timeout);
+    const raw = await runActVerb(cli, args.projectPath, args.timeout);
+    const headless = /^(1|true)$/i.test(process.env.EXTENSION_HEADLESS ?? "");
+    if (headless && [
+        "popup",
+        "action",
+        "sidebar"
+    ].includes(args.surface)) try {
+        const parsed = JSON.parse(raw);
+        const msg = String(parsed?.error?.message ?? "");
+        if (parsed?.ok === false && !parsed.hint && /active browser window|no active|headless/i.test(msg)) {
+            parsed.hint = "The dev browser is running headless (EXTENSION_HEADLESS), which has no visible window to attach a popup/sidebar to. Relaunch a headed dev session to open UI surfaces.";
+            return JSON.stringify(parsed);
+        }
+    } catch  {}
+    return raw;
 }
 const dom_inspect_schema = {
     name: "extension_dom_inspect",
@@ -2780,8 +3172,9 @@ async function dom_inspect_handler(args) {
         ok: false,
         error: {
             name: "BadRequest",
-            message: "content/page inspect requires a tab id"
-        }
+            message: "content/page inspect requires a numeric tab id (chrome.tabs id, not a CDP target id)."
+        },
+        hint: "To inspect a content script's DOM without hunting for a tab id, use extension_source_inspect (it auto-selects the active page and can navigate via its url arg). Use extension_dom_inspect with context popup/options/sidebar/devtools for an open surface (no tab needed)."
     });
     const cli = [
         "inspect",
@@ -2813,13 +3206,17 @@ function readCredentials() {
         if (1 !== data.version) return null;
         const token = String(data.token || "").trim();
         if (!token) return null;
+        const provider = "extensiondev" === data.provider || "github" === data.provider ? data.provider : void 0;
         return {
             version: 1,
             token,
             workspaceSlug: String(data.workspaceSlug || ""),
             projectSlug: String(data.projectSlug || ""),
             expiresAt: Number(data.expiresAt || 0),
-            api: String(data.api || "")
+            api: String(data.api || ""),
+            ...provider ? {
+                provider
+            } : {}
         };
     } catch  {
         return null;
@@ -2891,8 +3288,12 @@ function safeApiBase(raw) {
 async function fetchLoginConfig(apiBase, fetchImpl = fetch) {
     const override = String(process.env.EXTENSION_DEV_GITHUB_CLIENT_ID || "").trim();
     if (override) return {
+        provider: "github",
         clientId: override,
-        scope: "read:user"
+        scope: "read:user",
+        deviceCodeUrl: "/api/cli/device/code",
+        deviceTokenUrl: "/api/cli/device/token",
+        verificationUri: "https://github.com/login/device"
     };
     const res = await fetchImpl(`${apiBase}/api/cli/login/config`, {
         headers: {
@@ -2901,12 +3302,32 @@ async function fetchLoginConfig(apiBase, fetchImpl = fetch) {
     });
     if (!res.ok) throw new Error(`Could not fetch login config from ${apiBase} (${res.status}).`);
     const data = await res.json().catch(()=>({}));
+    const provider = "extensiondev" === data.provider ? "extensiondev" : "github";
     const clientId = String(data.githubClientId || "").trim();
-    if (!clientId) throw new Error("Login is not configured on the server (no GitHub client id). Set EXTENSION_DEV_GITHUB_CLIENT_ID to override.");
+    if ("github" === provider && !clientId) throw new Error("Login is not configured on the server (no GitHub client id). Set EXTENSION_DEV_GITHUB_CLIENT_ID to override.");
     return {
+        provider,
         clientId,
-        scope: String(data.scope || "read:user")
+        scope: String(data.scope || "read:user"),
+        deviceCodeUrl: String(data.deviceCodeUrl || "/api/cli/device/code"),
+        deviceTokenUrl: String(data.deviceTokenUrl || "/api/cli/device/token"),
+        verificationUri: String(data.verificationUri || "https://github.com/login/device")
+    };
+}
+function persistTokenResponse(args) {
+    const token = String(args.data.token || "").trim();
+    if (!token) throw new Error("Login returned no token.");
+    const creds = {
+        version: 1,
+        token,
+        workspaceSlug: String(args.data.workspaceSlug || ""),
+        projectSlug: String(args.data.projectSlug || ""),
+        expiresAt: Number(args.data.expiresAt || 0),
+        api: args.apiBase,
+        provider: args.provider
     };
+    writeCredentials(creds);
+    return creds;
 }
 async function exchangeAndPersist(args) {
     const doFetch = args.fetchImpl ?? fetch;
@@ -2931,18 +3352,11 @@ async function exchangeAndPersist(args) {
         };
     }
     if (!res.ok) throw new Error(`Login exchange failed (${res.status}): ${data.message || "unknown error"}`);
-    const token = String(data.token || "").trim();
-    if (!token) throw new Error("Login exchange returned no token.");
-    const creds = {
-        version: 1,
-        token,
-        workspaceSlug: String(data.workspaceSlug || ""),
-        projectSlug: String(data.projectSlug || ""),
-        expiresAt: Number(data.expiresAt || 0),
-        api: args.apiBase
-    };
-    writeCredentials(creds);
-    return creds;
+    return persistTokenResponse({
+        apiBase: args.apiBase,
+        data,
+        provider: "github"
+    });
 }
 function resolveToken() {
     const fromEnv = String(process.env.EXTENSION_DEV_TOKEN || "").trim();
@@ -3014,53 +3428,60 @@ async function publish(options = {}) {
 }
 const publish_schema = {
     name: "extension_publish",
-    description: "Publish a project to extension.dev and return a shareable URL. Auth-gated: requires EXTENSION_DEV_TOKEN (a workspace/project access token) in the environment. Posts to the platform's CLI publish endpoint directly. This is the only tool that talks to the hosted platform rather than the local browser.",
+    description: "Publish the project your stored token is scoped to (from extension_login, or EXTENSION_DEV_TOKEN) to extension.dev and return its shareable URL. The publish target is the token's project -- there is no projectPath, the local files are not uploaded. For a PUBLIC project the URL is the canonical public page and ttlHours does not apply; for a PRIVATE project it is a fresh time-limited share link (?share=) whose lifetime is ttlHours. Posts to the platform's CLI publish endpoint. Besides extension_login this is the only tool that talks to the hosted platform.",
     inputSchema: {
         type: "object",
         properties: {
-            projectPath: {
-                type: "string",
-                description: "Path to the extension project root"
-            },
             ttlHours: {
                 type: "number",
-                description: "Share-link lifetime in hours (1–168, default 24)"
+                description: "Private-project share-link lifetime in hours, 1-168 (default 24). Ignored for public projects."
             },
             buildSha: {
                 type: "string",
-                description: "Pin the share URL to a specific build sha"
+                description: "Pin the share URL to a specific build sha (7-40 hex chars). The platform verifies the build exists in the project's build index and rejects an unknown sha, so the returned URL always points at a real build."
             },
             api: {
                 type: "string",
                 description: "Platform base URL (defaults to https://www.extension.dev or EXTENSION_DEV_API_URL)"
             }
         },
-        required: [
-            "projectPath"
-        ]
+        required: []
     }
 };
-async function publish_handler(args) {
-    const token = resolveToken();
-    if (!token) return JSON.stringify({
+function fail(name, message) {
+    return JSON.stringify({
         ok: false,
         error: {
-            name: "PublishAuthError",
-            message: "No token. Run extension_login, or set EXTENSION_DEV_TOKEN (create one in the extension.dev dashboard)."
+            name,
+            message
         }
     });
+}
+async function publish_handler(args) {
+    const token = resolveToken();
+    if (!token) return fail("PublishAuthError", "No token. Run extension_login, or set EXTENSION_DEV_TOKEN (create one in the extension.dev dashboard).");
+    if (null != args.ttlHours) {
+        const t = Number(args.ttlHours);
+        if (!Number.isInteger(t) || t < 1 || t > 168) return fail("PublishBadRequest", "ttlHours must be an integer between 1 and 168.");
+    }
+    if (null != args.buildSha && "" !== args.buildSha) {
+        if (!/^[0-9a-f]{7,40}$/i.test(args.buildSha)) return fail("PublishBadRequest", "buildSha must be a 7-40 character hex git sha.");
+    }
     const result = await publish({
         ttlHours: args.ttlHours,
         buildSha: args.buildSha,
         api: args.api,
         token
     });
-    return result.ok ? JSON.stringify(result.data) : JSON.stringify(result);
+    if (!result.ok) return JSON.stringify(result);
+    const data = result.data;
+    if (null != args.ttlHours && "public" === data.visibility) data.note = "ttlHours was ignored: this is a public project, whose share URL is its canonical public page.";
+    return JSON.stringify(data);
 }
 const release_promote_DEFAULT_API = "https://www.extension.dev";
 const release_promote_schema = {
     name: "extension_release_promote",
-    description: "Promote a built extension to a release channel (e.g. stable, preview, beta) on extension.dev, headless. Auth-gated: requires a release token in EXTENSION_DEV_TOKEN (mint and revoke it in the dashboard under project settings -> Access tokens). Posts to the platform's CLI release endpoint; the project is identified by the token. Cutting a version-bump PR is not available headlessly (it writes to your source repo and needs an interactive login).",
+    description: "Promote a built extension to a release channel (e.g. stable, preview, beta) on extension.dev, headless. Auth-gated: uses your stored login (extension_login) or a release token in EXTENSION_DEV_TOKEN (mint and revoke it in the dashboard under project settings -> Access tokens). Posts to the platform's CLI release endpoint; the project is identified by the token. Cutting a version-bump PR is not available headlessly (it writes to your source repo and needs an interactive login).",
     inputSchema: {
         type: "object",
         properties: {
@@ -3102,7 +3523,7 @@ const release_promote_schema = {
         ]
     }
 };
-function fail(name, message) {
+function release_promote_fail(name, message) {
     return JSON.stringify({
         ok: false,
         error: {
@@ -3113,12 +3534,12 @@ function fail(name, message) {
 }
 async function release_promote_handler(args) {
     const token = resolveToken();
-    if (!token) return fail("ReleaseAuthError", "No token. Set EXTENSION_DEV_TOKEN to a release token (create one in the extension.dev dashboard under project settings -> Access tokens), or run extension_login.");
+    if (!token) return release_promote_fail("ReleaseAuthError", "No token. Set EXTENSION_DEV_TOKEN to a release token (create one in the extension.dev dashboard under project settings -> Access tokens), or run extension_login.");
     const buildId = String(args.buildId || "").trim();
     const channel = String(args.channel || "").trim();
-    if (!buildId || !channel) return fail("ReleaseInputError", "buildId and channel are required.");
+    if (!buildId || !channel) return release_promote_fail("ReleaseInputError", "buildId and channel are required.");
     const apiCheck = safeApiBase(String(args.api || process.env.EXTENSION_DEV_API_URL || release_promote_DEFAULT_API));
-    if (!apiCheck.ok) return fail("ReleaseConfigError", apiCheck.message);
+    if (!apiCheck.ok) return release_promote_fail("ReleaseConfigError", apiCheck.message);
     const url = `${apiCheck.base}/api/cli/release/promote`;
     const body = {
         buildId,
@@ -3139,7 +3560,7 @@ async function release_promote_handler(args) {
             body: JSON.stringify(body)
         });
     } catch (err) {
-        return fail("ReleaseNetworkError", `Could not reach ${url}: ${err?.message || err}`);
+        return release_promote_fail("ReleaseNetworkError", `Could not reach ${url}: ${err?.message || err}`);
     }
     const text = await res.text();
     let data;
@@ -3150,175 +3571,117 @@ async function release_promote_handler(args) {
             message: text
         };
     }
-    if (!res.ok) return fail("ReleaseError", `promote failed (${res.status}): ${data?.message || text || "unknown error"}`);
+    if (!res.ok) return release_promote_fail("ReleaseError", `promote failed (${res.status}): ${data?.message || text || "unknown error"}`);
     return JSON.stringify(data);
 }
-const DEFAULT_DEPLOY_VERSION = "1.2.1";
-function pinnedDeployVersion() {
-    return String(process.env.EXTENSION_DEPLOY_VERSION || "").trim() || DEFAULT_DEPLOY_VERSION;
-}
-function buildDeployArgs(args) {
-    const argv = [];
-    const pushValue = (flag, value)=>{
-        if (void 0 === value || "" === value) return;
-        argv.push(flag, String(value));
-    };
-    if (false !== args.dryRun) argv.push("--dry-run");
-    pushValue("--chrome-zip", args.chromeZip);
-    pushValue("--chrome-extension-id", args.chromeExtensionId);
-    pushValue("--chrome-publisher-id", args.chromePublisherId);
-    if (args.stagedPublish) argv.push("--chrome-staged-publish");
-    pushValue("--chrome-deploy-percentage", args.chromeDeployPercentage);
-    if (args.chromeSkipSubmitReview) argv.push("--chrome-skip-submit-review");
-    pushValue("--firefox-zip", args.firefoxZip);
-    pushValue("--firefox-sources-zip", args.firefoxSourcesZip);
-    pushValue("--firefox-extension-id", args.firefoxExtensionId);
-    pushValue("--firefox-channel", args.firefoxChannel);
-    pushValue("--edge-zip", args.edgeZip);
-    pushValue("--edge-product-id", args.edgeProductId);
-    if (args.edgeSkipSubmitReview) argv.push("--edge-skip-submit-review");
-    pushValue("--output-json", args.outputJson);
-    return argv;
-}
+const deploy_DEFAULT_API = "https://www.extension.dev";
 const deploy_schema = {
     name: "extension_deploy",
-    description: "Submit a built extension to the Chrome Web Store, Firefox AMO, and/or Edge Add-ons by driving the standalone @extension.dev/deploy CLI. Provide the built .zip path(s); the target stores are inferred from which zips you pass. DEFAULTS TO A DRY RUN (verifies auth and inputs, uploads nothing) - pass dryRun:false to actually submit, which is irreversible and enters store review. Store CREDENTIALS are NOT arguments: set them in the environment or a .env.submit file in projectPath (CHROME_CLIENT_ID/CHROME_CLIENT_SECRET/CHROME_REFRESH_TOKEN or CHROME_SERVICE_ACCOUNT_JSON; FIREFOX_JWT_ISSUER/FIREFOX_JWT_SECRET; EDGE_CLIENT_ID/EDGE_API_KEY). Runs `npx @extension.dev/deploy`.",
+    description: "Submit a built extension to the Chrome Web Store, Firefox AMO, and/or Edge Add-ons THROUGH extension.dev, which holds your store credentials and dispatches the release from your project's mirror CI. DEFAULTS TO A DRY RUN (preflight: verifies auth, the project, that the build exists, and the store workflow - dispatches nothing); pass dryRun:false to actually submit, which is irreversible and enters store review. The target project is identified by your token (extension_login or a release token in EXTENSION_DEV_TOKEN); store credentials are never tool arguments and local files are not uploaded. Pass browsers + buildSha. Posts to the platform's CLI store-submission endpoint.",
     inputSchema: {
         type: "object",
         properties: {
-            projectPath: {
-                type: "string",
-                description: "Working directory. Relative zip paths and a .env.submit credential file are resolved from here."
-            },
-            chromeZip: {
-                type: "string",
-                description: "Path to the built Chrome extension .zip"
-            },
-            chromeExtensionId: {
-                type: "string",
-                description: "Chrome extension ID (or set CHROME_EXTENSION_ID)"
-            },
-            chromePublisherId: {
-                type: "string",
-                description: "Chrome publisher UUID (or set CHROME_PUBLISHER_ID)"
-            },
-            firefoxZip: {
-                type: "string",
-                description: "Path to the built Firefox extension .zip"
-            },
-            firefoxSourcesZip: {
-                type: "string",
-                description: "Path to the Firefox sources .zip (optional)"
-            },
-            firefoxExtensionId: {
-                type: "string",
-                description: "Firefox add-on GUID or email-style ID"
+            browsers: {
+                type: "array",
+                items: {
+                    type: "string",
+                    enum: [
+                        "chrome",
+                        "firefox",
+                        "edge",
+                        "safari"
+                    ]
+                },
+                description: "Stores to submit to."
             },
-            firefoxChannel: {
+            buildSha: {
                 type: "string",
-                enum: [
-                    "listed",
-                    "unlisted"
-                ],
-                description: "Firefox channel (unlisted is required for a first submission)"
+                description: "The built commit SHA to submit. It must have a completed build in the project's build index; an unknown sha is rejected."
             },
-            edgeZip: {
+            channel: {
                 type: "string",
-                description: "Path to the built Edge extension .zip"
+                description: "Release channel to submit from (default stable)."
             },
-            edgeProductId: {
+            version: {
                 type: "string",
-                description: "Edge Partner Center product ID (or set EDGE_PRODUCT_ID)"
+                description: "Version label for the submission record (optional)."
             },
             dryRun: {
                 type: "boolean",
                 default: true,
-                description: "Verify auth and inputs without uploading or publishing. Pass false to actually submit (irreversible)."
-            },
-            stagedPublish: {
-                type: "boolean",
-                default: false,
-                description: "Chrome: publish as STAGED_PUBLISH so the rollout can be raised review-free later."
-            },
-            chromeDeployPercentage: {
-                type: "number",
-                description: "Chrome staged rollout percentage (1-100)."
-            },
-            chromeSkipSubmitReview: {
-                type: "boolean",
-                default: false,
-                description: "Chrome: upload only, skip the publish/submit-for-review step."
-            },
-            edgeSkipSubmitReview: {
-                type: "boolean",
-                default: false,
-                description: "Edge: upload only, skip the publish/submit-for-review step."
+                description: "Preflight only (verify auth, project, build, and store workflow). Pass false to actually dispatch the submission (irreversible, enters store review)."
             },
-            outputJson: {
+            api: {
                 type: "string",
-                description: "Write the machine-readable DeployResult JSON to this path."
+                description: "Platform base URL (defaults to https://www.extension.dev or EXTENSION_DEV_API_URL)"
             }
         },
         required: [
-            "projectPath"
+            "browsers",
+            "buildSha"
         ]
     }
 };
-async function deploy_handler(args) {
-    if (!args.chromeZip && !args.firefoxZip && !args.edgeZip) return JSON.stringify({
+function deploy_fail(name, message) {
+    return JSON.stringify({
         ok: false,
         error: {
-            name: "DeployInputError",
-            message: "No store targets. Provide at least one of chromeZip, firefoxZip, or edgeZip."
+            name,
+            message
         }
     });
-    const version = pinnedDeployVersion();
-    const argv = [
-        "--yes",
-        `@extension.dev/deploy@${version}`,
-        ...buildDeployArgs(args)
-    ];
-    return new Promise((resolve)=>{
-        const child = cross_spawn("npx", argv, {
-            cwd: args.projectPath,
-            stdio: [
-                "ignore",
-                "pipe",
-                "pipe"
-            ],
-            env: {
-                ...process.env,
-                FORCE_COLOR: "0",
-                NO_COLOR: "1"
-            }
-        });
-        let stdout = "";
-        let stderr = "";
-        child.stdout?.on("data", (d)=>stdout += d.toString());
-        child.stderr?.on("data", (d)=>stderr += d.toString());
-        child.on("close", (code)=>{
-            resolve(JSON.stringify({
-                ok: 0 === code,
-                dryRun: false !== args.dryRun,
-                code,
-                stdout: stdout.trim(),
-                stderr: stderr.trim()
-            }));
-        });
-        child.on("error", (err)=>{
-            resolve(JSON.stringify({
-                ok: false,
-                error: {
-                    name: "DeploySpawnError",
-                    message: `Could not run extension-deploy: ${err instanceof Error ? err.message : String(err)}`
-                }
-            }));
+}
+async function deploy_handler(args) {
+    const token = resolveToken();
+    if (!token) return deploy_fail("DeployAuthError", "No token. Run extension_login, or set EXTENSION_DEV_TOKEN (create one in the extension.dev dashboard under project settings -> Access tokens).");
+    const browsers = (Array.isArray(args.browsers) ? args.browsers : []).map((b)=>String(b).trim().toLowerCase()).filter(Boolean);
+    if (0 === browsers.length) return deploy_fail("DeployInputError", 'browsers is required (e.g. ["chrome","firefox","edge"]).');
+    const buildSha = String(args.buildSha || "").trim();
+    if (!buildSha) return deploy_fail("DeployInputError", "buildSha is required (the built commit to submit).");
+    const apiCheck = safeApiBase(String(args.api || process.env.EXTENSION_DEV_API_URL || deploy_DEFAULT_API));
+    if (!apiCheck.ok) return deploy_fail("DeployConfigError", apiCheck.message);
+    const url = `${apiCheck.base}/api/cli/stores/submit`;
+    const dryRun = false !== args.dryRun;
+    const body = {
+        browsers,
+        buildSha,
+        dryRun
+    };
+    if (args.channel) body.channel = String(args.channel).trim();
+    if (args.version) body.version = String(args.version).trim();
+    let res;
+    try {
+        res = await fetch(url, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${token}`,
+                "content-type": "application/json"
+            },
+            body: JSON.stringify(body)
         });
+    } catch (err) {
+        return deploy_fail("DeployNetworkError", `Could not reach ${url}: ${err?.message || err}`);
+    }
+    const text = await res.text();
+    let data;
+    try {
+        data = JSON.parse(text);
+    } catch  {
+        data = {
+            message: text
+        };
+    }
+    if (!res.ok) return deploy_fail("DeployError", `submit failed (${res.status}): ${data?.message || text || "unknown error"}`);
+    return JSON.stringify({
+        mode: "platform",
+        dryRun,
+        ...data
     });
 }
+const SAFE_CEILING_MS = 50000;
 const wait_schema = {
     name: "extension_wait",
-    description: "Wait for a running dev or start session to be ready. Polls the ready.json contract file and returns structured status.",
+    description: "Wait for a running dev or start session to be ready. Polls the ready.json contract file and returns structured status. A single call is bounded to ~50s to stay under the MCP client request timeout; if it returns status:'timeout', call it again to keep waiting (polling resumes on the same contract).",
     inputSchema: {
         type: "object",
         properties: {
@@ -3332,8 +3695,8 @@ const wait_schema = {
             },
             timeout: {
                 type: "number",
-                default: 60000,
-                description: "Timeout in milliseconds"
+                default: 45000,
+                description: "Requested wait in milliseconds. Clamped to ~50s per call so it never exceeds the MCP client request timeout; call again to keep waiting for slower builds."
             }
         },
         required: [
@@ -3343,7 +3706,9 @@ const wait_schema = {
 };
 async function wait_handler(args) {
     const { browser } = resolveSessionBrowser(args.projectPath, args.browser, "chrome");
-    const timeout = args.timeout ?? 60000;
+    const requested = args.timeout ?? 45000;
+    const timeout = Math.min(Math.max(requested, 1000), SAFE_CEILING_MS);
+    const clamped = requested > SAFE_CEILING_MS;
     const readyPath = node_path.resolve(args.projectPath, "dist", "extension-js", browser, "ready.json");
     const start = Date.now();
     const pollInterval = 1000;
@@ -3376,9 +3741,11 @@ async function wait_handler(args) {
     }
     return JSON.stringify({
         status: "timeout",
-        message: `Extension did not become ready within ${timeout}ms`,
+        message: `Extension not ready after ${timeout}ms this call`,
         readyPath,
-        hint: "The dev session may still be building. Try increasing the timeout, or check if the dev process is still running."
+        waitDuration: Date.now() - start,
+        clamped: clamped ? `requested ${requested}ms was clamped to ${SAFE_CEILING_MS}ms to stay under the MCP client request timeout` : void 0,
+        hint: "Still building — call extension_wait again to keep waiting (it resumes polling the same contract). If it never readies, check the dev process with extension_doctor."
     });
 }
 const add_feature_schema = {
@@ -3548,7 +3915,23 @@ async function add_feature_handler(args) {
     });
     const template = await getTemplateBySlug(templateSlug);
     const referenceFiles = template?.keyFiles ?? template?.files ?? [];
-    const featureDir = "content-script" === args.feature ? "content" : args.feature;
+    const FEATURE_DIR = {
+        "content-script": "content",
+        popup: "action"
+    };
+    const featureDir = FEATURE_DIR[args.feature] ?? args.feature;
+    const scriptExt = "react" === framework || "preact" === framework ? "tsx" : "ts";
+    const componentExt = "vue" === framework ? "vue" : "svelte" === framework ? "svelte" : "tsx";
+    const COMPONENT_BASE = {
+        content: "Content",
+        sidebar: "Sidebar",
+        action: "Action",
+        newtab: "NewTab",
+        options: "Options",
+        devtools: "DevTools",
+        background: "Background"
+    };
+    const componentBase = COMPONENT_BASE[featureDir] ?? featureDir.charAt(0).toUpperCase() + featureDir.slice(1);
     const filesToCreate = [];
     const manifestUpdates = MANIFEST_ADDITIONS[args.feature] ?? {};
     if ([
@@ -3562,24 +3945,42 @@ async function add_feature_handler(args) {
             path: `src/${featureDir}/index.html`,
             hint: "HTML entry point"
         }, {
-            path: `src/${featureDir}/scripts.${"vanilla" === framework ? "ts" : "tsx"}`,
+            path: `src/${featureDir}/scripts.${scriptExt}`,
             hint: "vanilla" === framework ? "Script entry point" : `${framework} mount point`
         }, {
             path: `src/${featureDir}/styles.css`,
             hint: "Stylesheet"
         });
-        if ("vanilla" !== framework) filesToCreate.push({
-            path: `src/${featureDir}/${featureDir.charAt(0).toUpperCase() + featureDir.slice(1)}App.tsx`,
-            hint: `Main ${framework} component`
+        if ("vanilla" !== framework) {
+            filesToCreate.push({
+                path: `src/${featureDir}/${componentBase}App.${componentExt}`,
+                hint: `Main ${framework} component`
+            });
+            if ("vue" === framework) filesToCreate.push({
+                path: `src/${featureDir}/shims-vue.d.ts`,
+                hint: "Vue SFC type shim (lets TS import .vue components)"
+            });
+        }
+    }
+    if ("content-script" === args.feature) {
+        filesToCreate.push({
+            path: "src/content/scripts.ts",
+            hint: "vanilla" === framework ? "Content script entry point" : `${framework} content-script mount point`
+        }, {
+            path: "src/content/styles.css",
+            hint: "Content script styles"
         });
+        if ("vanilla" !== framework) {
+            filesToCreate.push({
+                path: `src/content/ContentApp.${componentExt}`,
+                hint: `Main ${framework} component mounted by the content script`
+            });
+            if ("vue" === framework) filesToCreate.push({
+                path: "src/content/shims-vue.d.ts",
+                hint: "Vue SFC type shim (lets TS import .vue components)"
+            });
+        }
     }
-    if ("content-script" === args.feature) filesToCreate.push({
-        path: "src/content/scripts.ts",
-        hint: "Content script entry point"
-    }, {
-        path: "src/content/styles.css",
-        hint: "Content script styles"
-    });
     if ("background" === args.feature) filesToCreate.push({
         path: "src/background.ts",
         hint: "Background service worker / script"
@@ -3682,9 +4083,102 @@ async function pollForToken(args) {
         reason: "pending"
     };
 }
+async function requestDeviceCode(args) {
+    const doFetch = args.fetchImpl ?? fetch;
+    const res = await doFetch(`${args.apiBase}${args.path}`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            accept: "application/json"
+        },
+        body: JSON.stringify({
+            project: args.project,
+            clientName: args.clientName ?? "extension-mcp"
+        })
+    });
+    const text = await res.text();
+    let data;
+    try {
+        data = JSON.parse(text);
+    } catch  {
+        data = {
+            message: text
+        };
+    }
+    if (!res.ok) throw new Error(`Device code request failed (${res.status}): ${data.message || "unknown error"}`);
+    const deviceCode = String(data.device_code || "").trim();
+    const userCode = String(data.user_code || "").trim();
+    if (!deviceCode || !userCode) throw new Error("Device code response missing device_code/user_code.");
+    return {
+        deviceCode,
+        userCode,
+        verificationUri: String(data.verification_uri || "https://extension.dev/device"),
+        verificationUriComplete: String(data.verification_uri_complete || data.verification_uri || ""),
+        interval: Number(data.interval || 5),
+        expiresIn: Number(data.expires_in || 900)
+    };
+}
+async function pollDeviceToken(args) {
+    const doFetch = args.fetchImpl ?? fetch;
+    const deadline = Date.now() + args.budgetMs;
+    let interval = Math.max(1, args.interval);
+    for(;;){
+        const res = await doFetch(`${args.apiBase}${args.path}`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                accept: "application/json"
+            },
+            body: JSON.stringify({
+                device_code: args.deviceCode,
+                project: args.project
+            })
+        });
+        const text = await res.text();
+        let data;
+        try {
+            data = JSON.parse(text);
+        } catch  {
+            data = {
+                message: text
+            };
+        }
+        if (res.ok && data.token) {
+            const creds = persistTokenResponse({
+                apiBase: args.apiBase,
+                data,
+                provider: "extensiondev"
+            });
+            return {
+                ok: true,
+                creds
+            };
+        }
+        const error = String(data.error || "");
+        if ("access_denied" === error) return {
+            ok: false,
+            reason: "denied"
+        };
+        if ("expired_token" === error) return {
+            ok: false,
+            reason: "expired"
+        };
+        if ("slow_down" === error) interval += 5;
+        else if (error && "authorization_pending" !== error) return {
+            ok: false,
+            reason: "error",
+            message: String(data.message || error)
+        };
+        if (Date.now() + 1000 * interval >= deadline) return {
+            ok: false,
+            reason: "pending"
+        };
+        await new Promise((r)=>setTimeout(r, 1000 * interval));
+    }
+}
 const login_schema = {
     name: "extension_login",
-    description: "Authenticate to extension.dev via GitHub device-code and store a project-scoped access token locally so extension_publish can use it. Two-phase: call with `project` to get a code + URL for the user to authorize, then call again with the returned `deviceCode` to finish. Never returns the token. This is the only tool besides extension_publish that talks to the hosted platform.",
+    description: "Authenticate to extension.dev and store a project-scoped access token locally so extension_publish can use it. Two-phase: call with `project` to get a code + URL for the user to authorize, then call again with the returned `deviceCode` to finish. The server picks the flow: the extension.dev-gated device flow (you authorize at extension.dev/device; GitHub federation happens server-side, no GitHub token on this machine) or, as a fallback, the legacy GitHub device flow. Never returns the token. This is the only tool besides extension_publish that talks to the hosted platform.",
     inputSchema: {
         type: "object",
         properties: {
@@ -3747,6 +4241,52 @@ async function login_handler(args) {
     } catch (err) {
         return login_fail("LoginConfigError", err?.message || "Could not load login config.");
     }
+    if ("extensiondev" === config.provider) {
+        if (args.deviceCode) {
+            const poll = await pollDeviceToken({
+                apiBase,
+                path: config.deviceTokenUrl,
+                project,
+                deviceCode: String(args.deviceCode),
+                interval: 5,
+                budgetMs: RESUME_BUDGET_MS
+            });
+            if (poll.ok) return success(poll.creds);
+            if ("expired" === poll.reason) return login_fail("LoginExpired", "The device code expired. Run extension_login again to restart.");
+            if ("denied" === poll.reason) return login_fail("LoginDenied", "Authorization was denied at extension.dev/device.");
+            if ("error" === poll.reason) return login_fail("LoginError", poll.message || "Device login failed.");
+            return login_pending({
+                deviceCode: String(args.deviceCode),
+                userCode: "(see the previous response)",
+                verificationUri: config.verificationUri
+            });
+        }
+        let start;
+        try {
+            start = await requestDeviceCode({
+                apiBase,
+                path: config.deviceCodeUrl,
+                project
+            });
+        } catch (err) {
+            return login_fail("LoginStartError", err?.message || "Could not start the device flow.");
+        }
+        const poll = await pollDeviceToken({
+            apiBase,
+            path: config.deviceTokenUrl,
+            project,
+            deviceCode: start.deviceCode,
+            interval: start.interval,
+            budgetMs: FIRST_CALL_BUDGET_MS
+        });
+        if (poll.ok) return success(poll.creds);
+        if ("denied" === poll.reason) return login_fail("LoginDenied", "Authorization was denied at extension.dev/device.");
+        return login_pending({
+            deviceCode: start.deviceCode,
+            userCode: start.userCode,
+            verificationUri: start.verificationUri
+        });
+    }
     if (args.deviceCode) {
         const poll = await pollForToken({
             clientId: config.clientId,
@@ -3825,6 +4365,7 @@ async function whoami_handler() {
         workspaceSlug: creds.workspaceSlug,
         projectSlug: creds.projectSlug,
         api: creds.api,
+        provider: creds.provider ?? "github",
         expiresAt: creds.expiresAt ? new Date(1000 * creds.expiresAt).toISOString() : null,
         expiresInSeconds: creds.expiresAt ? creds.expiresAt - now : null,
         expired,
@@ -3849,7 +4390,7 @@ async function logout_handler() {
 }
 const install_browser_schema = {
     name: "extension_install_browser",
-    description: "Install a managed browser binary for extension testing. Useful in CI, Docker, or fresh environments where browsers are not pre-installed.",
+    description: "Install a managed browser binary for extension testing. Useful in CI, Docker, or fresh environments where browsers are not pre-installed. This downloads ~580-625 MB in a single blocking call (30s+ on a fast link); on a slow network it can exceed a client's default request timeout, so allow a generous timeout when calling it.",
     inputSchema: {
         type: "object",
         properties: {
@@ -4323,37 +4864,80 @@ async function detect_browsers_handler(args) {
         hint: missing.length ? `Missing browser(s): ${missing.map((d)=>d.browser).join(", ")}.${missing.some((d)=>MANAGED_INSTALLABLE.has(d.browser)) ? ` Use extension_install_browser to install ${missing.filter((d)=>MANAGED_INSTALLABLE.has(d.browser)).map((d)=>d.browser).join(", ")}.` : ""}` : "All requested browsers are available."
     });
 }
+function doctor_readReadyContract(projectPath, browser) {
+    try {
+        const raw = node_fs.readFileSync(node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json"), "utf8");
+        return JSON.parse(raw);
+    } catch  {
+        return null;
+    }
+}
 const doctor_schema = {
     name: "extension_doctor",
-    description: "Diagnose a dev session end-to-end: ready contract, dev-server process, control-port agreement, control channel, eval token, executor, and browser liveness. Returns one {check, status, detail, remediation?} entry per leg in dependency order — a 'skip' names the check that blocked it and is NOT a pass. Run this first when any act tool (storage/reload/eval/open) errors unexpectedly. Wraps `extension doctor`.",
+    description: "Diagnose a dev session end-to-end: ready contract, dev-server process, control-port agreement, control channel, eval token, executor, and browser liveness. Returns one {check, status, detail, remediation?} entry per leg in dependency order — a 'skip' names the check that blocked it and is NOT a pass. Run this first when any act tool (storage/reload/eval/open) errors unexpectedly. Wraps `extension doctor`. Call with no projectPath for a pre-flight environment check (node, extension CLI, template cache) before any project exists.",
     inputSchema: {
         type: "object",
         properties: {
             projectPath: {
                 type: "string",
-                description: "Path to the extension project root"
+                description: "Path to the extension project root. Omit for a pre-flight environment check with no project."
             },
             browser: {
                 type: "string",
                 description: "Browser session to diagnose. Defaults to the active dev session's browser for this project."
             }
-        },
-        required: [
-            "projectPath"
-        ]
+        }
     }
 };
+async function environmentPreflight() {
+    const checks = [];
+    const nodeMajor = Number(process.versions.node.split(".")[0]);
+    checks.push({
+        check: "node",
+        status: nodeMajor >= 20 ? "pass" : "fail",
+        detail: `Node ${process.versions.node} on ${process.platform}/${process.arch}`,
+        remediation: nodeMajor >= 20 ? void 0 : "Extension.js needs Node >= 20.18."
+    });
+    const { code, stdout, stderr } = await runExtensionCli([
+        "--version"
+    ], {
+        timeoutMs: 60000
+    });
+    const cliVersion = stdout.trim() || stderr.trim();
+    checks.push({
+        check: "extension-cli",
+        status: 0 === code ? "pass" : "fail",
+        detail: 0 === code ? `extension CLI resolvable (${cliVersion})` : "extension CLI could not be resolved",
+        remediation: 0 === code ? void 0 : "Install locally (npm i -D extension) or rely on npx; check network access to the npm registry."
+    });
+    const cacheFile = node_path.join(node_os.homedir(), ".cache", "extension-js", "templates-meta.json");
+    const cacheExists = node_fs.existsSync(cacheFile);
+    checks.push({
+        check: "template-cache",
+        status: cacheExists ? "pass" : "warn",
+        detail: cacheExists ? `Template catalog cached at ${cacheFile}` : "Template catalog not cached yet (first extension_list_templates will fetch it)"
+    });
+    const healthy = checks.every((c)=>"fail" !== c.status);
+    return JSON.stringify({
+        mode: "environment",
+        healthy,
+        checks,
+        hint: "Pass projectPath to diagnose a live dev session end-to-end."
+    });
+}
 async function doctor_handler(args) {
-    const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
+    if (!args.projectPath) return environmentPreflight();
+    const projectPath = args.projectPath;
+    const { browser } = resolveSessionBrowser(projectPath, args.browser);
     const { code, stdout, stderr } = await runExtensionCli([
         "doctor",
-        args.projectPath,
+        projectPath,
         "--browser",
         browser,
         "--output",
         "json"
     ], {
-        cwd: args.projectPath
+        cwd: projectPath
     });
     const out = stdout.trim();
     try {
@@ -4363,9 +4947,21 @@ async function doctor_handler(args) {
             if ("string" == typeof check.detail) check.detail = toMcpSpeak(check.detail);
             if ("string" == typeof check.remediation) check.remediation = toMcpSpeak(check.remediation);
         }
+        let healthy = 0 === code;
+        const contract = doctor_readReadyContract(projectPath, browser);
+        if (contract?.status === "error") {
+            healthy = false;
+            const detail = contract.errors && contract.errors.length ? contract.errors.join("; ") : contract.message || "The dev session recorded status: error in ready.json.";
+            checks.push({
+                check: "runtime-errors",
+                status: "fail",
+                detail: toMcpSpeak(detail),
+                remediation: "The build or extension load failed. Fix the reported error, let the dev server recompile, then re-run doctor."
+            });
+        }
         return JSON.stringify({
             browser,
-            healthy: 0 === code,
+            healthy,
             checks
         });
     } catch  {
@@ -4412,6 +5008,55 @@ function checkPrimitive(path, value, schema, issues) {
         });
     }
 }
+const ARG_ALIASES = {
+    projectPath: [
+        "path",
+        "dir",
+        "projectDir",
+        "cwd"
+    ],
+    projectName: [
+        "name"
+    ],
+    parentDir: [
+        "parent",
+        "into"
+    ],
+    slug: [
+        "template",
+        "templateSlug"
+    ],
+    expression: [
+        "code",
+        "js",
+        "script"
+    ],
+    manifestPath: [
+        "manifest"
+    ],
+    surface: [
+        "view"
+    ]
+};
+function normalizeArgAliases(inputSchema, args) {
+    const schema = inputSchema;
+    const props = schema.properties ?? {};
+    const out = {
+        ...args
+    };
+    for (const [canonical, aliases] of Object.entries(ARG_ALIASES))if (canonical in props) {
+        if (void 0 === out[canonical]) {
+            for (const alias of aliases)if (!(alias in props)) {
+                if (void 0 !== out[alias]) {
+                    out[canonical] = out[alias];
+                    delete out[alias];
+                    break;
+                }
+            }
+        }
+    }
+    return out;
+}
 function validateToolInput(inputSchema, args) {
     const schema = inputSchema;
     const issues = [];
@@ -4510,7 +5155,8 @@ async function startServer() {
             ],
             isError: true
         };
-        const issues = validateToolInput(tool.schema.inputSchema, args ?? {});
+        const normalizedArgs = normalizeArgAliases(tool.schema.inputSchema, args ?? {});
+        const issues = validateToolInput(tool.schema.inputSchema, normalizedArgs);
         if (issues.length) return {
             content: [
                 {
@@ -4521,7 +5167,7 @@ async function startServer() {
             isError: true
         };
         try {
-            const result = await tool.handler(args ?? {});
+            const result = await tool.handler(normalizedArgs);
             return {
                 content: [
                     {
@@ -4599,6 +5245,31 @@ async function runCli(cmd, args) {
         const apiBase = resolveApiBase(flag("api"));
         try {
             const config = await fetchLoginConfig(apiBase);
+            if ("extensiondev" === config.provider) {
+                const start = await requestDeviceCode({
+                    apiBase,
+                    path: config.deviceCodeUrl,
+                    project
+                });
+                log("");
+                log(`  Open ${start.verificationUri} and enter code: ${start.userCode}`);
+                log("");
+                log("  Waiting for authorization...");
+                const poll = await pollDeviceToken({
+                    apiBase,
+                    path: config.deviceTokenUrl,
+                    project,
+                    deviceCode: start.deviceCode,
+                    interval: start.interval,
+                    budgetMs: 1000 * start.expiresIn
+                });
+                if (!poll.ok) {
+                    log("denied" === poll.reason ? "Authorization was denied at extension.dev/device." : "expired" === poll.reason ? "The device code expired. Run login again." : "Timed out waiting for authorization. Run login again.");
+                    return 1;
+                }
+                log(`Logged in to ${poll.creds.workspaceSlug}/${poll.creds.projectSlug}.`);
+                return 0;
+            }
             const start = await startDeviceCode({
                 clientId: config.clientId,
                 scope: config.scope