settled-reach/content/_meta/npc-authoring-style-guide.md

NPC Authoring Style Guide

The Settled Reach | v0.1 Content Authoring Handbook Ticket: #379 | Sprint: 5 Authors: Gestalt (mechanical constraints), Mellanie (voice rules), Paula (tier templates, relationship design), Ozzie (anchor lines) Cross-references: D-024, D-025, D-028, D-029, D-032, D-034, D-035, D-036, D-039, D-050, D-056, D-059 Schemas: content/_schema/npc-profile.schema.json, dialogue-pool.schema.json, monologue-pool.schema.json

---

1. Purpose

This document is the single reference for all NPC content authoring in The Settled Reach. Every dialogue line, monologue line, NPC profile, and content pack must conform to the rules here. The guide is used by:

• Content authors writing dialogue pools, monologue pools, NPC profiles, and content packs
• Reviewers checking tag compliance, voice consistency, and mechanical correctness
• The generation pipeline (v0.2+) as the style constraint set for expanded content
• Future content authors (including AI-assisted generation) as the specification they must satisfy

If it's not in this guide, it's not a rule. If it contradicts a decision document, the decision document wins.

---

2. Content Tiers

Every NPC has a tier (D-023, D-024). The tier determines content depth and authoring budget.

Tier 1: Conspiracy-Entangled (Full Depth)

Attribute	Value
Pattern	FRIEND, MIRROR, or CATALYST
Motivation	Any
Line budget	70-100 lines (FRIEND), 50-70 lines (MIRROR/CATALYST)
Profile depth	Full 10-axis, all fields populated
Relationship arcs	Multi-phase (3-5 phases for FRIEND), stable-deep for MIRROR
Dual-lens notes	Required on profile and every 5th dialogue line minimum
FRIEND content	Hand-authored only. No generation expansion.
Triangle membership	1-3 triangles
Trust-gated dialogue	All three tiers (surface, real, secret) populated

v0.1 Tier 1 NPCs: Kael Davan (FRIEND/OPERATOR), Sera Venn (FRIEND/WITNESS), Naia Tamm (MIRROR/CIVILIAN)

Tier 2: Template-Situated (Social Context)

Attribute	Value
Pattern	ANCHOR, THRESHOLD, SYSTEM, GHOST, or REMNANT
Motivation	Any
Line budget	20-40 lines
Profile depth	Full 10-axis, supporting fields optional
Relationship arcs	Single phase, stable. Access tier shifts possible but not required.
Dual-lens notes	Required on profile; optional on individual lines
Triangle membership	1-2 triangles
Trust-gated dialogue	Surface required. Real recommended. Secret optional.

v0.1 Tier 2 NPCs (D-050 canonical): Voss (SYSTEM/OPERATOR), Lera Sessik (ANCHOR/OPERATOR), Torek Lintar (CATALYST/CIVILIAN), Devra (THRESHOLD/HANDLER), Maret Korr (WITNESS/SKEPTIC), Resha (CATALYST/CIVILIAN), Drin (SYSTEM/TURNCOAT), Renn (THRESHOLD/OPERATOR), Pell (CATALYST/TURNCOAT), Harek (ANCHOR/HANDLER)

Tier 3: Filler (Atmosphere)

Attribute	Value
Pattern	NOBODY
Motivation	CIVILIAN
Line budget	5-10 lines
Profile depth	Minimal: canonical_id, display_name, tier, pattern, motivation, want, routine
Relationship arcs	None
Dual-lens notes	Not required
Triangle membership	None
Trust-gated dialogue	Surface only

v0.1 Tier 3 NPCs (D-050 canonical): Sess (ANCHOR/CIVILIAN), Olin (CATALYST/CIVILIAN), Sabel (GHOST/OPERATOR), Tav (SYSTEM/CIVILIAN)

Off-stage: Nils Davan (GHOST/HANDLER) — referenced in dialogue, effects visible through other NPCs, rarely or never directly encountered.

Design note: The 30% flat population (D-029) is the noise floor. These NPCs make investigation signal meaningful. One memorable trait per Tier 3 NPC. Write the trait, write 5 greeting/routine lines, stop. But write them as real people — Tav worries about his first real responsibility. Sess remembers how the district used to be. Their genuineness is what makes the noise floor believable.

---

3. NPC Patterns (System A)

Patterns define an NPC's narrative archetype. Each pattern has specific authoring rules.

FRIEND

The emotional centerpiece. Full contradiction arc, multi-phase relationship, maximum content depth. D-034 is the specification.

Rule	Detail
Phases	3-5 phases: warmth -> trust -> doubt -> conflict -> new equilibrium
Contradiction	Must be observable through player observation, NOT told through dialogue
Sympathetic motivation	THE FRIEND isn't evil. Concealment comes from care or fear.
No clean resolution	Every player choice (confront, ignore, exploit, protect) has consequences
Tell progression	3+ tells that escalate across phases
Dialogue shift	Pre-discovery and post-discovery pools must feel different
Dual-lens resonance	The other character's playthrough recontextualizes FRIEND behavior
No generation expansion	All FRIEND content is hand-authored

Content budget: 70-100 lines per FRIEND NPC:

• 25-35 dialogue (greetings, shift talk, casual, deflection, confrontation)
• 15-20 trust-gated (insider ring talk, close warmth, secret-tier hints)
• 5-8 unprompted (NPC volunteers info early, warnings/deflections late)
• 10-15 monologue per character (bonded character + opposite character)
• 5-8 tell observation lines
• 3-5 contradiction discovery lines

MIRROR

The honest character. No contradiction arc, no deception tells, no secrets. Full emotional depth despite mechanical simplicity.

Rule	Detail
No tells	Empty tells array. Behavioral markers (visible stress, coping) are NOT deception tells.
No contradiction arc	No phases, no color shift, no betrayal moment
No secret-tier revelation	Trust progression reveals deeper FEELING, not deeper SECRETS
Absence as content	The player's observation pipeline flags the LACK of tells as notable
Emotional vulnerability	MIRROR wears their worry visibly. Transparency is load-bearing.

Content budget: 50-70 lines per MIRROR NPC. No contradiction discovery content. No tell observation content.

ANCHOR

Stabilizing community presence. Protects the status quo.

Rule	Detail
Social gatekeeper	Controls information flow through social position, not power
Protective reflex	Shields regulars and community members from outsiders
Tells signal vigilance	Not deception — watchfulness, redirection, protective silence

THRESHOLD

Controls access between social worlds.

Rule	Detail
Gatekeeper mechanic	Cooperation or opposition shapes player options
Access tier is the tool	THRESHOLD decides who gets insider access
Pressurable	The player can earn or force cooperation

GHOST

Absent figure whose influence is felt through others.

Rule	Detail
Minimal direct content	Referenced in dialogue, rarely seen
Off-screen pressure	Effects visible through other NPCs' behavior changes
Content is in OTHER NPCs' lines	Ghost's impact authored through relationship stubs

SYSTEM, CATALYST, REMNANT, NOBODY

See content/global/enums/patterns.yaml for definitions. Each follows the general tier rules above.

---

4. Functional Motivations (System B)

Motivations define the NPC's role relative to the conspiracy. Combined with pattern to produce the full NPC identity.

Motivation	Relationship to Ring	Content Implication
HANDLER	Manages ring operations	Authority dialogue, operational language, power dynamics
WITNESS	Knows something, possibly unwittingly	Information gates, trust-progression reveals
TURNCOAT	Wavering loyalty	Pressurable, flip conditions, dual-access content
CIVILIAN	Genuinely uninvolved	Mundane substrate, noise floor, honest responses
OPERATOR	Active ring participant	Operational jargon, insider access content, complicity
SKEPTIC	Questions status quo	Uncomfortable questions, institutional criticism

Composition examples:

• FRIEND + OPERATOR (Kael): "I was your friend AND your co-conspirator"
• FRIEND + WITNESS (Sera): "I was your friend AND I was hiding evidence"
• MIRROR + CIVILIAN (Naia): "The one person not lying, surrounded by liars"
• ANCHOR + OPERATOR (Lera): "Profitable blindness — is this enough? Yes, if I don't look"
• SYSTEM + OPERATOR (Voss): "The system works — for the wrong people"
• WITNESS + SKEPTIC (Maret): "I see the discrepancies. I can't pretend I don't"
• SYSTEM + TURNCOAT (Drin): "The institution made me vulnerable, and the ring exploited it"

Authoring guidance: When writing any NPC, start from the pattern+motivation tension. Every line should be legible as coming from that specific combination. An ANCHOR+OPERATOR speaks differently from an ANCHOR+CIVILIAN — the first maintains normalcy as active concealment, the second maintains normalcy because that's genuinely all they have.

---

4b. The 5 Key Axis Interactions

The 10 axes (D-024) don't exist in isolation. These 5 axis interactions generate the contradictions that drive gameplay. When authoring an NPC, identify which interactions are active — they determine what content to write.

Interaction	What It Creates	Example
Want x Secret	The contradiction between what they pursue and what they hide	Kael wants safety but his exit attempt is the biggest security risk. Sera wants connection but her concealment isolates her.
Routine x Secret	Observable deviations from normal behavior	Sera leaves the bar every time Torek arrives — the avoidance IS the tell. Kael lingers in restricted corridors during off-hours.
Tolerance x Relationships	When pressure on one relationship breaks another	Voss's compliance with Nils corrodes his authority over Kael. Naia's worry about Kael triggers Sera's unauthorized compliance check.
Want x Relationships	When personal desires conflict with social bonds	Kael's desire to protect Naia requires lying to the smuggler — the friend he sees every day.
Personality x Tolerance	How stress changes observable behavior	Kael goes quiet and checks exits. Sera redirects and overcompensates with helpfulness. Voss gets procedural and avoids the break room.

For each Tier 1 NPC, all 5 interactions must be active and authored. For Tier 2, at least 2 interactions should be authored. Tier 3 NPCs need at minimum the Want x Routine interaction (what they want shapes their observable daily life).

---

4c. Triangle Content Requirements

Triangles (3 NPCs with conflicting interests) are the atomic unit of social intrigue (D-024, D-025). Every Tier 1 and Tier 2 NPC belongs to at least one triangle.

v0.1 Triangles

#	Name	Members	Type	Core Tension
T1	Hub Power	Voss - Kael - Nils (off-stage)	Active fork	Voss has the title, Nils has the power, Kael is caught between
T2	Worried Knowledge	Maret - Drin - Voss	Active fork	Maret sees discrepancies, Drin is compromised, Voss needs silence
T3	Bar Tensions	Lera - Torek - Harek	Passive tension	Torek's spending draws attention, Lera protective, Harek watching
T4	Worried Partner	Naia - Kael - Sera	Active fork	Naia worries about Kael, confides in Sera, Sera discovers evidence
T5	Informant Question	Naia - Devra - Drin	Passive tension	Cross-template — potential unraveling vectors

What Authors Must Provide per Triangle

1. Observable signals: What the player can see that indicates triangle pressure (behavioral changes, spatial avoidance, tonal shifts in dialogue)
2. Smuggler relevance: How the smuggler reads this triangle — what they know, what they worry about
3. Detective relevance: How the detective reads this triangle — what they observe, what it suggests
4. Pressure points: What player actions could escalate or de-escalate the tension
5. Dialogue shift lines: At least 2-3 lines per triangle member that change when the triangle is under pressure vs. at rest

Triangle Rules

• Self-contained in v0.1 (D-053). No cross-triangle cascade. Pressure in T1 does not automatically affect T3. Cross-triangle cascade is a v0.2 storyteller feature.
• Observable, not narrated. Triangle tension must be visible through NPC behavior (tells, routine deviations, tonal shifts), not explained through dialogue exposition.
• Dual-lens mandatory. Every triangle must read differently through smuggler and detective perspectives.

---

4d. Access Tier Shift Paths

Access tiers change during gameplay based on player actions and story progression. Content authors must provide dialogue for both the starting state and the shifted state.

Social Site	Character	Starting Tier	Likely Shift	Trigger
Logistics Hub	Smuggler	insider + peer	insider > hostile	Cover blown — seen with detective, or ring member reports suspicion
Logistics Hub	Detective	authority	authority > peer	Earns trust by keeping a minor infraction quiet
Bar	Smuggler	insider (regular)	insider > hostile	Social contamination from hub events
Bar	Detective	public	public > insider	Repeated visits (3-4), earns regular status
Ring spaces	Smuggler	insider + peer	peer > hostile	Suspected of cooperation with detective
Ring spaces	Detective	public (doesn't know ring exists)	public > hostile	Stumbles into ring awareness — NPCs react defensively

Authoring implication: For every access tier in the table above, content packs must include dialogue that works at that tier. When a shift happens (e.g., smuggler goes from insider to hostile at the hub), the absence of insider-tier lines IS the emotional payload — the player notices that Kael no longer shares operational details, that the warmth is gone. This means public and hostile tier lines must be authored with enough depth to carry the post-shift experience.

---

5. Dialogue Authoring Rules

The Tag Taxonomy (D-035)

Every dialogue line requires 6 structural tags + up to 3 selection tags.

Structural Tags (Required)

Tag	Type	Format	Description
id	string	{npc-slug}_d_{###}	Stable line ID. Machine-parseable. Never reused. NPC-scoped per D-035 Sprint 15 amendment.
text	string	The line	The authored dialogue text
role	enum	lowercase-slug	Template role, not NPC name. NPCs fill roles at runtime.
access	list	[public, insider, ...]	D-028 Layer 1 hard filter. Who can hear this.
trust	enum	surface|real|secret	D-028 Layer 3 hard filter. What trust level unlocks this.
situation	list	[arrival, routine, ...]	D-028 Layer 2 context filter. When this line can fire.

Selection Tags (Recommended)

Tag	Type	Format	Description
topic	list	[colleague, cargo, ...]	D-028 Layer 4 weighted selection. Defaults to [routine].
mood	list	[content, anxious, ...]	D-028 Layer 4 weighted selection. Defaults to untagged (neutral).
tags	list	freeform strings	Escape hatch for author intent.

Authoring-Only Tags (Not Consumed by Engine)

Tag	Type	Description
dual_lens	map	Per-character interpretation notes
notes	string	Design notes for reviewers
knowledge_grant	object	What the player learns from hearing this line

The Four-Layer Pipeline

Content authors must understand how the engine selects lines. A line must pass ALL layers to fire.

Layer 1: ACCESS (hard filter)
  Does the player's current access tier match the line's access list?
  If no -> line is invisible. The player never knows it exists.

Layer 2: SITUATION (context filter)
  Is the current situation in the line's situation list?
  If no -> line is ineligible for this encounter.

Layer 3: TRUST (hard filter)
  Has the player reached the required trust level with this NPC?
  If no -> line is invisible.

Layer 4: MOOD + TOPIC (weighted selection)
  From the eligible pool, weight by mood and topic match.
  Higher match = more likely to be selected.

Authoring implication: A line tagged access: [insider], trust: secret, situation: [confrontation] will ONLY fire when:

1. The player has insider access (smuggler at the hub, not detective)
2. The player has earned secret-level trust (deep relationship)
3. The situation is a confrontation (triangle pressure escalated)

If any layer fails, the line is invisible. Tag conservatively.

Access Tier Rules

Tier	Who Gets It	Authoring Guidance
public	Everyone	Safe topics. Greetings. Shift small talk. What you'd say to a stranger.
insider	Group members	Ring operational talk. Close colleague warmth. What you'd say to someone who belongs.
authority	Institutional figures	Formal responses to power. Careful language. What you'd say to a cop.
peer	Earned personal trust	Real conversation. Honest opinions. What you'd say to someone you actually like.
hostile	Broken relationship	Accusations. Threats. Defensive walls. What you'd say to someone you no longer trust.

Critical rules:

• access is a list. A line can be eligible for multiple tiers: [public, peer].
• The smuggler starts with insider + peer at the hub. The detective starts with authority.
• When Kael transitions from Friendly to PersonOfInterest, insider and peer lines lock out. That absence IS the emotional payload.
• Never tag a line access: [insider, authority] unless you mean "ring members AND institutional figures hear the same line." That's almost never correct.

Trust Tier Rules

Tier	What It Gates	Authoring Guidance
surface	Default	Safe, non-committal. The public face. Most dialogue is here.
real	Earned through repeated positive interaction	Genuine opinions, workplace complaints, personal concerns. The real person.
secret	Highest tier	Information they'd normally hide. Ring involvement, fears, leverage. For MIRROR NPCs: deepest emotional vulnerability, NOT plot secrets.

Situation Assignment

Tag lines with situations they're appropriate for. The engine decides which situations are currently active.

Common mistakes:

• Tagging everything [routine]. If the line is specific to a time or context, tag it specifically.
• Omitting observation from lines that make sense when the player is watching from a distance.
• Using confrontation for any tense moment. confrontation means triangle pressure has escalated past threshold. Most tension is investigation or social.

---

6. Monologue Authoring Rules

Hard Partition (D-032)

Internal monologue is completely separate per playable character. The character tag is a hard partition, not a filter. The smuggler and detective have independent monologue pools. No shared lines.

Same trigger, different pool. That's how mirror moments work.

Monologue-Specific Tags

Tag	Type	Description
id	string	{npc-slug}_m_{s|d}_{###} — s for smuggler, d for detective. NPC-scoped per D-035 Sprint 15 amendment.
text	string	The monologue line (160 char max)
character	enum	smuggler or detective
trigger	enum	What causes this line to fire (see trigger types below)
prerequisites	object	AND-only knowledge gates (facts, entity attributes, relationship state)
priority	int 0-10	Selection weight. Default 5. Higher = more likely to fire.
cooldown	int	Minimum ticks before line can fire again
tags	list	Freeform tags

Trigger Types

Trigger	When It Fires	Authoring Guidance
enter_location	Player enters new area	First impressions, atmosphere, spatial awareness
observe_npc	Player sees an NPC doing something notable	Body language, activity, posture, tell
hear_sound	Sound event from fog edge	Interpretation of what the player can't see
observe_anomaly	NPC deviates from known routine	Requires prerequisite knowledge of normal pattern
post_conversation	After dialogue ends	Reflection on what was said, what wasn't, what felt off
discover_evidence	Player examines informational object	Interpretation of found evidence
witness_interaction	Player sees two NPCs interacting	Social observation, body language reading
time_idle	Player hasn't acted for a while	Ambient thoughts, rumination, noticing background
return_visit	Player returns to visited area	Changed perspective, comparison to last time

Display Constraints (Hard Ceiling)

Constraint	Value	Implication
Max length	160 characters	Hard ceiling. Most lines 80-120 characters.
Max visual lines	2	If it wraps to 3, cut it.
Display time	4-6 seconds (length-adjusted)	Target: 15-25 words per line.
Self-contained	Each line stands alone	A line must make sense even if the previous one didn't display.
25-word rule	If over 25 words, it must be the most important line in the pool	Most lines: 10-18 words. Average target: 14 words.

Prerequisite Authoring

Monologue lines can gate on knowledge state. Use sparingly — most lines should fire on trigger alone.

prerequisites:
  facts:
    - fact_id: "contraband.ring_exists"
      min_confidence: "knows_of"
  entity_attributes:
    - entity: "npc:kael-davan"
      key: "behavior_flags"
      value: "nervous"
  relationship:
    target: "npc:kael-davan"
    state: "friendly"

Confidence hierarchy (D-041):

• suspects — heard a rumor, gut feeling
• knows_of — has evidence something exists
• knows_details — understands specifics
• direct — personally witnessed

Rule: Gate on the MINIMUM confidence needed. If a monologue line works at suspects, don't gate it at knows_details. More gates = fewer fires = less content the player experiences.

---

7. Regional Culture: Krenn System / Sova Transit District (D-036)

All NPC dialogue and monologue must carry the Sova cultural substrate. This is not decoration — it's the baseline voice.

Krenn Naming Conventions

• First-name-primary. Compact, consonant-heavy. First names in all social contexts.
• Surnames exist for records, not conversation. Using a surname signals formality or institutional distance.
• Exception: The detective uses surnames for targets and unknowns. The shift to first-name IS a relationship marker.

Canonical Krenn names (v0.1): Kael, Voss, Lera, Torek, Drin, Maret, Naia, Sera, Nils, Renn, Harek, Pell, Tav, Olin, Resha, Sess, Sabel, Devra

Sova Atmosphere

The voice of Sova Transit District is "quotidian-with-undertow" — comfortable enough to be complacent, tight enough that extra income is tempting.

Element	Application
Sensory palette	Span gate hum, industrial lubricant, recycled air, cargo machinery, metal grating underfoot
Economic tone	Working-class pragmatic. Money is tight. Grey-market spending is a lifeline, not a crime spree.
Social fabric	Regulars, shift crews, bar habits, "the usual." Community defined by routine co-presence.
Institutional relationship	The Commission is distant, resented, tolerated. Station admin is bureaucracy. Nobody trusts institutions to help.
Trade jargon	Containers, manifests, shifts, routes, transition windows, temp storage, freight bay. Native vocabulary for dock workers — never explain or annotate.

What Sova Voice Is NOT

• Not grimdark. People laugh, drink, complain about their shifts, look forward to the bar.
• Not polished sci-fi. No one says "atmospheric recycling unit." They say "recycled air."
• Not exposition. Characters know where they live. They don't describe it to themselves.
• Not uniform. Lera's bartender warmth differs from Voss's terse authority. Culture is substrate, not script.

---

8. Dual-Lens Coordination

The Core Test (Every Line, Every Time)

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 1 or 2 fails, the line is broken. If 3 fails, the line isn't dual-lens — it's generic.

Three Types of Dual-Lens Difference

Type 1: Access Difference. The smuggler hears a line the detective doesn't (or vice versa). Enforced by access tag.

Type 2: Interpretation Difference. Both characters hear the same dialogue, but their monologue reactions interpret it differently. Enforced by separate monologue pools.

Type 3: Emotional Weight Difference. Relationship history creates different emotional stakes for the same observation.

The dual_lens Field

On dialogue lines and NPC profiles, use the authoring-only dual_lens field to document the split:

dual_lens:
  smuggler: "Operational context -- part of ring pipeline. 'Backed up' is cover."
  detective: "Anomaly -- overnight exceeds procedure. Flag for investigation."

This field is never consumed by the engine. It exists for reviewers and future authors.

---

9. Voice Register Quick Reference

Full voice specifications live in:

• Voice patterns (complete): docs/design/voice-patterns.md (#310) — sentence-level execution rules, contraction patterns, punctuation, stress markers, verbal tics
• Smuggler voice card: docs/design/smuggler-voice-card.md — full smuggler voice reference + moral arc

This section provides the quick-reference contrast. For authoring-level detail (contraction rules, sentence starters, stress markers), consult the voice patterns document directly.

Smuggler Voice

Parameter	Value
Sentence length	Short. Fragments. Rarely more than 2 sentences.
Vocabulary	Concrete, physical, sensory. Trade jargon without explaining. No institutional language.
Emotional register	Feeling-first, analysis second. Gut before brain.
Relationship mode	First-name basis. People by connection, not role.
Observation priority	People > environment > objects
Self-reference	Rare. Through physical sensation, not emotional labels.

Smuggler anchor lines:

1. "Kael's already at the dock. Good. The day's better when he's on shift." (warm)
2. "Shift transition in thirty minutes. If Voss kept the schedule thin, the route's clear." (operational)
3. "Kael keeps checking his lattice. Waiting for a message? Not like him to be jumpy." (concerned)
4. "He looked left. He always looks left when he's making something up. Two years I've known that tell." (hurt)
5. "Morning shift. Recycled air and cargo lubricant. Home sweet home." (atmospheric)

Detective Voice

Parameter	Value
Sentence length	Complete sentences. Structured. Occasional fragments for emphasis.
Vocabulary	Institutional layer over plain speech. "Noted," "flagged," "filing it."
Emotional register	Analysis-first, personal second. When personal breaks through, it's notable.
Relationship mode	Surname-first for targets. First-name for allies. The shift IS a marker.
Observation priority	Patterns > people > environment
Self-reference	More common than smuggler. Through professional lens.

Detective anchor lines:

1. "Logistics hub. Standard prefab, heavy foot traffic. Let's see what the shift change tells me." (clinical)
2. "That's the third time. Sera leaves when Torek arrives. Three different excuses, same result." (pattern)
3. "Good to see Sera. She always was the reliable one. At least someone speaks my language." (personal leak)
4. "Same booth. Same warm smile. Same offer to buy me a drink. ...Everything except whatever she's not saying." (conflicted)
5. "Grain spirit and low conversation. Only place that doesn't smell like freight lubricant." (atmospheric)

---

10. FRIEND Relationship Phase Mapping

THE FRIEND arc is the emotional centerpiece of v0.1. Both FRIEND NPCs follow a multi-phase relationship progression with distinct mechanical expressions at each phase.

Kael Davan (Smuggler's FRIEND)

Arc: comfort -> crack -> observation -> confrontation -> contaminated trust

Phase	Timing	RelationshipState	Access Available	Monologue Register	Tell State	Content Types
1: Comfort	0-10 min	Friendly (green)	insider, peer	Fond, casual	None (baseline)	Greeting, shift talk, bar casual, ring coordination
2: First Crack	10-15 min	Friendly (green)	insider, peer	Mild concern	Lattice checking, shortened interactions	Distracted dialogue, early worry monologue
3: The Observation	15-20 min	PersonOfInterest (amber)	insider/peer lock out	Alarm + confusion	Spatial: wrong place, wrong time	Contradiction discovery monologue (3-5 lines)
4: Confrontation	20-25 min	PersonOfInterest (amber)	public, hostile	Betrayal crystallizing	Looks-left tell confirmed	Deflection dialogue, evasion, the tell
5: Contaminated Trust	25-30 min	PersonOfInterest (amber)	public	Conflicted	Every warm interaction suspicious	Surface-normal dialogue, doubt monologue

Mechanical triggers for phase transitions:

• Phase 1->2: Time-based. Behavioral flags begin accumulating after ~10 minutes.
• Phase 2->3: Spatial trigger. Smuggler enters Corridor B-7, directly observes unauthorized meeting.
• Phase 3->4: Player-initiated. Smuggler chooses to ask Kael about the observation.
• Phase 4->5: Automatic. Post-confrontation, trust is structurally damaged regardless of dialogue choice.

Key authoring constraint: At Phase 3, insider and peer dialogue locks out. Kael still talks to the smuggler, but only public + surface lines remain. That absence IS the emotional payload. Authors must provide enough public/surface lines for Phases 3-5 to feel populated but noticeably colder than Phases 1-2.

Sera Venn (Detective's FRIEND)

Arc: trust -> background data -> pattern recognition -> the question -> contaminated trust

Phase	Timing	RelationshipState	Access Available	Monologue Register	Tell State	Content Types
1: Trust	0-10 min	Friendly (green)	peer	Professional + warmth	None (baseline)	Bar greeting, district orientation, institutional background
2: Background Data	10-15 min	Friendly (green)	peer	Noting connections	Social: relationships outside institutional channels	Naia introduction, community context
3: The Pattern	15-20 min	PersonOfInterest (amber)	peer, authority unlocks	Suspicion activating	Avoidance: leaves when Torek arrives (3x)	Pattern recognition monologue, avoidance observation
4: The Question	20-25 min	PersonOfInterest (amber)	peer, authority	Professional + personal conflict	Controlled deflection, quick warmth recovery	Confrontation dialogue, evasion
5: Contaminated Trust	25-30 min	PersonOfInterest (amber)	peer, authority	Analytical doubt	Overcompensation helpfulness	Surface-helpful dialogue, evaluating monologue

Mechanical triggers for phase transitions:

• Phase 1->2: Time-based + social triggers. Sera introduces detective to bar regulars.
• Phase 2->3: Observation accumulation. Third departure when Torek arrives triggers pattern recognition.
• Phase 3->4: Player-initiated. Detective chooses to ask about Torek.
• Phase 4->5: Automatic. Post-question, trust is contaminated regardless of Sera's response.

Key authoring contrast with Kael: Sera's peer access does NOT lock out at Phase 3. Instead, authority access opens. The detective gains institutional leverage while personal warmth remains but is contaminated. The content shift is additive (more dialogue available) rather than subtractive (Kael's loss of insider content).

---

11. Tag Taxonomy Complete Reference

Access Tiers (5 values)

public, insider, authority, peer, hostile

See content/global/enums/access-tiers.yaml for full descriptions.

Trust Tiers (3 values)

surface, real, secret

See content/global/enums/trust-tiers.yaml.

Situations (13 values)

arrival, shift_start, shift_end, shift_transition, bar_evening, night_shift, investigation, confrontation, social, alone, emergency, routine, observation

See content/global/enums/situations.yaml.

Topics (9 values)

colleague, routine, cargo, money, trust, danger, institution, personal, investigation

See content/global/enums/topics.yaml. Note: crime is deliberately excluded. NPCs think of smuggling as cargo or money, not crime.

Moods (8 values)

anxious, frustrated, content, suspicious, warm, hostile, relieved, focused

See content/global/enums/moods.yaml. (Updated Sprint 14 amendment to D-035.)

Monologue Triggers (9 values)

enter_location, observe_npc, hear_sound, observe_anomaly, post_conversation, discover_evidence, witness_interaction, time_idle, return_visit

See content/global/enums/triggers.yaml.

NPC Patterns (9 values)

FRIEND, MIRROR, ANCHOR, GHOST, CATALYST, THRESHOLD, REMNANT, SYSTEM, NOBODY

See content/global/enums/patterns.yaml.

Functional Motivations (6 values)

HANDLER, WITNESS, TURNCOAT, CIVILIAN, OPERATOR, SKEPTIC

See content/global/enums/motivations.yaml.

---

12. Mechanical Validation Checklist

Before submitting any content, run through these checks. Items marked HARD will be enforced by schema validation. Items marked SOFT require reviewer judgment.

Dialogue Lines

• HARD: id matches pattern {npc-slug}_d_{###} (e.g. kael-davan_d_001) — NPC-scoped per D-035 Sprint 15 amendment
• HARD: role is a valid lowercase slug matching a template role
• HARD: access is a non-empty list of valid access tier enums
• HARD: trust is one of surface, real, secret
• HARD: situation is a non-empty list of valid situation enums
• SOFT: topic and mood are populated (defaults apply if empty, but explicit is better)
• SOFT: Line passes dual-lens test (both characters, or correctly tier-gated)
• SOFT: access list makes sense (no [insider, authority] unless intentional)
• SOFT: trust tier matches content sensitivity (don't put ring talk at surface)
• SOFT: Line advances character, relationship, or narrative (no filler)

Monologue Lines

• HARD: id matches pattern {npc-slug}_m_{s|d}_{###} (e.g. pc-smuggler_m_s_001) — NPC-scoped per D-035 Sprint 15 amendment
• HARD: text is 160 characters or fewer
• HARD: trigger is a valid trigger enum
• HARD: Character partition: smuggler lines in smuggler files, detective in detective files
• SOFT: Under 25 words (or the most important line in the pool if over)
• SOFT: Self-contained (makes sense without context from previous line)
• SOFT: Voice register matches character (smuggler fragments, detective sentences)
• SOFT: Prerequisites gate on MINIMUM confidence needed (don't over-gate)
• SOFT: Trigger matches content (don't use enter_location for NPC observations)

NPC Profiles

• HARD: canonical_id matches npc:{slug} pattern
• HARD: tier is 1, 2, or 3
• HARD: pattern is a valid pattern enum
• HARD: motivation is a valid motivation enum
• HARD: FRIEND pattern requires friend_arc field
• SOFT: All 10 axes populated for Tier 1 and 2 (optional fields for Tier 3)
• SOFT: tells array empty for MIRROR pattern
• SOFT: dual_lens notes present for Tier 1 and 2
• SOFT: trust_levels descriptions provided for all populated tiers
• SOFT: information.knows uses valid category.topic fact IDs

Content Packs (Per NPC)

• SOFT: Line count within tier budget
• SOFT: Access tier distribution covers the NPC's expected encounters
• SOFT: Trust progression has content at each populated tier
• SOFT: Situation coverage: not everything tagged routine
• SOFT: Dual-lens notes on profile and every 5th line minimum (Tier 1)
• SOFT: FRIEND content covers all phases with distinct voice/mood shifts
• SOFT: Monologue for BOTH characters exists (Tier 1 minimum)

---

13. File Structure and Schema Reference

Directory Hierarchy

Dialogue is organized by location + role, not by NPC. This is deliberate — roles belong to templates, NPCs fill roles at runtime (D-025, D-028). Monologue is organized by character + location per the hard partition rule (D-032).

content/campaigns/main/systems/krenn/stations/sova/districts/transit/
  district.yaml              # District metadata
  pools.yaml                 # Seed-time pool definitions
  npcs/
    kael-davan.yaml          # NPC profile (npc-profile.schema.json)
    sera-venn.yaml
    voss.yaml
    ...
  locations/
    the-terminal.yaml        # Location definition (location.schema.json)
    the-last-shift.yaml
    maintenance-corridors.yaml
  dialogue/
    the-terminal/            # Dialogue pools by location + role
      dock-worker.yaml       # (dialogue-pool.schema.json)
      shift-supervisor.yaml
      scheduler.yaml
      new-hire.yaml
      courier.yaml
    the-last-shift/
      bar-owner.yaml
      bar-regular.yaml
      bartender.yaml
    maintenance-corridors/
      ring-operative.yaml
  monologue/
    smuggler/                # Hard character partition (D-032)
      general.yaml           # Location-independent lines
      the-terminal.yaml      # Location-specific lines
      the-last-shift.yaml
      maintenance-corridors.yaml
    detective/
      general.yaml
      the-terminal.yaml
      the-last-shift.yaml
      maintenance-corridors.yaml
  triangles/
    hub-power.yaml           # Triangle definition (triangle.schema.json)
    worried-knowledge.yaml
    bar-tensions.yaml
    worried-partner.yaml
    informant-question.yaml
  routines/
    schedules.yaml           # NPC daily schedules (routine.schema.json)
  templates/
    logistics-hub.yaml       # Social site template (D-025)
    bar.yaml
    smuggling-ring.yaml
  ticker/
    the-last-shift.yaml      # News ticker content

Key convention: Dialogue pools belong to dialogue/{location}/{role}.yaml, never dialogue/{npc-name}.yaml. The NPC assigned to a role is determined at runtime. FRIEND NPCs (Kael, Sera) are the exception — their content is NPC-specific because the FRIEND pattern is inherently character-bound, but the files still follow the location+role structure to maintain consistency.

Schema Validation

All YAML content files must validate against their JSON Schema:

Content Type	Schema File
NPC profiles	content/_schema/npc-profile.schema.json
Dialogue pools	content/_schema/dialogue-pool.schema.json
Monologue pools	content/_schema/monologue-pool.schema.json
Triangles	content/_schema/triangle.schema.json
Routines	content/_schema/routine.schema.json

Line ID Convention

Content Type	Pattern	Example
Dialogue	{npc-slug}_d_{###}	kael-davan_d_001
Monologue (smuggler)	{npc-slug}_m_s_{###}	pc-smuggler_m_s_001
Monologue (detective)	{npc-slug}_m_d_{###}	pc-detective_m_d_001

IDs are stable identifiers. Once assigned, never reused or reassigned. Number gaps are acceptable.

Naming Conventions

• File names: lowercase-hyphenated.yaml
• Role slugs: lowercase-hyphenated (e.g., dock-worker, bar-owner)
• NPC slugs: lowercase-hyphenated (e.g., kael-davan, sera-venn)
• Location slugs: lowercase-hyphenated (e.g., sova-transit)
• Fact IDs: category.topic (e.g., contraband.ring_exists, relationship.kael_naia_connection)

---

14. Anti-Patterns

Dialogue Anti-Patterns

Expository NPC. The NPC explains the world to the player.

• Bad: "The Commission regulates all trade through Sova Transit. Manifests must be filed within 8 hours."
• Fix: "Manifests are late again. Maret's going to catch heat." (Character knows the rules. Show the consequence, not the rule.)

Universal access. A line tagged [public] contains insider information.

• Bad: access: [public], text: "Container 4471 is flagged for rerouting during transition."
• Fix: Tag access: [insider] or rewrite for public consumption.

Trust mismatch. A surface-trust line reveals deep personal information.

• Bad: trust: surface, text: "I'm trying to get out of the ring. Don't tell Nils."
• Fix: That's trust: secret content. Gate it correctly.

Crime vocabulary. NPCs use the word "crime" or "smuggling" in casual conversation.

• Bad: "The smuggling operation runs during shift transitions."
• Fix: "The cargo moves during transitions. When oversight's thin." NPCs think in their own terms.

Monologue Anti-Patterns

Wrong voice register. Smuggler uses detective vocabulary or vice versa.

• Bad (smuggler): "I should investigate this anomaly further."
• Fix: "That's not right. I need to see what's going on."
• Bad (detective): "Kael's here. Good."
• Fix: "Davan's on shift. Standard."

Explaining the already-known. Character tells themselves something they already know.

• Bad (smuggler): "According to the manifest, container 4471 should weigh 240 kilograms."
• Fix: "4471's heavy. Too heavy."

Over-gating. Prerequisite blocks a line that would work without the gate.

• Bad: prerequisite requires knows_details when the line only needs suspects
• Fix: Gate on minimum confidence. More fires = more content = better experience.

Breaking the partition. A smuggler monologue line that sounds like the detective, or shared content between pools.

• Rule: If you can swap character: smuggler to character: detective and the line still works, it's not character-specific enough. Rewrite.

Profile Anti-Patterns

MIRROR with tells. A MIRROR NPC profile lists deception tells.

• Rule: MIRROR tells array must be empty. Behavioral markers (visible stress, coping mechanisms) are NOT tells.

FRIEND without phases. A FRIEND NPC profile omits the friend_arc.phases field.

• Rule: FRIEND pattern requires 3-5 phases with distinct triggers and routine deviations.

Tier 3 overwriting. A Tier 3 filler NPC with 40 dialogue lines.

• Rule: Tier 3 budget is 5-10 lines. One memorable trait. Write it, stop. Content budget is finite.

---

15. Generation Expansion Rules

Tier 2 and Tier 3 dialogue is expanded 4x from authored base lines (D-028: "write 10, generate 40"). The authored lines are the style anchors — generation must reproduce, not reinvent.

What Generation Can Do

• Vary phrasing of the same semantic content ("Shift's running smooth" -> "Smooth shift so far" -> "Nothing out of the ordinary today")
• Vary topic/mood tags within the same access and trust tier
• Combine elements from two base lines into a single generated line
• Add environmental color within the Sova sensory palette (span gate hum, recycled air, cargo sounds)

What Generation Cannot Do

• Introduce new information. Generated lines never reveal facts, names, or relationships not present in the base lines.
• Change access or trust tier. A generated line inherits the access and trust constraints of its base line(s).
• Break voice register. Generated lines must match the NPC's personality voice exactly — sentence length, contraction patterns, vocabulary level.
• Cross the character partition. Generated monologue lines stay in the correct character pool.
• Add knowledge grants. Only hand-authored lines can grant knowledge to the player.
• Create FRIEND content. All FRIEND NPC content is hand-authored. No generation expansion.

Generation Validation

Every generated line must pass:

1. Voice test: Read aloud. Does it sound like the same NPC who said the base lines?
2. Dual-lens test: Does it read differently through each character's perspective? (If the base line passes this test, the generated line must also.)
3. Tag inheritance: Are access, trust, situation, topic, and mood tags consistent with the base line?
4. No new information: Does the line reveal anything the base lines don't already establish?
5. Display constraint: Under 160 characters for monologue. Self-contained.

---

16. Worked Example: Writing a Dialogue Line

Context: Writing a line for Kael Davan at the Logistics Hub during a routine morning shift.

Step 1: Write the Line

"Morning. Voss kept the rotation thin -- we've got a clear window after 14:00."

Step 2: Assign Tags

- id: kael-davan_d_076
  text: "Morning. Voss kept the rotation thin -- we've got a clear window after 14:00."
  role: dock-worker
  access: [insider]
  trust: real
  situation: [shift_start]
  topic: [cargo, routine]
  mood: [content]
  tags: [ring-operational]

Step 3: Validate

• id: kael-davan_d_076 -- valid pattern (NPC-scoped per D-035 Sprint 15 amendment). Continues from kael-davan's terminal sequence (_034-_075).
• role: dock-worker -- valid slug.
• access: [insider] -- only ring members hear this. Detective never sees it. Correct.
• trust: real -- requires earned trust. Not surface-level small talk. Correct for operational ring dialogue.
• situation: [shift_start] -- morning shift context. Correct.
• topic: [cargo, routine] -- covers both operational and schedule content. Correct.
• mood: [content] -- Phase 1, baseline warm. Correct.

Step 4: Dual-Lens Check

dual_lens:
  smuggler: "Operational confirmation. The window is clear. Routine ring coordination."
  detective: "Never hears this line. Insider access only."

Step 5: Voice Check

• Uses first name (Voss). Correct for smuggler context.
• Short, operational. Fragment + sentence. Matches smuggler's colleague register.
• Trade jargon without explanation ("rotation thin," "clear window"). Correct for Krenn substrate.
• No institutional vocabulary. No analysis. Correct.

Line passes all checks.

---

Appendix A: Decision Cross-Reference

Decision	Title	Relevance to This Guide
D-023	Three-tier content model	Tier structure, content budgets
D-024	10-axis NPC model	Profile structure, tell system, triangle model
D-025	Social site as template unit	NPC-to-location relationship, functional clusters
D-027	Vertical slice criteria	Success criteria that FRIEND content must satisfy
D-028	Dialogue architecture	Four-layer pipeline, tagged line pools, generation expansion
D-029	Population entanglement 30/50/20	Tier distribution, noise floor
D-032	Separate monologue pools	Hard character partition
D-034	THE FRIEND pattern	Production-level NPC specification
D-035	Converged tag taxonomy	All tag definitions, pipeline layers
D-036	Sova Transit District setting	Regional culture, naming, atmosphere
D-037	Contraband specification	What NPCs are smuggling and why
D-039	v0.1 wow moments	Content that must exist for wow moments to fire
D-041	Knowledge graph data model	Prerequisite confidence hierarchy
D-047	v0.1 triangles	3 active forks, 2 passive tensions
D-050	NPC pattern/motivation mapping	Canonical v0.1 NPC assignments (System A + B)
D-053	Self-contained triangle forks	No cross-triangle cascade in v0.1
D-056	PC voice registers	Smuggler feeling-first, detective analysis-first
D-059	Monologue display constraints	160 char max, 2-line max, priority ordering

Appendix B: Content Budget Summary (v0.1)

Validated scope (v0.1 Content Scoping Workshop): ~695 authored content items.

Content Type	Authored	Generation-Expanded	Total
Tier 1 FRIEND dialogue (x2)	150-200	0	150-200
Tier 1 MIRROR dialogue (x1)	50-70	0	50-70
Tier 2 NPC dialogue (x10)	200-350	800-1400	1000-1750
Tier 3 NPC dialogue (x4)	20-40	80-160	100-200
Monologue (smuggler pool)	~100	0	~100
Monologue (detective pool)	~100	0	~100
Environmental text	~50	0	~50
News ticker	~20	0	~20
UI microcopy	~50	0	~50
PC-as-NPC content (x2)	~25	0	~25
Total authored	~695-1005
Total with generation			~1545-2565

FRIEND content (hand-authored, no expansion) represents ~20-30% of all authored lines. This is where voice consistency matters most. Monologue is hand-authored only — the character voice is too precise for generation expansion in v0.1.

---

End NPC Authoring Style Guide v0.1