nuzlocke-tracker/.beans/nuzlocke-tracker-25mh--genlocke-tracking.md

---
# nuzlocke-tracker-25mh
title: Genlocke tracking
status: todo
type: epic
priority: normal
created_at: 2026-02-08T12:17:19Z
updated_at: 2026-02-09T07:45:10Z
---

Track a **genlocke** — a series of linked nuzlocke runs, typically one per generation or region. The player picks one game per generation/region and surviving Pokemon carry over between legs.

## User Flow

### 1. Create Genlocke
The user starts a new genlocke and gives it a name.

### 2. Select Games (Legs)
The user picks which games to play, in order. The UI offers **preset templates** to speed this up, but the user can always customize:

- **True Genlocke** — One original game per generation (Red/Blue/Yellow → Gold/Silver/Crystal → Ruby/Sapphire/Emerald → ...). Uses the original releases only.
- **Normal Genlocke** — Uses the latest remake or enhanced version for each region (FireRed/LeafGreen → HeartGold/SoulSilver → Emerald → Platinum → ...). This is the most common format.
- **Custom** — The user picks any games in any order. No restrictions on which games or how many.

For the preset templates, the user still picks *which* game within each generation/region slot (e.g., FireRed vs LeafGreen for Gen 1). The template just determines which slots are shown. The user can add/remove/reorder legs after selecting a template.

Games are grouped by **region** (not release generation) for the purpose of presets, since that's how genlocke players think about it (e.g., FireRed is a "Kanto" leg, not a "Gen 3" leg).

### 3. Configure Rules
Two categories of rules are configured:

**Per-game nuzlocke rules** — The standard nuzlocke ruleset (first encounter only, permadeath, duplicates clause, level caps, etc.). These are set once and apply uniformly to all legs. Uses the existing `NuzlockeRules` interface.

**Genlocke-specific rules** — Overarching rules that govern how legs connect:
- **Keep HoF** (default) — Pokemon that enter the Hall of Fame at the end of a leg are transferred to the next leg as eggs (breed at level 1). This is the standard genlocke mechanic.
- **Retire HoF** — Pokemon that enter the Hall of Fame are retired. They (and their evolutionary families) become unavailable in future legs (added to a cumulative dupe list). This is also known as the "Gauntlet" rule. Increases difficulty by forcing new Pokemon each leg.
- Potentially more rules in the future (e.g., item carry-over restrictions, level scaling).

### 4. Sequential Run Progression
- When the genlocke is created, the **first leg** is automatically started as a new nuzlocke run.
- Each leg is a full nuzlocke run, tracked exactly like any standalone run (encounters, team, bosses, graveyard, etc.).
- When a leg is marked as **completed** (Hall of Fame), the next leg is started. A transfer step happens between legs where the user selects which surviving Pokemon to carry forward.
- When a leg is marked as **failed** (wipe), the genlocke itself is marked as failed (game over).
- The final leg's completion marks the entire genlocke as completed.

### 5. Genlocke Overview Page
A dedicated page showing:
- **Progress** — Which leg is active, which are completed, which are upcoming. Visual timeline or step indicator.
- **Configuration** — Selected games, rules, genlocke-specific rules.
- **Cumulative Stats** — Total encounters, total deaths, total HoF entries across all legs.
- **Lineage Tracking** — Show Pokemon that have carried over across multiple legs (their journey through the genlocke).
- **Cumulative Graveyard** — All deaths across all legs in one view.

## Data Model

### New entities:
- **`Genlocke`** — Top-level entity: name, status (active/completed/failed), genlocke rules (JSONB), created_at.
- **`GenlockeLeg`** — Join table linking a Genlocke to a NuzlockeRun: genlocke_id, run_id, leg_order. Defines the sequence.

### Changes to existing entities:
- **`NuzlockeRun`** — No schema changes needed. A run that's part of a genlocke is just a normal run that happens to be referenced by a GenlockeLeg. The genlocke-level rules are stored on the Genlocke, not duplicated per run.

### Transfer tracking:
- **`GenlockeTransfer`** — Records which Pokemon were carried between legs: from_leg_id, to_leg_id, encounter_id (the source encounter from the completed leg), to_encounter_id (the egg/gift encounter created in the next leg).

## Child Features (suggested breakdown)
1. **Genlocke creation wizard** — Multi-step UI: name → game selection (with presets) → rules → confirm
2. **Genlocke overview page** — Dashboard with progress, stats, configuration
3. **Leg progression** — Auto-start next leg when current completes, transfer step
4. **Transfer UI** — Select surviving Pokemon to carry forward between legs
5. **Lineage tracking** — Show a Pokemon's journey across legs
6. **Cumulative graveyard** — Deaths across all legs in one view
7. **Gauntlet/Retire HoF rule** — Enforce the "retire" mechanic with cumulative dupe list

## Success Criteria
- [x] A user can create a new genlocke via a multi-step wizard (name, game selection with presets, rules)
- [x] Games can be selected using True Genlocke, Normal Genlocke, or Custom presets, grouped by region
- [x] Nuzlocke rules are configured once and applied uniformly to all legs
- [x] Genlocke-specific rules (Keep HoF / Retire HoF) can be selected
- [x] The first leg starts automatically upon genlocke creation
- [ ] Each leg is a full nuzlocke run, tracked identically to standalone runs
- [ ] Completing a leg triggers a transfer step where surviving Pokemon can be carried forward
- [x] Failing a leg marks the entire genlocke as failed
- [x] Completing the final leg marks the genlocke as completed
- [ ] A genlocke overview page shows progress, configuration, cumulative stats, lineage, and graveyard
- [ ] Transferred Pokemon appear as eggs (base form, level 1) in the next leg
- [ ] Pokemon lineage is trackable across multiple legs
- [ ] A cumulative graveyard shows all deaths across the entire genlocke
- [ ] The Retire HoF / Gauntlet rule correctly retires HoF Pokemon and adds their families to the dupe list