chore: initialize homebrew-magic-rpg monorepo

Consolidates the HbM: RPG project (formerly the loose hbm-books working folder) into a single repo. ObsidianNotes, foundry-lore, and foundry-system are wired in as submodules pointing at their existing Gitea repos. Loose tooling scripts are organized under tools/, obsolete/one-off scripts (fix_vault.py, generate_mocs.py, debug-*.ts, write_file_helper.py) and _books/ (superseded by ObsidianNotes) are excluded via .gitignore rather than deleted. foundryvtt-admin is excluded pending its own separate repo.
2026-08-17 21:28:50 +02:00
commit a4f8941fca
25 changed files with 3702 additions and 0 deletions
@@ -0,0 +1,677 @@
+# FoundryVTT Spell Reference - HbM RPG v3
+
+> **Status**: Draft / Planning Document
+> **Audience**: Developer (next iteration of `hbm-rpg-v3` Foundry system)
+> **Purpose**: Single source of truth for all spells across all books + gap analysis for `SpellData` model and casting logic.
+
+---
+
+## Table of Contents
+
+1. [Schools & Disciplines Inventory](#1-schools--disciplines-inventory)
+2. [Witch Magic Symbols Inventory](#2-witch-magic-symbols-inventory)
+3. [Sacred Magic Deities Inventory](#3-sacred-magic-deities-inventory)
+4. [Unified Spell Catalog](#4-unified-spell-catalog)
+5. [SpellData Model - Gap Analysis](#5-spelldata-model--gap-analysis)
+6. [Casting Logic - Gap Analysis](#6-casting-logic--gap-analysis)
+7. [Constants Module - Required Additions](#7-constants-module--required-additions)
+8. [Character Sheet Spell Tab - Enhancement Spec](#8-character-sheet-spell-tab--enhancement-spec)
+9. [Spell Item Sheet - Enhancement Spec](#9-spell-item-sheet--enhancement-spec)
+10. [Compendium Pack Plan](#10-compendium-pack-plan)
+11. [Implementation Phases](#11-implementation-phases)
+
+---
+
+## 1. Schools & Disciplines Inventory
+
+### 1.1 Academic disciplines (Eastern European School of Magic)
+
+| Discipline ID (en) | Polish name | Color | Notes |
+|---|---|---|---|
+| `transmutation` | Alchemia Transmutacji | Brązowy + fioletowy | Subset of legacy Taumaturgia |
+| `brewing` | Warzenie Eliksirów | Brązowy + zielony | Subset of legacy Taumaturgia |
+| `botany` | Botanika | Zielony | - |
+| `elementsAir` | Magia Żywiołów - Powietrze | Żółty | - |
+| `elementsWater` | Magia Żywiołów - Woda | Niebieski | - |
+| `elementsFire` | Magia Żywiołów - Ogień | Pomarańczowy | - |
+| `elementsEarth` | Magia Żywiołów - Ziemia | Jasnozielony | - |
+| `artifacts` | Rzemiosło Artefaktów | Fioletowy | Subset of legacy Taumaturgia |
+| `golemancy` | Golemancja | - | Subset of legacy Taumaturgia, no spells in books |
+| `runes` | Magia Runiczna | - | Subset of legacy Taumaturgia, no spells in books |
+| `sources` | Źródła Mocy | Tęcza | - |
+| `illusion` | Magia Iluzji | Bladoniebieski | - |
+| `sacred` | Magia Sakralna | Biały (egzorcyści: czarny) | Sub-divided by deity |
+| `witch` | Wiedźmia Magia | - | Symbol-based casting |
+| `necromancy` | Nekromancja | (kanon) | - |
+
+### 1.2 Forbidden / extra-academic disciplines
+
+| Discipline ID (en) | Polish name | Source book |
+|---|---|---|
+| `blood` | Magia Krwi | *Arcanum Sanguinis* |
+| `crimson` | Magia Szkarłatu | *Chwała Szkarłatnemu Kultowi* |
+| `abyssAspects` | Magia Otchłani - Magia Aspektów | *Klątwa Otchłani* |
+| `abyssPrimal` | Magia Otchłani - Pierwotna Magia | *Klątwa Otchłani* |
+| `wildWitch` | Dzika Wiedźmia Magia | *Klątwa Otchłani* / *Księga Magii* |
+
+---
+
+## 2. Witch Magic Symbols Inventory
+
+> **Note**: List is **extensible** - more symbols may be added in future content. Stored as `string[]` in `constants.ts`, used for autocomplete only; spell data accepts arbitrary strings.
+
+| Symbol | Domain meaning |
+|---|---|
+| `Potentia` | Power / damage |
+| `Tutamen` | Protection / shield |
+| `Lux` | Light |
+| `Motus` | Movement |
+| `Iter` | Travel / path |
+| `Vacuos` | Void / displacement |
+| `Vitium` | Decay / corruption |
+| `Praecantatio` | Magic itself |
+| `Aer` | Air |
+| `Aqua` | Water |
+| `Gelum` | Cold / ice |
+| `Ignis` | Fire |
+| `Terra` | Earth |
+| `Cognitio` | Knowledge / mind |
+| `Alienis` | Alien / foreign |
+| `Illusio` | Illusion |
+| `Somnium` | Dream |
+| `Tenebrae` | Shadow / darkness |
+| `Auram` | Aura |
+| `Vinculum` | Binding |
+| `Telum` | Weapon / projectile |
+| `Sensus` | Sense / perception |
+| `Perditio` | Destruction |
+| `Perfodio` | Piercing / digging |
+| `Sano` | Healing |
+| `Volatus` | Flight |
+| `Tempestas` | Storm |
+
+---
+
+## 3. Sacred Magic Deities Inventory
+
+| Deity ID | Polish label | Notes |
+|---|---|---|
+| `common` | Modlitwy Powszechne | Available to all sacred casters |
+| `jahwe` | Bóg-Jahwe-Jedyny | Some spells race-gated (Anioł, Człowiek) |
+| `zeus` | Zeus-Jowisz | Storm domain |
+| `demeter` | Demeter-Ceres | Agriculture / nature |
+| `artemis` | Artemida-Diana | Hunt / beasts |
+| `hekate` | Hekate | **Hybrid sacred/witch** - symbols + zeal |
+| `aphrodite` | Afrodyta-Wenus | Charm / persuasion |
+| `eros` | Amor-Eros | Bonds / desire |
+
+> **Hekate is special**: her spells have witch-magic symbols and complexity, allowing them to be cast either as sacred (zeal) or witch (mana + symbols) prayers.
+
+---
+
+## 4. Unified Spell Catalog
+
+> Format per spell:
+> - **Name** (Polish), `id` (slug for compendium)
+> - `school` / `discipline` / `deity` / `castingMode`
+> - `circle` (T:Y) → `difficulty.threshold:difficulty.successes`
+> - `manaCost` / `bloodCost` (where applicable)
+> - `castingTime` / `range` / `areaOfEffect` / `targets` / `duration`
+> - `components` (verbal / somatic / material / symbols)
+> - `requirements` (race / talent / discipline mastery)
+> - `flags` (`isSuperspell`, `nonCombatOnly`, `requiresGroupCast`)
+> - `damageBase` (formula reference)
+> - `statusEffects[]` (conditions applied)
+> - `overcastOptions[]`
+> - `sourceBook`
+
+### 4.1 Magia Ogólna (Księga Magii)
+
+| # | id | Name | T:Y | Mana | Range | Duration | Symbols | Damage | Status | Notes |
+|---|---|---|---|---|---|---|---|---|---|---|
+| 1 | `magic-missile` | Magiczny Pocisk | 4:1 | 1 | 15 m | inst. | `Potentia` | `½ magicalAbilities` | - | Overcast: +1 dmg |
+| 2 | `magic-shield` | Magiczna Tarcza | 5:1 | 2 | 5 m | 2 r | `Tutamen` | - | - | HP = ½ MA + 1; OC: +1d2 HP / +1 r |
+| 3 | `gleam` | Poblask | 3:1 | 1 | self | 1 h | `Lux` | - | - | Item glows; OC: +1 h |
+| 4 | `telekinesis` | Telekineza | 4:1 | 1 | 20 m | 10 r | `Motus` | - | - | ≤1 kg; OC: +10 r / +1 kg |
+| 5 | `blink` | Przeskok | 5:2 | 3 | 20 m | inst. | `Iter, Praecantatio` | - | - | No AoO; OC: +5 m |
+| 6 | `teleport` | Teleportacja | 6:3 | 5 | known location | inst. (cast 10 min) | `Iter, Praecantatio, Vacuos` | - | - | OC: +1 person (3 mana) |
+| 7 | `ether-pierce` | Przebicie Eteru | 5:3 | 4 | 10 m | inst. | `Tutamen, Vitium` | `½ MA, ignores armor` | - | 2 dmg = 1 Rune Shield; OC: +1d2 dmg |
+| 8 | `energy-wave` | Fala Energii | 5:2 | 4 | 10 m | inst. | `Praecantatio, Potentia` | `½ MA AoE` | Oszołomiony (Reflex save) | Rect 3×8 m; OC: +1d3 dmg / +2 Y |
+| 9 | `truth-glimpse` | Przebłysk Prawdy | 4:1 | 1 | touch | 1 r | `Cognitio` | - | - | +1 die lie/behavior; OC: +1 r / +1 die |
+| 10 | `quick-thought` | Szybka Myśl | 5:1 | 1 | self | 1 r | `Cognitio` | - | - | +1 init, +1 die; OC stacking |
+
+### 4.2 Magia Żywiołów - Powietrze
+
+| # | id | Name | T:Y | Mana | Range | Duration | Symbols | Damage | Status |
+|---|---|---|---|---|---|---|---|---|---|
+| 11 | `flight` | Latanie | 5:2 | 3 | self | 10 r | `Volatus` | - | - |
+| 12 | `air-wave` | Powietrzna Fala | 5:1 | 3 | 10 m | inst. | `Aer, Potentia` | `½ MA AoE` | Powalony (Strength save) |
+| 13 | `danger-sense` | Wyczucie Zagrożenia | 6:1 | 4 | self | 2 r | `Aer, Sensus` | - | - |
+| 14 | `accuracy` | Celność | 6:1 | 2 | self | 2 r | `Sensus, Telum` | - | - |
+| 15 | `wind-swift` | Szybki jak Wiatr | 5:1 | 1 | self | 1 r | `Motus` | - | Immune Powalony |
+
+### 4.3 Magia Żywiołów - Woda
+
+| # | id | Name | T:Y | Mana | Range | Duration | Symbols | Damage | Status |
+|---|---|---|---|---|---|---|---|---|---|
+| 16 | `water-create` | Tworzenie i Kontrolowanie Wody | 5:1 | 1 | 5 m | 10 min | `Aqua` | - | - |
+| 17 | `ice-floor` | Lodowa Podłoga | 6:1 | 3 | 10 m | 2 r | `Gelum, Vinculum` | - | Powalony (Athletics save) |
+| 18 | `solace` | Ukojenie | 5:1 | 2 | self | 1 r | `Sano` | `heal ½ MA` | - |
+| 19 | `hailstorm` | Gradobicie | 5:4 | 5 | 10 m | 2 r | `Gelum, Praecantatio, Tempestas` | `MA dmg` | Trudny Teren; Reflex save |
+| 20 | `mystic-fog` | Mistyczna Mgła | 5:3 | 4 | self | 1 r | `Aqua, Tenebrae` | - | Oślepiony (enemies) |
+
+### 4.4 Magia Żywiołów - Ogień
+
+| # | id | Name | T:Y | Mana | Range | Duration | Symbols | Damage | Status |
+|---|---|---|---|---|---|---|---|---|---|
+| 21 | `ignition` | Podpalenie | 5:2 | 3 | 15 m | 1 r | `Ignis, Vinculum` | `3 + 3/turn` | Podpalony |
+| 22 | `kindle` | Wzniecanie Ognia | 3:1 | 1 | touch | inst. | `Ignis` | - | - |
+| 23 | `fire-cloak` | Ognista Powłoka | 5:2 | 4 | self | 3 r | `Ignis, Telum` | weapon +2 magical | - |
+| 24 | `fireball` | Kula Ognia | 6:1 | 2 | 15 m | inst. | `Ignis, Potentia` | `MA` | Podpalony 3 r (Reflex save) |
+| 25 | `burning-skin` | Gorejąca Skóra | 4:3 | 5 | self | 1 r | `Ignis, Tutamen` | `½ MA reactive` | - |
+
+### 4.5 Magia Żywiołów - Ziemia
+
+| # | id | Name | T:Y | Mana | Range | Duration | Symbols | Damage | Status |
+|---|---|---|---|---|---|---|---|---|---|
+| 26 | `stone-shield` | Skalista Tarcza | 5:1 | 2 | 5 m | 1 r | `Terra` | wall HP = MA | blocks LoS |
+| 27 | `quicksand` | Ruchome Piaski | 5:3 | 3 | 10 m | 2 r | `Terra, Perfodio, Vinculum` | - | half movement |
+| 28 | `earthquake` | Trzęsienie Ziemi | 4:6 | 5 | 10 m | 3 r | `Terra, Potentia, Perditio` | - | Unieruchomiony+Powalony, Nieprzytomny on 3 fails |
+| 29 | `gravel-armor` | Żwirowa Zbroja | 4:1 | 2 | self | 2 r | `Tutamen, Terra` | - | +1 armor, –½ speed |
+| 30 | `stone-trap` | Skalista Pułapka | 5:4 | 4 | 15 m | 1 min | `Terra, Vinculum, Telum` | `MA` (trigger) | - |
+
+### 4.6 Magia Sakralna - Modlitwy Powszechne
+
+| # | id | Name | T:Y | Mana | Range | Duration | Damage | Notes |
+|---|---|---|---|---|---|---|---|---|
+| 31 | `sanctify` | Uświęcenie | 4:1 | 2 | self | 1 r | weapon → magical | - |
+| 32 | `holy-steel` | Święta Stal | 5:1 | 3 | self | 1 r | weapon +1 magical | –1 die Reflex on hit |
+| 33 | `healing-touch` | Leczący Dotyk | 3:1 | 1 | touch | inst. | `heal MA or Devotion` | - |
+| 34 | `protection-prayer` | Modlitwa o Opiekę | 5:1 | 1 | self | 1 r | - | +1 die vs spells/curses |
+| 35 | `divine-justice` | Boska Sprawiedliwość | 6:1 | 2 | 10 m | inst. | `½ MA/Dev (+1d6 vs heretic)` | - |
+
+### 4.7 Magia Sakralna - Bóg-Jahwe-Jedyny
+
+| # | id | Name | T:Y | Mana | Race req | Damage | Notes |
+|---|---|---|---|---|---|---|---|
+| 36 | `david-blade` | Ostrze Dawida | 5:1 | 3 | **Anioł** | weapon S+1 magical slash | - |
+| 37 | `last-judgement` | Sąd Ostateczny | 6:3 | 6 | - | `3× MA/Dev` | Instant death heretic/demon/undead if Devotion ≥ Soul |
+| 38 | `solomon-wisdom` | Mądrość Salomona | 5:1 | 2 | - | - | +1 die all Mind tests, 1 h |
+| 39 | `fanatic-sacrifice` | Fanatyczne Poświęcenie | 6:2 | 5 | **Człowiek** | reciprocal ×2 | Przerażenie aura |
+| 40 | `cure-disease` | Uzdrowienie Chorych | 5:2 | 4 | - | - | Removes 1 disease/poison |
+
+### 4.8 Magia Sakralna - Zeus-Jowisz
+
+| # | id | Name | T:Y | Mana | Damage | Status |
+|---|---|---|---|---|---|---|
+| 41 | `thunderbolt` | Grom z Nieba | 5:4 | 4 | `2× MA/Dev AoE` | Ogłuszony |
+| 42 | `chain-lightning` | Błyskawice Łańcuchowe | 5:3 | 3 | `MA/Dev per chain` | - |
+| 43 | `aegis` | Egida | 6:1 | 2 | - | +1 armor, attacks –1 step |
+| 44 | `static-discharge` | Wyładowanie Elektrostatyczne | 4:4 | 4 | `½ MA/Dev` | Przewrócony |
+| 45 | `king-presence` | Obecność Króla Bogów | 6:3 | 6 | - | Authority aura |
+
+### 4.9 Magia Sakralna - Demeter-Ceres
+
+| # | id | Name | T:Y | Mana | Notes | nonCombatOnly |
+|---|---|---|---|---|---|---|
+| 46 | `harvest-blessing` | Błogosławieństwo Zasiewów | 6:2 | 3 | +20% yields | ✓ |
+| 47 | `earth-power` | Moc Ziemi | 5:2 | 4 | regen on natural soil | - |
+| 48 | `accelerated-harvest` | Przyspieszone Żniwa | 6:4 | 5 | rzucanie 1 h | ✓ |
+| 49 | `season-cycle` | Cykl Pór Roku | 6:6 | 6 | microclimate | - |
+| 50 | `mother-wrath` | Gniew Matki Ziemi | 4:4 | 4 | `½ MA/Dev` per move | - |
+
+### 4.10 Magia Sakralna - Artemida-Diana
+
+| # | id | Name | T:Y | Mana | Damage | Notes |
+|---|---|---|---|---|---|---|
+| 51 | `bridge` | Pomost | 6:1 | 4 | - | partial beast morph |
+| 52 | `awakening` | Przebudzenie | 5:3 | 5 | - | full beast morph |
+| 53 | `insect-swarm` | Chmara Insektów | 4:5 | 4 | - | –1 armor, –50% speed |
+| 54 | `divine-aim` | Boska Celność | 4:3 | 2 | - | +3 dice ranged |
+| 55 | `divine-spear` | Boska Włócznia | 5:2 | 3 | `MA/Dev ignore armor` | +1d3/extra success |
+
+### 4.11 Magia Sakralna - Hekate (hybrid sacred/witch)
+
+> **Special**: cast as either sacred (zeal cost) or witch (mana + symbols).
+
+| # | id | Name | T:Y | Mana | Symbols | Notes |
+|---|---|---|---|---|---|---|
+| 56 | `magic-amplify` | Wzmocnienie Magii | 4:3 | 4 | `Praecantatio, Auram` | +4 dice Magical Abilities |
+| 57 | `mana-theft` | Kradzież Many | 6:3 | 5 | `Praecantatio, Telum, Auram` | +2 mana / +1 max cost |
+| 58 | `magic-acceleration` | Magiczne Przyspieszenie | 5:2 | 3 | `Praecantatio, Potentia` | +1 Zapał |
+| 59 | `hekate-curse` | Klątwa Hekate | 6:2 | 6 | `Praecantatio, Vitium, Vinculum` | –1 die MA + Przerażony |
+| 60 | `arcane-knowledge` | Tajemne Poznanie | 5:1 | 2 | `Cognitio` | +1 die magic/theology lore |
+
+### 4.12 Magia Sakralna - Afrodyta-Wenus
+
+| # | id | Name | T:Y | Mana | Notes | nonCombatOnly |
+|---|---|---|---|---|---|---|
+| 61 | `innocence-charm` | Urok Niewinności | 5:1 | 2 | +2 Y to attack | - |
+| 62 | `heart-bond` | Więź Serc | 6:3 | 4 | empathic link | ✓ |
+| 63 | `passion-flame` | Płomień Namiętności | 6:1 | 5 | +2 die empathy/persuasion | - |
+| 64 | `goddess-beauty` | Piękno Bogini | 5:5 | 6 | +3 die persuasion | - |
+| 65 | `harmony-ray` | Promień Harmonii | 5:4 | 5 | suppress conflict | - |
+
+### 4.13 Magia Sakralna - Amor-Eros
+
+| # | id | Name | T:Y | Mana | Status | nonCombatOnly |
+|---|---|---|---|---|---|---|
+| 66 | `cupid-arrow` | Strzała Kupidyna | 4:3 | 3 | Zauroczony | - |
+| 67 | `heart-longing` | Tęsknota Serca | 5:1 | 2 | obsession | ✓ |
+| 68 | `senses-desire` | Pożądanie Zmysłów | 3:5 | 5 | +5 die romantic | - |
+| 69 | `destiny-thread` | Nić Przeznaczenia | (none) | 6 | bond (Soul save) | ✓ |
+| 70 | `desire-arrow` | Strzała Pożądania | 5:2 | 4 | Zauroczony if dmg > Soul | - |
+
+### 4.14 Magia Alchemii Transmutacji
+
+| # | id | Name | T:Y | Mana | Notes |
+|---|---|---|---|---|---|
+| 71 | `fools-gold` | Złoto Głupców | 6:2 | 3 | item appears as gold |
+| 72 | `detect-changes` | Wykrycie Zmian | `5:S` | 1 | GM-set difficulty; **no overcast** |
+| 73 | `magic-resistance` | Magiczna Odporność | 5:1 | 2 | immunity to chosen status |
+| 74 | `lead-transmute` | Przemiana w Ołów | 5:2 | 3 | –2 dice melee/ranged AoE |
+| 75 | `magnetism` | Magnetyzm | 5:1 | 5 | metal items expelled |
+
+### 4.15 Magia Iluzji
+
+| # | id | Name | T:Y | Mana | Symbols | Notes |
+|---|---|---|---|---|---|---|
+| 76 | `invisibility` | Niewidzialność | 5:2 | 5 | `Aer, Tenebrae` | - |
+| 77 | `mirror-image` | Zwierciadlany Wizerunek | 5:1 | 3 | `Sensus, Vitium, Illusio` | duplicate ≤20 m |
+| 78 | `mind-maze` | Labirynt Umysłu | 4:2 | 2 | `Cognitio, Alienis` | concentration check or lose action |
+| 79 | `magic-shackles` | Magiczne Kajdany | 4:2 | 3 | `Vinculum, Cognitio` | Unieruchomiony + no casting |
+| 80 | `dream-veil` | Woal Snów | 6:3 | 4 | `Somnium, Illusio, Cognitio` | `½ MA ignore armor` + Przerażony |
+
+### 4.16 Nekromancja
+
+| # | id | Name | T:Y | Mana | Notes |
+|---|---|---|---|---|---|
+| 81 | `ethereal-guide` | Eteryczny Przewodnik | 6:1 | 2 | summons mindless ghost |
+| 82 | `negation` | Negacja | 5:3 | 5 | anti-magic fog AoE |
+| 83 | `animate-skeleton` | Ożywienie Szkieletu | 6:2 | 3 | mindless skeleton |
+| 84 | `dispersal` | Rozsypanie | 5:1 | 4 | `2× MA`, destroy weak undead |
+| 85 | `speak-with-dead` | Rozmawianie ze Zmarłymi | 5:1 | 3 | 1 question / soul |
+
+### 4.17 Superzaklęcia (Księga Magii VI)
+
+> **All flagged**: `isSuperspell: true`, requires Mistrzostwo talent.
+
+| # | id | Name | T:Y | Mana | Mastery | Cast time | Group? | Notes |
+|---|---|---|---|---|---|---|---|---|
+| 86 | `super-destruction` | Destrukcja | 6:20 | 20 | any | 1 h | - | 50 m blast, 5 yr taint |
+| 87 | `super-disintegration` | Prawdziwa Dezintegracja | 6:15 | 15 | any | 10 min | - | irreversible |
+| 88 | `super-doom` | Zagłada | 6:30 | 30 | any | 3 h | **≥3 mages** | co-casters die |
+| 89 | `super-magical-plague` | Magiczna Plaga | 6:25 | 25 | botany/witch/brewing/abyss | 30 min | - | 2d3 years |
+| 90 | `super-aegis` | Aegis | 6:30 | 30 | any | 1 h | - | 24 h dome |
+| 91 | `super-landscape` | Transmutacja Krajobrazu | 6:20 | 20 | transmutation/earth/botany | 30 min | - | 5 km² permanent |
+| 92 | `super-portal` | Bramy Wymiarów | 6:25 | 25 | botany/witch/brewing/abyss | 2 h | - | 2d6 years |
+| 93 | `super-reanimation` | Reanimacja | 6:15 | 15 | sacred | 3 h | - | participants age 1d6 |
+
+### 4.18 Magia Szkarłatu (Chwała Szkarłatnemu Kultowi)
+
+| # | id | Name | T:Y | Mana | Range | Damage | Notes |
+|---|---|---|---|---|---|---|---|
+| C1 | `crimson-bolt` | Szkarłatny Pocisk | 6:1 | 1 | 15 m | `MA, ignore armor` | - |
+| C2 | `crimson-flames` | Szkarłatne Płomienie | 6:1 | 4 | 10 m | shield-eater | - |
+| C3 | `crimson-justice` | Szkarłatna Sprawiedliwość | 5:3 | 5 | 10 m | `2× MA` + AoE | Ogłuszony+Oślepiony |
+| C4 | `crimson-curse` | Klątwa Szkarłatu | 5:2 | 4 | 10 m | reactive | Nieprzytomny on cast |
+| C5 | `crimson-dagger` | Szkarłatny Sztylet | 5:2 | 3 | self | weapon +2 magical | **trigger**: free spell after kill (1/round) |
+| CS | `crimson-requiem` | Requiem | 6:25 | 25 | 100 m | `3d6 ignore all` | Superspell; 7 days "crimson dreams" |
+
+### 4.19 Magia Otchłani (Klątwa Otchłani)
+
+| # | id | Name | T:Y | Mana | Range | Damage | Notes |
+|---|---|---|---|---|---|---|---|
+| A1 | `primal-orb` | Pierwotna Kula | 5:2 | 2 | 15 m | `MA + 1d6` | chaotic targeting |
+| A2 | `mysterious-stream` | Tajemniczy Strumień | 6:2 | 3 | 10 m | `MA` | +1d3 Insanity |
+| A3 | `forbidden-ward` | Zakazana Osłona | 5:3 | 4 | self | reflect | reactive, 1 use |
+| A4 | `neutralization` | Neutralizacja | 6:3 | 5 | 20 m | `Mind/turn` | blocks casting |
+| A5 | `summon-abyss` | Przywołanie Istoty z Otchłani | `6:n` | 6 | 5 m | - | **variable Y per creature**: 2/4/6/10 |
+
+### 4.20 Magia Krwi (Arcanum Sanguinis) - TBD
+
+> **Status**: Per user clarification, Magia Krwi will get its own spell list in a future content release. Reserve `castingMode: 'blood'` and `bloodCost: number` field on `SpellData`. No spells to catalog yet.
+
+---
+
+## 5. SpellData Model - Gap Analysis
+
+> Reference: [.src/foundry-system/src/data/item-spell.ts](../.src/foundry-system/src/data/item-spell.ts)
+
+### 5.1 Current schema (v0.1.2)
+
+```ts
+{
+  circle, school, discipline,
+  castingMode: 'standard' | 'sacred' | 'witch',
+  difficulty: { threshold, successes },
+  components: { verbal, somatic, material },
+  castingTime, range, targets, duration,
+  manaCost, overcasting,
+  complexityLevel, // witch only
+  description, higherCircles
+}
+```
+
+### 5.2 Missing fields → required additions
+
+| New field | Type | Default | Why |
+|---|---|---|---|
+| `deity` | `string` | `''` | Sacred spells gated by deity (8 entries; `''` = common) |
+| `castingMode` (extend) | add `'blood'` to enum | - | Magia Krwi gets its own mode |
+| `bloodCost` | `number` | `0` | Magia Krwi resource cost |
+| `components.symbols` | `string[]` | `[]` | Witch / Hekate spell symbol list (replaces only-counting `complexityLevel`) |
+| `requirements.race` | `string[]` | `[]` | e.g. `['angel']`, `['human']` |
+| `requirements.talent` | `string[]` | `[]` | e.g. `['mastery']` for superspells |
+| `requirements.discipline` | `string[]` | `[]` | e.g. `['transmutation', 'botany']` for Magiczna Plaga |
+| `isSuperspell` | `boolean` | `false` | Distinguishes superzaklęcia |
+| `requiresGroupCast` | `boolean` | `false` | True for Zagłada |
+| `minCasters` | `number` | `1` | 3 for Zagłada |
+| `nonCombatOnly` | `boolean` | `false` | Tęsknota Serca, Więź Serc, Demeter rituals, etc. |
+| `areaOfEffect` | `SchemaField` | - | `{ shape: 'point'\|'square'\|'rectangle'\|'cone'\|'sphere'\|'line', x: number, y: number, unit: 'm' }` |
+| `damageBase` | `string` | `''` | Formula reference: `'magicalAbilities'`, `'magicalAbilities/2'`, `'magicalAbilities*2'`, `'1d6+magicalAbilities'`, etc. Parsed at cast time. |
+| `damageType` | `string` | `'magical'` | `'magical' \| 'physical-magical' \| 'pure'` (ignores armor) |
+| `ignoresArmor` | `boolean` | `false` | Crimson, Ether Pierce, Divine Spear |
+| `statusEffects` | `string[]` | `[]` | Conditions a spell may apply (`'stunned'`, `'prone'`, `'frightened'`, `'charmed'`, etc.) |
+| `saveAttribute` | `string` | `''` | If non-empty, target rolls `<attribute>+<saveSkill>` to resist |
+| `saveSkill` | `string` | `''` | e.g. `'reflex'`, `'determination'` |
+| `overcastOptions` | `array of {description, manaPerStep}` | `[]` | Replace free-text `overcasting` with structured list (legacy field kept for migration) |
+| `sourceBook` | `string` | `''` | `'kg-magii'` / `'crimson-cult'` / `'abyss-curse'` / `'arcanum-sanguinis'` / `'core-rules'` |
+| `castingTimeRounds` | `number` | `0` | 0 = action; >0 = rounds (used for combat enforcement of long casts) |
+| `castingTimeMinutes` | `number` | `0` | For non-combat scaling (rituals, superspells) |
+| `triggers` | `array of {event, effect}` | `[]` | Reactive effects: `{event:'killWithWeapon', effect:'freeCrimsonSpell'}`, `{event:'targetCastsSpell', effect:'forceUnconscious'}` |
+| `variableSuccesses` | `array of {label, successes}` | `[]` | For Przywołanie Istoty z Otchłani: `[{label:'Tajemny Krab', successes:2}, ...]` |
+
+### 5.3 Backward compatibility / migration
+
+- Keep legacy fields (`overcasting`, `complexityLevel`, `targets`) populated for one minor version.
+- Migration script in `src/migrations/0.2.0.ts`:
+  - Move `complexityLevel` count → ensure `components.symbols.length` matches; if symbols empty, leave count.
+  - Best-effort parse of `targets` string → `areaOfEffect` (regex: `/(\d+)\s*[×x]\s*(\d+)/`, `/promień\s+(\d+)/`).
+  - `overcasting` text → seed first entry of `overcastOptions[0].description`.
+
+---
+
+## 6. Casting Logic - Gap Analysis
+
+> Reference: [.src/foundry-system/src/logic/spell-cast.ts](../.src/foundry-system/src/logic/spell-cast.ts)
+
+### 6.1 Pre-cast validation gates (new)
+
+```
+function validateCast(actor, spell, opts) -> ValidationResult
+  - resourceCheck (mana / zeal / blood / mana+zeal for Hekate)
+  - raceCheck (spell.requirements.race)
+  - talentCheck (spell.requirements.talent - items on actor)
+  - disciplineCheck (spell.requirements.discipline - at least one match)
+  - deityCheck (sacred + non-empty deity → actor must be devoted to that deity)
+  - groupCastCheck (warn if requiresGroupCast and only 1 caster targeted)
+  - inCombatCheck for nonCombatOnly → block (warn-only override flag in opts)
+  - inCombatCheck for isSuperspell → WARN (do not block); bypass via opts.bypassSuperspellWarning
+  - witchSymbolCheck (count <= ceil(magic/2)) - already exists
+```
+
+### 6.2 New CastOptions
+
+```ts
+interface CastOptions {
+  manaSpent?: number;
+  zealSpent?: number;            // for Hekate when cast as sacred
+  bloodSpent?: number;           // for blood mode
+  hekateMode?: 'sacred' | 'witch'; // Hekate spell dispatch
+  bypassSuperspellWarning?: boolean;  // Downcasting talent, NPC quick-cast abilities
+  bypassNonCombatBlock?: boolean;     // GM override
+  groupCasters?: string[];       // actor IDs of co-casters
+  speaker?: ChatMessage.SpeakerData;
+}
+```
+
+### 6.3 New casting modes
+
+#### `castBlood(actor, spell, opts)`
+- Resource: deduct `spell.bloodCost` from `actor.system.attributes.blood.value` (new attribute on character data - or HP if blood pool not added)
+- Pool: `magic + magicalAbilities` (placeholder; final formula TBD when Blood Magic spells released)
+- No overcast for v1; revisit when content lands
+
+#### `castSacred` extension
+- If spell has `complexityLevel > 0` (Hekate), allow `opts.hekateMode === 'witch'` to dispatch to `castWitch` instead
+
+### 6.4 Damage rolling integration
+
+Currently `castSpell` only rolls the TS test - no damage application. Add:
+
+```
+function rollSpellDamage(actor, spell): Roll
+  - parse spell.damageBase formula
+  - resolve tokens: 'magicalAbilities', 'devotion', 'soul', '1d6', etc.
+  - return Roll for chat output
+```
+
+Display side-by-side in chat card: TS result | Damage formula result | Status effects to apply | Save target attribute+skill.
+
+### 6.5 Status effect auto-apply
+
+When TS test succeeds AND target has lower successes on save:
+- For each entry in `spell.statusEffects[]`, apply ActiveEffect via Foundry condition system
+- Hook into `conditions.ts` (already exists for combat status tracking)
+
+### 6.6 Trigger registration
+
+For reactive spells (Szkarłatny Sztylet, Klątwa Szkarłatu):
+- On successful cast → register a hook on actor (`flag.hbm-rpg-v3.triggers[]`)
+- Hook fires on matching combat event (`'killWithWeapon'` → free spell prompt; `'targetCastsSpell'` → opposed Determination test)
+- Triggers expire on duration end or single use
+
+### 6.7 Variable success summons
+
+For Przywołanie Istoty z Otchłani:
+- Cast UI prompts user to pick which entity (Tajemny Krab / Strażnik / Czempion / Simulacrum)
+- Required successes loaded from `spell.variableSuccesses[selected].successes`
+- Pass into TS test as `required` override
+
+### 6.8 Group cast orchestration
+
+For Zagłada:
+- Cast UI lists co-casters from `opts.groupCasters[]`
+- Each contributes their dice pool (sum)
+- On success, all participants take "death" status (per spell description)
+- Pre-cast warning chat card requires GM confirm
+
+---
+
+## 7. Constants Module - Required Additions
+
+> Reference: [.src/foundry-system/src/constants.ts](../.src/foundry-system/src/constants.ts)
+
+```ts
+export const CASTING_MODES = ['standard', 'sacred', 'witch', 'blood'] as const;
+
+export const SPELL_SCHOOLS = [
+  'general', 'elements', 'sacred', 'illusion', 'necromancy',
+  'transmutation', 'brewing', 'botany', 'artifacts', 'golemancy',
+  'runes', 'sources', 'witch',
+  'blood', 'crimson', 'abyssAspects', 'abyssPrimal', 'wildWitch',
+] as const;
+
+export const SACRED_DEITIES = [
+  'common', 'jahwe', 'zeus', 'demeter', 'artemis',
+  'hekate', 'aphrodite', 'eros',
+] as const;
+
+/**
+ * Witch magic symbols. EXTENSIBLE - new content may add more.
+ * Used for autocomplete only; spell.components.symbols accepts arbitrary strings.
+ */
+export const WITCH_SYMBOLS: readonly string[] = Object.freeze([
+  'Potentia', 'Tutamen', 'Lux', 'Motus', 'Iter', 'Vacuos', 'Vitium',
+  'Praecantatio', 'Aer', 'Aqua', 'Gelum', 'Ignis', 'Terra',
+  'Cognitio', 'Alienis', 'Illusio', 'Somnium', 'Tenebrae', 'Auram',
+  'Vinculum', 'Telum', 'Sensus', 'Perditio', 'Perfodio', 'Sano',
+  'Volatus', 'Tempestas',
+]);
+
+export const SOURCE_BOOKS = [
+  'core-rules', 'magic-book', 'arcanum-sanguinis',
+  'crimson-cult', 'abyss-curse', 'humanity-guide',
+  'bestiary', 'gold-steel-magic',
+] as const;
+
+export const AOE_SHAPES = ['point', 'square', 'rectangle', 'cone', 'sphere', 'line'] as const;
+
+export const CONDITIONS = [
+  'stunned', 'prone', 'frightened', 'charmed', 'unconscious',
+  'restrained', 'blinded', 'poisoned', 'burning',
+  'authority', 'dominated', 'concentrating',
+] as const;
+```
+
+---
+
+## 8. Character Sheet Spell Tab - Enhancement Spec
+
+> Reference: [.src/foundry-system/src/sheets/character-sheet.ts](../.src/foundry-system/src/sheets/character-sheet.ts)
+
+### 8.1 Grouping & filtering
+
+- Replace flat `spells` list with grouped structure in `_prepareContext`:
+  ```ts
+  spellsByDiscipline: Record<DisciplineId, Item[]>
+  spellsBySchool: Record<School, Item[]>
+  superspells: Item[]  // separate list pulled out
+  ```
+- Sidebar filter UI: by `school`, `castingMode`, `deity`, `circle`, search-by-name
+- Persist filter in `tabGroups['spellsFilter']`
+
+### 8.2 Per-row badges
+
+| Badge | Source field |
+|---|---|
+| Casting mode icon | `system.castingMode` (4 icons: ✦ standard, ✟ sacred, ✶ witch, ❤ blood) |
+| Source book pip | `system.sourceBook` (color-coded) |
+| Deity label | `system.deity` (only for sacred) |
+| Superspell star | `system.isSuperspell === true` |
+| Race-locked badge | `system.requirements.race.length > 0` |
+
+### 8.3 Cast button enhancements
+
+- Greyed out + tooltip when `validateCast()` fails (race/talent/discipline missing)
+- Yellow warning icon when superspell + actor in combat
+- Click → opens enhanced cast dialog with mana/zeal/blood field, hekate-mode toggle, group-caster picker, bypass-warning checkbox (GM only)
+
+### 8.4 Resource displays
+
+Add to stats tab header:
+- Mana / max-per-spell / per-round (existing)
+- **Blood pool** (new, only if any spell with `castingMode: 'blood'` is owned)
+- Zeal (existing)
+
+---
+
+## 9. Spell Item Sheet - Enhancement Spec
+
+> Reference: [.src/foundry-system/templates/item/spell.hbs](../.src/foundry-system/templates/item/spell.hbs)
+
+### 9.1 Add fieldsets (in order)
+
+1. **Identyfikacja** - name, sourceBook (select), school (select), discipline (select), deity (conditional select if school=sacred), circle
+2. **Tryb rzucania** - castingMode (select), bloodCost (if blood), components.symbols (tag picker against `WITCH_SYMBOLS`, free-text allowed)
+3. **Trudność** - threshold, successes, manaCost, castingTimeRounds, castingTimeMinutes
+4. **Zasięg & Obszar** - range, areaOfEffect (shape select + x/y inputs), targets (kept as freetext fallback)
+5. **Czas trwania** - duration, nonCombatOnly (checkbox)
+6. **Obrażenia** - damageBase (text), damageType (select), ignoresArmor (checkbox)
+7. **Efekty statusu** - statusEffects (multi-select against `CONDITIONS`), saveAttribute + saveSkill
+8. **Wymagania** - requirements.race (multi-select), .talent (multi-select), .discipline (multi-select)
+9. **Flagi** - isSuperspell, requiresGroupCast, minCasters
+10. **Nadczarowanie** - repeatable list of `overcastOptions[]` (description + manaPerStep)
+11. **Wyzwalacze (Triggery)** - repeatable list of `triggers[]` (event select + effect text)
+12. **Warianty sukcesu** - repeatable list of `variableSuccesses[]` (label + successes)
+13. **Opis & komponenty fabularne** - description (HTML), higherCircles (HTML, deprecated → migrated to overcastOptions)
+
+### 9.2 Conditional rendering (Handlebars)
+
+- Deity select: only if `system.school === 'sacred'`
+- Blood cost: only if `system.castingMode === 'blood'`
+- Witch complexity / symbols: if `castingMode === 'witch'` OR Hekate sacred spell
+- Variable successes: only if non-empty (collapsible)
+- Triggers: only if non-empty (collapsible)
+
+---
+
+## 10. Compendium Pack Plan
+
+### 10.1 System-bundled packs
+
+| Pack id | Type | Contents | Estimated count |
+|---|---|---|---|
+| `hbm-rpg-v3.spells-general` | Item | Magia Ogólna | 10 |
+| `hbm-rpg-v3.spells-elements` | Item | Żywioły × 4 | 20 |
+| `hbm-rpg-v3.spells-sacred` | Item | Sacred + 7 deities | 35 |
+| `hbm-rpg-v3.spells-academic` | Item | Transmutacja, Iluzja, Nekromancja | 15 |
+| `hbm-rpg-v3.spells-superspells` | Item | Superzaklęcia | 8 |
+| `hbm-rpg-v3.spells-crimson` | Item | Magia Szkarłatu | 6 |
+| `hbm-rpg-v3.spells-abyss` | Item | Magia Otchłani | 5 |
+| `hbm-rpg-v3.spells-blood` | Item | Magia Krwi (placeholder) | 0 (TBD) |
+| `hbm-rpg-v3.talents` | Item | All talents | TBD |
+| `hbm-rpg-v3.disciplines` | Item | All discipline definitions | ~15 |
+| `hbm-rpg-v3.classes` | Item | Class progression items | 5 |
+| `hbm-rpg-v3.races` | Item | Race definitions | 8 |
+| `hbm-rpg-v3.gear-baseline` | Item | Core weapons/armor/equipment | TBD |
+| `hbm-rpg-v3.elixirs-baseline` | Item | Aneks C eliksiry | TBD |
+| `hbm-rpg-v3.actors-bestiary` | Actor | Bestiariusz creatures | TBD |
+| `hbm-rpg-v3.actors-npcs` | Actor | Bestiariusz NPCs | TBD |
+
+### 10.2 Generation pipeline
+
+- Source: structured YAML/JSON in `.src/foundry-system/data/spells/*.yaml` (one file per discipline)
+- Build script (`scripts/build-packs.ts`) reads YAML, validates against Zod schema mirroring `SpellData`, writes LevelDB pack files into `packs/`
+- Run as part of `bun run package`
+
+---
+
+## 11. Implementation Phases
+
+### Phase A - Data model expansion (no UI changes)
+1. Extend `SpellData` schema with all fields from §5.2
+2. Add constants from §7
+3. Write migration `0.2.0` for existing world data
+4. Bump version → 0.2.0
+
+### Phase B - Compendium seeding
+1. Build YAML source files for all ~93 spells (§4) under `.src/foundry-system/data/spells/`
+2. Implement `scripts/build-packs.ts`
+3. Wire `bun run package` to generate packs
+
+### Phase C - Casting logic upgrade
+1. `validateCast()` pre-cast gates (§6.1)
+2. New `castBlood()` mode + extend `CastOptions` (§6.2-6.3)
+3. `rollSpellDamage()` + chat card overhaul (§6.4)
+4. Status effect auto-apply hook (§6.5)
+5. Trigger registration system (§6.6)
+6. Variable success / group cast UI (§6.7-6.8)
+
+### Phase D - Sheet UX
+1. Spell item sheet enhancements (§9)
+2. Character sheet spell tab grouping/filtering (§8)
+3. Cast dialog overhaul
+
+### Phase E - Quality & polish
+1. Localization keys (Polish + English) for all new fields
+2. CSS for badges, condition icons, source book pips
+3. Foundry compendium browser metadata (image, system tags)
+
+---
+
+## Appendix A - Spell Field Naming Convention
+
+- IDs: `kebab-case` matching slug-of-name (English-translated where idiomatic, Polish-derived otherwise)
+- All UI labels: localized via `lang/pl.json` & `lang/en.json` keys under `HBM.spell.*`
+- Damage formulas: lowercase camelCase tokens (`magicalAbilities`, `devotion`, `soul`, `mind`, `body`, `magic`)
+- Conditions: lowercase singular (`stunned`, `prone`, `frightened`)
+
+## Appendix B - Outstanding Questions
+
+1. **Blood Pool resource**: should `actor.system.attributes.blood` be a new dedicated pool, or does Magia Krwi simply consume HP? Pending Arcanum Sanguinis spell list.
+2. **Hekate "hybrid" persistence**: when cast as witch, should the spell consume zeal *or* mana? Currently planned: choose one per cast via `opts.hekateMode`.
+3. **Detect Changes (`detect-changes`)**: spell explicitly says "no overcast"; need a `noOvercast: boolean` flag, OR encode in `overcastOptions: []` (empty = no overcast).
+4. **Status effect saves**: which spells require an opposed Magia/Zdolności Magiczne test vs target's `saveAttribute + saveSkill`, and which auto-apply on TS success? Each spell needs explicit annotation in compendium YAML.
+5. **Dzika Wiedźmia Magia** spells: not enumerated separately in books; mostly variants of standard witch magic with chaos overlay. Defer to dedicated content drop.
@@ -0,0 +1,417 @@
+# Module / System Content Split - HbM RPG v3
+
+> **Status**: Draft / Planning Document
+> **Audience**: Developer (next iteration of `hbm-rpg-v3` Foundry system + companion lore module)
+> **Purpose**: Classify every chapter of every rulebook as **SYSTEM** (mechanics → Foundry system code/compendia), **MODULE** (lore → separate companion module), or **BOTH** (split content). Drives the package architecture for the v0.3+ release.
+
+---
+
+## Table of Contents
+
+1. [Classification Legend](#1-classification-legend)
+2. [Per-Book Classification](#2-per-book-classification)
+   1. [Podręcznik Gry](#21-podrecznik-gry)
+   2. [Księga Magii](#22-ksiega-magii)
+   3. [Arcanum Sanguinis](#23-arcanum-sanguinis)
+   4. [Chwała Szkarłatnemu Kultowi](#24-chwala-szkarlatnemu-kultowi)
+   5. [Klątwa Otchłani](#25-klatwa-otchlani)
+   6. [Przewodnik Ludzkości po Magicznym Świecie](#26-przewodnik-ludzkosci-po-magicznym-swiecie)
+   7. [Bestiariusz](#27-bestiariusz)
+   8. [Złoto Stal i Magia](#28-zloto-stal-i-magia)
+3. [Aggregate Summary](#3-aggregate-summary)
+4. [Proposed Package Architecture](#4-proposed-package-architecture)
+5. [Compendium Pack Plan (System)](#5-compendium-pack-plan-system)
+6. [Module Pack Plan (Lore)](#6-module-pack-plan-lore)
+7. [Cross-References & Dependencies](#7-cross-references--dependencies)
+8. [Migration & Build Pipeline](#8-migration--build-pipeline)
+
+---
+
+## 1. Classification Legend
+
+| Tag | Meaning | Destination |
+|---|---|---|
+| **[SYSTEM]** | Pure mechanics: rules, tables, stat blocks, character options | `hbm-rpg-v3` system package + bundled compendium packs |
+| **[MODULE]** | Pure lore/setting/fiction with no mechanical impact | `hbm-rpg-v3-lore` companion module (JournalEntry packs) |
+| **[BOTH]** | Mixed content - split per section: stats stay in system, narrative moves to module, cross-linked | Both packages, with bidirectional `@UUID` links |
+
+**Decision rule**:
+> If removing the content would require renumbering rules, breaking character creation, or invalidating compendium entries → **SYSTEM**.
+> If removing the content would only reduce flavor/setting depth → **MODULE**.
+> If both apply → **BOTH** with explicit split points.
+
+---
+
+## 2. Per-Book Classification
+
+### 2.1 Podręcznik Gry
+
+| Chapter | Class | Destination | Notes |
+|---|---|---|---|
+| Wstęp | **MODULE** | Lore module → JournalEntry "Świat HbM - Wprowadzenie" | Narrative about the Awakening |
+| I - Klasy (lata 1–5) | **SYSTEM** | Compendium: `classes` | Year-by-year unlocks |
+| II - Tworzenie Postaci (rasy, dziedziny) | **SYSTEM** | Compendia: `races`, `disciplines` | Race traits, discipline picks |
+| III - Atrybuty i Umiejętności | **SYSTEM** | Hard-coded in `actor-character.ts` + `constants.ts` | 4 attributes, 24 skills |
+| IV - Talenty | **SYSTEM** | Compendium: `talents` | All baseline talents |
+| V - Walka i Magia | **SYSTEM** | `logic/combat.ts`, `logic/spell-cast.ts` | Initiative, actions, tests |
+| VI - Odpoczywanie i Leczenie | **SYSTEM** | New `logic/rest.ts` | Short/long rest mechanics |
+| VII - Religia | **BOTH** | Stats → `disciplines/sacred`, deity entries; Lore → module | 7 deities |
+| Aneks A - Stany Postaci | **SYSTEM** | `logic/conditions.ts` (already exists) | Status effects |
+| Aneks B - Podstawowe Zaklęcia | **SYSTEM** | Compendium: `spells-general` | Superseded by Księga Magii - keep as reference variants |
+| Aneks C - Podstawowe Eliksiry | **SYSTEM** | Compendium: `elixirs-baseline` | Eliksir Zdrowia + others |
+| Aneks D - Cechy Broni | **SYSTEM** | `constants.ts` weapon traits | "Eksperymentalny" etc. |
+
+**Verdict**: ~90% SYSTEM. Only the foreword and parts of Religia (deity narratives) move to MODULE.
+
+---
+
+### 2.2 Księga Magii
+
+| Chapter | Class | Destination | Notes |
+|---|---|---|---|
+| Wstęp | **MODULE** | JournalEntry "Filozofia Magii" | Philosophical narrative |
+| I - Dziedziny Magii | **SYSTEM** | Compendium: `disciplines` | Discipline definitions |
+| II - Teoria Rzucania Zaklęć | **SYSTEM** | Hard-coded in `spell-cast.ts` + GM rules journal | Overcast, Symbolika, Variety |
+| III - Warzenie Eliksirów | **SYSTEM** | Compendium: `elixirs` + new `logic/brewing.ts` | Tolerance, brewing checks |
+| IV - Artefakty | **SYSTEM** | Compendium: `artifacts` | Stat blocks with upgrades |
+| V - Lista Zaklęć | **SYSTEM** | Compendia: `spells-*` (multiple packs by discipline) | All ~85 spells |
+| VI - Superzaklęcia | **SYSTEM** | Compendium: `spells-superspells` | 8 superspells |
+| VII - Tworzenie Zaklęć | **SYSTEM** | GM journal + future macro tooling | Creation rules + tables |
+| VIII - Dzika Magia Dzikich Wiedźm | **BOTH** | Sabaty/hierarchia → MODULE; chaos rules → SYSTEM | |
+
+**Verdict**: ~95% SYSTEM. Only the foreword and witch coven lore are MODULE.
+
+---
+
+### 2.3 Arcanum Sanguinis
+
+| Chapter | Class | Destination | Notes |
+|---|---|---|---|
+| Wstęp | **MODULE** | JournalEntry "Marginalia Magii Krwi" | Narrative about marginalization |
+| I - Magia Krwi a Otchłań | **MODULE** | JournalEntry chapter | Worldview, Inquisition relations |
+| II - Bóg Krwi / Robert Zaryn | **MODULE** | JournalEntries + Actor doc (Robert Zaryn) | NPC & deity lore |
+| III - Teoria Magii Krwi | **SYSTEM** | New `logic/blood-magic.ts` + new actor field `attributes.blood` | Blood Points, Self-Harm, Life Steal |
+| IV - Talenty | **SYSTEM** | Compendium: `talents-blood` | Szacunek do Życia → Rytualista / Pojedynkowicz trees |
+
+**Verdict**: 50/50 split - clean separation between organisational/divine lore and Blood Magic mechanics.
+
+---
+
+### 2.4 Chwała Szkarłatnemu Kultowi
+
+| Chapter | Class | Destination | Notes |
+|---|---|---|---|
+| Wstęp | **MODULE** | JournalEntry | Mysterious organisation tone |
+| I - Pogłoski | **MODULE** | JournalEntry | In-world rumors |
+| II - Struktura | **MODULE** | JournalEntry + Actor folder structure | Hierarchy: Rycerz→Pretor, Kultysta→Arcykapłan |
+| III - Lokalizacje | **MODULE** | JournalEntries with embedded Scenes | Obeliski, Domena Szkarłatu, Twierdze |
+| IV - Zaklęcia | **SYSTEM** | Compendium: `spells-crimson` | 5 + 1 superspell |
+| V - Artefakty | **BOTH** | Stats → `artifacts-crimson`; History → MODULE | Cross-link via `@UUID` |
+
+**Verdict**: 50/50.
+
+---
+
+### 2.5 Klątwa Otchłani
+
+| Chapter | Class | Destination | Notes |
+|---|---|---|---|
+| Wstęp | **MODULE** | JournalEntry | Nature of the Abyss |
+| I - Otchłań i Przebudzenie | **MODULE** | JournalEntry | History: pre-modern traces, 2023 |
+| II - Potężniejsza Magia | **SYSTEM** | `logic/abyss-magic.ts` | Aspects vs Primal mechanics |
+| III - Kara za nieudolność | **SYSTEM** | Roll table compendium: `roll-tables-abyss` | Failure penalty table |
+| IV - Talenty | **SYSTEM** | Compendium: `talents-abyss` | Swobodny Przepływ, Dar Otchłani, Metamagia |
+| V - Dary Otchłani | **SYSTEM** | Roll table d100 in `roll-tables-abyss` | Boons/banes |
+| VI - Personifikacje Otchłani | **BOTH** | Stats → `actors-abyss`; Lore → MODULE | Nil/Mundus/Tempus |
+| VII - Istoty Otchłani | **SYSTEM** | Compendium: `actors-abyss` | Mistrz Losu stat block |
+| VIII - Choroby Psychiczne | **SYSTEM** | New `conditions-mental` set in `conditions.ts` | Insanity mechanics |
+| IX - Zaklęcia | **SYSTEM** | Compendium: `spells-abyss` | 5 spells |
+| X - Artefakty | **SYSTEM** | Compendium: `artifacts-abyss` | Miotacz Entropii |
+| Aneks A - Kara Mistrza Losu | **SYSTEM** | Roll table | Penalty table |
+
+**Verdict**: 60% SYSTEM / 40% MODULE.
+
+---
+
+### 2.6 Przewodnik Ludzkości po Magicznym Świecie
+
+| Chapter | Class | Destination | Notes |
+|---|---|---|---|
+| Wstęp | **MODULE** | JournalEntry | |
+| I - Teoria Jednego Wszechświata | **MODULE** | JournalEntry | Cosmology, philosophy |
+| II - Planety i Frakcje | **MODULE** | JournalEntries + Scenes | Earth, Hiondirs, Xivell, Eldrakar, Malferian |
+| III - Życie na Sol-3 | **MODULE** | JournalEntry | Magical education, Inquisition |
+| IV - Cywilizacja Hiondirs-4 | **MODULE** | JournalEntry + Scene | |
+| V - Cywilizacja Xivell | **MODULE** | JournalEntry | Royal lineage, Crimson Cult genesis |
+| VI - Cywilizacja Eldrakar | **MODULE** | JournalEntry + Scene | |
+| VII - Cywilizacja Malferian | **MODULE** | JournalEntry | Consortium houses, rituals |
+| VIII - Federacja Sol-3 | **MODULE** | JournalEntry + Actor folder (Special Forces X, Gaja) | Syllia Orirel etc. |
+| IX - Święta Inkwizycja | **MODULE** | JournalEntry + Actor folder | Genesis, structure, ops |
+| X - Zaświaty | **MODULE** | JournalEntry | Hades, Niebo, Piekło hierarchies |
+| Aneks A–D | **MODULE** | JournalEntries (in-world documents) | Federation reports, Narcyza interview, Inquisitor notes |
+
+**Verdict**: ~98% MODULE. Race information is the only borderline - but actual race stats live in Podręcznik Gry, so this book stays purely lore.
+
+---
+
+### 2.7 Bestiariusz
+
+| Chapter | Class | Destination | Notes |
+|---|---|---|---|
+| I - Przeciwnicy | **SYSTEM** | Compendium: `actors-bestiary` | All hostile creature stat blocks |
+| II - Inne Postacie (NPC) | **BOTH** | Stats → `actors-npcs`; personality → MODULE | Cross-link via `@UUID` |
+| III - Talenty | **SYSTEM** | Compendium: `talents-special` | Wspomnienie Wspaniałego Świata, Pierwszy Patriarcha |
+
+**Verdict**: ~80% SYSTEM. NPC personality blurbs and faction histories are the MODULE pieces.
+
+---
+
+### 2.8 Złoto Stal i Magia
+
+| Chapter | Class | Destination | Notes |
+|---|---|---|---|
+| Wstęp | **MODULE** | JournalEntry | Post-Awakening economic revolution |
+| I - Geopolityka | **MODULE** | JournalEntry | USA/Chiny/Rosja/Europa post-2023 |
+| II - Ekonomia Magicznego Świata | **MODULE** | JournalEntry | Sectors, dwarf monopolies |
+| III - Handel Międzyrasowy | **MODULE** | JournalEntry + Scene (trade routes) | |
+| IV - Polityka na Ziemi | **MODULE** | JournalEntry | Dwarf lobby, Inquisition vs trade |
+| V - Bank Krasnoludzki | **MODULE** | JournalEntry + Actor (org) | |
+| VI - Waluty i Systemy Płatnicze | **BOTH** | Currency table → `roll-tables-economy`; cultural notes → MODULE | |
+| VII - Czarny Rynek i Kontrabanda | **BOTH** | Risk/negotiation rules → SYSTEM; catalog → MODULE | |
+| VIII - Krasnoludy | **BOTH** | Race traits → existing `races` compendium; culture → MODULE | |
+| IX - Mechanika Handlu dla PG | **SYSTEM** | New `logic/trade.ts` + journal | Founding company, transactions, smuggling |
+| Aneks A - Nowe Talenty | **SYSTEM** | Compendium: `talents-trade` | Zmysł Kamienia, Kupiecka Intuicja, Złoty Nos |
+| Aneks B - Przedmioty i Towary | **SYSTEM** | Compendium: `gear-trade` + price tables | Dwarven items, price lists |
+
+**Verdict**: 40% SYSTEM / 60% MODULE.
+
+---
+
+## 3. Aggregate Summary
+
+| Book | SYSTEM % | MODULE % | Primary destination |
+|---|---:|---:|---|
+| Podręcznik Gry | ~90 | ~10 | System (core) |
+| Księga Magii | ~95 | ~5 | System (core) |
+| Arcanum Sanguinis | ~50 | ~50 | Both |
+| Chwała Szkarłatnemu Kultowi | ~50 | ~50 | Both |
+| Klątwa Otchłani | ~60 | ~40 | Both |
+| Przewodnik Ludzkości | ~2 | ~98 | Module |
+| Bestiariusz | ~80 | ~20 | System |
+| Złoto Stal i Magia | ~40 | ~60 | Both |
+
+---
+
+## 4. Proposed Package Architecture
+
+```
+hbm-rpg-v3/                       (Foundry SYSTEM package)
+├── system.json
+├── src/                          (TypeScript)
+│   ├── data/                     (TypeDataModel for actors/items)
+│   ├── logic/                    (combat, spell-cast, brewing, blood-magic, abyss-magic, trade, rest, conditions)
+│   ├── sheets/                   (character, npc, item sheets)
+│   └── dice/                     (TS roll system)
+├── packs/                        (LevelDB compendia - see §5)
+└── data/                         (YAML source for pack generation)
+
+hbm-rpg-v3-lore/                  (Foundry MODULE package - separate repo / sub-folder)
+├── module.json                   (depends on hbm-rpg-v3 system)
+├── packs/                        (JournalEntry packs - see §6)
+├── data/                         (Markdown source for journal generation)
+└── assets/                       (images, maps, scene backgrounds)
+```
+
+### Why split?
+
+1. **System is mandatory**, module is optional → groups running custom settings can use the system without the canonical lore.
+2. **Update cadence differs**: rules patches (system) vs. lore expansions (module).
+3. **Distribution rights**: lore content may have separate licensing considerations.
+4. **Clean dependency graph**: module can `@UUID` link into system compendia (talents, spells, actors), but system never depends on module.
+
+---
+
+## 5. Compendium Pack Plan (System)
+
+### 5.1 Items
+
+| Pack id | Item type | Source | Est. count |
+|---|---|---|---|
+| `hbm-rpg-v3.spells-general` | spell | Księga Magii I-V | 10 |
+| `hbm-rpg-v3.spells-elements` | spell | Księga Magii V | 20 |
+| `hbm-rpg-v3.spells-sacred` | spell | Księga Magii V | 35 |
+| `hbm-rpg-v3.spells-academic` | spell | Transmutacja, Iluzja, Nekromancja | 15 |
+| `hbm-rpg-v3.spells-superspells` | spell | Księga Magii VI | 8 |
+| `hbm-rpg-v3.spells-crimson` | spell | Chwała Szkarłatnemu Kultowi | 6 |
+| `hbm-rpg-v3.spells-abyss` | spell | Klątwa Otchłani | 5 |
+| `hbm-rpg-v3.spells-blood` | spell | Arcanum Sanguinis | TBD |
+| `hbm-rpg-v3.talents-core` | talent | Podręcznik Gry IV | TBD |
+| `hbm-rpg-v3.talents-blood` | talent | Arcanum Sanguinis IV | TBD |
+| `hbm-rpg-v3.talents-abyss` | talent | Klątwa Otchłani IV | TBD |
+| `hbm-rpg-v3.talents-trade` | talent | Złoto Stal i Magia A | TBD |
+| `hbm-rpg-v3.talents-special` | talent | Bestiariusz III | TBD |
+| `hbm-rpg-v3.disciplines` | discipline | Księga Magii I | ~15 |
+| `hbm-rpg-v3.classes` | class | Podręcznik Gry I | 5 |
+| `hbm-rpg-v3.races` | race | Podręcznik Gry II + Złoto Stal i Magia VIII | 8 |
+| `hbm-rpg-v3.gear-baseline` | gear | Podręcznik Gry | TBD |
+| `hbm-rpg-v3.gear-trade` | gear | Złoto Stal i Magia B | TBD |
+| `hbm-rpg-v3.elixirs-baseline` | gear | Podręcznik Gry C | TBD |
+| `hbm-rpg-v3.elixirs` | gear | Księga Magii III | TBD |
+| `hbm-rpg-v3.artifacts` | gear | Księga Magii IV | TBD |
+| `hbm-rpg-v3.artifacts-crimson` | gear | Chwała Szkarłatnemu Kultowi V | TBD |
+| `hbm-rpg-v3.artifacts-abyss` | gear | Klątwa Otchłani X | TBD |
+
+### 5.2 Actors
+
+| Pack id | Actor type | Source | Est. count |
+|---|---|---|---|
+| `hbm-rpg-v3.actors-bestiary` | npc | Bestiariusz I | TBD |
+| `hbm-rpg-v3.actors-npcs` | npc | Bestiariusz II | TBD |
+| `hbm-rpg-v3.actors-abyss` | npc | Klątwa Otchłani VI–VII | TBD |
+
+### 5.3 Roll tables
+
+| Pack id | Source |
+|---|---|
+| `hbm-rpg-v3.roll-tables-abyss` | Klątwa Otchłani III, V, Aneks A |
+| `hbm-rpg-v3.roll-tables-economy` | Złoto Stal i Magia VI–VII |
+
+---
+
+## 6. Module Pack Plan (Lore)
+
+### 6.1 JournalEntry packs
+
+| Pack id | Source |
+|---|---|
+| `hbm-rpg-v3-lore.world-overview` | Podręcznik Gry Wstęp + Przewodnik I |
+| `hbm-rpg-v3-lore.deities` | Podręcznik Gry VII (lore parts) + Klątwa Otchłani VI |
+| `hbm-rpg-v3-lore.universe` | Przewodnik II–VII (planets & civilizations) |
+| `hbm-rpg-v3-lore.sol3-society` | Przewodnik III, VIII, IX |
+| `hbm-rpg-v3-lore.afterlife` | Przewodnik X |
+| `hbm-rpg-v3-lore.documents` | Przewodnik Aneksy A–D |
+| `hbm-rpg-v3-lore.blood-magic-history` | Arcanum Sanguinis Wstęp + I + II |
+| `hbm-rpg-v3-lore.crimson-cult` | Chwała Szkarłatnemu Kultowi Wstęp, I, II, III, V (history) |
+| `hbm-rpg-v3-lore.abyss` | Klątwa Otchłani Wstęp, I, VI (lore) |
+| `hbm-rpg-v3-lore.witch-covens` | Księga Magii VIII (lore parts) |
+| `hbm-rpg-v3-lore.economy` | Złoto Stal i Magia I–VIII (narrative parts) |
+| `hbm-rpg-v3-lore.npc-personalities` | Bestiariusz II (personality parts) |
+
+### 6.2 Scene packs (asset-bundled)
+
+| Pack id | Source |
+|---|---|
+| `hbm-rpg-v3-lore.scenes-locations` | Locations folder + Chwała III + Przewodnik IV–VII |
+
+### 6.3 Macro packs (optional)
+
+- Quick-roll macros for common GM rolls
+- Lore lookup macros (search across journal compendia)
+
+---
+
+## 7. Cross-References & Dependencies
+
+### 7.1 Dependency direction
+
+```
+hbm-rpg-v3-lore  ──depends-on──▶  hbm-rpg-v3  (system)
+                                       │
+                                       └─▶ no upward dependency
+```
+
+`module.json` declaration:
+```json
+{
+  "id": "hbm-rpg-v3-lore",
+  "title": "HbM RPG v3 - Lore Companion",
+  "system": "hbm-rpg-v3",
+  "compatibility": { "minimum": "13", "verified": "13" },
+  "relationships": {
+    "systems": [{ "id": "hbm-rpg-v3", "type": "system", "compatibility": { "minimum": "0.3.0" } }]
+  }
+}
+```
+
+### 7.2 Cross-link patterns
+
+- Lore JournalEntry references SYSTEM compendium item:
+  `@UUID[Compendium.hbm-rpg-v3.spells-crimson.{id}]{Szkarłatny Pocisk}`
+- SYSTEM item description references lore JournalEntry:
+  `@UUID[Compendium.hbm-rpg-v3-lore.crimson-cult.JournalEntry.{id}.JournalEntryPage.{pageId}]{Szkarłatny Kult}`
+- NPC actor (SYSTEM) → personality journal (MODULE) via biography `@UUID`
+
+### 7.3 Stable IDs
+
+All compendium documents must have **stable IDs** (slug-derived) to prevent cross-link breakage on rebuilds:
+- Spells: `spell-{slug}` (e.g. `spell-magic-missile`)
+- Talents: `talent-{slug}`
+- NPCs: `npc-{slug}`
+- Lore: `lore-{book}-{chapter}-{slug}`
+
+---
+
+## 8. Migration & Build Pipeline
+
+### 8.1 Source-of-truth strategy
+
+Each domain has a **machine-readable source file** under `.src/foundry-system/data/` (system) or `.src/foundry-lore/data/` (module). The Foundry pack files (`packs/*.db` or LevelDB folders) are **build artifacts**, not source.
+
+| Source format | Domain |
+|---|---|
+| YAML | spells, talents, gear, races, classes, disciplines |
+| YAML + Markdown | NPCs / actors (YAML stat block + Markdown description) |
+| Markdown | JournalEntry pages |
+| JSON | RollTables |
+
+### 8.2 Build scripts
+
+| Script | Output |
+|---|---|
+| `scripts/build-spell-packs.ts` | All `spells-*` LevelDB packs |
+| `scripts/build-actor-packs.ts` | All `actors-*` LevelDB packs |
+| `scripts/build-journal-packs.ts` | All `lore.*` packs (in module repo) |
+| `scripts/build-roll-tables.ts` | All `roll-tables-*` packs |
+| `scripts/build-all.ts` | Wraps all above; called by `bun run package` |
+
+### 8.3 Migration scripts
+
+When `SpellData` / `ActorData` schemas change, write a `src/migrations/{version}.ts` that runs on world load (Foundry `Hooks.once('ready')`).
+
+### 8.4 Validation
+
+- Zod (or Foundry's own DataModel) schema validation in build scripts → fail build on invalid spell/actor entry
+- Cross-reference linter: ensures every `@UUID[...]` in lore points to a real system compendium entry
+
+---
+
+## Appendix A - Implementation Order
+
+1. **v0.2.0 - System foundation**
+   - Expand `SpellData` schema (per `foundry-spell-reference.md` §5)
+   - Build `spells-*` packs from YAML sources
+   - Migration 0.1 → 0.2 for existing world spells
+2. **v0.3.0 - Compendium completeness**
+   - All talent / discipline / race / class packs built
+   - Bestiariusz actors imported
+3. **v0.4.0 - Mechanics expansion**
+   - `logic/blood-magic.ts`, `logic/abyss-magic.ts`, `logic/brewing.ts`, `logic/rest.ts`, `logic/trade.ts`
+   - Status conditions expanded (mental illnesses)
+4. **v0.5.0 - Lore module 1.0**
+   - Companion module `hbm-rpg-v3-lore` first release
+   - Przewodnik Ludzkości fully ported
+   - Cross-links established
+5. **v1.0.0 - Polish & full content**
+   - All 8 books represented
+   - English localization complete
+   - Compendium browser metadata, icons, art
+
+---
+
+## Appendix B - Outstanding Questions
+
+1. **Module repo location**: separate Git repo or sub-folder under `.src/`? Recommendation: separate folder `.src/foundry-lore/` for unified editing, separate `module.json` package output.
+2. **Asset licensing**: scene images, NPC portraits - which assets can ship in the module vs. be GM-supplied?
+3. **Polish-only vs bilingual**: should lore JournalEntries ship Polish-only initially, with English translation pack later?
+4. **Adventure content** (`adventures/` folder): adventure scenarios are neither system nor module content - recommend a third package `hbm-rpg-v3-adventures` per published adventure.
+5. **Foundry Module Marketplace listing**: needs cover art, description, screenshots before module submission.