# Asset Taxonomy & Naming Convention

**Code source of truth:** `lib/taxonomy.py`
**Pipeline slot mapping:** see table below + `SLOT_MAP` in taxonomy.py

## The 6 Asset Types

| Type | Slug | Purpose | Visual Spec |
|------|------|---------|-------------|
| **Identity** | `identity` | WHO the character is. Model consistency anchor. | Neutral/white BG. Clean lighting. Full or 3/4 body. |
| **Turnaround** | `turn` | Multi-angle spatial understanding. | Neutral BG. Specific camera angle. Consistent lighting. |
| **Expression** | `expr` | Facial/emotional reference for performance beats. | Tight face/upper body framing. Clear emotion. |
| **Location** | `loc` | Environment reference, NO characters. | Empty environment. Architecture, lighting, texture. |
| **Prop** | `prop` | Isolated object reference. | Neutral BG or simple context. Clear form/detail. |
| **Scene** | `scene` | Character IN environment. Mood/vibe/LoRA-ready. | Full composition. Cinematic lighting. |

## Naming Convention

**Format:** `{subject}_{type}_{variant}_v{NN}.{ext}`

| Segment | Rules | Examples |
|---------|-------|---------|
| `subject` | Lowercase alphanumeric + hyphens. Must start with letter. | `torch`, `int-lower-decks`, `plasma-cutter` |
| `type` | One of 6 enum values (see above). | `identity`, `turn`, `loc` |
| `variant` | Lowercase alphanumeric + hyphens. Descriptive. | `hero`, `front`, `wide`, `pipe-detail` |
| `version` | Zero-padded 2-digit integer. | `v01`, `v02`, `v99` |
| `ext` | `png`, `jpeg`, `webp`. `.jpg` normalized to `.jpeg` on ingest. | `png`, `jpeg` |

**NO underscores within segments.** Underscores are segment delimiters ONLY. Use hyphens for multi-word names.

### Examples

```
# Characters - identity
torch_identity_hero_v01.png
torch_identity_hero_v02.png

# Characters - turnarounds
torch_turn_front_v01.png
torch_turn_profile_v01.png
torch_turn_three-quarter_v01.png
torch_turn_back_v01.png

# Characters - scene (LoRA-ready)
torch_scene_lower-decks_v01.jpeg

# Characters - expression
torch_expr_anguish_v01.png
torch_expr_determined_v01.png

# Locations
int-lower-decks_loc_wide_v01.png
int-lower-decks_loc_pipe-detail_v03.png

# Props
plasma-cutter_prop_hero_v01.png
```

### Regex

```python
^(?P<subject>[a-z][a-z0-9]*(?:-[a-z0-9]+)*)
_(?P<type>identity|turn|expr|loc|prop|scene)
_(?P<variant>[a-z][a-z0-9]*(?:-[a-z0-9]+)*)
_v(?P<version>[0-9]{2})
\.(?P<ext>png|jpeg|webp)$
```

## Pipeline Slot Mapping

Ordered by Gemini recency bias (first = least attention, last = most):

| Asset Type | Pipeline Slot | Weight Range | Order | Auto-Resolved? |
|------------|--------------|-------------|-------|----------------|
| `loc` | environment | 1-2 | 1 (first) | Yes (moodboard) |
| `prop` | prop | 3-4 | 2 | Yes (if in shot) |
| `expr` | expression | 6-7 | 3 | Yes (if emotion specified) |
| `turn` | structure | 4-5 | 4 | Yes (based on camera angle) |
| `identity` | subject | 8-10 | 5 (last) | Yes (always included) |
| `scene` | vibe | 2-3 | 6 (anchor, if used) | **NO** (manual opt-in only) |

## "Hero" Is Dead (As a Type)

The word "hero" is retired as an **asset type**. It survives as a **variant** meaning "the primary/canonical one."

- Old: `hero.jpeg` (ambiguous - identity? scene comp? LoRA?)
- New: `torch_identity_hero_v01.png` (unambiguous - identity reference, hero variant)

## LoRA Readiness

`scene` type assets are inherently LoRA-ready. When open-source models support LoRA training:
1. Query all `scene` type assets from the taxonomy
2. Auto-generate caption .txt files from shot manifest prompt data
3. Export to training directory structure

Zero migration required - the naming convention already captures everything needed.