---
# nuzlocke-tracker-5tac
title: Enable naming generator for Genlockes
status: completed
type: task
priority: normal
created_at: 2026-02-11T21:14:21Z
updated_at: 2026-02-14T08:52:16Z
---

## Overview

Genlockes are multiple nuzlocke runs played back-to-back. Currently, naming scheme selection is only available per-run, meaning genlocke runs don't get naming schemes at all (they're created automatically during genlocke creation and leg advancement). This task adds genlocke-level naming scheme selection and lineage-aware name suggestions.

## Key Behaviors

### 1. Genlocke-Level Naming Scheme
- When creating a genlocke, the user selects a naming scheme (same categories as standalone runs)
- This scheme is stored on the `Genlocke` model and automatically applied to every leg's `NuzlockeRun`
- Both the initial run (created in `create_genlocke`) and subsequent runs (created in `advance_leg`) inherit the genlocke's naming scheme

### 2. Name Suggestions (Current Leg Only)
- Duplicate name checking stays scoped to the current run (already the case)
- Transferred pokemon carry their nicknames forward, so they naturally occupy names in the current run's used-name set

### 3. Lineage-Aware Name Suggestions (Roman Numerals)
- When catching a pokemon in a genlocke leg (leg 2+), the system checks if any pokemon from the same **evolution family** was caught in a previous leg
- If so, the original nickname is suggested with a roman numeral suffix (e.g., "Heracles II", "Heracles III")
- The numeral represents the Nth distinct leg where this evolution family was originally caught (not transferred)
  - Leg 1: Magikarp → "Heracles" (no numeral, first appearance)
  - Leg 2: Magikarp or Gyarados caught → suggest "Heracles II"
  - Leg 3: Magikarp caught again → suggest "Heracles III"
- Transferred pokemon don't count as new appearances (they're the same individual)
- The "base name" is taken from the first original encounter of that family across all legs
- The lineage suggestion appears as a **priority suggestion** alongside regular naming scheme suggestions
- The user can always choose a different name

### 4. How the API Changes
- `GET /runs/{run_id}/name-suggestions` gains an optional `pokemon_id` query param
- When `pokemon_id` is provided AND the run belongs to a genlocke:
  - Determine the pokemon's evolution family
  - Query previous legs' encounters (excluding transfer-target encounters) for matching family members
  - If matches found: compute the roman numeral and prepend "{base_name} {numeral}" to the suggestions list
- Regular naming scheme suggestions are returned as before

## Checklist

### Backend
- [x] Add `naming_scheme` column to `genlockes` table (Alembic migration)
- [x] Update `Genlocke` model with `naming_scheme: Mapped[str | None]`
- [x] Update `GenlockeCreate` schema to accept optional `naming_scheme: str | None`
- [x] Update `GenlockeResponse` and `GenlockeDetailResponse` to include `naming_scheme`
- [x] Update `create_genlocke` endpoint: pass `naming_scheme` to the first leg's `NuzlockeRun`
- [x] Update `advance_leg` endpoint: pass the genlocke's `naming_scheme` to the new leg's `NuzlockeRun`
- [x] Add roman numeral helper function (e.g., in `services/naming.py`)
- [x] Update `get_name_suggestions` endpoint to accept optional `pokemon_id` param
- [x] Implement lineage lookup: when in genlocke context with `pokemon_id`, query prior legs for evolution family matches (excluding transfers) and compute suggestion with roman numeral
- [ ] Add tests for lineage-aware name suggestions

### Frontend
- [x] Update `CreateGenlockeInput` type to include `namingScheme?: string | null`
- [x] Add naming scheme selector to genlocke creation wizard (in the Rules step or as a new step)
- [x] Update `GenlockeResponse` / `GenlockeDetailResponse` types to include `namingScheme`
- [x] Update `EncounterModal` to pass selected `pokemonId` to name suggestions API when in genlocke context
- [x] Update `getNameSuggestions` API client to accept optional `pokemonId` param
- [x] Display lineage suggestion prominently in the suggestions UI (e.g., first pill with distinct styling)