yam-flow 0.1.1 → 0.1.3

package/COMMANDS.md

@@ -39,6 +39,16 @@ $ueye
 yam template ueye-comparison
 ```
 
+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 --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
+```
+
 ## Review-Only
 
 ```text
@@ -136,6 +146,10 @@ yam proof /path/to/project
 yam proof --route deep --truth verified --command "npm run build: pass"
 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 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 proof --route deep --truth proven --require-runtime --runtime "mock server fixture"
 yam proof write /path/to/project --route deep --truth partial --command "npm run build: pass"

package/README.md

@@ -127,6 +127,10 @@ yam proof /path/to/project
 yam proof write /path/to/project --route quick --truth verified --command "npm run verify:self: pass"
 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 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
 yam safety "supabase db reset"
@@ -172,6 +176,33 @@ Publishing still requires confirming the final npm package name and account acce
 - fake versus real distinction
 - runtime truth matrix
 - visual evidence caps
+- Ueye visual run reports
+- runtime backend evidence
+- media generation proof caps
 - DB/Supabase safety signals
 
 It is implemented locally in `src/lib/trust-kernel.ts` and kept route-scoped. It is not an always-on release gate.
+
+## Ueye Capture And Compare
+
+`$ueye` stays one skill. It starts fast by default, then uses capture/compare only when a visual claim needs real evidence.
+
+```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
+```
+
+`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, design quality judgment, 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:
+
+```bash
+yam media proof --requested --attempted --output ./generated.png --wait-loop --json
+```
+
+For agent-driven visual QA, prefer the Codex in-app Browser plugin. Use the user's Chrome browser only when explicitly requested or when Chrome-only session/profile state is required.