shipscreens 0.1.6 → 0.1.7

package/README.md

@@ -1,6 +1,11 @@
 # ShipScreens CLI
 
-Use this when app-dev CI or MCP-enabled agents need deterministic store screenshot reruns as a build step.
+Best UX: treat screenshots as a build step. Keep the current Figma/Fastlane/manual screenshot workflow, tell your coding agent to ship release-safe screenshots, and let it inspect, plan, write a starter config when needed, capture connected device/emulator screens when no PNG folder exists, import existing screenshots when placeholders remain, build, verify, stage, and report via MCP or CLI. Use this package when app-dev CI or MCP-enabled agents need deterministic store-screenshot release ops that prevent Fastlane path churn, naming drift, and release-week rerun failures.
+
+## Tell your coding agent
+```text
+Use ShipScreens as the build step for our mobile release screenshots. Keep our current design workflow, inspect this repo, choose workspace-local MCP if available otherwise CLI, capture current device/emulator screens if no screenshot folder exists, generate deterministic Fastlane-ready outputs, run verify/stage, and return a short report with output paths, warnings, and next steps. Only ask me if device or locale scope, panel #1 messaging, or store-upload approval is unclear.
+```
 
 ## Quickstart
 ```bash
@@ -17,14 +22,19 @@ npx playwright install --with-deps chromium
 
 ## CI pipeline (copy/paste)
 ```bash
+npx --yes shipscreens@latest inspect-release-context --json
+npx --yes shipscreens@latest plan-release --json
+npx --yes shipscreens@latest write-starter-config --profile appstore --json
+npx --yes shipscreens@latest capture-screenshots --platform auto --out screenshots --slot 1 --profile appstore --json
+npx --yes shipscreens@latest import-screenshots --from screenshots --profile appstore --json
 npx --yes shipscreens@latest validate
 npx --yes shipscreens@latest lock
 npx --yes shipscreens@latest copy check --strict --write-pseudo-csv out/copy-pseudo.csv --write-report-json out/copy-check-report.json
-npx --yes shipscreens@latest build --out out --zip
-npx --yes shipscreens@latest verify --out out --zip --profile appstore
-npx --yes shipscreens@latest stage --from out --out out/stage --profile appstore
+npx --yes shipscreens@latest agent-run --out out --zip --stage --profile appstore --json
 ```
 
+With `--stage`, `agent-run` writes `out-stage`, `out/shipscreens.agent-report.json`, and `out/shipscreens.agent-summary.md` by default.
+
 Docs: https://shipscreens.com/tools/agent-cli/
 
 ## MCP server (stdio)

package/bin/shipscreens.js

@@ -12,6 +12,17 @@ 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';
@@ -41,7 +52,7 @@ 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>] [--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>] [--require-pro] [--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]
@@ -49,6 +60,11 @@ Usage:
   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] [--variant <id>] [--json]
   shipscreens copy import [-c shipscreens.config.yml] [--csv <path>] [--import-mode merge|replace]
@@ -61,14 +77,19 @@ 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
@@ -78,11 +99,11 @@ Commands:
 
 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>)
@@ -101,13 +122,24 @@ Options:
   --zip-out <path>      ZIP output file path (default: <out>/fastlane_assets.zip)
   --profile <appstore|playstore|any>  Strict verification/staging rules per store (default: any)
   --variant <id>        ASO experiment variant scope (writes under variants/<id>/...).
-  --from <dir>          Source output root for staging (default: config dir)
+  --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)
@@ -123,9 +155,8 @@ Options:
   -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
@@ -253,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),
@@ -266,13 +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' },
@@ -305,6 +512,7 @@ async function main() {
       client: { type: 'string' },
       'package-spec': { type: 'string' },
       'windows-cmd-shim': { type: 'boolean' },
+      'allow-partial': { type: 'boolean' },
       help: { type: 'boolean', short: 'h' },
     },
   });
@@ -378,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;
@@ -435,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`
     );
@@ -499,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'],
@@ -507,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'],
@@ -641,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`
     );
@@ -691,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({
@@ -726,6 +1014,44 @@ async function main() {
       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`,
       `${verifyResult.locales} locale(s)`,
@@ -734,12 +1060,16 @@ 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,
@@ -747,6 +1077,10 @@ async function main() {
         requirePro,
         build: result,
         verify: verifyResult,
+        stage: stageResult,
+        agentReport,
+        releaseContext,
+        reportPaths,
       },
       summary.join(', ')
     );