nuzlocke-tracker/.beans/nuzlocke-tracker-5tac--enable-naming-generator-for-genlockes.md

title, status, type, priority, created_at, updated_at

title	status	type	priority	created_at	updated_at
Enable naming generator for Genlockes	in-progress	task	normal	2026-02-11T21:14:21Z	2026-02-14T08:37:11Z

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

• Add naming_scheme column to genlockes table (Alembic migration)
• Update Genlocke model with naming_scheme: Mapped[str | None]
• Update GenlockeCreate schema to accept optional naming_scheme: str | None
• Update GenlockeResponse and GenlockeDetailResponse to include naming_scheme
• Update create_genlocke endpoint: pass naming_scheme to the first leg's NuzlockeRun
• Update advance_leg endpoint: pass the genlocke's naming_scheme to the new leg's NuzlockeRun
• Add roman numeral helper function (e.g., in services/naming.py)
• Update get_name_suggestions endpoint to accept optional pokemon_id param
• 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

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