shipscreens 0.1.5 → 0.1.7

package/bin/shipscreens.js

@@ -12,12 +12,25 @@ import { runExportFramefile } from '../cli/commands/exportFramefile.js';
 import { runVerify } from '../cli/commands/verify.js';
 import { runStage } from '../cli/commands/stage.js';
 import { runPlan } from '../cli/commands/plan.js';
+import {
+  renderInspectReleaseContextSummary,
+  runInspectReleaseContext,
+} from '../cli/commands/inspectReleaseContext.js';
+import { renderPlanReleaseSummary, runPlanRelease } from '../cli/commands/planRelease.js';
+import {
+  renderWriteStarterConfigSummary,
+  runWriteStarterConfig,
+} from '../cli/commands/writeStarterConfig.js';
+import { renderImportScreenshotsSummary, runImportScreenshots } from '../cli/commands/importScreenshots.js';
+import { renderCaptureScreenshotsSummary, runCaptureScreenshots } from '../cli/commands/captureScreenshots.js';
 import { runAuth } from '../cli/commands/auth.js';
 import { runInit } from '../cli/commands/init.js';
 import { runWizard } from '../cli/commands/wizard.js';
 import { runCopyImport } from '../cli/commands/copyImport.js';
+import { runCopyCheck } from '../cli/commands/copyCheck.js';
 import { resolveCliAuth } from '../cli/auth.js';
 import { listTemplateIds, resolveTemplateConfig } from '../cli/templateConfig.js';
+import { listMcpBootstrapClients, runMcpInit } from '../cli/mcpBootstrap.js';
 import { runMcpServer } from '../cli/mcpServer.js';
 import { loadShipScreensConfig } from '../cli/loadConfig.js';
 import { collectAssetReferences } from '../cli/assetRefs.js';
@@ -30,6 +43,7 @@ import {
 
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const DEMO_SCREENS_DIR = path.join(PACKAGE_ROOT, 'cli', 'assets', 'demo-screens');
+const MCP_BOOTSTRAP_CLIENT_LIST = listMcpBootstrapClients().join('|');
 
 function printHelp() {
   console.log(`ShipScreens CLI
@@ -37,62 +51,95 @@ function printHelp() {
 Usage:
   shipscreens init [--dir <path>] [--slides <n>] [--locales <id,id>] [--devices <id,id>] [--force] [--wizard] [--style <value>] [--template <id>]
   shipscreens wizard [--dir <path>] [--force] [--style <value>] [--template <id>] [--defaults]
-  shipscreens demo [--out <dir>] [--slides <n>] [--locales <id,id>] [--devices <id,id>] [--template <id>] [--mode <raw|rendered>] [--zip-out <path>] [--profile <appstore|playstore|any>] [--force]
-  shipscreens agent-run [--dir <path>] [--slides <n>] [--locales <id,id>] [--devices <id,id>] [--style <value>] [--template <id>] [--mode <raw|rendered>] [--out <dir>] [--zip] [--profile <appstore|playstore|any>] [--require-pro] [--force]
+  shipscreens demo [--out <dir>] [--slides <n>] [--locales <id,id>] [--devices <id,id>] [--template <id>] [--mode <raw|rendered>] [--zip-out <path>] [--profile <appstore|playstore|any>] [--variant <id>] [--force]
+  shipscreens agent-run [--dir <path>] [--slides <n>] [--locales <id,id>] [--devices <id,id>] [--style <value>] [--template <id>] [--mode <raw|rendered>] [--out <dir>] [--zip] [--profile <appstore|playstore|any>] [--variant <id>] [--stage] [--stage-out <dir>] [--report-json <path>] [--report-md <path>] [--require-pro] [--force]
   shipscreens devices [--json]
   shipscreens templates [--json]
   shipscreens validate [-c shipscreens.config.yml]
   shipscreens lock [-c shipscreens.config.yml] [--out shipscreens.lock.json] [--check]
-  shipscreens build [-c shipscreens.config.yml] [--mode shipscreens|rendered|raw|frameit] [--format dir|zip] [--out <dir>] [--zip] [--zip-out <path>] [--clean]
-  shipscreens verify [-c shipscreens.config.yml] [--out <dir>] [--zip] [--zip-out <path>] [--profile appstore|playstore|any]
-  shipscreens stage [-c shipscreens.config.yml] [--from <dir>] --out <dir> [--profile appstore|playstore|any]
+  shipscreens build [-c shipscreens.config.yml] [--mode shipscreens|rendered|raw|frameit] [--format dir|zip] [--out <dir>] [--zip] [--zip-out <path>] [--variant <id>] [--clean]
+  shipscreens verify [-c shipscreens.config.yml] [--out <dir>] [--zip] [--zip-out <path>] [--profile appstore|playstore|any] [--variant <id>]
+  shipscreens stage [-c shipscreens.config.yml] [--from <dir>] --out <dir> [--profile appstore|playstore|any] [--variant <id>]
+  shipscreens inspect-release-context [--dir <path>] [-c shipscreens.config.yml] [--json]
+  shipscreens plan-release [--dir <path>] [-c shipscreens.config.yml] [--profile appstore|playstore|any] [--mode raw|rendered] [--out <dir>] [--stage-out <dir>] [--json]
+  shipscreens write-starter-config [--dir <path>] [--profile appstore|playstore|any] [--slides <n>] [--locales <id,id>] [--devices <id,id>] [--template <id>] [--out <dir>] [--stage-out <dir>] [--force] [--json]
+  shipscreens capture-screenshots [--dir <path>] [--platform auto|android|ios-simulator|ios-device] [--device <id>] [--out screenshots] [--locale <id>] [--slot <n>] [--name <file.png>] [--profile appstore|playstore|any] [--list] [--json]
+  shipscreens import-screenshots [--dir <path>] [-c shipscreens.config.yml] [--from <dir>] [--locale <id|all>] [--profile appstore|playstore|any] [--out <dir>] [--stage-out <dir>] [--force] [--allow-partial] [--json]
   shipscreens export framefile [-c shipscreens.config.yml] [--ios-dir fastlane/screenshots] [--strings-encoding utf8|utf16le|utf16be] [--framefile-strategy merge|overwrite] [--check]
-  shipscreens plan [-c shipscreens.config.yml] [--out <dir>] [--zip-out <path>] [--profile appstore|playstore|any] [--json]
+  shipscreens plan [-c shipscreens.config.yml] [--out <dir>] [--zip-out <path>] [--profile appstore|playstore|any] [--variant <id>] [--json]
   shipscreens copy import [-c shipscreens.config.yml] [--csv <path>] [--import-mode merge|replace]
+  shipscreens copy check [-c shipscreens.config.yml] [--pseudo-locale <id>] [--pseudo-expand <n>] [--max-header-units <n>] [--max-sub-units <n>] [--max-token-length <n>] [--write-pseudo-csv <path>] [--write-report-json <path>] [--strict]
   shipscreens auth <login|finish|status|logout> [--domain <cognito-domain>] [--client-id <id>] [--api-base <url>] [--port <port>] [--manual] [--redirect-url <url>]
   shipscreens mcp serve
+  shipscreens mcp init --client <${MCP_BOOTSTRAP_CLIENT_LIST}> [--dir <path>] [--package-spec <spec>] [--windows-cmd-shim] [--force]
 
 Commands:
   init       Create a starter config + placeholder PNGs + copy.csv
   wizard     Step-by-step setup (locales/devices/template)
   demo       Create a demo project + export (no assets required)
-  agent-run  Non-interactive end-to-end flow (init -> validate -> build -> verify)
+  agent-run  Non-interactive end-to-end flow (init -> validate -> build -> verify -> optional stage/report)
   devices    List device ids (for shipscreens.config.yml)
-  templates  List style template ids (for init/wizard/agent-run)
+  templates  List style template ids (for init/wizard/write-starter-config/agent-run)
   validate   Validate shipscreens.config.yml (schema + asset paths)
   lock       Generate shipscreens.lock.json with sha256 hashes
   build      Generate Fastlane-ready outputs (headless Chromium, zero-padded filenames)
   verify     Verify Fastlane outputs (dir and/or zip)
   stage      Copy only upload-ready files into a new root
+  inspect-release-context  Inspect config, Fastlane roots, devices/locales, and missing assets
+  plan-release  Turn inspection into the next safe agent/CLI command sequence
+  write-starter-config  Non-interactively create config + copy.csv + placeholder PNGs for agents
+  capture-screenshots  Capture the currently visible connected device/emulator screen into a local source folder
+  import-screenshots  Copy existing screenshots into configured asset paths
   export     Export helper files for other tools
   plan       Print a deterministic build/stage plan (JSON)
   copy       Import locale copy from copy.csv into shipscreens.config.yml
+    check    Run pseudo-locale + long-string checks for submission quality
   auth       Manage CLI sign-in (required to remove watermarks in CLI exports)
-  mcp        Start a stdio MCP server that exposes ShipScreens tools
+  mcp        Start a stdio MCP server or write workspace-local MCP config
 
 Options:
   -c, --config <path>   Path to shipscreens.config.yml (default: ./shipscreens.config.yml)
-  --dir <path>          Output directory for init (default: .)
-  --slides <n>          Number of slides to scaffold (init, default: 5, max: 10)
-  --locales <list>      Comma-separated locales for init (default: en-US)
-  --devices <list>      Comma-separated device ids for init (default: iphone69,pixel8)
-  --force               Overwrite files when running init
+  --dir <path>          Output directory for init/write-starter-config (default: .)
+  --slides <n>          Number of slides to scaffold (init/write-starter-config, default: 5, max: 10)
+  --locales <list>      Comma-separated locales for init/write-starter-config (default: en-US)
+  --devices <list>      Comma-separated device ids for init/write-starter-config (default: iphone69,pixel8)
+  --force               Overwrite files when running init/write-starter-config
   --wizard              Run step-by-step init prompts
   --style <value>       Style preset: default | template:<id> | <template-id>
   --template <id>       Template preset (alias for --style template:<id>)
   --defaults            Skip the style prompt in wizard (use default/no style)
   --csv <path>          Path to copy.csv for copy import (default: ./copy.csv)
   --import-mode <mode>  CSV import mode (merge|replace, default: merge)
+  --pseudo-locale <id>  Locale id prefix for pseudo-locale checks (default: qps-ploc)
+  --pseudo-expand <n>   Pseudo-locale expansion ratio (default: 0.35)
+  --max-header-units <n>  Visual-width budget for headers (default: 34)
+  --max-sub-units <n>   Visual-width budget for subtitles (default: 54)
+  --max-token-length <n>  Long-token budget before wrap risk warning (default: 22)
+  --write-pseudo-csv <path>  Write pseudo-locale CSV rows for manual QA
+  --write-report-json <path>  Write full copy-check report JSON for CI/QA artifacts
+  --strict              Fail copy check when warnings are found
   --out <path>          Lock output file path (lock) or output root directory (build/verify/stage)
   --zip-out <path>      ZIP output file path (default: <out>/fastlane_assets.zip)
   --profile <appstore|playstore|any>  Strict verification/staging rules per store (default: any)
-  --from <dir>          Source output root for staging (default: config dir)
+  --variant <id>        ASO experiment variant scope (writes under variants/<id>/...).
+  --platform <value>    Capture source: auto|android|ios-simulator|ios-device (default: auto)
+  --device <id>         Device serial/UDID/name for capture-screenshots
+  --from <dir>          Source output root for staging, or source screenshots for import-screenshots
+  --locale <id|all>     Locale target for import-screenshots (default: primary config locale)
+  --slot <n>            Slot number for capture filename (01.png..99.png)
+  --name <file.png>     Explicit capture filename
+  --list                List capturable devices instead of writing a screenshot
+  --allow-partial       Let import-screenshots copy fewer images than configured targets
   --check               Verify outputs are valid/up-to-date (no write)
   --json                Emit machine-readable JSON (most commands; plan always emits JSON)
   --mode <shipscreens|rendered|raw|frameit> Build mode (default: rendered). shipscreens=rendered alias, frameit runs raw + export framefile --check
   --format <dir|zip>    Output format (default: dir)
   --zip                 Also write a ZIP (same as --format zip)
   --clean               Delete existing outputs for the current locale/device/bucket before writing
+  --stage               For agent-run, also create a clean upload root after verify
+  --stage-out <dir>     For agent-run, staged upload root (default: <out>-stage; implies --stage)
+  --report-json <path>  For agent-run, write a machine-readable proof report (default with --stage: <out>/shipscreens.agent-report.json)
+  --report-md <path>    For agent-run, write a short Markdown proof summary (default with --stage: <out>/shipscreens.agent-summary.md)
   --require-pro         Fail the build if Pro access is not available
   --manual              Print a login URL instead of starting a local callback server
   --redirect-url <url>  Full redirect URL after manual login (for auth finish)
@@ -102,14 +149,17 @@ Options:
   --android-dir <path>  Android output directory (default: fastlane/metadata/android)
   --strings-encoding <utf8|utf16le|utf16be>  Encoding for generated .strings (export framefile / build --mode frameit) (default: utf8)
   --framefile-strategy <merge|overwrite>  How to handle fastlane/screenshots/Framefile.json (export framefile / build --mode frameit) (default: merge)
+  --client <id>        MCP bootstrap target (${MCP_BOOTSTRAP_CLIENT_LIST}) for "mcp init"
+  --package-spec <spec>  Package spec used in generated MCP config (default: shipscreens@latest)
+  --windows-cmd-shim   Use "cmd /c npx ..." in the generated MCP config
   -h, --help            Show help
 
 Quickstart (no browser):
-  shipscreens wizard
-  shipscreens build --mode raw --zip --out out
-  shipscreens verify --out out --zip --profile appstore
+  shipscreens write-starter-config --profile appstore
+  shipscreens agent-run --mode raw --zip --out out/agent --stage --profile appstore
 
 MCP quickstart:
+  shipscreens mcp init --client cursor
   shipscreens mcp serve
 `);
 }
@@ -180,6 +230,15 @@ async function pathExists(targetPath) {
   }
 }
 
+function parseNumericFlag(name, value) {
+  if (value == null || value === '') return undefined;
+  const num = Number(value);
+  if (!Number.isFinite(num)) {
+    throw new Error(`Invalid --${name} value: ${value}`);
+  }
+  return num;
+}
+
 async function loadDemoScreenPngs() {
   try {
     const entries = await fs.readdir(DEMO_SCREENS_DIR);
@@ -225,6 +284,172 @@ async function findPlaceholderAssets({ configPath }) {
   return matches;
 }
 
+function defaultAgentStageOutDir(outDir) {
+  const raw = String(outDir || 'out/agent').trim() || 'out/agent';
+  const trimmed = raw.replace(/[\\/]+$/, '');
+  return `${trimmed || 'out/agent'}-stage`;
+}
+
+function resolveAgentArtifactPath({ baseDir, filePath }) {
+  const raw = String(filePath || '').trim();
+  if (!raw) return null;
+  return path.isAbsolute(raw) ? raw : path.resolve(baseDir, raw);
+}
+
+async function writeAgentArtifact(filePath, content) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, content, 'utf8');
+}
+
+function coalesceCount(...values) {
+  for (const value of values) {
+    if (Number.isFinite(Number(value))) return Number(value);
+  }
+  return 0;
+}
+
+function createAgentReport({
+  configPath,
+  targetDir,
+  outDir,
+  stageOutDir,
+  zipOut,
+  format,
+  mode,
+  profile,
+  variant,
+  requirePro,
+  build,
+  verify,
+  stage,
+  releaseContext,
+  reportPaths,
+}) {
+  const warnings = [];
+  if (!requirePro) {
+    warnings.push('Free CLI run may include a watermark. Run shipscreens auth login and rerun with --require-pro before production export.');
+  }
+  if (!stage) {
+    warnings.push('No staged upload root was requested. Pass --stage to create a clean deliver/supply root.');
+  }
+
+  const nextSteps = [];
+  if (stage) {
+    nextSteps.push('Review the staged upload root before store submission.');
+  } else {
+    nextSteps.push('Rerun agent-run with --stage to create a clean upload root.');
+  }
+  if (!requirePro) {
+    nextSteps.push('Unlock Pro, then rerun with --require-pro to fail closed if watermark-free export is unavailable.');
+  } else {
+    nextSteps.push('Keep --require-pro in CI so paid export failures stop the release before upload.');
+  }
+
+  return {
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    command: 'agent-run',
+    status: 'ok',
+    workspace: targetDir,
+    configPath,
+    mode,
+    format,
+    profile,
+    variant: variant || null,
+    requirePro: Boolean(requirePro),
+    outputs: {
+      buildRoot: outDir,
+      zipPath: build?.zipPath || verify?.zipPath || zipOut || null,
+      iosDir: verify?.iosDir || build?.iosDir || null,
+      androidDir: verify?.androidDir || build?.androidDir || null,
+      stageRoot: stage?.out || stageOutDir || null,
+      stagedIosDir: stage?.iosDir || null,
+      stagedAndroidDir: stage?.androidDir || null,
+      reportJson: reportPaths.json || null,
+      reportMarkdown: reportPaths.markdown || null,
+    },
+    counts: {
+      locales: coalesceCount(verify?.locales, stage?.locales, build?.locales),
+      slides: coalesceCount(verify?.slides, stage?.slides, build?.slides),
+      iosDevices: coalesceCount(verify?.iosDevices, stage?.iosDevices, build?.iosDevices),
+      androidDevices: coalesceCount(verify?.androidDevices, stage?.androidDevices, build?.androidDevices),
+      stagedFiles: stage ? coalesceCount(stage.files) : null,
+    },
+    warnings,
+    nextSteps,
+    releaseContext: releaseContext
+      ? {
+          storeTarget: releaseContext.storeTarget,
+          config: releaseContext.config,
+          missingAssets: releaseContext.missingAssets,
+          screenshotRoots: releaseContext.screenshotRoots,
+          warnings: releaseContext.warnings,
+          questions: releaseContext.questions,
+          agentHandoff: releaseContext.agentHandoff,
+        }
+      : null,
+    build,
+    verify,
+    stage: stage || null,
+  };
+}
+
+function renderAgentSummaryMarkdown(report) {
+  const releaseContextLines = report.releaseContext
+    ? [
+        '## Release Context',
+        `- Store target: ${report.releaseContext.storeTarget?.profile || 'unknown'} (${report.releaseContext.storeTarget?.confidence || 'unknown'})`,
+        `- Config: ${report.releaseContext.config?.relativePath || 'unknown'} (${report.releaseContext.config?.valid ? 'valid' : 'not ready'})`,
+        `- Missing assets: ${report.releaseContext.missingAssets?.length || 0}`,
+        `- Open questions: ${report.releaseContext.questions?.length || 0}`,
+        '',
+      ]
+    : ['## Release Context', '- Not inspected', ''];
+  const lines = [
+    '# ShipScreens Agent Report',
+    '',
+    `Generated: ${report.generatedAt}`,
+    `Status: ${report.status}`,
+    '',
+    '## Scope',
+    `- Workspace: ${report.workspace}`,
+    `- Config: ${report.configPath}`,
+    `- Mode: ${report.mode}`,
+    `- Format: ${report.format}`,
+    `- Profile: ${report.profile}`,
+    `- Variant: ${report.variant || 'none'}`,
+    `- Require Pro: ${report.requirePro ? 'yes' : 'no'}`,
+    '',
+    ...releaseContextLines,
+    '## Outputs',
+    `- Build root: ${report.outputs.buildRoot}`,
+    `- ZIP: ${report.outputs.zipPath || 'not requested'}`,
+    `- iOS dir: ${report.outputs.iosDir || 'not generated'}`,
+    `- Android dir: ${report.outputs.androidDir || 'not generated'}`,
+    `- Stage root: ${report.outputs.stageRoot || 'not requested'}`,
+    '',
+    '## Verification',
+    `- Locales: ${report.counts.locales}`,
+    `- Slides: ${report.counts.slides}`,
+    `- iOS devices: ${report.counts.iosDevices}`,
+    `- Android devices: ${report.counts.androidDevices}`,
+    '',
+    '## Stage',
+    report.stage
+      ? `- Staged files: ${report.counts.stagedFiles}\n- Staged iOS dir: ${report.outputs.stagedIosDir || 'none'}\n- Staged Android dir: ${report.outputs.stagedAndroidDir || 'none'}`
+      : '- Not requested',
+    '',
+    '## Warnings',
+    ...(report.warnings.length ? report.warnings.map((item) => `- ${item}`) : ['- None']),
+    '',
+    '## Next Steps',
+    ...report.nextSteps.map((item) => `- ${item}`),
+    '',
+  ];
+
+  return `${lines.join('\n')}\n`;
+}
+
 async function main() {
   const { positionals, values } = parseArgs({
     args: process.argv.slice(2),
@@ -238,12 +463,23 @@ async function main() {
       zip: { type: 'boolean' },
       'zip-out': { type: 'string' },
       clean: { type: 'boolean' },
+      stage: { type: 'boolean' },
+      'stage-out': { type: 'string' },
+      'report-json': { type: 'string' },
+      'report-md': { type: 'string' },
       'ios-dir': { type: 'string' },
       'android-dir': { type: 'string' },
       'strings-encoding': { type: 'string' },
       'framefile-strategy': { type: 'string' },
       profile: { type: 'string' },
+      variant: { type: 'string' },
+      platform: { type: 'string' },
+      device: { type: 'string' },
       from: { type: 'string' },
+      locale: { type: 'string' },
+      slot: { type: 'string' },
+      name: { type: 'string' },
+      list: { type: 'boolean' },
       json: { type: 'boolean' },
       'require-pro': { type: 'boolean' },
       manual: { type: 'boolean' },
@@ -265,6 +501,18 @@ async function main() {
       defaults: { type: 'boolean' },
       csv: { type: 'string' },
       'import-mode': { type: 'string' },
+      'pseudo-locale': { type: 'string' },
+      'pseudo-expand': { type: 'string' },
+      'max-header-units': { type: 'string' },
+      'max-sub-units': { type: 'string' },
+      'max-token-length': { type: 'string' },
+      'write-pseudo-csv': { type: 'string' },
+      'write-report-json': { type: 'string' },
+      strict: { type: 'boolean' },
+      client: { type: 'string' },
+      'package-spec': { type: 'string' },
+      'windows-cmd-shim': { type: 'boolean' },
+      'allow-partial': { type: 'boolean' },
       help: { type: 'boolean', short: 'h' },
     },
   });
@@ -338,6 +586,78 @@ async function main() {
     return;
   }
 
+  if (command === 'inspect-release-context') {
+    const result = await runInspectReleaseContext({
+      dir: values.dir,
+      configPath: values.config,
+    });
+    emitPayload('inspect-release-context', result, renderInspectReleaseContextSummary(result));
+    return;
+  }
+
+  if (command === 'plan-release') {
+    const result = await runPlanRelease({
+      dir: values.dir,
+      configPath: values.config,
+      profile: values.profile,
+      mode: values.mode,
+      outDir: values.out,
+      stageOutDir: values['stage-out'],
+    });
+    emitPayload('plan-release', result, renderPlanReleaseSummary(result));
+    return;
+  }
+
+  if (command === 'write-starter-config') {
+    const stylePreset = resolveStylePreset({ styleFlag: values.style, templateFlag: values.template });
+    const result = await runWriteStarterConfig({
+      dir: values.dir,
+      profile: values.profile,
+      slides: values.slides,
+      locales: values.locales,
+      devices: values.devices,
+      assets: stylePreset.presetAssets,
+      style: stylePreset.presetStyle,
+      force: values.force,
+      outDir: values.out,
+      stageOutDir: values['stage-out'],
+    });
+    emitPayload('write-starter-config', result, renderWriteStarterConfigSummary(result));
+    return;
+  }
+
+  if (command === 'capture-screenshots') {
+    const result = await runCaptureScreenshots({
+      dir: values.dir,
+      platform: values.platform,
+      device: values.device,
+      outDir: values.out,
+      name: values.name,
+      slot: values.slot,
+      locale: values.locale,
+      profile: values.profile,
+      list: values.list,
+    });
+    emitPayload('capture-screenshots', result, renderCaptureScreenshotsSummary(result));
+    return;
+  }
+
+  if (command === 'import-screenshots') {
+    const result = await runImportScreenshots({
+      dir: values.dir,
+      configPath: values.config,
+      fromDir: values.from,
+      locale: values.locale,
+      profile: values.profile,
+      outDir: values.out,
+      stageOutDir: values['stage-out'],
+      force: values.force,
+      allowPartial: values['allow-partial'],
+    });
+    emitPayload('import-screenshots', result, renderImportScreenshotsSummary(result));
+    return;
+  }
+
   if (command === 'auth') {
     await runAuth({ subcommand: positionals[1], values });
     return;
@@ -345,11 +665,37 @@ async function main() {
 
   if (command === 'mcp') {
     const subcommand = positionals[1] || 'serve';
-    if (subcommand !== 'serve') {
-      throw new Error(`Unknown mcp command: ${subcommand}`);
+    if (subcommand === 'serve') {
+      await runMcpServer();
+      return;
     }
-    await runMcpServer();
-    return;
+    if (subcommand === 'init') {
+      const result = await runMcpInit({
+        client: values.client,
+        dir: values.dir,
+        packageSpec: values['package-spec'],
+        windowsCmdShim: values['windows-cmd-shim'],
+        force: values.force,
+      });
+      const commandSummary = [result.command, ...result.args].join(' ');
+      emitPayload(
+        'mcp init',
+        result,
+        [
+          `OK: wrote ${result.clientLabel} MCP config -> ${result.configPath}`,
+          `- settings key: ${result.settingsKey}`,
+          result.transport ? `- transport: ${result.transport}` : null,
+          `- command: ${commandSummary}`,
+          `- merged existing config: ${result.mergedExistingConfig ? 'yes' : 'no'}`,
+          `- shipscreens entry changed: ${result.shipscreensEntryChanged ? 'yes' : 'no'}`,
+          `- total servers at key: ${result.serverCount}`,
+        ]
+          .filter(Boolean)
+          .join('\n')
+      );
+      return;
+    }
+    throw new Error(`Unknown mcp command: ${subcommand}`);
   }
 
   if (command === 'wizard') {
@@ -369,8 +715,7 @@ async function main() {
         `- ${result.configPath}\n` +
         `- ${result.csvPath}\n` +
         `Next: replace placeholder PNGs in assets/, then run:\n` +
-        `  shipscreens build --mode raw --zip --out out\n` +
-        `  shipscreens verify --out out --zip --profile appstore\n` +
+        `  shipscreens agent-run --mode raw --zip --out out/agent --stage --profile appstore\n` +
         `Pro unlock (remove watermark):\n` +
         `  shipscreens auth login`
     );
@@ -433,7 +778,7 @@ async function main() {
     const demoCopyByLocale = {
       // Keep demo copy ASCII-only so it renders consistently across environments/fonts.
       'en-US': [
-        ['Screenshots as a build step', 'wizard -> build -> verify -> tree'],
+        ['Tell your coding agent', 'keep flow -> verify -> stage'],
         ['Fastlane-ready outputs', 'deliver (iOS) + supply (Android)'],
         ['Reproducible exports', 'same inputs -> same outputs'],
         ['Verify before upload', 'catch mixed folders early'],
@@ -441,7 +786,7 @@ async function main() {
       ],
       // If the demo includes non-English locales, reuse the same copy to avoid implying translation is built-in.
       'ja-JP': [
-        ['Screenshots as a build step', 'wizard -> build -> verify -> tree'],
+        ['Tell your coding agent', 'keep flow -> verify -> stage'],
         ['Fastlane-ready outputs', 'deliver (iOS) + supply (Android)'],
         ['Reproducible exports', 'same inputs -> same outputs'],
         ['Verify before upload', 'catch mixed folders early'],
@@ -493,6 +838,7 @@ async function main() {
       mode,
       outDir: buildOutDir,
       zipOut,
+      variant: values.variant,
       clean: true,
       cliAuthToken,
       cliAuthProfile,
@@ -504,6 +850,7 @@ async function main() {
       zipOut,
       zip: true,
       profile,
+      variant: values.variant,
     });
 
     const stageResult = await runStage({
@@ -511,6 +858,7 @@ async function main() {
       fromDir: buildOutDir,
       outDir: stageOutDir,
       profile,
+      variant: values.variant,
     });
 
     const summary = [
@@ -532,6 +880,7 @@ async function main() {
         stageOutDir,
         mode,
         profile,
+        variant: values.variant || null,
         init: initResult,
         build: result,
         verify: verifyResult,
@@ -571,8 +920,7 @@ async function main() {
         `- ${result.configPath}\n` +
         `- ${result.csvPath}\n` +
         `Next: replace placeholder PNGs in assets/, then run:\n` +
-        `  shipscreens build --mode raw --zip --out out\n` +
-        `  shipscreens verify --out out --zip --profile appstore\n` +
+        `  shipscreens agent-run --mode raw --zip --out out/agent --stage --profile appstore\n` +
         `Pro unlock (remove watermark):\n` +
         `  shipscreens auth login`
     );
@@ -621,12 +969,22 @@ async function main() {
     const outDir = values.out || 'out/agent';
     const zipOut = rawZipOut || undefined;
     const zip = format === 'zip' || Boolean(zipOut);
+    const stageRequested = Boolean(values.stage || values['stage-out']);
+    const rawStageOutDir = typeof values['stage-out'] === 'string' ? values['stage-out'].trim() : '';
+    const stageOutDir = stageRequested ? rawStageOutDir || defaultAgentStageOutDir(outDir) : null;
+    const rawReportJsonPath = typeof values['report-json'] === 'string' ? values['report-json'].trim() : '';
+    const rawReportMdPath = typeof values['report-md'] === 'string' ? values['report-md'].trim() : '';
+    const reportJsonPathValue =
+      rawReportJsonPath || (stageRequested ? path.join(outDir, 'shipscreens.agent-report.json') : '');
+    const reportMdPathValue =
+      rawReportMdPath || (stageRequested ? path.join(outDir, 'shipscreens.agent-summary.md') : '');
     const { config } = await loadShipScreensConfig(configPath);
     const hasAndroid = (config.devices || []).some((device) => device.platform === 'android');
     const hasIos = (config.devices || []).some((device) => device.platform !== 'android');
     const defaultProfile = hasIos && !hasAndroid ? 'appstore' : !hasIos && hasAndroid ? 'playstore' : 'any';
     const profile = values.profile || defaultProfile;
     const requirePro = Boolean(values['require-pro']);
+    const releaseContext = await runInspectReleaseContext({ dir: targetDir, configPath });
     const { token: cliAuthToken, profile: cliAuthProfile } = await resolveCliAuth({ requirePro });
 
     const result = await runBuild({
@@ -637,6 +995,7 @@ async function main() {
       iosDir: values['ios-dir'],
       androidDir: values['android-dir'],
       zipOut,
+      variant: values.variant,
       stringsEncoding: values['strings-encoding'],
       framefileStrategy: values['framefile-strategy'],
       clean: values.clean,
@@ -652,7 +1011,46 @@ async function main() {
       zipOut,
       zip,
       profile,
+      variant: values.variant,
+    });
+
+    const stageResult = stageRequested
+      ? await runStage({
+          configPath,
+          fromDir: outDir,
+          outDir: stageOutDir,
+          profile,
+          variant: values.variant,
+        })
+      : null;
+
+    const reportPaths = {
+      json: resolveAgentArtifactPath({ baseDir: targetDir, filePath: reportJsonPathValue }),
+      markdown: resolveAgentArtifactPath({ baseDir: targetDir, filePath: reportMdPathValue }),
+    };
+    const agentReport = createAgentReport({
+      configPath,
+      targetDir,
+      outDir,
+      stageOutDir,
+      zipOut,
+      format,
+      mode,
+      profile,
+      variant: values.variant,
+      requirePro,
+      build: result,
+      verify: verifyResult,
+      stage: stageResult,
+      releaseContext,
+      reportPaths,
     });
+    if (reportPaths.json) {
+      await writeAgentArtifact(reportPaths.json, `${JSON.stringify(agentReport, null, 2)}\n`);
+    }
+    if (reportPaths.markdown) {
+      await writeAgentArtifact(reportPaths.markdown, renderAgentSummaryMarkdown(agentReport));
+    }
 
     const summary = [
       `OK: agent-run completed`,
@@ -662,18 +1060,27 @@ async function main() {
       `${verifyResult.androidDevices} Android device(s) -> ${verifyResult.androidDir}`,
     ];
     if (result.zipPath || verifyResult.zipPath) summary.push(`zip -> ${result.zipPath || verifyResult.zipPath}`);
+    if (stageResult) summary.push(`stage -> ${stageResult.out}`);
+    if (reportPaths.json) summary.push(`report json -> ${reportPaths.json}`);
+    if (reportPaths.markdown) summary.push(`report md -> ${reportPaths.markdown}`);
     emitPayload(
       'agent-run',
       {
         configPath,
         outDir,
         zipOut: zipOut || null,
+        stageOutDir,
         format,
         mode,
         profile,
+        variant: values.variant || null,
         requirePro,
         build: result,
         verify: verifyResult,
+        stage: stageResult,
+        agentReport,
+        releaseContext,
+        reportPaths,
       },
       summary.join(', ')
     );
@@ -705,6 +1112,41 @@ async function main() {
       );
       return;
     }
+    if (subcommand === 'check') {
+      const result = await runCopyCheck({
+        configPath,
+        pseudoLocale: values['pseudo-locale'],
+        pseudoExpand: parseNumericFlag('pseudo-expand', values['pseudo-expand']),
+        maxHeaderUnits: parseNumericFlag('max-header-units', values['max-header-units']),
+        maxSubUnits: parseNumericFlag('max-sub-units', values['max-sub-units']),
+        maxTokenLength: parseNumericFlag('max-token-length', values['max-token-length']),
+        writePseudoCsv: values['write-pseudo-csv'],
+        writeReportJson: values['write-report-json'],
+      });
+
+      const sample = result.issues.slice(0, 8);
+      const lines = [
+        `OK: copy check (${result.locales} locale(s) x ${result.slides} slide(s))`,
+        `- issues: ${result.issueCount}`,
+        `- pseudo locale: ${result.pseudoLocale} (expand=${result.pseudoExpand})`,
+        `- limits: header=${result.limits.headerUnits}, sub=${result.limits.subUnits}, token=${result.limits.tokenLength}`,
+      ];
+      if (result.pseudoCsvPath) lines.push(`- pseudo csv: ${result.pseudoCsvPath}`);
+      if (result.reportJsonPath) lines.push(`- report json: ${result.reportJsonPath}`);
+      if (sample.length) {
+        lines.push('- sample warnings:');
+        sample.forEach((issue) => {
+          lines.push(`  - [${issue.type}] slide ${issue.slide} ${issue.localeId} ${issue.field}: ${issue.detail}`);
+        });
+      }
+
+      if (values.strict && result.issueCount > 0) {
+        throw new Error(`copy check failed (--strict): ${result.issueCount} issue(s)\n${lines.join('\n')}`);
+      }
+
+      emitPayload('copy check', result, lines.join('\n'));
+      return;
+    }
     throw new Error(`Unknown copy command: ${subcommand || '(missing)'}`);
   }
 
@@ -750,6 +1192,7 @@ async function main() {
       iosDir: values['ios-dir'],
       androidDir: values['android-dir'],
       zipOut,
+      variant: values.variant,
       stringsEncoding: values['strings-encoding'],
       framefileStrategy: values['framefile-strategy'],
       clean: values.clean,
@@ -766,7 +1209,15 @@ async function main() {
     if (result.zipPath) summary.push(`zip -> ${result.zipPath}`);
     emitPayload(
       'build',
-      { configPath, format, mode: values.mode || 'rendered', outDir: outDir || null, zipOut: zipOut || null, ...result },
+      {
+        configPath,
+        format,
+        mode: values.mode || 'rendered',
+        outDir: outDir || null,
+        zipOut: zipOut || null,
+        variant: values.variant || null,
+        ...result,
+      },
       summary.join(', ')
     );
     return;
@@ -783,6 +1234,7 @@ async function main() {
       zipOut: rawZipOut || undefined,
       zip: values.zip || Boolean(rawZipOut),
       profile: values.profile,
+      variant: values.variant,
     });
     const summary = [
       `OK: verified`,
@@ -799,6 +1251,7 @@ async function main() {
         outDir: rawOut || null,
         zipOut: rawZipOut || null,
         profile: values.profile || null,
+        variant: values.variant || null,
         ...result,
       },
       summary.join(', ')
@@ -814,6 +1267,7 @@ async function main() {
       fromDir: rawFrom || undefined,
       outDir: rawOut || undefined,
       profile: values.profile,
+      variant: values.variant,
     });
     const details = result.iosVariant ? `, ios=${result.iosVariant}` : '';
     emitPayload(
@@ -832,6 +1286,7 @@ async function main() {
       androidDir: values['android-dir'],
       zipOut: values['zip-out'],
       profile: values.profile,
+      variant: values.variant,
     });
     process.stdout.write(JSON.stringify(plan, null, 2) + '\n');
     return;