docs(01-03): add SEED-README with Foundry pf2e clone instructions and pinned tag

- Pin Foundry pf2e tag to pf2e-8.0.3 (current stable, includes Player Core + APG content for all 16 D-16 classes)
- Document clone command, run command, and failure modes
- Reference Plan 03 (Wizard worked example) vs Plan 03b (bulk curation) split
This commit is contained in:
2026-04-27 14:42:58 +02:00
parent f703b2ed3f
commit 65676657fc

View File

@@ -0,0 +1,59 @@
# Phase 1 — ClassProgression Seed README
The seed script `server/prisma/seed-class-progression.ts` populates the `ClassProgression`
and `ClassFeatureOption` tables from the Foundry pf2e system repository (license: Apache 2.0
+ OGL 1.0a + Paizo Community Use Policy — verified 2026-04-27).
## One-time dev setup
Clone the pinned Foundry pf2e tag into the gitignored data folder:
```bash
cd server/prisma/data
git clone --depth 1 --branch pf2e-8.0.3 https://github.com/foundryvtt/pf2e.git foundry-pf2e
```
`server/prisma/data/foundry-pf2e/` is excluded from version control (.gitignore line added in Plan 01).
Do NOT commit the clone. Re-clone after a Foundry pf2e major version ships.
**Pinned tag:** `pf2e-8.0.3` (Pathfinder 2e system release on the `foundryvtt/pf2e` repo;
selected from `https://github.com/foundryvtt/pf2e/tags` — current stable Pathfinder 2e
release as of 2026-04-27, includes Player Core / APG content for all 16 D-16 classes).
> **Tag drift note (RESEARCH §Pitfall 5):** The Foundry pf2e JSON shape may change across
> major versions. If the seed script fails with "Class JSON does not match expected schema",
> either pin to an older tag here or update the parser in `seed-class-progression.ts`.
> Do **not** auto-track HEAD.
## Run the seed
```bash
cd server
npm run db:seed:class-progression
```
Idempotent: running twice does not duplicate rows. Console output reports `created` and
`updated` counts plus any errors.
## Failure modes
- **"Foundry pf2e clone not found at server/prisma/data/foundry-pf2e/packs/classes/"** —
run the `git clone` step above.
- **"Class JSON does not match expected schema"** — Foundry pf2e changed the JSON shape
between major versions. Update the seed parser or pin to an older tag.
## What gets seeded (cumulative across Plan 03 and Plan 03b)
- **ClassProgression** rows: 16 classes × 20 levels = 320 rows, with `grants[]`,
`proficiencyChanges`, `spellSlotIncrement`, `cantripIncrement`, `repertoireIncrement`,
`choiceType`, `choiceOptionsRef`. Plan 03 ships Wizard L1..L20 fully (worked example);
Plan 03b adds remaining 15 classes' L1..L20 rows (data-only — Plan 03's pipeline already
seeds 320 rows; Plan 03b just enriches them with overlay data).
- **ClassFeatureOption** rows: hand-curated Cleric Doctrines, Wizard Schools, Champion
Causes, Sorcerer Bloodlines (where L1-set), Druid Orders, etc. Joint goal across both
plans: ≥50 rows. Plan 03 ships at least 1 (Wizard School worked example); Plan 03b
ships ≥49 more.
- Spell-slot/cantrip/repertoire progressions come from the hand-curated overlay
`server/prisma/data/spell-slot-overlays.ts` because Foundry encodes them in prose
(Pitfall #6). Plan 03 ships Wizard's full L1..L19 entries; Plan 03b ships the other
6 caster classes plus empty arrays for non-casters.