yam-flow 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to yam-flow are documented here.
 
+## v0.1.5 - 2026-06-04
+
+### Added
+
+- Added Ueye surface context metadata for provider context, provider badge, execution surface, app surface, browser surface, control mode, preserved URL, preserved state, and evidence id.
+- Added surface context output to `yam ueye capture`, `yam ueye compare`, and `yam ueye report` so visual evidence can say where and how it was observed.
+- Added provider and execution surface fields to Ueye visual provenance records.
+
+### Improved
+
+- Strengthened `yam ueye report` for fast UI state preservation without making capture or compare an always-on gate.
+- Updated Ueye docs and templates so visual proof can distinguish source files, local screenshots, in-app browser checks, and other execution surfaces.
+
 ## v0.1.4 - 2026-06-03
 
 ### Added

package/COMMANDS.md

@@ -44,7 +44,7 @@ Opt-in visual evidence helpers:
 ```bash
 yam ueye capture --url http://localhost:3000 --out .yam/screens/home.png
 yam ueye compare --reference ./reference.png --actual .yam/screens/home.png
-yam ueye report --reference ./reference.png --actual .yam/screens/home.png --review-session-id pricing-card-v1 --similar "overall hierarchy" --different "button glow intensity" --missing "mobile state" --design-quality needs-polish --json
+yam ueye report --reference ./reference.png --actual .yam/screens/home.png --review-session-id pricing-card-v1 --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --similar "overall hierarchy" --different "button glow intensity" --missing "mobile state" --design-quality needs-polish --json
 yam media proof --requested --attempted --output ./generated.png --wait-loop --json
 yam proof --route ueye --truth partial --visual "browser/local screenshot comparison executed" --require-visual
 ```
@@ -149,7 +149,7 @@ yam proof --route ueye --truth verified --visual "reference image only"
 yam proof --route ueye --truth partial --visual-provenance '{"source_kind":"reference","source_hash":"unknown","comparison_result":"not-verified","truth_status":"partial"}'
 yam ueye capture --url http://localhost:3000 --out .yam/screens/home.png
 yam ueye compare --reference ./reference.png --actual .yam/screens/home.png --json
-yam ueye report --reference ./reference.png --actual .yam/screens/home.png --design-quality pass --json
+yam ueye report --reference ./reference.png --actual .yam/screens/home.png --design-quality pass --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --json
 yam media proof --requested --attempted --output ./generated.png --wait-loop --json
 yam runtime evidence --backend terminal --claim observed --evidence-id dev-server-1 --command "npm run dev" --json
 yam mission queue --agent-id implementer --scope "checkout form" --changed src/checkout.tsx --verification-hint "npm run typecheck" --rollback-hint "revert checkout form patch if typecheck or smoke fails" --json

package/README.md

@@ -129,7 +129,7 @@ yam proof --route ueye --truth verified --visual "reference image only"
 yam proof --route ueye --truth partial --visual-provenance '{"source_kind":"reference","source_hash":"unknown","comparison_result":"not-verified","truth_status":"partial"}'
 yam ueye capture --url http://localhost:3000 --out .yam/screens/home.png
 yam ueye compare --reference ./reference.png --actual .yam/screens/home.png
-yam ueye report --reference ./reference.png --actual .yam/screens/home.png --design-quality needs-polish --json
+yam ueye report --reference ./reference.png --actual .yam/screens/home.png --design-quality needs-polish --provider-context local --execution-surface in-app-browser --app-surface codex-app --browser-surface in-app-browser --preserved-state --json
 yam media proof --requested --attempted --output ./generated.png --wait-loop --json
 yam proof --route mission --mission-envelope '{"agent_id":"implementer","assigned_scope":"target component","changed_files":["src/file.ts"],"verification_hint":"npm run typecheck","truth_status":"partial"}'
 yam release report --json
@@ -177,6 +177,7 @@ Publishing still requires confirming the final npm package name and account acce
 - runtime truth matrix
 - visual evidence caps
 - Ueye visual run reports
+- Ueye surface context metadata
 - runtime backend evidence
 - runtime evidence mini summaries
 - mission patch queue lite records
@@ -197,6 +198,7 @@ These shapes keep reports machine-readable without turning normal work into a he
 - Benchmark optimization loop lite: use `yam measure <route>` and `yam template tuning` to record baseline, one route wording change, rerun result, keep/revert decision, and stop condition.
 - Structured diagnostic next action: every doctor/release diagnostic should say what was observed, what evidence supports it, what to do next, owner route, severity, and truth status.
 - Ueye review continuity/comparison report: `$ueye` run reports can link a previous review, current evidence, comparison delta, design quality result, and next action.
+- Ueye surface context: `$ueye` run reports can record provider context, provider badge, execution surface, app surface, browser surface, control mode, preserved URL/state, and evidence id.
 
 ## Ueye Capture And Compare
 
@@ -205,14 +207,14 @@ These shapes keep reports machine-readable without turning normal work into a he
 ```bash
 yam ueye capture --url http://localhost:3000 --out .yam/screens/home.png
 yam ueye compare --reference ./reference.png --actual .yam/screens/home.png --json
-yam ueye report --reference ./reference.png --actual .yam/screens/home.png --design-quality pass --json
+yam ueye report --reference ./reference.png --actual .yam/screens/home.png --design-quality pass --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --preserved-state --json
 ```
 
 `capture` uses a Playwright install from the current project when present, then falls back to the package context. It does not install browsers or add runtime dependencies by itself. If capture is unavailable, the visual claim stays `partial` or `blocked` until a real screenshot is supplied.
 
 `compare` is local-only and dependency-free. It records file hashes, dimensions, comparison result, and proof-ready visual provenance. Exact image matches can be `verified`; different screenshots stay `partial` so visual parity is not overclaimed.
 
-`report` gathers reference sources, implementation screenshots, comparison result, continuity fields, design quality judgment, and next action into one compact proof-ready JSON object.
+`report` gathers reference sources, implementation screenshots, comparison result, continuity fields, design quality judgment, surface context, and next action into one compact proof-ready JSON object.
 
 Generated media can guide visual direction, but it cannot prove the implemented UI by itself:
 

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, buildMediaGenerationProof, buildMissionPatchEnvelope, buildRollbackHint, buildRuntimeBackendEvidence, buildUeyeVisualProvenance, buildUeyeRunReport, buildYamCompletionProof, detectDbSafetyText as detectTrustDbSafetyText, isTruthStatus } from '../lib/trust-kernel.js';
+import { TRUTH_STATUSES, buildMediaGenerationProof, buildMissionPatchEnvelope, buildRollbackHint, buildRuntimeBackendEvidence, buildUeyeVisualProvenance, buildUeyeRunReport, buildUeyeSurfaceContext, buildYamCompletionProof, detectDbSafetyText as detectTrustDbSafetyText, isTruthStatus } from '../lib/trust-kernel.js';
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -122,7 +122,7 @@ 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 ueye report [--reference ref.png] [--actual screenshot.png] [--provider-context local] [--execution-surface in-app-browser] [--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]
@@ -808,7 +808,7 @@ function toolsDoctorNextActionDetails({ pack, rows, riskNotes, frameworkChecklis
     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'));
+        actions.push(nextActionDetail('ueye-evidence', 'info', 'UI-like project detected', 'for Ueye verified claims, record reference, actual screenshot, comparison result, and surface context', 'yam ueye report --reference ref.png --actual shot.png --provider-context local --execution-surface in-app-browser --json'));
     return uniqueNextActionDetails(actions);
 }
 async function scanSqlFiles(rootDir, { maxFiles = 30, maxBytes = 200000, maxDepth = 5 } = {}) {
@@ -1366,7 +1366,7 @@ 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]
+  yam ueye report [--reference ref.png] [--actual screenshot.png] [--review-session-id id] [--provider-context local] [--execution-surface in-app-browser] [--app-surface codex-app] [--browser-surface in-app-browser] [--control-mode manual|automated] [--preserved-state] [--preserved-url URL] [--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.
@@ -1377,7 +1377,7 @@ Notes:
 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 flags = parseSimpleFlags(args, new Set(['url', 'out', 'viewport', 'wait-until', 'timeout', 'full-page', 'provider-context', 'provider-badge', 'execution-surface', 'app-surface', 'browser-surface', 'control-mode', 'preserved-state', 'preserved-url', 'evidence-id', 'screenshot-id', 'json']));
     const url = String(flags.url || '');
     const out = String(flags.out || '');
     if (!url || !out) {
@@ -1401,6 +1401,24 @@ async function ueyeCapture(args = []) {
         await page.goto(url, { waitUntil, timeout });
         await page.screenshot({ path: target, fullPage: Boolean(flags.full_page) });
         const info = await imageFileInfo(target);
+        const surfaceContext = buildUeyeSurfaceContext({
+            provider_context: String(flags.provider_context || 'local-playwright'),
+            provider_badge: String(flags.provider_badge || flags.provider_context || 'local-playwright'),
+            execution_surface: String(flags.execution_surface || 'browser-capture'),
+            app_surface: String(flags.app_surface || 'local-project'),
+            browser_surface: String(flags.browser_surface || 'playwright'),
+            control_mode: String(flags.control_mode || 'automated-capture'),
+            route: 'ueye',
+            mode: 'capture',
+            url,
+            viewport: `${viewport.width}x${viewport.height}`,
+            screenshot_id: String(flags.screenshot_id || path.basename(target)),
+            evidence_id: String(flags.evidence_id || `ueye-capture-${timestampId()}`),
+            preserved_state: Boolean(flags.preserved_state),
+            preserved_url: String(flags.preserved_url || url),
+            local_only: true,
+            truth_status: 'verified'
+        });
         const result = {
             schema: 'yam.ueye-capture.v1',
             status: 'verified',
@@ -1410,6 +1428,7 @@ async function ueyeCapture(args = []) {
             full_page: Boolean(flags.full_page),
             sha256: info.sha256,
             dimensions: info.dimensions,
+            surface_context: surfaceContext,
             visual_evidence: `browser screenshot captured: ${target} (${info.dimensions}, sha256:${info.sha256})`
         };
         printJsonOrHuman(result, Boolean(flags.json), 'Ueye capture');
@@ -1435,7 +1454,7 @@ async function ueyeCapture(args = []) {
 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 flags = parseSimpleFlags(args, new Set(['reference', 'ref', 'actual', 'screenshot', 'json', 'reference-id', 'screenshot-id', 'provider-context', 'provider-badge', 'execution-surface', 'app-surface', 'browser-surface', 'control-mode', 'preserved-state', 'preserved-url', 'url', 'viewport', 'evidence-id']));
     const reference = String(flags.reference || flags.ref || '');
     const actual = String(flags.actual || flags.screenshot || '');
     if (!reference || !actual) {
@@ -1455,12 +1474,35 @@ async function ueyeCompare(args = []) {
         const sameDimensions = referenceInfo.dimensions === actualInfo.dimensions;
         const comparisonResult = exactMatch ? 'matched' : 'different';
         const truthStatus = exactMatch ? 'verified' : 'partial';
+        const surfaceContext = buildUeyeSurfaceContext({
+            provider_context: String(flags.provider_context || 'local-file'),
+            provider_badge: String(flags.provider_badge || flags.provider_context || 'local-file'),
+            execution_surface: String(flags.execution_surface || 'local-file-compare'),
+            app_surface: String(flags.app_surface || 'local-project'),
+            browser_surface: String(flags.browser_surface || 'not-used'),
+            control_mode: String(flags.control_mode || 'local-compare'),
+            route: 'ueye',
+            mode: 'compare',
+            url: String(flags.url || ''),
+            viewport: String(flags.viewport || ''),
+            screenshot_id: String(flags.screenshot_id || path.basename(actualPath)),
+            evidence_id: String(flags.evidence_id || `ueye-compare-${timestampId()}`),
+            preserved_state: Boolean(flags.preserved_state),
+            preserved_url: String(flags.preserved_url || flags.url || ''),
+            local_only: true,
+            truth_status: truthStatus
+        });
         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)),
+            provider_context: surfaceContext.provider_context,
+            provider_badge: surfaceContext.provider_badge,
+            execution_surface: surfaceContext.execution_surface,
+            app_surface: surfaceContext.app_surface,
+            browser_surface: surfaceContext.browser_surface,
             local_only: true,
             redacted: false,
             operator_provided: false,
@@ -1475,6 +1517,7 @@ async function ueyeCompare(args = []) {
             same_dimensions: sameDimensions,
             reference: referenceInfo,
             actual: actualInfo,
+            surface_context: surfaceContext,
             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`
@@ -1496,7 +1539,7 @@ async function ueyeCompare(args = []) {
 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 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', 'provider-context', 'provider-badge', 'execution-surface', 'app-surface', 'browser-surface', 'control-mode', 'preserved-state', 'preserved-url', 'url', 'evidence-id', 'json']));
     const reference = String(flags.reference || flags.ref || '');
     const actual = String(flags.actual || flags.screenshot || '');
     const referenceSources = [];
@@ -1505,6 +1548,24 @@ async function ueyeReport(args = []) {
     let blockedReason = String(flags.blocked_reason || '');
     const reviewSessionId = String(flags.review_session_id || `ueye-${timestampId()}`);
     const previousReport = await readPreviousUeyeReport(flags.previous_report);
+    const surfaceContext = buildUeyeSurfaceContext({
+        provider_context: String(flags.provider_context || 'not-recorded'),
+        provider_badge: String(flags.provider_badge || flags.provider_context || 'not-recorded'),
+        execution_surface: String(flags.execution_surface || flags.capture_backend || 'not-recorded'),
+        app_surface: String(flags.app_surface || 'not-recorded'),
+        browser_surface: String(flags.browser_surface || flags.capture_backend || 'not-recorded'),
+        control_mode: String(flags.control_mode || 'not-recorded'),
+        route: 'ueye',
+        mode: 'report',
+        url: String(flags.url || flags.preserved_url || ''),
+        viewport: String(flags.viewport || ''),
+        screenshot_id: String(flags.current_screenshot_id || flags.screenshot_id || ''),
+        evidence_id: String(flags.evidence_id || reviewSessionId),
+        preserved_state: Boolean(flags.preserved_state),
+        preserved_url: String(flags.preserved_url || flags.url || ''),
+        local_only: true,
+        truth_status: actual ? 'partial' : 'assumed'
+    });
     try {
         if (reference) {
             const info = await imageFileInfo(reference);
@@ -1513,6 +1574,11 @@ async function ueyeReport(args = []) {
                 source_path: info.path,
                 source_hash: info.sha256,
                 reference_id: String(flags.reference_id || path.basename(info.path)),
+                provider_context: surfaceContext.provider_context,
+                provider_badge: surfaceContext.provider_badge,
+                execution_surface: surfaceContext.execution_surface,
+                app_surface: surfaceContext.app_surface,
+                browser_surface: surfaceContext.browser_surface,
                 local_only: true,
                 operator_provided: true,
                 comparison_result: 'reference-recorded',
@@ -1527,6 +1593,11 @@ async function ueyeReport(args = []) {
                 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)),
+                provider_context: surfaceContext.provider_context,
+                provider_badge: surfaceContext.provider_badge,
+                execution_surface: surfaceContext.execution_surface,
+                app_surface: surfaceContext.app_surface,
+                browser_surface: surfaceContext.browser_surface,
                 local_only: true,
                 operator_provided: false,
                 comparison_result: 'implementation-recorded',
@@ -1546,6 +1617,11 @@ async function ueyeReport(args = []) {
     const report = buildUeyeRunReport({
         reference_sources: referenceSources,
         implementation_sources: implementationSources,
+        surface_context: {
+            ...surfaceContext,
+            screenshot_id: surfaceContext.screenshot_id || String(flags.current_screenshot_id || flags.screenshot_id || implementationSources[0]?.screenshot_id || ''),
+            truth_status: blockedReason ? 'blocked' : implementationSources.length ? 'partial' : 'assumed'
+        },
         comparison_result: comparisonResult,
         design_quality: String(flags.design_quality || 'not-checked'),
         blocked_reason: blockedReason,
@@ -1556,6 +1632,7 @@ async function ueyeReport(args = []) {
         previousReport,
         referenceSources,
         implementationSources,
+        surfaceContext: report.surface_context,
         comparisonResult,
         designQuality: String(flags.design_quality || 'not-checked'),
         similar: arrayFlag(flags.similar),
@@ -1609,7 +1686,7 @@ async function readPreviousUeyeReport(file = '') {
         };
     }
 }
-function buildUeyeComparisonReport({ reviewSessionId, previousReport, referenceSources, implementationSources, comparisonResult, designQuality, similar, different, missing, notes, resolved, newFindings, stillOpen, regressions, previousScreenshotId, currentScreenshotId, viewport, state, nextAction, truthStatus }) {
+function buildUeyeComparisonReport({ reviewSessionId, previousReport, referenceSources, implementationSources, surfaceContext, 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';
@@ -1633,6 +1710,7 @@ function buildUeyeComparisonReport({ reviewSessionId, previousReport, referenceS
             reference_count: referenceSources.length,
             implementation_count: implementationSources.length
         },
+        surface_context: surfaceContext || buildUeyeSurfaceContext(),
         comparison_result: comparisonResult,
         design_quality: designQuality,
         similar,

package/dist/lib/trust-kernel.d.ts

@@ -38,12 +38,36 @@ export interface UeyeVisualProvenance {
     source_hash: string;
     reference_id: string;
     screenshot_id: string;
+    provider_context: string;
+    provider_badge: string;
+    execution_surface: string;
+    app_surface: string;
+    browser_surface: string;
     local_only: boolean;
     redacted: boolean;
     operator_provided: boolean;
     comparison_result: string;
     truth_status: TruthStatus;
 }
+export interface UeyeSurfaceContext {
+    schema: 'yam.ueye-surface-context.v1';
+    provider_context: string;
+    provider_badge: string;
+    execution_surface: string;
+    app_surface: string;
+    browser_surface: string;
+    control_mode: string;
+    route: string;
+    mode: string;
+    url: string;
+    viewport: string;
+    screenshot_id: string;
+    evidence_id: string;
+    preserved_state: boolean;
+    preserved_url: string;
+    local_only: boolean;
+    truth_status: TruthStatus;
+}
 export interface RollbackHint {
     schema: 'yam.rollback-hint.v1';
     touched_files: string[];
@@ -74,6 +98,7 @@ export interface UeyeRunReport {
     schema: 'yam.ueye-run-report.v1';
     reference_sources: UeyeVisualProvenance[];
     implementation_sources: UeyeVisualProvenance[];
+    surface_context: UeyeSurfaceContext;
     comparison_result: string;
     design_quality: string;
     blocked_reason: string;
@@ -164,6 +189,7 @@ export interface YamCompletionProof {
     runtimeTruth: RuntimeTruthMatrix;
 }
 export declare function buildUeyeVisualProvenance(input?: Partial<UeyeVisualProvenance>): UeyeVisualProvenance;
+export declare function buildUeyeSurfaceContext(input?: Partial<UeyeSurfaceContext>): UeyeSurfaceContext;
 export declare function buildRollbackHint(input?: Partial<RollbackHint>): RollbackHint;
 export declare function buildMissionPatchEnvelope(input?: Partial<MissionPatchEnvelope>): MissionPatchEnvelope;
 export declare function buildRuntimeBackendEvidence(input?: Partial<RuntimeBackendEvidence>): RuntimeBackendEvidence;

package/dist/lib/trust-kernel.js

@@ -19,6 +19,11 @@ export function buildUeyeVisualProvenance(input = {}) {
         source_hash: String(input.source_hash || 'unknown'),
         reference_id: String(input.reference_id || ''),
         screenshot_id: String(input.screenshot_id || ''),
+        provider_context: String(input.provider_context || 'not-recorded'),
+        provider_badge: String(input.provider_badge || 'not-recorded'),
+        execution_surface: String(input.execution_surface || 'not-recorded'),
+        app_surface: String(input.app_surface || 'not-recorded'),
+        browser_surface: String(input.browser_surface || 'not-recorded'),
         local_only: Boolean(input.local_only),
         redacted: Boolean(input.redacted),
         operator_provided: Boolean(input.operator_provided),
@@ -26,6 +31,27 @@ export function buildUeyeVisualProvenance(input = {}) {
         truth_status: truth
     };
 }
+export function buildUeyeSurfaceContext(input = {}) {
+    return {
+        schema: 'yam.ueye-surface-context.v1',
+        provider_context: String(input.provider_context || 'not-recorded'),
+        provider_badge: String(input.provider_badge || input.provider_context || 'not-recorded'),
+        execution_surface: String(input.execution_surface || 'not-recorded'),
+        app_surface: String(input.app_surface || 'not-recorded'),
+        browser_surface: String(input.browser_surface || 'not-recorded'),
+        control_mode: String(input.control_mode || 'not-recorded'),
+        route: String(input.route || 'ueye'),
+        mode: String(input.mode || 'report'),
+        url: String(input.url || ''),
+        viewport: String(input.viewport || ''),
+        screenshot_id: String(input.screenshot_id || ''),
+        evidence_id: String(input.evidence_id || ''),
+        preserved_state: Boolean(input.preserved_state),
+        preserved_url: String(input.preserved_url || ''),
+        local_only: input.local_only !== undefined ? Boolean(input.local_only) : true,
+        truth_status: isTruthStatus(input.truth_status) ? input.truth_status : 'partial'
+    };
+}
 export function buildRollbackHint(input = {}) {
     return {
         schema: 'yam.rollback-hint.v1',
@@ -82,6 +108,10 @@ export function buildUeyeRunReport(input = {}) {
         schema: 'yam.ueye-run-report.v1',
         reference_sources: references,
         implementation_sources: implementations,
+        surface_context: buildUeyeSurfaceContext({
+            ...input.surface_context,
+            truth_status: isTruthStatus(input.surface_context?.truth_status) ? input.surface_context?.truth_status : derivedTruth
+        }),
         comparison_result: comparisonResult,
         design_quality: String(input.design_quality || 'not-checked'),
         blocked_reason: blockedReason,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yam-flow",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Progressive proof-first agent flow: start fast, deepen deliberately, stay honest by design.",
   "type": "module",
   "author": "0kim0bos",

package/references/ueye-proof.md

@@ -26,12 +26,12 @@ Ueye is one route. It should not split into separate lite/deep skills. Use these
 ```bash
 yam ueye capture --url http://localhost:3000 --out .yam/screens/home.png
 yam ueye compare --reference ./reference.png --actual .yam/screens/home.png --json
-yam ueye report --reference ./reference.png --actual .yam/screens/home.png --design-quality needs-polish --json
+yam ueye report --reference ./reference.png --actual .yam/screens/home.png --design-quality needs-polish --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --preserved-state --json
 ```
 
 - `capture` uses a project-local capture backend when present, then reports `blocked` instead of installing dependencies or pretending a screenshot exists.
 - `compare` is local-only and dependency-free. It records hashes, dimensions, comparison result, and visual provenance. Different screenshots stay `partial`; exact file matches can be `verified`.
-- `report` records the Ueye run as reference sources, implementation sources, comparison result, design quality, blocked reason, next action, and truth status.
+- `report` records the Ueye run as reference sources, implementation sources, comparison result, surface context, design quality, blocked reason, next action, and truth status.
 - `report` may include continuity fields when a previous review or screenshot is being rechecked.
 - Without capture or user-provided screenshots, report implementation/source review separately from visual verification and cap the visual claim.
 
@@ -93,6 +93,11 @@ Record these fields when a reference or screenshot materially affects the claim:
 - `source_hash`
 - `reference_id`
 - `screenshot_id`
+- `provider_context`
+- `provider_badge`
+- `execution_surface`
+- `app_surface`
+- `browser_surface`
 - `viewport`
 - `state`
 - `local_only`
@@ -103,6 +108,28 @@ Record these fields when a reference or screenshot materially affects the claim:
 
 Use `unknown` for missing hashes and `not-verified` for comparisons that were not actually rechecked. Do not upgrade a visual claim only because a reference was supplied.
 
+### Surface Context
+
+Purpose: preserve where and how a visual claim was observed without turning Ueye into an always-on capture gate.
+
+Record these fields when they affect the visual claim:
+
+- `provider_context`
+- `provider_badge`
+- `execution_surface`
+- `app_surface`
+- `browser_surface`
+- `control_mode`
+- `url`
+- `viewport`
+- `screenshot_id`
+- `evidence_id`
+- `preserved_state`
+- `preserved_url`
+- `truth_status`
+
+Use `not-recorded` when the field was not observed. Prefer `partial` over `verified` when surface context exists but no actual implementation screenshot was captured or supplied.
+
 ### Reference Read Proof
 
 Purpose: separate reading the reference from judging the implementation.

package/references/ueye.md

@@ -164,7 +164,23 @@ Record:
 - next visual action.
 - truth status.
 
-Use `yam ueye report --previous-report previous.json --review-session-id current-pass --similar "..." --different "..." --missing "..." --json` when you need a compact continuity record.
+Use `yam ueye report --previous-report previous.json --review-session-id current-pass --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --similar "..." --different "..." --missing "..." --json` when you need a compact continuity record.
+
+### Surface Context
+
+Use surface context when a Ueye claim depends on preserving the current app/browser state or explaining where visual evidence came from.
+
+Fields:
+
+- provider context and badge.
+- execution surface.
+- app surface.
+- browser surface.
+- control mode.
+- preserved URL/state.
+- evidence id.
+
+Keep this metadata descriptive. It should support honest visual claims, not force a heavy browser workflow for every Ueye run.
 
 ## P0-P3 Ledger
 

package/skills/ueye/SKILL.md

@@ -38,6 +38,7 @@ Do not use for:
 - Keep Ueye as one route: start fast, then opt into `yam ueye capture` and `yam ueye compare` only when a `verified` visual claim needs real screen evidence.
 - Use `yam ueye report` when reference, implementation screenshot, comparison result, design quality, and next action should be recorded as one compact run report.
 - For follow-up visual reviews, keep continuity explicit: previous report/source, current report/source, comparison delta, resolved findings, new findings, and next action.
+- Record surface context when it matters: provider context, provider badge, execution surface, app surface, browser surface, control mode, preserved URL/state, and evidence id.
 - Generated media can guide direction, but it cannot verify the implemented screen without implementation screenshot evidence.
 - Prefer the in-app browser for interactive visual checks. Do not switch to a profile-dependent browser unless the user explicitly asks or the task requires existing cookies, sessions, extensions, or profile state.
 
@@ -61,7 +62,7 @@ Do not use for:
    - Do not silently use a profile-dependent browser as a fallback. If the in-app browser cannot capture or inspect, report the visual cap as `partial` or `blocked`.
    - Use `yam ueye capture --url URL --out path.png` when a project-local capture backend is available and the claim needs real browser evidence.
    - Use `yam ueye compare --reference ref.png --actual shot.png` when reference fidelity needs a proof-ready local comparison record.
-   - Use `yam ueye report --reference ref.png --actual shot.png --design-quality needs-polish --json` to preserve the run-level visual provenance and next action.
+   - Use `yam ueye report --reference ref.png --actual shot.png --design-quality needs-polish --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --json` to preserve the run-level visual provenance, surface context, and next action.
    - When continuing a prior review, include previous/current report or screenshot identifiers and mark the comparison as improved, regressed, unchanged, or not-verified.
 9. Compare reference and implementation when reference fidelity was requested:
    - matched, similar, different, not-applicable, or not-verified.
@@ -91,18 +92,21 @@ Use these artifacts for reference-led implementation or serious visual review. K
 2. Visual Provenance:
    - source kind, path, hash, reference id, screenshot id, redaction/locality flags, operator-provided flag, comparison result, and truth status.
    - use this to prove the route from reference reading to implementation recheck.
-3. Reference Read Proof:
+3. Surface Context:
+   - provider context, provider badge, execution surface, app surface, browser surface, control mode, preserved URL/state, evidence id, and truth status.
+   - use this to explain where and how visual evidence was observed without forcing capture for every Ueye run.
+4. Reference Read Proof:
    - concrete observations from the reference before implementation.
    - no implementation claim should depend on an unrecorded reference observation.
-4. Reference vs Implementation Matrix:
+5. Reference vs Implementation Matrix:
    - compare the implemented result against the reference by aspect.
    - record matched, similar, different, not-applicable, or not-verified.
-5. Design Quality Review:
+6. Design Quality Review:
    - judge whether the result is good UI/UX/design after reference comparison.
    - use pass, needs-polish, or fails for each relevant design dimension.
-6. Review Continuity and Comparison Report, when this is a follow-up review:
+7. Review Continuity and Comparison Report, when this is a follow-up review:
    - record previous source/report, current source/report, comparison delta, resolved findings, new findings, still-open findings, truth status, and next action.
-7. Media Generation Proof, when generated images are part of the task:
+8. Media Generation Proof, when generated images are part of the task:
    - record whether generation was requested, attempted, blocked, or produced an output.
    - use `yam media proof --requested --attempted --output path.png --wait-loop --json` when a generated image materially affects the design direction.
    - never use generated media proof as a substitute for implemented screen evidence.

package/src/bin/yam.ts

@@ -16,6 +16,7 @@ import {
   buildRuntimeBackendEvidence,
   buildUeyeVisualProvenance,
   buildUeyeRunReport,
+  buildUeyeSurfaceContext,
   buildYamCompletionProof,
   detectDbSafetyText as detectTrustDbSafetyText,
   isTruthStatus
@@ -139,7 +140,7 @@ 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 ueye report [--reference ref.png] [--actual screenshot.png] [--provider-context local] [--execution-surface in-app-browser] [--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]
@@ -808,7 +809,7 @@ function toolsDoctorNextActionDetails({ pack, rows, riskNotes, frameworkChecklis
   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'));
+  if (frameworkChecklist?.uiLike) actions.push(nextActionDetail('ueye-evidence', 'info', 'UI-like project detected', 'for Ueye verified claims, record reference, actual screenshot, comparison result, and surface context', 'yam ueye report --reference ref.png --actual shot.png --provider-context local --execution-surface in-app-browser --json'));
   return uniqueNextActionDetails(actions);
 }
 
@@ -1348,7 +1349,7 @@ 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]
+  yam ueye report [--reference ref.png] [--actual screenshot.png] [--review-session-id id] [--provider-context local] [--execution-surface in-app-browser] [--app-surface codex-app] [--browser-surface in-app-browser] [--control-mode manual|automated] [--preserved-state] [--preserved-url URL] [--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.
@@ -1359,7 +1360,7 @@ Notes:
 
 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 flags = parseSimpleFlags(args, new Set(['url', 'out', 'viewport', 'wait-until', 'timeout', 'full-page', 'provider-context', 'provider-badge', 'execution-surface', 'app-surface', 'browser-surface', 'control-mode', 'preserved-state', 'preserved-url', 'evidence-id', 'screenshot-id', 'json']));
   const url = String(flags.url || '');
   const out = String(flags.out || '');
   if (!url || !out) {
@@ -1384,6 +1385,24 @@ async function ueyeCapture(args = []) {
     await page.goto(url, { waitUntil, timeout });
     await page.screenshot({ path: target, fullPage: Boolean(flags.full_page) });
     const info = await imageFileInfo(target);
+    const surfaceContext = buildUeyeSurfaceContext({
+      provider_context: String(flags.provider_context || 'local-playwright'),
+      provider_badge: String(flags.provider_badge || flags.provider_context || 'local-playwright'),
+      execution_surface: String(flags.execution_surface || 'browser-capture'),
+      app_surface: String(flags.app_surface || 'local-project'),
+      browser_surface: String(flags.browser_surface || 'playwright'),
+      control_mode: String(flags.control_mode || 'automated-capture'),
+      route: 'ueye',
+      mode: 'capture',
+      url,
+      viewport: `${viewport.width}x${viewport.height}`,
+      screenshot_id: String(flags.screenshot_id || path.basename(target)),
+      evidence_id: String(flags.evidence_id || `ueye-capture-${timestampId()}`),
+      preserved_state: Boolean(flags.preserved_state),
+      preserved_url: String(flags.preserved_url || url),
+      local_only: true,
+      truth_status: 'verified'
+    });
     const result = {
       schema: 'yam.ueye-capture.v1',
       status: 'verified',
@@ -1393,6 +1412,7 @@ async function ueyeCapture(args = []) {
       full_page: Boolean(flags.full_page),
       sha256: info.sha256,
       dimensions: info.dimensions,
+      surface_context: surfaceContext,
       visual_evidence: `browser screenshot captured: ${target} (${info.dimensions}, sha256:${info.sha256})`
     };
     printJsonOrHuman(result, Boolean(flags.json), 'Ueye capture');
@@ -1415,7 +1435,7 @@ async function ueyeCapture(args = []) {
 
 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 flags = parseSimpleFlags(args, new Set(['reference', 'ref', 'actual', 'screenshot', 'json', 'reference-id', 'screenshot-id', 'provider-context', 'provider-badge', 'execution-surface', 'app-surface', 'browser-surface', 'control-mode', 'preserved-state', 'preserved-url', 'url', 'viewport', 'evidence-id']));
   const reference = String(flags.reference || flags.ref || '');
   const actual = String(flags.actual || flags.screenshot || '');
   if (!reference || !actual) {
@@ -1436,12 +1456,35 @@ async function ueyeCompare(args = []) {
     const sameDimensions = referenceInfo.dimensions === actualInfo.dimensions;
     const comparisonResult = exactMatch ? 'matched' : 'different';
     const truthStatus = exactMatch ? 'verified' : 'partial';
+    const surfaceContext = buildUeyeSurfaceContext({
+      provider_context: String(flags.provider_context || 'local-file'),
+      provider_badge: String(flags.provider_badge || flags.provider_context || 'local-file'),
+      execution_surface: String(flags.execution_surface || 'local-file-compare'),
+      app_surface: String(flags.app_surface || 'local-project'),
+      browser_surface: String(flags.browser_surface || 'not-used'),
+      control_mode: String(flags.control_mode || 'local-compare'),
+      route: 'ueye',
+      mode: 'compare',
+      url: String(flags.url || ''),
+      viewport: String(flags.viewport || ''),
+      screenshot_id: String(flags.screenshot_id || path.basename(actualPath)),
+      evidence_id: String(flags.evidence_id || `ueye-compare-${timestampId()}`),
+      preserved_state: Boolean(flags.preserved_state),
+      preserved_url: String(flags.preserved_url || flags.url || ''),
+      local_only: true,
+      truth_status: truthStatus
+    });
     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)),
+      provider_context: surfaceContext.provider_context,
+      provider_badge: surfaceContext.provider_badge,
+      execution_surface: surfaceContext.execution_surface,
+      app_surface: surfaceContext.app_surface,
+      browser_surface: surfaceContext.browser_surface,
       local_only: true,
       redacted: false,
       operator_provided: false,
@@ -1456,6 +1499,7 @@ async function ueyeCompare(args = []) {
       same_dimensions: sameDimensions,
       reference: referenceInfo,
       actual: actualInfo,
+      surface_context: surfaceContext,
       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`
@@ -1476,7 +1520,7 @@ async function ueyeCompare(args = []) {
 
 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 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', 'provider-context', 'provider-badge', 'execution-surface', 'app-surface', 'browser-surface', 'control-mode', 'preserved-state', 'preserved-url', 'url', 'evidence-id', 'json']));
   const reference = String(flags.reference || flags.ref || '');
   const actual = String(flags.actual || flags.screenshot || '');
   const referenceSources = [];
@@ -1485,6 +1529,24 @@ async function ueyeReport(args = []) {
   let blockedReason = String(flags.blocked_reason || '');
   const reviewSessionId = String(flags.review_session_id || `ueye-${timestampId()}`);
   const previousReport = await readPreviousUeyeReport(flags.previous_report);
+  const surfaceContext = buildUeyeSurfaceContext({
+    provider_context: String(flags.provider_context || 'not-recorded'),
+    provider_badge: String(flags.provider_badge || flags.provider_context || 'not-recorded'),
+    execution_surface: String(flags.execution_surface || flags.capture_backend || 'not-recorded'),
+    app_surface: String(flags.app_surface || 'not-recorded'),
+    browser_surface: String(flags.browser_surface || flags.capture_backend || 'not-recorded'),
+    control_mode: String(flags.control_mode || 'not-recorded'),
+    route: 'ueye',
+    mode: 'report',
+    url: String(flags.url || flags.preserved_url || ''),
+    viewport: String(flags.viewport || ''),
+    screenshot_id: String(flags.current_screenshot_id || flags.screenshot_id || ''),
+    evidence_id: String(flags.evidence_id || reviewSessionId),
+    preserved_state: Boolean(flags.preserved_state),
+    preserved_url: String(flags.preserved_url || flags.url || ''),
+    local_only: true,
+    truth_status: actual ? 'partial' : 'assumed'
+  });
 
   try {
     if (reference) {
@@ -1494,6 +1556,11 @@ async function ueyeReport(args = []) {
         source_path: info.path,
         source_hash: info.sha256,
         reference_id: String(flags.reference_id || path.basename(info.path)),
+        provider_context: surfaceContext.provider_context,
+        provider_badge: surfaceContext.provider_badge,
+        execution_surface: surfaceContext.execution_surface,
+        app_surface: surfaceContext.app_surface,
+        browser_surface: surfaceContext.browser_surface,
         local_only: true,
         operator_provided: true,
         comparison_result: 'reference-recorded',
@@ -1508,6 +1575,11 @@ async function ueyeReport(args = []) {
         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)),
+        provider_context: surfaceContext.provider_context,
+        provider_badge: surfaceContext.provider_badge,
+        execution_surface: surfaceContext.execution_surface,
+        app_surface: surfaceContext.app_surface,
+        browser_surface: surfaceContext.browser_surface,
         local_only: true,
         operator_provided: false,
         comparison_result: 'implementation-recorded',
@@ -1526,6 +1598,11 @@ async function ueyeReport(args = []) {
   const report = buildUeyeRunReport({
     reference_sources: referenceSources,
     implementation_sources: implementationSources,
+    surface_context: {
+      ...surfaceContext,
+      screenshot_id: surfaceContext.screenshot_id || String(flags.current_screenshot_id || flags.screenshot_id || implementationSources[0]?.screenshot_id || ''),
+      truth_status: blockedReason ? 'blocked' : implementationSources.length ? 'partial' : 'assumed'
+    },
     comparison_result: comparisonResult,
     design_quality: String(flags.design_quality || 'not-checked'),
     blocked_reason: blockedReason,
@@ -1536,6 +1613,7 @@ async function ueyeReport(args = []) {
     previousReport,
     referenceSources,
     implementationSources,
+    surfaceContext: report.surface_context,
     comparisonResult,
     designQuality: String(flags.design_quality || 'not-checked'),
     similar: arrayFlag(flags.similar),
@@ -1593,6 +1671,7 @@ function buildUeyeComparisonReport({
   previousReport,
   referenceSources,
   implementationSources,
+  surfaceContext,
   comparisonResult,
   designQuality,
   similar,
@@ -1633,6 +1712,7 @@ function buildUeyeComparisonReport({
       reference_count: referenceSources.length,
       implementation_count: implementationSources.length
     },
+    surface_context: surfaceContext || buildUeyeSurfaceContext(),
     comparison_result: comparisonResult,
     design_quality: designQuality,
     similar,

package/src/lib/trust-kernel.ts

@@ -56,6 +56,11 @@ export interface UeyeVisualProvenance {
   source_hash: string;
   reference_id: string;
   screenshot_id: string;
+  provider_context: string;
+  provider_badge: string;
+  execution_surface: string;
+  app_surface: string;
+  browser_surface: string;
   local_only: boolean;
   redacted: boolean;
   operator_provided: boolean;
@@ -63,6 +68,26 @@ export interface UeyeVisualProvenance {
   truth_status: TruthStatus;
 }
 
+export interface UeyeSurfaceContext {
+  schema: 'yam.ueye-surface-context.v1';
+  provider_context: string;
+  provider_badge: string;
+  execution_surface: string;
+  app_surface: string;
+  browser_surface: string;
+  control_mode: string;
+  route: string;
+  mode: string;
+  url: string;
+  viewport: string;
+  screenshot_id: string;
+  evidence_id: string;
+  preserved_state: boolean;
+  preserved_url: string;
+  local_only: boolean;
+  truth_status: TruthStatus;
+}
+
 export interface RollbackHint {
   schema: 'yam.rollback-hint.v1';
   touched_files: string[];
@@ -96,6 +121,7 @@ export interface UeyeRunReport {
   schema: 'yam.ueye-run-report.v1';
   reference_sources: UeyeVisualProvenance[];
   implementation_sources: UeyeVisualProvenance[];
+  surface_context: UeyeSurfaceContext;
   comparison_result: string;
   design_quality: string;
   blocked_reason: string;
@@ -201,6 +227,11 @@ export function buildUeyeVisualProvenance(input: Partial<UeyeVisualProvenance> =
     source_hash: String(input.source_hash || 'unknown'),
     reference_id: String(input.reference_id || ''),
     screenshot_id: String(input.screenshot_id || ''),
+    provider_context: String(input.provider_context || 'not-recorded'),
+    provider_badge: String(input.provider_badge || 'not-recorded'),
+    execution_surface: String(input.execution_surface || 'not-recorded'),
+    app_surface: String(input.app_surface || 'not-recorded'),
+    browser_surface: String(input.browser_surface || 'not-recorded'),
     local_only: Boolean(input.local_only),
     redacted: Boolean(input.redacted),
     operator_provided: Boolean(input.operator_provided),
@@ -209,6 +240,28 @@ export function buildUeyeVisualProvenance(input: Partial<UeyeVisualProvenance> =
   };
 }
 
+export function buildUeyeSurfaceContext(input: Partial<UeyeSurfaceContext> = {}): UeyeSurfaceContext {
+  return {
+    schema: 'yam.ueye-surface-context.v1',
+    provider_context: String(input.provider_context || 'not-recorded'),
+    provider_badge: String(input.provider_badge || input.provider_context || 'not-recorded'),
+    execution_surface: String(input.execution_surface || 'not-recorded'),
+    app_surface: String(input.app_surface || 'not-recorded'),
+    browser_surface: String(input.browser_surface || 'not-recorded'),
+    control_mode: String(input.control_mode || 'not-recorded'),
+    route: String(input.route || 'ueye'),
+    mode: String(input.mode || 'report'),
+    url: String(input.url || ''),
+    viewport: String(input.viewport || ''),
+    screenshot_id: String(input.screenshot_id || ''),
+    evidence_id: String(input.evidence_id || ''),
+    preserved_state: Boolean(input.preserved_state),
+    preserved_url: String(input.preserved_url || ''),
+    local_only: input.local_only !== undefined ? Boolean(input.local_only) : true,
+    truth_status: isTruthStatus(input.truth_status) ? input.truth_status : 'partial'
+  };
+}
+
 export function buildRollbackHint(input: Partial<RollbackHint> = {}): RollbackHint {
   return {
     schema: 'yam.rollback-hint.v1',
@@ -268,6 +321,10 @@ export function buildUeyeRunReport(input: Partial<UeyeRunReport> = {}): UeyeRunR
     schema: 'yam.ueye-run-report.v1',
     reference_sources: references,
     implementation_sources: implementations,
+    surface_context: buildUeyeSurfaceContext({
+      ...input.surface_context,
+      truth_status: isTruthStatus(input.surface_context?.truth_status) ? input.surface_context?.truth_status : derivedTruth
+    }),
     comparison_result: comparisonResult,
     design_quality: String(input.design_quality || 'not-checked'),
     blocked_reason: blockedReason,

package/templates/ueye-comparison.md

@@ -31,6 +31,24 @@
 | comparison_result | matched / similar / different / not-verified / not-applicable |
 | truth_status | verified / partial / skipped / blocked / assumed |
 
+## Surface Context
+
+| Field | Value |
+| --- | --- |
+| provider_context | not-recorded |
+| provider_badge | not-recorded |
+| execution_surface | not-recorded |
+| app_surface | not-recorded |
+| browser_surface | not-recorded |
+| control_mode | not-recorded |
+| url |  |
+| viewport |  |
+| screenshot_id |  |
+| evidence_id |  |
+| preserved_state | true / false |
+| preserved_url |  |
+| truth_status | verified / partial / skipped / blocked / assumed |
+
 ## Reference Read Proof
 
 - Layout:
@@ -123,6 +141,17 @@ Use `pass`, `needs-polish`, or `fails` for each relevant design dimension before
   "previous_screenshot_id": "",
   "current_report_id": "",
   "current_screenshot_id": "",
+  "surface_context": {
+    "provider_context": "not-recorded",
+    "provider_badge": "not-recorded",
+    "execution_surface": "not-recorded",
+    "app_surface": "not-recorded",
+    "browser_surface": "not-recorded",
+    "control_mode": "not-recorded",
+    "preserved_state": false,
+    "preserved_url": "",
+    "truth_status": "partial"
+  },
   "viewport": "",
   "state": "",
   "comparison_result": "not-verified",

package/templates/ueye-review.md

@@ -42,6 +42,24 @@
 | comparison_result | matched / similar / different / not-verified / not-applicable |
 | truth_status | verified / partial / skipped / blocked / assumed |
 
+## Surface Context
+
+| Field | Value |
+| --- | --- |
+| provider_context | not-recorded |
+| provider_badge | not-recorded |
+| execution_surface | not-recorded |
+| app_surface | not-recorded |
+| browser_surface | not-recorded |
+| control_mode | not-recorded |
+| url |  |
+| viewport |  |
+| screenshot_id |  |
+| evidence_id |  |
+| preserved_state | true / false |
+| preserved_url |  |
+| truth_status | verified / partial / skipped / blocked / assumed |
+
 ## Reference Read Proof
 
 - Layout:
@@ -155,6 +173,17 @@ Result values: pass / needs-polish / fails.
   "previous_screenshot_id": "",
   "current_report_id": "",
   "current_screenshot_id": "",
+  "surface_context": {
+    "provider_context": "not-recorded",
+    "provider_badge": "not-recorded",
+    "execution_surface": "not-recorded",
+    "app_surface": "not-recorded",
+    "browser_surface": "not-recorded",
+    "control_mode": "not-recorded",
+    "preserved_state": false,
+    "preserved_url": "",
+    "truth_status": "partial"
+  },
   "viewport": "",
   "state": "",
   "comparison_result": "not-verified",

package/yam.manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "yam",
-  "version": "0.1.0",
+  "version": "0.1.5",
   "principles": [
     "Direction before execution.",
     "Start fast.",
@@ -22,7 +22,7 @@
     {
       "id": "ueye",
       "stage": "v0.3",
-      "purpose": "Tight UI/UX/design implementation and visual review with visual provenance, reference-read proof, visual comparison, design quality review, and P0-P3 issue tracking."
+      "purpose": "Tight UI/UX/design implementation and visual review with visual provenance, surface context, reference-read proof, visual comparison, design quality review, and P0-P3 issue tracking."
     },
     {
       "id": "question",