Finished up most documentation

spikes/card-harness/README.md

@@ -66,6 +66,12 @@ Camera framing eases with the lift/exit so the deeper separation does not
 unexpectedly enlarge the card. The edge mesh draws only extrusion side walls, not end caps beneath the
 dedicated artwork faces, preventing depth-fighting bands at farther zoom distances.
 Pack assets are loaded separately on first entry, with retry on failure.
+Before enabling pack interaction, textures are uploaded and shaders are compiled
+for the pouch, hidden card fronts, universal backs, and both neutral/revealed edge
+materials using the scene's lighting and environment. This preparation does not
+draw or reveal cards. The loading state lasts until it finishes; failures release
+the new pack resources and keep retry available. Returning to an already prepared
+pack retains its state without repeating this preparation.
 
 Wrapper deformation is coalesced to once per rendered frame, including touch dents
 and tear input. Fixed crease/crimp calculations are cached; unchanged pouch surfaces
@@ -73,6 +79,9 @@ and ribbons do not recalculate normals/bounds or upload vertex buffers. Hidden
 wrappers do not deform. Pack UI updates are also coalesced and only write changed
 values. These optimizations retain the same mesh resolution, deformation formulas,
 materials, lighting, pixel ratio, and antialiasing.
+Mint cards (`condition = 1`) bypass procedural wear calculations whose contribution
+is zero. Worn cards use the original wear equations, and all finish/substrate
+shading remains unchanged.
 
 There is no sound, haptics, particles, cloth simulation, backend, rewards persistence,
 pack progress persistence, or timeline/editor. This is a choreography proof, not an
@@ -86,12 +95,26 @@ Finish and substrate are separate:
 - Finish controls printed ink, foil, or holographic coating.
 - Substrate controls surface roughness/microtexture, underprint response, and edge/core appearance.
 
-Paper uses fine, irregular fibers and a broad, weak highlight. Linen uses raised
-interlaced threads with small shaded recesses. Plastic has a smooth clear-coat
-highlight even in Printed ink mode. Wood uses warped longitudinal grain with
-surface relief and a restrained warm tint. Metal retains its reflective
-underprint and adds a shallow luminance-driven etch, with darker artwork
-recessed slightly more than lighter artwork. Procedural detail fades below
+Paper uses fine, irregular fibers and a broad, weak highlight. Linen uses raised-looking
+interlaced threads with analytic slope lighting, a bounded two-sample procedural
+parallax offset, and broad ridge highlights that remain visible in Printed ink
+at oblique angles. Only the weave shifts with the view: artwork and lettering stay
+anchored. Surface detail scales the effect; unresolved threads fade to avoid
+shimmer. This is shader relief with no added geometry or change to the card's
+silhouette, back, or thickness. This linen look was visually approved September 10,
+2026 as `linen-relief-v1-2026-09-10`; its exact defaults are recorded in
+[`CURRENT-DEFAULTS.md`](CURRENT-DEFAULTS.md#linen). No extra toggle or configuration
+is required: selecting Linen applies it in Inspect, Lab, and the authored pack.
+Plastic has a smooth clear-coat
+highlight even in Printed ink mode. Wood uses raised longitudinal grain with
+bounded procedural parallax, stronger relief, and a restrained warm tint.
+The artwork stays anchored while grain shading and tint shift together.
+Metal retains its reflective underprint and uses luminance-driven recesses:
+bounded parallax shifts the artwork and finish mask together, with directional
+groove shading to emphasize depth. The effect fades at the card edges.
+Metal and wood depth were visually approved September 10, 2026 as
+`metal-wood-relief-v1-2026-09-10`. Surface detail scales the relief; neither
+material adds geometry or changes the card silhouette. Procedural detail fades below
 pixel resolution to limit shimmer.
 The universal card back uses fixed neutral material properties so front finish
 and substrate choices do not spoil a pack reveal.
@@ -107,6 +130,11 @@ slightly raised champagne-metal polishing over the etched steel base.
 - `blender_prototype/card_finish_material.py`
 - `blender_prototype/render_premium_review.py`
 
+The approved linen, metal, and wood depth follow-ups change runtime shader behavior,
+not the source artwork, generated normal map, or Blender reference renders. The
+asset manifest therefore retains its v4 reference revision; the scoped material
+approvals and parameters are tracked in `CURRENT-DEFAULTS.md`.
+
 The runtime shader and geometry are runtime implementations, not a claim of pixel-identical Blender output.
 Live review removed only David's face, hand, and lamb ellipse cutouts. Color-based coverage and title-panel protection remain. Holographic color and angle response are preserved; reduced sheen applies only to foil.
 
@@ -131,8 +159,32 @@ npm test
 
 These check exact pre-optimization wrapper geometry snapshots, surface update
 counts, per-frame input batching, pause/resume, pinch handoff, restart, reduced
-motion, and ordered reveals. They are CPU/state checks, not a real-device GPU or
-touch-latency benchmark; mobile performance still needs on-device validation.
+motion, ordered reveals, GPU preparation, and failure cleanup. They are CPU/state
+checks, not a real-device GPU or touch-latency benchmark; mobile performance still
+needs on-device validation.
+
+WebGL pixel parity and pack shader-preparation checks require a local headless
+Chromium browser with WebGL2 support, installed project dependencies, and generated
+reference assets (`npm run assets`):
+
+```sh
+SHADER_BROWSER=/absolute/path/to/chromium \
+SHADER_BROWSER_KIND=chromium \
+node scripts/shader-pixel-regression.mjs
+```
+
+The Chromium runner uses SwiftShader software WebGL. Browsers are not installed
+automatically; a missing browser, missing WebGL support, timeout, pixel mismatch,
+or unexpected shader program causes a nonzero exit rather than a skipped check.
+
+The pixel check compares 360 combinations of substrate, finish, condition, angle,
+and lighting against the current shader with unconditional wear evaluation,
+verifying that the mint fast path remains equivalent. A separately hash-verified
+v4 reference checks that Paper and Plastic remain unchanged and that the approved
+Linen, Metal, and Wood iterations produce a visual difference. The pack check exercises opening,
+all three reveals, and restart under point, directional, and spot lighting,
+checking for new shader programs after preparation. Software WebGL can validate
+pixel parity and program reuse, but its timings are not mobile GPU benchmarks.
 
 The asset-generation script uses cross-platform Node APIs and works on Windows and Linux. The retained `export:blender` script is an optional reference utility and is not part of the application pipeline.