7.4 KiB
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
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 resolves selected revisions in either location.
Accepted layout
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/:
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:
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:
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 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 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 records the preserved hashes. Legacy files and compatibility links subsequently deleted by the user are not restored.