106 lines
8.5 KiB
Markdown
106 lines
8.5 KiB
Markdown
# 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 local assembly 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.
|
||
|
||
Git retention is intentionally smaller while a revision is under `in-progress/`: source inputs, text records, review material and each resolution manifest are retained, but generated `med/` and `high/` files and low-resolution masks/editable masters are ignored. The four `low/[printing]/card.png` files are the tracked printing references. A local build still writes and validates all resolutions. When approved, the complete local package moves outside the scoped ignore rules into `artifacts/cards/`, where every production export is retained.
|
||
|
||
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/`. When a newer revision is approved, the replacement remains self-contained and the previous acceptance becomes a compact record at `in-progress/cards/[ID-title]/history/accepted-[revision]/`. Superseded working revisions similarly move to `history/revisions/[revision]/`.
|
||
|
||
Compact history keeps the original full manifest as `full-manifest.json`, content/build and textual source/review records, and one 500 × 700 `card.png` for each available printing. Art-only iterations keep one 500 × 700 art reference. Medium/high exports, masks, source rasters and extra review images are deleted after acceptance. A `record.json` explains the disposition; compact records are historical references, not buildable canonical revisions.
|
||
|
||
## 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, internalizes any live input borrowed from older work, 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 then compacts superseded working and accepted revisions using the retention rule above. It does not install harness fixtures. Approved revisions are frozen; revisions to them begin in a new working revision.
|
||
|
||
To apply the same cleanup once to a card accepted before this policy:
|
||
|
||
```sh
|
||
python3 tools/card-production/card_workspace.py compact --card BE-002
|
||
```
|
||
|
||
## 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.
|