@webpresso/agent-kit 0.25.0 → 0.26.1

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Webpresso agent-kit Claude Code plugin: blueprints, skills, hooks, MCP server",
-    "version": "0.25.0"
+    "version": "0.26.1"
   },
   "plugins": [
     {
@@ -23,5 +23,5 @@
       ]
     }
   ],
-  "version": "0.25.0"
+  "version": "0.26.1"
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "webpresso",
-  "version": "0.25.0",
+  "version": "0.26.1",
   "description": "Webpresso agent-kit: blueprints, skills, lore commit protocol, tech-debt lifecycle",
   "skills": "./skills",
   "commands": "./commands",

package/dist/esm/audit/toolchain-isolation.d.ts

@@ -0,0 +1,3 @@
+import type { RepoAuditResult } from './repo-guardrails.js';
+export declare function auditToolchainIsolation(root: string): RepoAuditResult;
+//# sourceMappingURL=toolchain-isolation.d.ts.map

package/dist/esm/audit/toolchain-isolation.js

@@ -0,0 +1,139 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+const FORBIDDEN_DEPENDENCY_PATTERNS = [
+    /^typescript$/u,
+    /^vite$/u,
+    /^vitest$/u,
+    /^@stryker-mutator\//u,
+    /^@playwright\/test$/u,
+    /^wrangler$/u,
+    /^oxlint$/u,
+    /^oxfmt$/u,
+    /^tsx$/u,
+];
+const FORBIDDEN_SCRIPT_PATTERNS = [
+    /(^|\s)(tsc|vite|vitest|stryker|playwright|wrangler|oxlint|oxfmt|tsx)(\s|$)/u,
+    /node\s+\.\/node_modules\/(typescript|vite|vitest|wrangler|oxlint|tsx)\//u,
+];
+const ALLOWED_SCRIPT_PREFIXES = ['wp ', 'vp run ', 'vp run -r '];
+export function auditToolchainIsolation(root) {
+    const packagePaths = findPackageJsonFiles(root);
+    const violations = [];
+    for (const packagePath of packagePaths) {
+        const pkg = readPackageJson(packagePath);
+        if (!pkg) {
+            violations.push({ file: packagePath, message: 'package.json must be valid JSON' });
+            continue;
+        }
+        if (isExemptPackage(root, packagePath, pkg))
+            continue;
+        for (const field of [
+            'dependencies',
+            'devDependencies',
+            'optionalDependencies',
+            'peerDependencies',
+        ]) {
+            for (const depName of Object.keys(pkg[field] ?? {})) {
+                if (!isForbiddenDependency(depName))
+                    continue;
+                violations.push({
+                    file: packagePath,
+                    message: `${field}.${depName} is toolchain-owned; route it through @webpresso/agent-kit/wp instead of declaring it directly`,
+                });
+            }
+        }
+        for (const [scriptName, scriptValue] of Object.entries(pkg.scripts ?? {})) {
+            if (typeof scriptValue !== 'string')
+                continue;
+            if (isAllowedScript(scriptValue))
+                continue;
+            if (!FORBIDDEN_SCRIPT_PATTERNS.some((pattern) => pattern.test(scriptValue)))
+                continue;
+            violations.push({
+                file: packagePath,
+                message: `script "${scriptName}" invokes a toolchain binary directly; use wp-managed commands instead`,
+            });
+        }
+    }
+    return {
+        ok: violations.length === 0,
+        title: 'Toolchain isolation',
+        checked: packagePaths.length,
+        violations,
+    };
+}
+function isExemptPackage(root, packagePath, pkg) {
+    if (pkg.name === '@webpresso/agent-kit')
+        return true;
+    const relativePath = path.relative(root, packagePath).split(path.sep).join('/');
+    // Catalog skill templates are sample project manifests shipped by agent-kit,
+    // not live consumer package manifests. They intentionally demonstrate raw
+    // framework CLIs in generated starter content and should not make agent-kit's
+    // own audit fail.
+    const unpackedPath = relativePath.replace(/^\.webpresso-packed-surface\//u, '');
+    if (unpackedPath.startsWith('catalog/') && unpackedPath.includes('/templates/'))
+        return true;
+    return false;
+}
+function findPackageJsonFiles(root) {
+    const files = [];
+    walk(root, files);
+    return files.sort();
+}
+function walk(dir, files) {
+    for (const entry of safeReadDir(dir)) {
+        const absolute = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (!shouldSkipDirectory(entry.name))
+                walk(absolute, files);
+            continue;
+        }
+        if (entry.isFile() && entry.name === 'package.json')
+            files.push(absolute);
+    }
+}
+function safeReadDir(dir) {
+    try {
+        return existsSync(dir) ? readdirSync(dir, { withFileTypes: true }) : [];
+    }
+    catch {
+        return [];
+    }
+}
+function shouldSkipDirectory(name) {
+    return [
+        '.git',
+        'node_modules',
+        'dist',
+        'build',
+        '.turbo',
+        '.next',
+        '.wrangler',
+        '.agent',
+        '.agents',
+        '.omx',
+        '.omc',
+        '.codex',
+        // Gitignored Claude Code agent surface — agent worktree scratch under
+        // .claude/worktrees/* carries vendored package manifests that are not the
+        // repo's own packages; walking it produces false positives on local dev
+        // machines and in consumer repos that run agent worktrees.
+        '.claude',
+    ].includes(name);
+}
+function readPackageJson(file) {
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function isForbiddenDependency(depName) {
+    return FORBIDDEN_DEPENDENCY_PATTERNS.some((pattern) => pattern.test(depName));
+}
+function isAllowedScript(script) {
+    const trimmed = script.trim();
+    return ALLOWED_SCRIPT_PREFIXES.some((prefix) => trimmed.startsWith(prefix));
+}
+//# sourceMappingURL=toolchain-isolation.js.map

package/dist/esm/cli/cli.d.ts

@@ -5,7 +5,7 @@
  * Lazy-loads subcommand modules based on the first argv to keep startup
  * cheap. Modeled on apps/cli-wp/src/cli.ts.
  */
-declare const SUPPORTED_COMMANDS: readonly ["blueprint", "config", "roadmap", "sync", "audit", "compile", "rule", "skill", "skills", "docs", "setup", "init", "dev", "doctor", "err", "test", "e2e", "ci", "typecheck", "lint", "format", "tech-debt", "worktree", "mcp", "hook", "hooks", "gain", "bench", "install", "add", "remove", "update", "exec", "run"];
+declare const SUPPORTED_COMMANDS: readonly ["blueprint", "config", "roadmap", "sync", "audit", "compile", "rule", "skill", "skills", "docs", "setup", "init", "dev", "deploy", "doctor", "err", "test", "e2e", "ci", "typecheck", "lint", "format", "tech-debt", "worktree", "mcp", "hook", "hooks", "gain", "bench", "install", "add", "remove", "update", "exec", "run"];
 export { SUPPORTED_COMMANDS };
 export declare function main(): Promise<number>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/esm/cli/cli.js

@@ -27,6 +27,7 @@ const SUPPORTED_COMMANDS = [
     'setup',
     'init',
     'dev',
+    'deploy',
     'doctor',
     'err',
     'test',
@@ -209,6 +210,11 @@ export async function main() {
             registerDevCommand(cli);
             break;
         }
+        case 'deploy': {
+            const { registerDeployCommand } = await import('./commands/deploy.js');
+            registerDeployCommand(cli);
+            break;
+        }
         case 'doctor': {
             const { registerDoctorCommand } = await import('./commands/doctor.js');
             registerDoctorCommand(cli);

package/dist/esm/cli/commands/audit-core.d.ts

@@ -1,5 +1,5 @@
 import type { RepoAuditResult } from '#audit/repo-guardrails';
-export type AuditKind = 'tph' | 'tph-e2e' | 'bundle-budget' | 'commit-message' | 'blueprint-lifecycle' | 'roadmap-links' | 'docs-frontmatter' | 'catalog-drift' | 'package-surface' | 'agents' | 'tech-debt' | 'no-relative-parent-imports' | 'no-link-protocol' | 'vision' | 'bucket-boundary' | 'skill-sizes' | 'broken-refs' | 'memory-rotation' | 'gitignore-agent-surfaces' | 'memory-unified' | 'compile-drift' | 'architecture-drift' | 'cloudflare-deploy-contract' | 'absolute-path-policy' | 'agent-cost' | 'blueprint-db-consistency' | 'blueprint-lifecycle-sql' | 'tech-debt-cadence' | 'cross-repo-correlation' | 'ai-contracts' | 'mutation' | 'quality' | 'guardrails' | 'hook-surface' | 'no-relative-package-scripts';
+export type AuditKind = 'tph' | 'tph-e2e' | 'bundle-budget' | 'commit-message' | 'blueprint-lifecycle' | 'roadmap-links' | 'docs-frontmatter' | 'catalog-drift' | 'package-surface' | 'agents' | 'tech-debt' | 'no-relative-parent-imports' | 'no-link-protocol' | 'vision' | 'bucket-boundary' | 'skill-sizes' | 'broken-refs' | 'memory-rotation' | 'gitignore-agent-surfaces' | 'memory-unified' | 'compile-drift' | 'architecture-drift' | 'cloudflare-deploy-contract' | 'toolchain-isolation' | 'absolute-path-policy' | 'agent-cost' | 'blueprint-db-consistency' | 'blueprint-lifecycle-sql' | 'tech-debt-cadence' | 'cross-repo-correlation' | 'ai-contracts' | 'mutation' | 'quality' | 'guardrails' | 'hook-surface' | 'no-relative-package-scripts';
 export type AuditOutcome = {
     kind: 'invalid-usage';
     message: string;

package/dist/esm/cli/commands/audit.js

@@ -59,6 +59,7 @@ const REPO_AUDIT_REGISTRY = {
     'no-legacy-cli-bin': async (root) => (await import('#audit/no-legacy-cli-bin')).auditNoLegacyCliBin(root),
     'architecture-drift': async (root) => (await import('#audit/architecture-drift')).auditArchitectureDrift(root),
     'cloudflare-deploy-contract': async (root) => (await import('#audit/cloudflare-deploy-contract')).auditCloudflareDeployContract(root),
+    'toolchain-isolation': async (root) => (await import('#audit/toolchain-isolation')).auditToolchainIsolation(root),
     'absolute-path-policy': async (root) => (await import('#audit/absolute-path-policy')).auditAbsolutePathPolicy(root),
     'agent-cost': async (root) => (await import('#audit/agent-cost')).auditAgentCost(root),
     'blueprint-db-consistency': async (root) => (await import('#audit/blueprint-db-consistency')).auditBlueprintDbConsistency(root),

package/dist/esm/cli/commands/deploy.d.ts

@@ -0,0 +1,4 @@
+import type { CAC } from 'cac';
+export declare const DEPLOY_COMMAND_HELP: string;
+export declare function registerDeployCommand(cli: CAC): void;
+//# sourceMappingURL=deploy.d.ts.map

package/dist/esm/cli/commands/deploy.js

@@ -0,0 +1,35 @@
+import { runDeployPlan } from '#deploy/run.js';
+export const DEPLOY_COMMAND_HELP = [
+    'Run a consumer-owned deploy adapter through the managed wp deploy surface.',
+    '',
+    'Examples:',
+    '  wp deploy --lane prd --dry-run',
+    '  wp deploy --lane preview_pr_123 --plan-json',
+].join('\n');
+export function registerDeployCommand(cli) {
+    cli
+        .command('deploy', DEPLOY_COMMAND_HELP)
+        .option('--lane <lane>', 'Deploy lane: dev, preview_main, preview_pr_<n>, or prd')
+        .option('--dry-run', 'Ask the adapter for its dry-run deploy plan')
+        .option('--plan-json', 'Print the validated deploy plan JSON without executing steps')
+        .action(async (options) => {
+        const lane = typeof options.lane === 'string' ? options.lane : undefined;
+        if (!lane) {
+            console.error('Usage: wp deploy --lane <dev|preview_main|preview_pr_<n>|prd>');
+            return 1;
+        }
+        try {
+            return await runDeployPlan({
+                cwd: process.cwd(),
+                lane,
+                dryRun: Boolean(options.dryRun),
+                planJson: Boolean(options.planJson),
+            });
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            return 1;
+        }
+    });
+}
+//# sourceMappingURL=deploy.js.map

package/dist/esm/cli/commands/init/gitignore-patcher.d.ts

@@ -3,7 +3,24 @@ export interface GitignoreBlock {
     id: string;
     patterns: readonly string[];
 }
+export type GeneratedIndexCleanupResult = {
+    kind: 'skipped-dry-run';
+    pathspecs: readonly string[];
+} | {
+    kind: 'skipped-not-git';
+    pathspecs: readonly string[];
+} | {
+    kind: 'ok';
+    pathspecs: readonly string[];
+    removedPaths: readonly string[];
+} | {
+    kind: 'failed';
+    pathspecs: readonly string[];
+    exitCode: number | null;
+    stderr: string;
+};
 /** Canonical gitignore block for webpresso generated/transient paths. */
 export declare const GENERATED_PATHS_BLOCK: GitignoreBlock;
+export declare function untrackGeneratedGitignoredPaths(repoRoot: string, block?: GitignoreBlock, opts?: Pick<MergeOptions, 'dryRun'>): GeneratedIndexCleanupResult;
 export declare function patchGitignore(targetPath: string, block: GitignoreBlock, opts?: MergeOptions): MergeResult;
 //# sourceMappingURL=gitignore-patcher.d.ts.map

package/dist/esm/cli/commands/init/gitignore-patcher.js

@@ -11,6 +11,7 @@
  * drift). Other content in `.gitignore` — including unrelated managed blocks
  * from other scaffolders — is preserved verbatim.
  */
+import { spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 const BEGIN = (id) => `# >>> managed by webpresso (${id})`;
@@ -55,6 +56,7 @@ export const GENERATED_PATHS_BLOCK = {
         '.opencode/',
         '.codex/',
         '.claude/settings.json',
+        '.claude/settings.local.json',
         '.claude/agents/',
         '.claude/hooks/',
         '.claude/rules/',
@@ -77,6 +79,46 @@ export const GENERATED_PATHS_BLOCK = {
         '.agent/.tail-hint-history.jsonl',
     ],
 };
+function generatedPathspecs(block) {
+    return block.patterns
+        .map((pattern) => pattern.trim())
+        .filter((pattern) => pattern.length > 0)
+        .filter((pattern) => !pattern.startsWith('#'))
+        .filter((pattern) => !pattern.startsWith('!'));
+}
+function parseGitRmStdout(stdout) {
+    return stdout
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith('rm '))
+        .map((line) => line.replace(/^rm ['"]?/, '').replace(/['"]?$/, ''));
+}
+export function untrackGeneratedGitignoredPaths(repoRoot, block = GENERATED_PATHS_BLOCK, opts = {}) {
+    const pathspecs = generatedPathspecs(block);
+    if (opts.dryRun)
+        return { kind: 'skipped-dry-run', pathspecs };
+    if (pathspecs.length === 0)
+        return { kind: 'ok', pathspecs, removedPaths: [] };
+    const gitProbe = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], {
+        cwd: repoRoot,
+        encoding: 'utf8',
+    });
+    if (gitProbe.status !== 0)
+        return { kind: 'skipped-not-git', pathspecs };
+    const gitRm = spawnSync('git', ['rm', '--cached', '-r', '--ignore-unmatch', '--', ...pathspecs], {
+        cwd: repoRoot,
+        encoding: 'utf8',
+    });
+    if (gitRm.status !== 0) {
+        return {
+            kind: 'failed',
+            pathspecs,
+            exitCode: gitRm.status,
+            stderr: String(gitRm.stderr ?? '').trim(),
+        };
+    }
+    return { kind: 'ok', pathspecs, removedPaths: parseGitRmStdout(String(gitRm.stdout ?? '')) };
+}
 export function patchGitignore(targetPath, block, opts = {}) {
     const exists = existsSync(targetPath);
     const original = exists ? readFileSync(targetPath, 'utf8') : '';

package/dist/esm/cli/commands/init/index.js

@@ -22,7 +22,7 @@ import { scaffoldAgent, RENDERED_SKILLS, TIER1_SKILLS, TIER2_SKILLS } from './sc
 import { scaffoldAgentRules } from './scaffold-agent-rules.js';
 import { scaffoldAgentSkills } from './scaffold-agent-skills.js';
 import { scaffoldCatalogIgnore } from './scaffold-catalog-ignore.js';
-import { GENERATED_PATHS_BLOCK, patchGitignore } from './gitignore-patcher.js';
+import { GENERATED_PATHS_BLOCK, patchGitignore, untrackGeneratedGitignoredPaths, } from './gitignore-patcher.js';
 import { scaffoldAgentsMd } from './scaffold-agents-md.js';
 import { scaffoldBlueprints } from './scaffold-blueprints.js';
 import { scaffoldDocs } from './scaffold-docs.js';
@@ -35,7 +35,7 @@ import { scaffoldAuditHooks } from './scaffolders/audit-hooks/index.js';
 import { ensureClaudeCodeUserPlugin } from './scaffolders/claude-plugin/index.js';
 import { scaffoldClaudeRules } from './scaffolders/claude-rules/index.js';
 import { ensureCodexCli } from './scaffolders/codex-cli/index.js';
-import { ensureCodexWebpressoMcp, ensureCodexPlaywrightMcp } from './scaffolders/codex-mcp/index.js';
+import { ensureCodexWebpressoMcp, ensureCodexPlaywrightMcp, ensureClaudePlaywrightMcp, } from './scaffolders/codex-mcp/index.js';
 import { scaffoldExampleSkill } from './scaffolders/example-skill/index.js';
 import { ensureGstack } from './scaffolders/gstack/index.js';
 import { scaffoldLoreCommits } from './scaffolders/lore-commits/index.js';
@@ -244,6 +244,7 @@ export async function runInit(flags) {
             overwrite: options.overwrite,
         });
         const generatedSurfaceIgnoreResult = patchGitignore(join(consumer.repoRoot, '.gitignore'), GENERATED_PATHS_BLOCK, { dryRun: options.dryRun, overwrite: true });
+        const generatedIndexCleanupResult = untrackGeneratedGitignoredPaths(consumer.repoRoot, GENERATED_PATHS_BLOCK, { dryRun: options.dryRun });
         const baseKitResults = tier3Selection.includes('base-kit')
             ? scaffoldBaseKit({
                 catalogDir,
@@ -436,6 +437,24 @@ export async function runInit(flags) {
                     console.log('  codex playwright mcp: skipped (--dry-run)');
                     break;
             }
+            const claudePlaywrightMcpResult = ensureClaudePlaywrightMcp({
+                options,
+                repoRoot: consumer.repoRoot,
+            });
+            switch (claudePlaywrightMcpResult.kind) {
+                case 'claude-playwright-mcp-written':
+                    console.log(`  claude playwright mcp: ✓ ${claudePlaywrightMcpResult.path}`);
+                    break;
+                case 'claude-playwright-mcp-unchanged':
+                    console.log(`  claude playwright mcp: already configured at ${claudePlaywrightMcpResult.path}`);
+                    break;
+                case 'claude-playwright-mcp-skipped-dry-run':
+                    console.log('  claude playwright mcp: skipped (--dry-run)');
+                    break;
+                case 'claude-playwright-mcp-invalid-json':
+                    console.warn(`  claude playwright mcp: ⚠ ${claudePlaywrightMcpResult.path} is not valid JSON; left unchanged`);
+                    break;
+            }
         }
         if (presets.includes('omx')) {
             agentHooksResult = await scaffoldAgentHooks({
@@ -669,6 +688,15 @@ export async function runInit(flags) {
         console.log(`  drifted:         ${summary.drifted}`);
         if (options.dryRun)
             console.log(`  would-change:    ${summary['skipped-dry']}`);
+        if (generatedIndexCleanupResult.kind === 'ok') {
+            console.log(`  git index cleanup: ${generatedIndexCleanupResult.removedPaths.length} untracked`);
+        }
+        else if (generatedIndexCleanupResult.kind === 'failed') {
+            console.warn(`  git index cleanup: failed (git rm --cached exited ${generatedIndexCleanupResult.exitCode})`);
+            if (generatedIndexCleanupResult.stderr.length > 0) {
+                console.warn(`  git index cleanup stderr: ${generatedIndexCleanupResult.stderr}`);
+            }
+        }
         if (tier3Selection.includes('base-kit')) {
             const qualityTargets = new Set(BASE_KIT_QUALITY_TARGETS);
             const qualityResults = baseKitResults.filter((result) => qualityTargets.has(relative(consumer.repoRoot, result.targetPath).replaceAll('\\', '/')));

package/dist/esm/cli/commands/init/scaffold-base-kit.js

@@ -138,7 +138,7 @@ function mergePackageJson(repoRoot, options, globalInstall = false) {
     const devDeps = (pkg['devDependencies'] ?? {});
     const hasAgentKitDevDep = typeof devDeps['@webpresso/agent-kit'] === 'string';
     const hasLegacyAgentKitDevDep = typeof devDeps['webpresso'] === 'string';
-    const shouldSkipSelfInstall = packageName === '@webpresso/agent-kit' || packageName === 'webpresso';
+    const shouldSkipSelfInstall = isSelfPackageName(packageName);
     const shouldManageAgentKitAsGlobal = globalInstall && !shouldSkipSelfInstall;
     const requiredAuthoringDeps = {
         '@playwright/test': 'latest',
@@ -236,10 +236,35 @@ function mergePackageJson(repoRoot, options, globalInstall = false) {
     writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
     return { targetPath: pkgPath, action: 'overwritten' };
 }
+/** agent-kit's own package identities: scoped canonical + legacy unscoped. */
+const SELF_PACKAGE_NAMES = ['@webpresso/agent-kit', 'webpresso'];
+/** True when `name` is one of agent-kit's own package identities. */
+function isSelfPackageName(name) {
+    return name !== undefined && SELF_PACKAGE_NAMES.includes(name);
+}
+/**
+ * True when `repoRoot` is agent-kit's own source repo (by package.json name).
+ * agent-kit dogfoods base-kit's scripts and shared templates, but the QUALITY
+ * starter samples (quality-sample.ts, e2e/smoke, sample configs) are teaching
+ * artifacts for FRESH consumer repos — scaffolding them into agent-kit's own
+ * source tree is pollution. This flag skips ONLY those samples.
+ */
+function isAgentKitSelfRepo(repoRoot) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(repoRoot, 'package.json'), 'utf8'));
+        return isSelfPackageName(pkg.name);
+    }
+    catch {
+        return false;
+    }
+}
 export function scaffoldBaseKit(input) {
     const { catalogDir, repoRoot, options, globalInstall = false } = input;
     const baseKitDir = join(catalogDir, 'base-kit');
     const results = [];
+    // Dogfooding boundary: agent-kit gets base-kit's scripts/templates but not the
+    // starter quality samples scaffolded into its own source tree.
+    const skipStarterSamples = isAgentKitSelfRepo(repoRoot);
     for (const [tmplRel, targetRel] of TEMPLATE_MAP) {
         const tmplPath = join(baseKitDir, tmplRel);
         if (!existsSync(tmplPath))
@@ -269,23 +294,25 @@ export function scaffoldBaseKit(input) {
         writeFileSync(targetPath, content);
         results.push({ targetPath, action: 'created' });
     }
-    for (const [tmplRel, targetRel] of QUALITY_BOOTSTRAP_ONLY_MAP) {
-        const tmplPath = join(baseKitDir, tmplRel);
-        if (!existsSync(tmplPath))
-            continue;
-        const targetPath = join(repoRoot, targetRel);
-        if (existsSync(targetPath)) {
-            results.push({ targetPath, action: 'identical' });
-            continue;
-        }
-        const content = readFileSync(tmplPath, 'utf8');
-        if (options.dryRun) {
-            results.push({ targetPath, action: 'skipped-dry' });
-            continue;
+    if (!skipStarterSamples) {
+        for (const [tmplRel, targetRel] of QUALITY_BOOTSTRAP_ONLY_MAP) {
+            const tmplPath = join(baseKitDir, tmplRel);
+            if (!existsSync(tmplPath))
+                continue;
+            const targetPath = join(repoRoot, targetRel);
+            if (existsSync(targetPath)) {
+                results.push({ targetPath, action: 'identical' });
+                continue;
+            }
+            const content = readFileSync(tmplPath, 'utf8');
+            if (options.dryRun) {
+                results.push({ targetPath, action: 'skipped-dry' });
+                continue;
+            }
+            mkdirSync(dirname(targetPath), { recursive: true });
+            writeFileSync(targetPath, content);
+            results.push({ targetPath, action: 'created' });
         }
-        mkdirSync(dirname(targetPath), { recursive: true });
-        writeFileSync(targetPath, content);
-        results.push({ targetPath, action: 'created' });
     }
     // Make husky hook files executable
     if (!options.dryRun) {

package/dist/esm/cli/commands/init/scaffolders/codex-cli/index.js

@@ -20,7 +20,11 @@ export function ensureCodexCli(input) {
         }
     }
     else if (!shouldSkipCodexRefresh()) {
-        spawn('vp', ['update', '-g', '@openai/codex'], { stdio: 'inherit' });
+        // `--latest` ignores the recorded semver range so the global is pulled to
+        // the absolute newest published release, matching the force-to-latest
+        // guarantee `vp install -g <bare>` gives the agent-kit self-update. Plain
+        // `vp update -g` is range-bound and can strand the global on an old major.
+        spawn('vp', ['update', '-g', '--latest', '@openai/codex'], { stdio: 'inherit' });
     }
     return { kind: 'codex-cli-ok', installed };
 }

package/dist/esm/cli/commands/init/scaffolders/codex-mcp/index.d.ts

@@ -1,7 +1,7 @@
 import type { MergeOptions } from '#cli/commands/init/merge';
 export declare const PLAYWRIGHT_MCP_SERVER_NAME = "playwright";
 export declare const PLAYWRIGHT_MCP_HEADER = "[mcp_servers.playwright]";
-export declare const PLAYWRIGHT_MCP_BLOCK = "[mcp_servers.playwright]\ncommand = \"vp\"\nargs = [\"dlx\", \"@playwright/mcp@latest\", \"--caps=testing,storage,network,devtools\"]\nenabled = true\nstartup_timeout_sec = 30\n";
+export declare const PLAYWRIGHT_MCP_BLOCK: string;
 export declare const WEBPRESSO_MCP_SERVER_NAME = "webpresso";
 export declare const WEBPRESSO_MCP_HEADER = "[mcp_servers.webpresso]";
 export interface EnsureCodexPlaywrightMcpInput {
@@ -21,6 +21,34 @@ export type EnsureCodexPlaywrightMcpResult = {
 };
 export declare function upsertPlaywrightMcpServer(raw: string): string;
 export declare function ensureCodexPlaywrightMcp(input: EnsureCodexPlaywrightMcpInput): EnsureCodexPlaywrightMcpResult;
+/**
+ * Upsert the `playwright` server into a `.mcp.json` document, preserving every
+ * other server (e.g. `context7`, `exa`) and any non-server top-level keys.
+ * Output is normalized to 2-space JSON with a trailing newline so repeated runs
+ * converge — idempotent after the first write.
+ */
+export declare function upsertClaudePlaywrightMcpServer(raw: string): string;
+export interface EnsureClaudePlaywrightMcpInput {
+    options: MergeOptions;
+    /** Project root whose `.mcp.json` is managed. */
+    repoRoot: string;
+    /** Test seam. Defaults to `<repoRoot>/.mcp.json`. */
+    configPath?: string;
+}
+export type EnsureClaudePlaywrightMcpResult = {
+    kind: 'claude-playwright-mcp-written';
+    path: string;
+} | {
+    kind: 'claude-playwright-mcp-unchanged';
+    path: string;
+} | {
+    kind: 'claude-playwright-mcp-skipped-dry-run';
+    path: string;
+} | {
+    kind: 'claude-playwright-mcp-invalid-json';
+    path: string;
+};
+export declare function ensureClaudePlaywrightMcp(input: EnsureClaudePlaywrightMcpInput): EnsureClaudePlaywrightMcpResult;
 export interface WebpressoInstallProbe {
     /** Test seam — override the candidate roots. Default: probe in fixed order. */
     candidates?: readonly string[];

package/dist/esm/cli/commands/init/scaffolders/codex-mcp/index.js

@@ -22,10 +22,27 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 export const PLAYWRIGHT_MCP_SERVER_NAME = 'playwright';
+/**
+ * Single source of truth for how the Playwright MCP server is launched. Both
+ * the Codex TOML block and the Claude Code `.mcp.json` block render from these.
+ * The portable `vp dlx` facade fetches the npm-published server on demand, so
+ * there is no machine-specific bin path to rot — the failure mode a hand-
+ * authored `~/.bun/bin/playwright-mcp` entry hits the moment that global bin
+ * disappears (ENOENT on spawn).
+ */
+const PLAYWRIGHT_MCP_COMMAND = 'vp';
+const PLAYWRIGHT_MCP_ARGS = [
+    'dlx',
+    '@playwright/mcp@latest',
+    '--caps=testing,storage,network,devtools',
+];
+function tomlStringArray(values) {
+    return `[${values.map((value) => `"${value}"`).join(', ')}]`;
+}
 export const PLAYWRIGHT_MCP_HEADER = `[mcp_servers.${PLAYWRIGHT_MCP_SERVER_NAME}]`;
 export const PLAYWRIGHT_MCP_BLOCK = `${PLAYWRIGHT_MCP_HEADER}
-command = "vp"
-args = ["dlx", "@playwright/mcp@latest", "--caps=testing,storage,network,devtools"]
+command = "${PLAYWRIGHT_MCP_COMMAND}"
+args = ${tomlStringArray(PLAYWRIGHT_MCP_ARGS)}
 enabled = true
 startup_timeout_sec = 30
 `;
@@ -70,6 +87,59 @@ export function ensureCodexPlaywrightMcp(input) {
     writeFileSync(configPath, next, 'utf8');
     return { kind: 'codex-playwright-mcp-written', path: configPath };
 }
+function claudePlaywrightServer() {
+    return { command: PLAYWRIGHT_MCP_COMMAND, args: [...PLAYWRIGHT_MCP_ARGS] };
+}
+function isJsonRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function parseJson(raw) {
+    try {
+        return { ok: true, value: JSON.parse(raw) };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+/**
+ * Upsert the `playwright` server into a `.mcp.json` document, preserving every
+ * other server (e.g. `context7`, `exa`) and any non-server top-level keys.
+ * Output is normalized to 2-space JSON with a trailing newline so repeated runs
+ * converge — idempotent after the first write.
+ */
+export function upsertClaudePlaywrightMcpServer(raw) {
+    const parsed = raw.trim().length > 0 ? parseJson(raw) : { ok: true, value: {} };
+    if (!parsed.ok) {
+        throw new Error('cannot upsert playwright into .mcp.json: existing file is not valid JSON');
+    }
+    const root = isJsonRecord(parsed.value) ? parsed.value : {};
+    const servers = isJsonRecord(root.mcpServers) ? root.mcpServers : {};
+    const next = {
+        ...root,
+        mcpServers: {
+            ...servers,
+            [PLAYWRIGHT_MCP_SERVER_NAME]: claudePlaywrightServer(),
+        },
+    };
+    return `${JSON.stringify(next, null, 2)}\n`;
+}
+export function ensureClaudePlaywrightMcp(input) {
+    const configPath = input.configPath ?? join(input.repoRoot, '.mcp.json');
+    if (input.options.dryRun) {
+        return { kind: 'claude-playwright-mcp-skipped-dry-run', path: configPath };
+    }
+    const existing = existsSync(configPath) ? readFileSync(configPath, 'utf8') : '';
+    if (existing.trim().length > 0 && !parseJson(existing).ok) {
+        return { kind: 'claude-playwright-mcp-invalid-json', path: configPath };
+    }
+    const next = upsertClaudePlaywrightMcpServer(existing);
+    if (next === existing) {
+        return { kind: 'claude-playwright-mcp-unchanged', path: configPath };
+    }
+    mkdirSync(dirname(configPath), { recursive: true });
+    writeFileSync(configPath, next, 'utf8');
+    return { kind: 'claude-playwright-mcp-written', path: configPath };
+}
 // ────────────────────────────────────────────────────────────────────────────
 // Agent-kit MCP server registration
 // ────────────────────────────────────────────────────────────────────────────