# Card work and approval

Card production lives in `in-progress/cards/`. Pipeline, font, material, branding, and harness experiments live in `spikes/`. Explicitly approved card revisions live in `artifacts/cards/`; shared tier layers remain in `artifacts/layers/` and fonts remain in `fonts/`.

## Working layout

```text
in-progress/cards/BE-002-the-fall/
  card.json                         # Stable ID, title, selected revision and stage
  README.md
  history/legacy/                   # Migrated historical packages, not new work
  revisions/v01/
    card.json                       # This revision's actual content/build inputs
    manifest.json                   # Stage, approval, input/export hashes
    build.py                        # Revision-specific assembly entry point
    source/                         # Native art, prompts, fit and text authoring data
    review/                         # Review images, validation and assessments
    low/manifest.json               # 500 × 700
    med/manifest.json               # 1000 × 1400
    high/manifest.json              # 2000 × 2800
    high/normal/
      card.png
      finish-mask.png
      text-mask.png
      card.svg                      # Optional editable master
    high/boundless/
    high/borderless/
    high/textless/
```

Every resolution has the same four printing directories. Normal and Borderless include applicable glyph masks; Textless and Boundless need no glyph protection, though an explicit zero map may be retained. Source/build records describe the whole revision and belong outside resolution folders. Resolution manifests contain exact dimensions and hashes for their own exports.

Use the exact master-catalogue ID for `cardId` (for example **BE-002**). Keep the catalogue display title in `title` and a readable **ID-title** directory name in `folderName` (for example **BE-002-the-fall**). Build/application references select by `cardId` and revision through the progress index; they do not reconstruct the directory from the title. Folder names are generated when a card is first scaffolded and stay stable across later title edits unless an explicit rename updates the profile/index. Number new revisions explicitly (`v01`, `v02`, …); do not infer selection or approval from file timestamps. A card's root `card.json` selects its revision. [The progress index](../in-progress/index.json) resolves selected revisions in either location.

## Accepted layout

```text
artifacts/cards/BE-002-the-fall/
  card.json                         # Content/build inputs and acceptance metadata
  manifest.json                     # Exact accepted revision, e.g. v01, and hashes
  build.py
  source/
  review/
  low/                              # 500 × 700, with its resolution manifest
    normal/
    boundless/
    borderless/
    textless/
  med/                              # 1000 × 1400, same printing directories
  high/                             # 2000 × 2800, same printing directories
```

The accepted directory holds one current approved card. Its manifest retains the revision number; there is no revision folder under `artifacts/cards/`. Working revisions retain their `revisions/v01/` structure. When a newer revision is approved, the previous accepted package moves to `in-progress/cards/[ID-title]/history/accepted-[revision]/` before the new package takes its place. Linked inputs remain pinned to the version they used.

## New work

From `sanctification/`:

```sh
python3 tools/card-production/card_workspace.py new \
  --card BE-002 --title 'The Fall' --rarity Extraordinary --revision v02
python3 tools/card-production/card_workspace.py status
```

The scaffold starts at **art-review** with empty printing folders. During illustration prototyping, retain native art, prompt and recorded fit under `source/`, with review images under `review/`; do not generate final printing exports or masks. Once the artwork is explicitly approved, assemble using the pinned shared layers/fonts and the pipeline's finish contract, set the revision and card profile to **assembly-review**, then refresh and validate its manifests:

```sh
python3 tools/card-production/card_workspace.py refresh --card BE-002 --revision v02
python3 tools/card-production/card_workspace.py validate --card BE-002 --revision v02
```

`refresh` records current working inputs/exports; it does not generate card art or printings. `validate` checks recorded hashes, dimensions, opaque faces, grayscale maps, linked SVG inputs and pinned shared assets. Imported proofs retain their original validation records; migration is not a new rendering or GPU validation.

The four imported `v01` revisions have wrapper builds that call the retained tier comparison builder and refresh their manifests. The comparison's `cards.json` now references canonical card IDs/revisions rather than duplicating their content records. New cards should have their own subject-specific builders and no dependency on the four-card comparison.

## Final card approval

Artwork approval and final card approval are separate. Only after the user explicitly approves an exact complete card revision should a production session run:

```sh
python3 tools/card-production/card_workspace.py approve \
  --card BE-002 --revision v02 --approval-note 'Exact user approval wording'
```

The tool validates the assembled revision, moves the entire revision to `artifacts/cards/BE-002-the-fall/`, records the approval, updates the index and compatibility links, and adjusts linked SVG/input paths for the new directory depth. It does not install harness fixtures. Approved revisions are frozen; revisions to them begin in a new working revision. Previous accepted packages remain in working history when replaced; the helper preserves their linked inputs and updates the current selection.

## Existing work migration

The September 14, 2026 migration moved 24 historical packages into per-card `history/legacy/` and organized the existing four-tier comparison exports as `v01`. None of these cards was promoted or given final approval. Original spike paths are compatibility symlinks so earlier documentation, recorded hashes, source references and historical builders continue to resolve. Historical packages and reports keep their original internal layout and paths; new production follows the standardized layout above. Archived font/harness compatibility links belong only to history, not new card authoring.

The follow-up [catalogue identity migration](../in-progress/catalogue-id-migration-2026-09-14.json) assigns the four user-supplied master IDs and renames their card folders. Old title-only card paths remain compatibility links. Revision `title` is catalogue metadata; existing `name` values remain the previously typeset display titles. Imported comparison records use `exportPrefix` solely for legacy fixture filenames, never as the catalogue identity.

[Migration record](../in-progress/migration-2026-09-14.json) records preserved historical hashes, canonical export hashes and editable SVG path adjustments. Images were moved without regeneration, resampling or grading. The tier comparison remains a pipeline experiment in `spikes/`, referencing the standardized cards.

The later accepted-layout migration flattens the accepted BE-002 and BE-010 packages, retaining their `v01` manifest identities and every PNG byte. [Layout validation](../artifacts/cards/layout-migration-2026-09-14.json) records the preserved hashes. Legacy files and compatibility links subsequently deleted by the user are not restored.