jpmschweitzer/settled-reach
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(design): add dual lens guide, MIRROR spec, interaction verbs, wow moments checklist, NPC pattern mapping

Browse Source 
Wave 2 of Sprint 3 "Know":
- #261: Dual Lens Authoring Guide (7 chapters, smuggler/detective voice registers)
- #380: THE MIRROR pattern spec with Naia Tamm reference implementation
- #396: Pattern/Motivation sections added to all 18 NPC wiki pages + index
- #400: v0.1 wow moments checklist mapping 6 D-039 moments to deliverables
- #402: Interaction verb spec (7 verbs, priority resolution, architecture)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
jpmschweitzer
2026-02-12 17:55:57 +01:00
co-authored by Claude Opus 4.6
parent 5fdb7f9c53
commit 58c7d882bc
23 changed files with 2247 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design/dual-lens-authoring-guide.md
+750
View File
@@ -0,0 +1,750 @@
# Dual Lens Authoring Guide
**v0.1 Content Design Document** | Blocks: 11 downstream tickets | Status: Draft
**Author:** Mellanie (Copywriter) + Paula (Narrative & Political Depth)
**Date:** 2026-02-12
---
## Document Purpose
This guide defines how content authors write for two playable characters experiencing the same world through different perspectives. Every dialogue line, monologue line, and NPC profile must work for BOTH the smuggler AND the detective. Same world. Two lenses. Zero shared monologue lines. Maximum narrative divergence from minimal content duplication.
**Critical Dependencies:**
- D-027: Vertical slice — smuggler + detective two-character proof
- D-028: Dialogue architecture — tagged line pools with four relational layers
- D-032: Separate monologue pools per character (hard partition, non-negotiable)
- D-034: THE FRIEND — production-level NPC pattern
- D-035: Converged tag taxonomy for dialogue and monologue line pools
---
## Chapter 1: Core Identity + Emotional Starting State
### Who Is The Smuggler?
**Occupation:** Logistics worker, Sova Transit District Freight Terminal ("The Terminal")
**Ring Position:** Mid-level operator. Handles physical cargo routing, knows the schedule windows, manages dock-side coordination.
**Time in Ring:** ~2 years. Comfortable with the work. Good at it.
**Lattice Tier:** Baseline (standard civilian-grade, no augmentation)
**What They Know At Session Start:**
- The ring exists. Who's in it: Nils (coordinator), Kael (closest colleague, ring member), Voss (shift supervisor, takes a cut), Renn (courier), and 2-3 others.
- The routes: freight bay → service corridor → temp storage → bar back room.
- The cargo: unlicensed lattice components, medical-grade neural replacements diverted from Syndic supply chains. They don't look too closely at the sealed containers.
- The schedule: shift transitions create 20-minute oversight gaps. The operation runs during these windows.
- The stakes: if caught, it's a Commission offense. Years in detention. But the money helps, the team is solid, and it's felt manageable for two years.
**What They Don't Know:**
- The detective is investigating (unless playing detective path and the smuggler has been flagged).
- Kael is trying to exit the ring. Meeting unknown contacts. Lying to the smuggler.
- Sera (Commission field tech) has flagged manifest discrepancies and is sitting on unreported evidence.
- The full upstream supply chain (knows cargo comes from off-station contact Sabel, doesn't know Syndic connections).
- How much Naia (Kael's partner) suspects. How much danger the ring is actually in.
**Emotional Baseline:**
- **Comfortable-tense.** Not happy, not miserable. The smuggler is managing a life with two faces: legitimate dock worker (public) and ring operator (hidden). The cognitive load is constant but bearable. The money eases the financial pressure that makes station life tight for most workers. The team feels like family — shared risk creates trust.
- **Loyal to people, not institutions.** First-name basis with everyone. Thinks relationally: Kael is "my shift partner," not "dock worker Davan." Voss is "tense today," not "the shift supervisor is agitated." Institutions (Commission, Concord, Syndic) are distant, abstract, often adversarial.
- **Operational thinking mode.** Time-aware, route-aware, schedule-aware. Worries about exposure: "Is Torek's spending too visible?" "Did Maret notice that manifest discrepancy?" "Is the detective going to connect Kael to the irregularities?"
- **Protectiveness over the team.** Would cover for Kael even at personal cost. Would warn Voss if something looked wrong. The ring isn't just work — it's the people the smuggler eats lunch with, drinks with, trusts.
---
### Who Is The Detective?
**Occupation:** Commission investigator, assigned to Sova Transit District for manifest irregularity investigation
**Assignment Duration:** New arrival. Session start is early in the investigation (first week).
**Lattice Tier:** Standard professional (Commission-grade diagnostic tools, analytical overlays, not investigative-tier augmentation)
**What They Know At Session Start:**
- There are manifest discrepancies tied to Sova Transit District freight operations. Containers logged but not reconciled with incoming manifests. Pattern suggests smuggling.
- Names from case files: Voss (shift supervisor), Maret (freight scheduler), Drin (dock inspector). Persons of interest, not confirmed suspects.
- Sova Transit District social geography: The Terminal (logistics hub), The Last Shift (bar, social nexus), maintenance corridors (off-books access routes).
- Institutional context: The previous Commission liaison rotated out 3 months ago. Current Commission presence is minimal (Sera Venn, field tech, not an investigator).
- Sera Venn is a pre-existing contact. Same institutional background, transferred to Sova a year ago. Reliable. The detective's one friendly face in the district.
**What They Don't Know:**
- Who the ring members are (Nils, Kael, Renn, etc. — names without context).
- The smuggler's identity. If the smuggler is in the ring, the detective doesn't know yet.
- Kael is trying to exit the ring. Sera is sitting on unreported evidence. Naia is worried about Kael and has confided in Sera.
- The social web connecting everyone. Who's loyal to whom. Who's protecting whom. Who's compromised and how.
- How embedded the ring is in the district's economic immune system. The detective reads it as criminal enterprise. Doesn't yet understand it as community survival mechanism.
**Emotional Baseline:**
- **Professional-cautious.** The detective is trained to observe, analyze, withhold judgment until evidence accumulates. But they're also human — isolation in an unfamiliar community, reliance on Sera for social grounding, awareness that non-cooperation is the district default.
- **Analytical habit.** Counts things. Tracks frequencies. Flags inconsistencies. Self-directs: "filing it," "noted," "coincidence?" Internal bookkeeping runs in background. The institutional training doesn't turn off.
- **Institutional frame.** Thinks in terms of evidence, patterns, leverage. Surnames before first names for targets. "Davan, K." not "Kael." The shift from surname to first-name IS a relationship marker.
- **Moral position.** The detective believes in the work. Smuggling isn't victimless — unlicensed lattice components can cause neural degradation, medical-grade replacements diverted from Syndic supply chains mean someone else doesn't get the replacement they need. The ring is breaking the law. The investigation is justified. But the detective is also starting to see the grey: Kael isn't a cartel boss, he's a dock worker who said yes once and kept saying yes. Complexity accumulates.
---
### Starting State Comparison
| Dimension | Smuggler | Detective |
|-----------|----------|-----------|
| **Knowledge of the ring** | Insider. Knows who, what, when, where. Operational detail. | Suspects. Has data anomalies, no confirmed names. Investigative frame. |
| **Relationship to NPCs** | Personal. First-name basis. History, trust, loyalty. | Clinical. Surname-first. Categorizes by role and behavior. |
| **Emotional orientation** | Protective. Worries about people. "Is Kael okay?" | Analytical. Worries about patterns. "Why is Kael nervous?" |
| **Lattice capability** | Baseline. No enhanced perception, no analytical overlays. | Professional. Diagnostic access, pattern recognition tools. |
| **Social position** | Insider. Belongs. Everyone knows the smuggler. | Outsider. Institutional authority resented by the community. |
| **Moral framing** | Pragmatic complicity. "We're careful. We take care of our own." | Institutional clarity. "This is a crime. There are victims." |
| **What threatens them** | Exposure (being caught, losing the team). | Failure (case goes cold, ring stays hidden). |
---
## Chapter 2: The Dual-Lens Rule
### The Core Test
Every content piece — dialogue line, monologue line, NPC profile axis — must work for BOTH characters. Ask:
1. **Does this line make sense if the smuggler experiences it?**
2. **Does this line make sense if the detective experiences it?**
3. **Does this line reveal something different to each character?**
4. **Is the access tier correct for both characters?**
5. **Does this line advance at least one character's emotional arc?**
If the answer to 1 or 2 is "no," the line is broken. If the answer to 3 is "no," the line isn't dual-lens — it's just generic.
---
### Three Types of Dual-Lens Difference
**Type 1: Access Difference**
The smuggler hears a line the detective doesn't (or vice versa) because of `access` tier filtering.
*Example:*
```yaml
- id: terminal_d_044
role: dock_worker
text: "Container 4471 sat in temp storage overnight. Scheduling backed up again."
access: [public, peer]
trust: surface
situation: [shift_start]
dual_lens:
smuggler: "Operational context — part of the ring pipeline. 'Backed up' is cover language."
detective: "Anomaly — overnight exceeds standard procedure. Flag for investigation."
```
Both characters can hear this line (`public` + `peer` both accessible). But the smuggler ALSO hears ring-specific operational dialogue that the detective never accesses:
```yaml
- id: terminal_d_045
role: dock_worker
text: "4471's routed for transfer at 14:30. Voss kept the window clear."
access: [insider]
trust: real
situation: [shift_transition]
dual_lens:
smuggler: "Confirmation — the route is active, Voss is cooperating."
detective: "Never hears this line. Doesn't have insider access."
```
**Type 2: Interpretation Difference**
Both characters hear the same NPC dialogue, but their monologue reactions interpret it differently.
*Shared dialogue line:*
```yaml
- id: bar_d_033
role: bartender
text: "Sera left early. Headache, she said."
access: [public]
trust: surface
```
*Smuggler monologue reaction:*
```yaml
- id: bar_m_051
character: smuggler
trigger: post_conversation
text: "Sera's gone. Good — one less Commission presence in the room."
mood: [relieved]
```
*Detective monologue reaction:*
```yaml
- id: bar_m_052
character: detective
trigger: post_conversation
prerequisite:
known_attributes:
subject: sera_venn
key: behavior_flags
value_contains: avoidance_pattern
text: "Second time Sera's left when Torek arrived. Coincidence?"
mood: [suspicious]
```
Same dialogue. Smuggler reads it as relief (less oversight). Detective reads it as a behavioral tell (avoidance pattern forming).
**Type 3: Emotional Weight Difference**
The relationship history creates different emotional stakes for the same observation.
*Observation trigger:* Kael checking his lattice for the third time in ten minutes.
*Smuggler monologue:*
```yaml
- id: terminal_m_011
character: smuggler
trigger: observe_anomaly
prerequisite:
relationship_state: Friendly
subject: kael_davan
text: "Kael keeps checking his lattice. Waiting for a message? Not like him to be jumpy."
mood: [concerned]
topic: [colleague]
```
*Detective monologue:*
```yaml
- id: terminal_m_042
character: detective
trigger: observe_anomaly
prerequisite:
relationship_state: Known
subject: kael_davan
text: "Dock worker Davan — lattice activity spiked. Expecting a message? Or checking for surveillance?"
mood: [analytical]
topic: [investigation]
```
Same behavior. Smuggler worries about a friend ("Not like him"). Detective analyzes a subject ("Dock worker Davan"). Emotional weight is asymmetric.
---
### Tag Implications
The dual-lens rule is enforced through the tag taxonomy (D-035). Here's how tags create different content surfaces from the same pool:
**`access` Tag — Hard Filter (D-028 Layer 1)**
| Access Tier | Who Gets It | Smuggler Example | Detective Example |
|-------------|-------------|------------------|-------------------|
| `public` | Everyone | Bar greeting, shift small talk | Commission procedural questions |
| `peer` | Known or Friendly relationship | Coworker gossip, shift complaints | Institutional background sharing (Sera to detective) |
| `insider` | Friendly relationship only | Ring operational talk, close confidences | Never unlocked for ring NPCs (detective is outsider) |
| `authority` | Detective only, works at Unknown/Known/PersonOfInterest | Institutional leverage questions | Smuggler never has authority access |
| `hostile` | Hostile relationship only | Threats, final warnings | Post-cover-blown confrontation |
**Critical rule:** When Kael transitions from Friendly to PersonOfInterest (THE FRIEND contradiction), `insider` and `peer` lines LOCK OUT. The smuggler still sees Kael, still interacts with Kael, but the warm operational dialogue disappears. That absence IS the emotional payload.
**`trust` Tag — Hard Filter (D-028 Layer 3)**
Within each access tier, `trust` further filters content:
| Trust Level | What It Gates |
|-------------|--------------|
| `surface` | Safe topics, social norms, what anyone would say |
| `real` | Honest opinions, unguarded speech, actual feelings |
| `secret` | Dangerous knowledge, confessions, things that create leverage |
A line tagged `access: [insider], trust: secret` is the deepest content — only available to the smuggler, only when Kael is Friendly, only when trust has been earned through repeated interaction.
**`character` Tag — Hard Partition (D-032)**
Monologue pools are completely separate. The smuggler's monologue pool lives in `monologue-smuggler.yaml`. The detective's pool lives in `monologue-detective.yaml`. **No shared lines.** This is non-negotiable.
Same trigger, different pool. That's how mirror moments work without either pool knowing about the other.
---
### Authoring Workflow
When writing a line:
1. **Write the line.** Concrete, in the speaker's voice.
2. **Check both readings.** Document the dual-lens split in the `dual_lens` field:
```yaml
dual_lens:
smuggler: "How the smuggler interprets this."
detective: "How the detective interprets this."
```
3. **Verify neither reading breaks.** If the line only works for one character, use a different `access` tier or rely on character-specific monologue to recontextualize.
4. **Tag correctly.** The `access`, `trust`, `situation`, `mood`, and `topic` tags must express the dual-lens difference mechanically.
---
## Chapter 3: Access Tier Mapping
### Per-NPC Access Mapping
How each character relates to key NPCs at session start:
| NPC | Smuggler Access | Detective Access | Shift Path (Smuggler) | Shift Path (Detective) |
|-----|----------------|------------------|---------------------|----------------------|
| **Kael Davan (THE FRIEND)** | `insider`, `peer` | `public` → `authority` (if flagged) | `insider` → locked out (post-contradiction, PersonOfInterest) | `public` → `authority` (investigation progresses) |
| **Sera Venn (THE FRIEND)** | `public` (Commission, wary) | `peer` → `authority` (post-contradiction) | No shift (smuggler doesn't develop relationship) | `peer` → `authority` (trust breaks, PersonOfInterest) |
| **Voss (shift supervisor)** | `insider` (colleague, knows smuggler is ring) | `authority` | `insider` → `hostile` (if cover blown) | `authority` → `peer` (if detective earns trust) |
| **Lera Sessik (bar owner)** | `insider` (bar regular, ring-aware) | `public` → `peer` (repeat visits) | No major shift | `public` → `peer` (regular status, 3-4 visits) |
| **Naia Tamm (Kael's partner)** | `peer` (through Kael) | `public` → `peer` (through Sera) | `peer` → `hostile` (if Naia learns truth about ring) | `public` → `peer` (Sera introduction) |
| **Torek Lintar (bar regular)** | `insider` or `peer` (depends on whether smuggler knows Torek's ring connection) | `public` | No shift | `public` → `authority` (if financial tells flagged) |
| **Maret Korr (freight scheduler)** | `insider` (hub colleague) | `authority` | No major shift | `authority` → `peer` (if Maret cooperates) |
| **Drin Rosta (dock inspector)** | `insider` (hub colleague, smuggler knows Drin is compromised) | `authority` | `insider` → `hostile` (if Drin turns informant) | `authority` (detective can pressure via gambling debt) |
---
### Access Tier Shift Paths (Per Social Site)
**The Terminal (Logistics Hub)**
| Character | Starting Tier | Likely Shift | Trigger | Content Requirement |
|-----------|--------------|--------------|---------|---------------------|
| Smuggler | `insider` + `peer` | `insider` → `hostile` | Cover blown — seen with detective, ring member reports suspicion | Dialogue lines for "former colleague now enemy" tone. Monologue lines for paranoia, betrayal. |
| Detective | `authority` | `authority` → `peer` | Earns trust by keeping a minor infraction quiet, helping with a non-smuggling problem | Dialogue lines for "institutional authority softening to personal rapport." Monologue shift from clinical to sympathetic. |
**The Last Shift (Bar)**
| Character | Starting Tier | Likely Shift | Trigger | Content Requirement |
|-----------|--------------|--------------|---------|---------------------|
| Smuggler | `insider` (regular) | `insider` → `hostile` | Social contamination from hub (ring turns on smuggler) | Bar dialogue shifts from warm to cold. Lera stops saving the smuggler's seat. Torek stops buying rounds. |
| Detective | `public` | `public` → `peer` | Repeated visits (3-4), becomes a regular, earns Lera's respect | Greeting dialogue warms. Sera introduces detective to regulars. Access to bar gossip unlocks. |
**The Ring (Smuggling Operations)**
| Character | Starting Tier | Likely Shift | Trigger | Content Requirement |
|-----------|--------------|--------------|---------|---------------------|
| Smuggler | `insider` + `peer` | `peer` → `hostile` | Suspected of cooperation with detective, unauthorized contact (like Kael) | Ring dialogue becomes interrogative. Nils questions loyalty. Operational info stops flowing. |
| Detective | `public` (doesn't know ring exists) | `public` → `hostile` | Stumbles into ring awareness — NPCs react defensively | Immediate evasion. Doors close. No access to insider content, but NPCs' defensive behavior is itself evidence. |
---
### What Access Tier Shifts Mean for Content Packs
Every content pack must support:
1. **Starting state dialogue** — the baseline access tier per character
2. **Shifted state dialogue** — the most likely tier transition per character
3. **Monologue that tracks the shift** — the character's internal reaction to changed access
Example from Kael content pack:
*Starting state (Friendly, insider access):*
```yaml
- id: terminal_d_120
role: dock_worker
text: "Container 4471 is flagged. I'll reroute it during shift transition."
access: [insider]
trust: real
situation: [shift_transition]
notes: "Ring operational talk. Only smuggler hears this."
```
*Shifted state (PersonOfInterest, insider locked out):*
```yaml
- id: terminal_d_121
role: dock_worker
text: "Shift's running smooth today. No issues."
access: [public]
trust: surface
situation: [shift_start]
notes: "Post-contradiction. Kael is surface-normal. The warmth is gone. The insider content is locked."
```
*Smuggler monologue tracking the shift:*
```yaml
- id: terminal_m_122
character: smuggler
trigger: post_conversation
prerequisite:
relationship_state: PersonOfInterest
subject: kael_davan
text: "Same old Kael. Same jokes, same routine. ...What are you not telling me?"
mood: [conflicted]
topic: [colleague]
notes: "Phase 5: Contaminated trust. Every normal interaction is now suspicious."
```
---
## Chapter 4: Divergence Escalation Curve
The vertical slice is 30 minutes. Divergence between the smuggler and detective experiences escalates over time. Here's the minute-by-minute curve:
### Minutes 0-10: Minimal Divergence
**Shared Experience:**
- Both characters enter the same locations (The Terminal, The Last Shift).
- Both see the same NPCs moving through their routines.
- Both hear similar `public`-tier dialogue (greetings, small talk, shift schedules).
- Both experience the same sensory atmosphere (station hum, cargo machinery, recycled air).
**Minimal Differences:**
- Monologue voice is different (smuggler: casual, relational; detective: analytical, institutional).
- NPC greetings vary by recognition (smuggler gets "There you are" from Kael; detective gets "Can I help you?" from Voss).
- The smuggler's monologue references operational context ("shift transition in thirty minutes"). The detective's monologue references investigative context ("manifest discrepancies tied to this hub").
**Player Experience:**
The two characters feel similar. The world is shared. The voice is different, but the content overlap is high. This is intentional — it establishes the baseline before divergence accelerates.
---
### Minutes 10-20: Growing Divergence
**Access Tiers Start to Differ:**
- The smuggler hears `insider` dialogue from Kael, Voss, Lera. Ring operational talk. Close colleague warmth.
- The detective hears `authority` dialogue from Maret, Drin, Voss. Institutional leverage questions. Evasive answers.
- The smuggler's `peer` access to bar regulars unlocks gossip, complaints, social texture. The detective is still `public` at the bar — polite but distant.
**Monologue Pools Diverge:**
- The smuggler's monologue starts tracking operational risk: "Torek's spending is too visible." "Maret's been quiet lately — did she notice something?"
- The detective's monologue starts tracking behavioral tells: "Dock worker Davan — lattice activity spiked." "Voss deflected when I asked about overnight containers."
**NPCs Respond Differently:**
- Kael is warm to the smuggler (Friendly relationship), clinical to the detective (Unknown or Known).
- Sera is warm to the detective (Friendly, pre-existing contact), wary to the smuggler (Commission presence).
- Lera is protective of regulars around the detective (defensive), casual with the smuggler (insider).
**Player Experience:**
The same room. Different colors. Different names. Different monologue. The player who's played both paths starts to notice: "Wait, I didn't hear that line as the detective." The asymmetry is becoming visible.
---
### Minutes 20-30: Maximum Divergence
**Completely Different Internal Experiences:**
**Smuggler (navigating ring crisis):**
- Kael's contradiction discovered. The FRIEND arc is in Phase 3-4 (shock, confrontation).
- Monologue is emotionally loaded: hurt, betrayal, protectiveness, fear of exposure.
- Access to `insider` content at The Terminal and bar. Operational dialogue about shift windows, container routing, risk management.
- Relationship stakes are personal: "Kael is lying to me. What do I do? Confront? Protect? Report to Nils?"
**Detective (uncovering evidence):**
- Sera's contradiction discovered. The FRIEND arc is in Phase 3-4 (pattern confirmed, question asked).
- Monologue is analytically loaded: suspicion, professional conflict, moral cost of using Sera's concealment.
- Access to `authority` content at The Terminal. Institutional leverage. Maret might cooperate. Drin might turn.
- Relationship stakes are institutional: "Sera knows something. Do I press? Report her? Protect her?"
**Zero Overlap in Emotional Journey:**
- The smuggler is inside a community facing internal betrayal.
- The detective is outside a community trying to crack it open.
- The same events (Kael's nervousness, Sera's avoidance, Torek's spending) mean completely different things to each character.
**Player Experience:**
"I was only seeing HALF of this." The replay reveals a completely different game. Not just "I knew different things" — "I cared about different things." The divergence is total.
---
### Content Authoring Implications
| Minutes | Dialogue Overlap | Monologue Overlap | NPC Behavior Overlap | Content Requirement |
|---------|-----------------|-------------------|---------------------|---------------------|
| 0-10 | ~80% | 0% (separate pools) | ~90% (same routines) | Heavy `public` dialogue, light `insider`/`authority` |
| 10-20 | ~50% | 0% | ~70% (NPCs start reacting differently) | Balanced `public`/`insider`/`authority`, access tier shifts begin |
| 20-30 | ~30% | 0% | ~50% (relationships diverged) | Heavy `insider` (smuggler) and `authority` (detective), THE FRIEND arcs at peak |
---
## Chapter 5: Authoring Checklist
Before submitting a line, ask:
### Question 1: Does this line make sense if the smuggler hears it?
**Test:** Read the line aloud. Imagine the smuggler — a dock worker who's been on Sova for years, knows the ring from inside, thinks in operational terms, worries about people. Does this line sound like something an NPC would say TO a smuggler? Or does it assume the listener is an outsider / authority figure?
**Common failures:**
- NPC explains basic station layout to the smuggler (the smuggler already knows).
- NPC uses institutional vocabulary the smuggler wouldn't recognize ("manifest reconciliation protocol" instead of "the paperwork doesn't match").
- NPC is defensive or evasive without cause (why would Kael be evasive with his closest colleague unless something's wrong?).
**Fix:** Rewrite the line for insider context. Or tag it `access: [authority, public]` so the smuggler never hears it.
---
### Question 2: Does this line make sense if the detective hears it?
**Test:** Read the line aloud. Imagine the detective — a Commission investigator, new to the district, analytical training, institutional frame, no prior relationships except Sera. Does this line sound like something an NPC would say TO a detective? Or does it assume the listener already belongs to the community?
**Common failures:**
- NPC uses in-group slang or references without explanation (the detective doesn't have the context yet).
- NPC is too warm / too trusting (why would Voss share operational details with an investigator?).
- NPC volunteers sensitive information unprompted (people don't do that to authorities they don't trust).
**Fix:** Rewrite the line for outsider context. Or tag it `access: [insider, peer]` so the detective never hears it.
---
### Question 3: Does this line reveal something different to each character?
**Test:** If both characters hear this line, do they interpret it differently? Does the smuggler's monologue reaction differ from the detective's? If both characters hear "Container 4471 sat in temp storage overnight," does one read it as operational routine and the other as procedural anomaly?
**Common failures:**
- The line is purely informational with no interpretive space ("The bar opens at 15:00" — both characters just learn the hours).
- The line is so specific to one character's context that the other character's hearing it feels wrong.
- The dual-lens difference isn't meaningful — both characters react the same way.
**Fix:** Add subtext. Create interpretive ambiguity. Or split the line into two versions (one `insider`, one `public`) that say similar things with different connotations.
---
### Question 4: Is the access tier correct for both characters?
**Test:** Check the `access` tag. If it includes `insider`, can the detective reach that tier with this NPC? (Usually no — the detective is an outsider to the ring.) If it includes `authority`, does the smuggler have authority leverage over this NPC? (Usually no — the smuggler is peer-level.)
**Common failures:**
- Line tagged `access: [public, insider]` — both characters hear it, but the insider-specific content makes no sense to the detective.
- Line tagged `access: [authority]` — detective gets institutional leverage questions, but the NPC's answer assumes peer relationship.
- No `access` tag (defaults to `public`) — line contains sensitive information that should be tier-gated.
**Fix:** Be explicit. If the line only works for one character, tag it `access: [insider]` or `access: [authority]` exclusively. If it works for both, tag `access: [public, peer]` and test both readings.
---
### Question 5: Does this line advance at least one character's emotional arc?
**Test:** Does this line move a relationship forward? Deepen trust, reveal a contradiction, escalate tension, provide comfort, create doubt? Or is it purely functional (greeting, filler, repetition)?
**Common failures:**
- Line is generic social lubricant ("Nice weather today" — there's no weather on a station).
- Line repeats information the character already has ("Kael works at the dock" — the smuggler knows this).
- Line doesn't connect to any NPC axis (Want, Secret, Relationship, Tolerance) or triangle tension.
**Fix:** Every line should serve character, relationship, or narrative. If it doesn't, cut it or replace it with a line that does. Content budget is finite. No filler.
---
## Chapter 6: THE FRIEND Specification
### The Pattern
Each playable character has one "FRIEND" NPC — a production-level complex character that exercises every content and systems pipeline at full depth. THE FRIEND is the emotional centerpiece of v0.1 and carries D-027 success criterion #3 ("player names an NPC they felt conflicted about").
**THE FRIEND follows a reusable pattern:**
| Element | Requirement |
|---------|-------------|
| **Relationship phases** | 3+ phases with distinct monologue registers (comfort → doubt → conflict) |
| **Observable contradiction** | Discoverable through observation, not told through dialogue |
| **Sympathetic motivation** | THE FRIEND isn't evil — their concealment comes from care or fear |
| **No clean resolution** | Every choice (confront, ignore, exploit, protect) has consequences |
| **Dual-lens resonance** | The other character's playthrough recontextualizes THE FRIEND's behavior |
| **Triangle integration** | THE FRIEND's contradiction connects to at least one triangle |
| **Tell progression** | 3+ observable behavioral changes the monologue system flags |
| **Dialogue shift** | Pre-discovery and post-discovery dialogue pools feel different |
---
### Smuggler's FRIEND: Kael Davan
**Who:** Dock worker, Sova Transit District Logistics Hub. The smuggler's closest colleague. Ring member. Handles physical cargo routing.
**Surface Presentation (Minutes 0-10):**
Warm, reliable, slightly sardonic. Greets the smuggler with genuine affection. Talks about shift schedules, complains about Voss, asks about the smuggler's weekend. Feels like the best coworker you've ever had.
**What the Smuggler Knows:**
Kael is a ring member. This isn't a secret from the smuggler — it's shared context. They work together on both the legitimate side and the ring side. The smuggler trusts Kael because they've shared risk for two years.
**The Contradiction:**
The smuggler sees Kael in the restricted maintenance corridor (Corridor B-7) talking to someone the smuggler doesn't recognize. Late. Off-shift. The person leaves before the smuggler gets close.
Smuggler monologue: *"That's Kael. But who's he talking to? I don't know that face."*
This is NOT the detective. This is someone from outside the ring's known network. Kael has a side arrangement the smuggler doesn't know about.
**The Shift Arc (Triangle 4: The Worried Partner)**
Kael is at the center of Triangle 4 (Naia-Kael-Sera). His partner Naia is worried about his late nights. Naia has confided in Sera (Commission field tech, the detective's FRIEND). Kael is oblivious to the anxiety he's causing. The unknown contact is someone offering to help Kael exit the ring — to protect Naia. Kael is trying to get out. But from the smuggler's perspective, any unauthorized contact is a security breach.
| Phase | Timing | Smuggler Observes | Monologue Register | Tell |
|-------|--------|------------------|-------------------|------|
| **Phase 1: Comfort** | 0-10 min | Kael is warm, reliable, present. Business as usual. | Fond, casual: *"Kael's already at the dock. Good. The day's better when he's on shift."* | None — baseline comfortable |
| **Phase 2: First Crack** | 10-15 min | Kael checks lattice more often. Excuses himself from lunch early. | Mild concern: *"Kael's distracted today. Probably nothing."* | Behavioral: increased lattice checking, shortened interactions |
| **Phase 3: The Contradiction** | 15-20 min | Corridor B-7. Unknown contact. Spatial deviation. | Alarm + confusion: *"That wasn't anyone from our rotation. And Kael didn't tell me about a meeting."* | Spatial: Kael in unexpected location at unexpected time |
| **Phase 4: Confrontation** | 20-25 min | Smuggler asks. Kael deflects: "Just a thing. Don't worry about it." He's lying. | Betrayal crystallizing: *"He looked left before answering. He always looks left when he's making something up."* | Dialogue: evasion, subject change, the tell confirmed |
| **Phase 5: Contaminated Trust** | 25-30 min | Everything looks normal again. But the smuggler is watching. | Conflicted: *"Same old Kael. Laughing at the same jokes. ...What are you not telling me?"* | Emotional: every warm interaction is now suspicious |
**RelationshipState Transition:**
`Friendly` (green) → `PersonOfInterest` (amber) at Phase 3 contradiction discovery.
**Access Tier Shift:**
`insider` + `peer` dialogue locks out at Phase 3. Kael still talks to the smuggler, but the warmth is gone. Only `public` + `surface` lines remain. That absence IS the narrative.
**Content Requirements:**
~70-100 authored lines (no generation expansion):
- 25-35 dialogue lines (greetings, shift talk, bar casual, ring coordination, deflection, confrontation responses)
- 15-20 trust-gated lines (insider ring talk, close colleague warmth, secret-tier hints about wanting out)
- 5-8 unprompted lines (Kael volunteers info early, warnings/deflections late)
- 10-15 monologue lines (smuggler about Kael: warmth, concern, contradiction discovery, post-confrontation, contaminated trust)
- 10-15 monologue lines (detective about Kael: identification, behavioral observation, suspicion, informant potential)
- 5-8 tell observation lines (lattice checking, distraction, looks-left tell, spatial deviation)
- 3-5 contradiction discovery lines (Corridor B-7 moment from multiple angles)
---
### Detective's FRIEND: Sera Venn
**Who:** Commission field technician, off-duty bar regular. The detective's pre-existing contact in the district. Same institutional background. Transferred to Sova a year ago. The detective's social anchor.
**Surface Presentation (Minutes 0-10):**
Competent, slightly wry, comfortable in the district. When the detective visits the bar, Sera waves them over. Easy rapport. Fills in background — who the regulars are, what the district's like. The detective's guide to an unfamiliar place.
**What the Detective Knows:**
Sera is reliable. She transferred for routine work after a stressful posting elsewhere. She doesn't have skin in the smuggling game. She's the detective's safe harbor.
**The Contradiction:**
Sera always leaves when Torek Lintar arrives at the bar. Always. Three times in a row. Different excuses each time. "Early shift tomorrow." "Headache." "Need to check something at the kiosk."
Detective monologue: *"That's the third time Sera's left when Torek walked in. That's not coincidence."*
**The Shift Arc (Triangle 4: The Worried Partner)**
Sera is at the other node of Triangle 4. Naia (Kael's partner) confides in Sera about Kael's late nights. Sera — being a Commission tech with system access — ran an unofficial compliance check on Kael's work patterns. She found manifest discrepancies. She knows something is wrong. She hasn't reported it because Naia is her friend, and reporting would mean Kael gets investigated, possibly arrested, and Naia's life falls apart. Sera is sitting on unreported evidence. She avoids Torek because Torek is ring-adjacent, and she doesn't want to be seen near him while concealing what she knows.
| Phase | Timing | Detective Observes | Monologue Register | Tell |
|-------|--------|-------------------|-------------------|------|
| **Phase 1: Trust** | 0-10 min | Sera is warm, informative, helpful. Shares district intel freely. | Professional + personal warmth: *"Good to see Sera. She always was the reliable one."* | None — baseline comfortable |
| **Phase 2: Background Data** | 10-15 min | Sera mentions Naia (Kael's partner) as "a friend." Naia joins them once. Genuine rapport. | Noting: *"Sera's connected here. Good. She knows the locals."* | Social: Sera has relationships outside institutional channels |
| **Phase 3: The Pattern** | 15-20 min | Third departure when Torek arrives. Three different excuses. Same result. | Suspicion activating: *"That's the third time. Three excuses, one result. That's data."* | Behavioral: avoidance pattern, excuse variety, timing correlation |
| **Phase 4: The Question** | 20-25 min | Detective asks about Torek. Sera tenses. Deflects: "He's just loud. I don't like loud drunks." | Professional analysis + personal conflict: *"She's not lying. But she's not telling me everything."* | Dialogue: controlled deflection, topic change, re-establishing warmth quickly |
| **Phase 5: Contaminated Trust** | 25-30 min | Sera continues being helpful. Maybe MORE helpful — compensating. | Analytical doubt: *"Still the same Sera. Still reliable. ...But reliable about what?"* | Emotional: detective's observation lines shift from trusting to evaluating |
**RelationshipState Transition:**
`Friendly` (green) → `PersonOfInterest` (amber) at Phase 3 pattern confirmation.
**Access Tier Shift:**
`peer` dialogue available at Phase 1-2. At Phase 3, `authority` dialogue unlocks (detective can press institutional leverage questions). `peer` warmth remains but is contaminated.
**Content Requirements:**
~70-100 authored lines (no generation expansion):
- 25-35 dialogue lines (bar greetings, district orientation, Naia conversation, institutional discussion, deflection about Torek, confrontation responses)
- 15-20 trust-gated lines (peer-tier institutional background, secret-tier hints about what she found)
- 5-8 unprompted lines (Sera volunteers district background early, steers away from sensitive areas late)
- 10-15 monologue lines (detective about Sera: trust/relief, pattern observation, contradiction discovery, post-confrontation)
- 10-15 monologue lines (smuggler about Sera: institutional categorization, avoidance notation, cautious assessment)
- 5-8 tell observation lines (avoidance pattern x3, topic deflection, overcompensation helpfulness, extended kiosk time)
- 3-5 contradiction discovery lines (third departure from multiple angles)
---
### Why THE FRIEND Works Narratively
**Kael's contradiction isn't "Kael is secretly evil."**
The contradiction is "Kael is secretly desperate, and his desperation is making him do exactly the kind of thing that could get everyone caught." The smuggler's anger is justified (protocol breach). Kael's motivation is sympathetic (protecting family). No clean answer. That's the conflict.
**Sera's contradiction isn't "Sera is corrupt."**
The contradiction is "Sera is a good person making a terrible choice: loyalty to a friend vs. duty to her institution." The detective's discovery doesn't reveal a villain — it reveals a moral compromise the detective might understand. The question becomes: do I report Sera? Use what she knows? Confront and risk losing my only ally?
**Dual-Lens Resonance:**
The smuggler who's played the detective path knows the investigation is closing in — Kael's exit attempt reads differently (not betrayal, desperation). The detective who's played the smuggler path knows why Sera is protecting Naia — Sera's silence reads differently (not corruption, loyalty).
---
## Chapter 7: Voice Signature
### Smuggler — Internal Voice Register
**One-line summary:** Watches people, not systems. Thinks in fragments. Worries about friends the way a dock worker worries — practically, physically, with the knot in the stomach, not the word for it.
#### Voice Parameters
| Parameter | Value | Example |
|-----------|-------|---------|
| **Sentence length** | Short. Fragments welcome. Rarely more than 2 sentences per monologue. | *"Kael's here. Good."* |
| **Vocabulary** | Concrete, physical, sensory. Trade jargon (containers, manifests, shifts, routes) without explaining. No institutional language. | *"Recycled air and cargo lubricant."* Not: "Standard atmospheric recycling." |
| **Emotional register** | Feeling-first, analysis second. Names the gut before the brain catches up. | *"Starting to worry"* before *"something's off."* |
| **Relationship mode** | First-name basis. People defined by connection, not role. | *"Kael"* not *"Davan."* *"Voss is tense"* not *"the shift supervisor seems agitated."* |
| **Observation priority** | People > environment > objects. Notices body language before cargo. | *"Kael keeps checking his lattice"* before *"Container 4471 is still in temp."* |
| **Operational thinking** | Present when thinking about the job. Time-aware, route-aware, schedule-aware. Filtered through "is this safe for my people?" | *"Transition window opens in fifty minutes."* |
| **Self-reference** | Rare. Thinks about others, not herself. When it occurs, through physical sensation. | *"My stomach dropped"* not *"I feel betrayed."* |
| **Humor** | Dry, situational, understated. Dark when stressed. Never witty. | *"Home sweet home"* about a cargo bay. |
**What the smuggler doesn't do:**
- Doesn't analyze systems.
- Doesn't use institutional vocabulary.
- Doesn't explain things to herself that she already knows.
- Doesn't monologue in paragraphs.
#### Voice Anchors (Reference Lines)
These 5 lines define the boundaries. Every smuggler monologue should feel like it could sit next to these:
1. **Baseline warm:** *"Kael's already at the dock. Good. The day's better when he's on shift."*
2. **Operational:** *"Shift transition in thirty minutes. If Voss kept the schedule thin, the route's clear."*
3. **Concerned:** *"Kael keeps checking his lattice. Waiting for a message? Not like him to be jumpy."*
4. **Hurt:** *"He looked left. He always looks left when he's making something up. Two years I've known that tell. Kael is lying to me."*
5. **Atmospheric:** *"Morning shift. Recycled air and cargo lubricant. Home sweet home."*
#### Anti-Patterns (What the Smuggler Does NOT Sound Like)
- *"I should investigate this anomaly further."* (Too clinical. She'd think: *"That's not right."*)
- *"The scheduling irregularity suggests systemic manipulation."* (Institutional vocabulary. She'd think: *"Voss changed the rotation again."*)
- *"I need to consider the implications of Kael's behavior for our operational security."* (Analytical distance. She'd think: *"What the hell is Kael doing?"*)
- *"According to the manifest, container 4471 should weigh 240 kilograms."* (Explaining what she already knows. She'd think: *"4471's heavy. Too heavy."*)
---
### Detective — Internal Voice Register
**One-line summary:** Categorizes first, feels second. Thinks in complete sentences. The institutional training runs in the background like an operating system — it never turns off, but sometimes the human overrides it.
#### Voice Parameters
| Parameter | Value | Example |
|-----------|-------|---------|
| **Sentence length** | Complete sentences, but not long. More structured than the smuggler. Occasional fragments for emphasis. | *"Standard prefab, heavy foot traffic. Let's see what the shift change tells me."* |
| **Vocabulary** | Institutional layer over plain speech. Professional terms: "case file," "filing it," "noted," "flagged." Not technical jargon — investigative habit. | *"Dock worker. Davan, K. Unremarkable on paper."* The surname-comma-initial is institutional reflex. |
| **Emotional register** | Analysis-first, personal second. When personal breaks through, it's notable — a crack in the professional surface. | *"She's not lying. But she's not telling me everything. Sera, what do you know?"* The first-name appeal IS the emotion. |
| **Relationship mode** | Surname-first for targets and unknowns. First-name for allies and trusted. The shift IS a relationship marker. | *"Davan, K."* early → *"Kael"* never (smuggler's FRIEND, not detective's). *"Sera"* always (detective's FRIEND). |
| **Observation priority** | Patterns > people > environment. Notices deviations from expected before noticing the person. | *"That's twice now"* before *"Sera leaves."* The count matters more than the actor. |
| **Analytical thinking** | Automatic. Counts, tracks, flags. Self-directs: "filing it," "noted," "coincidence?" Internal bookkeeping. | *"Three times. Three excuses. That's data."* |
| **Self-reference** | More common than the smuggler, but always through professional lens. Monitors own state as evidence. | *"I'm reading too much into this"* — self-aware about analytical bias. |
| **Humor** | Wry, observational. Appreciates irony at a distance. Can laugh at himself. Never cruel. | *"Only place in this district that doesn't smell like freight lubricant."* |
**What the detective doesn't do:**
- Doesn't think in fragments (that's the smuggler).
- Doesn't use trade jargon he hasn't learned.
- Doesn't name-drop relationships he doesn't have.
- Doesn't express vulnerability directly — it leaks, he doesn't pour.
#### Voice Anchors (Reference Lines)
1. **Clinical baseline:** *"Logistics hub. Standard prefab, heavy foot traffic. Let's see what the shift change tells me."*
2. **Pattern recognition:** *"That's the third time. Sera leaves when Torek arrives. Three different excuses, same result. That's not coincidence."*
3. **Personal leak:** *"Good to see Sera. She always was the reliable one. At least someone in this district speaks my language."*
4. **Conflicted:** *"Same booth. Same warm smile. Same offer to buy me a drink. ...Everything except whatever she's not saying."*
5. **Atmospheric:** *"Grain spirit and low conversation. Only place in this district that doesn't smell like freight lubricant."*
#### Anti-Patterns (What the Detective Does NOT Sound Like)
- *"Kael's here. Good."* (Too terse. That's the smuggler. The detective: *"Davan's on shift. Standard."*)
- *"I feel uneasy about Sera's behavior."* (Direct emotional vocabulary. He'd think: *"Something's off with Sera. Can't place it yet."*)
- *"This container has been tampered with, indicating smuggling activity."* (Explaining the obvious. He'd think: *"Weight's wrong. Noted."*)
- *"My heart sank when I saw the evidence."* (Physical emotion — smuggler's register. Detective: *"Didn't want to see that. But there it is."*)
---
### Voice Register Comparison — Same Observation, Two Characters
**Trigger:** Seeing a container in temp storage overnight.
- **Smuggler:** *"That container's been in temp since yesterday. Someone forgot to process it, or someone's stalling."*
- **Detective:** *"Container in overnight temp. Unusual for a hub this size — turnaround is normally sub-eight hours. Flag it."*
**Trigger:** Entering the bar.
- **Smuggler:** *"Lera's. Grain spirit and noise. Could use both right now."*
- **Detective:** *"The Last Shift. Same crowd as yesterday. Let's see who's NOT here tonight."*
**Trigger:** Noticing Naia Tamm is upset.
- **Smuggler:** *"Naia looks rough today. Should check on her later."*
- **Detective:** *"Tamm seems distressed. Not her baseline. Something at home, or something she's heard?"*
**Trigger:** Hearing raised voices behind a door.
- **Smuggler:** *"Raised voices from the back room. Devra's in there. That's not a brokering call."*
- **Detective:** *"Arguing behind that door. The bartender didn't flinch. Either she's used to it or she knows what it is."*
---
## Conclusion
The dual-lens rule is simple: **one world, two perspectives, zero shared monologue lines.** Every content piece must work for both characters. The smuggler sees home and sees betrayal. The detective sees a crime scene and sees moral complexity. Same NPCs. Same locations. Completely different games.
Write for the voice. Tag for the system. Test for both lenses. Cut ruthlessly.
That's the job.
---
**End Dual Lens Authoring Guide v0.1**
docs/design/interaction-verbs-v0.1.md
+415
View File
@@ -0,0 +1,415 @@
# Interaction Verb Specification v0.1
**Ticket:** #402
**Status:** v0.1 design spec
**Source:** Workshop output A-04 (D-044), D-INTERACT lead decision (D-051), D-060 (`verbs[]` rename)
**Soft dependency:** NEW-9 (server `InteractionOptions` component)
---
## 1. Overview
The interaction verb system is how the player interfaces with the simulation. Every interaction between the player character and the world is expressed as a **verb** -- a discrete, typed action that triggers server-side processing and produces client-side feedback.
v0.1 uses a **single context-sensitive action button**. When the player presses `[E]` near an interactable entity, the system selects the highest-priority available verb and executes it. The player does not choose between verbs in v0.1 -- the system picks.
Underneath, the architecture supports **N verbs per entity** via the `verbs[]` array. The server computes all available verbs for every entity in the player's perception range on every tick. The v0.1 client reads only `verbs[0]` (the highest-priority option). The v0.2 client will present the full list as a verb wheel or horizontal label row. No server changes are required for this transition.
There are **7 interaction verbs** in v0.1:
| # | Verb | Type | Player Input |
|---|------|------|-------------|
| 1 | Move | Active | WASD keys |
| 2 | Look | Passive | Automatic (perception system) |
| 3 | Monologue | Reactive | Automatic (server-triggered) |
| 4 | Examine Object | Active | Context key on environment |
| 5 | Examine NPC | Active | Context key on NPC |
| 6 | Talk | Active | Context key on NPC |
| 7 | Overhear | Passive | Automatic (proximity-based) |
**Cross-references:**
- Game concept and vertical slice: [D-005](../../decisions/scope.md#d-005), [D-027](../../decisions/scope.md#d-027)
- Perception and fog: [D-011](../../decisions/perception.md#d-011), [D-015](../../decisions/perception.md#d-015)
- Dialogue architecture: [D-028](../../decisions/content.md#d-028)
- Monologue pools: [D-032](../../decisions/content.md#d-032)
- Tag taxonomy: [D-035](../../decisions/content.md#d-035)
- Knowledge graph: [D-041](../../decisions/architecture.md#d-041)
- ObserverSnapshot v3: D-054
---
## 2. Terminology
### `verbs[]` -- the canonical term
A **verb** is a player-initiated or system-triggered interaction with the world. Each entity in the player's perception has a `verbs[]` array listing available interactions, computed by the server every tick.
The term `verbs[]` replaces all prior references to `actions[]`, `AvailableActions`, `EntityInteractions`, and `ActionOption`. This rename was confirmed in the closing round of the v0.1 Content Scoping Workshop (D-060) and applies across:
- Server code (Rust structs and enums)
- Client code (GDScript)
- YAML content files
- Wiki documentation
- Decision files
### Key definitions
| Term | Definition |
|------|-----------|
| **Verb** | A typed interaction between the player character and an entity or the environment. |
| **`verbs[]`** | Per-entity array of available verbs, sorted by priority (index 0 = highest priority). Embedded in `ObserverSnapshot.nearby_interactions`. |
| **Active verb** | Requires player input to execute (Move, Examine Object, Examine NPC, Talk). |
| **Passive verb** | Fires automatically when conditions are met (Look, Overhear). |
| **Reactive verb** | Triggered by the server in response to game events, not by direct player action (Monologue). |
| **Context key** | The single action button (`[E]` in v0.1) that executes the highest-priority available verb on the targeted entity. |
| **Verb priority** | Numeric rank determining which verb the context key executes when multiple are available. Lower number = higher priority. See Section 4. |
---
## 3. Per-Verb Specifications
### 3.1 Move
**The player moves to a tile or location.**
Move is the foundational verb. Physical presence in the world determines what the player can perceive, who they can interact with, and what information they have access to. Movement is not just locomotion -- it is a commitment of time and attention that creates observable behavior for NPCs.
| Aspect | Specification |
|--------|--------------|
| **Trigger** | WASD key input (continuous while held). |
| **UI need** | Character sprite moves on tilemap. Camera follows (locked to character per D-015). Footstep audio triggers (D-038: `sfx_footstep_metal.ogg` / `sfx_footstep_metal_run.ogg`). |
| **Server event** | `PlayerAction::Move(direction)`. Server validates against collision map, updates player entity position, recalculates LOS (symmetric shadowcasting per D-035/perception), updates `ObserverSnapshot` with new visible entities and fog state. |
| **Content requirement** | Collision map per social site. Tile walkability data. No authored text content. |
| **Knowledge impact** | Indirect. Moving into LOS range of an entity may trigger `DirectObservation` knowledge source updates. Moving into proximity range of NPC conversations enables Overhear. Moving to a new location may trigger `enter_location` monologue. |
| **v0.1 scope** | Full implementation. WASD movement, collision, LOS recalculation. Walk speed only (no run toggle in v0.1). |
---
### 3.2 Look
**The player observes the environment through their character's perception.**
Look is the passive observation verb. It fires continuously as long as the player has line-of-sight to entities. The player does not press a button to Look -- the perception system handles it. Look is how the player gains spatial awareness: who is where, what they are doing, and how entities relate to each other in space.
| Aspect | Specification |
|--------|--------------|
| **Trigger** | Automatic. Fires every tick for all entities within the player's LOS (shadowcasting per D-011). No player input required. |
| **UI need** | Entities rendered on tilemap within LOS. Entity color reflects relationship state (D-033: teal for unknown, green for friendly, amber for person of interest, red for hostile). Fog of perception obscures entities outside LOS. Vision cone renders forward/peripheral/blind zones (D-015). |
| **Server event** | Not a discrete event. The perception system continuously evaluates which entities fall within the player's LOS and populates `ObserverSnapshot.visible_entities`. Entity visibility triggers `KnowledgeEvent` updates for position and `last_observed_tick`. |
| **Content requirement** | None directly. Entities must have visual representations (sprite/placeholder). Entity color palette defined in D-033. |
| **Knowledge impact** | Updates `location` key for observed entities (Direct confidence). Updates `last_observed_tick`. If an NPC is observed performing a routine deviation (tell), may set `behavior_flags` and trigger Monologue via `observe_npc` or `observe_anomaly`. |
| **v0.1 scope** | Full implementation. Natural vision cone + fog of perception. No additional perception modes (thermal, camera feeds, etc. are deferred per D-017). |
---
### 3.3 Monologue
**The player character's internal voice reacts to observations and events.**
Monologue is the player character's inner narrator. It is reactive -- triggered by the server based on game events, not by player input. Monologue bridges the gap between the top-down camera and the character's subjective experience (D-016). It is the primary vehicle for character voice, anomaly flagging, atmospheric commentary, and diegetic hints.
Monologue is character-specific. The smuggler and detective have completely separate monologue pools (D-032). Same trigger, different pool, different voice.
| Aspect | Specification |
|--------|--------------|
| **Trigger** | Server-initiated. The monologue system evaluates triggers every tick against the player character's current state. 9 trigger types defined in D-035: `enter_location`, `observe_npc`, `hear_sound`, `observe_anomaly`, `post_conversation`, `discover_evidence`, `witness_interaction`, `time_idle`, `return_visit`. Each monologue line has a `prerequisite` map (AND-only) that gates on knowledge state. |
| **UI need** | Monologue text rendered in world-space layer (not HUD). Character-tinted text (smuggler: amber-white `#f0e0c8`, detective: blue-white `#c8d8f0`). Max 160 characters, max 2 visual lines. Display time 3-6 seconds (length-adjusted). Fade in 0.3s, fade out 0.5s. Monologue chime audio (D-038: `sfx_monologue_chime.ogg`, or `sfx_monologue_chime_urgent.ogg` for anomaly/contradiction triggers). Queue depth 1 (drop lower priority). Cooldown 2s between lines. Priority ordering per D-059. |
| **Server event** | Monologue system selects the highest-priority eligible line from the active character's monologue pool. Sends `MonologueDisplay { id, text, priority, trigger_type }` in `ObserverSnapshot.monologue`. Client renders. |
| **Content requirement** | Separate monologue pool files per character per location (e.g., `monologue-smuggler.yaml`, `monologue-detective.yaml`). Each line tagged per D-035: `character`, `trigger`, `prerequisite`, `priority`, `cooldown`. Estimated volume: ~200 authored monologue lines across both characters for v0.1 (per workshop budget). |
| **Knowledge impact** | Monologue does not directly update the knowledge graph -- it reflects it. However, the *trigger* that caused the monologue (e.g., `observe_anomaly`) may have already updated knowledge. Some monologue lines serve as player-facing confirmation that a knowledge update occurred (e.g., "He checked his lattice again. Third time." confirms `behavior_flags` update). |
| **v0.1 scope** | Full implementation. All 9 trigger types. Prerequisite evaluation against knowledge graph. Priority-based queue. Fires during dialogue (for wow moment #3 -- FRIEND contradiction triggers monologue while the player is in conversation). |
**Priority ordering** (highest to lowest):
| Rank | Trigger Type | Rationale |
|------|-------------|-----------|
| 1 | `observe_anomaly` | Anomalies are rare and time-critical. |
| 2 | `witness_interaction` | NPC-to-NPC events the player should notice. |
| 3 | `discover_evidence` | Direct investigation payoff. |
| 4 | `post_conversation` | Reflection on just-completed dialogue. |
| 5 | `hear_sound` | Sensory input from outside LOS. |
| 6 | `observe_npc` | Commentary on observed NPC behavior. |
| 7 | `enter_location` | Arrival at a new area. |
| 8 | `return_visit` | Revisiting a known area. |
| 9 | `time_idle` | Unprompted reflective thought (wow moment #6). |
---
### 3.4 Examine Object
**The player examines a specific object in the environment.**
Examine Object is how the player investigates environmental elements: terminals, manifests, cargo containers, notices, equipment. It produces descriptive text and may update the knowledge graph with FactId entries.
| Aspect | Specification |
|--------|--------------|
| **Trigger** | Player presses context key (`[E]`) while targeting an examinable object within interaction range. Object must be in LOS and within close range. |
| **UI need** | Context prompt appears when player is in range: `[E] Examine`. On execution, description text displayed in HUD panel (or inline). Text sourced from server (client does not load content files per D-048). |
| **Server event** | `PlayerAction::InteractPrimary(target_stable_id)`. Server resolves verb as `VerbKind::ExamineObject`. Retrieves examine description for the target object. May evaluate knowledge prerequisites (some objects reveal different information based on what the player already knows). Returns `ExamineResult { target_id, description, knowledge_grants }` in `ObserverSnapshot.examine_result`. |
| **Content requirement** | Examine descriptions per examinable object. Detective and smuggler may receive different descriptions for the same object (filtered by access tier per D-028). Environmental objects in the 3 social sites: cargo terminals, manifests, shift schedules, bar fixtures, maintenance panels, door locks. Estimated: ~30-50 examine descriptions across all locations. |
| **Knowledge impact** | May grant new FactId entries (e.g., examining a manifest reveals `fact:shift_schedule_discrepancy`). May update existing EntityKnowledge if the object references an NPC (e.g., examining a terminal shows Kael's access log, updating `routine_pattern` for Kael). Knowledge grants are specified per examine description in the content YAML via `knowledge_grants` field. |
| **v0.1 scope** | Full implementation. Static examine descriptions with access-tier filtering. No multi-step examination (examine once, get the full description). No item pickup (evidence is knowledge, not inventory per D-046). |
---
### 3.5 Examine NPC
**The player observes a specific NPC without initiating contact.**
Examine NPC is passive intelligence gathering. The player studies an NPC from a distance -- watching their behavior, reading body language, noting patterns. This is the detective's primary loop entry point and the smuggler's surveillance mode. Critically, Examine NPC does not alert the target NPC. The player gathers information without social cost.
The separation between Examine NPC and Talk is load-bearing for the investigation loop:
- The detective's loop: **Examine first** (accumulate tells across multiple observations) then **Talk later** (use evidence in confrontation).
- The smuggler's loop: **Talk first** (social, operational, casual) then **Examine when suspicious** ("something's off, let me watch them").
Collapsing Examine and Talk into a single "Interact" verb would break both loops.
| Aspect | Specification |
|--------|--------------|
| **Trigger** | Player presses context key (`[E]`) while targeting an NPC within mid-to-close range and in LOS. Only available when Talk is not the higher-priority verb (see Section 4 for priority resolution). |
| **UI need** | Context prompt: `[E] Observe`. On execution, observation text displayed (behavioral description, tell observations, appearance notes). Text sourced from server. No dialogue UI opens. |
| **Server event** | `PlayerAction::InteractPrimary(target_stable_id)`. Server resolves verb as `VerbKind::ExamineNpc`. Server evaluates target NPC's current behavioral state, active tells, and the observing character's knowledge level. Returns observation description. May trigger `observe_npc` monologue. Updates `InteractionLog` (tracks observation count per target). |
| **Content requirement** | Observation descriptions per NPC, tiered by knowledge state. At `Suspects` confidence: surface-level observations ("Dock worker. Focused on the manifest."). At `KnowsOf`+: behavioral observations ("He's checked his lattice three times this shift. That's not routine."). Tell observation lines per NPC (D-034 specifies 5-8 per FRIEND NPC). Estimated: ~5-10 observation lines per T1/T2 NPC, ~2-3 per T3 NPC. |
| **Knowledge impact** | May update `behavior_flags` (tell observations: "nervous", "schedule_changes", "evasive"). May update `routine_pattern` if the NPC is observed deviating from their known routine. May increment tell observation counter (tracked in `behavior_flags` per D-055). Confidence level may advance from `Suspects` to `KnowsOf` through repeated observation (gated by `InteractionLog` count). |
| **v0.1 scope** | Full implementation. Knowledge-tiered observation descriptions. Tell detection system (NPC behavioral flags mapped to observable tells). No "analyze" sub-verb (lattice-assisted analysis deferred to v0.2). |
---
### 3.6 Talk
**The player initiates conversation with an NPC.**
Talk is active information exchange. The player approaches an NPC and begins a dialogue. This is the primary verb for social gameplay: building trust, gathering information, confronting contradictions, and maintaining cover. Talk has a social cost -- the NPC knows you engaged, and other NPCs may observe the interaction.
Dialogue uses tagged line pools with systemic selection (D-028), not branching trees. Lines are filtered by access tier, trust level, situation, and topic. The server selects and serves dialogue lines; the client displays them.
| Aspect | Specification |
|--------|--------------|
| **Trigger** | Player presses context key (`[E]`) while targeting an NPC within close range and in LOS. Talk takes priority over Examine NPC for most NPCs (see Section 4). |
| **UI need** | Context prompt: `[E] Talk`. On execution, dialogue panel opens (HUD layer). Displays NPC dialogue lines with player response options (selected from eligible pool). Sim speed drops to 50% during dialogue (D-052). Dialogue panel is one of the P0 UI scenes (1 scene, 1 script). Monologue can fire simultaneously in the world layer during dialogue (separate visual layer). |
| **Server event** | `PlayerAction::InteractPrimary(target_stable_id)`. Server resolves verb as `VerbKind::Talk`. Server opens a dialogue session: evaluates access tiers (D-028 Layer 1: insider/outsider/authority/peer/hostile), filters by trust level (D-028 Layer 3: surface/real/secret), applies situation context (D-028 Layer 2), selects eligible lines. Returns `ActiveDialogue { partner_id, lines, response_options }` in `ObserverSnapshot.active_dialogue`. Player selects a response; server processes `PlayerAction::DialogueResponse(choice)`. |
| **Content requirement** | Dialogue pools per template role and location (D-028). ~165-210 authored lines per Tier 2 template, generation-expanded 4x. Four relational layers all present from v0.1: access tiers, relationship history, trust-gated gossip, unprompted disclosure. FRIEND NPCs require ~25-35 dialogue lines + 15-20 trust-gated + 5-8 unprompted (D-034). |
| **Knowledge impact** | Dialogue can grant knowledge through `knowledge_grants` tags on lines. Trust level may advance or degrade based on dialogue choices (relationship history, D-028 Layer 2). `RelationshipState` may transition (Unknown to Known on first conversation, Known to Friendly through repeated positive interaction). Gossip lines may reveal information about third parties (updating EntityKnowledge for NPCs not present in the conversation). |
| **v0.1 scope** | Full implementation of all four dialogue layers. Tagged line pool selection. Access-tier filtering. Trust-gated disclosure. NPC-initiated unprompted disclosure (weighted by trust and mood). Post-contradiction confrontation dialogue (FRIEND arc Phase 4). |
---
### 3.7 Overhear
**The player overhears NPC-to-NPC conversation based on proximity.**
Overhear is environmental intelligence. When the player is within earshot of two or more NPCs having a conversation, fragments of that conversation are presented to the player. Overhear is passive -- the player does not press a button. The player merely needs to be close enough, and the server delivers fragments.
Overhear is the primary mechanism for the player to learn about NPC relationships, concerns, and secrets without direct engagement. It rewards spatial awareness and patience. The quality and completeness of overheard information depends on proximity (D-018: close range = high accuracy, medium range = imprecise).
| Aspect | Specification |
|--------|--------------|
| **Trigger** | Automatic. The server detects when the player character is within hearing range of an active NPC-to-NPC conversation. No player input required. Proximity thresholds follow D-018 three-range sound model: close range (full content, high trust), medium range (fragments, directional, imprecise). |
| **UI need** | Overheard text rendered as fragments -- partial lines, attributed to speakers if in LOS, unattributed if only audible. Visual indicators at fog edge for medium-range overhearing (D-018). Overheard text styled distinctly from monologue and dialogue (italicized or bracketed, lower opacity). No dialogue panel opens. |
| **Server event** | NPC conversation system runs independently of player action. When the player entity is within hearing range, the server includes relevant fragments in `ObserverSnapshot.overheard` as `Vec<OverheardFragment>`. Each fragment contains: `speaker_id` (if visible), `text`, `audibility` (clear/muffled/indistinct), `topic_hint`. |
| **Content requirement** | NPC-to-NPC conversation scripts. These are short, repeating exchanges that NPCs perform as part of their routines. Bar chatter, workplace complaints, shift handover talk, gossip. Key scripted conversations: Kael and colleague discussing schedules (innocuous surface, routine deviation subtext), bar regulars discussing Torek's spending, maintenance workers referencing Drin's absences. Estimated: ~40-60 overheard lines across all social sites. |
| **Knowledge impact** | Overheard content may update `known_associates` (hearing two NPCs talk confirms they interact). May update `behavior_flags` (hearing an NPC complain about schedule changes). May trigger `hear_sound` or `witness_interaction` monologue. Critical for wow moment #3 setup: overhearing references to NPC behavior that the player later observes directly. Knowledge source tagged as `Heard` (D-041), which carries lower confidence than `DirectObservation`. |
| **v0.1 scope** | Full implementation. Proximity-based fragment delivery. Close-range = clear text with speaker attribution. Medium-range = muffled fragments with directional indicator. NPC-to-NPC conversations run on schedule (not dynamically generated). Long-range insert alerts deferred (D-018 stretch goal). |
---
## 4. v0.1 Priority Resolution
v0.1 uses a single context-sensitive action button (`[E]`). When multiple verbs are available on a target, the system selects the highest-priority verb. The player does not choose.
### Priority order
| Priority | Verb | Condition |
|----------|------|-----------|
| 1 (highest) | **Talk** | Target is NPC, in close range, NPC has available dialogue, NPC is not flagged as `PersonOfInterest` with unresolved contradiction |
| 2 | **Examine NPC** | Target is NPC, in mid-to-close range, NPC IS flagged as `PersonOfInterest` with unresolved contradiction (post-contradiction, observation becomes primary) |
| 3 | **Examine NPC** | Target is NPC, in mid range only (too far for Talk) |
| 4 | **Examine Object** | Target is examinable environment object, in close range |
| 5 | **Talk** | Target is NPC, in close range, but NPC has limited/exhausted dialogue pool for current situation |
### Context-sensitive priority shifts
The priority order is not static. It shifts based on game state:
**Default state (pre-contradiction):**
- NPC in close range: `[E] Talk` (Talk > Examine NPC)
- NPC in mid range: `[E] Observe` (Examine NPC, Talk unavailable at this distance)
- Object in close range: `[E] Examine`
**Post-contradiction state (NPC flagged as PersonOfInterest):**
- NPC in close range: `[E] Observe` (Examine NPC > Talk)
- This represents the detective shifting from social mode to surveillance mode, or the smuggler shifting from trust to suspicion
- Talk remains available in v0.2 as a secondary verb (`[F] Talk`)
**Post-confrontation state (after confrontation dialogue):**
- NPC in close range: `[E] Talk` returns to primary (conversation continues, relationship has shifted)
### Resolution rules
1. **Only one verb executes per input.** The context key triggers exactly one verb.
2. **Server computes all available verbs.** The full `verbs[]` array is populated every tick per entity.
3. **Client reads `verbs[0]`.** The v0.1 client displays and executes only the first (highest-priority) verb.
4. **Passive/reactive verbs are not in `verbs[]`.** Look, Monologue, and Overhear are not player-activated and do not appear in the verb array. They fire independently.
5. **`verbs[]` contains only active verbs.** Move, Examine Object, Examine NPC, and Talk are the verbs that can populate `verbs[]`. Move is handled by WASD (not context key), so in practice `verbs[]` contains Examine Object, Examine NPC, and Talk.
---
## 5. Architecture Notes
### How `verbs[]` works at the server level
The server populates `verbs[]` per entity every tick. The computation follows this pipeline:
```
Per-entity verb evaluation (runs in perception phase):
1. Entity type check
- NPC -> eligible for: Examine NPC, Talk
- Object -> eligible for: Examine Object
- Environment -> eligible for: Examine Object (if tagged examinable)
2. Distance check
- Close range -> all eligible verbs available
- Mid range -> Talk removed (requires close range)
- Far range / out of LOS -> no verbs (entity not interactable)
3. Sightline check
- Entity must be in player's LOS (shadowcasting result)
- No interaction through walls or fog
4. Relationship state check
- PersonOfInterest + unresolved contradiction -> Examine NPC priority rises above Talk
- Hostile -> Talk may be removed (NPC refuses engagement)
5. Conversation state check
- NPC in active conversation with another NPC -> Talk unavailable (NPC is busy), Overhear activates passively
- NPC in active dialogue with player -> only DialogueResponse verbs available
6. Dialogue availability check
- NPC with exhausted dialogue for current situation -> Talk priority drops
- NPC with high-priority disclosure queued -> Talk priority rises
7. Priority sort
- Available verbs sorted by priority (see Section 4)
- Result written to verbs[] array on the entity's nearby_interaction entry
```
### Data structures
The `verbs[]` array is embedded in the `ObserverSnapshot` within `nearby_interactions`:
```
ObserverSnapshot {
...
nearby_interactions: Vec<NearbyInteraction>,
...
}
NearbyInteraction {
entity_id: StableId,
entity_type: EntityType,
distance: f32,
verbs: Vec<VerbOption>, // <-- the verbs[] array
}
VerbOption {
kind: VerbKind, // ExamineObject, ExamineNpc, Talk
label: String, // "Examine", "Observe", "Talk"
priority: u8, // lower = higher priority
available: bool, // false if conditions not met (greyed out in v0.2)
}
enum VerbKind {
ExamineObject,
ExamineNpc,
Talk,
}
```
The `VerbKind` enum does not include Move (handled by WASD input), Look (passive perception), Monologue (server-triggered), or Overhear (passive proximity). These verbs operate outside the `verbs[]` system.
### Client reads, server decides
The client is a dumb renderer (D-048, D-052). It does not evaluate content files, compute verb availability, or resolve priorities. The client:
1. Reads `nearby_interactions` from `ObserverSnapshot`
2. For the entity nearest to the cursor/facing direction, reads `verbs[0]`
3. Displays the label as the context prompt: `[E] {verbs[0].label}`
4. On `[E]` press, sends `PlayerAction::InteractPrimary(entity_id)` to the server
5. The server resolves which verb was meant (it already knows -- it computed the array)
### Future extension (v0.2+)
The v0.2 client reads the full `verbs[]` array and presents multiple options:
```
v0.1: [E] Talk
v0.2: [E] Talk [F] Observe
```
No server changes required. The protocol already carries the full verb list. The client simply renders more of it.
Further future: a verb wheel or radial menu for entities with 3+ available verbs (e.g., an NPC near an examinable object -- Talk, Observe, Examine nearby object).
---
## 6. Content Authoring Implications
The verb system defines what content must exist for each interaction type. Content authors need to produce material for each verb that fires on their NPCs, objects, and locations.
### Per-verb content requirements
| Verb | Content Type | Author Responsibility | Estimated Volume (v0.1) |
|------|-------------|----------------------|------------------------|
| **Move** | Collision maps, walkability | Level design (not prose authoring) | 3 social site maps |
| **Look** | Entity sprites/placeholders, color palette | Visual design | 17 NPC representations + objects |
| **Monologue** | Monologue pool YAML files | Mellanie (prose), Gestalt (triggers/prerequisites) | ~200 authored lines, partitioned by character (D-032) |
| **Examine Object** | Examine descriptions per object | Content authors | ~30-50 descriptions across all locations |
| **Examine NPC** | Observation descriptions per NPC, tiered by knowledge | Content authors | ~5-10 lines per T1/T2 NPC, ~2-3 per T3 NPC |
| **Talk** | Dialogue pool YAML files per role and location | Mellanie (prose), content team (tagging) | ~165-210 authored lines per template, 4x generation-expanded (D-028) |
| **Overhear** | NPC-to-NPC conversation scripts | Content authors | ~40-60 overheard lines across all social sites |
### Content file structure
Per the content directory design (D-057):
```
content/districts/sova-transit/
dialogue/
hub-dock-worker.yaml # Talk content: dock worker role at Terminal
hub-supervisor.yaml # Talk content: supervisor role at Terminal
bar-owner.yaml # Talk content: bar owner role at Last Shift
bar-regular.yaml # Talk content: regular role at Last Shift
...
monologue/
monologue-smuggler.yaml # Monologue: all smuggler lines for this district
monologue-detective.yaml # Monologue: all detective lines for this district
examines/
hub-objects.yaml # Examine Object: Terminal equipment, manifests
bar-objects.yaml # Examine Object: bar fixtures, notices
corridor-objects.yaml # Examine Object: maintenance panels, doors
observations/
npc-observations.yaml # Examine NPC: observation descriptions by NPC + knowledge tier
overheard/
hub-conversations.yaml # Overhear: Terminal NPC-to-NPC exchanges
bar-conversations.yaml # Overhear: Last Shift NPC-to-NPC exchanges
corridor-conversations.yaml # Overhear: corridor NPC-to-NPC exchanges
```
### Key authoring rules
1. **Talk requires dialogue pools.** Every NPC the player can Talk to needs dialogue lines tagged with access tier, trust level, and situation. FRIEND NPCs need the full 4-layer treatment (D-028). T3 NPCs need at minimum a greeting pool.
2. **Examine NPC requires observation descriptions.** Every NPC observable at mid range needs at least a surface-level observation description. T1/T2 NPCs need knowledge-tiered descriptions that reveal more as the player's confidence level increases.
3. **Overhear requires NPC-to-NPC conversation scripts.** These are independent of player dialogue pools. They fire when NPCs are near each other on their routines. Content must be written as fragmentary, overheardable exchanges -- not full conversations.
4. **Monologue is triggered by server events, not player choice.** Authors write monologue lines against specific triggers and prerequisites. The server decides when to fire them. Authors cannot assume the player will see monologue in any particular order -- prerequisite gates ensure logical sequencing.
5. **Examine Object descriptions should be character-aware.** The same terminal may show different information to the smuggler (cargo routing details) and the detective (access logs, anomaly flags). Use access tier tags to differentiate.
6. **All text comes from the server.** The client never loads or evaluates content files (D-048). Authors write content that the server selects and serves. The client renders what it receives.
---
*v0.1 specification. 7 verbs, single context-sensitive action, `verbs[]` architecture ready for N-verb expansion. Last updated: 2026-02-12.*
docs/design/npc-patterns/the-mirror.md
+631
View File
@@ -0,0 +1,631 @@
# THE MIRROR — NPC Pattern Specification
**Pattern Type:** Production-level Tier 1 (emotional depth, full 10-axis model)
**Design Principle:** Transparency as contrast mechanism
**Ticket:** #380
**Reference Implementation:** Naia Tamm (Sova Transit District v0.1)
---
## 1. Pattern Definition
THE MIRROR is the honest-character NPC pattern. No contradiction arc, no deep secret, no hidden agenda. MIRROR NPCs are transparent — what you see is what you get.
**Core mechanic:** Their role in the system is to make surrounding dishonesty visible by contrast. When everyone else is hiding something, the one person who isn't becomes the emotional anchor.
**Design payload:** In a game built around asymmetric information and deception detection, THE MIRROR is the NPC whose absence of deception becomes its own kind of content. The player learns to read tells on every other NPC — facial tics, evasive answers, spatial deviations. Encountering someone without tells is disorienting and emotionally significant.
**Thematic integration:** THE MIRROR connects directly to Gore's contentment axis and the game's central question: "Is this enough?" The MIRROR NPC typically answers: "It was enough — until everything around me started falling apart." Their contentment is genuine, their worry is genuine, their emotional reactions are genuine. That honesty makes everyone else's lies painful by proximity.
---
## 2. Mechanical Rules
### What MIRROR NPCs Do NOT Have
| Absent System | Why Missing | Content Signal |
|--------------|-------------|----------------|
| **No tells** | Tells imply deception or concealment. MIRROR has nothing to conceal from the player (though they may be uninformed about events around them). The absence of tells IS the tell — when the player has learned to read behavioral flags on every other NPC, encountering someone without them is the anomaly. | The player's monologue might note: "No hesitation. No evasion. Either she's telling the truth or she's the best liar I've ever met." The absence becomes noticeable. |
| **No secrets** (or only mundane surface-level ones) | The `secret_held` field is empty or contains only ordinary privacy (e.g., "worried about partner's late nights" — visible to anyone observant). No trust gates that reveal hidden criminal knowledge or conspiracies. | If a MIRROR has a "secret," it's one they'd share with a sympathetic stranger at a bar. There's no revelation moment where the player discovers the MIRROR was hiding something all along. |
| **No contradiction arc** | No phases, no discovery moment, no color shift from green to amber. The relationship with MIRROR is stable across the session. | The trust level may deepen (public → insider → peer), but there's no betrayal moment. The MIRROR you meet at minute 5 is the same MIRROR at minute 25. |
| **No trust-gated dialogue that changes the picture of who they are** | Trust progression reveals more FEELING, not more SECRETS. Deeper access tiers show emotional vulnerability, not concealed information. | At `public` tier: "I'm worried about Kael." At `peer` tier: "I don't know what to do. I love him, but I can't keep living like this." Same truth, deeper emotion. |
### What MIRROR NPCs DO Have
| Present System | Function | Why Essential |
|---------------|----------|---------------|
| **Full 10-axis profile** | Want, Secret/Vulnerability, Relationships 1-3, Tolerance, Routine, Information, Contentment, Personality, Tell (absent), Skills | MIRROR is not a shallow NPC. They're Tier 1 depth — full emotional complexity, just without deception. |
| **Tier 1 emotional depth despite pattern simplicity** | Rich personality, genuine reactions, emotional stakes in the world around them | The player trusts the MIRROR because the MIRROR is WORTH trusting. They're not a cardboard cutout labeled "honest person." They're a complete character whose honesty is part of their identity. |
| **Genuine emotional reactions to the world** | MIRROR NPCs respond to events around them with authentic worry, joy, confusion, anger — whatever fits their personality and situation | When the ring's actions threaten someone the MIRROR loves, the MIRROR's distress is real. The player FEELS it because they've learned this person doesn't perform emotions — they experience them. |
| **Emotional vulnerability as content** | The MIRROR's lack of deception makes them emotionally EXPOSED. They wear their worry visibly. They confide in friends. They react honestly to stress. | This vulnerability is load-bearing. The player becomes protective of the MIRROR. Threats to the MIRROR create player urgency. |
---
## 3. Content Requirements
**Total authored line budget:** 50-70 lines (Tier 1 MIRROR is slightly lower than FRIEND pattern's 70-100, because no contradiction arc content)
| Content Type | Line Count | Function |
|-------------|-----------|----------|
| **Dialogue** | 25-35 | Greetings (5), emotional state conversation (8-10), relationship discussion (5-7), situation responses (5-8), peer-tier vulnerability (3-5) |
| **Trust-gated dialogue** | 10-15 | Deeper emotional exposure at insider/peer tiers. Not secret revelations — emotional revelations. "I'm scared" vs "I'm worried." |
| **Unprompted lines** | 3-5 | MIRROR volunteers emotional state or asks for help. "Have you seen Kael today? I'm worried." |
| **Monologue triggers** | 10-15 per character | Player's internal reaction to MIRROR's honesty. Smuggler: guilt (if protecting someone the MIRROR loves). Detective: relief (finally someone not lying) + strategic value (MIRROR as witness to behavioral change). |
| **Voice sample** | 3-5 lines | Covering: baseline warm, worried, brittle (close to tolerance break) |
**No contradiction discovery content.** No tell observation content (because no tells). No phase-shift dialogue. This is where MIRROR saves budget relative to FRIEND.
### Dual-Lens Distribution
**Smuggler perspective (if MIRROR is connected to a ring member):** Emotional collateral. The MIRROR's worry creates guilt. The smuggler knows WHY the person the MIRROR loves is behaving strangely and can't say. Seeing the MIRROR's distress is a cost of operations.
**Detective perspective:** Potential witness + emotional anchor. A partner who suspects their loved one is hiding something is a classic entry point for investigation. The MIRROR knows behavioral patterns, routines, recent changes. The detective can cultivate trust by being sympathetic.
---
## 4. Tell System Rules
**Core principle:** MIRROR has no tells because tells imply deception or concealment.
### The Absence-as-Content Design
| What the Player Experiences | System State | Mechanical Expression |
|-----------------------------|--------------|---------------------|
| Early game: MIRROR seems ordinary | No behavioral flags set. No `contradiction_flagged`. No tell observations in monologue. | The player's training (from interacting with NPCs who DO have tells) hasn't fired. This feels normal. |
| Mid game: Player has learned to read other NPCs | The player has observed: Kael looks left when lying, Sera leaves when Torek arrives, Voss fidgets when questioned about manifests. | The player's mental model now expects tells. They're watching for them. |
| MIRROR interaction: No tells present | Player talks to MIRROR. MIRROR makes eye contact, answers directly, emotional state matches words. No spatial deviation, no topic deflection, no nervous tics. | The ABSENCE is striking. The player's monologue notes it: "No hesitation. She's either telling the truth or she's the best actor I've ever seen." |
| Resolution: Trust through transparency | If the player cross-references MIRROR's information with other sources, it checks out. MIRROR was telling the truth. | The player LEARNS that honesty exists in this world. That one person isn't performing. That becomes the emotional fulcrum for everything else. |
### How This Interacts with the Contradiction System
FRIEND NPCs have contradiction arcs: warmth → trust → doubt → conflict. Color shifts green to amber. The emotional payload is betrayal.
MIRROR NPCs have NO contradiction arc. Color remains green (or progresses public → insider → peer within green). The emotional payload is RELIEF and PROTECTION.
**Mechanical distinction:**
- FRIEND: `EntityKnowledge.state` transitions to `KnowledgeState::Contradicted` when tells accumulate.
- MIRROR: `EntityKnowledge.state` remains `KnowledgeState::Confirmed` or `KnowledgeState::Direct`. No contradiction flags ever set.
**Content signal:** The player's monologue about MIRROR evolves from neutral observation to active trust: "She's worried. Can't blame her — her partner is acting strange." → "I believe her. She doesn't know what's happening, but she's telling me everything she does know."
---
## 5. Dialogue Architecture
MIRROR dialogue follows the standard four-layer system (D-028) but with simplified secret-tier structure.
### Access Tiers (Layer 1)
| Tier | What MIRROR Shares | Example |
|------|-------------------|---------|
| **Public** | Observable emotional state, general information about their life/relationships | "I teach at the community school. The kids are doing well this term." |
| **Insider** | Specific worry, named relationships, genuine vulnerability | "Kael's been coming home late. Says it's work, but the schedule doesn't match. I don't know what to think." |
| **Peer** | Deep emotional exposure, requests for help or advice | "I'm scared, honestly. Not of Kael — of what Kael might be involved in. I don't know who else to talk to." |
| **Authority** (if detective) | Cooperation with investigation, willingness to provide information about loved one despite emotional cost | "If you think Kael is in trouble, I want to know. I'll help if I can. Just — please don't hurt him." |
**No secret tier that reveals hidden criminal knowledge.** The MIRROR doesn't have hidden criminal knowledge. The "secret" tier for MIRROR is the deepest emotional vulnerability, not a plot revelation.
### Trust Progression
```
Public (stranger) → Insider (acquaintance) → Peer (trusted friend) → Authority (if applicable)
What changes: Depth of emotional sharing, not type of information.
What doesn't change: The facts. MIRROR tells the same truth at all tiers. The emotion around it deepens.
```
**Example progression (Naia about Kael):**
- **Public:** "Kael works at the freight hub. Dock worker. We've been together six years."
- **Insider:** "Kael's been stressed lately. Late nights, evasive when I ask about it. I'm worried."
- **Peer:** "I love him. But I can't keep doing this — the not-knowing is killing me. I think something's wrong. I just don't know what."
- **Authority (detective):** "If you're investigating something at the hub, and if Kael is involved — I need to know. I'll help. I just need the truth."
Same story. Deeper emotion. No revelation that changes the player's understanding of who Naia is.
### Monologue Trigger Design
MIRROR NPCs trigger monologue focused on the PC's EMOTIONAL REACTION to the MIRROR's honesty, not on information extraction.
**Smuggler monologue about MIRROR (if MIRROR is connected to ring member):**
| Trigger | Monologue Content | Emotional Layer |
|---------|------------------|-----------------|
| Observe MIRROR waiting at bar | "Naia's at the bar again. Alone. Keeps looking at the door. I know where Kael is. I can't say." | Guilt. The smuggler's operational knowledge creates distance from the MIRROR's suffering. |
| MIRROR asks about loved one | "She asked if I'd seen Kael today. What do I say? 'Yeah, he's fine, just moving contraband?' Can't tell her. Can't lie to her face either." | Moral tension. The MIRROR's directness makes evasion feel worse. |
| MIRROR shares deep worry | "She's really scared. Not just worried — scared. And she has no idea what's actually happening. If she knew..." | Protective instinct + guilt. The smuggler wants to shield the MIRROR from both the truth and the consequences. |
**Detective monologue about MIRROR:**
| Trigger | Monologue Content | Emotional Layer |
|---------|------------------|-----------------|
| First conversation with MIRROR | "She's not hiding anything. I've interviewed enough people to know when someone's performing. She's genuinely worried." | Relief. In a district where everyone seems evasive, the MIRROR is a breath of fresh air. |
| MIRROR shares information about loved one | "She knows his routine better than anyone. The late nights, the evasions — she's been tracking them without realizing it. She's building my case for me." | Strategic recognition. The MIRROR is a witness to behavioral change — the best kind. |
| MIRROR asks for help | "She wants me to figure out what's wrong. Not to arrest anyone — just to know. That's... trust. Real trust." | Emotional weight. The detective realizes the investigation has personal stakes for the MIRROR. Success means breaking someone's heart. |
---
## 6. Naia Tamm — Reference Implementation
Naia Tamm is the v0.1 MIRROR NPC in Sova Transit District. Let me walk through how her 10-axis profile demonstrates each MIRROR rule.
### Core Identity
- **Name:** Naia Tamm
- **Age:** 33
- **Role:** Teacher, Station Sova community school
- **Social Site:** The Last Shift (Bar)
- **Triangle:** Triangle 4 — The Worried Partner (Naia - Kael - Sera)
### 10-Axis MIRROR Implementation
#### 1. Want (Tier 1 depth, no deception)
**Primary:** Understand what's happening with Kael.
Naia and Kael have been together 6 years. Kael started coming home late, evasive answers, money that doesn't match hours. Naia doesn't know about the ring. Naia knows the person they share a life with is hiding something. The not-knowing is worse than almost any truth.
**Secondary:** Protect the life they've built.
Naia wants it resolved without destroying everything — the home, the relationship, the stability. This is why Naia confides in Sera instead of confronting Kael directly: wants advice, not a fight.
**MIRROR rule demonstrated:** Want is ABOUT someone else's secret, not concealing Naia's own. Naia's motivation is transparent to the player from the first conversation.
#### 2. Secret / Vulnerability (surface-level only)
**Surface secret:** Worried about Kael. Visible to anyone who sees Naia's stress.
**Deep secret:** Naia confided in Sera about Kael's behavior. This is the action that set Sera's compliance check in motion, though Naia doesn't know that. Naia shared a personal worry with a trusted friend.
**Vulnerability:** Emotional exposure. Naia's worry is genuine, visible, exploitable.
**MIRROR rule demonstrated:** Naia's "secret" is that she confided in a friend. That's not a conspiracy — it's ordinary human behavior under stress. The vulnerability is EMOTIONAL, not criminal.
#### 3. Relationships (genuine, no hidden agendas)
**Kael Davan (partner, 6 years):** Deep love, growing anxiety. Doesn't question Kael's character — just Kael's honesty.
**Sera Venn (close friend, 10 months):** Genuine friendship. Trusts Sera as someone who can give perspective without gossip.
**Lera Sessik (bar acquaintance):** Social connection. Lera is warm to Naia — protective attention to someone visibly struggling.
**MIRROR rule demonstrated:** All relationships are exactly what they appear to be. No hidden resentments, no secret alliances, no ulterior motives. Naia likes who she likes for straightforward reasons.
#### 4. Tolerance Threshold (moderate, genuine limits)
**Moderate.** Patient — teaching station kids requires it. But patience is fraying. Every evasive answer from Kael chips at tolerance. If pushed to breaking point, Naia confronts Kael directly — which could trigger Kael's crisis, force Sera's hand, or give the detective an opening.
**MIRROR rule demonstrated:** Tolerance threshold is real and observable. No hidden resilience, no secret breaking point. What Naia says she can tolerate is what she can tolerate.
#### 5. Daily Routine (predictable, no spatial deviations)
- 07:00 - 15:00: Teaching (community school, Residential Radial A)
- 15:00 - 15:30: Commute back to Transit District
- 15:30 - 17:30: Bar (The Last Shift) — meets Sera, social time
- 17:30 - 22:00: Home. Waits for Kael.
- Late evenings: Alone in apartment, wondering where Kael is.
**MIRROR rule demonstrated:** Routine is stable, observable, doesn't hide anything. Naia is where she says she'll be. No unauthorized corridor meetings, no suspicious timing patterns. The routine itself is transparent.
#### 6. Information Inventory (knows what she knows, doesn't know what she doesn't)
**Knows:** Kael's normal routine (6 years of partnership), Kael's recent deviations (late nights, evasive answers), Sera's Commission role (knows Sera is a tech, not investigator), bar social dynamics, school community.
**Doesn't know:** Ring, smuggling, Kael's membership, manifest discrepancies, Sera's compliance check, the detective's investigation.
**MIRROR rule demonstrated:** Naia's knowledge state is exactly what it appears to be. She's not concealing anything she knows. She genuinely doesn't know the conspiracy exists. This makes her the perfect witness to BEHAVIORAL change without knowledge of CAUSE.
#### 7. Contentment (low and declining — thematically essential)
**Was content:** Stable job, loving partner, community. Now relationship anxiety is coloring everything. Teaching is harder when distracted. Bar visits tinged with worry. Home is where the absence lives.
**MIRROR rule demonstrated:** Contentment trajectory is VISIBLE and GENUINE. Naia isn't pretending to be happy or hiding dissatisfaction. Her emotional state is observable in her voice, her behavior, her routine changes (increased bar presence = avoiding empty apartment).
#### 8. Personality Traits (no performance, no mask)
- **Primary: Caring** — genuinely invested in other people's wellbeing
- **Secondary: Patient** — tolerates uncertainty longer than most, but not indefinitely
- **Tertiary: Perceptive** — reads emotional states well. Knows when Kael is lying even if can't prove it.
**MIRROR rule demonstrated:** These traits are REAL, not performed. Naia's caring isn't a manipulation tactic. Her perceptiveness makes her WORRIED (she knows something's wrong) but doesn't make her SUSPICIOUS (she trusts Kael's character even while doubting his honesty about the situation).
#### 9. Tell System (ABSENT — the design payload)
Naia's entry in the wiki lists three "tells":
| Tell | Trigger | Observable To |
|------|---------|---------------|
| Visible stress | Tired eyes, distracted conversation, checking lattice | Sera, Lera, Detective, bar regulars |
| Mentions Kael unprompted | Worry overflowing into conversation | Sera, Detective (if sitting nearby) |
| Increased bar presence | Coming more often, staying longer — avoiding empty apartment | Lera (notices pattern), Sera (recognizes coping mechanism) |
**CRITICAL MIRROR DISTINCTION:** These are NOT tells in the deception-detection sense. They're not "behavioral flags that signal concealment." They're GENUINE STRESS MARKERS. Naia is visibly worried because Naia IS worried. There's no contradiction between internal state and external behavior.
**The system perspective:** A TELL is a deviation that signals deception (Kael looks left when lying, Sera leaves when Torek arrives). Naia's behaviors are COPING MECHANISMS and EMOTIONAL EXPRESSIONS, not tells. The player's monologue doesn't say "She's hiding something." It says "She's really struggling."
**MIRROR rule demonstrated:** The absence of deception-tells IS the content. The player who has learned to read evasion on other NPCs will notice that Naia makes direct eye contact, answers questions fully, doesn't deflect topics, doesn't have spatial anomalies beyond her normal routine. That ABSENCE becomes the signal: "This person is being honest with me."
#### 10. Skill Set (civilian, no hidden capabilities)
**Occupational:** Teaching, community engagement, youth education, curriculum management.
**Combat tag:** NO. Entirely civilian.
**Lattice capability:** Baseline.
**MIRROR rule demonstrated:** No hidden skills, no secret training, no combat capability concealed behind a civilian facade. Naia is exactly what she presents: a teacher who's worried about her partner.
### Naia's Triangle Role (Emotional Center)
**Triangle 4: The Worried Partner (Naia - Kael - Sera)**
Naia is the emotional center. Naia's worry about Kael triggered Sera's investigation. Naia's trust in Sera makes Sera's concealment more painful. Naia connects the detective's investigation to Kael's personal life through Sera, through Naia's own observations, through the fact that a worried partner is the best witness to behavioral change.
**Why MIRROR works here:** Naia is UNINVOLVED in the conspiracy but CENTRAL to its emotional impact. She's the person both the smuggler and detective want to protect — and the person whose honest worry makes the smuggling operation's human cost visible. If Naia were lying, the triangle would be about competing deceptions. Because Naia is honest, the triangle is about the COST of everyone else's deceptions.
### Dual-Lens Implementation
**Smuggler perspective (if smuggler is Kael's friend):**
Naia is emotional collateral. The smuggler knows why Kael is busy and can't say. Seeing Naia's worry creates guilt. If Naia asks the smuggler about Kael, there's no good answer.
Sample monologue: *"Naia's at the bar again. Alone. Looking at the door every time it opens. I know where Kael is. I can't say."*
**Detective perspective:**
Naia is a potential source. A partner who suspects their loved one is hiding something is a classic entry point. The detective can cultivate Naia's trust by being sympathetic — listen, validate, gently probe. Naia might not know specifics, but knows Kael's routine, habits, recent changes better than anyone.
Sample monologue: *"The partner — Naia Tamm. Teacher. Visibly stressed. Keeps looking at the door. If Davan is involved, this partner knows something changed, even if they don't know what."*
**MIRROR payload in dual-lens:** SAME transparency, DIFFERENT player reaction. Smuggler feels guilt. Detective sees opportunity. Both recognize honesty. The MIRROR's transparency makes the two characters' different relationships to truth more visible by contrast.
---
## 7. Generator Template
For creating future MIRROR NPCs. This is the content pack structure for a MIRROR.
### Profile Fields (What to Fill)
```yaml
npc_id: "{name-lowercase}"
name: "{Full Name}"
age: {25-50 typical}
role: "{Occupation — typically civilian}"
social_site: "{Primary location}"
tier: 1 # MIRROR is Tier 1 depth
pattern: "MIRROR"
entanglement: "mundane" # MIRROR is never directly entangled
# 10-Axis Profile
want:
primary: "{Want that's ABOUT someone else or visible situation — no hidden agenda}"
secondary: "{Want that's protective or stabilizing — preserve what they have}"
secret:
surface: "{Visible emotional state — worry, stress, joy}"
deep: "{Ordinary privacy or emotional vulnerability — NOT conspiracy knowledge}"
vulnerability: "{Emotional exposure, not operational risk}"
relationships:
relationship_1:
target: "{Name}"
type: "{Genuine bond — no hidden resentment}"
history: "{How they met, why they care}"
tension: "{Current stress in relationship — external, not deceptive}"
relationship_2: ...
relationship_3: ...
tolerance: "{moderate/high — describe genuine limits, what would make them break}"
routine:
"{Time range}": "{Activity — predictable, no hidden meetings}"
# No spatial deviations, no unauthorized locations
information:
knows:
- "{Visible facts about their life}"
- "{Behavioral observations about loved ones}"
- "{Community knowledge}"
doesnt_know:
- "{Conspiracy details}"
- "{Hidden agendas of others}"
- "{Secret motivations}"
contentment: "{low/moderate — declining if connected to stressed loved one}"
personality:
primary: "{Caring, Honest, Warm — prosocial trait}"
secondary: "{Patient, Loyal, Perceptive — supportive trait}"
tertiary: "{Genuine emotional responsiveness}"
tell_system:
tells: [] # Empty array — MIRROR has no deception tells
behavioral_markers:
- "{Genuine stress marker — visible worry, not concealment}"
- "{Coping mechanism — increased social presence, routine changes}"
# These are NOT tells. They're genuine emotional expressions.
skills:
occupational: ["{Teaching}", "{Community work}", "{Civilian profession}"]
combat: false # MIRROR is never combat-capable
lattice: "baseline"
```
### Dialogue Content Pack Structure
```yaml
# File: districts/{location}/dialogue/{role}-mirror.yaml
- id: "{location}_d_001"
text: "Greeting — warm, open, no guardedness"
role: "{role}"
access: ["public"]
trust: "surface"
situation: ["greeting"]
mood: ["warm"]
- id: "{location}_d_002"
text: "Sharing worry — direct, no evasion"
role: "{role}"
access: ["public", "insider"]
trust: "surface"
situation: ["worried_inquiry"]
mood: ["anxious"]
- id: "{location}_d_010"
text: "Deep emotional vulnerability — peer tier"
role: "{role}"
access: ["peer"]
trust: "real" # Not 'secret' — MIRROR has no secrets tier content
situation: ["emotional_crisis"]
mood: ["desperate"]
# Monologue content (separate per character, per D-032)
# File: districts/{location}/monologue-smuggler.yaml
- id: "{location}_m_s_001"
text: "Smuggler feels guilt observing MIRROR's distress"
character: "smuggler"
trigger: "observe_npc"
prerequisite:
target.known_attributes.name: "{Name}"
target.known_attributes.emotional_state: "worried"
# File: districts/{location}/monologue-detective.yaml
- id: "{location}_m_d_001"
text: "Detective recognizes MIRROR as honest witness"
character: "detective"
trigger: "post_conversation"
prerequisite:
target.known_attributes.name: "{Name}"
target.known_attributes.honesty_assessment: "transparent"
```
### What Fields to Leave Empty
| Field | State | Why |
|-------|-------|-----|
| `tell_system.tells` | Empty array `[]` | MIRROR has no deception tells |
| `secret.criminal_knowledge` | Omit entirely | MIRROR doesn't have criminal secrets |
| `contradiction_arc` | Omit entirely | MIRROR has no contradiction phases |
| `access: ["authority"]` content | Minimal | Only if MIRROR cooperates with investigation — still no secret reveals |
| `trust: "secret"` tier content | Omit or minimal | MIRROR's deepest tier is emotional vulnerability, not plot revelation |
### What Makes a Good MIRROR Candidate
**Ideal MIRROR characteristics:**
1. **Emotionally connected to an entangled NPC** — Partner, sibling, close friend of someone in the conspiracy. Their honesty makes the conspiracy's human cost visible.
2. **Civilian role** — Teacher, bartender, service worker. Not institutional (Commission, Security). Not criminal. Represents ordinary life.
3. **Observable worry or stress** — MIRROR's emotional state is VISIBLE because they don't hide it. Their distress is the content.
4. **Genuine perceptiveness** — MIRROR notices behavioral changes in loved ones but doesn't KNOW the cause. "Something's wrong" without "I know what's wrong." Perfect witness to change without knowledge of crime.
5. **Prosocial personality** — Caring, loyal, honest. The player trusts them BECAUSE they're trustworthy. The game needs at least one person whose goodness is real.
**Poor MIRROR candidates:**
- NPCs with institutional power (they'd have investigative tools)
- NPCs with hidden skills or backgrounds (contradicts transparency)
- NPCs who are themselves criminals (MIRROR must be genuinely uninvolved)
- NPCs without emotional stakes in the district (MIRROR's honesty is load-bearing only if they CARE)
---
## 8. Design Notes: Why MIRROR Isn't Boring
**The risk:** A character with no secrets, no tells, no contradiction arc sounds mechanically thin. "Just an honest person" doesn't feel like a gameplay system.
**Why it works:**
### The Contrast Mechanic
MIRROR is mechanically interesting BECAUSE of the surrounding systems. In a game where:
- Every FRIEND has a contradiction arc (warmth → doubt → conflict)
- Every CATALYST disrupts equilibrium through action
- Every SYSTEM embodies corrupted institutions
- Every WITNESS carries dangerous knowledge
- Every GHOST applies pressure from off-screen
...the ONE character with no deception becomes the ANCHOR. The player learns to expect complexity, hidden agendas, behavioral tells. MIRROR subverts that learned expectation by being EXACTLY what they appear to be.
**Mechanical payload:** The observation pipeline (Ozzie + Gestalt + Paula's unified system) trains the player to notice tells. The MIRROR's ABSENCE of tells is itself an observation event. The player's monologue fires: "No evasion. No deflection. Either honest or the best liar I've encountered." The uncertainty itself creates tension until the player verifies the honesty.
### The Emotional Fulcrum
When the ring's actions threaten the MIRROR (Naia worrying about Kael, potentially losing her relationship and stability), the player FEELS it because they've learned to believe this person.
**Smuggler:** The guilt of watching an innocent person suffer because of your operations. You can't tell her. You can't protect her. You're part of the cause of her pain.
**Detective:** The weight of knowing your investigation will break this person's life. Success means revealing that her partner is a criminal. The MIRROR trusted you to find answers — and the answers will destroy her.
**That's the design payoff.** MIRROR's transparency isn't boring — it's the emotional investment that makes the conspiracy's consequences real. The player cares about protecting the MIRROR because the MIRROR is the one person in the district who isn't performing, isn't hiding, isn't playing angles. That honesty makes them precious.
### The Trust Anchor
In a district where everyone has an agenda, the MIRROR is the person the player can RELY on. When the smuggler needs to know what's happening with Kael, Naia will tell the truth as she understands it. When the detective needs a witness, Naia will cooperate fully. The MIRROR's reliability is itself a strategic asset — but one that comes with emotional cost (using an innocent person's trust).
**System interaction:** The trust-gated gossip system (D-028 Layer 3, #171) means NPCs share information at different access tiers. With most NPCs, the player wonders: "Is this real or are they steering me?" With MIRROR, that question is answered: "This is real. She's telling me everything she knows." That certainty is VALUABLE in a game built on asymmetric information.
### The Replay Dimension
On second playthrough, playing the other character, the MIRROR's honesty becomes even more visible. The player KNOWS Naia isn't involved. They see her worry from a different angle:
- **Playthrough 1 (smuggler):** "I know why Kael is busy. Naia's worry is collateral damage."
- **Playthrough 2 (detective):** "Naia's worry is my opening. She's the way in."
Same honesty. Different use. The player's knowledge that Naia is a MIRROR (from first playthrough) makes the second playthrough's interaction with her more complex: "I know she's honest. How do I use that? Should I?"
**Replay payload:** MIRROR transparency survives across playthroughs. FRIEND contradictions change (different seed might assign FRIEND to different NPC). MIRROR remains honest regardless of seed. That constancy is mechanically useful for teaching the player to recognize honesty — and ethically complex when the player knows they'll exploit it.
---
## 9. Implementation Checklist
For developers implementing a MIRROR NPC:
### ECS Component Setup
```rust
// MIRROR NPCs use standard NPC components but with specific flags
NPCProfile {
pattern: NPCPattern::Mirror,
tier: ContentTier::One, // MIRROR is always Tier 1
entanglement: EntanglementLevel::Mundane, // Never directly criminal
}
TellSystem {
tells: vec![], // Empty — no deception tells
behavioral_markers: vec![
BehavioralMarker::VisibleStress,
BehavioralMarker::EmotionalExpression,
// These are NOT tells — they're genuine coping mechanisms
],
}
ContradictionState {
has_contradiction_arc: false, // MIRROR never contradicts
relationship_phase: RelationshipPhase::Stable, // No phase transitions
}
SecretInventory {
criminal_secrets: vec![], // Empty
personal_vulnerabilities: vec![
Vulnerability::EmotionalExposure,
Vulnerability::UninformedWitness,
],
}
```
### Dialogue System Configuration
```rust
// MIRROR dialogue has simpler trust structure
DialogueProfile {
access_tiers: vec![
AccessTier::Public, // General conversation
AccessTier::Insider, // Named relationships, specific worries
AccessTier::Peer, // Deep emotional vulnerability
AccessTier::Authority, // (Optional) Cooperation with investigation
],
trust_gates: vec![
TrustGate { tier: TrustTier::Surface, access: [Public, Insider] },
TrustGate { tier: TrustTier::Real, access: [Peer, Authority] },
// NO TrustTier::Secret — MIRROR doesn't have secret-tier content
],
}
```
### Knowledge System Integration
```rust
// Observer's knowledge state about MIRROR
EntityKnowledge {
state: KnowledgeState::Confirmed, // Or Direct. Never Contradicted.
known_attributes: {
"honesty_assessment": "transparent",
"reliability": "solid",
"facade_status": "N/A", // MIRROR has no facade
"emotional_state": "worried", // Visible, genuine
"threat_to_position": "none", // MIRROR is not operationally dangerous
"moral_standing": "innocent", // Never shifts to complicit
},
contradiction_flagged: None, // MIRROR never flags contradictions
}
```
### Monologue Event Triggers
```rust
// When player observes MIRROR, monologue focuses on emotional reaction
if npc.pattern == NPCPattern::Mirror {
if observer.has_learned_to_read_tells() {
// Trigger "absence of tells" observation
monologue_event = MonologueEvent {
trigger: MonologueTrigger::ObserveNPC,
target: npc.entity_id,
filter_tags: ["honesty_recognition", "emotional_anchor"],
};
}
if npc.emotional_state == EmotionalState::Distressed
&& observer.knows_cause_of_distress()
&& !observer.can_share_knowledge() {
// Trigger guilt/conflict monologue (if smuggler)
monologue_event = MonologueEvent {
trigger: MonologueTrigger::ObserveNPC,
target: npc.entity_id,
filter_tags: ["guilt", "emotional_collateral"],
};
}
}
```
### Testing Validation
**MIRROR correctness tests:**
1. **No contradiction flags should ever set** for MIRROR entity.
2. **EntityKnowledge.state should never transition to Contradicted** for MIRROR.
3. **TellSystem.tells should remain empty array** throughout session.
4. **Monologue events about MIRROR should NOT include tags:** `"deception"`, `"evasion"`, `"suspicious"`.
5. **Monologue events about MIRROR SHOULD include tags:** `"honesty"`, `"transparency"`, `"genuine"`, `"emotional_anchor"`.
6. **Trust progression should not unlock "secret" tier content** — only surface/real tiers should have content.
---
## Summary
**THE MIRROR pattern is the emotional foundation of the game's moral complexity.**
In a world where everyone is hiding something, the one person who isn't becomes the player's anchor — and their vulnerability. The MIRROR's transparency is mechanically expressed through the ABSENCE of systems (no tells, no contradiction arc, no secrets) that are present on every other NPC. That absence becomes visible through contrast.
**The design works because:**
- The observation pipeline trains the player to expect deception
- The MIRROR subverts that expectation through consistent honesty
- The player's verification of honesty (cross-referencing MIRROR's info against other sources) creates trust
- That trust makes the MIRROR's emotional stakes real
- Threats to the MIRROR create urgency and moral weight
**Naia Tamm demonstrates every rule:** She has full Tier 1 depth, genuine emotional complexity, visible stress, transparent relationships, predictable routine, and zero deception. Her honesty makes Kael's secrets painful, Sera's concealment costly, and the investigation's human consequences visible.
**For content authors:** MIRROR is mechanically simple (no contradiction content) but emotionally complex (full 10-axis depth). The 50-70 line budget focuses on genuine emotional expression, trust progression through vulnerability, and dual-lens player reaction. The MIRROR is the person both characters want to protect — and the person who makes the cost of deception real.
---
**End Pattern Specification.**
**Files referenced:**
- `/var/home/jeroenschweitzer/Projects/settled-reach/copy/docs/wiki/npcs/naia-tamm.md` — Reference implementation
- `/var/home/jeroenschweitzer/Projects/settled-reach/copy/decisions/content.md` — D-024 (10-axis model), D-028 (dialogue architecture), D-029 (entanglement ratio), D-032 (separate monologue pools), D-034 (THE FRIEND pattern), D-035 (tag taxonomy)
- `/var/home/jeroenschweitzer/Projects/settled-reach/copy/docs/workshops/v01-content-scoping/round2-gestalt.md` — Pattern definitions and NPC mapping
- `/var/home/jeroenschweitzer/Projects/settled-reach/copy/docs/workshops/v01-gap-analysis/round2-gestalt.md` — Unified observation system, character identity integration
docs/design/v0.1-wow-moments-checklist.md
+275
View File
@@ -0,0 +1,275 @@
# v0.1 Wow Moment Content Checklist
**Source:** D-039 (6 wow moments for 30-minute session)
**Ticket:** #400 (v0.1 wow moment content checklist)
**Last updated:** 2026-02-12
---
## Overall Completion Status
| # | Moment | Content | Implementation | Status |
|---|--------|---------|----------------|--------|
| 1 | Arrival | 1 of 5 deliverables ready | 3 of 8 tickets done | Not started |
| 2 | The Character's Eye | 0 of 4 deliverables ready | 1 of 6 tickets done | Not started |
| 3 | THE FRIEND's Contradiction | 0 of 5 deliverables ready | 1 of 7 tickets done | Not started |
| 4 | The Divergence Reveal | 0 of 4 deliverables ready | 0 of 5 tickets done | Not started |
| 5 | The News Ticker Gut-Punch | 0 of 3 deliverables ready | 0 of 4 tickets done | Not started |
| 6 | The Quiet Moment | 0 of 2 deliverables ready | 0 of 3 tickets done | Not started |
**Summary:** 1 of 23 content deliverables ready. 5 of 33 implementation tickets done. All 6 moments currently blocked by upstream authoring and architecture work, with #261 (Dual Lens Authoring Guide) as the critical path root.
---
### Moment 1: Arrival
**Description**: Station hum playing, NPCs already moving on routines, first monologue chime fires. The player's first impression: "Where am I? This feels real." The world is already alive before the player does anything.
**Timing**: Minute 0-1 of session
**Content deliverables:**
- [ ] Opening monologue lines -- smuggler arrival (10-15 tightly sequenced lines, per #299)
- [ ] Opening monologue lines -- detective arrival (10-15 tightly sequenced lines, per #300)
- [ ] Diegetic tutorial monologue lines -- per character (8-10 lines each teaching movement, fog, sound, NPC interaction, insert; per #330)
- [x] Audio asset specification defined (D-038: `amb_station_base.ogg`, `sfx_monologue_chime.ogg`)
- [ ] Audio asset files -- station ambient + monologue chime (2 of the 8 minimum viable files; per #327)
**Implementation tickets:**
- [x] #229 -- Define ObserverSnapshot structure (done)
- [x] #280 -- Define core types: ObserverSnapshot, PlayerInput, SimBridge (done)
- [x] #294 -- Create UI shell stubs: HUD, minimap, monologue display (done)
- [ ] #88 -- Daily routine system: DailyRoutine component, time-based transitions (backlog)
- [ ] #101 -- Routine execution system: schedule-driven NPC movement (backlog)
- [ ] #119 -- Monologue event generation - server: trigger on perception events (backlog)
- [ ] #122 -- Monologue display - client: text display, timed queue management (backlog)
- [ ] #327 -- Audio asset set: 8 minimum viable files via Stable Audio Open (backlog)
**Content tickets:**
- [ ] #259 -- First 5 minutes experience design (backlog)
- [ ] #299 -- Opening hook content: smuggler first 5 minutes (backlog, blocked by #261, #310, #309, #315)
- [ ] #300 -- Opening hook content: detective first 5 minutes (backlog, blocked by #261, #310, #309, #315)
- [ ] #330 -- Diegetic tutorial monologue lines: per character (backlog, blocked by #299, #300)
- [ ] #255 -- Client audio manager (backlog)
- [ ] #125 -- Close-range stereo audio - client (backlog, blocked by #255)
**Dependencies:**
- #261 (Dual Lens Authoring Guide) must be complete before opening hook content can be authored
- #310 (Character voice speech patterns) must exist for consistent voice in opening lines
- Monologue server system (#119, #120) must be implemented to deliver lines
- Monologue client display (#122) must be implemented to render lines
- NPC routine system (#88, #101) must be running so NPCs are already moving at session start
- Audio manager (#255) and audio assets (#327) must exist for station hum and monologue chime
**Status**: Not started -- all content deliverables blocked by #261 (Dual Lens Authoring Guide). UI shell stubs exist; core architecture defined. Audio assets not yet produced.
---
### Moment 2: The Character's Eye
**Description**: While the player explores, their character's monologue flags something the player did not notice -- an NPC routine deviation, a behavioral anomaly, a spatial detail. The urgent monologue chime fires. The player realizes: "My character is smarter than me." This is the moment the monologue system proves its worth as a perception mechanic, not just flavor text.
**Timing**: Minute 5-15 of session
**Content deliverables:**
- [ ] Observation monologue lines -- per character (within #399 monologue pool: ~100 lines per character, categories include NPC routine commentary, contradiction hints, environmental observations)
- [ ] NPC routine deviation content -- at least 1 NPC must deviate from established routine in a way the monologue system can flag
- [ ] Tell observation lines for Kael Davan (8 lines across 4 tell categories; part of #297 content pack)
- [ ] Tell observation lines for Sera Venn (part of #298 content pack)
**Implementation tickets:**
- [x] #112 -- Observer visibility query (done: given observer entity, return visible entities and tiles)
- [ ] #239 -- Observation event generator: compare snapshot against knowledge, emit ObservationEvents (backlog)
- [ ] #243 -- Routine deviation detection: compare NPC position vs known routine pattern (backlog, blocked by #88)
- [ ] #119 -- Monologue event generation - server: trigger on perception events (backlog, blocked by #239)
- [ ] #120 -- Monologue line pool system: tag-based line selection (backlog)
- [ ] #90 -- Personality and tell system: TellSystem with 5 categories, v0.1 rendered as monologue text (backlog)
**Content tickets:**
- [ ] #399 -- Monologue content pool: minimum viable ~200 lines (backlog, blocked by #261, #382)
- [ ] #297 -- THE FRIEND: Kael Davan full profile + content pack, includes tell observation lines (backlog, blocked by #261, #310)
- [ ] #298 -- THE FRIEND: Sera Venn full profile + content pack, includes tell observation lines (backlog, blocked by #261, #310)
**Dependencies:**
- Observation event pipeline (#239) must compare snapshot against knowledge graph to detect anomalies
- Routine deviation detection (#243) must be running so NPCs can break patterns
- Monologue pool system (#120) must support tag-based selection with `observe_anomaly` and `observe_npc` triggers
- Urgent monologue chime audio asset (`sfx_monologue_chime_urgent.ogg`) from #327
- D-059 monologue display constraints: `observe_anomaly` is priority 1 (highest), ensuring it interrupts lower-priority monologue
**Status**: Not started -- observation pipeline (#239) and routine deviation detection (#243) are the key server blockers. Content blocked by #261 and #382.
---
### Moment 3: THE FRIEND's Contradiction
**Description**: THE FRIEND NPC -- Kael Davan (smuggler path) or Sera Venn (detective path) -- is observed in the wrong place at the wrong time. The urgent monologue chime fires. The character's internal voice registers the contradiction. If the player asks the FRIEND about it, they deflect. The player feels: "I trusted you. What are you doing?" This is D-027 success criterion #3: the player names an NPC they felt conflicted about.
**Timing**: Minute 20-25 of session
**Content deliverables:**
- [ ] Kael Davan full content pack: ~91 authored lines across 5 arc phases (comfort, first crack, contradiction, confrontation, contaminated trust) per D-058 template and #297
- [ ] Sera Venn full content pack: ~70-100 authored lines with equivalent phase structure, per #298
- [ ] Contradiction discovery monologue: 1 critical monologue line per character per FRIEND (the wow moment #3 trigger; highest-stakes single line in the project)
- [ ] Confrontation dialogue: 8-12 lines per FRIEND for post-contradiction conversation with deflection
- [ ] Spatial staging data: Kael in Corridor B-7 during shift transition; Sera avoiding Torek Lintar in specific location with time window
**Implementation tickets:**
- [x] #366 -- Observer snapshot knowledge integration (done)
- [ ] #239 -- Observation event generator: detect spatial anomaly (FRIEND at contradiction location) (backlog)
- [ ] #243 -- Routine deviation detection: flag FRIEND breaking established pattern (backlog, blocked by #88)
- [ ] #304 -- Entity color system spec: relationship-to-player mapping including green-to-amber shift on PersonOfInterest transition (backlog, blocked by #303)
- [ ] #119 -- Monologue event generation - server: trigger urgent monologue on contradiction observation (backlog)
- [ ] #120 -- Monologue line pool system: prerequisite-gated line selection for friend_arc phase (backlog)
- [ ] #168 -- Tagged line pool structure: dialogue pool with trust-gated access (backlog)
**Content tickets:**
- [ ] #297 -- THE FRIEND: Kael Davan full profile + content pack (backlog, blocked by #261, #310)
- [ ] #298 -- THE FRIEND: Sera Venn full profile + content pack (backlog, blocked by #261, #310)
- [ ] #332 -- Contradiction arc design document: reusable FRIEND pattern (backlog, blocked by #297, #298)
- [ ] #318 -- THE FRIEND visual treatment spec: earned visual detail, green-to-amber phase shift (backlog, blocked by #303, #297, #298)
**Dependencies:**
- FriendArc state machine must be implemented (Warmth -> Trust -> Doubt -> Conflict per workshop Section 6)
- Knowledge graph contradiction detection: `ToldBy` entry conflicting with `DirectObservation` entry must trigger `Contradicted` state (D-041 notes this ships Sprint 3+)
- 5 atomic state changes in one tick: knowledge graph update, FriendArc phase advance, RelationshipState change (Friendly -> PersonOfInterest), monologue trigger (urgent), entity color shift (green -> amber)
- `InteractionLog` component must exist to track interaction count for Warmth->Trust threshold (>=3 interactions + >=600 ticks)
- All content from Warmth and Trust phases must exist so the player has built attachment before the contradiction fires
- NOTE: No dedicated FriendArc implementation ticket exists yet -- **ticket needed** for the FriendArc state machine and contradiction observation system
**Status**: Not started -- this is the most complex moment. Requires the full FRIEND content pipeline plus FriendArc state machine implementation. Content blocked by #261. Server-side contradiction detection deferred to Sprint 3+ per D-041.
---
### Moment 4: The Divergence Reveal
**Description**: On second playthrough with the other character, the player enters the same room and sees different entity colors, different NPC names in monologue (first-name vs surname), different internal observations. The world is structurally identical but perceptually inverted. The player realizes: "I was only seeing HALF of this." This moment does not require new content -- it requires that all existing content is properly dual-lens authored.
**Timing**: Second playthrough, minute 5-10 of session
**Content deliverables:**
- [ ] Dual Lens Authoring Guide: the root document defining how the same world plays differently through smuggler vs detective perspective (#261)
- [ ] All dual-lens content for first location (Terminal): smuggler sees colleagues, detective sees subjects of investigation -- same NPCs, different access tiers, different monologue pools (within #399, #297, #298)
- [ ] Mirror moment design document: 10-15 paired observations, same event triggering different monologue per character (#329)
- [ ] PC-as-NPC content: the other character exists as an NPC with routine entries and observation monologue lines (#401)
**Implementation tickets:**
- [ ] #182 -- Divergent starting knowledge: smuggler knows criminals/workplace gossip, detective knows institutional info/case files (backlog)
- [ ] #183 -- Divergent relationships: same NPCs, different trust levels per character (backlog)
- [ ] #304 -- Entity color system spec: same NPC shows different color per character's relationship state (backlog, blocked by #303)
- [ ] #120 -- Monologue line pool system: `character` tag as hard partition per D-032 ensures completely separate pools (backlog)
- [ ] #90 -- Personality and tell system: same tells visible to both characters but interpreted differently via monologue (backlog)
**Content tickets:**
- [ ] #261 -- Dual Lens Authoring Guide: critical path root, blocks all dual-lens content (backlog, Sprint 3 P0)
- [ ] #329 -- Mirror moment design document: 10-15 paired observations (backlog, blocked by #297, #298)
- [ ] #399 -- Monologue content pool: must contain separate pools per character (backlog, blocked by #261, #382)
- [ ] #401 -- PC-as-NPC content authoring: 5-7 routine entries + 3-5 observation lines per character (backlog, Sprint 5, blocked by #381, #383, #297, #298)
- [ ] #381 -- PC-as-NPC unified spec (backlog)
**Dependencies:**
- #261 (Dual Lens Authoring Guide) is the root dependency -- every piece of dual-lens content flows through it
- Character voice registers (D-056 / #310) must be defined so smuggler and detective monologue feel distinct
- D-032 (separate monologue pools per character) must be enforced in the monologue line pool system
- Entity color system (#304) must support per-character relationship state mapping
- Divergent starting knowledge (#182) and divergent relationships (#183) must be seeded at game start
- This moment only works after the player has completed one full playthrough -- no implementation needed for "second playthrough" detection; the content itself creates the revelation
**Status**: Not started -- #261 is the critical path root (blocks 9+ downstream tickets). Divergent knowledge/relationship tickets in backlog. Mirror moment document not yet started.
---
### Moment 5: The News Ticker Gut-Punch
**Description**: A news ticker headline scrolls at the bar (The Last Shift). Both characters see the same headline. Their internal monologue reacts in opposite ways -- the smuggler reads threat, the detective reads opportunity (or vice versa). Three words of ticker text plus two monologue reactions create the most efficient demonstration of asymmetric information in the game. D-306 calls this "cheapest wow-per-word in the project."
**Timing**: Variable (player must visit The Last Shift bar). Most likely minute 10-20.
**Content deliverables:**
- [ ] News ticker headline pool: ~20 dual-lens headlines for Meridian feed (freight data, Assembly politics, local infrastructure, Commission advisories; per #395 and #306)
- [ ] Dual monologue reactions per headline: each headline needs a smuggler reaction and a detective reaction (within #399 monologue pool, tagged with `trigger: observe_object` or similar)
- [ ] Ticker display format and visual spec (part of #316 text display hierarchy spec, bar-world-space rendering per Stig's UI BOM)
**Implementation tickets:**
- [ ] #306 -- News ticker / Meridian feed content: 20-30 lines (backlog, blocked by #302)
- [ ] #395 -- News ticker headline pool: ~20 dual-lens headlines (backlog, Sprint 4)
- [ ] #316 -- Text display hierarchy spec: 4 content pipelines including ticker (backlog)
- [ ] Ticker renderer (client): world-space text display at bar location -- covered in Stig's UI BOM (1 scene + 1 script, P1). NOTE: No dedicated implementation ticket exists yet for the ticker client renderer -- **ticket needed**
**Content tickets:**
- [ ] #306 -- News ticker / Meridian feed content (backlog, blocked by #302 Sova Texture Appendix)
- [ ] #395 -- News ticker headline pool with dual-lens reactions (backlog, Sprint 4)
- [ ] #399 -- Monologue content pool: must include ticker-reaction monologue lines (backlog)
**Dependencies:**
- ObserverSnapshot v3 includes `ticker_headlines` field (D-054) -- protocol support designed
- Bar spatial layout (#312) must place the ticker in a visible location within The Last Shift
- Sova Texture Appendix (#302) must exist for setting-consistent ticker language
- Monologue system must fire `observe_object` trigger when player reads a ticker headline
- D-032 separate pools ensure smuggler and detective get different reactions to the same headline
- NOTE: The `ticker_headlines` field exists in the ObserverSnapshot v3 design but no server-side ticket exists for populating it -- **ticket needed** for server-side ticker headline system
**Status**: Not started -- content blocked by #302 (Sova Texture Appendix). No client renderer ticket exists. Server-side ticker system needs a ticket.
---
### Moment 6: The Quiet Moment
**Description**: The player idles in a corridor. No interaction, no event. After a pause, an unprompted reflective monologue fires -- the character thinking about their life, their friend, what they are doing here. The player feels: "I care about this person." This moment proves that the monologue system works as atmosphere, not just as a game mechanic. It makes the character feel like a person, not a cursor.
**Timing**: Variable (fires on `time_idle` trigger after player has been stationary for a threshold duration). Most likely in corridors between locations.
**Content deliverables:**
- [ ] Idle/reflective monologue lines: minimum 2 lines per character (per D-039), ideally 4-6 per character within the ~200 line monologue pool (#399). Must use `trigger: time_idle`. Content should reference THE FRIEND, the setting, or the character's personal situation.
- [ ] Corridor ambient context: monologue lines should reference corridor sensory details (span gate hum, ventilation whistle, recycled air) from #302 Sova Texture Appendix
**Implementation tickets:**
- [ ] #119 -- Monologue event generation - server: must support `time_idle` trigger type (backlog, blocked by #239)
- [ ] #120 -- Monologue line pool system: must select lines tagged with `time_idle` trigger after idle threshold (backlog)
- [ ] #122 -- Monologue display - client: must render reflective lines with standard (non-urgent) chime (backlog)
**Content tickets:**
- [ ] #399 -- Monologue content pool: must include `time_idle` triggered lines per character (backlog, blocked by #261, #382)
- [ ] #302 -- Sova Texture Appendix: sensory details needed for corridor reflective monologue (backlog)
**Dependencies:**
- Monologue trigger system must implement `time_idle` as one of the 9 trigger types (D-035)
- Idle detection: server must track how long the player character has been stationary and emit a `time_idle` trigger event after threshold
- `time_idle` is priority 9 (lowest in D-059 priority ordering) -- it should only fire when nothing else is happening, which is exactly the design intent
- Monologue chime audio (`sfx_monologue_chime.ogg`) from #327 -- the standard chime, not the urgent variant
- Prerequisite system should gate some idle monologue behind having met THE FRIEND (so the reflective moment references someone the player knows)
**Status**: Not started -- idle trigger implementation needed in server monologue system. Content blocked by #261 and #382.
---
## Cross-Cutting Dependencies
These items block multiple wow moments and represent the highest-leverage work:
| Dependency | Blocks Moments | Ticket | Status |
|------------|---------------|--------|--------|
| Dual Lens Authoring Guide | 1, 2, 3, 4, 5, 6 | #261 | Backlog (Sprint 3 P0, critical path root) |
| Character voice speech patterns | 1, 2, 3, 4 | #310 | Backlog |
| Monologue event generation - server | 1, 2, 3, 6 | #119 | Backlog |
| Monologue line pool system | 2, 3, 4, 6 | #120 | Backlog |
| Monologue display - client | 1, 2, 3, 6 | #122 | Backlog |
| Monologue content pool (~200 lines) | 2, 4, 5, 6 | #399 | Backlog (Sprint 4) |
| Observation event generator | 2, 3 | #239 | Backlog |
| Routine deviation detection | 2, 3 | #243 | Backlog |
| NPC daily routine system | 1, 2, 3 | #88 | Backlog |
| Audio asset set (8 files) | 1, 2, 6 | #327 | Backlog |
| Entity color system spec | 3, 4 | #304 | Backlog |
| Sova Texture Appendix | 5, 6 | #302 | Backlog |
## Missing Tickets Identified
The following gaps were found during this analysis -- tickets need to be created:
1. **FriendArc state machine implementation** (server): 4-phase state machine (Warmth -> Trust -> Doubt -> Conflict) with explicit transition triggers, atomic 5-state-change on contradiction observation, `InteractionLog` component. Blocks Moment 3. Workshop Section 6 (round2-tracking.md) has the full spec.
2. **Server-side ticker headline system**: Populate `ticker_headlines` field in ObserverSnapshot v3. Select headlines from content pool, deliver through bridge. Blocks Moment 5.
3. **Ticker client renderer**: World-space text display at The Last Shift bar location. 1 scene + 1 script per Stig's UI BOM (P1). Blocks Moment 5.
4. **Idle detection system** (server): Track player character stationary duration, emit `time_idle` trigger after configurable threshold. May be folded into #119 (Monologue event generation) but should be explicitly scoped. Blocks Moment 6.
---
*Compiled for ticket #400. Cross-references: D-039 (wow moments), D-027 (vertical slice criteria), D-034 (THE FRIEND), D-032 (separate monologue pools), D-035 (tag taxonomy), D-038 (audio scope), D-041 (knowledge graph), D-054 (ObserverSnapshot v3), D-056 (PC voice registers), D-058 (FRIEND content pack template), D-059 (monologue display constraints).*
docs/wiki/npcs/devra.md
+9
View File
@@ -116,4 +116,13 @@ The supply brokering business isn't just cover — it's real income and real soc
---
## Pattern / Motivation
**Pattern (System A):** THRESHOLD — Devra is the ring's gatekeeper. Access to the operation's logistics, to Sabel's supply chain, to Nils's strategic direction — all of it runs through Devra. She is the person you go through or you do not go. For the detective, reaching the ring's operational layer means getting past Devra's cover. For the smuggler, coordination with the upstream supply means working through Devra's scheduling.
**Motivation (System B):** HANDLER — Devra manages operations from above. She conveys Nils's strategy, coordinates with Sabel, manages internal ring logistics, and delivers escalation demands to Voss and Kael. She applies pressure downward on behalf of the off-stage authority. She does not run day-to-day dock operations — she manages the people who do.
**Composition read:** THRESHOLD + HANDLER creates the obstacle with authority: "You go through her or you don't go." Devra gates access to the ring (THRESHOLD) while applying top-down operational pressure (HANDLER). This dual function makes her the most structurally important ring member on-station — she is both the wall and the hand pushing people against it. Her competence makes her formidable; her ambition (she could run this better than Nils) makes her interesting. The player who tries to reach the ring's inner workings must reckon with Devra twice: once as a barrier, once as a manager.
---
**Cross-References:** [Renn](renn.md), [Pell](pell.md), [Lera Sessik](lera-sessik.md), [Sabel](sabel.md)
docs/wiki/npcs/drin.md
+9
View File
@@ -45,4 +45,13 @@ Drin exists as the **compromised institutional node** in Triangle 2 (Worried Kno
---
## Pattern / Motivation
**Pattern (System A):** SYSTEM — Drin is the dock inspector. He IS the inspection system — his reports, his sign-offs, his presence at the freight bays constitute the institutional process that is supposed to catch irregularities. When Drin is compromised, the system itself is corrupted. This is not a person failing at a job; it is an institution rotting from within.
**Motivation (System B):** TURNCOAT — Drin's loyalty has shifted under coercion. The gambling debt to Harek created a vulnerability that the ring exploits through omission: Drin does not actively smuggle, he simply fails to inspect. His turncoat status is passive — he was turned not by ideology or ambition but by debt and avoidance.
**Composition read:** SYSTEM + TURNCOAT creates institutional rot: "The inspection system is broken because the inspector is broken." Drin embodies the institution (SYSTEM) and has betrayed it (TURNCOAT), meaning the legitimate oversight mechanism and the criminal exploitation of it exist in the same person. For the detective, cracking Drin means cracking the system — his compromise is the proof that the hub's operations are not what they appear. For the smuggler, keeping Drin quiet means keeping the system working in the ring's favor. The composition is the most mechanically productive in the set because the same NPC serves inverted functions for the two player characters.
---
**Cross-References:** [Harek](harek.md), [Maret Korr](maret-korr.md), [Voss](voss.md), [Pell](pell.md)
docs/wiki/npcs/harek.md
+9
View File
@@ -110,4 +110,13 @@ Drin owes Harek money from card games — a significant sum that Drin can't easi
---
## Pattern / Motivation
**Pattern (System A):** ANCHOR — Harek is physically present and complacent. He is at the bar playing cards, drinking, enjoying a stable life he has no desire to change. His contentment is genuine and unexamined — Harek has enough, wants nothing more, and has never thought to ask whether "enough" is the right question. The ANCHOR pattern means Harek represents the social floor that the investigation disturbs.
**Motivation (System B):** HANDLER — Harek uses leverage as a structural mechanism. The gambling debt Drin owes him creates a power dynamic that the ring exploits, even though Harek did not design it as a tool. A security officer with a dock inspector who owes him favors is useful — and that usefulness has been noticed by people with operational intent. Harek holds the lever without fully understanding the machine it operates.
**Composition read:** ANCHOR + HANDLER creates the unconscious lever: "Harek doesn't know his card games built a weapon." Harek's complacent contentment (ANCHOR) generated a tool of coercion (HANDLER) without deliberate intent. He did not set out to compromise Drin — he won card games, extended credit, and maintained a social dynamic that happened to produce leverage. The ring noticed and exploited the result. This structural role is what makes Harek uniquely important: he bridges the bar (social presence, card games, community standing) and the hub (security authority, patrol knowledge, access awareness). His HANDLER motivation means the debt functions as a mechanism, not a personal project — Harek does not use it for personal gain beyond the social capital of being owed. But the structural consequence is that Drin's inspection negligence, which enables the entire smuggling operation's dock-side processing, traces back to Harek's card table. For the detective, connecting Harek's debt to Drin's compromised inspections is the path from social observation to operational evidence. For the smuggler, Harek's complacency is an asset — as long as Harek stays comfortable and unquestioning, the leverage on Drin remains stable and invisible.
---
**Cross-References:** [Drin](drin.md), [Lera Sessik](lera-sessik.md), [Torek Lintar](torek-lintar.md), [Voss](voss.md)
docs/wiki/npcs/index.md
+20 -20
View File
@@ -4,26 +4,26 @@
## Roster Table
| # | Name | Role | Social Site | Tier | Entanglement | Triangles |
|---|------|------|-------------|------|--------------|-----------|
| 1 | **Kael Davan** | Dock Worker | Hub + Ring | **Tier 1 (FRIEND)** | Entangled | Hub Power, Worried Partner |
| 2 | **Sera Venn** | Commission Field Tech | Bar | **Tier 1 (FRIEND)** | Mundane | Worried Partner |
| 3 | Arvo Voss | Shift Supervisor | Hub | Tier 2 | Mundane | Hub Power, Worried Knowledge |
| 4 | Lera Sessik | Bar Owner | Bar | Tier 2 | Mundane | Bar Tensions |
| 5 | Torek Lintar | Dock Worker / Bar Regular | Bar + Hub | Tier 2 | Mundane | Bar Tensions |
| 6 | Devra Talsen | Ring Coordinator | Ring + Bar | Tier 2 | Entangled | (Referenced, not triangle member in v0.1) |
| 7 | Maret Korr | Freight Scheduler | Hub | Tier 2 | Mundane | Worried Knowledge |
| 8 | Resha Neven | New Hire Dock Worker | Hub | Tier 2 | Mundane | (Background tension, not formal triangle) |
| 9 | Naia Tamm | Teacher (Kael's Partner) | Bar | Tier 2 | Mundane | Worried Partner |
| 10 | Drin Rosta | Maintenance Tech | Hub | Tier 3 | Flat | Worried Knowledge, Informant Question |
| 11 | Sess Kolvur | Bartender | Bar | Tier 3 | Flat | None |
| 12 | Olin Tavren | Drifter / New Arrival | Bar | Tier 3 | Flat | Bar Tensions |
| 13 | Renn Harsk | Courier | Ring + Hub | Tier 2 | Entangled | Informant Question |
| 14 | Pell Torssen | Wavering Ring Member | Ring | Tier 2 | Entangled | Informant Question |
| 15 | Harek Valde | Off-Duty Security | Bar + Hub | Tier 2 | Mundane | None (external pressure on Triangle 2) |
| 16 | Sabel Hersk | Off-Station Fence | Ring (off-station) | Tier 3 | Flat | None (off-station) |
| 17 | Tav Merik | Lookout | Ring + Hub | Tier 3 | Flat | None |
| 18 | Nils Davan | Ring Coordinator (Off-Stage) | Ring (off-station) | Off-Stage | Entangled | Hub Power |
| # | Name | Role | Social Site | Tier | Pattern | Motivation | Entanglement | Triangles |
|---|------|------|-------------|------|---------|------------|--------------|-----------|
| 1 | **Kael Davan** | Dock Worker | Hub + Ring | **Tier 1 (FRIEND)** | FRIEND | OPERATOR | Entangled | Hub Power, Worried Partner |
| 2 | **Sera Venn** | Commission Field Tech | Bar | **Tier 1 (FRIEND)** | FRIEND | WITNESS | Mundane | Worried Partner |
| 3 | Arvo Voss | Shift Supervisor | Hub | Tier 2 | SYSTEM | OPERATOR | Mundane | Hub Power, Worried Knowledge |
| 4 | Lera Sessik | Bar Owner | Bar | Tier 2 | ANCHOR | OPERATOR | Mundane | Bar Tensions |
| 5 | Torek Lintar | Dock Worker / Bar Regular | Bar + Hub | Tier 2 | CATALYST | CIVILIAN | Mundane | Bar Tensions |
| 6 | Devra Talsen | Ring Coordinator | Ring + Bar | Tier 2 | THRESHOLD | HANDLER | Entangled | (Referenced, not triangle member in v0.1) |
| 7 | Maret Korr | Freight Scheduler | Hub | Tier 2 | WITNESS | SKEPTIC | Mundane | Worried Knowledge |
| 8 | Resha Neven | New Hire Dock Worker | Hub | Tier 2 | CATALYST | CIVILIAN | Mundane | (Background tension, not formal triangle) |
| 9 | Naia Tamm | Teacher (Kael's Partner) | Bar | Tier 2 | MIRROR | CIVILIAN | Mundane | Worried Partner |
| 10 | Drin Rosta | Maintenance Tech | Hub | Tier 3 | SYSTEM | TURNCOAT | Flat | Worried Knowledge, Informant Question |
| 11 | Sess Kolvur | Bartender | Bar | Tier 3 | ANCHOR | CIVILIAN | Flat | None |
| 12 | Olin Tavren | Drifter / New Arrival | Bar | Tier 3 | CATALYST | CIVILIAN | Flat | Bar Tensions |
| 13 | Renn Harsk | Courier | Ring + Hub | Tier 2 | THRESHOLD | OPERATOR | Entangled | Informant Question |
| 14 | Pell Torssen | Wavering Ring Member | Ring | Tier 2 | CATALYST | TURNCOAT | Entangled | Informant Question |
| 15 | Harek Valde | Off-Duty Security | Bar + Hub | Tier 2 | ANCHOR | HANDLER | Mundane | None (external pressure on Triangle 2) |
| 16 | Sabel Hersk | Off-Station Fence | Ring (off-station) | Tier 3 | GHOST | OPERATOR | Flat | None (off-station) |
| 17 | Tav Merik | Lookout | Ring + Hub | Tier 3 | SYSTEM | CIVILIAN | Flat | None |
| 18 | Nils Davan | Ring Coordinator (Off-Stage) | Ring (off-station) | Off-Stage | GHOST | HANDLER | Entangled | Hub Power |
**Entanglement breakdown**:
- **Tier 1 (THE FRIEND)**: 2 NPCs (Kael, Sera) — 1 entangled, 1 mundane
docs/wiki/npcs/kael-davan.md
+9
View File
@@ -394,4 +394,13 @@ Born on Station Sova. Grew up in the freight district — child of logistics wor
---
## Pattern / Motivation
**Pattern (System A):** FRIEND — Kael is a trust anchor whose relationship with the player character is the emotional core of the smuggler's experience. The FRIEND pattern means Kael's betrayal (or the smuggler's betrayal of Kael) carries maximum emotional weight.
**Motivation (System B):** OPERATOR — Kael runs ring cargo at the dock level. He routes containers, manages handoffs, coordinates timing. His day-to-day function is operational execution, not strategic direction or pressure application.
**Composition read:** FRIEND + OPERATOR creates the identity betrayal: "I was your friend AND your co-conspirator." The player trusted Kael as a person (FRIEND) while relying on Kael as a functional colleague (OPERATOR). When the contradiction surfaces — Kael meeting an unauthorized contact, attempting to exit — the betrayal cuts both relationships simultaneously. The warmth was real. The operational reliability was real. The secret exit attempt violates both, and the player cannot separate the personal loss from the professional one.
---
**End Kael Davan Profile**. This is the full Tier 1 production depth. Sera Venn (detective's FRIEND) follows the same structure with different contradiction mechanics.
docs/wiki/npcs/lera-sessik.md
+9
View File
@@ -114,4 +114,13 @@ Lera has been behind this bar for 18 years. She's watched people come and go, re
---
## Pattern / Motivation
**Pattern (System A):** ANCHOR — Lera embodies contentment through her bar. Eighteen years behind the same counter, the same regulars, the same rhythms. She represents the stable social infrastructure that the investigation threatens to disrupt. Her version of "Is this enough?" is answered by the bar itself — yes, if nobody asks hard questions.
**Motivation (System B):** OPERATOR — Lera runs The Last Shift. She manages inventory, serves customers, facilitates the social space, and maintains the delicate balance between profit and discretion. Her function is operational: keeping the bar viable, which means keeping the grey-market spending flowing without attracting institutional attention.
**Composition read:** ANCHOR + OPERATOR creates profitable blindness: "Is this enough? Yes — if I don't look." Lera's contentment (ANCHOR) is sustained by her operational competence (OPERATOR) — she runs the bar well enough that the moral compromises stay manageable. The willful ignorance is not laziness; it is active maintenance of a life she built. When the investigation arrives, it threatens both the emotional equilibrium and the business model simultaneously. Lera must choose between the comfort she's anchored to and the truth she's been operating around.
---
**Cross-References:** [Torek Lintar](torek-lintar.md), [Harek](harek.md), [Sera Venn](sera-venn.md), [Naia Tamm](naia-tamm.md), [Olin](olin.md)
docs/wiki/npcs/maret-korr.md
+9
View File
@@ -114,4 +114,13 @@ Maret didn't ask to see the discrepancies. She sees them because that's her job.
---
## Pattern / Motivation
**Pattern (System A):** WITNESS — Maret's v0.1 function is defined by what she has seen, not her institutional role. The player approaches Maret because she carries information — manifest discrepancies, bay allocation anomalies, the correlation between Voss's schedule adjustments and cargo irregularities. WITNESS describes her story function: she observed something she was not meant to observe.
**Motivation (System B):** SKEPTIC — Maret doubts the numbers. Not passively — she is actively re-checking manifests, cross-referencing gate logs, building a private discrepancy log. Her skepticism is data-driven and escalating. She has not yet acted on her doubt, but the doubt itself makes her dangerous because it means she might.
**Composition read:** WITNESS + SKEPTIC creates dangerous knowledge: "She saw something and she can't stop questioning it." Maret did not choose to witness the discrepancies (WITNESS) — her job put the data in front of her. But her response is not passive acceptance; it is systematic doubt (SKEPTIC). The combination means Maret is a time bomb with her own fuse: she is gathering evidence not because anyone asked her to, but because her meticulous nature will not let her stop. For the detective, Maret is the cooperative witness who has already done half the work. For the smuggler, Maret is the threat you cannot neutralize without revealing why the numbers matter.
---
**Cross-References:** [Voss](voss.md), [Drin](drin.md), [Resha](resha.md), [Naia Tamm](naia-tamm.md)
docs/wiki/npcs/naia-tamm.md
+9
View File
@@ -114,4 +114,13 @@ Naia teaches station kids. Has a community, a reputation, a daily rhythm. Whatev
---
## Pattern / Motivation
**Pattern (System A):** MIRROR — Naia has no contradiction arc, no secret, no hidden agenda. She is exactly what she appears to be: a teacher worried about her partner. The MIRROR pattern means Naia reflects the truth of the district back at the player without distortion. In a world where everyone is hiding something, Naia's honesty is both a relief and a weapon — her transparency makes the concealment around her more painful.
**Motivation (System B):** CIVILIAN — Naia is uninvolved in any conspiracy or operation. She teaches station kids, worries about Kael, confides in Sera, and goes to the bar. Her civilian status is not a simplification — it is the source of her narrative power. The damage done to Naia is devastating precisely because she did nothing to invite it.
**Composition read:** MIRROR + CIVILIAN creates honest transparency surrounded by liars: "The one person not lying — surrounded by liars." Naia's reflective honesty (MIRROR) combined with her complete uninvolvement (CIVILIAN) means she is the emotional baseline against which all deception is measured. When events drag Naia into the conspiracy through Kael's ring involvement and Sera's concealment, the damage is devastating because Naia was genuine. For the smuggler, Naia is the face of guilt — the person whose life is being destroyed by what the smuggler helps maintain. For the detective, Naia is a source whose value comes from her innocence, and cultivating that innocence as an investigative asset carries its own moral cost.
---
**Cross-References:** [Kael Davan](kael-davan.md), [Sera Venn](sera-venn.md), [Lera Sessik](lera-sessik.md)
docs/wiki/npcs/nils-davan.md
+3 -5
View File
@@ -72,12 +72,10 @@ Nils is the **escalation pressure source**. He pushes for higher volume, tighter
## Pattern / Motivation
**GHOST + HANDLER**
**Pattern (System A):** GHOST — Nils is physically absent from Sova Transit District. His power is felt exclusively through intermediaries — lattice messages to Kael, relayed orders through Devra, operational pressure that cascades through the entire ring. No one outside the inner circle (Kael, Devra) has met Nils in person. The GHOST pattern means Nils shapes events without being present to confront, cultivate, or observe.
**Motivation (System B):** HANDLER — Nils manages ring operations from above. He sets volume targets, applies escalation pressure, makes personnel decisions, and drives the strategic direction that everyone on-station must execute. The ring's growth imperative comes from Nils; the consequences of that imperative fall on others.
- **GHOST**: Physically absent from Sova Transit District. Power felt exclusively through intermediaries — lattice messages, relayed orders, operational pressure. No one outside the ring's inner circle (Kael, Devra) has met Nils in person.
- **HANDLER**: Manages ring operations from above. Sets volume targets, applies escalation pressure, makes personnel decisions. The ring's strategic direction comes from Nils; execution is delegated.
**Core motivation**: Growth. Nils wants the operation to scale. More volume, more profit, more reach. This puts him in tension with every on-station operator who prefers stability (Devra, Voss, Kael). Nils either doesn't see or doesn't care that escalation increases risk for people on the ground.
**Composition read:** GHOST + HANDLER creates absent authority applying pressure through intermediaries. Nils's physical absence (GHOST) combined with his top-down management style (HANDLER) means the ring's most dangerous decisions are made by someone who never sees their consequences. He pushes for higher volume without experiencing the anxiety it creates in Voss, the risk it imposes on Kael, or the instability it breeds in Pell. For the smuggler, Nils is the unseen boss whose demands shape every operational day. For the detective, Nils is the name that surfaces late in the investigation — the coordinator behind the coordinator, the authority that explains why everyone on-station is afraid.
---
docs/wiki/npcs/olin.md
+9
View File
@@ -44,4 +44,13 @@ In Triangle 3 (Bar Tensions), Olin's questions and Torek's spending create a com
---
## Pattern / Motivation
**Pattern (System A):** CATALYST — Olin's arrival forces the district to evaluate a new variable. His questions about work schedules, shift structures, and hub operations create productive uncertainty. Every established character must assess Olin — friend or threat, innocent or planted — and that assessment itself disrupts the stable social equilibrium.
**Motivation (System B):** CIVILIAN — Olin is tagged CIVILIAN for v0.1, meaning no confirmed hidden agenda. At Tier 3 with 10-15 lines of content, there is not enough depth to resolve Olin's ambiguity. The CIVILIAN tag is the safe designation — if Olin is promoted to Tier 2 in v0.2, the hidden motivation can be revealed through dynamic tier promotion.
**Composition read:** CATALYST + CIVILIAN creates ambiguous disruption: "Friend or threat? The question IS the disruption." Olin forces evaluation (CATALYST) without providing resolution (CIVILIAN). The game deliberately does not confirm whether Olin is a scout, an informant, a rival operator, or genuinely just looking for work. This unresolvable ambiguity is the point — both player characters must spend attention and resources assessing a variable that may never pay off. The disruption is in the assessment itself, not in any action Olin takes.
---
**Cross-References:** [Lera Sessik](lera-sessik.md), [Torek Lintar](torek-lintar.md)
docs/wiki/npcs/pell.md
+9
View File
@@ -115,4 +115,13 @@ Pell is an informant looking for a handler. The detective is the obvious candida
---
## Pattern / Motivation
**Pattern (System A):** CATALYST — Pell's wavering forces the entire ring into crisis response. His anxiety, missed meetings, and irregular schedule compel other ring members to react — Renn reports suspicion, Devra increases surveillance, Nils considers action. Pell is a disruption vector whose instability threatens the operation's equilibrium.
**Motivation (System B):** TURNCOAT — Pell is actively considering cooperation with authorities. His loyalty is shifting under pressure — the escalating volume, the tightening risk, the paranoia that the ring's growth has invited institutional attention. Unlike Drin's passive turncoat status (omission), Pell's is deliberate: he is looking for a handler.
**Composition read:** CATALYST + TURNCOAT creates maximum instability: "When Pell breaks, everything moves." Pell's disruption (CATALYST) is driven by a deliberate shift in loyalty (TURNCOAT), making him the ring's existential threat. The other catalysts (Torek, Resha, Olin) disrupt accidentally; Pell's disruption is the consequence of a conscious decision to betray. For the smuggler, Pell is the biggest internal threat — the decision to support, report, or manage Pell defines the operation's future. For the detective, finding Pell before the ring acts on Renn's suspicion means gaining the case's keystone witness. The timing is everything, and Pell's anxiety is the countdown.
---
**Cross-References:** [Renn](renn.md), [Drin](drin.md), [Devra](devra.md), [Harek](harek.md)
docs/wiki/npcs/renn.md
+9
View File
@@ -112,4 +112,13 @@ Renn came into the ring through Nils — a friend-of-a-friend introduction. He's
---
## Pattern / Motivation
**Pattern (System A):** THRESHOLD — Renn controls the physical movement of contraband through the district's corridors. He is the gatekeeper of cargo flow — the person who moves product between freight bay, storage, and handoff points. Tracing Renn means tracing the route. Blocking Renn means blocking the operation's physical pipeline.
**Motivation (System B):** OPERATOR — Renn runs courier routes. He times runs through maintenance corridors, coordinates with Devra's schedule, and executes the physical logistics of moving contraband. His function is execution — hands-on, spatial, operational.
**Composition read:** THRESHOLD + OPERATOR creates the physical gatekeeper: "Renn moves the product. Trace Renn, find the route." Renn controls access to the smuggling route (THRESHOLD) and personally executes the movement (OPERATOR). Unlike Devra's organizational gatekeeping, Renn's threshold is physical — he is the body in the corridor with the contraband. For the detective, catching Renn in a dead spot with cargo is the most direct path to blowing the operation. For the smuggler, Renn's reliability on courier runs is what keeps the pipeline flowing. His vulnerability is his visibility: a person moving cargo through restricted corridors during off-hours is the most catchable link in the chain.
---
**Cross-References:** [Pell](pell.md), [Devra](devra.md), [Kael Davan](kael-davan.md), [Drin](drin.md)
docs/wiki/npcs/resha.md
+9
View File
@@ -110,4 +110,13 @@ Resha asks questions because she's learning. Some of those questions — about l
---
## Pattern / Motivation
**Pattern (System A):** CATALYST — Resha's innocent questions about locked bays, irregular schedules, and unmanifested containers force the ring's infrastructure into defensive reactions. Every question she asks creates pressure on Voss and Kael. She is a disruption vector — not by intent, but by the simple act of trying to learn her job.
**Motivation (System B):** CIVILIAN — Resha is not investigating, not scheming, not cooperating with anyone. She is a new hire trying to understand procedures. Her questions are genuine, not strategic. The CIVILIAN motivation means the disruption is accidental — born of earnestness, not suspicion.
**Composition read:** CATALYST + CIVILIAN creates innocent disruption: "She just asked. Everyone flinched." Resha disrupts (CATALYST) through pure curiosity (CIVILIAN), which makes her impossible to manage through normal channels. You cannot tell a new hire to stop asking procedural questions without explaining why — and the explanation is the thing that must stay hidden. The system is so compromised that learning it honestly is itself a threat. For the smuggler, Resha is a variable that requires constant steering. For the detective, Resha is a fresh pair of eyes whose observations carry no political filtering — whatever Resha noticed, she noticed because it was genuinely anomalous.
---
**Cross-References:** [Voss](voss.md), [Kael Davan](kael-davan.md), [Maret Korr](maret-korr.md)
docs/wiki/npcs/sabel.md
+9
View File
@@ -42,4 +42,13 @@ Sabel is the **upstream connection** — the thread that leads from the local sm
---
## Pattern / Motivation
**Pattern (System A):** GHOST — Sabel is off-station, physically absent from the play area. The player does not interact with Sabel directly in any meaningful way. Sabel's power is felt through supply chain influence — origin codes on manifests, timing confirmations via lattice, references in ring members' dialogue. The GHOST pattern means Sabel shapes events from elsewhere without being present to confront or cultivate.
**Motivation (System B):** OPERATOR — Sabel runs the supply chain. Transit confirmations, shipment scheduling, cargo preparation — all operational execution from a remote position. Sabel's function is logistics, not strategy or pressure. The supply keeps coming regardless of what happens on Sova.
**Composition read:** GHOST + OPERATOR creates distant machinery: "Sabel shapes events from elsewhere." Sabel's absent power (GHOST) is exercised through operational execution (OPERATOR) — a supply chain that functions without requiring Sabel's physical presence on-station. For the detective, Sabel is a data phantom: origin codes, transit records, freight patterns that point to an upstream source the detective cannot reach within the vertical slice. For the smuggler, Sabel is the reliable engine that keeps the product flowing — professional, impersonal, and indifferent to the human consequences on the ground. Sabel's coldness is narrative content: the ring is disposable to its supplier.
---
**Cross-References:** [Devra](devra.md), [Renn](renn.md)
docs/wiki/npcs/sera-venn.md
+9
View File
@@ -394,4 +394,13 @@ Born on Krenn Prime surface. Grew up in a mid-sized settlement where the Commiss
---
## Pattern / Motivation
**Pattern (System A):** FRIEND — Sera is a trust anchor whose relationship with the detective is the emotional core of the detective's experience. The FRIEND pattern means Sera's concealment carries maximum emotional weight because the detective relied on her as both a personal ally and an institutional peer.
**Motivation (System B):** WITNESS — Sera carries unreported evidence. She ran an unauthorized compliance check and found manifest discrepancies tied to Kael's shifts. Her motivation in the system is defined by what she has seen and is concealing, not by any operational role in the ring.
**Composition read:** FRIEND + WITNESS creates the concealment betrayal: "I was your friend AND I was hiding evidence." The detective trusted Sera as a safe harbor in an unfamiliar district (FRIEND) while Sera was sitting on the exact data the detective needed (WITNESS). The contamination is retrospective — every helpful tip Sera shared is recontextualized once the concealment surfaces. Was her helpfulness genuine, or was it compensation? The answer is both, and that ambiguity is the emotional payload.
---
**End Sera Venn Profile**. This is the full Tier 1 production depth. Parallels Kael Davan (smuggler's FRIEND) with different contradiction mechanics: cumulative pattern recognition vs. single spatial observation, institutional concealment vs. operational security breach, slow doubt vs. sudden alarm.
docs/wiki/npcs/sess.md
+9
View File
@@ -44,4 +44,13 @@ Sess is the **ambient observer** — the social wallpaper who notices everything
---
## Pattern / Motivation
**Pattern (System A):** ANCHOR — Sess embodies quiet contentment behind the bar. His version of "Is this enough?" is answered by routine: pour drinks, observe, go home. Sess represents the stable social atmosphere that the district's conflicts play out against. His contentment is not ignorance — it is a deliberate choice to keep his life simple.
**Motivation (System B):** CIVILIAN — Sess is uninvolved. He has no agenda, no conspiracy, no operational role. He bartends. He sees things. He does not act on what he sees. The CIVILIAN motivation means Sess is social wallpaper with observational depth — present everywhere, invested in nothing.
**Composition read:** ANCHOR + CIVILIAN creates atmospheric texture: "Sees everything, says nothing — because nothing's wrong with HIS life." Sess's contentment (ANCHOR) is sustained by his disengagement (CIVILIAN). He observes the district's tensions from behind the bar without being pulled into them. This makes him a unique resource for patient players: Sess has seen patterns that no one else has assembled, but unlocking that information requires repeated investment in a character who has no reason to share. The v0.2 potential is significant — NOBODY tier promotion could reveal that Sess's quiet contentment conceals an observation post no one suspected.
---
**Cross-References:** [Lera Sessik](lera-sessik.md)
docs/wiki/npcs/tav.md
+9
View File
@@ -46,4 +46,13 @@ Tav is the **peripheral ring member** — the person at the lowest level of the
---
## Pattern / Motivation
**Pattern (System A):** SYSTEM — Tav follows ring procedure. He is the lookout — positioned at corridor intersections during operations, watching for patrols, signaling the courier. His function is institutional: he is a cog in the ring's operational machinery, executing a defined role within a defined process. SYSTEM describes his mechanical participation, not his personal investment.
**Motivation (System B):** CIVILIAN — Tav is the lowest rung. He watches the door. That is the whole job. He does not understand the operation above him, does not participate in planning, and has minimal connection to the ring's strategy. The CIVILIAN motivation reflects his peripheral engagement — he was told it mattered, and he believed it.
**Composition read:** SYSTEM + CIVILIAN creates the lowest operational rung: "Tav watches the door. That's the whole job." Tav participates in the system (SYSTEM) without understanding it (CIVILIAN). He is the ring member most likely to be caught and least likely to have useful information — he knows routes and timing, not names or structure. For the detective, catching Tav reveals a thread but not the tapestry. For the smuggler, Tav is a reliable set of eyes whose nervous energy makes him effective on watch but vulnerable to pressure. The v0.2 potential is in what Tav represents: a young person trapped in a role he barely understands, doing dangerous work because someone told him it was important.
---
**Cross-References:** [Renn](renn.md), [Devra](devra.md)
docs/wiki/npcs/torek-lintar.md
+9
View File
@@ -110,4 +110,13 @@ Torek buys rounds. Tips well. Has a new jacket. Latest lattice accessories. He's
---
## Pattern / Motivation
**Pattern (System A):** CATALYST — Torek's visible spending disrupts the district's equilibrium. His generosity at the bar, his new accessories, his round-buying — all of it forces other characters to react, evaluate, and adapt. Torek doesn't intend to cause disruption; his lifestyle IS the disruption.
**Motivation (System B):** CIVILIAN — Torek is uninvolved in any conspiracy. Whether his money comes from the ring, a side hustle, or an inheritance, Torek himself is simply living. He is not scheming, not investigating, not operating. He is spending money and enjoying himself. The CIVILIAN motivation means the disruption is accidental — a signal without intent.
**Composition read:** CATALYST + CIVILIAN creates the accidental signal: "He doesn't know he's a liability." Torek's disruption (CATALYST) comes from innocence (CIVILIAN), not from deliberate action. This makes him harder to manage — you cannot negotiate with someone who does not know they are a problem. For the smuggler, Torek is a financial tell that cannot be silenced without revealing why it matters. For the detective, Torek is a spending pattern that could mean anything. The ambiguity is load-bearing precisely because Torek himself does not have the answer.
---
**Cross-References:** [Lera Sessik](lera-sessik.md), [Olin](olin.md), [Harek](harek.md), [Sera Venn](sera-venn.md)
docs/wiki/npcs/voss.md
+9
View File
@@ -117,4 +117,13 @@ Voss is the shift supervisor. Nils Davan (Kael's older sibling, ring coordinator
---
## Pattern / Motivation
**Pattern (System A):** SYSTEM — Voss is the institutional authority at the logistics hub. His shift schedule is the operational machinery that enables the smuggling operation. He represents the legitimate system that has been co-opted: the schedule runs, the manifests process, the handoffs happen — all through the shift supervisor's authority.
**Motivation (System B):** OPERATOR — Voss runs the schedule. He processes manifests, manages personnel, creates coverage windows. His function is operational execution of the machinery he controls, not top-down pressure or strategic direction. He is middle management: competent, procedural, operating the system.
**Composition read:** SYSTEM + OPERATOR creates corrupted machinery: "The system works — for the wrong people." Voss IS the institutional process (SYSTEM) and he actively runs it (OPERATOR), meaning the legitimate logistics infrastructure and the criminal operation share the same human engine. For the detective, following the manifest trail leads to the shift supervisor's schedule — the system itself is the evidence. For the smuggler, Voss is the mechanism that keeps the operation running, and his resentment toward Nils is the gear most likely to grind.
---
**Cross-References:** [Kael Davan](kael-davan.md), [Maret Korr](maret-korr.md), [Drin](drin.md), [Resha](resha.md)