Mana-Loop/AGENTS.md

# Mana Loop — Agent Guide

Browser incremental/idle game. Next.js 16 + Zustand, no backend, localStorage persistence.

## 🔑 Git

```
https://n8n-gitea:tkF9HFgxL2k4cmT@gitea.tailf367e3.ts.net/Anexim/Mana-Loop.git
```
```bash
git config --global user.name "n8n-gitea"
git config --global user.email "n8n-gitea@anexim.local"
```

## Workflow

```bash
cd /home/user/repos/Mana-Loop && git pull origin master
# ... work ...
git add -A && git commit -m "type: desc" && git push origin master
```

## Session Start

1. `docs/project-structure.txt`
2. `docs/dependency-graph.json`
3. `gitea_start_session` → retrieve active task registry and issues
4. Evaluate the queue to find the highest-priority `ai_state: todo` item (or locate an existing `in-progress` task if resuming work)
5. `gitea_update_issue_status` → `ai_state: "in-progress"`
6. Work, log with `gitea_add_comment`, then `gitea_update_issue_status` → `ai_state: "done"`

## Labels

`ai_state: todo` | `ai_state: in-progress` | `ai_state: review` | `ai_state: blocked` | `ai_state: done`

## Terminal Tool

Always pair `run_command` → `get_process_status` in same turn. Use `wait: 120` for long tasks.

## Sub-Agents

Use for 3+ sequential independent calls. Zero context from parent — paste everything needed.

## Architecture

- **Stack:** Next.js 16, TS 5, Tailwind 4 + shadcn/ui, Zustand+persist, Vitest, Bun
- **No backend:** Pure client-side. No Prisma, no database. State persisted to localStorage.
- **Active stores (8 Zustand stores):**
  - `useGameStore` — Coordinator/tick pipeline, imports all other stores
  - `useManaStore` — Mana pools, regen, element conversion
  - `useCombatStore` — Spire/floors, combat, spells, achievements
  - `useCraftingStore` — Enchanting (Design/Prepare/Apply), equipment instances, loot
  - `useAttunementStore` — Enchanter/Invoker/Fabricator attunement levels & XP
  - `usePrestigeStore` — Insight, prestige upgrades, pact persistence, loop state
  - `useDisciplineStore` — Discipline activation, XP ticking, perk evaluation (slice)
  - `useUIStore` — Logs, pause, game over/victory flags
- **Legacy:** Fully migrated. No legacy `store.ts`, `store/`, or `store-modules/` directories remain.

### Adding Effects
1. `data/enchantments/` — Add effect definition in the appropriate category file
2. `craftingStore.ts` → effects computation
3. Equipment effects flow through `src/lib/game/effects.ts` → `getUnifiedEffects()`

### Adding Disciplines
1. Choose the correct data file under `data/disciplines/`:
   - `base.ts` — Raw Mana Mastery (3 disciplines)
   - `elemental.ts` — Elemental Attunement (21 disciplines — all 22 mana types)
   - `elemental-regen.ts` — Elemental Regen (8 disciplines — 7 base + transference)
   - `elemental-regen-advanced.ts` — Advanced Regen (15 disciplines — 8 composite + 6 exotic + transference composite)
   - `enchanter.ts` — Core Enchanter disciplines (4 disciplines)
   - `enchanter-utility.ts` — Utility enchantment disciplines (2 disciplines)
   - `enchanter-spells.ts` — Spell enchantment disciplines (3 disciplines)
   - `enchanter-special.ts` — Special enchantment disciplines (1 discipline)
   - `invoker.ts` — Invoker combat disciplines (2 disciplines)
   - `fabricator.ts` — Fabricator crafting/golem disciplines (5 disciplines)
2. Define a `DisciplineDefinition` (see `types/disciplines.ts`):
   - `statBonus.stat` must match a key consumed by `computeDisciplineEffects()`
   - Set `difficultyFactor` and `scalingFactor` to control growth rate
   - Add perks (`once`, `capped`, or `infinite`)
3. Re-export from `data/disciplines/index.ts` so it appears in `ALL_DISCIPLINES`
4. Add any new `statBonus.stat` keys to `discipline-effects.ts` → `computeDisciplineEffects()`

### Discipline Math (quick reference)
```
StatBonus     = baseValue × (XP / scalingFactor)^0.65
ManaDrainPerTick = drainBase × (1 + (XP / difficultyFactor)^0.4)
```
- XP accrues every tick the discipline is active and mana drain is met
- `concurrentLimit` starts at 1 and expands by 1 per 500 total XP (max 4)

### Adding Spells
1. `constants/spells-modules/` — Add to the appropriate category file
2. `data/enchantments/spell-effects/` — Add enchantment effect for the spell
3. Re-export from barrel files

### Store Architecture (Key Files)
- `stores/gameStore.ts` — Main coordinator, combines all stores, tick orchestration
- `stores/tick-pipeline.ts` → `buildTickContext()` / `applyTickWrites()` pattern
- `stores/combat-actions.ts` — Combat tick processing
- `stores/gameLoopActions.ts` — Climb/spire actions
- `stores/pipelines/[name].ts` — Individual pipeline phases

## Crafting System

### Enchanting: 3-Step Flow — Design → Prepare → Apply
- **Design:** Select effects for a named design. Time: 1h + 0.5h per stack (summed across all effects). Dual design slot with Enchant Mastery special.
- **Prepare:** Clears existing enchantments, costs `capacity × 10` raw mana, time: `2h + 1h per 50 capacity`. ONLY stage where explicit disenchanting occurs.
- **Apply:** Applies saved design to prepared equipment. Time: `2h + stacks` hours. Mana: `20 + 5×stacks` per hour.

### Equipment
- 8 slots: mainHand, offHand, head, body, hands, feet, accessory1, accessory2
- 43 equipment types across 8 categories (casters, swords, catalysts, head, body, hands, feet, accessories)
- Instance fields: `instanceId`, `typeId`, `name`, `enchantments[]`, `usedCapacity`, `totalCapacity`, `rarity`, `quality`
- Stacking cost: each additional stack costs 20% more

### Golemancy
- Component-based construction: Core + Frame + Mind Circuit + Enchantments. Players design custom golems from 4 cores, 7 frames, 4 mind circuits, and 8 enchantments.
- Golem slots: `floor(fabricatorLevel / 2)`, max 5 at level 10 (+2 from Golem Crafting discipline = max 7)
- Guardian Constructs require Guardian Core + Crystal-Steel Hybrid Frame + Guardian Circuit (Invoker 5 + Fabricator 5 + Guardian Pact)

### Guardian System
- Guardians on every 10th floor
- **Base (floors 10–80):** 7 base elements + Transference, static definitions with unique names
- **Tier 2 — Composite (floors 90–160):** 8 composite elements (Metal, Sand, Lightning, Frost, BlackFlame, RadiantFlames, Miasma, ShadowGlass)
- **Tier 3 — Exotic (floors 170–240):** 6 exotic elements (Crystal, Stellar, Void, Soul, Time, Plasma)
- **Tier 4+ — Procedural (floors 250+):** Dual-element → multi-element combination bosses cycling through element pairs, scaling indefinitely through 8 tiers
- HP formula: `floor(5000 × (floor/10) ^ (1.1 + floor/200))`
- Pact signing: costs raw mana + time, grants permanent boons

### Combat
- Cast-speed based: `castProgress += HOURS_PER_TICK × spellCastSpeed × attackSpeedMult`
- Elemental bonuses: super effective (1.5×), same element (1.25×), weak (0.75×), neutral (1.0×)
- Element opposites (bidirectional): fire↔water, air↔earth, light↔dark, frost↔fire
- Element counters (directional): lightning→water (lightning counters water), earth→lightning (earth counters lightning)
- Composite element counters: blackflame counters frost/water/light (and they counter blackflame); radiantflames counters frost/water/dark (and they counter radiantflames)
- Miasma counters air (and air counters miasma); Shadow glass counters light (and light counters shadow glass)
- All mana types double as spell elements
- Enemy modifiers (max 2 per enemy): Armored, Agile, Mage, Shield, Swarm
- Room types: Combat (default), Guardian (every 10th), Swarm (15%), Speed (10%), Puzzle (20% on every 7th floor)
- Floor HP: `100 + floor × 50 + floor^1.7` for non-guardian floors

### Time & Incursion
- `TICK_MS`: 200ms, `HOURS_PER_TICK`: 0.04, `MAX_DAY`: 30
- Incursion starts day 20
- Incursion strength: `min(0.95, (totalHours / maxHours) × 0.95)`

### Prestige (Insight)
- `baseInsight = floor(maxFloorReached × 15 + totalManaGathered / 500 + signedPacts.length × 150)`
- Multiplied by discipline and boon bonuses. No victory ×3 multiplier (victory condition not yet defined)
- 15 prestige upgrade types: manaWell, manaFlow, insightAmp, spireKey, temporalEcho, steadyHand, ancientKnowledge, elementalAttune, spellMemory, guardianPact, quickStart, elemStart, unlockedManaTypeCapacity, pactBinding, pactInterferenceMitigation
- Signed pacts do NOT persist through prestige (reset each loop)

### Starting State
- Attunement: Enchanter only (level 1)
- Mana: Only Transference unlocked
- Equipment: Basic Staff with Mana Bolt enchantment (mainHand), Civilian Shirt (body), Civilian Shoes (feet)
- 1 discipline slot, 1 concurrent discipline

## Banned

Lifesteal/healing, scroll crafting, ascension skills, LabTab, pause mechanics, familiar system, shields, mana types: `life`, `blood`, `wood`, `mental`, `force`

## File Limit

400 lines max (pre-commit hook enforces).

## Mana Types

**Base (7):** Fire 🔥 Water 💧 Air 🌬️ Earth ⛰️ Light ☀️ Dark 🌑 Death 💀
**Utility (1):** Transference 🔗
**Composite (8):** Fire+Earth=Metal ⚙️, Earth+Water=Sand ⏳, Fire+Air=Lightning ⚡, Air+Water=Frost ❄️, Dark+Fire=BlackFlame 🌋, Light+Fire=Radiant Flames 🌟, Air+Death=Miasma ☁️, Earth+Dark=Shadow Glass 🖤
**Exotic (6):** Sand+Sand+Light=Crystal 💎, Plasma+Light+Fire=Stellar ⭐, Dark+Dark+Death=Void 🕳️, Light+Dark+Transference=Soul 💫, Soul+Sand+Transference=Time ⏱️, Lightning+Fire+Transference=Plasma ⚡

**Total: 22 mana types** (7 base + 1 utility + 8 composite + 6 exotic)