# 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.

## Foundry pf2e v8 layout note

In Foundry pf2e v8 (the pinned tag `pf2e-8.0.3`), class JSONs live under
`packs/pf2e/classes/`. Earlier major versions (v7) used `packs/classes/` directly. The
seed script reads from the v8 path; if you bump the pinned tag back to a v7 release,
update `FOUNDRY_CLASSES_DIR` in `server/prisma/seed-class-progression.ts` accordingly.

## Failure modes

- **"Foundry pf2e clone not found at server/prisma/data/foundry-pf2e/packs/pf2e/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.