# Line ID Authoring Guide

**Decision:** D-084 (dual-namespace line ID scheme)
**Resolves:** Q-028 (collision-resistant IDs for auto-generated NPCs)
**Ticket:** #544

---

## The Short Version

- **Role pool lines:** Use `{role-slug}_d_{###}` — e.g., `dock-worker_d_001`. These lines are shared by all NPCs with that role. This is the default for all auto-generated NPC content.
- **Named NPC lines:** Use `{npc-slug}_d_{###}` — e.g., `kael-davan_d_001`. Unchanged from current practice.
- **Instance-specific lines (rare):** Use `{role-slug}-{counter}_d_{###}` — e.g., `dock-worker-07_d_001`. Only needed when a specific generated NPC needs content different from the role pool.

---

## How Line IDs Work

A line ID identifies **content**, not speaker. The speaker is identified by their `StableId` in the history log. So `dock-worker_d_001` being said by 40 different dock workers is correct: the log records `(StableId: 12, dock-worker_d_001)`, `(StableId: 37, dock-worker_d_001)`, etc. No collision.

This means the role pool approach already handles most cases — the "collision problem" is mainly a concern for the rare case where you want a specific generated NPC to say something *different* from others of the same role.

---

## Namespace Reference

### Named NPC lines (Tier 1 and Tier 2 authored NPCs)

```
Format:  {npc-slug}_{content-type}_{###}
Example: kael-davan_d_001     (Kael's dialogue line 1)
         sera-venn_d_015      (Sera's dialogue line 15)
         pc-smuggler_m_s_001  (Smuggler monologue line 1)
```

File location: One file per NPC (e.g., `dialogue/maintenance-corridors/kael-davan.yaml`)

Numbering: Sequential within the file. Gaps are acceptable (deleted lines leave permanent gaps). Never reuse a number.

---

### Role pool lines (auto-generated NPCs, Tier 3 flat, Tier 2 mundane)

```
Format:  {role-slug}_{content-type}_{###}
Example: dock-worker_d_001    (any dock worker, dialogue line 1)
         bar-regular_d_008    (any bar regular, dialogue line 8)
         transit-worker_d_003 (any transit worker, dialogue line 3)
```

File location: One file per role-at-location (e.g., `dialogue/the-terminal/dock-worker.yaml`)

These lines are shared by **all instances** of the role. Write them to suit any dock worker, not a specific one.

---

### Instance-specific lines (opt-in, rare)

Use only when the generation system has flagged a specific NPC as needing content that differs from the role pool. Examples: a generated dock worker who is also a triangle member with a specific tell; a generated bar regular who witnessed a specific event.

```
Format:  {role-slug}-{zero-padded counter}_{content-type}_{###}
Example: dock-worker-07_d_001  (instance 7 of dock-worker role, line 1)
         bar-regular-02_d_005  (instance 2 of bar-regular role, line 5)
```

The counter (01, 02, ... N) is assigned by the generation system in world-seed-deterministic order. The NPC's generated profile file will tell you which counter to use.

File location: Same directory as the role pool file, separate file with instance slug as name (e.g., `dialogue/the-terminal/dock-worker-07.yaml`)

---

## Quick Decision Guide

| Situation | ID format to use |
|-----------|------------------|
| Named authored NPC (Kael, Sera, Voss...) | `{npc-slug}_d_{###}` |
| Lines any dock worker can say | `dock-worker_d_{###}` |
| Lines any bar regular can say | `bar-regular_d_{###}` |
| Generated NPC with specific triangle role | `{role-slug}-{counter}_d_{###}` |
| Generated NPC who's just background | `{role-slug}_d_{###}` — no instance ID needed |

---

## Schema Compatibility

The existing ID regex `^[a-z][a-z0-9-]*_[dme]_\d{3}$` accepts all three formats. No schema change is required. The content validator (`make validate-content`) checks for duplicate IDs across all files in a district.

---

## Numbering Rules

1. Start at `001`, increment by 1 for each new line.
2. Never reuse a number, even if a line is deleted. Gaps are fine.
3. Lines within a single file have a contiguous prefix — `dock-worker_d_001` through `dock-worker_d_042`, etc.
4. Cross-file: `kael-davan.yaml` at the terminal and `kael-davan.yaml` at maintenance corridors both use the `kael-davan_d_###` namespace. Continue numbering from where the other file left off (check the existing files first, use a fresh sequence if the NPC is new to a location).

---

*D-084 — authored by Gestalt, Sprint 18*