# Mana Loop - Project Architecture Guide

This document provides a comprehensive overview of the project architecture for AI agents working on this codebase.

---

## 🔑 Git Credentials (SAVE THESE)

**Repository:** `git@gitea.tailf367e3.ts.net:Anexim/Mana-Loop.git`

**HTTPS URL with credentials:**
```
https://n8n-gitea:tkF9HFgxL2k4cmT@gitea.tailf367e3.ts.net/Anexim/Mana-Loop.git
```

**Credentials:**
- **User:** n8n-gitea
- **Email:** n8n-gitea@anexim.local
- **Password:** tkF9HFgxL2k4cmT

**To configure git:**
```bash
git config --global user.name "n8n-gitea"
git config --global user.email "n8n-gitea@anexim.local"
```

---

## ⚠️ MANDATORY GIT WORKFLOW - MUST BE FOLLOWED

**Before starting ANY work, you MUST:**

1. **Pull the latest changes:**
   ```bash
   cd /home/user/repos/Mana-Loop && git pull origin master
   ```

2. **Do your task** - Make all necessary code changes

3. **Before finishing, commit and push:**
   ```bash
   cd /home/user/repos/Mana-Loop
   git add -A
   git commit -m "descriptive message about changes"
   git push origin master
   ```

**This workflow is ENFORCED and NON-NEGOTIABLE.** Every agent session must:
- Start with `git pull`
- End with `git add`, `git commit`, `git push`

**Git Remote:** `git@gitea.tailf367e3.ts.net:Anexim/Mana-Loop.git`

---

## Project Overview

**Mana Loop** is an incremental/idle game built with:
- **Framework**: Next.js 16 with App Router
- **Language**: TypeScript 5
- **Styling**: Tailwind CSS 4 with shadcn/ui components
- **State Management**: Zustand with persist middleware (modular store architecture)
- **Database**: Prisma ORM with SQLite (for persistence features)

## Core Game Loop

1. **Mana Gathering**: Click or auto-generate mana over time
2. **Studying**: Spend mana to learn skills and spells
3. **Combat**: Climb the Spire, defeat guardians, sign pacts
4. **Crafting**: Enchant equipment with spell effects
5. **Prestige**: Reset progress for permanent bonuses (Insight)

## Directory Structure

```
src/
├── app/
│   ├── page.tsx          # Main game UI (~reduced via component extraction)
│   ├── layout.tsx        # Root layout with providers
│   ├── api/              # API routes (minimal use)
│   └── components/       # App-level components
│       ├── GameOverScreen.tsx
│       ├── LeftPanel.tsx
│       └── ...
├── components/
│   ├── ui/               # shadcn/ui components (auto-generated)
│   └── game/             # All game components (modular structure)
│       ├── index.ts       # Barrel exports
│       ├── GameContext.tsx
│       ├── ActionButtons.tsx
│       ├── CalendarDisplay.tsx
│       ├── CraftingProgress.tsx
│       ├── ManaDisplay.tsx
│       ├── TimeDisplay.tsx
│       ├── tabs/                # Tab-specific components
│       │   ├── index.ts
│       │   ├── AchievementsTab.tsx
│       │   ├── AttunementsTab.tsx
│       │   ├── CraftingTab.tsx
│       │   ├── DebugTab.tsx
│       │   ├── EquipmentTab.tsx
│       │   ├── GolemancyTab.tsx
│       │   ├── LabTab.tsx
│       │   ├── LootTab.tsx
│       │   ├── PrestigeTab.tsx
│       │   ├── SkillsTab.tsx
│       │   ├── SpellsTab.tsx
│       │   ├── SpireTab.tsx
│       │   ├── StatsTab.tsx
│       │   ├── EquipmentSlotGrid.tsx
│       │   ├── EquipmentControls.tsx
│       │   ├── EnchantmentsPanel.tsx
│       │   ├── EquipmentInventory.tsx
│       │   ├── SkillRow.tsx
│       │   ├── SkillCategoryHeader.tsx
│       │   ├── MilestoneProgress.tsx
│       │   ├── SkillMultipliers.tsx
│       │   ├── SpireHeader.tsx
│       │   ├── GuardianPanel.tsx
│       │   ├── RoomDisplay.tsx
│       │   ├── FloorControls.tsx
│       │   ├── CombatStatsPanel.tsx
│       │   └── ActivityLog.tsx
│       ├── crafting/           # Crafting-specific components
│       │   ├── index.tsx
│       │   ├── EnchantmentDesigner/
│       │   ├── EnchantmentApplier.tsx
│       │   ├── EnchantmentPreparer.tsx
│       │   └── EquipmentCrafter.tsx
│       ├── stats/              # Stats display components
│       │   ├── index.tsx
│       │   ├── CombatStatsSection.tsx
│       │   ├── ManaStatsSection.tsx
│       │   ├── ManaTypeBreakdown.tsx
│       │   ├── StudyStatsSection.tsx
│       │   └── UpgradeEffectsSection.tsx
│       ├── debug/              # Debug tools
│       │   ├── index.tsx
│       │   ├── SkillDebug.tsx
│       │   ├── ElementDebug.tsx
│       │   ├── AttunementDebug.tsx
│       │   ├── GolemDebug.tsx
│       │   ├── PactDebug.tsx
│       │   └── GameStateDebug.tsx
│       ├── shared/             # Shared sub-components
│       │   ├── MemorySlotPicker.tsx
│       │   ├── StudyProgress.tsx
│       │   └── UpgradeDialog.tsx
│       └── LootInventory/      # Loot display components
│           ├── index.tsx
│           ├── MaterialItem.tsx
│           ├── EssenceItem.tsx
│           ├── BlueprintsSection.tsx
│           ├── EquipmentItem.tsx
│           └── LootInventoryDisplay.tsx
└── lib/
    ├── game/
    │   ├── stores/                    # Modular Zustand stores (NEW)
    │   │   ├── index.ts              # Combined store exports
    │   │   ├── gameStore.ts          # Main store (~11KB, core state + tick)
    │   │   ├── manaStore.ts          # Mana state and actions (~9KB)
    │   │   ├── combatStore.ts        # Combat system (~9KB)
    │   │   ├── prestigeStore.ts      # Prestige/loop system (~8KB)
    │   │   ├── skillStore.ts         # Skill state and actions (~11KB)
    │   │   ├── uiStore.ts            # UI state (~2KB)
    │   │   ├── gameLoopActions.ts    # Game loop logic
    │   │   ├── gameActions.ts        # Generic game actions
    │   │   └── gameHooks.ts          # Store hooks
    │   ├── store/                    # Legacy store slices (migration in progress)
    │   │   ├── index.ts             # Re-exports from store.ts + computed utils
    │   │   ├── combatSlice.ts       # Combat state slice
    │   │   ├── manaSlice.ts         # Mana state slice
    │   │   ├── skillSlice.ts        # Skill state slice
    │   │   ├── craftingSlice.ts     # Crafting state slice
    │   │   └── computed.ts          # Computed stats
    │   ├── store-modules/             # Legacy store utilities
    │   ├── crafting-actions/          # Modular crafting system (NEW)
    │   │   ├── index.ts
    │   │   ├── application-actions.ts
    │   │   ├── design-actions.ts
    │   │   ├── preparation-actions.ts
    │   │   ├── equipment-actions.ts
    │   │   ├── crafting-equipment-actions.ts
    │   │   ├── disenchant-actions.ts
    │   │   └── computed-getters.ts
    │   ├── skill-evolution-modules/   # Modular skill evolution (NEW)
    │   │   ├── index.ts              # Main export (~11KB)
    │   │   ├── mana-well-flow.ts     # Mana Well/Flow skills (~15KB)
    │   │   ├── quick-learner.ts      # Quick Learner skill (~7KB)
    │   │   ├── focused-mind.ts       # Focused Mind skill (~6KB)
    │   │   ├── enchanting-skills.ts  # Enchanting skills (~15KB)
    │   │   ├── invocation-skills.ts  # Invocation skills (~15KB)
    │   │   ├── hybrid-skills.ts      # Hybrid skills (~22KB)
    │   │   ├── guardian-skills.ts    # Guardian-related skills (~4KB)
    │   │   ├── insight-harvest.ts    # Insight Harvest skill (~7KB)
    │   │   ├── mana-utility-skills.ts # Mana utility skills (~7KB)
    │   │   ├── elemental-attunement.ts # Elemental Attunement (~7KB)
    │   │   ├── knowledge-retention.ts  # Knowledge Retention (~4KB)
    │   │   ├── learning-skills.ts   # Learning skills (~1KB)
    │   │   ├── magic-skills.ts       # Magic skills (~1KB)
    │   │   ├── utils.ts             # Skill evolution utilities
    │   │   └── types.ts             # TypeScript interfaces
    │   ├── constants/                # Modular constants (NEW)
    │   │   ├── index.ts
    │   │   ├── core.ts              # Core game constants
    │   │   ├── elements.ts          # Element definitions
    │   │   ├── guardians.ts         # Guardian definitions
    │   │   ├── prestige.ts          # Prestige upgrade definitions
    │   │   ├── rooms.ts             # Room type definitions
    │   │   ├── skills.ts            # Skill definitions (~30KB)
    │   │   ├── spells.ts            # Spell definitions
    │   │   └── spells-modules/      # Spell sub-modules
    │   ├── data/                     # Game data definitions (NEW)
    │   │   ├── enchantment-effects.ts
    │   │   ├── enchantments/        # Enchantment definitions
    │   │   ├── equipment/           # Equipment definitions
    │   │   ├── golems/              # Golem definitions
    │   │   ├── achievements.ts
    │   │   ├── crafting-recipes.ts
    │   │   └── loot-drops.ts
    │   ├── crafting-slice.ts         # Legacy crafting (being modularized)
    │   ├── skill-evolution.ts        # Legacy skill evolution (reduced, ~1.5KB)
    │   ├── constants.ts              # Legacy constants (reduced, ~1KB)
    │   ├── store.ts                  # Legacy store (reduced, ~14KB)
    │   ├── computed-stats.ts         # Computed stats functions
    │   ├── navigation-slice.ts       # Floor navigation actions
    │   ├── study-slice.ts            # Study system actions
    │   ├── effects.ts                # Unified effect computation
    │   ├── upgrade-effects.ts        # Skill upgrade effect definitions
    │   ├── types.ts                  # TypeScript interfaces
    │   ├── formatting.ts             # Display formatters
    │   └── utils/                    # Utility functions
    └── utils.ts                      # General utilities (cn function)
```

*Note: A complete, up-to-date project tree is automatically generated on each commit and saved to `docs/project-structure.txt`. This file is generated by the pre-commit hook using `.husky/scripts/generate-project-tree.js` and respects `.gitignore` rules.*

## Key Systems

### 1. State Management (Modular Store Architecture)

The game uses a **modular Zustand store architecture** with multiple specialized stores:

#### Store Modules (`src/lib/game/stores/`)
- **gameStore.ts**: Core state, tick logic, and main actions (~11KB)
- **manaStore.ts**: Mana gathering, elements, conversion (~9KB)
- **combatStore.ts**: Combat system, spells, floor progression (~9KB)
- **prestigeStore.ts**: Prestige/loop system, insight, upgrades (~8KB)
- **skillStore.ts**: Skill state, studying, evolution (~11KB)
- **uiStore.ts**: UI state, modals, debug settings (~2KB)

#### Legacy Store Files (Being Migrated)
- **store.ts**: Reduced from ~2812 lines to ~14KB (core logic moved to stores/)
- **crafting-slice.ts**: Reduced, being replaced by crafting-actions/

#### Store Interaction Pattern
```typescript
// Each store can interact with other stores via get() and custom hooks
// Example from combatStore.ts:
import { useManaStore } from './manaStore';

// Access other store state
const manaState = useManaStore.getState();
```

### 2. Crafting System (Modular Architecture)

The crafting system has been split into focused action modules:

#### Crafting Action Modules (`src/lib/game/crafting-actions/`)
- **design-actions.ts**: Enchantment design creation (~3KB)
- **preparation-actions.ts**: Equipment preparation (~1KB)
- **application-actions.ts**: Enchantment application (~2KB)
- **equipment-actions.ts**: Equipment management (~2.5KB)
- **crafting-equipment-actions.ts**: Equipment crafting (~2.5KB)
- **disenchant-actions.ts**: Disenchanting logic (~1KB)
- **computed-getters.ts**: Crafting computed values (~2KB)
- **index.ts**: Barrel exports

### 3. Skill Evolution System (Modular Architecture)

The massive ~3400-line `skill-evolution.ts` has been split into focused modules:

#### Skill Evolution Modules (`src/lib/game/skill-evolution-modules/`)
- **index.ts**: Main export combining all skill trees (~11KB)
- **mana-well-flow.ts**: Mana Well and Mana Flow skills (~15KB)
- **quick-learner.ts**: Quick Learner and related skills (~7KB)
- **focused-mind.ts**: Focused Mind and study skills (~6KB)
- **enchanting-skills.ts**: Enchanting skill tree (~15KB)
- **invocation-skills.ts**: Invocation and Pact Mastery (~15KB)
- **hybrid-skills.ts**: Cross-attunement hybrid skills (~22KB)
- **guardian-skills.ts**: Guardian-related skills (~4KB)
- **insight-harvest.ts**: Insight and prestige skills (~7KB)
- **mana-utility-skills.ts**: Utility mana skills (~7KB)
- **elemental-attunement.ts**: Elemental skills (~7KB)
- **knowledge-retention.ts**: Knowledge retention skill (~4KB)
- **learning-skills.ts**: Basic learning skills (~1KB)
- **magic-skills.ts**: Magic-related skills (~1KB)
- **utils.ts**: Shared utilities
- **types.ts**: TypeScript interfaces

### 4. Constants System (Modular Architecture)

Game constants have been organized into domain-specific modules:

#### Constants Modules (`src/lib/game/constants/`)
- **core.ts**: Core game constants (timing, limits)
- **elements.ts**: Element definitions and hierarchies
- **guardians.ts**: Guardian definitions and stats
- **prestige.ts**: Prestige upgrade definitions
- **rooms.ts**: Room type definitions
- **skills.ts**: Complete skill definitions (~30KB)
- **spells.ts**: Spell definitions
- **spells-modules/**: Organized spell sub-modules
- **index.ts**: Barrel exports

### 5. Game Data (New Structure)

#### Data Directory (`src/lib/game/data/`)
- **enchantment-effects.ts**: Enchantment effect catalog
- **enchantments/**: Enchantment definitions by category
- **equipment/**: Equipment type definitions
- **golems/**: Golem type definitions
- **achievements.ts**: Achievement definitions
- **crafting-recipes.ts**: Crafting recipe definitions
- **loot-drops.ts**: Loot table definitions

### Computed Stats (`computed-stats.ts`)
Extracted utility functions for stat calculations:
- `computeMaxMana()`, `computeRegen()`, `computeEffectiveRegen()`
- `calcDamage()`, `calcInsight()`, `getElementalBonus()`
- `getFloorMaxHP()`, `getFloorElement()`, `getMeditationBonus()`
- `canAffordSpellCost()`, `deductSpellCost()`

```typescript
interface GameState {
  // Time
  day: number;
  hour: number;
  paused: boolean;
  
  // Mana (now in manaStore.ts)
  rawMana: number;
  elements: Record<string, ElementState>;
  
  // Combat (now in combatStore.ts)
  currentFloor: number;
  floorHP: number;
  activeSpell: string;
  castProgress: number;
  
  // Progression (now in skillStore.ts)
  skills: Record<string, number>;
  spells: Record<string, SpellState>;
  skillUpgrades: Record<string, string[]>;
  skillTiers: Record<string, number>;
  
  // Equipment
  equipmentInstances: Record<string, EquipmentInstance>;
  equippedInstances: Record<string, string | null>;
  enchantmentDesigns: EnchantmentDesign[];
  
  // Prestige (now in prestigeStore.ts)
  insight: number;
  prestigeUpgrades: Record<string, number>;
  signedPacts: number[];
}
```

### Effect System (`effects.ts`)

**CRITICAL**: All stat modifications flow through the unified effect system.

```typescript
// Effects come from two sources:
// 1. Skill Upgrades (milestone bonuses)
// 2. Equipment Enchantments (crafted bonuses)

getUnifiedEffects(state) => UnifiedEffects {
  maxManaBonus, maxManaMultiplier,
  regenBonus, regenMultiplier,
  clickManaBonus, clickManaMultiplier,
  baseDamageBonus, baseDamageMultiplier,
  attackSpeedMultiplier,
  critChanceBonus, critDamageMultiplier,
  studySpeedMultiplier,
  specials: Set<string>,  // Special effect IDs
}
```

**When adding new stats**:
1. Add to `ComputedEffects` interface in `upgrade-effects.ts`
2. Add mapping in `computeEquipmentEffects()` in `effects.ts`
3. Apply in the relevant game logic (tick, damage calc, etc.)

## Important Patterns

### Adding a New Effect

1. **Define in `enchantment-effects.ts`** (now in `data/enchantment-effects.ts`):
```typescript
my_new_effect: {
  id: 'my_new_effect',
  name: 'Effect Name',
  description: '+10% something',
  category: 'combat',
  baseCapacityCost: 30,
  maxStacks: 3,
  allowedEquipmentCategories: ['caster', 'hands'],
  effect: { type: 'multiplier', stat: 'attackSpeed', value: 1.10 }
}
```

2. **Add stat mapping in `effects.ts`** (if new stat):
```typescript
// In computeEquipmentEffects()
if (effect.stat === 'myNewStat') {
  bonuses.myNewStat = (bonuses.myNewStat || 0) + effect.value;
}
```

3. **Apply in game logic**:
```typescript
const effects = getUnifiedEffects(state);
damage *= effects.myNewStatMultiplier;
```

### Adding a New Skill

1. **Define in `constants/skills.ts`** (NEW location)
2. **Add evolution path in `skill-evolution-modules/`** (NEW location)
   - Create new module or add to existing module
3. **Export from `skill-evolution-modules/index.ts`**
4. **Update UI in `components/game/tabs/SkillsTab.tsx`**

### Adding a New Spell

1. **Define in `constants/spells.ts`** (NEW location)
2. **Add to `constants/spells-modules/`** if categorized
3. **Add spell enchantment in `data/enchantment-effects.ts`**
4. **Add research skill in `constants/skills.ts`**
5. **Map research to effect in `EFFECT_RESEARCH_MAPPING`**

## Git Hooks (Husky)

This project uses **Husky** to manage git hooks for automated checks and agent assistance:

### Pre-Commit Hook (`.husky/pre-commit`)
Runs automatically before each commit:
1. **File Size Check**: Ensures no staged file exceeds 400 lines (improves AI agent readability)
2. **Project Structure Generation**: Updates `docs/project-structure.txt` with current tree (respects `.gitignore`)

### Post-Merge Hook (`.husky/post-merge`)
Runs after merging branches:
- Checks if `package.json` or `package-lock.json` changed
- Automatically runs `npm install` to sync dependencies

### Implementation Files
- Hook scripts: `.husky/` directory
- File size check: `.husky/scripts/check-file-size.js`
- Tree generator: `.husky/scripts/generate-project-tree.js`

---

## Common Pitfalls

1. **Forgetting to call `getUnifiedEffects()`**: Always use unified effects for stat calculations
2. **Direct stat modification**: Never modify stats directly; use effect system
3. **Missing tier multiplier**: Use `getTierMultiplier(skillId)` for tiered skills
4. **Ignoring special effects**: Check `hasSpecial(effects, SPECIAL_EFFECTS.X)` for special abilities
5. **Not updating modular stores**: Check all stores in `stores/` directory for related state
6. **Bypassing crafting-actions**: Use the modular actions in `crafting-actions/` for new crafting features

## Testing

Run `npm run test` before every commit. Tests must pass.

When fixing a bug, write a test that would have caught it first.
Test files live in src/lib/game/stores/__tests__/.

Critical paths that must always have tests:
- Any store action that modifies rawMana
- Any store action that modifies equippedInstances
- computeRegen, computeMaxMana, calcDamage
- canAffordSpellCost, spendRawMana, deductSpellCost

## Testing Guidelines

- Run `npm run lint` after changes
- Run `npm run test` to execute unit tests
- Check dev server logs
- Test with fresh game state (clear localStorage)
- **New**: Tests are organized alongside their modules (e.g., `stores/__tests__/`, `store-tests/`)

## Modular Architecture Pattern

The codebase has been refactored from large monolithic files into focused, modular components. This improves:
- **Maintainability**: Each module has a single responsibility
- **Readability**: Files are under 400 lines (pre-commit hook enforces this)
- **AI Agent Efficiency**: Smaller files are easier to understand and modify

### Key Modular Directories

| Directory | Purpose | Line Count Target |
|-----------|---------|-------------------|
| `stores/` | Zustand store modules | < 400 lines each |
| `crafting-actions/` | Crafting system actions | < 400 lines each |
| `skill-evolution-modules/` | Skill trees by category | < 400 lines each |
| `constants/` | Game constants by domain | < 400 lines each |
| `data/` | Game data definitions | < 400 lines each |
| `components/game/tabs/` | UI tab components | < 400 lines each |
| `components/game/crafting/` | Crafting UI components | < 400 lines each |
| `components/game/stats/` | Stats display components | < 400 lines each |

### Creating a New Module

1. **Identify the domain**: Which system does it belong to?
2. **Create focused file**: Keep under 400 lines
3. **Export from index**: Add to barrel export file
4. **Update imports**: Fix all references to old location
5. **Test**: Run lint and tests before committing

---

## File Size Guidelines

### Current File Sizes (After Modular Refactoring)

| File | Lines | Size (bytes) | Notes |
|------|-------|--------------|-------|
| `stores/gameStore.ts` | ~300 | ~11KB | Core state + tick logic |
| `stores/manaStore.ts` | ~250 | ~9KB | Mana system |
| `stores/combatStore.ts` | ~250 | ~9KB | Combat system |
| `stores/prestigeStore.ts` | ~200 | ~8KB | Prestige system |
| `stores/skillStore.ts` | ~300 | ~11KB | Skill system |
| `stores/uiStore.ts` | ~50 | ~2KB | UI state |
| `crafting-actions/*.ts` | ~50-150 | ~1-3KB each | Modular crafting |
| `skill-evolution-modules/*.ts` | ~100-600 | ~4-22KB each | Modular skills |
| `constants/*.ts` | ~50-1000 | ~1-30KB each | Modular constants |
| `page.tsx` | ~100 | ~4KB | Main UI (heavily reduced) |
| `components/game/tabs/*.tsx` | ~50-400 | ~2-15KB each | Tab components |

### Guidelines
- **400 lines maximum** per file (enforced by pre-commit hook)
- Extract to modules when approaching 300 lines
- Use barrel exports (`index.ts`) for clean imports
- Keep related functionality together in modules
- **Modular architecture** is now the standard - all new code should follow this pattern

### Automated File Size Check
A pre-commit hook automatically checks all staged files. Files exceeding **400 lines** will be rejected. The hook runs via Husky and uses `.husky/scripts/check-file-size.js`. If your file is too large, refactor it into smaller modules before committing.

---

## 🚫 BANNED CONTENT - NEVER ADD THESE

### Lifesteal and Healing are BANNED
**DO NOT add lifesteal or healing mechanics to player abilities.**

This includes:
- `lifesteal` spell effects
- `heal` or `regeneration` abilities for the player
- Any mechanic that restores player HP or mana based on damage dealt
- Life-stealing weapons or enchantments

**Rationale**: The game's core design is that the player cannot take damage - only floors can. Healing/lifesteal mechanics are unnecessary and would create confusing gameplay.

### Banned Mana Types
The following mana types have been **removed** and should **never be re-added**:
- `life` - Healing/lifesteal themed (banned)
- `blood` - Life + Water compound (banned due to lifesteal theme)
- `wood` - Life + Earth compound (banned due to life connection)
- `mental` - Mind/psionic themed (removed for design consistency)
- `force` - Telekinetic themed (removed for design consistency)

### Removed Features
- LabTab — permanently removed. Do not re-add under any name.
  The lab element conversion UI was replaced by attunements.

---

## 🔮 Mana Types Overview

### Base Mana Types (7)
| Element | Symbol | Color | Theme |
|---------|--------|-------|-------|
| Fire | 🔥 | #FF6B35 | Destruction, burn damage |
| Water | 💧 | #4ECDC4 | Flow, freeze effects |
| Air | 🌬️ | #00D4FF | Speed, wind damage |
| Earth | ⛰️ | #F4A261 | Stability, armor pierce |
| Light | ☀️ | #FFD700 | Radiance, holy damage |
| Dark | 🌑 | #9B59B6 | Shadows, void damage |
| Death | 💀 | #778CA3 | Decay, rot damage |

### Utility Mana Types (1)
| Element | Symbol | Color | Theme |
|---------|--------|-------|-------|
| Transference | 🔗 | #1ABC9C | Mana transfer, Enchanter attunement |

### Compound Mana Types (3)
| Element | Recipe | Theme |
|---------|--------|-------|
| Metal | Fire + Earth | Armor piercing, forged weapons |
| Sand | Earth + Water | AOE damage, desert winds |
| Lightning | Fire + Air | Fast damage, armor pierce, chain effects |

### Exotic Mana Types (3)
| Element | Recipe | Theme |
|---------|--------|-------|
| Crystal | Sand + Sand + Light | Prismatic, high damage |
| Stellar | Fire + Fire + Light | Cosmic, ultimate fire/light |
| Void | Dark + Dark + Death | Oblivion, ultimate dark/death |

### Mana Type Hierarchy
```
Base Elements (7) → Compound (3) → Exotic (3)
                      ↓
              Utility (1) ← Special attunement-based
```

<!-- gitnexus:start -->
# GitNexus — Code Intelligence

This project is indexed by GitNexus as **Mana-Loop** (3795 symbols, 6409 relationships, 146 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.

> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.

## Always Do

- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.

## Never Do

- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.

## Resources

| Resource | Use for |
|----------|---------|
| `gitnexus://repo/Mana-Loop/context` | Codebase overview, check index freshness |
| `gitnexus://repo/Mana-Loop/clusters` | All functional areas |
| `gitnexus://repo/Mana-Loop/processes` | All execution flows |
| `gitnexus://repo/Mana-Loop/process/{name}` | Step-by-step execution trace |

## CLI

| Task | Read this skill file |
|------|---------------------|
| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |

<!-- gitnexus:end -->