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.