From 65676657fc8958dd49e9126f4e648227897a889f Mon Sep 17 00:00:00 2001
From: Alexander Zielonka <zielonka@zeasy.software>
Date: Mon, 27 Apr 2026 14:42:58 +0200
Subject: [PATCH] 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
---
 .../SEED-README.md                            | 59 +++++++++++++++++++
 1 file changed, 59 insertions(+)
 create mode 100644 .planning/phases/01-level-up-pf2e-regelkonform/SEED-README.md

diff --git a/.planning/phases/01-level-up-pf2e-regelkonform/SEED-README.md b/.planning/phases/01-level-up-pf2e-regelkonform/SEED-README.md
new file mode 100644
index 0000000..24ed405
--- /dev/null
+++ b/.planning/phases/01-level-up-pf2e-regelkonform/SEED-README.md
@@ -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.