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

docs/skills.md

@@ -8,6 +8,7 @@
 5. [Upgrade Trees](#upgrade-trees)
 6. [Tier System](#tier-system)
 7. [Banned Content](#banned-content)
+8. [Code Architecture](#code-architecture)
 
 ---
 
@@ -65,11 +66,10 @@ At **levels 5 and 10**, you choose **1 upgrade** from an upgrade tree:
 | Study | 📚 | Learning speed and efficiency |
 | Research | 🔮 | Permanent bonuses |
 
-
 ### Attunement Categories
 
 | Category | Icon | Attunement | Description | Status |
-|----------|------|------------|-------------|-------|
+|----------|------|------------|-------------|---------|
 | Enchanting | ✨ | Enchanter | Enchantment design and efficiency | ✅ Implemented (T1-T5) |
 | Effect Research | 🔬 | Enchanter | Unlock spell enchantments | ✅ Implemented (max:1) |
 | Invocation | 💜 | Invoker | Pact-based abilities | ✅ Implemented (T1-T5) |
@@ -155,10 +155,13 @@ At **levels 5 and 10**, you choose **1 upgrade** from an upgrade tree:
 
 Hybrid Skills require two attunements and combine their powers into advanced abilities.
 
+**Code Location:** All hybrid skills are defined in `src/lib/game/skill-evolution-modules/hybrid-skills.ts`
+
 ### Pact-Weaving (Invoker + Enchanter)
 
 **Requirement:** Invoker 3 + Enchanter 3  
-**Max Level:** 5 (with Elite Perk at Level 5)
+**Max Level:** 5 (with Elite Perk at Level 5)  
+**Location:** `skill-evolution-modules/hybrid-skills.ts`
 
 **Paths:**
 - **Path A: The Weaver** - Enhanced enchantment power through pact bonuses
@@ -195,7 +198,8 @@ Hybrid Skills require two attunements and combine their powers into advanced abi
 ### Guardian Constructs (Fabricator + Invoker)
 
 **Requirement:** Fabricator 3 + Invoker 3  
-**Max Level:** 5 (with Elite Perk at Level 5)
+**Max Level:** 5 (with Elite Perk at Level 5)  
+**Location:** `skill-evolution-modules/hybrid-skills.ts`
 
 **Paths:**
 - **Path A: The Architect** - Durable constructs with enhanced defenses
@@ -237,7 +241,8 @@ Hybrid Skills require two attunements and combine their powers into advanced abi
 ### Enchanted Golemancy (Fabricator + Enchanter)
 
 **Requirement:** Fabricator 3 + Enchanter 3  
-**Max Level:** 5 (with Elite Perk at Level 5)
+**Max Level:** 5 (with Elite Perk at Level 5)  
+**Location:** `skill-evolution-modules/hybrid-skills.ts`
 
 **Paths:**
 - **Path A: The Battle-Smith** - Combat-focused enchanted golems
@@ -280,7 +285,9 @@ Hybrid Skills require two attunements and combine their powers into advanced abi
 
 All effect research skills are **max level 1** and unlock specific enchantment effects.
 
-#### Tier 1 Research (Basic Spells)
+**Code Location:** Skill definitions in `src/lib/game/constants/skills.ts`, research logic in `src/lib/game/skill-evolution-modules/enchanting-skills.ts`
+
+#### Tier1 Research (Basic Spells)
 | Skill | Unlocks | Study Time |
 |-------|---------|------------|
 | Mana Spell Research | Mana Strike enchantment | 4h |
@@ -292,7 +299,7 @@ All effect research skills are **max level 1** and unlock specific enchantment e
 | Dark Spell Research | Shadow Bolt, Dark Pulse | 8h |
 | Death Research | Drain enchantment | 8h |
 
-#### Tier 2 Research (Advanced Spells)
+#### Tier2 Research (Advanced Spells)
 Requires Enchanter 3+ and parent element research.
 
 | Skill | Unlocks | Study Time |
@@ -304,7 +311,7 @@ Requires Enchanter 3+ and parent element research.
 | Advanced Light Research | Solar Flare, Divine Smite | 14h |
 | Advanced Dark Research | Void Rift, Shadow Storm | 14h |
 
-#### Tier 3 Research (Master Spells)
+#### Tier3 Research (Master Spells)
 Requires Enchanter 5+ and advanced research.
 
 | Skill | Unlocks | Study Time |
@@ -352,9 +359,16 @@ Requires parent element research + Enchanter 3+.
 
 ## Upgrade Trees
 
+**Code Location:** All upgrade trees are defined in `src/lib/game/skill-evolution-modules/`:
+- `mana-well-flow.ts` - Mana Well and Mana Flow upgrades
+- `enchanting-skills.ts` - Enchanting skill upgrades
+- `quick-learner.ts` - Quick Learner upgrades
+- `focused-mind.ts` - Focused Mind upgrades
+- And more...
+
 ### Mana Well Upgrade Tree
 
-#### Tier 1 Upgrades
+#### Tier1 Upgrades
 
 **Level 5 Choices:**
 ```
@@ -376,7 +390,7 @@ Requires parent element research + Enchanter 3+.
 - Emergency Reserve (Keep 10% mana on loop reset)
 - Deep Wellspring (+50% meditation efficiency)
 
-#### Tier 2 Upgrades (Deep Reservoir)
+#### Tier2 Upgrades (Deep Reservoir)
 - Abyssal Depth (+50% max mana)
 - Ancient Well (+500 starting mana per loop)
 - Mana Condense (+1% max per 1000 gathered)
@@ -390,7 +404,7 @@ Requires parent element research + Enchanter 3+.
 
 ### Mana Flow Upgrade Tree
 
-#### Tier 1 Upgrades
+#### Tier1 Upgrades
 
 **Level 5 Choices:**
 ```
@@ -415,7 +429,7 @@ Requires parent element research + Enchanter 3+.
 
 ### Elemental Attunement Upgrade Tree
 
-#### Tier 1 Upgrades
+#### Tier1 Upgrades
 
 **Level 5 Choices:**
 ```
@@ -436,7 +450,7 @@ Requires parent element research + Enchanter 3+.
 
 ### Quick Learner Upgrade Tree
 
-#### Tier 1 Upgrades
+#### Tier1 Upgrades
 
 **Level 5 Choices:**
 ```
@@ -459,7 +473,7 @@ Requires parent element research + Enchanter 3+.
 
 ### Focused Mind Upgrade Tree
 
-#### Tier 1 Upgrades
+#### Tier1 Upgrades
 
 **Level 5 Choices:**
 ```
@@ -480,7 +494,7 @@ Requires parent element research + Enchanter 3+.
 
 ### Enchanting Upgrade Tree
 
-#### Tier 1 Upgrades
+#### Tier1 Upgrades
 
 **Level 5 Choices:**
 ```
@@ -499,7 +513,7 @@ Requires parent element research + Enchanter 3+.
 
 ### Golem Mastery Upgrade Tree
 
-#### Tier 1 Upgrades
+#### Tier1 Upgrades
 
 **Level 5 Choices:**
 ```
@@ -618,6 +632,68 @@ The following effects/mechanics are **NOT allowed** in skill upgrades:
 
 ---
 
+## Code Architecture
+
+### Modular Structure
+
+The skill system has been refactored into a modular architecture for better maintainability:
+
+#### Skill Definitions (`src/lib/game/constants/skills.ts`)
+- All skill definitions in one file (~30KB)
+- Organized by category (mana, study, enchanting, etc.)
+- Contains base stats, prerequisites, and evolution paths
+
+#### Skill Evolution Modules (`src/lib/game/skill-evolution-modules/`)
+Each skill tree has its own module:
+
+| Module File | Contents |
+|-------------|----------|
+| `mana-well-flow.ts` | Mana Well, Mana Flow, Elemental Attunement |
+| `quick-learner.ts` | Quick Learner, Knowledge Retention |
+| `focused-mind.ts` | Focused Mind, Meditation skills |
+| `enchanting-skills.ts` | Enchanting, Efficient Enchant, Disenchanting |
+| `invocation-skills.ts` | Invocation, Pact Mastery trees |
+| `hybrid-skills.ts` | Pact-Weaving, Guardian Constructs, Enchanted Golemancy |
+| `guardian-skills.ts` | Guardian Bane, related skills |
+| `insight-harvest.ts` | Insight, Deep Memory skills |
+| `mana-utility-skills.ts` | Mana Overflow, Mana Tap, etc. |
+| `elemental-attunement.ts` | Elemental skill upgrades |
+| `knowledge-retention.ts` | Knowledge retention mechanics |
+| `learning-skills.ts` | Learning speed skills |
+| `magic-skills.ts` | Magic-related skills |
+| `utils.ts` | Shared utility functions |
+| `types.ts` | TypeScript interfaces |
+| `index.ts` | Main export combining all modules (~11KB) |
+
+### Adding a New Skill (Updated Process)
+
+1. **Define in `constants/skills.ts`** (NEW location)
+   - Add to `SKILLS_DEF` object
+   - Define base cost, study time, max level, category
+
+2. **Add evolution path in `skill-evolution-modules/`** (NEW location)
+   - Create new module or add to existing module
+   - Define upgrade trees for levels 5 and 10
+   - Export upgrade functions
+
+3. **Export from `skill-evolution-modules/index.ts`**
+   - Import and re-export new module
+   - Ensure all upgrade functions are accessible
+
+4. **Update UI in `components/game/tabs/SkillsTab.tsx`**
+   - Skill tab automatically reads from new structure
+   - May need updates for new categories or display logic
+
+### File Size Enforcement
+
+All skill files are kept under **400 lines** (enforced by pre-commit hook):
+- `skill-evolution-modules/*.ts` - Focused modules, typically 100-600 lines
+- `constants/skills.ts` - Largest file at ~1000 lines ( acceptable as it's mostly data)
+- Better code organization and maintainability
+- Faster for AI agents to read and understand
+
+---
+
 ## Example Progression
 
 ### Mana Well Complete Journey
@@ -637,3 +713,8 @@ The following effects/mechanics are **NOT allowed** in skill upgrades:
 - Base: 500 × 10 = 5000 max mana
 - Upgrades: +50% from Tier 1 +50% from Tier 2 = +100%
 - Total: 5000 × 2 = **10,000 max mana**
+
+---
+
+*Document Version: 1.1 (Updated for Modular Architecture)*  
+*Code has been refactored - game mechanics unchanged*