tarot/docs/REGISTRY_MAPPING.md

## Registry System: Position-Based Card Details

### Overview
The registry uses a **position-based lookup system** that maps card positions (1-78) to interpretive data stored in `CardDetailsRegistry`. This system is independent of card names, allowing the same registry entries to work across different deck variants.

### Design Principle
**Card position is the permanent identifier**, not the card name. This means:
- Card #44 is always "Magus position" in the deck order
- If you rename card #44 to "Magus", "Magician", "Mage", or any other variant, it still maps to the same registry entry
- Different deck variants can have completely different names but use the same spiritual/interpretive data

### File Organization
Your deck files follow this numbering (which drives card position):
- **1-14**: Cups (Ace, Ten, 2-9, Knight, Prince, Princess, Queen)
- **15-28**: Pentacles/Disks (same structure)
- **29-42**: Swords (same structure)
- **43-64**: Major Arcana (43=Fool, 44=Magus, ..., 64=Universe)
- **65-78**: Wands (same structure)

Example: `44_Magus.webp` → Card at position 44 → Magus name → Registry position 44 → Details for position 44

### Position-Based Lookup Process

```
Card created with number (position)
    ↓
card.number = 44
    ↓
load_into_card(card)
    ↓
get_by_position(44)
    ↓
Position 44 maps to registry key "I" (1st trump after Fool)
    ↓
registry.get("I") → Returns Magician/Magus details
    ↓
Details loaded into card object (independent of card.name)
```

### Position Mapping

**Minor Arcana Positions:**
- 1-14: Cups - Maps to "Ace of Cups" through "Queen of Cups"
- 15-28: Pentacles - Maps to "Ace of Pentacles" through "Queen of Pentacles"
- 29-42: Swords - Maps to "Ace of Swords" through "Queen of Swords"
- 65-78: Wands - Maps to "Ace of Wands" through "Queen of Wands"

**Major Arcana Positions:**
- 43 → "o" (Roman for 0/Fool)
- 44 → "I" (Roman for 1/Magus)
- 45 → "II" (Roman for 2)
- ...continuing through...
- 64 → "XXI" (Roman for 21/Universe)

### Implementation

```python
def _build_position_map(self) -> Dict[int, str]:
    """
    Maps card position (1-78) to registry key:
    - Minor Arcana: position → card name ("Ace of Cups", etc.)
    - Major Arcana: position → Roman numeral ("o", "I", "II", etc.)
    """
    # Builds complete 1-78 mapping
    return position_map

def get_by_position(self, position: int) -> Optional[Dict[str, Any]]:
    """Get details for a card by its position (1-78)."""
    registry_key = self._position_map.get(position)
    return self._details.get(registry_key)

def load_into_card(self, card: 'Card') -> bool:
    """Load card details using position-based lookup."""
    details = self.get_by_position(card.number)
    # Populate card with: explanation, interpretation, keywords, etc.
```

### Why Position-Based?

1. **Deck Variant Independence**: Different decks can use completely different names
2. **Stable Identity**: Card position never changes across variants
3. **Scalable**: Easily support new deck variants by just changing card names
4. **Future Proof**: New interpretations can be added keyed to positions, not names

### Example Flow

File: `44_Magus.webp`
↓
Card object: number=44, name="Magus", arcana="Major"
↓
`load_into_card(card)` called
↓
`get_by_position(44)` returns registry key "I"
↓
Registry lookup: `registry.get("I")`
↓
Populates card with Magician/Magus interpretation:
- keywords: ["manifestation", "resourcefulness", ...]
- interpretation: "Communication; Conscious Will; ..."
- guidance: "Focus your energy and intention..."

### Key Point

Even if you rename card #44 to something completely different, it will still load the same interpretation because the lookup is based on **position (44)**, not **name ("Magus")**.

↓
Registry lookup: `registry.get("o")`
↓
Populates card with: explanation, interpretation, keywords, etc.