@sdods/cli 0.3.2 → 0.5.2

package/dist/commands/browsers.d.ts

@@ -1,17 +1,31 @@
 import type { Command } from 'commander';
+type Engine = 'chromium' | 'firefox' | 'webkit';
 export interface BrowserStatus {
     name: string;
-    engine: 'chromium' | 'firefox' | 'webkit';
+    engine: Engine;
+    /** The branded channel this browser launches, when it is not the bundled build. */
+    channel: string | null;
     installed: boolean;
     executable: string | null;
     playwrightVersion: string;
 }
 export declare function browserStatuses(names?: string[]): Promise<BrowserStatus[]>;
-/** Install browser engines (used by `browsers install`, `doctor --fix`, `init`). */
+/** Install browser engines and channels (used by `browsers install`, `doctor --fix`, `init`). */
 export declare function installBrowsers(opts?: {
     browsers?: string[];
     withDeps?: boolean;
     cwd?: string;
 }): Promise<void>;
+/**
+ * Opens and closes each browser once.
+ *
+ * A browser that has never run sets up its profile on first launch, and an automation run started
+ * before that finishes dies with "Target page, context or browser has been closed" — seen on a
+ * freshly installed Edge, where the first `sdods run -b edge` failed every scenario and the
+ * identical rerun passed every one. Anywhere a browser is provisioned and used in the same job,
+ * this makes the first run deterministic.
+ */
+export declare function warmupBrowsers(names: string[]): Promise<string[]>;
 export declare function register(program: Command): void;
+export {};
 //# sourceMappingURL=browsers.d.ts.map

package/dist/commands/browsers.js

@@ -1,19 +1,60 @@
 import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
+import { join } from 'node:path';
 import { execa } from 'execa';
 import pc from 'picocolors';
 import { BrowserSchema } from '@sdods/contracts';
 import { SdodsError } from '@sdods/core';
 import { createContext } from '../context.js';
 import { collect, json, ok, table } from '../ui.js';
+// Typed against BrowserName (not `string`) so a new browser is a compile error here rather than a
+// silent fall-through to chromium.
 const ENGINE_OF = {
     chromium: 'chromium',
+    edge: 'chromium',
     firefox: 'firefox',
     webkit: 'webkit',
     'mobile-chrome': 'chromium',
     'mobile-safari': 'webkit',
 };
-export async function browserStatuses(names = Object.keys(ENGINE_OF)) {
+/**
+ * Browsers that are a system install of a branded channel rather than a Playwright download.
+ * `playwright install msedge` runs the vendor installer; there is nothing in the browsers cache to
+ * find afterwards, which is why these need their own install target and their own detection.
+ */
+const CHANNEL_OF = { edge: 'msedge' };
+/** Browsers Playwright downloads, i.e. the ones a bare `browsers list` can expect to be present. */
+const DOWNLOADED_BROWSERS = Object.keys(ENGINE_OF).filter((b) => !CHANNEL_OF[b]);
+/**
+ * Where the stable Microsoft Edge binary lives, mirroring Playwright's own channel resolution.
+ * `playwright-core`'s `executablePath()` cannot answer this: for a channel browser it returns the
+ * bundled Chromium path, which exists on nearly every machine and would report Edge as installed
+ * when it is not.
+ */
+function channelExecutable(channel) {
+    if (channel !== 'msedge')
+        return null;
+    if (process.platform === 'darwin')
+        return '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge';
+    if (process.platform === 'linux')
+        return '/opt/microsoft/msedge/msedge';
+    if (process.platform === 'win32') {
+        const suffix = join('Microsoft', 'Edge', 'Application', 'msedge.exe');
+        const roots = [
+            process.env.LOCALAPPDATA,
+            process.env.PROGRAMFILES,
+            process.env['PROGRAMFILES(X86)'],
+        ].filter((r) => Boolean(r));
+        for (const root of roots) {
+            const candidate = join(root, suffix);
+            if (existsSync(candidate))
+                return candidate;
+        }
+        return roots.length ? join(roots[0], suffix) : null;
+    }
+    return null;
+}
+export async function browserStatuses(names = DOWNLOADED_BROWSERS) {
     const require = createRequire(import.meta.url);
     let pw;
     let version = 'unknown';
@@ -25,6 +66,7 @@ export async function browserStatuses(names = Object.keys(ENGINE_OF)) {
         return names.map((name) => ({
             name,
             engine: ENGINE_OF[name] ?? 'chromium',
+            channel: CHANNEL_OF[name] ?? null,
             installed: false,
             executable: null,
             playwrightVersion: version,
@@ -32,9 +74,10 @@ export async function browserStatuses(names = Object.keys(ENGINE_OF)) {
     }
     return names.map((name) => {
         const engine = ENGINE_OF[name] ?? 'chromium';
+        const channel = CHANNEL_OF[name] ?? null;
         let executable = null;
         try {
-            executable = pw[engine].executablePath();
+            executable = channel ? channelExecutable(channel) : pw[engine].executablePath();
         }
         catch {
             executable = null;
@@ -42,51 +85,111 @@ export async function browserStatuses(names = Object.keys(ENGINE_OF)) {
         return {
             name,
             engine,
+            channel,
             installed: Boolean(executable && existsSync(executable)),
             executable,
             playwrightVersion: version,
         };
     });
 }
-/** Install browser engines (used by `browsers install`, `doctor --fix`, `init`). */
+/** Install browser engines and channels (used by `browsers install`, `doctor --fix`, `init`). */
 export async function installBrowsers(opts = {}) {
-    const engines = [
-        ...new Set((opts.browsers?.length ? opts.browsers : Object.keys(ENGINE_OF)).map((b) => ENGINE_OF[b] ?? b)),
-    ];
-    const args = ['playwright', 'install', ...(opts.withDeps ? ['--with-deps'] : []), ...engines];
-    await execa('npx', args, { stdio: 'inherit', cwd: opts.cwd });
+    const names = (opts.browsers?.length ? opts.browsers : DOWNLOADED_BROWSERS);
+    const engines = [...new Set(names.filter((b) => !CHANNEL_OF[b]).map((b) => ENGINE_OF[b] ?? b))];
+    const channels = [...new Set(names.map((b) => CHANNEL_OF[b]).filter((c) => !!c))];
+    if (engines.length) {
+        const args = ['playwright', 'install', ...(opts.withDeps ? ['--with-deps'] : []), ...engines];
+        await execa('npx', args, { stdio: 'inherit', cwd: opts.cwd });
+    }
+    // Channels are a system install run by the vendor's own installer, so `--with-deps` does not
+    // apply and they cannot share the engine invocation.
+    for (const channel of channels) {
+        await execa('npx', ['playwright', 'install', channel], { stdio: 'inherit', cwd: opts.cwd });
+    }
+}
+/**
+ * Opens and closes each browser once.
+ *
+ * A browser that has never run sets up its profile on first launch, and an automation run started
+ * before that finishes dies with "Target page, context or browser has been closed" — seen on a
+ * freshly installed Edge, where the first `sdods run -b edge` failed every scenario and the
+ * identical rerun passed every one. Anywhere a browser is provisioned and used in the same job,
+ * this makes the first run deterministic.
+ */
+export async function warmupBrowsers(names) {
+    const pw = (await import('playwright-core'));
+    const warmed = [];
+    for (const name of names) {
+        const engine = ENGINE_OF[name] ?? 'chromium';
+        const channel = CHANNEL_OF[name];
+        const browser = await pw[engine].launch({ headless: true, ...(channel ? { channel } : {}) });
+        await browser.close();
+        warmed.push(name);
+    }
+    return warmed;
 }
 export function register(program) {
     const browsers = program.command('browsers').description('Install and list browser engines');
     browsers
         .command('install')
-        .description('Install browser engines (default: chromium, firefox, webkit)')
+        .description('Install browsers (default: chromium, firefox, webkit)')
+        // The positional form reads naturally and is what the docs have always shown, but Commander
+        // rejects excess positionals by default, so `browsers install chromium` failed outright.
+        .argument('[browsers...]', 'browsers to install, e.g. chromium edge')
         .option('-b, --browser <name>', 'browser to install (repeatable)', collect, [])
         .option('--with-deps', 'also install OS dependencies (Linux CI)')
         .option('-p, --project <slug>', 'install the browsers declared by a project')
-        .action(async (opts, cmd) => {
+        .action(async (positional, opts, cmd) => {
         const ctx = createContext(cmd);
-        let list = opts.browser;
+        let list = [...positional, ...opts.browser];
         if (opts.project)
             list = ctx.registry.get(opts.project).browsers;
         for (const b of list)
             BrowserSchema.parse(b);
         await installBrowsers({ browsers: list, withDeps: opts.withDeps, cwd: ctx.rootDir });
-        ok(`Installed ${list.length ? list.join(', ') : 'chromium, firefox, webkit'}`);
+        ok(`Installed ${list.length ? list.join(', ') : DOWNLOADED_BROWSERS.join(', ')}`);
+    });
+    browsers
+        .command('warmup')
+        .description('Launch each browser once so the first real run is not its first launch')
+        .option('-b, --browser <name>', 'browser to warm up (repeatable)', collect, [])
+        .option('-p, --project <slug>', 'warm up the browsers declared by a project')
+        .action(async (opts, cmd) => {
+        const ctx = createContext(cmd);
+        let list = opts.browser;
+        if (!list.length && opts.project)
+            list = ctx.registry.get(opts.project).browsers;
+        if (!list.length)
+            list = [...DOWNLOADED_BROWSERS];
+        for (const b of list)
+            BrowserSchema.parse(b);
+        const warmed = await warmupBrowsers(list);
+        ok(`Warmed up ${warmed.join(', ')}`);
     });
     browsers
         .command('list')
         .description('Show which browsers are installed and where; exits 1 if any is missing')
         .option('-p, --project <slug>', 'limit to the browsers declared by a project')
+        .option('-b, --browser <name>', 'limit to one browser (repeatable)', collect, [])
         .action(async (opts, cmd) => {
         const ctx = createContext(cmd);
-        const names = opts.project ? ctx.registry.get(opts.project).browsers : Object.keys(ENGINE_OF);
+        // A bare `browsers list` reports the browsers Playwright downloads. Channel browsers are a
+        // system install that most machines will not have, and exiting 1 for a missing Edge nobody
+        // asked for would turn this into a permanently failing command.
+        const names = opts.browser.length
+            ? opts.browser
+            : opts.project
+                ? ctx.registry.get(opts.project).browsers
+                : DOWNLOADED_BROWSERS;
+        for (const b of names)
+            BrowserSchema.parse(b);
         const statuses = await browserStatuses(names);
         if (ctx.opts.json)
             return json(statuses);
         table(statuses.map((s) => ({
             browser: s.name,
             engine: s.engine,
+            channel: s.channel ?? '',
             installed: s.installed ? pc.green('yes') : pc.red('no'),
             playwright: s.playwrightVersion,
             executable: s.executable ?? '',

package/dist/commands/config.js

@@ -16,13 +16,17 @@ export function registerConfigCommands(program) {
         const cfg = ctx.registry.resolve(opts.project, opts.env);
         const view = opts.showSecrets ? cfg : redact(cfg);
         if (opts.explain) {
-            const rows = explainConfig(cfg).map((r) => ({
-                path: r.path,
-                layer: r.layer,
-                value: typeof r.value === 'object'
-                    ? JSON.stringify(r.value)
-                    : String(opts.showSecrets ? r.value : redactLeaf(r.path, r.value)),
-            }));
+            // Values come from the same redacted tree as the other views, so --explain can never show
+            // what plain `config show` hides (it used to apply a weaker regex of its own).
+            const tree = { project: view.project, env: view.env, runtime: view.runtime };
+            const rows = explainConfig(cfg).map((r) => {
+                const value = valueAt(tree, r.path);
+                return {
+                    path: r.path,
+                    layer: r.layer,
+                    value: typeof value === 'object' ? JSON.stringify(value) : String(value),
+                };
+            });
             if (ctx.opts.json)
                 return json(rows);
             return table(rows, ['path', 'layer', 'value']);
@@ -71,9 +75,13 @@ export function registerConfigCommands(program) {
             process.exitCode = 2;
     });
 }
-function redactLeaf(path, value) {
-    return /(password|secret|token|apikey|api_key)/i.test(path) && typeof value === 'string' && value
-        ? '***'
-        : value;
+function valueAt(tree, path) {
+    let cur = tree;
+    for (const seg of path.split('.')) {
+        if (cur === null || typeof cur !== 'object')
+            return undefined;
+        cur = cur[seg];
+    }
+    return cur;
 }
 //# sourceMappingURL=config.js.map

package/dist/commands/doctor.js

@@ -4,6 +4,8 @@ import { execa } from 'execa';
 import pc from 'picocolors';
 import { collectVarRefs, loadDotEnvLayer, loadEnvFile } from '@sdods/core';
 import { createContext } from '../context.js';
+import { browserStatuses } from './browsers.js';
+import { MIN_PLAYWRIGHT_FOR_STEP_RESULTS, installedPlaywrightVersion, stepResultsWarning, } from '../runner-compat.js';
 import { json, out } from '../ui.js';
 export function registerDoctorCommand(program) {
     program
@@ -23,6 +25,17 @@ export function registerDoctorCommand(program) {
         });
         checks.push(await versionCheck('bun', ['--version'], 'optional: bun install/build are faster'));
         checks.push(await versionCheck('runner', ['playwright', '--version'], 'install workspace dependencies: bun install (or npm install)', 'npx'));
+        const runnerVersion = installedPlaywrightVersion(ctx.rootDir);
+        if (runnerVersion) {
+            checks.push({
+                name: 'step results',
+                ok: !stepResultsWarning(runnerVersion),
+                detail: stepResultsWarning(runnerVersion)
+                    ? `@playwright/test ${runnerVersion} records every Gherkin step SKIPPED in messages.ndjson`
+                    : `@playwright/test ${runnerVersion} (>= ${MIN_PLAYWRIGHT_FOR_STEP_RESULTS})`,
+                fix: `npm i -D @playwright/test@^${MIN_PLAYWRIGHT_FOR_STEP_RESULTS} (or bun add -d)`,
+            });
+        }
         const browsers = await browserCheck();
         checks.push(...browsers);
         if (opts.fix && browsers.some((b) => !b.ok)) {
@@ -297,27 +310,18 @@ async function versionCheck(name, args, fix, bin = name) {
     }
 }
 async function browserCheck() {
-    const out = [];
-    for (const b of ['chromium', 'firefox', 'webkit']) {
-        try {
-            const mod = await import('playwright-core');
-            const path = mod[b].executablePath();
-            out.push({
-                name: `browser:${b}`,
-                ok: existsSync(path),
-                detail: existsSync(path) ? path : 'not installed',
-                fix: `sdods browsers install -b ${b}`,
-            });
-        }
-        catch {
-            out.push({
-                name: `browser:${b}`,
-                ok: false,
-                detail: 'browser runner not resolvable',
-                fix: 'install workspace dependencies: bun install (or npm install)',
-            });
-        }
-    }
-    return out;
+    // Reuses `browsers list`'s detection so the two commands can never disagree about what is
+    // installed — and so channel browsers are probed by path rather than by the bundled engine's
+    // executable, which exists whether or not the branded browser does.
+    const statuses = await browserStatuses(['chromium', 'edge', 'firefox', 'webkit']);
+    return statuses.map((s) => ({
+        name: `browser:${s.name}`,
+        ok: s.installed,
+        detail: s.installed ? (s.executable ?? 'installed') : 'not installed',
+        fix: `sdods browsers install -b ${s.name}`,
+        // Edge is a system browser a project opts into. A machine that does not run Edge suites should
+        // not get a red doctor for not having it.
+        optional: Boolean(s.channel),
+    }));
 }
 //# sourceMappingURL=doctor.js.map

package/dist/commands/features.js

@@ -1,5 +1,5 @@
 import { relative } from 'node:path';
-import { listFeatureFiles, parseFeatureFile, scenariosOf } from '@sdods/core';
+import { listFeatureFiles, normalizeTagExpr, parseFeatureFile, parseTagExpr, scenariosOf, } from '@sdods/core';
 import { createContext } from '../context.js';
 import { json, table } from '../ui.js';
 export function register(program) {
@@ -8,18 +8,20 @@ export function register(program) {
         .command('list')
         .description('List features with module, layer, suite, scenario count and tags')
         .requiredOption('-p, --project <slug>', 'project slug')
-        .option('--tags <expr>', 'only scenarios carrying this tag (simple @tag filter)')
+        .option('--tags <expr>', 'only scenarios matching this tag expression (as in `sdods run`)')
         .option('--scenarios', 'one row per scenario instead of per feature')
         .action((opts, cmd) => {
         const ctx = createContext(cmd);
         const cfg = ctx.registry.resolve(opts.project);
+        const tagExpr = normalizeTagExpr(opts.tags);
+        const selector = tagExpr ? parseTagExpr(tagExpr) : undefined;
         const rows = [];
         for (const file of listFeatureFiles(cfg.project.root)) {
             const rel = relative(cfg.project.root, file).replace(/\\/g, '/');
             const parsed = parseFeatureFile(file);
             const mod = ctx.registry.moduleOfFeature(opts.project, rel)?.name ?? '';
-            const scenarios = scenariosOf(parsed).filter((s) => !opts.tags || s.tags.includes(opts.tags));
-            if (!scenarios.length && opts.tags)
+            const scenarios = scenariosOf(parsed).filter((s) => !selector || selector.evaluate(s.tags));
+            if (!scenarios.length && selector)
                 continue;
             if (opts.scenarios) {
                 for (const s of scenarios) {

package/dist/commands/init.js

@@ -136,7 +136,9 @@ export async function initWorkspace(target, flags) {
             '@sdods/cli': dep('@sdods/cli'),
             '@sdods/core': dep('@sdods/core'),
             '@sdods/contracts': dep('@sdods/contracts'),
-            '@playwright/test': flags.link && flags.pm === 'bun' ? 'link:@playwright/test' : '^1.62.1',
+            // 1.63 is the floor, not a preference: below it an npm-installed workspace records every
+            // Gherkin step SKIPPED in messages.ndjson (see runner-compat.ts).
+            '@playwright/test': flags.link && flags.pm === 'bun' ? 'link:@playwright/test' : '^1.63.0',
             'playwright-bdd': flags.link && flags.pm === 'bun' ? 'link:playwright-bdd' : '^9.2.0',
         },
         devDependencies: {
@@ -338,7 +340,7 @@ Docs: https://docs.sdods.com
         browsersInstalled = res.exitCode === 0;
     }
     if (flags.claude) {
-        const res = await execa('npx', ['sdods', 'agent', 'install-claude'], {
+        const res = await execa('npx', ['-y', '@sdods/cli', 'agent', 'install-claude'], {
             cwd: target,
             reject: false,
             stdio: 'pipe',

package/dist/commands/integrations.js

@@ -1,10 +1,10 @@
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import pc from 'picocolors';
-import { SdodsError, DEFAULT_ARTIFACTS_DIR, Logger } from '@sdods/core';
+import { DEFAULT_ARTIFACTS_DIR } from '@sdods/core';
 import { createContext } from '../context.js';
+import { LINKS_FILE, notifyRun } from '../notify.js';
 import { json, ok, out, table, warn } from '../ui.js';
-const LINKS_FILE = ['.sdods', 'issue-links.json'];
 /** `sdods integrations test|notify|sync|links` — GitHub and Jira without the server or a database. */
 export function register(program) {
     const cmd = program
@@ -15,6 +15,7 @@ export function register(program) {
         .description('Check credentials and reachability for each enabled provider')
         .requiredOption('-p, --project <slug>', 'project slug')
         .option('--provider <name>', 'only this provider (github|jira)')
+        .option('--create-labels', 'create configured GitHub labels the repository is missing')
         .action(async (opts, c) => {
         const ctx = createContext(c);
         const entry = ctx.registry.entry(opts.project);
@@ -45,13 +46,14 @@ export function register(program) {
                 });
                 continue;
             }
-            const res = await p.provider.test();
+            const res = await p.provider.test({ createMissingLabels: Boolean(opts.createLabels) });
             rows.push({
                 provider: p.name,
                 enabled: true,
                 ok: res.ok,
                 detail: res.detail,
                 secrets: fmtSecrets(p.secrets),
+                ...(ctx.opts.json && res.labels ? { labels: res.labels } : {}),
             });
         }
         if (ctx.opts.json)
@@ -77,47 +79,16 @@ export function register(program) {
         .option('--artifacts-dir <dir>', 'artifacts root', DEFAULT_ARTIFACTS_DIR)
         .action(async (opts, c) => {
         const ctx = createContext(c);
-        const { buildRunSummaryFromFiles, getProviders, createIntegrationContext, FileIssueLinkStore, } = await import('@sdods/integrations');
-        const artifactsRoot = join(ctx.rootDir, opts.artifactsDir);
-        const runDir = join(artifactsRoot, opts.runId);
-        if (!existsSync(runDir)) {
-            throw new SdodsError('RUN_FAILED', `Run directory not found: ${runDir}`, {
-                hint: 'Pass --artifacts-dir or check the run id (sdods report --last).',
-                exitCode: 2,
-            });
-        }
-        const summary = buildRunSummaryFromFiles(runDir, {
+        const { summary, slug, actions: results, } = await notifyRun({
+            rootDir: ctx.rootDir,
+            registry: ctx.registry,
+            artifactsRoot: join(ctx.rootDir, opts.artifactsDir),
+            runId: opts.runId,
             projectSlug: opts.project,
             reportUrl: opts.reportUrl,
-        });
-        const slug = summary.run.projectSlug;
-        const entry = ctx.registry.entry(slug);
-        const providers = await getProviders(entry.config, {
-            only: opts.provider ? [opts.provider] : undefined,
-            projectRoot: entry.root,
-        });
-        const ictx = createIntegrationContext({
-            store: new FileIssueLinkStore(join(ctx.rootDir, ...LINKS_FILE)),
-            logger: new Logger('integrations'),
             dryRun: Boolean(opts.dryRun),
-            artifactsRoot,
+            only: opts.provider ? [opts.provider] : undefined,
         });
-        const results = [];
-        for (const p of providers) {
-            if (!p.enabled)
-                continue;
-            if (p.initError) {
-                results.push({ provider: p.name, kind: 'skipped', detail: p.initError });
-                continue;
-            }
-            try {
-                const res = await p.provider.onRunFinished(summary, ictx);
-                results.push(...res.actions);
-            }
-            catch (e) {
-                results.push({ provider: p.name, kind: 'error', detail: e.message });
-            }
-        }
         if (ctx.opts.json)
             return json({ run: summary.run, totals: summary.totals, actions: results });
         const t = summary.totals;

package/dist/commands/mcp.js

@@ -1,11 +1,18 @@
 import pc from 'picocolors';
 import { SdodsError } from '@sdods/core';
+import { ALL_CAPABILITIES, DEFAULT_CAPABILITIES } from '@sdods/mcp';
 import { createContext } from '../context.js';
 import { json, ok, out } from '../ui.js';
 const CLIENTS = ['claude', 'codex', 'cursor', 'vscode', 'windsurf'];
+/**
+ * The default capability list, derived rather than restated. It used to be spelled out in three
+ * places in this file — the fallback, the flag default and the "did the user change it" sentinel —
+ * so adding a capability silently left the CLI handing out the old set.
+ */
+const DEFAULT_CAPS = DEFAULT_CAPABILITIES.join(',');
 function capsOf(raw) {
     if (!raw || raw === 'all')
-        return raw === 'all' ? 'all' : ['core', 'analyze', 'run', 'data', 'schedules'];
+        return raw === 'all' ? 'all' : [...DEFAULT_CAPABILITIES];
     return raw
         .split(',')
         .map((s) => s.trim())
@@ -17,7 +24,7 @@ export function register(program) {
         .description('Start the SDODS MCP server (stdio by default) or install client configuration')
         .option('-p, --project <slug>', 'default project for tools and prompts')
         .option('-e, --env <name>', 'default environment')
-        .option('--caps <list>', 'capabilities: core,analyze,run,data,agents,issues,schedules or "all"', 'core,analyze,run,data,schedules')
+        .option('--caps <list>', `capabilities: ${ALL_CAPABILITIES.join(',')} or "all"`, DEFAULT_CAPS)
         .option('--http', 'serve streamable HTTP instead of stdio')
         .option('--port <n>', 'HTTP port', '4001')
         .option('--host <host>', 'HTTP host', '127.0.0.1')
@@ -79,7 +86,7 @@ export function register(program) {
         .option('--caps <list>')
         .option('--http-url <url>', 'configure the HTTP transport instead of stdio')
         .option('--token-placeholder <text>', 'placeholder written for the bearer token')
-        .option('--no-playwright', 'do not add the bundled Playwright MCP server')
+        .option('--with-playwright', 'also register the raw upstream Playwright MCP server (ungoverned; the sdods server already wraps it as browser_*)')
         .option('--file', 'always write the config file instead of calling `claude mcp add` / `codex mcp add`')
         .option('--print', 'print the snippet instead of writing files')
         .action(async (client, opts, cmd) => {
@@ -96,11 +103,10 @@ export function register(program) {
         const o = {
             project: opts.project ?? parent.project,
             env: opts.env ?? parent.env,
-            caps: opts.caps ??
-                (parent.caps !== 'core,analyze,run,data,schedules' ? parent.caps : undefined),
+            caps: opts.caps ?? (parent.caps !== DEFAULT_CAPS ? parent.caps : undefined),
             httpUrl: opts.httpUrl,
             tokenPlaceholder: opts.tokenPlaceholder,
-            withPlaywright: opts.playwright !== false,
+            withPlaywright: opts.withPlaywright === true,
         };
         const s = snippets(o)[client];
         if (opts.print || ctx.opts.json) {
@@ -117,7 +123,7 @@ export function register(program) {
             const done = await registerViaClientCli(client, o, ctx.rootDir);
             if (done) {
                 ok(`Registered the sdods MCP server with ${client} (${cliCommands(o)[client]})`);
-                if (o.withPlaywright && client === 'codex')
+                if (o.withPlaywright === true && client === 'codex')
                     out(pc.dim('Also registered the bundled Playwright MCP server as "playwright".'));
                 return;
             }
@@ -131,7 +137,10 @@ export function register(program) {
 /** `claude mcp add` (project scope) or `codex mcp add`; false when the CLI is unavailable. */
 async function registerViaClientCli(client, o, cwd) {
     const { execa } = await import('execa');
-    const stdio = ['npx', 'sdods', 'mcp'];
+    // `npx sdods` resolves only when the cwd happens to sit inside a checkout that has the binary in
+    // node_modules/.bin. From anywhere else npx goes to the registry, where no package named `sdods`
+    // exists, and the client reports CONNECTION_CLOSED. Name the package that owns the bin instead.
+    const stdio = ['npx', '-y', '@sdods/cli', 'mcp'];
     if (o.project)
         stdio.push('--project', o.project);
     if (o.env)
@@ -168,7 +177,7 @@ async function registerViaClientCli(client, o, cwd) {
     const ok1 = await run(addArgs);
     if (!ok1)
         return false;
-    if (o.withPlaywright !== false) {
+    if (o.withPlaywright === true) {
         const pw = client === 'claude'
             ? [
                 'mcp',