# Mana Loop — Agent Guide

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

## 🔑 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. `get_repo_summary` → resume in-progress or pick top todo
4. `update_issue_status` → `ai:in-progress`
5. Work, log with `add_comment`, then `update_issue_status` → `ai:done`

## Labels

`ai:todo` | `ai:in-progress` | `ai:review` | `ai:blocked` | `ai: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/Playwright, Bun
- **Active stores:** `src/lib/game/stores/{game,mana,combat,prestige,discipline,ui}Store.ts`
- **Legacy (migrating):** `src/lib/game/store/` and `store-modules/`
- **Crafting:** 3-step flow — Design → Prepare → Apply via `crafting-actions/`
- **Disciplines:** `data/disciplines/` + `stores/discipline-slice.ts` + `utils/discipline-math.ts`
- **Effects:** All stat mods through `getUnifiedEffects()` — discipline bonuses enter via `computeDisciplineEffects()`

### Adding Effects
1. `data/enchantment-effects.ts`
2. `effects.ts` → `computeEquipmentEffects()`
3. Access via `getUnifiedEffects(state)`

### Adding Disciplines
1. Choose the correct data file under `data/disciplines/`:
   - `base.ts` — available to all attunements
   - `enchanter.ts` — requires Enchanter attunement
   - `invoker.ts` — requires Invoker attunement
   - `fabricator.ts` — requires Fabricator attunement
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 +3)

### Adding Spells
1. `constants/spells.ts`
2. `data/enchantment-effects.ts`
3. `EFFECT_RESEARCH_MAPPING`

## Banned

Lifesteal/healing, scroll crafting, ascension skills, LabTab, pause, 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 🔗  
**Compound (3):** Fire+Earth=Metal, Earth+Water=Sand, Fire+Air=Lightning  
**Exotic (3):** Sand+Sand+Light=Crystal, Fire+Fire+Light=Stellar, Dark+Dark+Death=Void