Sanctification/docs/card-art-handoff.md

# Card Art Handoff — 2026-09-11

## Agreed Direction

- Stained glass is primary; tapestry/linen and illuminated-manuscript influences support it. Sacred, stylized, restrained, and readable.
- Full-card illustration, outer frame, text backing, and typeset text are separate authoring components. Common through Extraordinary share one frame system per tier; Legendary artwork variants may have bespoke art/layouts. Rarity, printing, artwork variant, substrate, and finish remain distinct.
- Common people appear in the middle distance doing an ordinary action. Use broad panes, restrained colors, simple geometry, and no gold. The original Timothy was too premium; the new proof is the preferred direction.
- Legendary should have exceptional presence: epic scale or contemplative beauty. More ornament or symbols are not mandatory. Rarity never implies spiritual worth.
- One quiet subject-type label belongs on text-bearing printings. Period, tradition, and History grouping belong in app metadata. Text must fit and remain readable; deeper content/sources belong in inspection.
- Trinity/Foundation artwork, wear/condition, and imperfections are deferred. Obsolete face/hand/lamb cutout guidance was removed; do not reintroduce it.

| Printing | Components |
|---|---|
| Normal | Art + frame + backing + text |
| Textless | Art + frame; no lettering |
| Borderless | Art + backing + text |
| Boundless | Art only |

## Implemented Timothy Proof

Folder: [spikes/timothy-layer-proof](../spikes/timothy-layer-proof/). The user said the result “looks amazing and proves the concept really well.” Small tweaks remain welcome.

- [Source illustration](../spikes/timothy-layer-proof/source/timothy-art.png): generated through the built-in image tool. Timothy reads a scroll beside a modest doorway with another person; blue/green/cream, broad stained-glass treatment. Native 1060 × 1484, uniformly enlarged to 2000 × 2800 without cropping.
- [card.json](../spikes/timothy-layer-proof/card.json): Timothy / Common / Person / “Faithful disciple”; full KJV 2 Timothy 4:7, including terminal colon. These are Paul's words to Timothy, not a quote spoken by Timothy. Source link and context are included.
- [layout.json](../spikes/timothy-layer-proof/layout.json): 5:7 canvas, 60 px frame, 12 px frame/backing overlap, fixed text/focal boxes. Noto Serif and Noto Sans typography.
- [build.mjs](../spikes/timothy-layer-proof/build.mjs): Inkscape exports vector/text layers; ImageMagick assembles cards and sizes; Node creates masks and checks. Both applications are installed. No GIMP/MCP was needed.
- [Review sheet](../spikes/timothy-layer-proof/output/review/printings.png), [editable SVG](../spikes/timothy-layer-proof/output/timothy-editable.svg), and [validation report](../spikes/timothy-layer-proof/output/validation.json). Runtime cards live in `output/cards/`; matching masks in `output/masks/`.

Rebuild from `/home/dkzver/docker`:

```sh
node sanctification/spikes/timothy-layer-proof/build.mjs
```

The script overwrites its generated outputs. Edit source inputs/build logic for reproducible tweaks; save manual SVG edits separately. It still hardcodes Timothy filenames, panel divider coordinates, and a one-line title. It is a proof, not a general card generator or two-line text layout engine.

## Corner Fix — Preserve This

The user saw pale corner specks in the harness. The original export had antialiased circular PNG corners, while the harness uses quadratic rounded geometry and an opaque front material. Lighter artwork mixed into the frame boundary could show through sampling.

Runtime exports now use fully opaque rectangles. `frame-runtime` and `normal-runtime-overlay` extend solid frame color into all outer corners; the 3D geometry determines the silhouette. Simply disabling alpha on the old rounded export was insufficient because pale RGB remained at its curved edge. Borderless/Boundless extend the illustration instead. Finish masks are rectangular data maps, with zero coverage beneath active frame/backing.

The rebuilt Normal/Textless corner samples are solid `#304747` with mask value zero. All four runtime masters passed opacity checks; text bounds, 99,200 overlay-join pixels, and repeated Normal composition passed. The user offered to perform visual validation; **post-fix harness confirmation has not yet been received**. The current review sheet uses rectangular runtime images; rounded authoring layers still exist, but separate rounded preview-card exports were not implemented.

## Masks, Docs, and Remaining Work

Timothy coverage starts with saturation `smoothstep(0.08,0.58)` × value `smoothstep(0.015,0.16)`, suppressed under active frame/backing. Frame and text panels are printed ink in this proof. Removed text panels must not leave obsolete protected regions in Textless/Boundless. Exact approved shader/material behavior remains in [CURRENT-DEFAULTS.md](../spikes/card-harness/CURRENT-DEFAULTS.md).

[Art Direction](./art-direction.md) was updated for the layered system, printing definitions, Common restraint, Legendary presence, concise typography/category, and deferrals. [Functional Spec](./functional-spec-v2.md) received matching deferred wording; its heading says v4. Harness README/defaults had obsolete cutout wording removed and experimental wear labeled deferred.

[Card Layer Pipeline](./card-layer-pipeline.md) is still a broader proposal: its opening and GIMP-first tooling text are stale, and not all proposed checks are implemented. Use this handoff and the actual build for current behavior. Font hashes are recorded, not enforced against a lockfile. The simple seam fixture does not constitute a comprehensive defect suite. Earlier interrupted attempts to add a proof README/prompt file did not land; the new [session prompt](./card-generation-session-prompt.md) captures the workflow for future generations.

Preserve the existing dirty worktree, including pre-existing deleted root `card-back.png`, `common.png`, and `legendary.png`. The proof has not replaced harness reference fixtures. For review, load a rebuilt card and its matching mask through Lab's local image inputs. Avoid changing shader defaults to compensate for an asset defect.

Environment note: tools repeatedly failed with `bwrap: loopback: Failed RTM_NEWADDR`. Approved shell escalation worked; the patch helper sometimes still failed when updating existing files. This is an environment issue, not a project dependency problem.