yam-flow 0.1.2 → 0.1.4

package/dist/bin/yam.js

@@ -8,7 +8,7 @@ import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
-import { TRUTH_STATUSES, buildMissionPatchEnvelope, buildRollbackHint, buildUeyeVisualProvenance, buildYamCompletionProof, detectDbSafetyText as detectTrustDbSafetyText, isTruthStatus } from '../lib/trust-kernel.js';
+import { TRUTH_STATUSES, buildMediaGenerationProof, buildMissionPatchEnvelope, buildRollbackHint, buildRuntimeBackendEvidence, buildUeyeVisualProvenance, buildUeyeRunReport, buildYamCompletionProof, detectDbSafetyText as detectTrustDbSafetyText, isTruthStatus } from '../lib/trust-kernel.js';
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -122,6 +122,11 @@ Usage:
   yam proof write [dir] [--format json|md] [--out file] [--route route] [--truth status] [--command text]
   yam ueye capture --url URL --out screenshot.png [--viewport 1440x900] [--full-page] [--json]
   yam ueye compare --reference ref.png --actual screenshot.png [--json]
+  yam ueye report [--reference ref.png] [--actual screenshot.png] [--json]
+  yam media proof [--requested] [--attempted] [--output file] [--json]
+  yam runtime evidence [--backend terminal|in-app-browser|playwright|tmux|zellij] [--claim observed|started|stopped|cleanup-verified] [--json]
+  yam mission queue [--agent-id id] [--scope text] [--changed file] [--verification-hint text] [--json]
+  yam benchmark report [--baseline n] [--current n] [--unit ms] [--target lower|higher] [--json]
   yam release report [--json]
   yam safety [text...]
   yam memory <init|add|list|summary|resolve> [dir] [options]
@@ -130,7 +135,7 @@ Usage:
   yam tune-log [dir]
   yam install
   yam uninstall
-  yam doctor
+  yam doctor [--json]
   yam examples
   yam path
   yam version
@@ -359,7 +364,34 @@ function failOrReport(label, issues, quiet = false) {
     process.exitCode = 1;
     return issues.length;
 }
-async function doctor() {
+async function doctor(args = []) {
+    const flags = parseSimpleFlags(args, new Set(['json']));
+    const report = await buildDoctorReport();
+    if (flags.json) {
+        console.log(JSON.stringify(report, null, 2));
+        if (!report.ok)
+            process.exitCode = 1;
+        return;
+    }
+    if (report.ok) {
+        console.log('yam doctor: ok');
+        console.log('No hooks, automations, or global config are required.');
+        console.log('Skill install state is reported by `yam status`.');
+        console.log(`yam-lite hook: ${report.yamLiteHook} (optional)`);
+        return;
+    }
+    console.log('yam doctor: issues');
+    for (const issue of report.issues)
+        console.log(`- ${issue}`);
+    if (report.nextActions.length) {
+        console.log('');
+        console.log('Next actions:');
+        for (const action of report.nextActions)
+            console.log(`- ${action}`);
+    }
+    process.exitCode = 1;
+}
+async function buildDoctorReport() {
     const issues = [];
     for (const skill of SKILLS) {
         if (!await exists(path.join(ROOT, 'skills', skill, 'SKILL.md')))
@@ -390,18 +422,112 @@ async function doctor() {
     const verifyIssues = await verify({ quiet: true });
     if (verifyIssues > 0)
         issues.push(`verify reported ${verifyIssues} issue(s)`);
-    if (!issues.length) {
-        console.log('yam doctor: ok');
-        const globalHook = await readJsonOrDefault(path.join(os.homedir(), '.codex', 'hooks.json'), {});
-        console.log('No hooks, automations, or global config are required.');
-        console.log('Skill install state is reported by `yam status`.');
-        console.log(`yam-lite hook: ${hookConfigHasYamLite(globalHook) ? 'enabled' : 'disabled'} (optional)`);
-        return;
+    const globalHook = await readJsonOrDefault(path.join(os.homedir(), '.codex', 'hooks.json'), {});
+    const nextActionDetails = doctorNextActionDetails(issues);
+    return {
+        schema: 'yam.doctor.v1',
+        generatedAt: new Date().toISOString(),
+        ok: issues.length === 0,
+        issues,
+        nextActions: nextActionDetails.map((action) => action.next_action),
+        nextActionDetails,
+        yamLiteHook: hookConfigHasYamLite(globalHook) ? 'enabled' : 'disabled'
+    };
+}
+function doctorNextActions(issues = []) {
+    return doctorNextActionDetails(issues).map((action) => action.next_action);
+}
+function doctorNextActionDetails(issues = []) {
+    const actions = [];
+    for (const issue of issues) {
+        if (/missing source skill/i.test(issue))
+            actions.push(nextActionDetail('restore-skill-source', 'warning', issue, 'run from a complete yam-flow checkout or reinstall the published package', 'npm install -g yam-flow@latest && yam install'));
+        else if (/missing truth matrix/i.test(issue))
+            actions.push(nextActionDetail('restore-truth-matrix', 'warning', issue, 'restore references/truth-matrix.md before publishing', 'git checkout -- references/truth-matrix.md'));
+        else if (/unexpected local hooks/i.test(issue))
+            actions.push(nextActionDetail('remove-project-hook', 'warning', issue, 'remove project hooks unless this repo is intentionally dogfooding them', 'inspect .codex/hooks.json and remove only intentional stale hooks'));
+        else if (/unexpected .*automation/i.test(issue))
+            actions.push(nextActionDetail('remove-stale-automation', 'warning', issue, 'remove stale yam/timeto automations before claiming clean install state', 'inspect ~/.codex/automations and remove stale entries manually'));
+        else if (/legacy|retired/i.test(issue))
+            actions.push(nextActionDetail('replace-old-skills', 'warning', issue, 'run `yam install` to replace old skill entries', 'yam install'));
+        else if (/verify reported/i.test(issue))
+            actions.push(nextActionDetail('run-verify', 'error', issue, 'run `npm run verify` and fix the reported package boundary or metadata issue', 'npm run verify'));
+    }
+    return uniqueNextActionDetails(actions);
+}
+function nextActionDetail(id, severity, reason, nextAction, command = '') {
+    const priority = priorityForSeverity(severity);
+    const ownerRoute = ownerRouteForAction(id, reason, command);
+    return {
+        id,
+        severity,
+        priority,
+        owner_route: ownerRoute,
+        reason,
+        next_action: nextAction,
+        command,
+        tool_intent: toolIntentForCommand(command),
+        fix_first: priority === 'P0' || priority === 'P1',
+        blocks_release: priority === 'P0',
+        truth_status: 'partial'
+    };
+}
+function priorityForSeverity(severity = '') {
+    if (/error|danger|block/i.test(String(severity)))
+        return 'P0';
+    if (/warn/i.test(String(severity)))
+        return 'P1';
+    if (/info/i.test(String(severity)))
+        return 'P2';
+    return 'P3';
+}
+function ownerRouteForAction(id = '', reason = '', command = '') {
+    const text = `${id} ${reason} ${command}`;
+    if (/visual|ueye|screenshot|browser/i.test(text))
+        return '$ueye';
+    if (/release|publish|package|registry|dist|version/i.test(text))
+        return '$deep';
+    if (/database|supabase|destructive|production|migration/i.test(text))
+        return '$deep';
+    if (/mission|subagent|team|lane/i.test(text))
+        return '$mission';
+    if (/research|docs|current/i.test(text))
+        return '$scout';
+    return '$quick';
+}
+function toolIntentForCommand(command = '') {
+    const text = String(command || '').toLowerCase();
+    if (!text)
+        return 'read_only';
+    if (/(publish|registry|release|npm pack|npm publish)/i.test(text))
+        return 'publish';
+    if (/(rm |delete|drop|truncate|reset|migrate|push|deploy|write|commit|add |install)/i.test(text))
+        return 'destructive';
+    if (/(dev|server|tmux|playwright|browser|screenshot|runtime|port|pid)/i.test(text))
+        return 'runtime';
+    if (/(ueye|visual|image|screen)/i.test(text))
+        return 'visual';
+    if (/(build|typecheck|lint|test|verify|doctor|status|pack)/i.test(text))
+        return 'read_only';
+    return 'write';
+}
+function normalizeToolIntent(value = '') {
+    const text = String(value || '').toLowerCase().replace(/[-\s]/g, '_');
+    if (['read_only', 'write', 'destructive', 'runtime', 'visual', 'publish'].includes(text))
+        return text;
+    return 'read_only';
+}
+function uniqueNextActionDetails(actions = []) {
+    const seen = new Set();
+    const unique = [];
+    for (const action of actions) {
+        const key = `${action.id}:${action.next_action}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        unique.push(action);
     }
-    console.log('yam doctor: issues');
-    for (const issue of issues)
-        console.log(`- ${issue}`);
-    process.exitCode = 1;
+    return unique;
 }
 async function tools(args = []) {
     const subcommand = args[0] || 'doctor';
@@ -460,6 +586,7 @@ async function buildToolsDoctorReport(targetDir = process.cwd()) {
         packageInfo.packageJson ? JSON.stringify(packageInfo.pkg?.devDependencies || {}) : ''
     ].join('\n'));
     const projectSurfaces = await detectProjectToolSurfaces(dir, packageInfo.pkg);
+    const frameworkChecklist = await detectFrameworkChecklist(dir, packageInfo.pkg);
     const sqlScan = await scanSqlFiles(dir);
     const rows = [
         readinessRow('Codex home', await exists(codexHome) ? 'ready' : 'missing', codexHome),
@@ -479,6 +606,13 @@ async function buildToolsDoctorReport(targetDir = process.cwd()) {
         ...safety.hits,
         ...sqlScan.findings.map((finding) => ({ level: finding.level, reason: `${finding.file}: ${finding.reason}` }))
     ];
+    const nextActionDetails = toolsDoctorNextActionDetails({
+        pack,
+        rows,
+        riskNotes,
+        frameworkChecklist,
+        commands: detection.packageJson ? detection.commands : {}
+    });
     return {
         schemaVersion: 1,
         generatedAt: new Date().toISOString(),
@@ -489,8 +623,11 @@ async function buildToolsDoctorReport(targetDir = process.cwd()) {
         packageManager: detection.packageJson ? detection.packageManager : null,
         instructionSurfaces,
         projectSurfaces,
+        frameworkChecklist,
         sqlScan,
         riskNotes,
+        nextActions: nextActionDetails.map((action) => action.next_action),
+        nextActionDetails,
         routeRecommendations: {
             dbSupabase: safety.hits.length || sqlScan.findings.length ? '$deep required before claiming safe' : '$deep when destructive or production mutation appears',
             currentDocs: 'use current-docs proof only when version/freshness matters',
@@ -522,6 +659,13 @@ function printToolsDoctorReport(data) {
         for (const surface of data.projectSurfaces)
             console.log(`- ${surface}`);
     }
+    if (data.frameworkChecklist?.detected) {
+        console.log('');
+        console.log(`Framework checklist: ${data.frameworkChecklist.framework}`);
+        for (const check of data.frameworkChecklist.checks) {
+            console.log(`- ${check.id}: ${check.label} (${check.route})`);
+        }
+    }
     if (data.sqlScan.filesScanned > 0) {
         console.log('');
         console.log(`SQL scan: ${data.sqlScan.filesScanned} file(s), ${data.sqlScan.findings.length} risk finding(s)`);
@@ -535,6 +679,12 @@ function printToolsDoctorReport(data) {
         for (const note of data.riskNotes)
             console.log(`- ${note.level}: ${note.reason}`);
     }
+    if (data.nextActions?.length) {
+        console.log('');
+        console.log('Next actions:');
+        for (const action of data.nextActions)
+            console.log(`- ${action}`);
+    }
     console.log('');
     console.log('Route recommendations:');
     console.log(`- DB/Supabase destructive or production write work: ${data.routeRecommendations.dbSupabase}`);
@@ -611,6 +761,56 @@ async function detectProjectToolSurfaces(dir, pkg = null) {
         surfaces.push('.env file detected; values were not read');
     return surfaces;
 }
+async function detectFrameworkChecklist(dir, pkg = null) {
+    const deps = {
+        ...pkg?.dependencies,
+        ...pkg?.devDependencies
+    };
+    const depNames = Object.keys(deps || {});
+    const hasReact = depNames.includes('react');
+    const hasNext = depNames.includes('next') || await exists(path.join(dir, 'next.config.js')) || await exists(path.join(dir, 'next.config.mjs')) || await exists(path.join(dir, 'next.config.ts'));
+    const hasVite = depNames.includes('vite') || await exists(path.join(dir, 'vite.config.js')) || await exists(path.join(dir, 'vite.config.ts'));
+    const framework = hasNext ? 'next-app' : hasReact && hasVite ? 'react-vite' : hasReact ? 'react' : pkg ? 'node-package' : 'unknown';
+    const uiLike = hasReact || hasNext || hasVite || await exists(path.join(dir, 'app')) || await exists(path.join(dir, 'src', 'app')) || await exists(path.join(dir, 'pages'));
+    const checks = [];
+    if (uiLike) {
+        checks.push(checklistRow('states', 'default/loading/error/empty states are reachable before claiming complete', '$ueye'), checklistRow('responsive', 'mobile and desktop layouts avoid overlap and clipped text', '$ueye'), checklistRow('accessibility', 'interactive controls have accessible labels and keyboard path', '$ueye'), checklistRow('runtime', 'browser or in-app runtime evidence is recorded when claiming visual verified', '$ueye'));
+    }
+    if (hasNext) {
+        checks.push(checklistRow('boundaries', 'server/client boundaries and async data states match the framework pattern', '$deep when risky'));
+    }
+    if (pkg) {
+        checks.push(checklistRow('package', 'run the smallest honest type/build/package check before publishing', '$quick or $deep'));
+    }
+    return {
+        schema: 'yam.framework-checklist.v1',
+        detected: checks.length > 0,
+        uiLike,
+        framework,
+        routeHint: uiLike ? '$ueye for visual claims; $deep when runtime/data risk appears' : '$quick by default; deepen on risk',
+        checks
+    };
+}
+function checklistRow(id, label, route) {
+    return { id, label, route };
+}
+function toolsDoctorNextActions(input) {
+    return toolsDoctorNextActionDetails(input).map((action) => action.next_action);
+}
+function toolsDoctorNextActionDetails({ pack, rows, riskNotes, frameworkChecklist, commands }) {
+    const actions = [];
+    if (!pack)
+        actions.push(nextActionDetail('project-pack', 'info', 'project pack missing', 'create or refresh yam.project.md so route choices reuse local project context', 'yam init-project .'));
+    if (rows.some((row) => row.name === 'Yam skills' && row.status !== 'ready'))
+        actions.push(nextActionDetail('install-skills', 'warning', 'skill install state is incomplete', 'run `yam install` and restart Codex before relying on installed skills', 'yam install'));
+    if (riskNotes.some((note) => note.level === 'danger'))
+        actions.push(nextActionDetail('deep-safety', 'error', 'destructive database or production write signal detected', 'use $deep before claiming destructive database or production write safety', 'yam safety "<command or SQL>"'));
+    if (frameworkChecklist?.detected && !commands?.build && !commands?.typecheck)
+        actions.push(nextActionDetail('verification-command', 'warning', 'build/typecheck command not detected', 'add or document a small build/typecheck command for implementation verification', 'yam pack .'));
+    if (frameworkChecklist?.uiLike)
+        actions.push(nextActionDetail('ueye-evidence', 'info', 'UI-like project detected', 'for Ueye verified claims, record reference, actual screenshot, and comparison result', 'yam ueye report --reference ref.png --actual shot.png --json'));
+    return uniqueNextActionDetails(actions);
+}
 async function scanSqlFiles(rootDir, { maxFiles = 30, maxBytes = 200000, maxDepth = 5 } = {}) {
     const root = path.resolve(rootDir || process.cwd());
     const files = [];
@@ -956,11 +1156,26 @@ async function release(args = []) {
         if (check.note)
             console.log(`  ${check.note}`);
     }
+    if (report.provenance) {
+        console.log(`- Git commit: ${report.provenance.git_commit || 'unknown'}`);
+        console.log(`- Git dirty: ${report.provenance.git_dirty ? 'yes' : 'no'}`);
+        console.log(`- Dist freshness: ${report.freshness.dist}`);
+    }
+    if (report.tarball) {
+        console.log(`- Tarball: ${report.tarball.tarball_name || report.tarball.status}`);
+        if (report.tarball.file_count !== undefined)
+            console.log(`- Tarball files: ${report.tarball.file_count}`);
+    }
     if (report.failed.length) {
         console.log('- Failed:');
         for (const id of report.failed)
             console.log(`  - ${id}`);
     }
+    if (report.next_actions?.length) {
+        console.log('- Next actions:');
+        for (const action of report.next_actions)
+            console.log(`  - ${action.next_action}`);
+    }
     if (!report.ok)
         process.exitCode = 1;
 }
@@ -975,6 +1190,10 @@ function runReleaseReport() {
         ['dist_freshness', ['npm', ['run', 'dist:freshness']]]
     ].map(([id, command]) => runReleaseCheck(id, command));
     const failed = checks.filter((check) => check.status !== 'passed').map((check) => check.id);
+    const provenance = releaseProvenance(checks);
+    const tarball = releaseTarballProvenance();
+    const freshness = releaseFreshness(checks, provenance, tarball);
+    const nextActions = releaseNextActions(checks, provenance, tarball);
     return {
         schema: 'yam.release-report.v1',
         generated_at: startedAt,
@@ -983,9 +1202,114 @@ function runReleaseReport() {
         ok: failed.length === 0,
         truth_status: failed.length === 0 ? 'verified' : 'blocked',
         checks,
-        failed
+        failed,
+        provenance,
+        tarball,
+        freshness,
+        next_actions: nextActions
+    };
+}
+function releaseProvenance(checks = []) {
+    const gitCommit = runReadOnlyCommand('git', ['rev-parse', '--short', 'HEAD']);
+    const gitStatus = runReadOnlyCommand('git', ['status', '--short']);
+    const distChanged = runReadOnlyCommand('git', ['diff', '--name-only', '--', 'dist']);
+    const packageFiles = checks.find((check) => check.id === 'package_boundary')?.status === 'passed' ? 'checked' : 'not-verified';
+    return {
+        schema: 'yam.release-provenance.v1',
+        package_name: PACKAGE_JSON.name,
+        version: VERSION,
+        git_commit: gitCommit.trim(),
+        git_dirty: Boolean(gitStatus.trim()),
+        git_status_lines: gitStatus.trim().split(/\r?\n/).filter(Boolean).slice(0, 20),
+        dist_changed_files: distChanged.trim().split(/\r?\n/).filter(Boolean).slice(0, 20),
+        package_files: packageFiles,
+        generated_at: new Date().toISOString(),
+        truth_status: gitCommit.trim() && packageFiles === 'checked' ? 'partial' : 'assumed'
+    };
+}
+function releaseTarballProvenance() {
+    const result = spawnSync('npm', ['pack', '--json', '--dry-run', '--ignore-scripts'], {
+        cwd: ROOT,
+        encoding: 'utf8',
+        env: { ...process.env, npm_config_cache: path.join(os.tmpdir(), 'yam-npm-cache') },
+        timeout: 120000
+    });
+    if (result.status !== 0) {
+        return {
+            schema: 'yam.release-tarball-provenance.v1',
+            status: 'blocked',
+            reason: summarizeCheckOutput([result.stdout, result.stderr, result.error?.message].filter(Boolean).join('\n')),
+            truth_status: 'blocked'
+        };
+    }
+    try {
+        const data = JSON.parse(String(result.stdout || '[]'))[0] || {};
+        return {
+            schema: 'yam.release-tarball-provenance.v1',
+            status: 'checked',
+            tarball_name: String(data.filename || ''),
+            package_size: Number(data.size || data.packageSize || 0),
+            unpacked_size: Number(data.unpackedSize || 0),
+            file_count: Array.isArray(data.files) ? data.files.length : Number(data.entryCount || 0),
+            integrity: String(data.integrity || ''),
+            shasum: String(data.shasum || ''),
+            truth_status: data.filename ? 'verified' : 'partial'
+        };
+    }
+    catch (error) {
+        return {
+            schema: 'yam.release-tarball-provenance.v1',
+            status: 'blocked',
+            reason: `could not parse npm pack output: ${errorMessage(error)}`,
+            truth_status: 'blocked'
+        };
+    }
+}
+function releaseFreshness(checks = [], provenance = {}, tarball = {}) {
+    const checkStatus = (id) => checks.find((check) => check.id === id)?.status || 'not-run';
+    const dist = checkStatus('dist_freshness') === 'passed' && !provenance.dist_changed_files?.length ? 'fresh' : 'needs-check';
+    const registry = checkStatus('registry_status') === 'passed' ? 'publishable-version' : 'not-verified';
+    const boundary = checkStatus('package_boundary') === 'passed' ? 'checked' : 'not-verified';
+    const smoke = checkStatus('cli_smoke') === 'passed' ? 'checked' : 'not-verified';
+    const tarballStatus = tarball.status === 'checked' ? 'checked' : 'not-verified';
+    return {
+        schema: 'yam.release-freshness.v1',
+        dist,
+        registry,
+        package_boundary: boundary,
+        cli_smoke: smoke,
+        tarball: tarballStatus,
+        truth_status: [dist, registry, boundary, smoke, tarballStatus].every((value) => !/not-verified|needs-check/.test(value)) ? 'verified' : 'partial'
     };
 }
+function releaseNextActions(checks = [], provenance = {}, tarball = {}) {
+    const actions = [];
+    for (const check of checks) {
+        if (check.status === 'passed')
+            continue;
+        actions.push(nextActionDetail(`release-${check.id}`, check.status === 'blocked' ? 'error' : 'warning', check.note || `${check.id} did not pass`, `fix ${check.id} before publishing`, check.command));
+    }
+    if (provenance.git_dirty) {
+        actions.push(nextActionDetail('release-git-dirty', 'warning', 'working tree has uncommitted changes', 'commit or intentionally keep local-only changes before tagging a release', 'git status --short'));
+    }
+    if (provenance.dist_changed_files?.length) {
+        actions.push(nextActionDetail('release-dist-drift', 'warning', 'dist has unstaged or uncommitted differences', 'run build and commit generated dist only if this package publishes dist', 'npm run build'));
+    }
+    if (tarball.status !== 'checked') {
+        actions.push(nextActionDetail('release-tarball-provenance', 'error', tarball.reason || 'tarball provenance was not produced', 'run npm pack dry-run before publishing', 'npm pack --dry-run'));
+    }
+    return uniqueNextActionDetails(actions);
+}
+function runReadOnlyCommand(command, args = []) {
+    const result = spawnSync(command, args, {
+        cwd: ROOT,
+        encoding: 'utf8',
+        timeout: 30000
+    });
+    if (result.status !== 0)
+        return '';
+    return String(result.stdout || '');
+}
 function runReleaseCheck(id, commandSpec) {
     const [command, args] = commandSpec;
     const start = Date.now();
@@ -1029,6 +1353,8 @@ async function ueye(args = []) {
         return ueyeCapture(args.slice(1));
     if (subcommand === 'compare')
         return ueyeCompare(args.slice(1));
+    if (subcommand === 'report')
+        return ueyeReport(args.slice(1));
     console.error(`unknown ueye command: ${subcommand}`);
     return ueyeUsage();
 }
@@ -1040,10 +1366,12 @@ Opt-in visual evidence helpers. Ueye stays one skill: fast by default, capture/c
 Usage:
   yam ueye capture --url URL --out screenshot.png [--viewport 1440x900] [--full-page] [--json]
   yam ueye compare --reference ref.png --actual screenshot.png [--json]
+  yam ueye report [--reference ref.png] [--actual screenshot.png] [--review-session-id id] [--similar text] [--different text] [--missing text] [--resolved text] [--new-finding text] [--still-open text] [--regression text] [--viewport 1440x900] [--state default] [--design-quality pass|needs-polish|fails|not-checked] [--json]
 
 Notes:
   capture uses a locally available Playwright install when present. It does not download browsers or install dependencies.
   compare uses local files only and reports sha256, dimensions, comparison_result, and proof-ready visual provenance.
+  report produces a proof-ready Ueye visual run report and continuity/comparison record without requiring a new capture.
 `);
 }
 async function ueyeCapture(args = []) {
@@ -1165,6 +1493,447 @@ async function ueyeCompare(args = []) {
         process.exitCode = 1;
     }
 }
+async function ueyeReport(args = []) {
+    if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h')
+        return ueyeUsage();
+    const flags = parseSimpleFlags(args, new Set(['reference', 'ref', 'actual', 'screenshot', 'capture-backend', 'compare-backend', 'design-quality', 'blocked-reason', 'next-action', 'next-visual-action', 'review-session-id', 'reference-id', 'screenshot-id', 'previous-screenshot-id', 'current-screenshot-id', 'previous-report', 'comparison-notes', 'similar', 'different', 'missing', 'resolved', 'new-finding', 'still-open', 'regression', 'viewport', 'state', 'json']));
+    const reference = String(flags.reference || flags.ref || '');
+    const actual = String(flags.actual || flags.screenshot || '');
+    const referenceSources = [];
+    const implementationSources = [];
+    let comparisonResult = 'not-verified';
+    let blockedReason = String(flags.blocked_reason || '');
+    const reviewSessionId = String(flags.review_session_id || `ueye-${timestampId()}`);
+    const previousReport = await readPreviousUeyeReport(flags.previous_report);
+    try {
+        if (reference) {
+            const info = await imageFileInfo(reference);
+            referenceSources.push(buildUeyeVisualProvenance({
+                source_kind: 'reference_image',
+                source_path: info.path,
+                source_hash: info.sha256,
+                reference_id: String(flags.reference_id || path.basename(info.path)),
+                local_only: true,
+                operator_provided: true,
+                comparison_result: 'reference-recorded',
+                truth_status: 'partial'
+            }));
+        }
+        if (actual) {
+            const info = await imageFileInfo(actual);
+            implementationSources.push(buildUeyeVisualProvenance({
+                source_kind: 'implementation_screenshot',
+                source_path: info.path,
+                source_hash: info.sha256,
+                reference_id: String(flags.reference_id || referenceSources[0]?.reference_id || ''),
+                screenshot_id: String(flags.current_screenshot_id || flags.screenshot_id || path.basename(info.path)),
+                local_only: true,
+                operator_provided: false,
+                comparison_result: 'implementation-recorded',
+                truth_status: 'partial'
+            }));
+        }
+        if (reference && actual && referenceSources[0]?.source_hash === implementationSources[0]?.source_hash) {
+            comparisonResult = 'matched';
+        }
+        else if (reference && actual) {
+            comparisonResult = 'different';
+        }
+    }
+    catch (error) {
+        blockedReason = errorMessage(error);
+    }
+    const report = buildUeyeRunReport({
+        reference_sources: referenceSources,
+        implementation_sources: implementationSources,
+        comparison_result: comparisonResult,
+        design_quality: String(flags.design_quality || 'not-checked'),
+        blocked_reason: blockedReason,
+        next_action: String(flags.next_visual_action || flags.next_action || '')
+    });
+    const comparisonReport = buildUeyeComparisonReport({
+        reviewSessionId,
+        previousReport,
+        referenceSources,
+        implementationSources,
+        comparisonResult,
+        designQuality: String(flags.design_quality || 'not-checked'),
+        similar: arrayFlag(flags.similar),
+        different: arrayFlag(flags.different),
+        missing: arrayFlag(flags.missing),
+        notes: arrayFlag(flags.comparison_notes),
+        resolved: arrayFlag(flags.resolved),
+        newFindings: arrayFlag(flags.new_finding),
+        stillOpen: arrayFlag(flags.still_open),
+        regressions: arrayFlag(flags.regression),
+        previousScreenshotId: String(flags.previous_screenshot_id || previousReport?.screenshot_id || ''),
+        currentScreenshotId: String(flags.current_screenshot_id || flags.screenshot_id || implementationSources[0]?.screenshot_id || ''),
+        viewport: String(flags.viewport || ''),
+        state: String(flags.state || 'unknown'),
+        nextAction: report.next_action,
+        truthStatus: report.truth_status
+    });
+    const result = {
+        ...report,
+        review_session_id: reviewSessionId,
+        tool_intent: 'visual',
+        capture_backend: String(flags.capture_backend || 'not-recorded'),
+        compare_backend: String(flags.compare_backend || 'local-file-hash'),
+        continuity: comparisonReport.continuity,
+        comparison_report: comparisonReport
+    };
+    printJsonOrHuman(result, Boolean(flags.json), 'Ueye report');
+    if (report.truth_status === 'blocked')
+        process.exitCode = 1;
+}
+async function readPreviousUeyeReport(file = '') {
+    const target = String(file || '');
+    if (!target)
+        return null;
+    try {
+        const data = await readJson(path.resolve(expandHome(target)));
+        return {
+            path: path.resolve(expandHome(target)),
+            review_session_id: data.review_session_id || data.comparison_report?.review_session_id || '',
+            screenshot_id: data.comparison_report?.current_screenshot_id || data.current_screenshot_id || data.screenshot_id || '',
+            truth_status: data.truth_status || data.comparison_report?.truth_status || 'partial',
+            comparison_result: data.comparison_result || data.comparison_report?.comparison_result || 'not-verified'
+        };
+    }
+    catch (error) {
+        return {
+            path: path.resolve(expandHome(target)),
+            blocked_reason: errorMessage(error),
+            truth_status: 'blocked',
+            comparison_result: 'not-verified'
+        };
+    }
+}
+function buildUeyeComparisonReport({ reviewSessionId, previousReport, referenceSources, implementationSources, comparisonResult, designQuality, similar, different, missing, notes, resolved, newFindings, stillOpen, regressions, previousScreenshotId, currentScreenshotId, viewport, state, nextAction, truthStatus }) {
+    const hasReference = referenceSources.length > 0;
+    const hasImplementation = implementationSources.length > 0;
+    const continuityTruth = previousReport?.blocked_reason ? 'blocked' : previousReport ? 'partial' : 'assumed';
+    return {
+        schema: 'yam.ueye-comparison-report.v1',
+        review_session_id: reviewSessionId,
+        previous_report: previousReport,
+        continuity: {
+            schema: 'yam.ueye-review-continuity.v1',
+            current_review_session_id: reviewSessionId,
+            previous_review_session_id: previousReport?.review_session_id || '',
+            previous_report_path: previousReport?.path || '',
+            previous_screenshot_id: previousScreenshotId || previousReport?.screenshot_id || '',
+            current_screenshot_id: currentScreenshotId || '',
+            carries_forward: Boolean(previousReport && !previousReport.blocked_reason),
+            truth_status: continuityTruth
+        },
+        evidence_summary: {
+            has_reference: hasReference,
+            has_implementation_screenshot: hasImplementation,
+            reference_count: referenceSources.length,
+            implementation_count: implementationSources.length
+        },
+        comparison_result: comparisonResult,
+        design_quality: designQuality,
+        similar,
+        different,
+        missing,
+        resolved,
+        new_findings: newFindings,
+        still_open: stillOpen,
+        regressions,
+        previous_screenshot_id: previousScreenshotId || previousReport?.screenshot_id || '',
+        current_screenshot_id: currentScreenshotId || '',
+        viewport,
+        state,
+        notes,
+        next_action: nextAction || (truthStatus === 'verified' ? 'no action required' : 'capture or provide implementation screenshot, then compare again'),
+        truth_status: truthStatus
+    };
+}
+async function media(args = []) {
+    const subcommand = args[0] || 'help';
+    if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h')
+        return mediaUsage();
+    if (subcommand === 'proof')
+        return mediaProof(args.slice(1));
+    console.error(`unknown media command: ${subcommand}`);
+    return mediaUsage();
+}
+function mediaUsage() {
+    console.log(`yam media
+
+Opt-in media generation proof helpers. Generated media can support visual direction, but it cannot verify implemented UI without implementation screenshot evidence.
+
+Usage:
+  yam media proof [--tool name] [--requested] [--attempted] [--output file] [--wait-loop] [--blocked-reason text] [--json]
+`);
+}
+async function mediaProof(args = []) {
+    if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h')
+        return mediaUsage();
+    const flags = parseSimpleFlags(args, new Set(['tool', 'requested', 'attempted', 'output', 'wait-loop', 'blocked-reason', 'next-action', 'json']));
+    const output = String(flags.output || '');
+    let outputHash = 'unknown';
+    let outputPath = '';
+    let blockedReason = String(flags.blocked_reason || '');
+    if (output) {
+        try {
+            const info = await imageFileInfo(output);
+            outputHash = info.sha256;
+            outputPath = info.path;
+        }
+        catch (error) {
+            blockedReason = blockedReason || errorMessage(error);
+            outputPath = path.resolve(expandHome(output));
+        }
+    }
+    const proof = buildMediaGenerationProof({
+        tool_name: String(flags.tool || ''),
+        generation_requested: Boolean(flags.requested),
+        generation_attempted: Boolean(flags.attempted || output),
+        output_path: outputPath,
+        output_hash: outputHash,
+        wait_loop_checked: Boolean(flags.wait_loop),
+        blocked_reason: blockedReason,
+        next_action: String(flags.next_action || '')
+    });
+    printJsonOrHuman(proof, Boolean(flags.json), 'Media proof');
+    if (proof.truth_status === 'blocked')
+        process.exitCode = 1;
+}
+async function runtime(args = []) {
+    const subcommand = args[0] || 'help';
+    if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h')
+        return runtimeUsage();
+    if (subcommand === 'evidence')
+        return runtimeEvidence(args.slice(1));
+    console.error(`unknown runtime command: ${subcommand}`);
+    return runtimeUsage();
+}
+function runtimeUsage() {
+    console.log(`yam runtime
+
+Usage:
+  yam runtime evidence [--backend terminal|in-app-browser|playwright|tmux|zellij] [--claim observed|started|stopped|cleanup-verified] [--evidence-id id] [--command text] [--pid n] [--port n] [--url URL] [--exit-code n] [--screenshot-id id] [--cleanup-checked] [--note text] [--json]
+
+Notes:
+  Records a small runtime evidence shape. It does not start, stop, or inspect processes by itself.
+`);
+}
+async function runtimeEvidence(args = []) {
+    if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h')
+        return runtimeUsage();
+    const flags = parseSimpleFlags(args, new Set(['backend', 'claim', 'evidence-id', 'command', 'pid', 'port', 'url', 'exit-code', 'screenshot-id', 'started-at', 'stopped-at', 'cleanup-checked', 'note', 'truth', 'intent', 'json']));
+    const evidence = buildRuntimeBackendEvidence({
+        backend: flags.backend,
+        claim: flags.claim,
+        evidence_id: String(flags.evidence_id || `runtime-${timestampId()}`),
+        command: String(flags.command || ''),
+        cleanup_checked: Boolean(flags.cleanup_checked),
+        note: String(flags.note || ''),
+        truth_status: isTruthStatus(flags.truth) ? flags.truth : undefined
+    });
+    const runtimeDetails = runtimeEvidenceDetails(flags);
+    if (!isTruthStatus(flags.truth) && evidence.truth_status === 'verified' && !runtimeDetailsHasVerification(runtimeDetails)) {
+        evidence.truth_status = 'partial';
+    }
+    const result = {
+        ...evidence,
+        runtime_details: runtimeDetails,
+        tool_intent: normalizeToolIntent(flags.intent || 'runtime'),
+        next_action: runtimeEvidenceNextAction(evidence)
+    };
+    printJsonOrHuman(result, Boolean(flags.json), 'Runtime evidence');
+    if (result.truth_status === 'blocked' || result.truth_status === 'real_required_missing')
+        process.exitCode = 1;
+}
+function runtimeEvidenceDetails(flags = {}) {
+    return {
+        schema: 'yam.runtime-details.v1',
+        pid: numberOrNull(flags.pid),
+        port: numberOrNull(flags.port),
+        url: String(flags.url || ''),
+        exit_code: numberOrNull(flags.exit_code),
+        screenshot_id: String(flags.screenshot_id || ''),
+        started_at: String(flags.started_at || ''),
+        stopped_at: String(flags.stopped_at || '')
+    };
+}
+function runtimeDetailsHasVerification(details = {}) {
+    return Boolean(details.url || details.screenshot_id || details.pid !== null || details.port !== null || details.exit_code !== null || details.started_at || details.stopped_at);
+}
+function runtimeEvidenceNextAction(evidence) {
+    if (evidence.truth_status === 'proven' || evidence.truth_status === 'verified')
+        return 'attach this evidence to `yam proof` when making a runtime claim';
+    if (evidence.claim === 'cleanup_verified' && !evidence.cleanup_checked)
+        return 'rerun with --cleanup-checked only after process exit or intentional persistence is confirmed';
+    if (evidence.backend === 'none' || evidence.backend === 'unknown')
+        return 'record the actual runtime backend before claiming runtime verification';
+    return 'add command output, screenshot id, pid/session id, or cleanup proof before upgrading the claim';
+}
+async function mission(args = []) {
+    const subcommand = args[0] || 'help';
+    if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h')
+        return missionUsage();
+    if (subcommand === 'queue' || subcommand === 'patch')
+        return missionQueue(args.slice(1));
+    console.error(`unknown mission command: ${subcommand}`);
+    return missionUsage();
+}
+function missionUsage() {
+    console.log(`yam mission
+
+Usage:
+  yam mission queue [--lane-id id] [--agent-id id] [--status pending|applied|verified|blocked|reverted] [--scope text] [--changed file] [--depends-on lane] [--generated file] [--verification-hint text] [--rollback-hint text] [--before-check text] [--out file] [--truth status] [--json]
+
+Notes:
+  Produces a patch queue item for mission handoff/review. It does not run workers; persistence is opt-in with --out.
+`);
+}
+async function missionQueue(args = []) {
+    if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h')
+        return missionUsage();
+    const flags = parseSimpleFlags(args, new Set(['lane-id', 'agent-id', 'status', 'scope', 'changed', 'generated', 'depends-on', 'verification-hint', 'rollback-hint', 'before-check', 'safe-revert-note', 'truth', 'intent', 'out', 'json']));
+    const changedFiles = arrayFlag(flags.changed);
+    const generatedFiles = arrayFlag(flags.generated);
+    const laneId = String(flags.lane_id || flags.agent_id || `lane-${timestampId()}`);
+    const status = normalizeMissionQueueStatus(flags.status || 'pending');
+    const rollback = buildRollbackHint({
+        touched_files: changedFiles,
+        generated_files: generatedFiles,
+        before_check: String(flags.before_check || ''),
+        safe_revert_note: String(flags.safe_revert_note || flags.rollback_hint || '')
+    });
+    const envelope = buildMissionPatchEnvelope({
+        agent_id: String(flags.agent_id || `agent-${timestampId()}`),
+        assigned_scope: String(flags.scope || ''),
+        changed_files: changedFiles,
+        verification_hint: String(flags.verification_hint || ''),
+        rollback_hint: rollback,
+        truth_status: isTruthStatus(flags.truth) ? flags.truth : changedFiles.length ? 'partial' : 'assumed'
+    });
+    const item = {
+        schema: 'yam.mission-patch-queue-item.v1',
+        lane_id: laneId,
+        status,
+        depends_on: arrayFlag(flags.depends_on),
+        tool_intent: normalizeToolIntent(flags.intent || (changedFiles.length || generatedFiles.length ? 'write' : 'read_only')),
+        patch_envelope: envelope,
+        next_action: missionQueueNextAction(envelope, status)
+    };
+    const result = {
+        schema: 'yam.mission-patch-queue-lite.v1',
+        generated_at: new Date().toISOString(),
+        persistence: flags.out ? 'written' : 'not-persisted',
+        out: flags.out ? path.resolve(expandHome(flags.out)) : '',
+        items: [item],
+        queue_depth: 1,
+        next_action: item.next_action,
+        truth_status: envelope.truth_status
+    };
+    if (flags.out) {
+        const target = path.resolve(expandHome(flags.out));
+        await fsp.mkdir(path.dirname(target), { recursive: true });
+        await fsp.writeFile(target, `${JSON.stringify(result, null, 2)}\n`);
+    }
+    printJsonOrHuman(result, Boolean(flags.json), 'Mission patch queue');
+}
+function normalizeMissionQueueStatus(value = '') {
+    const text = String(value || '').toLowerCase();
+    if (['pending', 'applied', 'verified', 'blocked', 'reverted'].includes(text))
+        return text;
+    return 'pending';
+}
+function missionQueueNextAction(envelope, status = 'pending') {
+    if (status === 'blocked')
+        return 'resolve or document the blocker before applying dependent mission lanes';
+    if (status === 'reverted')
+        return 'rerun the before-check or verification hint before continuing dependent work';
+    if (!envelope.assigned_scope)
+        return 'add --scope so the patch can be reviewed against an assigned boundary';
+    if (!envelope.changed_files.length)
+        return 'add at least one --changed file when this represents code-changing work';
+    if (!envelope.verification_hint)
+        return 'add --verification-hint so reviewers know the smallest honest check';
+    if (!envelope.rollback_hint.safe_revert_note && !envelope.rollback_hint.before_check)
+        return 'add rollback or before-check detail before using this for risky work';
+    return 'attach this envelope to the mission proof summary and cross-check changed files';
+}
+async function benchmark(args = []) {
+    const subcommand = args[0] || 'help';
+    if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h')
+        return benchmarkUsage();
+    if (subcommand === 'report')
+        return benchmarkReport(args.slice(1));
+    console.error(`unknown benchmark command: ${subcommand}`);
+    return benchmarkUsage();
+}
+function benchmarkUsage() {
+    console.log(`yam benchmark
+
+Usage:
+  yam benchmark report [--label text] [--baseline n] [--current n] [--unit ms] [--target lower|higher] [--next-action text] [--json]
+
+Notes:
+  Records a small optimization loop result. It does not run benchmarks by itself.
+`);
+}
+async function benchmarkReport(args = []) {
+    if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h')
+        return benchmarkUsage();
+    const flags = parseSimpleFlags(args, new Set(['label', 'baseline', 'current', 'unit', 'target', 'next-action', 'rollback-hint', 'intent', 'json']));
+    const baseline = numberOrNull(flags.baseline);
+    const current = numberOrNull(flags.current);
+    const target = String(flags.target || 'lower').toLowerCase() === 'higher' ? 'higher' : 'lower';
+    const hasNumbers = baseline !== null && current !== null;
+    const delta = hasNumbers ? current - baseline : null;
+    const percent = hasNumbers && baseline !== 0 ? (delta / baseline) * 100 : null;
+    const status = benchmarkStatus({ baseline, current, target });
+    const result = {
+        schema: 'yam.benchmark-report.v1',
+        generated_at: new Date().toISOString(),
+        label: String(flags.label || 'unnamed'),
+        baseline,
+        current,
+        unit: String(flags.unit || ''),
+        target,
+        delta,
+        percent,
+        status,
+        tool_intent: normalizeToolIntent(flags.intent || 'read_only'),
+        rollback_hint: String(flags.rollback_hint || (status === 'regressed' ? 'inspect the optimization patch and revert the touched surface if the regression is confirmed' : 'no rollback action recorded')),
+        next_action: String(flags.next_action || benchmarkNextAction(status)),
+        truth_status: hasNumbers ? 'verified' : 'partial'
+    };
+    printJsonOrHuman(result, Boolean(flags.json), 'Benchmark report');
+    if (status === 'regressed')
+        process.exitCode = 1;
+}
+function numberOrNull(value) {
+    if (value === undefined || value === null || value === '')
+        return null;
+    const number = Number(value);
+    return Number.isFinite(number) ? number : null;
+}
+function benchmarkStatus({ baseline, current, target }) {
+    if (baseline === null || current === null)
+        return 'needs-baseline';
+    if (current === baseline)
+        return 'unchanged';
+    if (target === 'higher')
+        return current > baseline ? 'improved' : 'regressed';
+    return current < baseline ? 'improved' : 'regressed';
+}
+function benchmarkNextAction(status) {
+    if (status === 'improved')
+        return 'record the measurement source and keep the smallest relevant regression check';
+    if (status === 'regressed')
+        return 'treat this as a fix-first item before continuing planned optimization';
+    if (status === 'unchanged')
+        return 'keep the change only if it improves clarity or enables the next measured step';
+    return 'capture baseline and current values before claiming optimization impact';
+}
 function parseSimpleFlags(args = [], allowed = new Set()) {
     const flags = {};
     const positionals = [];
@@ -1179,14 +1948,19 @@ function parseSimpleFlags(args = [], allowed = new Set()) {
         if (allowed.size && !allowed.has(key))
             continue;
         const normalizedKey = key.replace(/-/g, '_');
-        if (['json', 'full-page'].includes(key)) {
+        if (['json', 'full-page', 'requested', 'attempted', 'available', 'wait-loop', 'cleanup-checked'].includes(key)) {
             flags[normalizedKey] = true;
             continue;
         }
         const value = inlineValue ?? args[index + 1] ?? '';
         if (inlineValue === undefined)
             index += 1;
-        flags[normalizedKey] = value;
+        if (flags[normalizedKey] !== undefined) {
+            flags[normalizedKey] = [...arrayFlag(flags[normalizedKey]), value];
+        }
+        else {
+            flags[normalizedKey] = value;
+        }
     }
     flags._ = positionals;
     return flags;
@@ -1326,9 +2100,11 @@ async function proof(args = []) {
     printProofList('Evidence', summary.evidence);
     printProofList('Visual evidence', summary.visual);
     printProofList('Runtime evidence', summary.runtime);
+    printProofList('Runtime backend evidence', summary.runtimeBackendEvidence || []);
     printProofList('Visual provenance', summary.visualProvenance || []);
     printProofList('Mission patch envelope', summary.missionEnvelope || []);
     printProofList('Rollback hint', summary.rollbackHint || []);
+    printProofList('Media proof', summary.mediaProof || []);
     printProofList('Changed surfaces', summary.changed);
     printProofList('Skipped', summary.skipped);
     printProofList('Blocked', summary.blocked);
@@ -1404,6 +2180,11 @@ function buildProofSummary(parsed, artifact) {
         evidence: [...artifact.evidence, ...arrayFlag(parsed.flags.evidence)],
         visual: [...artifact.visual, ...arrayFlag(parsed.flags.visual)],
         runtime: [...artifact.runtime, ...arrayFlag(parsed.flags.runtime)],
+        runtimeBackendEvidence: [
+            ...structuredEvidenceList(artifact.runtimeBackendEvidence),
+            ...structuredEvidenceList(parsed.flags.runtime_backend_evidence),
+            ...directRuntimeBackendEvidence(parsed.flags)
+        ],
         visualProvenance: [
             ...structuredEvidenceList(artifact.visualProvenance),
             ...structuredEvidenceList(parsed.flags.visual_provenance)
@@ -1416,6 +2197,10 @@ function buildProofSummary(parsed, artifact) {
             ...structuredEvidenceList(artifact.rollbackHint),
             ...structuredEvidenceList(parsed.flags.rollback_hint)
         ],
+        mediaProof: [
+            ...structuredEvidenceList(artifact.mediaProof),
+            ...structuredEvidenceList(parsed.flags.media_proof)
+        ],
         cleanup: parsed.flags.cleanup || artifact.cleanup || '',
         changed: [...artifact.changed, ...arrayFlag(parsed.flags.changed)],
         skipped: [...artifact.skipped, ...arrayFlag(parsed.flags.skipped)],
@@ -1465,6 +2250,9 @@ function renderProofMarkdown(summary) {
         '## Runtime evidence',
         ...renderProofMarkdownList(summary.runtime),
         '',
+        '## Runtime backend evidence',
+        ...renderProofMarkdownList(summary.runtimeBackendEvidence || []),
+        '',
         '## Visual provenance',
         ...renderProofMarkdownList(summary.visualProvenance || []),
         '',
@@ -1474,6 +2262,9 @@ function renderProofMarkdown(summary) {
         '## Rollback hint',
         ...renderProofMarkdownList(summary.rollbackHint || []),
         '',
+        '## Media proof',
+        ...renderProofMarkdownList(summary.mediaProof || []),
+        '',
         '## Changed surfaces',
         ...renderProofMarkdownList(summary.changed),
         '',
@@ -1504,7 +2295,7 @@ function renderProofMarkdownList(values) {
 function parseProofArgs(args = []) {
     const flags = {};
     const positionals = [];
-    const aliases = new Set(['goal', 'route', 'truth', 'command', 'evidence', 'visual', 'runtime', 'visual-provenance', 'mission-envelope', 'rollback-hint', 'cleanup', 'changed', 'skipped', 'blocked', 'assumed', 'assumption', 'unverified', 'from', 'format', 'out', 'file', 'json', 'require-runtime', 'require-real-runtime', 'require-tmux', 'require-visual']);
+    const aliases = new Set(['goal', 'route', 'truth', 'command', 'evidence', 'visual', 'runtime', 'runtime-backend', 'runtime-claim', 'runtime-evidence-id', 'runtime-command', 'cleanup-checked', 'runtime-note', 'runtime-backend-evidence', 'visual-provenance', 'mission-envelope', 'rollback-hint', 'media-proof', 'cleanup', 'changed', 'skipped', 'blocked', 'assumed', 'assumption', 'unverified', 'from', 'format', 'out', 'file', 'json', 'require-runtime', 'require-real-runtime', 'require-tmux', 'require-visual']);
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (arg.startsWith('--')) {
@@ -1513,14 +2304,14 @@ function parseProofArgs(args = []) {
             if (!aliases.has(key))
                 continue;
             const normalizedKey = key.replace(/-/g, '_');
-            if (key === 'json' || key.startsWith('require-')) {
+            if (key === 'json' || key.startsWith('require-') || key === 'cleanup-checked') {
                 flags[normalizedKey] = true;
                 continue;
             }
             const value = inlineValue ?? args[index + 1] ?? '';
             if (inlineValue === undefined)
                 index += 1;
-            if (['command', 'evidence', 'visual', 'runtime', 'visual-provenance', 'mission-envelope', 'rollback-hint', 'changed', 'skipped', 'blocked', 'assumed', 'assumption', 'unverified'].includes(key)) {
+            if (['command', 'evidence', 'visual', 'runtime', 'runtime-backend-evidence', 'visual-provenance', 'mission-envelope', 'rollback-hint', 'media-proof', 'changed', 'skipped', 'blocked', 'assumed', 'assumption', 'unverified'].includes(key)) {
                 flags[normalizedKey] = [...arrayFlag(flags[normalizedKey]), value];
             }
             else {
@@ -1559,9 +2350,11 @@ function emptyProofArtifact() {
         evidence: [],
         visual: [],
         runtime: [],
+        runtimeBackendEvidence: [],
         visualProvenance: [],
         missionEnvelope: [],
         rollbackHint: [],
+        mediaProof: [],
         cleanup: '',
         changed: [],
         skipped: [],
@@ -1583,9 +2376,11 @@ async function parseProofJson(file, empty) {
             evidence: arrayFlag(data.evidence),
             visual: arrayFlag(data.visual || data.visualEvidence),
             runtime: arrayFlag(data.runtime || data.runtimeEvidence),
+            runtimeBackendEvidence: structuredEvidenceList(data.runtimeBackendEvidence || data.runtime_backend_evidence),
             visualProvenance: structuredEvidenceList(data.visualProvenance || data.visual_provenance),
             missionEnvelope: structuredEvidenceList(data.missionEnvelope || data.mission_envelope),
             rollbackHint: structuredEvidenceList(data.rollbackHint || data.rollback_hint),
+            mediaProof: structuredEvidenceList(data.mediaProof || data.media_proof),
             cleanup: String(data.cleanup || data.cleanupStatus || ''),
             changed: arrayFlag(data.changed || data.files),
             skipped: arrayFlag(data.skipped),
@@ -1611,9 +2406,11 @@ async function parseProofMarkdown(file, empty) {
         evidence: readProofList(text, 'Evidence'),
         visual: readProofList(text, 'Visual evidence'),
         runtime: firstProofList(text, ['Runtime evidence', 'Processes', 'tmux']),
+        runtimeBackendEvidence: readProofList(text, 'Runtime backend evidence'),
         visualProvenance: readProofList(text, 'Visual provenance'),
         missionEnvelope: readProofList(text, 'Mission patch envelope'),
         rollbackHint: readProofList(text, 'Rollback hint'),
+        mediaProof: readProofList(text, 'Media proof'),
         cleanup: readProofField(text, 'Cleanup') || readProofField(text, 'Cleanup status'),
         changed: firstProofList(text, ['Changed surfaces', 'Files']),
         skipped: readProofList(text, 'Skipped'),
@@ -1661,6 +2458,18 @@ function arrayFlag(value) {
 function structuredEvidenceList(value) {
     return arrayFlag(value).map((item) => formatStructuredEvidence(item)).filter(Boolean);
 }
+function directRuntimeBackendEvidence(flags) {
+    if (!flags.runtime_backend && !flags.runtime_claim && !flags.runtime_evidence_id && !flags.runtime_command && !flags.runtime_note && !flags.cleanup_checked)
+        return [];
+    return [JSON.stringify(buildRuntimeBackendEvidence({
+            backend: flags.runtime_backend,
+            claim: flags.runtime_claim,
+            evidence_id: flags.runtime_evidence_id,
+            command: flags.runtime_command,
+            cleanup_checked: Boolean(flags.cleanup_checked),
+            note: flags.runtime_note
+        }))];
+}
 function formatStructuredEvidence(value) {
     if (!value)
         return '';
@@ -1682,6 +2491,12 @@ function formatStructuredEvidence(value) {
         if (data.schema === 'yam.rollback-hint.v1' || data.touched_files || data.safe_revert_note) {
             return JSON.stringify(buildRollbackHint(data));
         }
+        if (data.schema === 'yam.runtime-backend-evidence.v1' || data.backend || data.evidence_id) {
+            return JSON.stringify(buildRuntimeBackendEvidence(data));
+        }
+        if (data.schema === 'yam.media-generation-proof.v1' || data.generation_requested || data.output_hash) {
+            return JSON.stringify(buildMediaGenerationProof(data));
+        }
         return JSON.stringify(data);
     }
     catch {
@@ -1690,7 +2505,7 @@ function formatStructuredEvidence(value) {
 }
 function hasProofEvidence(parsed) {
     const flags = parsed.flags || {};
-    return ['command', 'evidence', 'visual', 'runtime', 'visual_provenance', 'mission_envelope', 'rollback_hint', 'changed', 'skipped', 'blocked'].some((key) => arrayFlag(flags[key]).length > 0) || Boolean(flags.cleanup);
+    return ['command', 'evidence', 'visual', 'runtime', 'runtime_backend_evidence', 'visual_provenance', 'mission_envelope', 'rollback_hint', 'media_proof', 'changed', 'skipped', 'blocked'].some((key) => arrayFlag(flags[key]).length > 0) || Boolean(flags.cleanup || flags.runtime_backend || flags.runtime_claim);
 }
 function printProofList(label, values) {
     console.log(`- ${label}:`);
@@ -1944,7 +2759,8 @@ async function detectProject(targetDir = process.cwd(), { quiet = false } = {})
             lint: null,
             test: null,
             build: null
-        }
+        },
+        frameworkChecklist: null
     };
     if (!result.packageJson) {
         if (!quiet) {
@@ -1961,6 +2777,7 @@ async function detectProject(targetDir = process.cwd(), { quiet = false } = {})
     result.commands.lint = runCommand(result.packageManager, pickScript(scripts, ['lint']));
     result.commands.test = runCommand(result.packageManager, pickScript(scripts, ['test', 'spec']));
     result.commands.build = runCommand(result.packageManager, pickScript(scripts, ['build']));
+    result.frameworkChecklist = await detectFrameworkChecklist(dir, pkg);
     if (!quiet)
         printDetection(result);
     return result;
@@ -1978,6 +2795,13 @@ function printDetection(result) {
     console.log(`- $quick: ${result.commands.typecheck || result.commands.lint || result.commands.test || result.commands.build || 'Level 0 read/inspect; no command detected'}`);
     console.log(`- $ueye: ${result.commands.typecheck || result.commands.build || 'Browser/screenshot check; no command detected'}`);
     console.log(`- $deep: ${[result.commands.typecheck, result.commands.lint, result.commands.test, result.commands.build].filter(Boolean).join(' && ') || `No command detected; define in ${PROJECT_PACK}`}`);
+    if (result.frameworkChecklist?.detected) {
+        console.log('');
+        console.log(`Framework checklist: ${result.frameworkChecklist.framework}`);
+        for (const check of result.frameworkChecklist.checks) {
+            console.log(`- ${check.id}: ${check.label} (${check.route})`);
+        }
+    }
 }
 function budget(routeArg = '') {
     const normalized = normalizeRoute(routeArg);
@@ -2383,6 +3207,14 @@ async function main() {
         return proof(process.argv.slice(3));
     if (command === 'ueye')
         return ueye(process.argv.slice(3));
+    if (command === 'media')
+        return media(process.argv.slice(3));
+    if (command === 'runtime')
+        return runtime(process.argv.slice(3));
+    if (command === 'mission')
+        return mission(process.argv.slice(3));
+    if (command === 'benchmark')
+        return benchmark(process.argv.slice(3));
     if (command === 'release')
         return release(process.argv.slice(3));
     if (command === 'safety')
@@ -2406,7 +3238,7 @@ async function main() {
     if (command === 'verify')
         return verify();
     if (command === 'doctor')
-        return doctor();
+        return doctor(process.argv.slice(3));
     if (command === 'examples')
         return examples();
     if (command === 'path')