yam-flow 0.1.1 → 0.1.3

package/dist/bin/yam.js

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import fsp from 'node:fs/promises';
+import { createRequire } from 'node:module';
 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);
 }
@@ -118,6 +120,10 @@ Usage:
   yam tools doctor [dir]
   yam proof [dir|--from file] [--route route] [--truth status] [--command text] [--evidence text]
   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 release report [--json]
   yam safety [text...]
   yam memory <init|add|list|summary|resolve> [dir] [options]
@@ -126,7 +132,7 @@ Usage:
   yam tune-log [dir]
   yam install
   yam uninstall
-  yam doctor
+  yam doctor [--json]
   yam examples
   yam path
   yam version
@@ -355,7 +361,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')))
@@ -386,18 +419,33 @@ 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;
-    }
-    console.log('yam doctor: issues');
-    for (const issue of issues)
-        console.log(`- ${issue}`);
-    process.exitCode = 1;
+    const globalHook = await readJsonOrDefault(path.join(os.homedir(), '.codex', 'hooks.json'), {});
+    return {
+        schema: 'yam.doctor.v1',
+        generatedAt: new Date().toISOString(),
+        ok: issues.length === 0,
+        issues,
+        nextActions: doctorNextActions(issues),
+        yamLiteHook: hookConfigHasYamLite(globalHook) ? 'enabled' : 'disabled'
+    };
+}
+function doctorNextActions(issues = []) {
+    const actions = [];
+    for (const issue of issues) {
+        if (/missing source skill/i.test(issue))
+            actions.push('run from a complete yam-flow checkout or reinstall the published package');
+        else if (/missing truth matrix/i.test(issue))
+            actions.push('restore references/truth-matrix.md before publishing');
+        else if (/unexpected local hooks/i.test(issue))
+            actions.push('remove project hooks unless this repo is intentionally dogfooding them');
+        else if (/unexpected .*automation/i.test(issue))
+            actions.push('remove stale yam/timeto automations before claiming clean install state');
+        else if (/legacy|retired/i.test(issue))
+            actions.push('run `yam install` to replace old skill entries');
+        else if (/verify reported/i.test(issue))
+            actions.push('run `npm run verify` and fix the reported package boundary or metadata issue');
+    }
+    return [...new Set(actions)];
 }
 async function tools(args = []) {
     const subcommand = args[0] || 'doctor';
@@ -456,6 +504,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),
@@ -485,8 +534,16 @@ async function buildToolsDoctorReport(targetDir = process.cwd()) {
         packageManager: detection.packageJson ? detection.packageManager : null,
         instructionSurfaces,
         projectSurfaces,
+        frameworkChecklist,
         sqlScan,
         riskNotes,
+        nextActions: toolsDoctorNextActions({
+            pack,
+            rows,
+            riskNotes,
+            frameworkChecklist,
+            commands: detection.packageJson ? detection.commands : {}
+        }),
         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',
@@ -518,6 +575,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)`);
@@ -531,6 +595,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}`);
@@ -607,6 +677,53 @@ 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({ pack, rows, riskNotes, frameworkChecklist, commands }) {
+    const actions = [];
+    if (!pack)
+        actions.push('create or refresh yam.project.md so route choices reuse local project context');
+    if (rows.some((row) => row.name === 'Yam skills' && row.status !== 'ready'))
+        actions.push('run `yam install` and restart Codex before relying on installed skills');
+    if (riskNotes.some((note) => note.level === 'danger'))
+        actions.push('use $deep before claiming destructive database or production write safety');
+    if (frameworkChecklist?.detected && !commands?.build && !commands?.typecheck)
+        actions.push('add or document a small build/typecheck command for implementation verification');
+    if (frameworkChecklist?.uiLike)
+        actions.push('for Ueye verified claims, record reference, actual screenshot, and comparison result');
+    return [...new Set(actions)];
+}
 async function scanSqlFiles(rootDir, { maxFiles = 30, maxBytes = 200000, maxDepth = 5 } = {}) {
     const root = path.resolve(rootDir || process.cwd());
     const files = [];
@@ -1017,6 +1134,390 @@ async function readStdinTextIfAvailable() {
         chunks.push(Buffer.from(chunk));
     return Buffer.concat(chunks).toString('utf8').trim();
 }
+async function ueye(args = []) {
+    const subcommand = args[0] || 'help';
+    if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h')
+        return ueyeUsage();
+    if (subcommand === 'capture')
+        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();
+}
+function ueyeUsage() {
+    console.log(`yam ueye
+
+Opt-in visual evidence helpers. Ueye stays one skill: fast by default, capture/compare only when verified visual claims need real evidence.
+
+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] [--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 without requiring a new capture.
+`);
+}
+async function ueyeCapture(args = []) {
+    if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h')
+        return ueyeUsage();
+    const flags = parseSimpleFlags(args, new Set(['url', 'out', 'viewport', 'wait-until', 'timeout', 'full-page', 'json']));
+    const url = String(flags.url || '');
+    const out = String(flags.out || '');
+    if (!url || !out) {
+        console.error('usage: yam ueye capture --url URL --out screenshot.png [--viewport 1440x900] [--full-page] [--json]');
+        process.exitCode = 1;
+        return;
+    }
+    const target = path.resolve(expandHome(out));
+    const viewport = parseViewport(String(flags.viewport || '1440x900'));
+    const timeout = Number(flags.timeout || 30000);
+    const waitUntil = String(flags.wait_until || 'networkidle');
+    let browser;
+    try {
+        const playwright = await loadOptionalPlaywright();
+        const chromium = playwright?.chromium;
+        if (!chromium)
+            throw new Error('Playwright chromium launcher was not found');
+        await fsp.mkdir(path.dirname(target), { recursive: true });
+        browser = await chromium.launch({ headless: true });
+        const page = await browser.newPage({ viewport });
+        await page.goto(url, { waitUntil, timeout });
+        await page.screenshot({ path: target, fullPage: Boolean(flags.full_page) });
+        const info = await imageFileInfo(target);
+        const result = {
+            schema: 'yam.ueye-capture.v1',
+            status: 'verified',
+            url,
+            out: target,
+            viewport: `${viewport.width}x${viewport.height}`,
+            full_page: Boolean(flags.full_page),
+            sha256: info.sha256,
+            dimensions: info.dimensions,
+            visual_evidence: `browser screenshot captured: ${target} (${info.dimensions}, sha256:${info.sha256})`
+        };
+        printJsonOrHuman(result, Boolean(flags.json), 'Ueye capture');
+    }
+    catch (error) {
+        const result = {
+            schema: 'yam.ueye-capture.v1',
+            status: 'blocked',
+            url,
+            out: target,
+            reason: errorMessage(error),
+            next_action: 'Install Playwright in the current project or provide a user/browser screenshot, then use `yam ueye compare`.',
+            visual_cap: 'blocked'
+        };
+        printJsonOrHuman(result, Boolean(flags.json), 'Ueye capture');
+        process.exitCode = 1;
+    }
+    finally {
+        if (browser)
+            await browser.close().catch(() => { });
+    }
+}
+async function ueyeCompare(args = []) {
+    if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h')
+        return ueyeUsage();
+    const flags = parseSimpleFlags(args, new Set(['reference', 'ref', 'actual', 'screenshot', 'json', 'reference-id', 'screenshot-id']));
+    const reference = String(flags.reference || flags.ref || '');
+    const actual = String(flags.actual || flags.screenshot || '');
+    if (!reference || !actual) {
+        console.error('usage: yam ueye compare --reference ref.png --actual screenshot.png [--json]');
+        process.exitCode = 1;
+        return;
+    }
+    const referencePath = path.resolve(expandHome(reference));
+    const actualPath = path.resolve(expandHome(actual));
+    try {
+        const referenceInfo = await imageFileInfo(referencePath);
+        const actualInfo = await imageFileInfo(actualPath);
+        if (referenceInfo.dimensions === 'unknown' || actualInfo.dimensions === 'unknown') {
+            throw new Error('compare requires image files with readable PNG, JPEG, or GIF dimensions');
+        }
+        const exactMatch = referenceInfo.sha256 === actualInfo.sha256;
+        const sameDimensions = referenceInfo.dimensions === actualInfo.dimensions;
+        const comparisonResult = exactMatch ? 'matched' : 'different';
+        const truthStatus = exactMatch ? 'verified' : 'partial';
+        const provenance = buildUeyeVisualProvenance({
+            source_kind: 'implementation_screenshot',
+            source_path: actualPath,
+            source_hash: actualInfo.sha256,
+            reference_id: String(flags.reference_id || path.basename(referencePath)),
+            screenshot_id: String(flags.screenshot_id || path.basename(actualPath)),
+            local_only: true,
+            redacted: false,
+            operator_provided: false,
+            comparison_result: comparisonResult,
+            truth_status: truthStatus
+        });
+        const result = {
+            schema: 'yam.ueye-compare.v1',
+            status: truthStatus,
+            comparison_result: comparisonResult,
+            exact_match: exactMatch,
+            same_dimensions: sameDimensions,
+            reference: referenceInfo,
+            actual: actualInfo,
+            visual_evidence: `browser/local screenshot comparison executed: reference=${referencePath}, actual=${actualPath}, result=${comparisonResult}`,
+            visual_provenance: provenance,
+            proof_hint: `yam proof --route ueye --truth ${truthStatus} --visual "browser/local screenshot comparison executed: ${comparisonResult}" --visual-provenance '${JSON.stringify(provenance)}' --require-visual`
+        };
+        printJsonOrHuman(result, Boolean(flags.json), 'Ueye compare');
+    }
+    catch (error) {
+        const result = {
+            schema: 'yam.ueye-compare.v1',
+            status: 'blocked',
+            comparison_result: 'not-verified',
+            reason: errorMessage(error),
+            visual_cap: 'blocked'
+        };
+        printJsonOrHuman(result, Boolean(flags.json), 'Ueye compare');
+        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', '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 || '');
+    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: 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,
+                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_action || '')
+    });
+    const result = {
+        ...report,
+        capture_backend: String(flags.capture_backend || 'not-recorded'),
+        compare_backend: String(flags.compare_backend || 'local-file-hash')
+    };
+    printJsonOrHuman(result, Boolean(flags.json), 'Ueye report');
+    if (report.truth_status === 'blocked')
+        process.exitCode = 1;
+}
+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;
+}
+function parseSimpleFlags(args = [], allowed = new Set()) {
+    const flags = {};
+    const positionals = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = String(args[index] || '');
+        if (!arg.startsWith('--')) {
+            positionals.push(arg);
+            continue;
+        }
+        const [rawKey, inlineValue] = arg.includes('=') ? arg.split(/=(.*)/s, 2) : [arg, undefined];
+        const key = rawKey.slice(2);
+        if (allowed.size && !allowed.has(key))
+            continue;
+        const normalizedKey = key.replace(/-/g, '_');
+        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;
+    }
+    flags._ = positionals;
+    return flags;
+}
+function parseViewport(value = '1440x900') {
+    const match = String(value || '').match(/^(\d{2,5})x(\d{2,5})$/i);
+    if (!match)
+        return { width: 1440, height: 900 };
+    return { width: Number(match[1]), height: Number(match[2]) };
+}
+async function loadOptionalPlaywright() {
+    let projectError = '';
+    try {
+        const projectRequire = createRequire(path.join(process.cwd(), 'package.json'));
+        return projectRequire('playwright');
+    }
+    catch (error) {
+        projectError = errorMessage(error);
+        // Fall through to the yam package context for local development or bundled installs.
+    }
+    const dynamicImport = new Function('specifier', 'return import(specifier)');
+    try {
+        return await dynamicImport('playwright');
+    }
+    catch (error) {
+        throw new Error(`Playwright not found from current project or yam package context. Current project: ${projectError}; package context: ${errorMessage(error)}`);
+    }
+}
+async function imageFileInfo(file) {
+    const absolute = path.resolve(expandHome(file));
+    const buffer = await fsp.readFile(absolute);
+    const stat = await fsp.stat(absolute);
+    return {
+        path: absolute,
+        sha256: crypto.createHash('sha256').update(buffer).digest('hex'),
+        bytes: stat.size,
+        dimensions: imageDimensions(buffer)
+    };
+}
+function imageDimensions(buffer) {
+    const png = pngDimensions(buffer);
+    if (png)
+        return png;
+    const jpeg = jpegDimensions(buffer);
+    if (jpeg)
+        return jpeg;
+    const gif = gifDimensions(buffer);
+    if (gif)
+        return gif;
+    return 'unknown';
+}
+function pngDimensions(buffer) {
+    if (buffer.length < 24)
+        return '';
+    if (buffer.readUInt32BE(0) !== 0x89504e47 || buffer.readUInt32BE(4) !== 0x0d0a1a0a)
+        return '';
+    return `${buffer.readUInt32BE(16)}x${buffer.readUInt32BE(20)}`;
+}
+function gifDimensions(buffer) {
+    if (buffer.length < 10)
+        return '';
+    const signature = buffer.toString('ascii', 0, 6);
+    if (signature !== 'GIF87a' && signature !== 'GIF89a')
+        return '';
+    return `${buffer.readUInt16LE(6)}x${buffer.readUInt16LE(8)}`;
+}
+function jpegDimensions(buffer) {
+    if (buffer.length < 4 || buffer[0] !== 0xff || buffer[1] !== 0xd8)
+        return '';
+    let offset = 2;
+    while (offset < buffer.length) {
+        if (buffer[offset] !== 0xff)
+            return '';
+        const marker = buffer[offset + 1];
+        const length = buffer.readUInt16BE(offset + 2);
+        if (marker >= 0xc0 && marker <= 0xc3 && offset + 8 < buffer.length) {
+            return `${buffer.readUInt16BE(offset + 7)}x${buffer.readUInt16BE(offset + 5)}`;
+        }
+        offset += 2 + length;
+    }
+    return '';
+}
+function printJsonOrHuman(result, json = false, label = 'yam') {
+    if (json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(label);
+    for (const [key, value] of Object.entries(result)) {
+        if (key === 'schema')
+            continue;
+        if (typeof value === 'object' && value !== null) {
+            console.log(`- ${key}: ${JSON.stringify(value)}`);
+        }
+        else {
+            console.log(`- ${key}: ${value}`);
+        }
+    }
+}
 function detectDbSafetyText(text = '') {
     return detectTrustDbSafetyText(text);
 }
@@ -1057,9 +1558,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);
@@ -1135,6 +1638,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)
@@ -1147,6 +1655,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)],
@@ -1196,6 +1708,9 @@ function renderProofMarkdown(summary) {
         '## Runtime evidence',
         ...renderProofMarkdownList(summary.runtime),
         '',
+        '## Runtime backend evidence',
+        ...renderProofMarkdownList(summary.runtimeBackendEvidence || []),
+        '',
         '## Visual provenance',
         ...renderProofMarkdownList(summary.visualProvenance || []),
         '',
@@ -1205,6 +1720,9 @@ function renderProofMarkdown(summary) {
         '## Rollback hint',
         ...renderProofMarkdownList(summary.rollbackHint || []),
         '',
+        '## Media proof',
+        ...renderProofMarkdownList(summary.mediaProof || []),
+        '',
         '## Changed surfaces',
         ...renderProofMarkdownList(summary.changed),
         '',
@@ -1235,7 +1753,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('--')) {
@@ -1244,14 +1762,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 {
@@ -1290,9 +1808,11 @@ function emptyProofArtifact() {
         evidence: [],
         visual: [],
         runtime: [],
+        runtimeBackendEvidence: [],
         visualProvenance: [],
         missionEnvelope: [],
         rollbackHint: [],
+        mediaProof: [],
         cleanup: '',
         changed: [],
         skipped: [],
@@ -1314,9 +1834,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),
@@ -1342,9 +1864,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'),
@@ -1392,6 +1916,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 '';
@@ -1413,6 +1949,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 {
@@ -1421,7 +1963,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}:`);
@@ -1675,7 +2217,8 @@ async function detectProject(targetDir = process.cwd(), { quiet = false } = {})
             lint: null,
             test: null,
             build: null
-        }
+        },
+        frameworkChecklist: null
     };
     if (!result.packageJson) {
         if (!quiet) {
@@ -1692,6 +2235,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;
@@ -1709,6 +2253,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);
@@ -2112,6 +2663,10 @@ async function main() {
         return tools(process.argv.slice(3));
     if (command === 'proof')
         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 === 'release')
         return release(process.argv.slice(3));
     if (command === 'safety')
@@ -2135,7 +2690,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')