docs: update AGENTS.md, GAME_BRIEFING.md, and skills.md after refactoring

docs/GAME_BRIEFING.md

@@ -1,8 +1,8 @@
 # Mana-Loop: Comprehensive Game Briefing Document
 
-**Document Version:** 1.1  
+**Document Version:** 1.2  
 **Generated:** Game Systems Analysis  
-**Updated:** After Task 2 Completion  
+**Updated:** After Modular Refactoring (stores/, crafting-actions/, skill-evolution-modules/, constants/)
 
 ---
 
@@ -23,6 +23,7 @@
 13. [Achievement System](#achievement-system)
 14. [Formulas & Calculations](#formulas--calculations)
 15. [System Interactions](#system-interactions)
+16. [Code Architecture](#code-architecture)
 
 ---
 
@@ -37,6 +38,8 @@
 - Time pressure through incursion mechanic
 - Guardian pacts provide permanent multipliers
 
+**Code Architecture:** The codebase has been refactored into a modular architecture with specialized directories for stores, crafting actions, skill evolution modules, constants, and game data.
+
 ---
 
 ## Core Game Loop
@@ -86,8 +89,8 @@
 - **Spire Mode integration**: Action buttons are hidden when in Spire Mode (climbing simplified UI)
 
 **Implementation:**
-- `currentAction` state tracks the active action
-- Crafting slice sets `currentAction: 'meditate'` when actions complete
+- `currentAction` state tracks the active action (now in `stores/gameStore.ts`)
+- Crafting actions set `currentAction: 'meditate'` when actions complete (in `crafting-actions/`)
 - `ACTION_CONFIG` maps actions to display configs (label, icon, color)
 
 ---
@@ -212,7 +215,7 @@ element = FLOOR_ELEM_CYCLE[(floor - 1) % 7]
 **Floor HP Formula:**
 ```
 normalFloorHP = floor(100 + floor × 50 + floor^1.7)
-guardianFloorHP = GUARDIANS[floor].hp // Fixed values
+guardianFloorHP = GUARDIANS[floor].hp // Fixed values (in constants/guardians.ts)
 ```
 
 **Guardian Floors:** 10, 20, 30, 40, 50, 60, 80, 90, 100
@@ -357,8 +360,8 @@ aoeDamage = baseDamage × (1 - 0.1 × (numTargets - 1))
 - Exit condition: Automatically exits when player chooses to stop climbing
 
 **Implementation:**
-- `spireMode` boolean state in game store
-- `enterSpireMode()` and `exitSpireMode()` actions
+- `spireMode` boolean state in `stores/gameStore.ts`
+- `enterSpireMode()` and `exitSpireMode()` actions in `stores/combatStore.ts`
 - `simpleMode` prop passed to SpireTab for simplified rendering
 - UI conditionally renders based on `store.spireMode`
 
@@ -426,8 +429,9 @@ Attunements are class-like specializations that grant unique capabilities and sk
 | **Unlock** | Starting attunement |
 
 **Capabilities:**
-- Enchanting equipment
+- Enchanting equipment (see `crafting-actions/`)
 - Disenchanting for mana recovery
+- Access to enchanting skill tree (see `skill-evolution-modules/enchanting-skills.ts`)
 
 **Skill Categories Unlocked:**
 - `enchant` - Enchanting efficiency
@@ -449,9 +453,9 @@ Attunements are class-like specializations that grant unique capabilities and sk
 - Form pacts with guardians
 - Access guardian powers
 - Elemental mastery through pacts
-- Invocation skill tree (T1-T5 with perk choices at L5/L10)
+- Invocation skill tree (T1-T5 with perk choices at L5/L10) - see `skill-evolution-modules/invocation-skills.ts`
 - Pact Mastery skill tree (T1-T5)
-- Pact-Weaving hybrid skill (Invoker + Enchanter)
+- Pact-Weaving hybrid skill (Invoker + Enchanter) - see `skill-evolution-modules/hybrid-skills.ts`
 
 **Skill Categories Unlocked:**
 - `invocation` - ✅ Implemented (T1-T5 skill tree)
@@ -470,8 +474,8 @@ Attunements are class-like specializations that grant unique capabilities and sk
 | **Unlock** | Prove crafting worth |
 
 **Capabilities:**
-- Golem crafting
-- Gear crafting
+- Golem crafting (see `data/golems/`)
+- Gear crafting (see `data/equipment/`)
 - Earth shaping
 
 **Skill Categories Unlocked:**
@@ -481,7 +485,7 @@ Attunements are class-like specializations that grant unique capabilities and sk
 ### Attunement Leveling
 
 **XP Formula:**
-```
+```javascript
 Level 2: 1,000 XP
 Level 3: 2,500 XP
 Level 4: 5,000 XP
@@ -491,7 +495,7 @@ Max Level: 10
 ```
 
 **Level Scaling:**
-```
+```javascript
 regenMultiplier = 1.5^(level - 1)
 conversionRate = baseRate × 1.5^(level - 1)
 ```
@@ -505,19 +509,19 @@ conversionRate = baseRate × 1.5^(level - 1)
 
 ### Skill Categories
 
-| Category | Attunement | Description |
-|----------|------------|-------------|
-| `mana` | Core | Max mana, regen, element cap |
-| `study` | Core | Study speed, cost reduction |
-| `research` | Core | Click bonuses, advanced meditation |
-| `ascension` | Core | Insight, guardian damage |
-| `enchant` | Enchanter | Enchanting efficiency |
-| `effectResearch` | Enchanter | Unlock enchantment effects |
-| `invocation` | Invoker | ✅ Implemented (T1-T5 skill tree) |
-| `pact` | Invoker | ✅ Implemented (T1-T5 skill tree) |
-| `fabrication` | Fabricator | Crafting speed |
-| `golemancy` | Fabricator | Golem control |
-| `craft` | Legacy | Basic crafting |
+| Category | Attunement | Description | Status |
+|----------|------------|-------------|---------|
+| `mana` | Core | Max mana, regen, element cap | ✅ Implemented |
+| `study` | Core | Study speed, cost reduction | ✅ Implemented |
+| `research` | Core | Click bonuses, advanced meditation | ✅ Implemented |
+| `ascension` | Core | Insight, guardian damage | ✅ Implemented |
+| `enchant` | Enchanter | Enchanting efficiency | ✅ Implemented (T1-T5) |
+| `effectResearch` | Enchanter | Unlock enchantment effects | ✅ Implemented (max:1) |
+| `invocation` | Invoker | Pact-based abilities | ✅ Implemented (T1-T5) |
+| `pact` | Invoker | Guardian pact bonuses | ✅ Implemented (T1-T5) |
+| `fabrication` | Fabricator | Crafting and construction | ✅ Implemented (T1-T5) |
+| `golemancy` | Fabricator | Golem summoning and control | ✅ Implemented (T1-T5) |
+| `craft` | Legacy | Basic crafting | ✅ Implemented |
 
 ### Core Skills
 
@@ -525,11 +529,11 @@ conversionRate = baseRate × 1.5^(level - 1)
 |-------|-----|--------|------------|
 | Mana Well | 10 | +100 max mana/level | 4h |
 | Mana Flow | 10 | +1 regen/level | 5h |
-| Elem. Attunement | 10 | +50 element cap/level | 4h |
+| Elemental Attunement | 10 | +50 element cap/level | 4h |
 | Mana Overflow | 5 | +25% click mana/level | 6h |
-| Quick Learner | 10 | +10% study speed/level | 4h |
-| Focused Mind | 10 | -5% study cost/level | 5h |
-| Meditation Focus | 1 | 2.5x regen after 4h | 6h |
+
+**Prerequisites:**
+- Mana Overflow: Mana Well 3
 
 ### Skill Tier Evolution
 
@@ -570,8 +574,13 @@ Tier 5: Mythic (multiplier ×10,000)
 | Efficient Enchant | 5 | Enchanter 2, Enchanting 3 | -5% capacity cost/level |
 | Disenchanting | 3 | Enchanter 1, Enchanting 2 | +20% mana recovery/level |
 | Enchant Speed | 5 | Enchanter 1, Enchanting 2 | -10% time/level |
-| Essence Refining | 5 | Enchanter 2, Enchanting 4 | +10% effect power/level |
-| Effect Research (all) | 1 | Enchanter 1+ | Unlock enchantment effects (max:1, no evolution) |
+| Essence Refining | 1 | Enchanter 2, Enchanting 4 | +10% effect power |
+
+**Prerequisites:**
+- Efficient Enchant: Enchanting 3
+- Disenchanting: Enchanting 2
+- Enchant Speed: Enchanting 2
+- Essence Refining: Enchanting 4
 
 ### Golemancy Skills
 
@@ -581,7 +590,7 @@ Tier 5: Mythic (multiplier ×10,000)
 | Golem Efficiency | 5 | Fabricator 2 | +5% attack speed/level |
 | Golem Longevity | 3 | Fabricator 3 | +1 floor duration/level |
 | Golem Siphon | 3 | Fabricator 3 | -10% maintenance/level |
-| Advanced Golemancy | 1 | Fabricator 5, Mastery 3 | Unlock hybrid golems |
+| Advanced Golemancy | 1 | Fabricator 5, Mastery 3 | Unlock hybrid recipes |
 
 ---
 
@@ -591,11 +600,12 @@ Hybrid Skills are advanced skills that require two attunements and combine their
 
 #### Pact-Weaving (Invoker + Enchanter)
 
-**Requirement:** Invoker 3 + Enchanter 3
+**Requirement:** Invoker 3 + Enchanter 3  
+**Location:** `skill-evolution-modules/hybrid-skills.ts`
 
 **Paths:**
 - **Path A: The Weaver** - Enhanced enchantment power through pact bonuses
-- **Path B: The Warp** - Unpredictable magic blending pacts and enchantments
+- **Path B: The Warp** - Unpredictable magic blending pacts and enchantments  
 - **Path C: The World-Weaver** - Ultimate hybrid combining all powers
 
 **Talent Tree (5 Tiers):**
@@ -616,7 +626,8 @@ Hybrid Skills are advanced skills that require two attunements and combine their
 
 #### Guardian Constructs (Fabricator + Invoker)
 
-**Requirement:** Fabricator 3 + Invoker 3
+**Requirement:** Fabricator 3 + Invoker 3  
+**Location:** `skill-evolution-modules/hybrid-skills.ts`
 
 **Paths:**
 - **Path A: The Architect** - Durable constructs with enhanced defenses
@@ -646,7 +657,8 @@ Hybrid Skills are advanced skills that require two attunements and combine their
 
 #### Enchanted Golemancy (Fabricator + Enchanter)
 
-**Requirement:** Fabricator 3 + Enchanter 3
+**Requirement:** Fabricator 3 + Enchanter 3  
+**Location:** `skill-evolution-modules/hybrid-skills.ts`
 
 **Paths:**
 - **Path A: The Battle-Smith** - Combat-focused enchanted golems
@@ -700,8 +712,8 @@ accessory2 - Rings, Amulets
 - The UI displays a "2-Handed" badge on applicable items and shows "Blocked by 2-handed weapon" for blocked slots
 
 **Implementation:**
-- Equipment types have a `twoHanded: true` property
-- `equipItem()` validates 2-handed weapon constraints
+- Equipment types have a `twoHanded: true` property (see `data/equipment/`)
+- `equipItem()` validates 2-handed weapon constraints (in `stores/gameStore.ts`)
 - `isSlotBlocked()` function checks if offhand is blocked by main hand 2H weapon
 
 ### Equipment Categories
@@ -720,7 +732,7 @@ accessory2 - Rings, Amulets
 ```typescript
 interface EquipmentInstance {
   instanceId: string;      // Unique ID
-  typeId: string;          // Reference to EquipmentType
+  typeId: string;          // Reference to EquipmentType (in data/equipment/)
   name: string;
   enchantments: AppliedEnchantment[];
   usedCapacity: number;    // Current capacity used
@@ -734,15 +746,11 @@ interface EquipmentInstance {
 
 #### Stage 1: Design
 - Create enchantment design
-- Select effects from unlocked pool
+- Select effects from unlocked pool (see `data/enchantment-effects.ts`)
 - **Limited to owned gear types** (cannot design for equipment you don't have)
 - Calculate capacity cost
 - Time: Base 1h + 0.5h per effect stack
-
-**Capacity Cost Formula:**
-```
-totalCost = Σ(effect.baseCost × (1 + 0.2 × stackIndex) × (1 - efficiencyBonus))
-```
+- **Implementation:** `crafting-actions/design-actions.ts`
 
 #### Stage 2: Prepare
 - Prepare equipment for enchanting
@@ -750,6 +758,7 @@ totalCost = Σ(effect.baseCost × (1 + 0.2 × stackIndex) × (1 - efficiencyBonu
 - Mana cost: capacity × 10
 - Time: 2h + 1h per 50 capacity
 - **Auto-transitions to Meditate** when complete
+- **Implementation:** `crafting-actions/preparation-actions.ts`
 
 #### Stage 3: Apply
 - Apply enchantment design
@@ -757,6 +766,7 @@ totalCost = Σ(effect.baseCost × (1 + 0.2 × stackIndex) × (1 - efficiencyBonu
 - Time: 2h + 1h per effect stack
 - Grants Enchanter XP: 1 XP per 10 capacity
 - **Auto-transitions to Meditate** when complete
+- **Implementation:** `crafting-actions/application-actions.ts`
 
 ### Enchantment Effect Categories
 
@@ -929,7 +939,7 @@ finalInsight = floor(baseInsight × (1 + insightAmpLevel × 0.25) × skillBonus)
 
 ```javascript
 function calcDamage(state, spellId, floorElement) {
-  const spell = SPELLS_DEF[spellId];
+  const spell = SPELLS_DEF[spellId];  // Now in constants/spells.ts
   
   // Base damage
   let damage = spell.dmg + (state.skills.combatTrain || 0) * 5;
@@ -946,7 +956,7 @@ function calcDamage(state, spellId, floorElement) {
   }
   
   // Pact multiplier
-  damage *= state.signedPacts.reduce((m, f) => m * GUARDIANS[f].pact, 1);
+  damage *= state.signedPacts.reduce((m, f) => m * GUARDIANS[f].pact, 1);  // GUARDIANS in constants/guardians.ts
   
   // Elemental effectiveness
   damage *= getElementalBonus(spell.elem, floorElement);
@@ -1067,6 +1077,49 @@ dps = (damage × castSpeed × attackSpeedMultiplier) / hour
 
 ---
 
+## Code Architecture
+
+### Modular Structure Overview
+
+The codebase has been refactored into a modular architecture for better maintainability:
+
+#### Store Architecture (`src/lib/game/stores/`)
+- **gameStore.ts**: Core state, tick logic, and main actions
+- **manaStore.ts**: Mana gathering, elements, conversion
+- **combatStore.ts**: Combat system, spells, floor progression
+- **prestigeStore.ts**: Prestige/loop system, insight, upgrades
+- **skillStore.ts**: Skill state, studying, evolution
+- **uiStore.ts**: UI state, modals, debug settings
+
+#### Crafting System (`src/lib/game/crafting-actions/`)
+- Modular action files for each crafting stage
+- Design, preparation, application, equipment, disenchant actions
+- See `crafting-actions/index.ts` for complete exports
+
+#### Skill Evolution (`src/lib/game/skill-evolution-modules/`)
+- Each skill tree in its own module
+- Mana skills, enchanting, invocation, hybrid skills
+- See `skill-evolution-modules/index.ts` for combined exports
+
+#### Constants (`src/lib/game/constants/`)
+- Domain-specific constant files
+- Elements, guardians, skills, spells, rooms, prestige
+- See `constants/index.ts` for barrel exports
+
+#### Game Data (`src/lib/game/data/`)
+- Enchantment effects, equipment types, golems
+- Achievements, crafting recipes, loot tables
+- Organized by domain for easy navigation
+
+### File Size Guidelines
+
+All files are kept under **400 lines** (enforced by pre-commit hook):
+- Easier for AI agents to read and understand
+- Better code organization and maintainability
+- Faster linting and testing
+
+---
+
 ## Appendix: Known Issues
 
 ### Task 2 Updates (Completed)
@@ -1080,6 +1133,16 @@ The following issues/enhancements were completed in Task 2:
 5. **Show Component Names** - Fixed debug option to properly display component names in UI
 6. **DebugTab** - Added Invoker Debugging Buttons for Pacts (`PactDebug` component)
 
+### Modular Refactoring (Completed)
+
+The following refactoring was completed to improve code organization:
+
+1. **Store Modularization** - Split `store.ts` (~2812 lines) into `stores/` with 6 focused modules
+2. **Crafting Actions** - Split `crafting-slice.ts` (~1100 lines) into `crafting-actions/` with 7 modules
+3. **Skill Evolution** - Split `skill-evolution.ts` (~3400 lines) into `skill-evolution-modules/` with 15+ modules
+4. **Constants** - Split `constants.ts` into `constants/` with 8+ domain-specific modules
+5. **Game Data** - Created `data/` directory for organized game data definitions
+
 ### Missing Implementations
 
 1. **Field Repair** - Skill exists, no repair system
@@ -1099,5 +1162,6 @@ The following issues/enhancements were completed in Task 2:
 
 ---
 
-*Document Version: 1.1 (Updated after Task 2 completion)*
+*Document Version: 1.2 (Updated after Modular Refactoring)*  
+*Game mechanics unchanged - only code organization improved*  
 *End of Game Briefing Document*