Merge pull request #51 from Daren9m/codex/issue-28-visual-pipeline

Add complete bestiary visual description pipeline

Author: Daren9m

docs/bestiary-image-pipeline.md

@@ -0,0 +1,31 @@
+# Bestiary image pipeline
+
+The bestiary image workflow is deliberately split into description, review, and image stages. An image prompt cannot be compiled until its monster visual record is approved.
+
+## Source and attribution
+
+The monster index includes material from the *System Reference Document 5.2.1* by Wizards of the Coast LLC, [available from D&D Beyond](https://www.dndbeyond.com/srd) and licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/legalcode). The visual sidecar preserves that attribution and the pinned source commit in `src/data/monster-visuals.json`. Generated descriptions and images must remain original expressions; do not copy third-party prose or artwork.
+
+## Files
+
+- `src/data/monster-visuals.json` is the editable sidecar keyed by `monsterId`. It contains source facts, description fields, review/image status, prompt version, and a hash of visual-relevant monster inputs.
+- `src/data/monster-visual-batches.json` assigns every monster exactly once to the pilot or one of 11 production batches.
+- `src/lib/monster-visuals.ts` defines the schema, art bible, validation, hashing, batching, and prompt compiler.
+- `scripts/enrich-bestiary-visuals.ts` synchronizes records after a bestiary import without replacing authored descriptions.
+
+## Workflow
+
+1. Run `npm run import:bestiary` when the pinned SRD source changes.
+2. Run `npm run visuals:sync`. New monsters receive pending records populated only with structured source facts.
+3. Author the physical description fields for a batch. Record distinguishing anatomy, silhouette, surface materials, palette, pose, environment, required elements, forbidden elements, and accessible alt text. Stage the 14-monster pilot with `npm run visuals:seed-pilot` and the remaining 317 descriptions with `npm run visuals:seed-production`. Both commands preserve matching reviewed records and refuse to replace any description that has subsequently been edited.
+4. Review against the licensed source and set `reviewStatus` to `approved`. Set `imageStatus` to `ready` only when the description is ready for generation.
+5. Compile the prompt through `compileMonsterImagePrompt`, generate candidate images, and track review through `draft` and `approved`.
+6. Run `npm run visuals:audit`, `npm run visuals:check`, `npm test`, and `npm run typecheck` before merging.
+
+If a monster's visual-relevant inputs or the prompt version changes, synchronization preserves its authored text but marks approved work `needs-revision`. Duplicate or orphaned records stop synchronization rather than being silently discarded.
+
+Run `npm run visuals:export-review` to create a batch-by-batch Markdown review packet under `docs/visual-review`. Those files are generated views; make corrections in the sidecar or authored seed source and export again.
+
+## Batch contract
+
+The pilot contains one representative of each creature type in a fixed order. After removing those 14 monsters, the remaining 317 are sorted by challenge rating, then name, then ID. Production batches 1–9 contain 29 monsters each; batches 10–11 contain 28 each. The manifest contains no timestamps, so repeated generation is byte-stable.

docs/visual-review/README.md

@@ -0,0 +1,20 @@
+# Monster visual review
+
+These files are generated from `src/data/monster-visuals.json`. Edit the sidecar or authored seed source, not these review files.
+
+Source: *System Reference Document 5.2.1* by Wizards of the Coast LLC, CC-BY-4.0.
+
+| Batch | Monsters | Pending | Approved | Needs revision |
+| --- | ---: | ---: | ---: | ---: |
+| [14-type style pilot](./pilot.md) | 14 | 14 | 0 | 0 |
+| [Production batch 1](./production-01.md) | 29 | 29 | 0 | 0 |
+| [Production batch 2](./production-02.md) | 29 | 29 | 0 | 0 |
+| [Production batch 3](./production-03.md) | 29 | 29 | 0 | 0 |
+| [Production batch 4](./production-04.md) | 29 | 29 | 0 | 0 |
+| [Production batch 5](./production-05.md) | 29 | 29 | 0 | 0 |
+| [Production batch 6](./production-06.md) | 29 | 29 | 0 | 0 |
+| [Production batch 7](./production-07.md) | 29 | 29 | 0 | 0 |
+| [Production batch 8](./production-08.md) | 29 | 29 | 0 | 0 |
+| [Production batch 9](./production-09.md) | 29 | 29 | 0 | 0 |
+| [Production batch 10](./production-10.md) | 28 | 28 | 0 | 0 |
+| [Production batch 11](./production-11.md) | 28 | 28 | 0 | 0 |