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

docs(copy): Sprint 12 Wave 1 — Miri's five foundation docs

Browse Source 
Cultural generation guide (#189), Sova Texture Appendix (#302),
Contraband specification (#321), Sova Station Profile (#320), and
Span Gate Transit Schedule (#336). These are the blocking foundation
docs for all three content packs (#190/#191/#192) and the Meridian
Coverage Map (#335).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
jpmschweitzer
2026-02-19 16:16:04 +01:00
co-authored by Claude Sonnet 4.6
parent 7916ebac5f
commit 6719cf0fe3
10 changed files with 2774 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design/contraband-specification.md
+247
View File
@@ -0,0 +1,247 @@
# Contraband Specification — Lattice Components & Supply Chain
**Ticket:** #321
**Author:** Miri
**Status:** canonical
**Last updated:** 2026-02-19
Reference: D-037 (contraband decision), D-036 (Sova setting), D-017 (perception modes)
---
## Purpose
This document defines the specific contraband being smuggled in the Sova Transit District scenario. It provides the supply chain, street terminology, moral dimensions, and detection/evasion methods that NPC dialogue and investigation mechanics depend on.
**Why this exists:** Mellanie cannot write ring NPC dialogue without knowing what the ring is smuggling and why people want it. Paula cannot design NPC motivations without knowing the moral stakes. The detective cannot investigate without knowing what they're looking for. This document is the shared reference.
---
## Part 1: Primary Contraband — Unlicensed Lattice Components
### What They Are
**Neural lattice components** are the hardware and firmware elements that make up the neural lattice implant — the Reach's universal human-machine interface. Every citizen with a lattice (i.e., almost everyone) has a configuration of components that determines their lattice tier and capability.
**Unlicensed lattice components** are lattice hardware and firmware obtained outside of Lattice Commission certification channels. This includes:
- **Enhancement modules:** Hardware add-ons that expand a Baseline lattice toward Augmented-tier capability. Improved sensory processing, faster Meridian query response, expanded information overlay capacity.
- **Aftermarket firmware:** Software modifications that unlock capability built into the hardware but blocked by Commission certification tiers. The hardware is the same; the firmware determines what it can do.
- **Capability-specific mods:** Targeted modifications for specific use cases — enhanced audio discrimination, improved spatial mapping, pattern recognition support. Often developed for occupational purposes in systems where Commission access is expensive.
- **Medical-grade neural replacements:** Certified neural lattice replacement components diverted from legitimate Syndic supply chains. Priced far below standard Syndic channels because they're off-manifest.
### Commission Regulatory Framework
The Lattice Commission regulates neural lattice technology under Reach-wide mandate. The certification system works as follows:
- **Baseline tier:** Standard-issue. Commission-certified, universally available, low-cost. Factory default capabilities only.
- **Augmented tier:** Institutional or premium. Requires Commission recertification, documented justification (occupational need, institutional role), and ongoing compliance monitoring. Significantly more expensive.
- **Enhanced tier:** Specialist. Requires extensive justification, Commission review board approval, and continuous monitoring. Rare.
- **Transcendent tier:** Theoretical or classified. Not available through any public channel.
The regulation exists for stated reasons: safety (unregulated hardware poses health risks), security (enhanced lattice capability creates surveillance and data-access concerns), and economic stability (Commission certification fees are a significant revenue stream).
The regulation also exists for unstated reasons: the Commission's tier pricing structure benefits Syndic manufacturers who hold Commission approval. Aftermarket components break the Commission's market control.
### Why People Want Unlicensed Components
The demand is not criminal in motivation. Most buyers want lattice components for ordinary reasons:
**Occupational capability:** A freight worker whose job involves spatial reasoning and pattern detection can do that job better with Augmented-tier pattern recognition support. Commission-certified upgrade: expensive, requires institutional sponsorship. Aftermarket equivalent: costs a month's wages, no sponsorship required, available through the ring.
**Medical necessity:** Neural lattices degrade over time, especially in older models and in people who've done intensive lattice work for years. Replacement components are essential healthcare. Syndic pricing for lattice replacements is calibrated to institutional buyers (hospitals, Commission offices). For individuals — particularly working-class individuals without employer-sponsored medical plans — the legitimate price is prohibitive. Aftermarket replacements work the same way for a fraction of the cost.
**Personal autonomy:** Some people simply believe they have the right to determine their own lattice configuration without Commission approval. The Guardians of Severance take this position philosophically. The ring's customers mostly take it practically.
**Access inequality:** The Commission's tier system means that institutional workers (investigators, administrators, Syndic employees) get enhanced lattice capability through their employer. Workers outside institutional employment don't. Aftermarket components are one way the non-institutional population accesses capabilities the institutional population considers routine.
### The Moral Dimension
The ring is smuggling **access**, not weapons.
No one is importing military-grade targeting systems or hostile surveillance technology. The contraband is the same components that the detective uses, bought through a different channel, without Commission paperwork.
The moral question the player faces is not "is it wrong to trade in harmful things?" It is "is it wrong to provide people with things the Commission has decided they're not allowed to have, for reasons that primarily serve the Commission's business interests?"
This question does not have a clean answer. The ring knows it doesn't have a clean answer. The ring's members have made their peace with working in the gray zone. Some of them use their own products.
**Key moral detail:** Naia (Kael's partner) uses a diverted medical-grade lattice replacement. Her original lattice degraded faster than expected — occupational wear. The legitimate replacement was priced at 14 months of combined wages. The aftermarket replacement worked. This is one of the ring's own. This is, in part, why Kael is in the ring at all. The detective doesn't learn this until they have Kael's trust.
---
## Part 2: Secondary Contraband
### Severance Counter-Surveillance Technology
**What it is:** Hardware and software tools designed to evade, disrupt, or spoof Meridian monitoring. Produced and distributed by the Guardians of Severance (the counter-surveillance movement) but also trafficked commercially to buyers who have no ideological alignment — they just want privacy.
**Why it's in the ring:** The ring uses Severance tech for operational purposes. They also move product for Severance-adjacent customers. It's not their primary business, and they don't advertise it, but if someone in their network needs a comm scrambler or a lattice signature mask, the ring can provide.
**Moral dimension:** Severance tech protects privacy, which is a legitimate interest. It also enables the ring's operations, which is less sympathetic. And it undermines Commission surveillance, which is either a feature or a bug depending on your perspective.
**Commission classification:** Category 2 violation — possession of surveillance countermeasure technology. More serious than unlicensed lattice components. The ring is careful with this part of their inventory.
**Detection note:** Severance tech is harder to scan for than lattice components — it's designed not to be found. The detective's augmented lattice can detect the signature of active Severance scrambling, but passive Severance hardware (not currently running) doesn't trigger. The smuggler knows this.
### Off-Manifest Biologicals
**What they are:** Medical supplies, pharmaceutical compounds, biological cultures, and occasionally re-embodiment materials that are diverted from official Syndic supply chains and moved through informal channels.
**Why they're off-manifest:** Multiple reasons:
- Syndic pricing for medical supplies creates a gray market, same as lattice components
- Some biological materials are classified as controlled under Commission or Concord Assembly pharmaceutical regulations — legitimate reasons for control, but regulations calibrated for Syndic-scale distribution, not individual access
- Re-embodiment backup materials are tightly controlled — owning a personal backup of your own cognitive state is technically legal but creating and moving the physical medium outside certified facilities is not
**Why the ring handles them:** The same logistics infrastructure that moves unlicensed lattice components can move biologicals. The margin is smaller, the risk is comparable, and some of the same customers want both.
**Moral dimension:** This is the murkiest category. Moving medical supplies to people who can't afford Syndic pricing — sympathetic. Moving re-embodiment backup materials to people who want personal insurance against death without going through the certified system — complicated. Moving materials of unknown provenance through an unregulated supply chain without knowing what they actually are — this is where the ring's "we don't ask" culture becomes a liability.
**Volume in v0.1:** Minor fraction of total cargo. The ring focuses on lattice components. The biologicals are occasional, handled only through a specific trusted member, and never discussed in the same conversation as the lattice business.
---
## Part 3: Supply Chain
### Upstream — Manufacture and Acquisition
**Aftermarket lattice component manufacturers:**
- Primarily operate in systems with lighter Commission presence — frontier and deep-frontier manufacturing, occasionally mid-Reach systems with local regulatory variance
- Not criminal enterprises in their origin systems — they operate legally where they are; the illegality is at the destination end where Commission certification applies
- Some Syndic-adjacent: subsidiaries or licensing agreements that produce off-spec components under plausible deniability
- Products are shipped in legitimate freight that also carries legitimate cargo — the contraband fraction of any given container transit is small
**Acquisition chain:**
- Coordinator receives orders from the distribution network
- Acquisition contacts at origin-system freight handlers arrange for components to be included in outbound shipments with doctored manifests
- The doctored manifests show legitimate cargo codes; the actual components are repacked into containers that look right
**Detection risk at origin:** Low. Commission enforcement is concentrated at destination hubs (where the Commission has jurisdiction), not at frontier or mid-Reach origin points.
### Midstream — The Ring's Role
**The ring's function is transit, not manufacture or retail.** They are a distribution node in a larger network. Their specific value is:
- Access to Sova's span gate (a legitimate freight chokepoint)
- Relationships with dock workers who control scanner routing
- Knowledge of scanner blind spots and maintenance windows
- The ability to blend contraband into legitimate freight flows
**Operational mechanics:**
1. **Notification:** Coordinator receives arrival details through off-Meridian channels. This information is passed to ring members through code language on Meridian or through physical dead drops.
2. **Preparation:** Ring member verifies scanner bay availability and status. Flags maintenance windows. Identifies lowest-scrutiny route through the hub.
3. **Receipt:** Contraband arrives in a standard freight container. On the manifest, it's listed as a legitimate cargo category (machine parts, agricultural supplies, industrial components — whatever is plausible for the transit route).
4. **Routing:** Ring member routes the container to a scanner bay with known compliance. Either a bay with a calibration blind spot (specific scanner types can't detect lattice components in certain packing configurations) or a bay operated by a ring-aware worker who logs a clean scan.
5. **Handoff:** Container moves to staging. Ring member marks it for the receiving contact's pickup. The receiving contact has legitimate access to staging (Syndic freight broker, commercial customer, station resident with freight delivery).
6. **Payment:** Through the coordinator, via off-manifest routes. The ring doesn't handle large cash-equivalent transactions on Meridian. Payment is managed in chunks, routed through legitimate purchases.
**What can go wrong:** The ring's operational security depends on nothing standing out. Problems occur when:
- A worker outside the ring notices something — wrong container in wrong bay, worker behavior that's off-routine
- A scanner bay does a spot-check instead of the expected throughput scan
- A ring member's behavior attracts attention (Torek's recent carelessness is an example)
- The detective's manifest analysis flags anomalies in the shipping record
### Downstream — Distribution
**The ring's customers are not known to most ring members.** The coordinator manages the downstream. Ring members know they're moving components; they don't know who ends up with them.
From what's inferrable:
- Local distribution: station residents, some district workers, a few customers from other districts on Sova
- Off-station: the span gate delivers cargo to the planetary freight depot on Velen. Some product continues via Velen's distribution network to system population centers.
- Regional: occasional higher-value shipments routed through the system to other ring nodes beyond Krenn System. The ring doesn't manage this leg.
**The v0.1 scope:** The detective's investigation is concerned with the Sova Transit District operation. The broader network is context, not target. Discovering that the ring is part of a larger network is an investigation milestone, not the investigation conclusion.
---
## Part 4: Terminology Reference
### Formal/Institutional Terms (Detective + Commission)
| Term | Meaning |
|---|---|
| **Unlicensed lattice components** | Hardware/firmware outside Commission certification |
| **Category 3 violation** | Commission classification for lattice tampering |
| **Manifest discrepancy** | Difference between declared and actual cargo |
| **Cargo routing anomaly** | Container reaching destination via non-standard path |
| **Off-manifest transfer** | Goods moving without Meridian-logged documentation |
| **Surveillance countermeasure equipment** | Severance tech (formal term) |
| **Category 2 violation** | Commission classification for Severance possession |
### Street/Ring Terms (Smuggler + NPC Insider)
| Term | Meaning | Context |
|---|---|---|
| **components** | Unlicensed lattice mods | "Got a components run tonight." |
| **inserts** | Same as above, slightly more specific | "The inserts are in Bay 7." |
| **upgrade kits** | Packaged lattice enhancement sets | "They ordered two upgrade kits this week." |
| **medical** | Medical-grade lattice replacements specifically | "This one's medical — handle it carefully." |
| **scramblers** | Severance tech | "He wanted a scrambler, I told him to ask the coordinator." |
| **the product** | Generic for whatever the ring is moving | "The product moves at 0200." |
| **a clean manifest** | Successfully falsified cargo documentation | "Manifest is clean." |
| **a bad can** | A container that's been flagged or is otherwise problematic | "Don't touch that one — it's a bad can." |
| **the coordinator** | The ring's off-site manager | Referred to obliquely. Never by name in non-secure channels. |
---
## Part 5: Detection and Evasion
### How the Commission Detects Contraband
**Manifest analysis:** Comparing declared cargo against shipping codes, routing patterns, and commercial plausibility. Anomalies flag for review. The detective's augmented lattice can run this analysis on a per-container basis; the Commission system runs it across all incoming freight as a pattern recognition exercise.
**Physical scanning:** Standard freight scanners check for mass discrepancies, specific material signatures, and packing anomalies. Unlicensed lattice components are difficult to detect via standard scan — they read as generic electronics without specific interrogation protocols. Enhanced scan (requiring cause and authorization) can identify lattice component signatures specifically.
**Lattice signature analysis:** An enhanced lattice running the right query can detect the electromagnetic signature of recently modified lattice hardware in proximity. This requires close physical proximity and active scanning — not passive detection. The detective could deploy this if they have a specific target and authorization.
**Behavioral surveillance:** Watching who goes where, who talks to whom, who handles certain containers. The Meridian logs access patterns in institutional spaces (Commission-authorized areas). Manual surveillance in non-Meridian spaces is the detective's work.
### How the Ring Evades Detection
**Manifest doctoring:** The primary defense. Contraband is listed as plausible legitimate cargo. Batch sizes are kept below the threshold that triggers automatic enhanced review. Shipping routes use established legitimate freight paths.
**Scanner routing:** Contraband containers are routed to scanner bays known to have calibration limitations or operated by ring-aware workers. The ring maintains awareness of which bays are running which protocols on any given day.
**Timing:** Operations occur during shift transitions (when attention is divided), during maintenance windows (when some scanner systems are offline), and during high-volume pushes (when individual container scrutiny is lower).
**Operational security:** No discussion of specifics on Meridian-logged channels. Limited need-to-know within the ring. The coordinator knows the full picture; individual ring members know only their operational role.
**Normalcy as cover:** The ring's greatest protection is that everything looks normal. No late-night break-ins. No dramatic meetings in dark corridors. Everything happens within the ordinary flow of freight operations. The detective is looking for anomalies in a sea of normal; the ring works to minimize the anomalies.
---
## Part 6: Gameplay Implications
### For the Smuggler
The smuggler's daily work IS the ring's operation. They don't separate their legitimate job from their criminal one — they do both simultaneously. The investigative element for a smuggler playthrough is not "will I get caught" but "how do I keep everything in balance as the detective's investigation narrows."
The three physical inventory items (D-065) connect directly to this:
1. **Manifest copy** — proves cargo discrepancy, but having it means carrying evidence of the operation
2. **Corridor access token** — proves ring membership, physical risk if discovered
3. **Personal comm log** — recorded conversations that prove network connections, the most dangerous of the three
### For the Detective
The detective's investigation begins with manifest analysis and behavioral observation. The progress trajectory is:
- Level 1: Notice statistical anomalies in freight manifests (requires augmented lattice + access)
- Level 2: Connect specific containers to specific workers (requires surveillance + NPC knowledge)
- Level 3: Establish the supply chain (requires either informant cooperation or direct evidence)
- Level 4: Identify the coordinator and the broader network (requires trust-gated disclosure or confrontation)
The detective does not need to know everything in this document. They discover it through investigation. This document is the ground truth that their knowledge state moves toward.
### Moral Ambiguity in Practice
The intent is that a player who investigates Kael seriously — who learns about Naia's medical situation, who understands why Kael is in the ring — should not feel straightforwardly good about bringing Kael down. The smuggler player, similarly, should not feel entirely comfortable with their complicity once they understand the ring's full scope.
The contraband is designed to be sympathetic at its core (medical necessity, access inequality) while creating complications the deeper you look (the biologicals of unknown provenance, the Severance tech enabling things the player may not endorse). Neither character has clean hands. Neither character has indefensible ones. That's the design intent.
---
*This document is the canonical contraband reference for v0.1 content. NPC dialogue involving ring operations, cargo handling, or investigation should cross-reference here for terminology consistency. If a content gap is identified — a term needed that isn't here, a scenario not covered — flag to Miri for addition.*
*Miri — Sprint 12*
docs/design/contradiction-arc-friend-pattern.md
+272
View File
@@ -0,0 +1,272 @@
# Contradiction Arc — THE FRIEND Pattern
**Ticket:** #332
**Source:** D-034 (THE FRIEND ECS spec), D-039 (wow moments — #3), D-041 (contradiction detection), D-028 (dialogue architecture)
**Derived from:** Kael Davan (smuggler's FRIEND, #297) + Sera Venn (detective's FRIEND, #298)
**Date:** 2026-02-19
---
## Overview
THE FRIEND is a reusable NPC pattern. One per playable character. The FRIEND is the emotional centerpiece of v0.1 — the NPC the player names when asked "who did you feel conflicted about?" (D-027 success criterion #3).
The pattern has one invariant: **the contradiction is observable through physical space or behavioral pattern, never through dialogue.**
The player discovers the truth by watching, not asking. Dialogue confirms or deflects — it never reveals first.
---
## The Five Phases
| Phase | Duration | NPC State | Player Experience |
|-------|----------|-----------|-------------------|
| 1. **Warmth** | 0-10 min | Baseline positive. No deviations. | This NPC is your best relationship. The day is better when they're here. |
| 2. **Background** | 10-15 min | Subtle behavioral flag begins. Not enough to read yet. | Social context accumulates. You learn who this person is to the world. |
| 3. **First Contradiction** | 15-20 min | Observable anomaly fires. Color shifts from green to amber. | Something doesn't fit. The belief you formed in Phase 1 is contradicted. |
| 4. **Confrontation Opportunity** | 20-25 min | Deflection. The TELL fires during the deflection. | You ask. They don't answer. But you notice something. |
| 5. **Contaminated Trust** | 25-30 min | Surface behavior returns to baseline. | The FRIEND acts normal. But you're watching now. Every Phase 1 moment is retroactively suspect. |
### Phase 1 requirements
- FRIEND must exhibit genuine warmth — greet the player first, share information willingly, reference personal connection
- At least one Phase 1 scene establishes an emotional anchor (shared meal, personal reference, easy banter)
- Routine is fully normal — punctual, sociable, consistent
- No behavioral flags — anything in Phase 1 must be readable as normal in isolation
### Phase 2 requirements
- FRIEND continues warm baseline but begins accumulating subtle signals
- Subtle signals must be individually readable as normal: leaving early has a plausible reason, checking lattice is common behavior
- Phase 2 establishes context that will retroactively charge Phase 3: introduce the relationship that's being protected, establish the FRIEND's expertise/role, build emotional depth
- At least one Phase 2 scene introduces the third party the FRIEND is protecting (Naia for Kael, Naia-via-Sera for the detective's arc)
### Phase 3 requirements — the contradiction
**Type A: Spatial Anomaly**
Character is in a location they have no legitimate reason to be in, at an illegitimate time, doing something outside expected protocol. Single observation. Sudden alarm.
*Kael example:* In Corridor B-7 (restricted, not his zone) after his shift, meeting an unrecognized person outside ring protocol. The smuggler sees it and the prior belief ("Kael operates within ring protocol") is immediately contradicted.
**Type B: Behavioral Pattern**
Character exhibits a consistent behavioral response across multiple observations. No single observation is conclusive — the third occurrence completes the pattern. Gradual recognition.
*Sera example:* Leaves the bar within 2-3 minutes every time Torek arrives. Three occurrences, three different stated reasons. Detective training fires on the third: this is not coincidence.
**Pattern B requires three observations** before the contradiction fires — one is nothing, two is coincidence, three is data.
**Both types:**
- The contradiction must be spatially or behaviorally discoverable — something the player's character would notice from observation
- Dialogue does not reveal the contradiction — the FRIEND either doesn't know the player observed, or has a plausible explanation that doesn't collapse the contradiction
- Color shifts from green (Friendly) to amber (PersonOfInterest) when contradiction is observed
- Knowledge graph: contradiction fact set to `suspects` level, triggering contradiction-detection monologue
### Phase 4 requirements — the confrontation opportunity
Player initiates dialogue about the Phase 3 observation.
**Required structure:**
1. Player asks about the anomaly (spatial presence, behavioral pattern, etc.)
2. FRIEND deflects — gives a plausible answer that doesn't confirm or deny
3. **The TELL fires during the deflection.** Not before, not after — during the deflection. The tell is how you know they're hiding something.
4. The tell must be:
- Established or at minimum detectable before Phase 4 (player can already know this tell)
- Observable through the character's behavior, not through dialogue content
- Something that becomes clearer in retrospect once the player knows to watch for it
**Key constraint:** The FRIEND does not confess in Phase 4. The confrontation reveals the lie, not the truth. The truth comes later — either through investigation, a separate disclosure event, or the player's own inference.
### Phase 5 requirements — contaminated trust
Surface behavior returns to Phase 1 baseline. The FRIEND continues as before.
**What changes:**
- Every prior Phase 1 moment is retroactively ambiguous. Was the warmth genuine, or instrumental?
- New monologue lines fire that filter current observations through doubt: "Same old Kael. Same jokes, same routine. ...What are you not telling me?"
- Relationship state: PersonOfInterest persists. Color stays amber.
- Three resolution paths open (see below)
**The answer to "was the warmth genuine?"** is always both — yes AND they were hiding something. This ambiguity is the emotional payload. The FRIEND pattern does not deliver a villain. It delivers a person making a hard choice.
---
## Resolution Paths
Three paths available post-Phase 4. None is correct. All carry costs.
| Path | Action | What It Tests |
|------|--------|---------------|
| **Understanding** | Gentle confrontation — player asks again, creates space for disclosure | Willingness to extend trust despite evidence |
| **Betrayal** | Report to authority (ring leadership / Commission) | Institutional loyalty over personal loyalty |
| **Observation** | Watch and wait — build knowledge without confronting | Information-gathering over emotional resolution |
**Design constraint:** No path delivers a clean outcome within v0.1. Understanding may get partial confession but not full truth. Betrayal removes the FRIEND from play but doesn't close the case. Observation extends the ambiguity indefinitely.
---
## Tell Progression
Every FRIEND NPC requires at least three tells, each with different observability:
| Tell Level | Observability | Timing | Purpose |
|-----------|---------------|--------|---------|
| **Peripheral** | Visible to any observer with some attention | Phase 2 onset | Subconscious accumulation — player may notice retroactively |
| **Forward** | Visible to focused observers / in direct interaction | Phase 3-4 | Confirmation tell — fires when the player is paying attention |
| **Direct** | Confirmed in post-conversation monologue | Phase 4 | The TELL — fires during the deflection, seals the case |
### Kael's tells
1. Increased lattice checking (peripheral, Phase 2)
2. Shortening social interactions / leaving early (any, Phase 2-3)
3. **Looks left when lying** (forward, Phase 4 — the personal tell the smuggler knows from years of friendship)
4. Unauthorized spatial presence in B-7 (any, Phase 3 — the contradiction itself)
### Sera's tells
1. Extended Commission kiosk time (peripheral, Phase 2)
2. Overcompensation with information (forward, Phase 2-3)
3. **Topic deflection — redirects rather than goes silent** (forward, Phase 4 — controlled delivery reveals the redirect IS the tell)
4. Leaves bar when Torek arrives (any, Phase 3 — the contradiction itself, cumulative)
---
## Knowledge Graph Mechanics
What the FRIEND arc requires from the knowledge system (D-041):
### Phase 1-2: baseline
```
player.KnowledgeGraph[friend_npc]:
confidence: KnowsOf # Knows who they are and their role
relationship: Friendly # Warm relationship established
state: Active
known_attributes.trust_level: trusted
```
### Phase 3: contradiction fires
```
# The contradiction event is observed
player.KnowledgeGraph.facts[investigation.{friend}_contradiction_event]:
confidence: Suspects # "Something's off"
state: Active
# If prior knowledge entry conflicts with observation:
player.KnowledgeGraph[friend_npc]:
state: Contradicted # Both entries get this — D-041 contradiction detection
# Triggers: ContradictionEvent → monologue system → relationship review
relationship: PersonOfInterest # Color shifts amber
```
### Phase 4: tell confirmed
```
# Tell confirmed in post-conversation monologue
player.KnowledgeGraph.facts[behavioral.{friend}_evasion]:
confidence: Direct # Set during conversation, Direct = "I just saw this"
state: Active
# Contradiction fact upgraded
player.KnowledgeGraph.facts[investigation.{friend}_contradiction_event]:
confidence: KnowsOf # Now more than suspicion — confirmed deliberate
```
### Phase 5: contaminated trust
```
player.KnowledgeGraph[friend_npc]:
confidence: KnowsDetails # You know they're hiding something specific
relationship: PersonOfInterest # Stays amber — cannot return to Friendly without deep trust event
state: Contradicted # Persists until resolution path completes
```
---
## Content Requirements Per FRIEND NPC
### Authored lines (no generation expansion)
| Content Type | Count | Notes |
|-------------|-------|-------|
| Dialogue — surface tier | 8-10 | Phase 1-5 casual lines, available at any trust |
| Dialogue — real tier | 6-8 | Phase 1-3 insider/operational content |
| Dialogue — secret tier | 3-5 | Phase 5 disclosure (if Understanding path taken) |
| Dialogue — confrontation options | 4-6 | Phase 4 initiation + FRIEND response variants |
| Monologue — about FRIEND (player char) | 12-15 | Full arc coverage; character partitioned (D-032) |
| Tell observation lines | 5-8 | One per tell, per observability tier |
| Contradiction discovery monologue | 3-4 | Fires when Phase 3 contradiction is observed |
| Post-contradiction monologue | 4-6 | Phase 5 filtered-through-doubt lines |
| Dual-lens notes (not in engine) | 1-2 per character | For authoring consistency |
**Total per FRIEND NPC: ~70-100 authored lines.** No generation expansion — every line hand-authored.
### Dual-lens authoring
The same FRIEND NPC is experienced differently by each playable character. Authors must write:
- Primary arc (bonded character): full emotional weight, personal tell knowledge, relationship history
- Secondary observation (other character): distant, filtered through their lens — the FRIEND is "just" a Commission worker / dock worker until patterns accumulate
**The dual-lens makes the FRIEND arc pay off on replay.** Playing the other character, you now understand Sera's avoidance or Kael's tension from a completely different angle.
---
## Checklist for New FRIEND NPCs
Use this checklist when creating a new FRIEND for a future playable character.
### Design requirements
- [ ] FRIEND motivation chosen: what drives the concealment? (Kael: protect partner, Sera: protect friend)
- [ ] Contradiction type chosen: spatial anomaly (Type A) or behavioral pattern (Type B)
- [ ] Third party identified: who the FRIEND is protecting, and why this creates the contradiction
- [ ] Sympathetic motivation: FRIEND has a reason the player can understand, even if they can't endorse it
- [ ] No clean resolution: the FRIEND arc ends in ambiguity, not revelation or catharsis
- [ ] Triangle integration: FRIEND participates in at least one active triangle (D-024)
- [ ] Dual-lens: secondary character observation notes written
### Tell requirements
- [ ] Three tells defined: peripheral + forward + direct
- [ ] Peripheral tell established in Phase 2 monologue (retroactive recognition)
- [ ] Direct tell fires during Phase 4 deflection (post-conversation monologue)
- [ ] Tell known by player character from prior context (friendship history or professional training)
### Phase requirements
- [ ] Phase 1 includes genuine emotional anchor (shared activity, personal reference, easy rapport)
- [ ] Phase 2 introduces the third party the FRIEND is protecting
- [ ] Phase 3 contradiction is physically/behaviorally observable (not dialogue-revealed)
- [ ] Phase 3 has required observation count: Type A = 1, Type B = 3
- [ ] Phase 4 deflection gives plausible answer that doesn't collapse the contradiction
- [ ] Phase 5 has three distinct resolution paths, none delivering clean closure
### Content requirements
- [ ] ~70-100 authored lines total (no generation expansion)
- [ ] Monologue pools hard-partitioned by character (D-032)
- [ ] Contradiction discovery monologue written (3-4 lines, fires on Phase 3 observation)
- [ ] Post-contradiction filtered-through-doubt monologue written (4-6 lines)
- [ ] All prerequisite fact IDs from knowledge-vocabulary-v01.md — no invented strings
### Systems integration
- [ ] FRIEND is in the knowledge graph at `KnowsOf + Friendly` from Phase 1
- [ ] Contradiction fact ID defined in knowledge-vocabulary-v01.md (e.g., `investigation.{friend}_contradiction_event`)
- [ ] Tell fact ID defined (e.g., `behavioral.{friend}_evasion`)
- [ ] Phase transitions map to relationship state changes (Friendly → PersonOfInterest)
- [ ] Resolution paths have distinct knowledge state outcomes
---
## Why This Pattern Works
**Single mechanical insight:** Asymmetric information creates emotional weight. The player has information (the observation) that the FRIEND doesn't know the player has. The FRIEND acts normally. The player watches through a new lens. That gap IS the dramatic irony.
**Systems framing:** The FRIEND arc is asymmetric information mechanics applied to trust. The player's knowledge graph and the FRIEND's knowledge graph are out of sync. The moment they sync — when the FRIEND realizes the player knows — is where the confrontation lives.
**Emergent replayability:** The dual-lens design means the FRIEND arc reads completely differently on a second playthrough as the other character. Sera's tells mean something different when you know what she's hiding. Kael's warmth is more painful when you know the exit attempt will fail. This is emergent story from system interaction, not scripted revelation.
---
*Design document. Reusable pattern template for all future FRIEND NPCs.*
*Derived from: Kael Davan (#297), Sera Venn (#298).*
*Full spec: D-034, D-039, D-041*
docs/design/cultural-generation-guide.md
+296
View File
@@ -0,0 +1,296 @@
# Cultural Generation Guide — The Settled Reach
**Ticket:** #189
**Author:** Miri
**Status:** canonical
**Last updated:** 2026-02-19
---
## Purpose
This guide provides the framework for generating culturally consistent content in The Settled Reach. Every named district, NPC, and piece of authored dialogue reflects a specific cultural context. This guide codifies how to derive that context from first principles so that any content author — writing a dockworker or a station administrator, a bar greeting or a confrontation line — can produce work that feels like it belongs.
The Sova Transit District in the Krenn System is the first concrete instance of this framework. All examples in this guide are drawn from Sova. Subsequent settings use the same framework applied to different parameters.
---
## Part 1: The Framework — Five Dimensions of Cultural Context
Every location in The Settled Reach has cultural context along five dimensions. These are not rigid categories — they blend and interact. But knowing them for a setting before writing a single line of dialogue prevents inconsistency.
### Dimension 1: Reach Position
**Range:** Core → Mid-Reach → Frontier → Deep Frontier
This determines the age of institutions, the density of infrastructure, and the relationship between residents and authority.
| Position | Infrastructure | Institutional Presence | Resident Attitude to Authority | Setting Feel |
|---|---|---|---|---|
| **Core** | Mature, well-maintained | Heavy. Commission offices, Concord representatives, Syndic headquarters | Deferential-to-compliant. Authority is a daily reality. | Corporate. Managed. Politics visible. |
| **Mid-Reach** | Functional, mixed-era | Moderate. Commission terminals, periodic visits, field investigators | Pragmatic-to-skeptical. Authority exists but isn't everywhere. | Working. Lived-in. Rules enforced selectively. |
| **Frontier** | Sparse, improvised | Light. Syndic representatives, occasional Commission audit | Independent-to-resistant. Authority is a distant abstraction. | Improvised. Tight-knit. Self-reliant. |
| **Deep Frontier** | Minimal | Nominal or none | Sovereign. Authority is whatever the community enforces. | Harsh. Communal. Rules of necessity. |
**Sova Transit District:** Mid-Reach. Commission presence is intermittent — enough to maintain order, not enough to catch everything. The district's residents are pragmatic about authority: they comply when observed, continue as normal when not.
---
### Dimension 2: Economic Base
**Range:** Freight → Resource Extraction → Manufacturing → Service → Research → Mixed
Economic base determines daily rhythms, vocabulary, and the social pressures that create narrative stakes.
| Economic Base | Daily Rhythm | NPC Concerns | Social Pressure | Narrative Hook |
|---|---|---|---|---|
| **Freight** | Span gate schedules. Shift rotations. Cargo waves. | Manifests, container counts, shift assignments, dock schedules. | Wages stable but tight. Extra income tempting. | Manifest discrepancy. Smuggling access. |
| **Resource Extraction** | Mining shifts. Equipment maintenance cycles. | Equipment reliability, extraction quotas, safety protocols. | Dangerous work, irregular income, company-town dynamics. | Workplace accident cover-up. Union pressure. |
| **Manufacturing** | Production cycles. Quality control. | Production quotas, supply chains, quality flags. | Line work monotony, automation anxiety, middle-management tension. | Sabotage. Corporate espionage. |
| **Service** | Tourist/commercial traffic. | Tips, regulars, reputation management. | Income dependent on traffic volume. Reputation fragile. | Blackmail. Theft. Information sale. |
| **Research** | Project deadlines. Funding cycles. | Research progress, institutional politics, publication credit. | Competitive, status-driven, secrecy around results. | Data theft. Fabrication. Factions. |
**Sova Transit District:** Freight primary. The span gate transit schedule structures everything. NPC routines, the ring's operational calendar, and social patterns (when the bar fills, when corridors are quiet) all derive from freight rhythm.
---
### Dimension 3: Settlement Age and Character
**Range:** New Colony (< 20 years) → Established (20-80 years) → Mature (80-200 years) → Old (200+ years)
Settlement age determines architectural character, generational memory, and whether residents think of themselves as pioneers or locals.
| Age | Architecture | Cultural Identity | Generational Memory | Relationship to Origin |
|---|---|---|---|---|
| **New Colony** | Prefab, temporary-feeling. Little personalization. | Identity still forming. People compare everything to where they came from. | Recent. First-generation. Stories of the journey. | Strong nostalgia for origin system. |
| **Established** | Prefab base showing modification. Layers visible. Some personalization, some institutional standardization. | Local identity forming but not solid. Mix of origin-cultures. | Mixed. Parents remember old places; children only know here. | Ambivalent. Here is home, but parents' memories linger. |
| **Mature** | Mixed construction eras clearly visible. Original structure heavily modified. Strong local character in older sections. | Distinct local identity. People think of themselves as "from here." | Distant. The origin is history, not memory. | Local pride. Skepticism of core-system assumptions. |
| **Old** | Accretive. Original construction may be invisible under layers. Idiosyncratic. | Deeply rooted identity. History is ambient. | Institutional. Stories are embedded in place-names and customs. | The origin system is foreign. "We are our own thing." |
**Sova Transit District:** Established-to-Mature. The district is ~40 years old on a station settled ~180 years ago. The district itself shows layered construction — prefab base, retrofitted sections, personalized details. Local identity is present but not deep. Workers think of themselves as Sova people, not Krenn people; but they don't have the rootedness of a settlement in its third or fourth generation.
---
### Dimension 4: Cultural Reference Point
The cultural reference point is the system of origin for the majority population, combined with how many generations of local drift have occurred.
This determines:
- **Naming conventions** — how names sound, what they reference, whether family names matter
- **Social norms** — eye contact, titles, how trust is established
- **Relationship to technology** — whether lattice use is stigmatized, normalized, or a source of pride
- **Attitudes toward the Commission** — reverence, compliance, resentment, or active evasion
**Krenn System Cultural Profile (established, working-class mid-Reach):**
- **Names:** Compact, consonant-heavy, first-name-primary in social contexts. Family names exist but are used formally (official documents, institutional contexts, introductions to strangers). Nicknames common among colleagues. Off-system names (longer vowels, different consonant clusters) stand out subtly but aren't cause for suspicion — just quietly noted.
- **Social norms:**
- Eye contact is normal during conversation, brief during passing. Sustained eye contact from a stranger reads as challenge or authority.
- Physical contact minimal — a hand on the shoulder is significant. A handshake is formal.
- Complaining is fine. Complaining to the person you're complaining about is not.
- Mind your business is the unspoken rule. People don't ask intrusive questions; they don't volunteer information they haven't been asked for. This makes the detective's investigation harder and the smuggler's operation safer.
- Trust is established through repeated small interactions over time, not through declarations.
- **Technology attitudes:** Lattice use is unreflective — ubiquitous, taken for granted, the way breathing is taken for granted. Checking your lattice overlay in conversation is rude but common. The Unbound (those without lattices) are a known category — treated with mild curiosity and zero hostility. Nobody makes a fuss about it. Augmented lattice (institutional or premium) carries subtle status markers — people notice, don't comment.
- **Commission attitude:** Pragmatic compliance. The Commission regulates neural lattice technology; that regulation affects everyone, constantly. Workers find it mildly onerous (recertification requirements, software update mandates, firmware flags on aftermarket accessories). The Commission isn't hated — it's just the reality of living in the Reach. Like weather.
---
### Dimension 5: Institutional Ecosystem
Every location has a set of institutions that structure daily life. Understanding which institutions are present, which are visible, and which are resented tells you how NPCs talk about authority, rules, and power.
**Core institutions across the Reach:**
| Institution | Role | Local Manifestation |
|---|---|---|
| **Concord Assembly** | Reach-wide legislature | Background. Distant. Appears in news tickers. Not visible on the ground. |
| **Lattice Commission** | Neural tech regulation | Kiosks, certification terminals, field investigators. The most visible institutional presence in most districts. |
| **Syndics** | Commercial entities, freight and resource management | The actual employers of most working-class NPCs. Contracts, shipping manifests, wage structures. |
| **Meridian** | Information network | Ambient. The infrastructure everyone uses without thinking about. Dead spots are notable. |
| **Station Administration** | Local governance | Immediate authority. Maintenance schedules, district regulations, housing allocation. |
| **Medical Services** | Re-embodiment and healthcare | Presence varies by wealth. Clinics in working districts, full services in affluent ones. |
**Sova Transit District institutional profile:**
- Syndic logistics consortium: the main employer, highly visible in daily operations
- Station Administration: present through maintenance schedules, posted notices, the occasional administrator in the corridors
- Lattice Commission: intermittent. A kiosk in the logistics hub lobby, field investigators who visit quarterly (usually)
- Medical clinic: small, basic. Re-embodiment services require transfer to the main station medical center
- Meridian: strong coverage in institutional spaces (hub, bar), degraded in older sections, minimal in maintenance corridors
---
## Part 2: Derived Guidelines — From Framework to Content
### 2.1 Naming Conventions
Naming conventions follow from Dimension 4 (Cultural Reference Point). The table below captures the Krenn System standard, which serves as the v0.1 model.
**Krenn System naming rules:**
- **First names:** 1-2 syllables, consonant-forward, no double vowels in typical form. Examples: Kael, Voss, Drin, Lera, Torek, Maret, Naia, Sera, Nils, Kosse, Pael, Tev, Ren, Resha, Harek, Sess, Devra.
- **Family names:** 1-2 syllables, similar phoneme pattern. Examples: Davan, Lintar, Sessik, Korr.
- **Social usage:** First name in most contexts. "Supervisor Voss" for institutional address. Full name only in formal or hostile contexts.
- **Nicknaming:** Common among colleagues. A name like "Renn" might be short for something nobody uses.
- **Off-system names:** Slightly softer vowels, longer syllable count, different consonant clusters. Example: Olin, Sabel. These stand out quietly — the detective's lattice may flag them as non-Krenn-origin before the detective consciously registers why.
**IP check:** Krenn names are constructed to feel plausibly human-future without mapping to any existing franchise. They are NOT Hamilton Commonwealth names (conspicuously contemporary English, which is Hamilton's signature device). They are NOT Banks Culture names (often whimsical or elaborate). They are NOT Firefly or Star Wars (no Earth-ethnic-name echoes). They suggest cultural drift across 180 years of mid-Reach settlement.
---
### 2.2 Economic Vocabulary
Economic base (Dimension 2) determines the vocabulary of daily life. Workers in a freight hub speak differently from workers in a mining operation or a research station. This vocabulary should permeate every NPC's dialogue — not as jargon dumps, but as the ambient language of their daily reality.
**Sova Transit District — Freight Economic Vocabulary:**
See companion document: **Sova Texture Appendix (#302)** for the full slang glossary.
Core vocabulary patterns for freight:
- Work = "shift" (not "rotation," not "duty," not "tour")
- The gate = "the gate" casually, "the span gate terminal" institutionally — never "the span gate" in casual speech
- Cargo containers = "containers" or "cans" (informal) — never "pods"
- Cargo manifests = "manifests" (precise), "paperwork" (dismissive), "the file" (when being evasive)
- Credits = "marks" in casual conversation (a Krenn System local usage)
- Off-shift time = "off-book" among the ring; just "after" for civilians ("see you after")
- Lattice communication = "pinging" (sending), "a ping" (notification)
---
### 2.3 Social Rhythms and Norms
The freight rhythm (span gate schedules, shift rotations) structures social life. Content authors should use these rhythms as temporal anchors for dialogue and monologue.
**Sova Transit social rhythm:**
| Time | Activity | Social Atmosphere |
|---|---|---|
| 0600-0800 | Morning shift change | High traffic, business-focused, brief greetings |
| 0800-1200 | Morning freight cycle | Focused work, minimal social interaction |
| 1200-1400 | Midday break | Break room social time, bar has light lunch trade |
| 1400-1600 | Afternoon freight cycle | Quieter, post-lunch pace |
| 1600-1800 | Evening shift change | Second major transition, people heading to or from |
| 1800-2200 | Peak bar hours | The Last Shift fills up. Main social time of the day. |
| 2200-0200 | Late night | Bar quiet (late regulars only). Corridors quieter. Ring operations typical timing. |
| 0200-0600 | Deep night | Minimal staffing. Maintenance windows. Skeleton shift. |
---
### 2.4 Relationship to Authority
Dimension 3 (Reach Position) determines how NPCs speak about, around, and to authority figures. This affects dialogue at every trust tier.
**Sova Transit — Authority Relationship Patterns:**
| NPC Type | To Commission directly | About Commission (behind back) | To institutional-tagged stranger |
|---|---|---|---|
| Flat NPC (civilian) | Cooperative, neutral. Answers questions. Doesn't volunteer. | "They do their job. Just don't want them doing *my* job." | Polite. Slightly more careful with word choice. Watches for cues. |
| Triangle NPC (mundane) | Cooperative. Slightly more nervous if personally concerned. | "They'll always find something to flag if they look hard enough." | Normal, with an undercurrent of evaluation: are they relevant to me? |
| Entangled NPC (ring) | Carefully cooperative. Prepared answers. Nothing extra. | "Commission pokes around twice a year and finds nothing because they don't know where to look." | Alert. Measures words. Changes topics smoothly. |
---
### 2.5 Technology Integration
Lattice use is unreflective for most NPCs — it's background, like breathing. Content should treat lattice references the way people treat phone references: incidentally, in passing, without ceremony.
**Correct treatment:**
> "I pinged you twice. Did you sleep through your lattice?"
**Wrong treatment (over-technological):**
> "I sent a message through the neural lattice communication network to your personal lattice implant."
**Wrong treatment (under-technological):**
> "I tried to call you." *(This isn't the Reach — people don't "call." They "ping.")*
The exception: NPCs under stress or in unusual circumstances may reference their lattice more explicitly — "I checked three times, it's not in the manifest" — where the precision itself signals anxiety.
---
## Part 3: Scaling Beyond v0.1
The Krenn System instance demonstrates the framework. Future settings apply the same five dimensions with different parameters. The cultural output — naming conventions, vocabulary, social norms, authority attitudes — follows from the parameters, not from free-form invention.
**Quick-generation checklist for a new district:**
1. **Reach Position:** Core / Mid-Reach / Frontier / Deep Frontier
→ Determines institutional density and authority attitude
2. **Economic Base:** Freight / Extraction / Manufacturing / Service / Research / Mixed
→ Determines daily rhythm and vocabulary domain
3. **Settlement Age:** New / Established / Mature / Old
→ Determines architectural character and cultural rootedness
4. **Cultural Reference Point:** Which system of origin? How many generations of local drift?
→ Determines naming conventions and social norms
5. **Institutional Ecosystem:** Which institutions are present, how visibly?
→ Determines how NPCs relate to authority
From these five inputs, the following outputs are derivable for any new setting:
- Naming conventions (with example names)
- Economic vocabulary (10-15 terms)
- Social rhythm (daily time anchors)
- Authority relationship patterns (flat/triangle/entangled × authority figure)
- Technology integration register (how casually lattice is referenced)
**When a new setting is created:** Write a cultural profile following this guide and add it to `docs/wiki/cultural-groups/`. Tag it with the relevant star system. Link from the district entry in the wiki.
---
## Part 4: The Dual Lens Principle — Culture Serves Asymmetry
Every cultural detail in The Settled Reach exists to serve asymmetric information. Culture is not decoration — it's the medium through which two characters experience the same world differently.
**What this means in practice:**
The same cultural detail should mean something different to the smuggler and the detective:
| Cultural Detail | Smuggler Reads It As | Detective Reads It As |
|---|---|---|
| "Mind your business" norm | Operational cover. Nobody asks, nobody knows. | Investigative friction. People won't volunteer. |
| First-name social culture | Social camouflage. Insider by default. | Access challenge. Have to earn first names. |
| Lattice pings as communication | Ring coordination. Off-Meridian pings are clean. | Evidence trail. Pings log to Meridian (mostly). |
| Bar as social heart | Safe social space. Home territory. | Intelligence gathering venue. |
| Commission presence intermittent | The gap in oversight is the operational window. | The jurisdictional gap is also my investigative constraint. |
| Span gate schedule as daily rhythm | The operational calendar. Timing is everything. | Investigation timeline. Window when oversight is thinnest. |
**Authoring instruction:** When writing any cultural detail — a sign, a greeting, a social norm — ask: what does the smuggler see, and what does the detective see? If the answer is identical, the detail is decorative. If the answers differ, the detail is load-bearing.
---
## Appendix: v0.1 Named Characters — Krenn System Consistency Check
All named characters in the Sova Transit District, with naming convention validation:
| Name | Convention Check | Role | Notes |
|---|---|---|---|
| Kael Davan | Krenn standard | Dock worker, ring member, smuggler's FRIEND | Full name used in formal contexts |
| Sera Venn | Krenn standard | Commission field tech, detective's FRIEND | "Venn" slightly softer than typical Krenn surname — deliberate: she's institutional, slightly apart |
| Lera Sessik | Krenn standard | Bar owner, The Last Shift | "Lera's" informal name. Never Lera Sessik to regulars. |
| Torek Lintar | Krenn standard | Dock inspector, compromised | Full name used when the detective runs his file |
| Voss | Krenn standard | Logistics supervisor | Single name in social use. Probably Voss-something officially. |
| Drin | Krenn standard | Maintenance tech, flat NPC | Single name. Been here long enough nobody uses a surname. |
| Maret Korr | Krenn standard | Freight scheduler, ring-adjacent | "Korr" is direct Krenn standard |
| Naia | Krenn standard | Kael's partner (mentioned, not primary) | Brief, soft — contrast to Kael |
| Nils | Krenn standard | Bar regular (mentioned) | |
| Kosse | Krenn standard | Station name / character reference | |
| Pael | Krenn standard | Maintenance tech, flat NPC (Sprint 12: #307) | |
| Tev | Krenn standard | Lookout/runner, flat NPC (Sprint 12: #307) | |
| Ren | Krenn standard | Drifter, flat NPC (Sprint 12: #307) | "Ren" is earlier-established; "Renn" is the courier variant from Round 2 mapping |
**Off-system characters (deliberate naming deviation):**
| Name | Deviation | Role | Purpose of Deviation |
|---|---|---|---|
| Resha | Softer vowel pattern | New hire | Implies off-system origin — explains why they ask too many questions |
| Sabel | Different phoneme cluster | Ring fence/buyer, external contact | External contact should sound external |
**IP check:** All Krenn names validated against Hamilton (Contemporary English — cleared), Banks (whimsical/elaborate — cleared), Reynolds (Dutch/Germanic — cleared), Simmons (Greek/Latin register — cleared), Morgan (Anglo-American register — cleared). No franchise overlap found.
---
*This guide is a living document. As new settings are established, update the scaling examples. As cultural decisions are refined through gameplay testing, update the social norm descriptions. The framework is the constant; the instances are the evidence.*
*Miri — Sprint 12*
docs/design/first-5-minutes-experience.md
+232
View File
@@ -0,0 +1,232 @@
# First 5 Minutes Experience Design
**Ticket:** #259
**Owner:** Gestalt (systems framework)
**Unblocks:** #260 (opening hook content per character)
**Source:** D-027 (vertical slice success criteria), D-032 (monologue pools), D-041 (background knowledge)
**Date:** 2026-02-19
---
## Design Constraints
### What this IS
A systemic opening sequence using only existing game systems. No cutscene. No special tutorial mode. No force-scripted path. The game runs at tick 1 — fog active, NPCs on schedule, world simulating — and the player experiences a designed version of that.
"Designed" means: the storyteller has selected a seed-specific opening state that makes the first 5 minutes feel motivated, not random. The player has clear first actions without being told to do them.
### What this is NOT
- A cutscene explaining the premise
- An objective marker pointing the player somewhere
- A tutorial UI teaching them how to move
- A scripted conversation they must complete
- A guaranteed identical sequence on every run
### D-027 success criteria — first 5 minutes contribution
The first 5 minutes must lay the foundation for all four success criteria:
1. **30 minutes of breathing room** — opening must feel like daily life, not like a conspiracy. The hook should be subtle enough that the player isn't in investigation mode yet.
2. **Different games** — smuggler and detective must feel like different people in different situations from tick 1.
3. **Named NPC** — the FRIEND relationship must be established in the first 5 minutes, before any contamination.
4. **Emerge from systems** — the first "something is wrong" must be observable, not spoken.
---
## Systems That Fire in the First 5 Minutes
### Tick 0: World state initialized
At game start, before the player's first input:
- Knowledge graph loaded with Background facts (per Appendix A, `docs/design/knowledge-flags-v01.md`)
- NPCs on their Phase 1 schedules (D-034 friend arc: baseline, no deviations)
- Fog fully opaque — the player's vision cone starts revealing the world from their spawn position
- Ambient audio playing (span gate hum, station background)
### First input: Movement
First LOS reveal is the first conscious experience. The world expands around the player's movement. This is simultaneously:
- Tutorial for the fog system (learned by doing, not told)
- Spatial introduction to the opening location
- First monologue opportunity: `enter_location` trigger fires on first tile in a new zone
**Design requirement:** The spawn location must have something interesting in LOS range without moving. The player should be able to see at least one NPC or meaningful location element from their starting position.
### First monologue: enter_location trigger
The insert chime plays (UI sounds bus, D-068). First internal monologue line fires from the `enter_location` trigger pool for this location.
**This line does three things:**
1. Establishes character voice (who are you?)
2. Establishes relationship to the space (do you belong here?)
3. Plants the first seed of the day's texture (operational awareness or investigative alertness)
The player doesn't need to understand the monologue system — they just hear a thought that sounds like them.
### First NPC: observe_npc trigger
Within the first minute of play, a significant NPC should enter the player's LOS. This is designed into the opening state: the FRIEND is present or arrives during this window.
The observe_npc trigger fires an appropriate opening-register monologue line. For the FRIEND specifically:
- Smuggler → sees Kael: warmth, ease, "the day is better when he's here"
- Detective → sees Sera (if bar opening) or a stranger (if Terminal opening): recognition vs. observation
**The FRIEND must be established in the first 5 minutes.** This is the anchor for success criterion #3.
### First operational beat
Within 2-3 minutes, the player encounters something to DO — not a quest, but a situation that pulls them toward action.
- **Smuggler:** Kael is at dock. Lunch window approaching. Shift board has today's assignments. Checking in = social interaction + operational context.
- **Detective:** Sera's usual booth. Or a manifest terminal with flagged entry. Or Voss giving the new arrival a territorial once-over.
The first action should be something the character would naturally do. Not "find the smuggling ring" — "say hello to Kael" or "get a read on the district."
---
## Character Opening Designs
### Smuggler Opening
**Core emotional register:** Operational confidence. This is your place. You know these people, this space, this rhythm. Something small is slightly off — but you won't notice it for a few minutes.
**Starting location:** The Terminal (Logistics Hub), dock floor or break room area.
**Background knowledge active at game start:**
- Full ring routing knowledge (`knows_details: knowledge.ring_routing_knowledge`)
- Kael is a ring member and close friend (`knows_details + friendly`)
- Today's operational context (whether a drop is scheduled or it's a routine day)
**First 5 minutes beat sequence:**
| Beat | Trigger | System | Content Purpose |
|------|---------|--------|-----------------|
| 1 | Enter Terminal | `enter_location` | Voice + tone established. "Home sweet home" register. |
| 2 | See Kael (if on shift) | `observe_npc` | FRIEND Phase 1 warmth. "The day's better when he's on shift." |
| 3 | See shift board / loading arms | `enter_location` / `observe_anomaly` | Operational awareness. World is working. |
| 4 | First Phase 2 signal (optional, seed-dependent) | `observe_anomaly` or time | Kael checks lattice. Brief distracted pause. Too subtle to read. |
| 5 | First interaction opportunity | WASD to Kael, dialogue opens | Natural: greet your friend. Establishes the relationship interactively. |
**Hook:** The day feels normal. That's the hook. You're inside something, comfortable. The player doesn't know yet that they're going to want to understand what Kael is hiding.
---
### Detective Opening
**Core emotional register:** Arriving into someone else's established rhythm. You are the outsider here. The district has its own momentum and you have to find your place in it.
**Starting location:** Variable by seed — see opening variant table below.
**Background knowledge active at game start:**
- Manifest discrepancy flagged (`suspects: investigation.manifest_discrepancy`)
- Commission jurisdiction understood (`knows_details: world.commission_sova_jurisdiction`)
- Corridor B-7 flagged as restricted zone (`knows_of: location.corridor_b7_restricted`)
- Sera Venn as pre-existing contact (if bar-first variant)
**First 5 minutes beat sequence:**
| Beat | Trigger | System | Content Purpose |
|------|---------|--------|-----------------|
| 1 | Arrive in district / enter first location | `enter_location` | Clinical register. "Sova Transit. Working-class pragmatic. Start reading the room." |
| 2 | See first NPC (Voss or dock worker) | `observe_npc` | Institutional observation. Territorial reception or neutral professionalism. |
| 3 | See Sera (if bar variant) or manifest terminal (if Terminal variant) | `observe_npc` or `observe_anomaly` | Either: warmth of familiar contact OR analytic flagging of first anomaly |
| 4 | First lattice query opportunity | `observe_anomaly` near manifest data | Detective's analytical lattice flags a discrepancy. Knows this behavior. |
| 5 | First adversarial NPC | Voss or institutional resistance | First social friction. The district doesn't want you here. |
**Hook:** The detective is watching. Every detail potentially matters. The detective never relaxes into the environment the way the smuggler does — but they notice things the smuggler misses. The player feels competent and slightly outside.
**First NPC is adversarial by default** (per sprint brief). Even in the warm-arrival Sera variant, the first dock-floor NPC (Voss) reads the detective as an institutional intrusion and responds territorially. The detective has authority; using it has social costs.
---
## Seed-Selected Opening Variants
The storyteller selects from 3-4 opening states per character at game start. This creates replay variation without scripted divergence — the systems remain the same, the initial conditions differ.
### Smuggler variants (3-4 opening states)
| Variant | Initial Condition | First Difference Felt |
|---------|------------------|----------------------|
| **A: Quiet morning** | Kael on shift, no deviations, routine operational day | Day feels completely normal. The crack doesn't appear until 10+ minutes. |
| **B: Kael is late** | Kael hasn't arrived at expected time — first behavioral anomaly is his absence, not his presence | Player starts without the FRIEND anchor. Absence itself is the first tell. |
| **C: Heat from Voss** | Shift supervisor is monitoring the dock more than usual — scheduling tension | Operational caution from the start. The ring feels more exposed. |
| **D: Container held** | An operational container is in temp storage longer than routing protocol specifies | First anomaly is logistical, not relational. Triggers operational investigation before social. |
**Storyteller selection logic:** The storyteller picks based on seed-configured narrative pressure. Quiet morning on low-pressure seeds; Kael late or container held on medium-pressure; all three tensions concurrent on high-pressure opens.
### Detective variants (3-4 opening states)
| Variant | Initial Condition | First Difference Felt |
|---------|------------------|----------------------|
| **A: Bar first (warm arrival)** | Sera has been contacted ahead of time — detective starts at The Last Shift | First contact is friendly. District access comes through Sera's social network. |
| **B: Terminal first (cold arrival)** | No pre-contact — detective enters through the dock floor | First NPC is territorial (Voss). Institutional authority is the only access mechanism. |
| **C: Evidence in hand** | Arrives with two manifest discrepancies already flagged from prior analysis | Opens in investigation mode. First observations are filtered through existing suspicion. |
| **D: Institutional escort** | Commission liaison accompanies detective briefly — creates visible institutional friction with locals | Authority is visible and creates social walls immediately. Bar regulars see the badge first. |
**Storyteller selection logic:** Bar-first on low-pressure seeds (softest introduction, most narrative space). Evidence-in-hand on high-pressure seeds (player is already in investigation mode, mystery accelerates).
---
## The "Not A Tutorial" Rule
The first 5 minutes teach the systems through play, not instruction.
| System | How It's Taught |
|--------|----------------|
| Fog / LOS | Player moves; fog reveals. No explanation needed. |
| Monologue | Chime plays + character speaks. Player hears their internal voice immediately. No UI callout. |
| NPC observation | Observe an NPC; monologue responds. Causal connection is felt, not explained. |
| Knowledge graph | Relationship color appears on FRIEND (green). Player learns to read colors before understanding what they mean. |
| Dialogue | First dialogue is low-stakes — greeting a colleague. Player learns the system exists before they need to use it strategically. |
| Insert / map | Player opens insert naturally (looking for objectives). Insert contains only what their character would have on it. |
**No tutorial pop-ups.** Monologue handles all context. If the player does something and a monologue line fires about it, that IS the tutorial.
---
## Opening Hook Content Brief (for #299/#300)
This section briefs Mellanie and Paula on what the opening hook monologue lines need to accomplish.
### Smuggler opening hook (feeds #299)
**Lines needed:**
- 3-5 `enter_location` (Terminal) lines — operational warmth, different registers
- 2-3 `observe_npc` (Kael, Phase 1) lines — genuine affection, colleague register
- 2-3 `observe_npc` (Voss) lines — professional caution, working relationship
- 1-2 `observe_npc` (dock floor general) lines — belonging, routine
- 2-3 variant lines for non-standard opens (Kael absent, container held)
**Voice requirements:** Short sentences. Operational. Comfortable. The smuggler is home.
**Knowledge prereqs available:** All Background facts active from tick 0. No investigation prereqs needed for opening lines. `ring_routing_knowledge` at `knows_details` — lines can reference operational reality.
### Detective opening hook (feeds #300)
**Lines needed:**
- 3-5 `enter_location` (Terminal or bar) lines — observational register, arriving perspective
- 2-3 `observe_npc` (Sera, if bar variant) lines — recognition + warmth + slight wistfulness
- 2-3 `observe_npc` (Voss or unknown dock worker) lines — clinical assessment, outsider reading the room
- 2-3 `observe_anomaly` lines — lattice firing on first anomalies
- 2-3 variant lines for cold-arrival opens (terminal first, no Sera contact)
**Voice requirements:** Complete sentences. Precise. Observational. The detective is reading, not inhabiting.
**Knowledge prereqs available:** `suspects: investigation.manifest_discrepancy` active from tick 0. Lines can reference the anomaly as existing suspicion. `knows_details: world.commission_sova_jurisdiction` — institutional confidence is in voice from the start.
---
## Success Metric
The first 5 minutes are successful if:
1. The player has not been told what to do, but knows what to do
2. The player has met the FRIEND before anything suspicious has happened
3. The player has experienced at least one monologue line that felt like it came from inside them
4. The player is curious about something — the district, a person, the operational texture — without being told to be curious
5. The two characters feel like different people in different situations, not the same player in two costumes
---
*Systems design brief. Line authoring: Mellanie (#299, #300). Paula may add narrative texture per character voice.*
docs/design/knowledge-flags-v01.md
+273
View File
@@ -0,0 +1,273 @@
# Knowledge Flags — v0.1 Quick Reference
**For:** Mellanie (content authoring), Paula (narrative design)
**Source:** docs/design/knowledge-vocabulary-v01.md (full specification)
**Ticket:** #309 — unblocks #299, #300 (opening hook content)
**Date:** 2026-02-19
---
## How to Use This Document
When writing a monologue line that should only fire once the character knows something specific, add a `prerequisites:` block. Use the fact IDs and shorthand from this document — do not invent strings.
### The three prerequisite types
```yaml
# 1. Entity relationship check
prerequisites:
relationship:
target: npc:kael-davan # use the NPC's kebab-case file name
state: friendly # unknown | known | friendly | person_of_interest | hostile
# 2. World fact check
prerequisites:
facts:
- fact_id: investigation.kael_corridor_meeting
min_confidence: suspects # suspects | knows_of | knows_details | direct
# 3. Entity attribute check (rare — use for specific behavioral tells)
prerequisites:
entity_attributes:
- entity: npc:kael-davan
key: behavior_flags
value: avoidance
```
All conditions are AND. For OR logic, write two lines with different prerequisites targeting the same trigger.
---
## Confidence Level Cheat Sheet
| Level | Shorthand | Plain English | When to use it |
|-------|-----------|---------------|----------------|
| `suspects` | `suspects:` | "Something's off" | Early-game, vague lines — player has noticed but not confirmed |
| `knows_of` | `knows:` | "X is connected to Y" | Mid-game, specific lines — player has real information |
| `knows_details` | `knows_details:` | "X did Y because Z" — actionable | Late-game, confrontation-adjacent lines — player knows enough to act |
| `direct` | `direct:` | "I'm looking at it right now" | Set by perception system, not authored — use only for immediate-observation monologue |
**Design rule:** Most lines need no prerequisites (they fire freely on trigger). Gated lines should reveal something the ungated versions can't say. Don't over-gate — use prerequisites to create *surprise when a new line appears*, not to withhold most of the content.
---
## Valid Fact IDs
### `investigation.*` — case findings
Use for: specific events witnessed, evidence found, NPC behaviors confirmed through investigation.
```
investigation.kael_corridor_meeting Kael was seen in B-7 off-shift, meeting someone
investigation.kael_corridor_sighting Detective's initial B-7 observation (detective only)
investigation.kael_unknown_contact Kael's contact is not from the regular rotation
investigation.kael_ring_membership Kael is a ring member
investigation.kael_exit_attempt Kael is trying to leave the ring
investigation.manifest_discrepancy Cargo manifests show irregularities
investigation.cargo_anomaly Specific container/weight/route anomaly
investigation.shift_mismatch Shift records don't match observed personnel
investigation.voss_ring_involvement Voss manages schedule changes to cover drops
investigation.torek_spending_pattern Torek is spending beyond his means
investigation.drin_inspection_pattern Drin's inspections are conspicuously lax
investigation.drin_gambling_debt Drin has a gambling debt — leverage
investigation.oversight_gap_pattern Inspection gaps are systematic, not random
investigation.surveillance_gaps Specific corridor camera blind spots
investigation.smuggling_route The exact smuggling route through the station
investigation.ring_existence A smuggling ring is definitely operating here
investigation.renn_courier_role Renn is a courier for the ring
investigation.corridor_regular_use Maintenance corridors are routinely used for drops
investigation.container_delay A specific container has been held too long
investigation.sera_evidence_held Sera has unreported manifest evidence
investigation.naia_lattice_condition Naia's lattice is degrading — the medical components are for her
investigation.ring_leadership Who directs ring operations (late discovery)
```
### `awareness.*` — situational awareness
Use for: who's present right now, active threats, operational status.
```
awareness.detective_presence A Commission detective is on Sova
awareness.detective_investigating_ring Detective is specifically targeting the ring
awareness.commission_audit_scheduled An audit is coming — officially scheduled
awareness.ring_route_compromise The current drop route may be blown
awareness.surveillance_change Corridor surveillance patterns have changed
awareness.ring_tension_escalation Something is wrong inside the ring
awareness.inspection_sweep_active Active sweep in progress right now
```
### `behavioral.*` — recognized patterns
Use for: tells and habits confirmed through multiple observations.
```
behavioral.kael_evasion Kael looks left when lying — tell recognized
behavioral.kael_behavioral_change Kael is quieter, distracted, different from normal
behavioral.sera_avoidance_pattern Sera consistently avoids Torek Lintar
behavioral.sera_topic_deflection Sera deflects Commission/manifest topics
behavioral.sera_kiosk_pattern Sera stops at the same kiosk at the same time
behavioral.sera_knowledge_detail Sera's offhand comments reveal too much routing knowledge
behavioral.voss_awareness Voss is tracking people — beyond normal supervisor behavior
```
### `knowledge.*` — operational knowledge
Use for: procedural/institutional knowledge the character has accumulated or knows from background.
```
knowledge.ring_routing_knowledge Full drop routes and timing protocols (smuggler background)
knowledge.ring_bar_operations The bar has a role in ring communications
knowledge.bar_back_room_significance The back room at The Last Shift matters somehow
knowledge.bar_ring_awareness Bar regulars have varying awareness of the ring
knowledge.kael_exit_plan Kael has a specific exit plan — timing, contact, conditions
```
### `contraband.*` — smuggling ring world facts
Use for: what the ring is moving and how.
```
contraband.ring_exists A smuggling operation is running through Sova (smuggler starts at knows_details)
contraband.ring_lattice_components The ring moves unlicensed lattice mods
contraband.ring_medical_components The ring also moves diverted medical-grade lattice
contraband.supply_chain Understanding of where the components come from
contraband.severance_tech_presence Severance counter-surveillance tech is in play
contraband.drop_tonight A drop is scheduled for tonight
```
### `location.*` — spatial knowledge
Use for: what a location is, who has access, what it's used for.
```
location.corridor_b7_restricted Corridor B-7 requires credentials
location.corridor_b7_drop_site B-7 is an active drop site
location.maintenance_corridors_access Character can navigate the maintenance corridor layout
location.bay4_sealed Bay 4 is sealed — inspection or cover
location.span_gate_schedule_gap Span gate has a window that enables unseen drops
```
### `relationship.*` — inter-NPC connections
Use for: third-party connections between NPCs (not player-NPC relationship).
```
relationship.kael_naia_connection Kael and Naia are romantically partnered
relationship.ring_membership Player has identified specific ring members
relationship.trust_network Who trusts whom inside the ring (operational level)
```
### `social.*` — social positioning
Use for: player's social standing in a specific context.
```
social.bar_regular_status Player is a recognized regular at The Last Shift
```
---
## Valid NPC IDs (for `relationship:` and `entity_attributes:` blocks)
```
npc:kael-davan Dock worker, smuggler's FRIEND, ring member
npc:sera-venn Commission field tech, detective's FRIEND
npc:voss Shift supervisor, ring operative
npc:maret-korr Scheduler
npc:drin Inspector, ring-adjacent
npc:torek-lintar Dock worker, spending beyond means
npc:naia-tamm Ring adjacent, Kael's partner
npc:nils-davan Kael's brother, dock worker
npc:lera-sessik Bar owner at The Last Shift
npc:renn Drifter, ring courier
npc:pell Maintenance
npc:sess Dock worker
npc:tav Dock worker
npc:sabel Bar regular
npc:harek Bar regular / dock adjacent
npc:olin Ring operative
npc:resha Ring operative
npc:devra Ring operative
```
---
## Character Starting Knowledge
Lines in the opening sequence should fire on Background knowledge — these facts are in the graph from tick 0, no investigation needed.
### Smuggler — knows at game start
The smuggler IS in the ring. These prerequisites will always pass:
| Fact ID | Confidence |
|---------|-----------|
| `contraband.ring_exists` | `knows_details` |
| `knowledge.ring_routing_knowledge` | `knows_details` |
| `contraband.ring_lattice_components` | `knows_details` |
| `location.corridor_b7_drop_site` | `knows_details` |
| `location.maintenance_corridors_access` | `knows_details` |
| `world.lattice_regulation_active` | `knows_of` |
### Detective — knows at game start
The detective has anomalies flagged, but nothing confirmed:
| Fact ID | Confidence |
|---------|-----------|
| `investigation.manifest_discrepancy` | `suspects` |
| `contraband.ring_exists` | `suspects` |
| `world.lattice_regulation_active` | `knows_details` |
| `location.corridor_b7_restricted` | `knows_of` |
---
## Opening Hook Prereq Patterns (for #299/#300)
### Smuggler opening lines (first 10-15 monologue lines)
The smuggler arrives with operational awareness. Use these patterns:
```yaml
# No prereqs — fires for any player on arrival (atmospheric, sets tone)
trigger: enter_location
tags: [arrival, atmospheric]
# Fires when smuggler sees a specific known NPC
trigger: observe_npc
# No prereqs needed — smuggler knows everyone from background
tags: [npc, kael, warm]
# First sign something might be wrong
prerequisites:
facts:
- fact_id: contraband.ring_exists
min_confidence: knows_details # Always true for smuggler — line fires immediately
tags: [operational, setup]
```
### Detective opening lines (first 10-15 monologue lines)
The detective arrives with a case hypothesis. Use these patterns:
```yaml
# No prereqs — arrives fresh, first impressions
trigger: enter_location
tags: [arrival, institutional]
# First lattice-flag moment
prerequisites:
facts:
- fact_id: investigation.manifest_discrepancy
min_confidence: suspects # True from background — detective has the anomaly flagged
tags: [investigation, lattice]
# Sees a person of interest for the first time
trigger: observe_npc
# No prereqs for first sighting — use relationship gating on follow-up lines
tags: [npc, observation]
```
---
*Quick reference for Sprint 12 content authoring. Full specification: docs/design/knowledge-vocabulary-v01.md*
docs/design/knowledge-vocabulary-v01.md
+531
View File
@@ -0,0 +1,531 @@
# Knowledge Vocabulary for v0.1 Content
**Source:** D-041 (Knowledge Graph Data Model), D-035 (Tag Taxonomy), D-028 (Dialogue Architecture), D-075 (Dialogue Filtering)
**Ticket:** #368
**Unblocks:** #309 (knowledge state vocabulary for v0.1) → #299, #300 (opening hook content)
**Date:** 2026-02-19
---
## Overview
Two knowledge stores, one prerequisite system.
**Entity knowledge** — what your character knows *about a specific NPC*. Stored per entity in `EntityKnowledge.known_attributes`. Six attribute categories. Accessed via `relationship:` and `entity_attributes:` blocks in `prerequisites:`.
**Fact knowledge** — what your character knows *about the world*. Stored in `KnowledgeGraph.facts`, keyed by `FactId` in `category.topic` format. Eight categories. Accessed via `facts:` blocks in `prerequisites:`.
Both stores gate monologue lines (D-035 `prerequisite` tag) and dialogue access tiers (D-028 / D-075).
---
## Part 1: Confidence Levels
Four levels. Ordered ascending. Knowledge decays downward over time (once per game-minute, per D-031/D-026).
| Engine Name | Author Shorthand | Plain English | What It Unlocks |
|-------------|-----------------|---------------|-----------------|
| `Suspects` | `suspects:` | "Something's off" / "I've heard the name" | Initial investigation, vague monologue, open-ended questions |
| `KnowsOf` | `knows:` | "X is involved in Y" / "X has a connection to Z" | Topic-specific dialogue, specific monologue, peer-tier access (D-075) |
| `KnowsDetails` | `knows_details:` | "X did Y at Z because W" — actionable | Confrontation unlock, secret-tier dialogue (D-075), detailed monologue |
| `Direct` | `direct:` | "I'm looking at X right now" | Live position, full rendering fidelity — **set by perception system, not authored** |
**Decay path:** `Direct` → `KnowsDetails` → `KnowsOf` → `Suspects` (floor — `Suspects` does not decay further).
**For content authors:** Lines gated at `suspects:` fire early and broadly. Lines gated at `knows_details:` fire late and rarely. Design monologue arcs with both ends — arrival lines (no prereqs) and deep-investigation lines (high confidence prereqs).
---
## Part 2: Entity Knowledge
Entity knowledge tracks what character A knows about a specific NPC B. Stored in `EntityKnowledge.known_attributes` as a BTreeMap of string keys. The `EntityKnowledge` struct also carries `confidence`, `relationship`, `state`, and `source` fields at the top level.
### 2.1 Entity Knowledge Categories
Six categories of entity-level knowledge for v0.1:
| Category | What It Covers | Key Attributes |
|----------|---------------|----------------|
| **identity** | Who they are — name, role, faction affiliation | `name`, `role`, `faction`, `species` |
| **location** | Where they go — last known position, routine zones | `routine_pattern` (observed), `last_known_position` (system-managed) |
| **behavior** | How they act — tells, flags, pattern anomalies | `routine_pattern`, `behavior_flags`, `tell_observed` |
| **relationship** | Their connections — to the player, to other NPCs | `relationship_type`, `trust_level`, `loyalty_assessment` |
| **secret** | What they're hiding — leverage, contradiction flags | `leverage_held`, `leverage_confidence`, `contradiction_flagged` |
| **contraband** | Ring involvement — membership, operational knowledge | `faction` (ring member), `behavior_flags` (contraband-tagged) |
Full attribute definitions: `content/global/knowledge/entity-attributes.yaml`
### 2.2 Prerequisite Format — Entity Checks
```yaml
# Check relationship state with a specific entity
prerequisites:
relationship:
target: npc:kael-davan
state: friendly # unknown | known | friendly | person_of_interest | hostile
# Check a specific entity attribute value
prerequisites:
entity_attributes:
- entity: npc:kael-davan
key: behavior_flags
value: avoidance
# Both together (all conditions AND)
prerequisites:
relationship:
target: npc:kael-davan
state: person_of_interest
entity_attributes:
- entity: npc:kael-davan
key: contradiction_flagged
value: meeting_unknown_contact
```
**Relationship states** (D-033): `unknown` · `known` · `friendly` · `person_of_interest` · `hostile`
### 2.3 Entity Shorthand Conventions
For planning and #309 shortlist authoring:
| Shorthand | Meaning | Prerequisite Equivalent |
|-----------|---------|------------------------|
| `met: npc:{id}` | NPC is in the knowledge graph at all | entity entry exists, any confidence |
| `has_seen: npc:{id}` | NPC was directly observed in LOS at least once | Direct confidence was set at least once |
| `knows_npc: npc:{id}` | Character knows who this NPC is (KnowsOf+) | entity confidence ≥ KnowsOf |
| `friend: npc:{id}` | Friendly relationship established | relationship state = friendly |
| `poi: npc:{id}` | NPC flagged as person of interest | relationship state = person_of_interest |
| `hostile: npc:{id}` | Character perceives NPC as hostile | relationship state = hostile |
---
## Part 3: Fact Knowledge
Fact knowledge tracks non-entity information — events, situations, operational states, world conditions. Stored in `KnowledgeGraph.facts` keyed by `FactId`.
### 3.1 Fact ID Naming Convention
**Format:** `{category}.{topic_in_snake_case}`
**Examples:**
- `investigation.kael_corridor_meeting`
- `awareness.detective_presence`
- `behavioral.sera_avoidance_pattern`
- `knowledge.ring_routing_knowledge`
**Naming rules:**
- Category is always one of the eight below
- Topic uses `snake_case`, no spaces, no hyphens
- Topic should name one discrete fact — specific enough to gate a specific line
- Avoid generic topics: `thing_happened` → no; `kael_seen_with_unknown_contact` → yes
- NPC facts use the NPC's canonical short name: `kael`, `sera`, `voss`, `torek`, `drin`, `renn`
- Shared facts across characters use identical IDs — same fact, different confidence per character
### 3.2 Fact Categories
Eight categories for v0.1:
| Category | What It Tracks | Namespace Usage |
|----------|---------------|-----------------|
| `investigation` | Case-specific findings — events witnessed, evidence discovered, NPC behaviors confirmed | Primary investigation facts, both characters |
| `awareness` | Situational awareness — who's present, active threats, operational status changes | Real-time or near-term situational facts |
| `behavioral` | Behavioral patterns recognized across multiple observations | Accumulated tell data, avoidance patterns, habit deviations |
| `knowledge` | Operational knowledge — ring procedures, bar dynamics, specific institutional mechanics | Character-background knowledge + learned procedures |
| `contraband` | Smuggling ring facts — existence, components, routes, supply chain | Ring-specific world facts |
| `location` | Location-specific facts — access rights, significance, usage patterns | Spatial knowledge that drives spatial decisions |
| `relationship` | Inter-NPC connections — who knows who, what connects them | Third-party relationship knowledge (not player-NPC) |
| `social` | Social positioning — standing in a social context, bar regular status | Context-specific social facts |
> **Note on `progress` category:** A `progress` namespace exists in the file structure but is not used directly in prerequisite checks. Narrative phase gating uses relationship states and specific investigation facts rather than explicit progress flags. Authors should NOT create `progress.*` facts for opening hook content — use investigation fact chains instead.
### 3.3 Prerequisite Format — Fact Checks
```yaml
# Single fact check
prerequisites:
facts:
- fact_id: investigation.kael_corridor_meeting
min_confidence: suspects
# Multiple facts (all must pass)
prerequisites:
facts:
- fact_id: knowledge.ring_routing_knowledge
min_confidence: knows_details
- fact_id: awareness.detective_presence
min_confidence: knows_of
# Combined entity + fact check
prerequisites:
relationship:
target: npc:kael-davan
state: friendly
facts:
- fact_id: investigation.kael_corridor_meeting
min_confidence: knows_of
```
**`min_confidence` values:** `suspects` · `knows_of` · `knows_details` · `direct`
### 3.4 Fact Shorthand Conventions
For planning, shortlists, and #309 authoring:
| Shorthand | Meaning | Prerequisite Equivalent |
|-----------|---------|------------------------|
| `suspects: {fact_id}` | Fact known at Suspects level | `min_confidence: suspects` |
| `knows: {fact_id}` | Fact known at KnowsOf level | `min_confidence: knows_of` |
| `knows_details: {fact_id}` | Fact known at KnowsDetails level | `min_confidence: knows_details` |
| `phase: {progress_fact}` | Narrative milestone reached | relationship-state check or specific investigation fact |
---
## Part 4: v0.1 Fact Catalog — Transit District
Canonical fact list for the Sova Transit District scenario. All fact IDs in content must appear here. This is the source of truth for #309 (knowledge state vocabulary for v0.1).
Facts marked **[S]** are relevant to the Smuggler, **[D]** to the Detective, **[B]** to both.
### 4.1 Investigation Facts
Case-specific findings accumulated through play.
| Fact ID | Plain Description | Typical Confidence When Learned | Chars |
|---------|------------------|--------------------------------|-------|
| `investigation.kael_corridor_meeting` | Kael was seen in corridor B-7 off-shift, apparently meeting someone | `suspects` (glimpsed) → `knows_of` (confirmed) | B |
| `investigation.kael_corridor_sighting` | Kael spotted in the maintenance corridors at an unusual hour (detective's initial observation ID) | `suspects` | D |
| `investigation.kael_unknown_contact` | The person Kael met in B-7 is unknown — not from the regular rotation | `suspects` → `knows_of` | B |
| `investigation.kael_ring_membership` | Kael is a member of the smuggling ring | `suspects` → `knows_details` | B |
| `investigation.manifest_discrepancy` | Cargo manifests show irregularities — containers, weights, routing anomalies | `suspects` (detective lattice scan) → `knows_of` | B |
| `investigation.manifest_discrepancy` | *Same ID, different source:* Smuggler notices an anomalous entry in shared manifest data | `suspects` → `knows_of` | S |
| `investigation.cargo_anomaly` | A specific cargo anomaly — wrong container, wrong weight, wrong route | `suspects` (observation) | D |
| `investigation.shift_mismatch` | Shift records don't match observed personnel — someone's covering for someone | `knows_of` | B |
| `investigation.voss_ring_involvement` | Voss is involved in ring operations — schedule changes cover for drops | `knows_of` (pattern) → `knows_details` | B |
| `investigation.torek_spending_pattern` | Torek is spending beyond his means — drinks, visible spending uptick | `knows_of` (observation) | B |
| `investigation.drin_inspection_pattern` | Drin's inspection style is conspicuously casual — clearing containers without real checking | `knows_of` | D |
| `investigation.drin_gambling_debt` | Drin has a gambling debt — provides leverage for whoever is running him | `knows_details` | D |
| `investigation.oversight_gap_pattern` | Inspection gaps are systematic, not accidental — someone designed the blind spots | `knows_of` → `knows_details` | D |
| `investigation.surveillance_gaps` | Specific surveillance gaps in the maintenance corridors — where the cameras don't reach | `knows_details` | B |
| `investigation.smuggling_route` | The specific smuggling route through the station | `knows_details` | B |
| `investigation.ring_existence` | A smuggling operation is definitely running through Sova Transit | `suspects` (accumulating anomalies) → `knows_of` | D |
| `investigation.renn_courier_role` | Renn operates as a courier in the ring — runs packages between drop sites | `knows_of` | D |
| `investigation.corridor_regular_use` | The maintenance corridors are regularly used for smuggling runs, not just incidentally | `knows_of` | D |
| `investigation.container_delay` | A specific container has been held in temporary storage longer than normal — something is wrong | `suspects` | S |
| `investigation.sera_evidence_held` | Sera has unreported evidence about manifest irregularities — sitting on it deliberately | `suspects` (avoidance pattern) → `knows_details` (Sera discloses) | D |
| `investigation.kael_exit_attempt` | Kael is actively trying to leave the ring | `knows_of` → `knows_details` | B |
| `investigation.naia_lattice_condition` | Naia's neural lattice is degrading — the medical components are for her | `knows_details` (Kael discloses or Naia encountered) | B |
> **Normalization note:** `investigation.kael_corridor_meeting` (smuggler perspective, meeting focus) and `investigation.kael_corridor_sighting` (detective perspective, initial observation) describe different observations of the same event. They should remain as separate IDs — the detective may reach `kael_corridor_meeting` after establishing `kael_corridor_sighting`. Content authors should prefer `kael_corridor_meeting` when writing lines that reference the meeting itself.
### 4.2 Awareness Facts
Situational awareness — who's here, what's active, what's changed.
| Fact ID | Plain Description | Typical Confidence | Chars |
|---------|------------------|-------------------|-------|
| `awareness.detective_presence` | A Commission detective is operating on Sova Station | `knows_of` (rumor, observation) | S |
| `awareness.detective_investigating_ring` | The detective is specifically investigating the ring, not a routine audit | `knows_details` | S |
| `awareness.commission_audit_scheduled` | A Commission audit is coming — schedule confirmed | `knows_of` | B |
| `awareness.ring_route_compromise` | The current smuggling route may be compromised or under observation | `suspects` → `knows_of` | S |
| `awareness.surveillance_change` | Surveillance patterns in the corridors have changed recently | `suspects` | S |
| `awareness.ring_tension_escalation` | Tension inside the ring is escalating — someone is scared or making moves | `suspects` → `knows_of` | S |
| `awareness.inspection_sweep_active` | Active inspection sweep in progress right now | `direct` | B |
### 4.3 Behavioral Facts
Patterns recognized through repeated observation across multiple scenes.
| Fact ID | Plain Description | Typical Confidence | Chars |
|---------|------------------|-------------------|-------|
| `behavioral.kael_evasion` | Kael uses a specific evasion tell (looks left when lying) — recognized post-conversation | `direct` (set in conversation) | S |
| `behavioral.kael_behavioral_change` | Kael's behavior has noticeably changed recently — quieter, distracted, different routine | `suspects` → `knows_of` | S |
| `behavioral.sera_avoidance_pattern` | Sera consistently avoids Torek Lintar — leaves when he arrives, repositions | `suspects` (one observation) → `knows_of` (pattern confirmed) | B |
| `behavioral.sera_topic_deflection` | Sera deflects specific topics — Commission work, manifest audits | `suspects` → `knows_of` | B |
| `behavioral.sera_kiosk_pattern` | Sera habitually stops at the same kiosk at the same time — a recognizable routine | `knows_of` | B |
| `behavioral.sera_knowledge_detail` | Sera's offhand comments reveal detailed knowledge of manifest routing she shouldn't have | `knows_of` | S |
| `behavioral.voss_awareness` | Voss appears to be tracking people — situational awareness beyond normal supervisor behavior | `suspects` | D |
### 4.4 Knowledge Facts
Operational knowledge — ring procedures, social dynamics, institutional mechanics.
| Fact ID | Plain Description | Typical Confidence | Chars |
|---------|------------------|-------------------|-------|
| `knowledge.ring_routing_knowledge` | Full knowledge of the ring's drop routes and timing protocols | `knows_details` | S (background) |
| `knowledge.ring_bar_operations` | The bar (The Last Shift) has a role in ring communications or social cover | `knows_of` → `knows_details` | B |
| `knowledge.bar_back_room_significance` | The bar's back room has significance — meeting space, handoff point, or storage | `suspects` → `knows_details` | D |
| `knowledge.bar_ring_awareness` | The bar's regulars have varying levels of ring awareness — it's an open secret at some level | `knows_of` | B |
| `knowledge.kael_exit_plan` | Kael has a specific plan for exiting the ring — timing, conditions, contact | `knows_details` | B |
### 4.5 Contraband Facts
Smuggling ring world facts — existence, composition, operations.
| Fact ID | Plain Description | Typical Confidence | Chars |
|---------|------------------|-------------------|-------|
| `contraband.ring_exists` | A smuggling operation is running through Sova Transit District | `suspects` (detective) / `knows_details` (smuggler, background) | B |
| `contraband.ring_lattice_components` | The ring moves unlicensed lattice components — aftermarket neural mods | `knows_of` → `knows_details` | B |
| `contraband.ring_medical_components` | The ring also diverts medical-grade lattice replacements from Syndic supply chains | `knows_details` | B |
| `contraband.supply_chain` | Understanding of the ring's supply chain — where components come from | `knows_details` | B |
| `contraband.severance_tech_presence` | Severance counter-surveillance technology is in play on the station | `suspects` | D |
| `contraband.drop_tonight` | A drop is scheduled for tonight specifically | `knows_details` | S |
### 4.6 Location Facts
Location-specific access, restrictions, and significance.
| Fact ID | Plain Description | Typical Confidence | Chars |
|---------|------------------|-------------------|-------|
| `location.corridor_b7_restricted` | Corridor B-7 is a restricted access zone — requires credentials | `knows_of` | B |
| `location.corridor_b7_drop_site` | B-7 is an active drop site for the ring | `knows_details` | B |
| `location.maintenance_corridors_access` | Character knows the maintenance corridor layout and can navigate it | `knows_of` (detective, investigation) / `knows_details` (smuggler, background) | B |
| `location.bay4_sealed` | Bay 4 is sealed — inspection or deliberate cover | `suspects` | B |
| `location.span_gate_schedule_gap` | The span gate schedule has a window that enables unseen drops | `knows_details` | S |
### 4.7 Relationship Facts
Third-party inter-NPC connections — what one character knows about relationships between others.
| Fact ID | Plain Description | Typical Confidence | Chars |
|---------|------------------|-------------------|-------|
| `relationship.kael_naia_connection` | Kael and Naia are romantically partnered — not just colleagues | `knows_of` → `knows_details` | B |
| `relationship.ring_membership` | Character has identified specific ring members | `knows_of` (list incomplete) → `knows_details` (full ring) | B |
| `relationship.trust_network` | Understanding of who trusts whom inside the ring | `knows_details` | S |
### 4.8 Social Facts
Social positioning in a specific context.
| Fact ID | Plain Description | Typical Confidence | Chars |
|---------|------------------|-------------------|-------|
| `social.bar_regular_status` | Character is established as a regular at The Last Shift — recognized, trusted in that context | `knows_of` | B |
---
## Part 5: Prerequisite Format Quick Reference
### Full YAML format (engine canonical)
```yaml
- id: transit_m_s_025
character: smuggler
text: "Kael keeps checking his lattice. Waiting for a message? Not like him to be jumpy."
trigger: observe_anomaly
prerequisites:
relationship: # Optional: entity relationship state check
target: npc:kael-davan
state: friendly
facts: # Optional: world fact checks — ALL must pass
- fact_id: investigation.kael_corridor_meeting
min_confidence: suspects
entity_attributes: # Optional: entity attribute value checks
- entity: npc:kael-davan
key: behavior_flags
value: lattice_checking
priority: 7
tags: [npc, kael, tell, friend-arc]
```
### Shorthand map (for #309 planning, not used directly in YAML)
| Shorthand | Full YAML | Notes |
|-----------|-----------|-------|
| `suspects: investigation.kael_corridor_meeting` | `facts: [{fact_id: investigation.kael_corridor_meeting, min_confidence: suspects}]` | |
| `knows: awareness.detective_presence` | `facts: [{fact_id: awareness.detective_presence, min_confidence: knows_of}]` | |
| `knows_details: contraband.ring_routing_known` | `facts: [{fact_id: contraband.ring_routing_known, min_confidence: knows_details}]` | |
| `met: npc:kael-davan` | entity in KnowledgeGraph at any confidence | |
| `has_seen: npc:kael-davan` | entity had Direct confidence at some point | |
| `friend: npc:kael-davan` | `relationship: {target: npc:kael-davan, state: friendly}` | |
| `poi: npc:kael-davan` | `relationship: {target: npc:kael-davan, state: person_of_interest}` | |
### Multi-condition logic
All conditions within a `prerequisites:` block are **AND** — all must pass for the line to be eligible.
To express **OR** logic: author multiple lines targeting the same trigger with different prerequisites. The engine selects the highest-priority eligible line.
---
## Part 6: Common Authoring Patterns
### Pattern 1: Progressive revelation — early
Line fires from the first suspicious observation. No prior facts required.
```yaml
trigger: observe_anomaly
# No prerequisites — fires on any anomaly observation
tags: [environmental, caution]
```
### Pattern 2: Progressive revelation — mid
Line fires after initial suspicion is established:
```yaml
prerequisites:
facts:
- fact_id: investigation.kael_corridor_meeting
min_confidence: suspects
```
### Pattern 3: Progressive revelation — late
Line fires with actionable evidence in hand:
```yaml
prerequisites:
facts:
- fact_id: investigation.kael_ring_membership
min_confidence: knows_details
```
### Pattern 4: THE FRIEND arc — contradiction trigger
Line fires when the contradiction is discovered (both relationship state and investigative knowledge required):
```yaml
prerequisites:
relationship:
target: npc:kael-davan
state: person_of_interest
facts:
- fact_id: investigation.kael_corridor_meeting
min_confidence: knows_of
tags: [npc, kael, contradiction, friend-arc]
```
### Pattern 5: D-075 trust tier — secret-tier dialogue gate
Secret-tier dialogue requires both `friendly` relationship AND `knows_details` on target (D-075):
```yaml
# This is handled by the dialogue engine — content authors do NOT need to
# add this as a prerequisite on dialogue lines. It applies automatically.
# For MONOLOGUE lines that mirror the emotional weight of secret disclosure:
prerequisites:
relationship:
target: npc:kael-davan
state: friendly
facts:
- fact_id: investigation.kael_exit_attempt
min_confidence: knows_details
```
### Pattern 6: Opening hook (for #299/#300)
Opening hook lines fire from character Background knowledge. The character arrives already knowing these things — do not gate them on investigation facts.
```yaml
# Smuggler — knows the ring, knows the route. No investigation prereqs needed.
# Gate on simple triggers (enter_location, time_idle) with no prerequisites.
trigger: enter_location
# No prerequisites — smuggler's operational awareness is Background knowledge
tags: [arrival, operational]
# Detective — knows Commission jurisdiction, has manifest anomaly suspicion.
prerequisites:
facts:
- fact_id: investigation.manifest_discrepancy
min_confidence: suspects
```
---
## Appendix A: Character Starting Knowledge
What each character knows at game start. Source: `Background` (set at initialization). These facts do NOT need to be discovered — they are in the knowledge graph from tick 0.
### Smuggler starting facts
| Fact ID | Starting Confidence | Notes |
|---------|--------------------:|-------|
| `contraband.ring_exists` | `knows_details` | Is an active member |
| `knowledge.ring_routing_knowledge` | `knows_details` | Knows the full routing protocol |
| `contraband.ring_lattice_components` | `knows_details` | Knows what they're moving |
| `location.corridor_b7_drop_site` | `knows_details` | Knows the drop sites |
| `location.maintenance_corridors_access` | `knows_details` | Knows the layout |
| `relationship.ring_membership` | `knows_of` | Knows some ring members; full membership is `knows_details` |
| `world.lattice_regulation_active` | `knows_of` | Knows why there's demand |
| `world.unlicensed_lattice_demand` | `knows_of` | Understands the moral context |
| `location.corridor_b7_restricted` | `knows_of` | Knows the official restriction |
### Detective starting facts
| Fact ID | Starting Confidence | Notes |
|---------|--------------------:|-------|
| `investigation.manifest_discrepancy` | `suspects` | Has flagged anomalies, no confirmation yet |
| `contraband.ring_exists` | `suspects` | Has a case, not yet confirmed |
| `world.lattice_regulation_active` | `knows_details` | Full institutional knowledge |
| `world.commission_sova_jurisdiction` | `knows_details` | Knows their authority |
| `location.corridor_b7_restricted` | `knows_of` | Knows the restricted zone map |
| `investigation.surveillance_gaps` | `suspects` | Has noticed something is off |
---
## Appendix B: Fact ID Index
Alphabetical index for quick lookup. Format: `category.fact_name` → section.
| Fact ID | Section |
|---------|---------|
| `awareness.commission_audit_scheduled` | 4.2 |
| `awareness.detective_investigating_ring` | 4.2 |
| `awareness.detective_presence` | 4.2 |
| `awareness.inspection_sweep_active` | 4.2 |
| `awareness.ring_route_compromise` | 4.2 |
| `awareness.ring_tension_escalation` | 4.2 |
| `awareness.surveillance_change` | 4.2 |
| `behavioral.kael_behavioral_change` | 4.3 |
| `behavioral.kael_evasion` | 4.3 |
| `behavioral.sera_avoidance_pattern` | 4.3 |
| `behavioral.sera_knowledge_detail` | 4.3 |
| `behavioral.sera_kiosk_pattern` | 4.3 |
| `behavioral.sera_topic_deflection` | 4.3 |
| `behavioral.voss_awareness` | 4.3 |
| `contraband.drop_tonight` | 4.5 |
| `contraband.ring_exists` | 4.5 |
| `contraband.ring_lattice_components` | 4.5 |
| `contraband.ring_medical_components` | 4.5 |
| `contraband.severance_tech_presence` | 4.5 |
| `contraband.supply_chain` | 4.5 |
| `investigation.cargo_anomaly` | 4.1 |
| `investigation.container_delay` | 4.1 |
| `investigation.corridor_regular_use` | 4.1 |
| `investigation.drin_gambling_debt` | 4.1 |
| `investigation.drin_inspection_pattern` | 4.1 |
| `investigation.kael_corridor_meeting` | 4.1 |
| `investigation.kael_corridor_sighting` | 4.1 |
| `investigation.kael_exit_attempt` | 4.1 |
| `investigation.kael_ring_membership` | 4.1 |
| `investigation.kael_unknown_contact` | 4.1 |
| `investigation.manifest_discrepancy` | 4.1 |
| `investigation.naia_lattice_condition` | 4.1 |
| `investigation.oversight_gap_pattern` | 4.1 |
| `investigation.ring_existence` | 4.1 |
| `investigation.renn_courier_role` | 4.1 |
| `investigation.ring_leadership` | 4.1 |
| `investigation.sera_evidence_held` | 4.1 |
| `investigation.shift_mismatch` | 4.1 |
| `investigation.smuggling_route` | 4.1 |
| `investigation.surveillance_gaps` | 4.1 |
| `investigation.torek_spending_pattern` | 4.1 |
| `investigation.voss_ring_involvement` | 4.1 |
| `knowledge.bar_back_room_significance` | 4.4 |
| `knowledge.bar_ring_awareness` | 4.4 |
| `knowledge.kael_exit_plan` | 4.4 |
| `knowledge.ring_bar_operations` | 4.4 |
| `knowledge.ring_routing_knowledge` | 4.4 |
| `location.bay4_sealed` | 4.6 |
| `location.corridor_b7_drop_site` | 4.6 |
| `location.corridor_b7_restricted` | 4.6 |
| `location.maintenance_corridors_access` | 4.6 |
| `location.span_gate_schedule_gap` | 4.6 |
| `relationship.kael_naia_connection` | 4.7 |
| `relationship.ring_membership` | 4.7 |
| `relationship.trust_network` | 4.7 |
| `social.bar_regular_status` | 4.8 |
---
*Fact catalog current as of 2026-02-19. All fact IDs in existing content are documented here. New IDs added during Sprint 12 content authoring should be added to the relevant section and Appendix B.*
docs/design/mirror-moment-design.md
+273
View File
@@ -0,0 +1,273 @@
# Mirror Moment Design Document
**Ticket:** #329
**Owners:** Gestalt (framework + specs), Paula + Mellanie (line authoring)
**Source:** D-032 (separate monologue pools), D-034 (FRIEND pattern), D-039 (wow moments)
**Date:** 2026-02-19
---
## What Is a Mirror Moment
A mirror moment is a shared trigger that fires different monologue for each playable character.
Same event. Same tile position. Different observation. The smuggler and the detective see the same thing and think completely different thoughts. Neither perspective is wrong. Neither is complete.
**The dramatic irony is the point.** On first playthrough, you get one lens. On replay as the other character, you revisit the same moment and understand what the other character was thinking. The world you thought you understood had another interpretation the whole time.
---
## Mechanics
### How mirrors work (D-032)
Monologue pools are hard-partitioned by `character` tag. Same trigger fires two different pools — one for the smuggler, one for the detective. The engine selects from the appropriate pool based on which character is playing.
```yaml
# Same trigger, two pools — the mirror
- id: example_mirror_s_001
character: smuggler
trigger: observe_npc # Trigger condition
text: "Smuggler's interpretation of the event"
tags: [mirror, the-friends-routine]
- id: example_mirror_d_001
character: detective
trigger: observe_npc # Same trigger condition
text: "Detective's interpretation of the same event"
tags: [mirror, the-friends-routine]
```
### Mirror vs. standard monologue
Standard monologue: fires for any character, addresses the environment from their general perspective.
Mirror: intentionally paired — the contrast between the two lines IS the content.
**Not every environmental line needs a mirror.** Most monologue is character-specific without being a deliberate paired contrast. Mirrors are designed — each one has a specific dramatic irony that pays off on replay.
### Prerequisite considerations
Mirror moments can have prerequisites that differ by character. The smuggler sees Kael's routine as familiar. The detective sees the same routine as data. But both must be able to encounter the trigger — prerequisite design should not lock one character out of a mirror unless that's intentional.
---
## The Seven Core Mirrors
### Mirror 1: The Friend's Routine
**Trigger:** `observe_npc` — observe Kael Davan at the beginning of his shift (dock floor, Phase 1 timing)
**Dramatic irony:** The smuggler sees their most trusted colleague. The detective sees a dock worker with flagged manifests.
| Character | Monologue Register | Key Emotional Note |
|-----------|-------------------|-------------------|
| Smuggler | Warm recognition, ease, competence acknowledged | "The day's better when Kael's on shift" |
| Detective | Clinical observation, professional assessment | "Davan. He's the one on three of the flagged manifests" |
**Prereqs:**
- Smuggler: none — fires on game start
- Detective: `suspects: investigation.manifest_discrepancy` (has flagged the anomaly)
**Payload on replay:** The detective's cool assessment of "the one on three flagged manifests" lands differently when you've played the smuggler and know Kael is your most trusted friend.
---
### Mirror 2: The Empty Corridor
**Trigger:** `enter_location` — enter Corridor B-7 (maintenance corridor, restricted zone)
**Dramatic irony:** The smuggler knows this place. The detective is piecing it together.
| Character | Monologue Register | Key Emotional Note |
|-----------|-------------------|-------------------|
| Smuggler | Operational familiarity — this is a work space | "Quiet tonight. Route's clear. Move." |
| Detective | Investigative alertness — spatial reasoning about why this corridor | "This shouldn't connect to the main dock flow. Someone redesigned the access." |
**Prereqs:**
- Smuggler: `knows_details: knowledge.ring_routing_knowledge` (always true — background knowledge)
- Detective: none — first-time observation lines for arrival; `suspects: investigation.manifest_discrepancy` for more specific reads
**Payload on replay:** The detective's spatial analysis ("someone redesigned the access") is exactly what the smuggler takes for granted — someone DID redesign it, to create the drop route.
---
### Mirror 3: The Worried Partner
**Trigger:** `observe_npc` — observe Naia Tamm at The Last Shift (bar, first encounter)
**Dramatic irony:** The smuggler knows exactly why Naia looks worried — she's worried about Kael, and the smuggler knows why Kael is distracted. The detective sees a civilian who might be a useful connection.
| Character | Monologue Register | Key Emotional Note |
|-----------|-------------------|-------------------|
| Smuggler | Guilt-adjacent recognition — knows more than Naia does | "Naia. She's got that look — the one she gets when Kael's not telling her something." |
| Detective | Analytical warmth — potential social anchor, reads the worry | "Someone waiting for someone who's late. Or someone carrying something they can't put down." |
**Prereqs:**
- Smuggler: `knows: relationship.kael_naia_connection` (learns through background or Kael references)
- Detective: none — fires on first observation of Naia
**Payload on replay:** The detective's "someone carrying something they can't put down" is unknowingly accurate — Naia is carrying worry about Kael that she can't voice. The smuggler knew the source.
---
### Mirror 4: The Spending
**Trigger:** `observe_npc` — observe Torek Lintar at The Last Shift during a spending moment (rounds for the bar, visible display)
**Dramatic irony:** The smuggler sees an operational risk — someone advertising that they have more money than they should. The detective sees the investigation materializing.
| Character | Monologue Register | Key Emotional Note |
|-----------|-------------------|-------------------|
| Smuggler | Operational caution — this is how you get caught | "Torek's buying rounds again. Someone needs to say something. This is how you draw attention." |
| Detective | Investigative recognition — the pattern confirms | "There it is. Dock inspector, mid-pay-grade, buying rounds at a freight bar. Where does that come from?" |
**Prereqs:**
- Smuggler: none — fires on observation (smuggler intuits operational risk)
- Detective: `suspects: investigation.torek_spending_pattern` (has noticed the pattern beginning)
**Payload on replay:** The smuggler's exasperation ("this is how you get caught") is exactly what eventually happens — Torek's spending is how the detective builds the case.
---
### Mirror 5: Sera Leaving
**Trigger:** `witness_interaction` — observe Sera Venn abruptly leave the bar when Torek Lintar arrives (The Last Shift)
**Dramatic irony:** This is the core Sera contradiction trigger for the detective. For the smuggler, it's just a Commission woman who doesn't like Torek — plausible, not significant.
| Character | Monologue Register | Key Emotional Note |
|-----------|-------------------|-------------------|
| Smuggler | Mild observation, dismissive — not their circle | "Commission woman doesn't like Torek. Smart. He's loud." |
| Detective | Pattern recognition accumulating — third observation fires the arc | "Three times. Same exit, three different reasons. That's not personality — that's data." |
**Prereqs:**
- Smuggler: none — fires on any observation of the departure
- Detective (Phase 3): fires specifically on third observed departure — the contradiction completes
**Notes:** This mirror has asymmetric emotional weight by design. For the smuggler it's noise; for the detective it's the arc-completion moment. The contrast is the dramatic irony — on replay as the detective, you understand why the same moment that was nothing to the smuggler was everything to the detective.
---
### Mirror 6: The Hum
**Trigger:** `hear_sound` — hear the span gate harmonics (ambient sound in the Transit District, audible near the gate)
**Dramatic irony:** The smuggler hears the operational heartbeat — the gate timing is part of their work. The detective hears institutional infrastructure that someone is exploiting.
| Character | Monologue Register | Key Emotional Note |
|-----------|-------------------|-------------------|
| Smuggler | Operational familiarity — rhythmic, known, workable | "Gate cycle. Twenty-two minutes before the next transit window. Plenty of time." |
| Detective | Analytical listening — patterns reveal structure | "The gate schedule has a window. Someone's using it. You don't exploit something this consistent by accident." |
**Prereqs:**
- Smuggler: none — fires on any span gate sound observation
- Detective: `suspects: investigation.manifest_discrepancy` (has the anomaly, is building the picture)
**Payload on replay:** The detective's "you don't exploit something this consistent by accident" is confirmed by the smuggler's casual knowledge of the transit window timing.
---
### Mirror 7: The Commission Kiosk
**Trigger:** `observe_npc` — observe Sera Venn at the Commission calibration kiosk (Level 3, morning diagnostics routine)
**Dramatic irony:** The smuggler sees Commission presence and reads it as operational risk. The detective sees their closest ally doing their job — and then maybe something else.
| Character | Monologue Register | Key Emotional Note |
|-----------|-------------------|-------------------|
| Smuggler | Caution, professional distance — Commission means danger | "Commission tech running diagnostics. Stay normal. She's doing her job. Let her do it." |
| Detective | Fond recognition shifting to observation | "Sera, running morning rounds. Same time, same kiosk. She always is. ...Why does she stay so long?" |
**Prereqs:**
- Smuggler: none — fires on any Sera observation (context-adjusted by Phase)
- Detective: `knows: behavioral.sera_kiosk_pattern` fires the extended-time observation variant
**Payload on replay:** The smuggler's "let her do her job" — not knowing that Sera ISN'T just doing her job, she's compulsively rechecking compliance data to make sure she hasn't been caught — reframes the detective's late-game worry ("why does she stay so long?").
---
## Authoring Guidelines
### What makes a mirror effective
**1. Asymmetric depth.** One character has more context than the other. The better-informed read is more specific; the less-informed read is still true — just incomplete. Neither is wrong.
**2. The replay payoff is the point.** Write both lines imagining the player who knows both perspectives. The goal is the recognition moment: "Oh — that's what they were thinking."
**3. Same emotional register is wrong.** If both characters sound the same, it's not a mirror — it's two generic observations. The characters must feel differently about the same trigger.
**4. Don't editorialize.** Neither character says "little did I know..." or provides retrospective framing. They speak in the moment, from their knowledge state. The irony emerges from context, not from the line itself.
### Trigger selection
Mirror moments work best on triggers that are:
- **Routine** — something that recurs throughout the session, so both characters naturally encounter it
- **Spatially available to both** — the smuggler and detective both operate in the three social sites
- **Emotionally loaded differently** — the same object/person/sound has different resonance depending on your knowledge
Triggers to avoid for mirrors:
- One-time scripted events (both characters might not see them)
- Confrontation triggers (those are character-specific by design)
- Lines gated so heavily by prerequisites that one character rarely sees them
### Line count per mirror
Each core mirror: **2-4 lines per character** — variations on the same observation for different confidence states or visit counts (e.g., first visit, return visit).
Total for 7 core mirrors: approximately **28-56 lines** (14-28 per character), spread across trigger types.
### Paired notation for authors
When authoring mirror lines, use `dual_lens` authoring note to document the contrast:
```yaml
- id: mirror_7_s_001
character: smuggler
trigger: observe_npc
text: "Commission tech running diagnostics. Stay normal. She's doing her job. Let her do it."
tags: [mirror, the-commission-kiosk]
dual_lens:
smuggler: "Defensive distance — Commission means risk, avoid attention"
detective: "Same NPC as the detective's FRIEND — the contrast is that the smuggler dismisses exactly what the detective is learning to doubt"
notes: "Paired with mirror_7_d_001"
```
---
## Organic Mirrors (3-5 to discover during content review)
During Mellanie's content pack authoring (#190, #191, #192), additional mirror moments will emerge organically when the same environmental element naturally reads differently for each character. Authors should flag these with `[MIRROR CANDIDATE]` in comments.
**Likely candidates:**
- Voss giving shift assignments (the smuggler reads operational signaling; the detective reads management as cover)
- Kael at lunch (the smuggler reads normalcy; the detective reads behavioral data)
- Lera serving a regular order (the smuggler reads social comfort; the detective reads access patterns)
- The empty bay at shift transition (the smuggler reads operational window; the detective reads anomalous access pattern)
These become confirmed mirrors after both character packs are written — identify paired lines that emerged independently, then strengthen the contrast deliberately.
---
## Integration with Content Authoring
### For Mellanie (#190, #191, #192 content packs)
When authoring NPC-observation and environmental lines, flag any line that:
- Involves a character or location that is significant to both the smuggler and detective
- Would read differently depending on what the observing character knows
- Contains a detail that is loaded for one character but neutral for another
Flag format: add `[MIRROR CANDIDATE: {brief description of the contrast}]` as an authoring note.
### For Paula (#299, #300 opening hooks)
Opening hook content should include at least 2-3 mirror moments from the Core 7 above. The smuggler's arrival at the Terminal should establish The Friend's Routine (Mirror 1) and may include The Hum (Mirror 6). The detective's arrival should include Mirror 1 (from their clinical perspective) and Mirror 5 setup (Sera present in bar).
### Prerequisite cross-reference
All mirror moment prerequisite fact IDs are defined in: `docs/design/knowledge-flags-v01.md`
---
*Design document. Core 7 mirrors are confirmed and spec'd. Organic mirrors (3-5) to be identified during content authoring.*
*Line authoring: Mellanie + Paula. Framework: Gestalt.*
docs/design/sova-station-profile.md
+186
View File
@@ -0,0 +1,186 @@
# Sova Station Profile — Station Beyond Transit District
**Ticket:** #320
**Author:** Miri
**Status:** canonical
**Last updated:** 2026-02-19
Reference: D-036 (Sova setting), D-050 (Velen/Krenn system)
Blocks: #335 (Meridian Coverage Map for Sova Transit)
---
## Purpose
Sova Transit District is not all of Station Sova. NPCs reference the wider station constantly — medical services are "at the main station," a certain district has a better bar, administrative offices are "upstation," off-ring contacts live in other sectors. Dialogue needs to know what's there without the game needing to implement any of it in v0.1.
This document defines the parts of Station Sova that exist beyond the playable Transit District. It is a reference document for content authors, not a design specification for future development.
---
## Overview
**Station name:** Station Sova
**System:** Krenn System
**Orbit:** Station Sova is a permanent orbital facility around Velen, the Krenn System's primary habitable world
**Population:** ~12,000 permanent residents; fluctuating transient population of 1,000-3,000 (freight workers, visitors, crew)
**Primary function:** Logistics hub for Krenn System freight operations — the transit point between Velen's planetary freight depot and outgoing freight routes
**Governance:** Station Administrator (appointed by Krenn System Concord Compact, confirmed by regional Concord Assembly representation)
**Construction:** Original core built during early Krenn settlement (~150 years ago). Significant expansion ~80 years ago. Current configuration largely stable for ~40 years.
**Architectural character:** Classic mid-Reach logistics station — functional, layered, mixed-era. Not elegant. Not derelict. The kind of structure that works because it's been maintained, not because it was designed to last.
---
## Station Districts
Station Sova is divided into six administrative districts. Only the Transit District is playable in v0.1; the others exist as references in dialogue and establishing context.
### 1. Transit District (Playable — v0.1)
The freight logistics hub. Span gate terminal, cargo handling, customs processing, and the service economy that serves freight workers. Full documentation in D-036 and `docs/design/sova-texture-appendix.md`.
**Population:** ~800 (workers and service economy residents)
**Character:** Working-class freight district. "Quotidian-with-undertow."
**Key locations:** The Terminal (logistics hub), The Last Shift (bar), maintenance corridors
**Meridian coverage:** Strong in institutional spaces, degraded in older sections, minimal in maintenance corridors
---
### 2. Residential Core
The largest district by physical space. Station Sova's main housing blocks, organized by construction era and (informally) by occupational affiliation.
**Population:** ~6,000
**Character:** Unremarkable mid-Reach residential. Standard housing modules, shared communal spaces, a mix of long-term residents and contract workers. Not comfortable enough to be pleasant, not uncomfortable enough to drive people away. Home.
**Relevant to v0.1 content:**
- Most Transit District workers live here, not in the Transit District itself. They commute (a short internal transit ride).
- NPCs who've left the bar for the evening have gone here, not immediately to bed — there's a residential stop in between.
- When NPCs say "I'm heading home," this is where they're going.
- Station housing is assigned through the Administration; moving districts requires paperwork. Workers who've been here for years have established housing they don't want to lose — another reason not to attract institutional attention.
**Off-limit in v0.1 content:** Don't invent specific addresses or named locations in the Residential Core. Reference it generically.
---
### 3. Administrative Hub (Upstation)
Station Administration offices, Commission regional office, Concord Assembly liaison office, main station security, and the formal infrastructure of governance.
**Population:** ~1,000 (administrative staff, Commission personnel, security, liaisons)
**Character:** Institutional. Cleaner than the rest of the station. Better maintained. The kind of spaces where people wear official-issue everything and speak more carefully.
**Relevant to v0.1 content:**
- When the detective needs to file reports, pull Commission records, or deal with institutional bureaucracy, it happens here (or via Meridian queries routed to here).
- The detective's direct superior has an office here. Their interactions with the chain of command mostly happen via Meridian, but physical visits are possible.
- The ring's greatest institutional threat: if the Commission regional office takes interest in Transit District operations, the scale of scrutiny increases dramatically. The district's current intermittent Commission presence is favorable; Commission attention from Upstation is not.
- Workers from the Transit District rarely go to the Administrative Hub voluntarily. Going there attracts attention. Being seen going there — if you're ring-adjacent — is a tell.
**Shorthand in NPC dialogue:** "Upstation" — any NPC in the Transit District uses this term to mean the Administrative Hub and surrounding institutional spaces. "They went upstation about it" means they escalated to official channels.
---
### 4. Medical Center
The station's primary healthcare facility, including re-embodiment services.
**Population:** ~500 (medical staff, patients, support)
**Character:** Functional medical institutional. Better equipment than the Transit District's small clinic. More staff. Commission-accredited re-embodiment facility.
**Relevant to v0.1 content:**
- Serious medical issues that the district clinic can't handle are referred here: "They sent him to the main medical center."
- Re-embodiment services: the full facility is here. The Transit District clinic can stabilize, not restore. People who die in the Transit District are recovered and restored at the main medical center, assuming they've maintained backup status.
- Medical-grade lattice replacement: legitimate lattice component replacement (as opposed to the ring's aftermarket version) is performed here under Commission oversight. The wait list is long. The price is high. The ring's medical-grade diverted components exist in part because this facility's legitimate access is priced beyond working-class reach.
- One detail for Naia's situation (if referenced in content): Naia was quoted a legitimate replacement timeline and price at the main medical center. The timeline was 8-12 months waiting list. The price was prohibitive. Kael's ring activity began shortly after.
---
### 5. Commercial Quarter
Retail, food service, entertainment, and light commercial activity. The station's "main street."
**Population:** ~1,500 (residents, visitors, commercial staff)
**Character:** Mid-range commercial. Better quality than the Transit District's bar and food vendors. More expensive. For Transit District workers, a visit to the Commercial Quarter is a mild treat — it costs more, but the food is better and the drinks have more options.
**Relevant to v0.1 content:**
- Workers occasionally reference going to the Commercial Quarter for something specific ("better than that place in the Quarter"). The Transit District workers have mild pride about their district's bar vs. what they perceive as the more pretentious options in the Commercial Quarter.
- The ring does not operate in the Commercial Quarter. Too much Meridian coverage. Too many eyes. Their business stays in the Transit District.
- A few NPCs (Maret Korr, for instance) might occasionally reference shopping in the Commercial Quarter for specific items. It's a small social marker: people who go to the Quarter regularly have slightly more disposable income.
---
### 6. Industrial Sector
Manufacturing and processing facilities: station power generation, environmental systems, primary maintenance, water recycling, atmospheric management.
**Population:** ~700 (industrial and maintenance staff)
**Character:** Heavy industrial. Workers here are different from freight workers — more technical, more specialized, more solitary. They service the systems that keep everyone alive.
**Relevant to v0.1 content:**
- Station maintenance workers (like Drin) work in the Transit District but have a professional connection to the Industrial Sector. Their guild structure, if any, is organized across both.
- The ventilation issue in Transit District Sector 3 is technically under the Industrial Sector's maintenance jurisdiction. The reason repairs are delayed is a combination of Industrial Sector queue management and Transit District Administration's low priority in maintenance allocation. Neither district's administration has the authority to force the other to act. This is the bureaucratic reality behind the local complaint.
- If a significant system failure affects the station, it originates here. The span gate terminal's power supply, for instance, runs through Industrial Sector infrastructure.
---
## Governance Structure
**Station Administrator:** Appointed position. Currently Administrator Hassel (known by name in institutional circles, by title to most residents, not known at all to many workers in the Transit District). Oversees all district administration.
**District Administrators:** Each district has a sub-administrator who reports to the Station Administrator. The Transit District's sub-administrator is rarely physically present in the district — they manage via Meridian reports and quarterly visits.
**Commission Regional Office (Upstation):** The station's Commission presence reports to the regional Commission office (off-station). The regional office sets investigative priorities. The station office executes them. The investigative mandate that brought the detective to Sova Transit was issued by the regional Commission office, routed through the station Commission office, executed as a "logistics compliance review." The chain is: Regional Commission → Station Commission → Station Administrator → Transit District Administration.
**Security:** Station security is organized through the Administrative Hub. The Transit District has a minimal security presence (one officer on shift, available by Meridian call). Major security responses come from the Administrative Hub. The ring knows this response time and plans around it.
---
## What's Off-Station (References Only)
NPCs may reference locations and entities beyond Sova Station. These are real but out-of-scope for v0.1 playable content.
**Velen:** The Krenn System's primary habitable world. Temperate-maritime climate. The span gate connects Sova Station to a planetary freight depot on Velen's surface. Most cargo that flows through Sova Transit either originates or terminates on Velen. The planet is visible through the station's viewports — a blue-green sphere with frequent cloud cover. Residents call it simply "the surface" or "downwell." Most station workers have been to Velen; some lived there before moving to the station for work.
**Velen Freight Depot:** The planet-side destination of the Sova span gate. A functional logistics hub that mirrors the Transit District's function. The ring's product goes through here on its way to planet-side distribution. The ring has contacts in the Velen depot — logistics workers in an identical job to the ring's members, running the same kind of operation.
**Other Krenn System stations:** The Krenn System has two other smaller orbital facilities (mining support station and an administrative relay). They're referenced occasionally in news tickers and operational scheduling. Not relevant to v0.1.
**The horizon gate:** Sova Station has a connection to the Reach's horizon gate network — the interstellar transport infrastructure. The horizon gate terminal is in the Administrative Hub district, not the Transit District. Characters with legitimate need can book transit to other systems. This connection is what makes Sova relevant to a larger smuggling network; contraband doesn't originate in-system, it comes from elsewhere via horizon gate and moves through Sova's span gate to Velen.
---
## Meridian Coverage Notes
(Relevant for Ticket #335 — Meridian Coverage Map for Sova Transit, which this document unblocks)
**Station-wide coverage status:**
| District | Coverage | Notes |
|---|---|---|
| Administrative Hub | Comprehensive | Commission-grade infrastructure. Full monitoring in all public spaces. |
| Commercial Quarter | Comprehensive | Commercial monitoring standards. Dense coverage for transaction tracking. |
| Medical Center | Comprehensive | Patient record and equipment monitoring. Full coverage. |
| Residential Core | Standard | Full coverage in common areas, standard-grade residential coverage in units. |
| Industrial Sector | Standard with gaps | Monitoring in operational areas; some older infrastructure zones with reduced coverage. |
| **Transit District** | **Degraded (see detail)** | **See `docs/design/sova-texture-appendix.md` Section 5 and Ticket #335** |
The Transit District's degraded coverage is partly structural (older sections, mixed infrastructure) and partly the result of the ring's ongoing Severance tech deployment in specific dead spots. The ring did not create the dead spots — they identified and exploited existing coverage gaps, then maintained and selectively deepened them using Severance equipment.
---
## Content Authoring Notes
**When referencing off-Transit-District locations:**
- Keep references vague and experiential: "the main medical center," "upstation," "the Quarter," "the industrial section" — never specific room numbers or facility names for out-of-scope locations
- NPCs should reference these places as workers refer to any adjacent district: familiarly but not in detail
- The detective may pull Commission records that reference other districts — these can include district names (Administrative Hub, Medical Center) but should not include fabricated detail about their internal layout
**What NPCs know:**
- Transit District workers know the station layout in the way workers know where they work: they know their commute route, the medical center, the Commercial Quarter, and have vague awareness of everything else
- NPCs who've lived here longer know more (Lera would know who works at specific Commercial Quarter establishments; Drin would know the Industrial Sector workers by name)
- The detective's insert can provide district maps at a general level — they know Sova Station's layout from Commission briefing files, but not at the ground-level social detail that residents carry
---
*This document establishes the off-district context that NPC dialogue requires. The playable Transit District is embedded in a larger station that has its own rhythms, hierarchies, and institutions. That context should be ambient in content — felt as background, not foregrounded.*
*Miri — Sprint 12*
docs/design/sova-texture-appendix.md
+253
View File
@@ -0,0 +1,253 @@
# Sova Texture Appendix
**Ticket:** #302
**Author:** Miri
**Status:** canonical
**Last updated:** 2026-02-19
Companion to: `docs/design/cultural-generation-guide.md`
Reference: D-036 (setting), D-037 (contraband)
---
## Purpose
This appendix provides the sensory, linguistic, and social texture of Sova Transit District. It is the reference Mellanie uses for environmental text, NPC dialogue, and monologue authoring. It is also the reference Araminta uses for signage content and decorative detail.
Everything here is canonical for v0.1. Any divergence from this appendix in authored content should be flagged and resolved.
---
## Section 1: Slang Glossary — 20 Terms
Sova Transit District has developed its own working vocabulary over 40 years. This is not exotic alien slang — it is the language of people who do physical work in the same building every day, who have developed shortcuts for things they say constantly, and who occasionally use vocabulary to mark in-group membership.
### Work and Schedule
| Term | Meaning | Usage | Notes |
|---|---|---|---|
| **marks** | Credits (the standard currency unit) | "That run paid out four hundred marks." | Krenn System local usage. Not reach-wide. "Credits" is the formal/institutional term. |
| **shift** | Work period (typically 8 hours) | "I've got another four hours on shift." | Never say "rotation" or "tour" — those are military register, wrong for a freight district. |
| **the after** | Off-shift social time | "See you in the after." / "Heading to Lera's in the after." | Specific to Sova Transit — the period after the main shift wave when people decompress at the bar. |
| **the gate** | Span gate terminal (informally) | "Two more transits through the gate this evening." | "The span gate terminal" is institutional. "The gate" is how everyone actually refers to it. |
| **a push** | A particularly heavy cargo day (high transit volume) | "It's a push today, we're running behind." | Derives from the physical feeling of high-volume freight work. |
| **running light** | Low-cargo day, easy shift | "Gate traffic's down — running light this afternoon." | Opposite of "a push." |
| **the floor** | The main logistics hub workspace | "Meet me on the floor at 0900." | Distinguishes the active workspace from offices/break room. |
| **sign-off** | End-of-shift handover | "Waiting on sign-off from Voss before I can leave." | The formal process of handing off responsibility. Used literally but also as general end-of-process term. |
### People and Social
| Term | Meaning | Usage | Notes |
|---|---|---|---|
| **on-book** | Within official channels, traceable | "Keep this on-book — I don't want complications." | Implies its opposite (off-book) exists and is known. |
| **off-book** | Outside official channels, not traceable | "That container moved off-book last night." | Ring usage primarily, but anyone in the district understands the term. Using it casually signals in-group awareness. |
| **a regular** | A bar regular, someone who's been coming to The Last Shift for years | "Ask Drin — he's a regular, he'd know." | Social status marker. Regulars are trusted community members. |
| **Commission eyes** | Commission presence (investigative or surveillance) | "There were Commission eyes on the floor yesterday." | Not hostile exactly — just careful. The phrase itself is a warning. |
| **tight mouth** | Someone who doesn't talk about things they shouldn't | "Sess is a tight mouth — you can say what you need." | Compliment in Sova. Being a tight mouth is trustworthy. |
| **loose** | Someone whose reliability or discretion is questionable | "Torek's been loose lately. Something's wrong with him." | Can mean careless, nervous, unreliable, or compromised. Context-dependent. |
### District and Infrastructure
| Term | Meaning | Usage | Notes |
|---|---|---|---|
| **Sector 3** | Older section of the district with chronic ventilation issues | "It's Sector 3 in here today." (meaning: unpleasantly warm and stale) | Local complaint made cultural shorthand. Used for any space with poor air quality. |
| **the gap** | The unofficial maintenance corridors between old and new construction | "Meet me in the gap at 2300." | Ring terminology primarily, but maintenance workers also use it. |
| **the feed** | The Meridian news ticker in the bar and hub lobby | "You see what was on the feed this morning?" | The communal information source. Not watched actively but referenced constantly. |
| **dead air** | A Meridian dead spot (poor or absent coverage) | "Careful pinging from the break room — the far corner is dead air." | Important to know for the detective (coverage gaps limit investigation capability) and the ring (dead air zones are safe communication spaces). |
| **the clinic** | Small medical facility in the district | "Took him to the clinic, they sent him to the main station for anything serious." | Establishing that serious medical needs require leaving the Transit District. |
| **a re-em** | Re-embodiment (colloquial) | "He almost didn't come back from that one — had to do a re-em." | Casual reference to the setting's death/resurrection technology. The matter-of-fact tone reflects how normalized this is in the Reach. |
---
## Section 2: Informal Decoration — The Human Mark on Institutional Space
The Transit District is 40 years old. In that time, workers have personalized the spaces they inhabit daily. This personalization is the human layer over institutional structure — and it's readable.
### Locker Areas (Hub Break Room)
- **Personal items on display:** Workers with long tenure often leave small decorative items on top of their lockers — a small potted plant (maintenance workers are proud of anything growing), a printed family image in a cheap clip frame, a figurine. These are subtle status markers: the longer your items have survived, the more established you are.
- **Stickers on lockers:** Union notices, small humorous prints, Meridian feed screenshots of something funny, a schedule drawn by hand in someone's own ink because the Meridian calendar didn't show what they needed to see. Not excessive. A few per locker, if any.
- **Hand-lettered notices:** Shift swap requests. Lost item reports ("Missing: insulated mug, blue, my name on the bottom. Please return."). Notices for informal events. These are pinned near the locker room entrance on a community board that is technically for official notices and has been completely colonized by informal ones.
### The Last Shift (Bar Interior)
- **The back bar shelf:** Lera keeps a curated collection of objects on the shelf behind the bar. Some are gifts from regulars. A small figure. A transit token from a gate that doesn't exist anymore (it closed; the token is a reminder). An industrial ceramic mug that's been there since before Lera owned the place. These are not decoration — they are the bar's memory.
- **The corner booth:** Someone carved initials into the underside of the table years ago. It's become a tradition. The underside of the corner booth table is covered in initials and short phrases, none of which are visible unless you deliberately look.
- **Graffiti (external only):** The district's external corridor walls, especially near maintenance access points, have accumulated graffiti over the years. It ranges from tagging (names in stylized Krenn script) to short phrases and symbols associated with the Guardians of Severance (counter-surveillance imagery — not political slogans, just visual signals that someone was here who didn't want to be found).
- **Meridian displays:** The bar's Meridian screen — the one that runs the news feed — has been locally configured with a custom background that no one knows the origin of. It shows a slightly washed-out image of a star seen from orbit, probably from an old transit recording. It cycles in the background behind the feed text. Nobody has changed it in years.
### Hub Workspace (The Floor)
- **Workstation personalization:** Minimal (supervisors don't officially allow it but don't enforce the rule). A sticker on a scanner terminal. A hand-drawn reminder taped to a container staging area ("THIS BAY — PRIORITY FREIGHT ONLY — NO EXCEPTIONS"). The reminder has been there for so long it's yellowed.
- **Informal signage:** Near the break room entrance, someone has written "0600 - 0800 MORNING RUSH — BE PATIENT WITH EACH OTHER" in block letters on a whiteboard that has been there long enough the letters are permanent. Nobody removes it. Nobody discusses it. It's just true.
- **Scanner bay markings:** Workers have developed an unofficial color-coding system for scanner bay status that supplements (and sometimes contradicts) the official Meridian-logged system. A piece of yellow material tied to a handle means "bay running but slow today." A red piece means "don't use this bay — something's off." The ring uses a version of this system for operational purposes.
---
## Section 3: Sensory Details — Smell, Sound, Light, Temperature
### Smells
| Location | Primary | Secondary | Notes |
|---|---|---|---|
| **Logistics hub (the floor)** | Industrial lubricant, faintly metallic | Container seal compound (sharp, chemical), recycled air with a cargo edge | The smell of work. Familiar, ignorable, fundamentally unglamorous. |
| **Break room / lockers** | Recycled air, mild human presence | Someone's lunch, coffee-equivalent from the dispenser, old coat in a locker | Warmer than the floor. Less industrial. The air is breathed-in. |
| **Maintenance corridors** | Dust, metal, old sealant | Ventilation system exhaust (musty in the older sections) | Sector 3's ventilation smell is noticeably worse — stale air with a faint biological undertone. Not dangerous. Just unpleasant. |
| **The Last Shift (bar)** | Cooked food, drink, human warmth | Cleaning compound underneath, Meridian music electronics if you're near the speakers | Comfortable. The smell of a place that's used. |
| **Near span gate terminal** | Ozone, electrical, slight metallic ionization | The "Interstitium trace" — a distinctive scent that clings to everything that passes through the gate. Not quite describable. Metallic? Cold? | Distinctive enough that people who've traveled through gates recognize it. Those who grew up near the terminal have stopped noticing it entirely. |
**Monologue note:** The Interstitium trace is monologue-useful. A character who grew up without gate access would notice it. A character who's worked the terminal for years wouldn't. It's one of the details that differentiates characters who are from Sova versus those who've just arrived.
### Sound
| Sound | Source | Rhythm | Character Notes |
|---|---|---|---|
| **The span gate hum** | Gate terminal, deep subsonic vibration | Constant, with variations: rises before transit, peaks during transit, settles after | This is the district's heartbeat. Everyone has tuned it out. When it stops for maintenance, the silence is unsettling in a way most people can't immediately identify. |
| **Grav-lift motors** | Container handling equipment on the floor | Intermittent, in waves matching freight cycles | Brief, purposeful. Not loud. A background to conversation on the floor. |
| **Scanner pings** | Freight scanners during container checks | Rhythmic during active scanning, sporadic otherwise | Individual pings are short, clean tones. A scanner in full operation sounds like irregular dripping. |
| **Ventilation system** | Throughout the district | Constant | Sector 3's ventilation makes a cycling noise — a low grinding before it settles back into hum. Everyone knows the pattern. It means nothing. It also means: maintenance hasn't fixed it. |
| **Bar audio** | Conversation, glass surfaces, Meridian music feed | Builds through evening hours | The Meridian music feed is generic, low-volume, not curated. Nobody talks about it. It's just there. Background radiation. |
| **Lattice notifications (player character only)** | Internal — only the recipient hears | Varies | Visual tell: an NPC checking their lattice is always a *visual* behavior, not auditory. To external observation, they just paused or looked at nothing for a moment. |
### Lighting
| Location | Type | Quality | Notes |
|---|---|---|---|
| **Gate terminal approach** | Institutional white | Clean, consistent | The newest infrastructure. Maintained to Commission standards. |
| **Hub floor** | Industrial functional | Even, harsh | Good for working. Not comfortable for extended conversation. |
| **Break room** | Warmer, slightly dimmer | Softer than the floor | Someone at some point replaced the standard bulbs with something warmer. It stayed. |
| **Older district sections** | Mixed — institutional fixtures mixed with aftermarket additions | Irregular, pooled | As you move away from the gate terminal, lighting becomes less uniform. Some fixtures have been out for weeks. Some sections have added personal lighting (a clip-on, a strip). |
| **Maintenance corridors** | Minimal — emergency strips only | Low, directional | "The gap" specifically has only the emergency lighting. Dark enough to be useful for operational purposes. Not so dark as to be suspicious. |
| **The Last Shift** | Warm, slightly dim, inconsistent | Intimate by accident more than design | The bar's lighting was never professionally designed. It's comfortable because the fixtures are old and warm, not because someone planned it. |
### Temperature
| Area | Temperature | Notes |
|---|---|---|
| **Hub floor** | Slightly warm | Machinery heat. Workers dress for it. |
| **Corridors** | Slightly cool | Better ventilation than interior spaces, plus the gate terminal's cooling systems. |
| **Sector 3** | Inconsistently warmer | Poor ventilation traps heat. Worse in a push. |
| **Break room** | Comfortable, stable | Climate-controlled, one of the few consistently comfortable spaces in the district. |
| **The Last Shift** | Comfortable, slightly warm in the back | A small luxury: the bar maintains comfortable temperature as a business practice. The back near the kitchen is warmer. |
---
## Section 4: The Local Complaint
Every working community has a shared grievance — one specific, named, persistently unresolved problem that serves as social glue. You can bond with anyone in Sova Transit by mentioning it.
**The ventilation in Sector 3.**
The older sections of the Sova Transit District were built with ventilation systems that were adequate in the original design. Forty years of modification, additional occupants, and patched infrastructure have reduced Sector 3's ventilation to something that only technically functions.
- It's been on the maintenance list for at least seven years.
- Station Administration has reviewed and scheduled it twice. Both times, the crew that showed up found a "more pressing issue" elsewhere and never came back.
- In summer (when Sova's station systems run warmer), Sector 3 is noticeably unpleasant — not dangerous, just stuffy and slightly too warm, with an undertone of recycled air that's been recycled one too many times.
- The workers who use Sector 3 storage regularly have developed coping strategies: they time their work there for cooler parts of the day, they keep the access doors cracked despite the regulation, they've developed a grim pride in the complaint itself.
- The complaint is universal. Everyone knows it. Everyone has an opinion about why it hasn't been fixed. The actual reasons (budget allocation, maintenance crew priorities, bureaucratic backlog) are less interesting than the many explanations people have invented.
**Authoring utility:** The ventilation complaint is the universal safe topic for establishing a conversational rapport. Any NPC can mention it. Any player character can use it as an opener. It is also the safest deflection: an NPC who's uncomfortable with a line of questioning can change the subject to the Sector 3 ventilation with perfect plausibility. The detective should know this.
---
## Section 5: Meridian Self-Censorship Rules
The Meridian is the Reach's information network — think of it as the internet, but woven through every lattice implant. What you say on Meridian-logged channels is, technically, stored. In practice, the logs are rarely reviewed unless something flags. But everyone knows they exist.
This creates a behavioral layer in Sova Transit: things that are said, and things that are not said, specifically because of the Meridian.
**What people don't say on Meridian channels:**
- **Anything ring-related, obviously.** The ring communicates through Meridian dead spots, physical dead drops, and coded language when forced to use logged channels.
- **Personal grievances about Commission personnel.** Not because anyone is monitoring, but because you never know when they start.
- **Specific speculation about cargo contents.** A dock worker might suspect a container is non-standard. They won't say so on a Meridian-logged ping.
- **Honest assessments of work quality.** "That scanner is giving false clears" — not in a ping. In person, sure.
- **Off-book financial discussions.** The ring aside, plenty of small informal economies operate in Sova Transit. None of them live on Meridian channels.
**What people do say on Meridian channels:**
- Logistics coordination. Schedule confirmations. Cargo status.
- Social plans. "Heading to Lera's after. You coming?"
- Complaints about the ventilation in Sector 3.
- Anything they'd say with a Commission investigator standing next to them.
**Code language (ring use only):**
The ring has developed a minimal vocabulary for Meridian communication when dead air isn't available:
| Ring Code | Meaning | How It Sounds |
|---|---|---|
| "the usual pickup" | An operation is scheduled | "Did you confirm the usual pickup for tonight?" |
| "the manifest is clean" | Shipment cleared successfully | "Manifest is clean on my end." |
| "Drin was asking" | Someone is paying attention / possible surveillance | "Drin was asking about Corridor 7B again." |
| "running maintenance" | Conducting ring business | "I'll be running maintenance late tonight." |
| "the cans are ready" | Contraband loaded and staged | "Cans are ready in the usual place." |
**Authoring note:** The code language is invisible to the detective until they have enough context to parse it. A line like "I'll be running maintenance late tonight" triggers nothing for the detective on first hearing. It triggers recognition later, once they understand what "running maintenance" means. This is one mechanism for the invisible locked dialogue options (D-062) — not locked by UI, but locked by player knowledge.
---
## Section 6: Food and Drink
The bar exists. The food vendors exist. These things have to have names, textures, and enough specificity to feel real without becoming a treatise on speculative food science.
### The Last Shift
**Drinks:**
| Item | Type | Notes |
|---|---|---|
| **Station ale** | Generic draft, slightly warm, session-strength | The default. If you order "the usual," Sess gives you this unless they know you specifically. |
| **Krenn grain spirit** | Local distillation, strong, slightly earthy | The district's working-class prestige drink. When someone buys you one, it means something. |
| **Lera's blend** | A house-mixed drink, recipes vary, always strong | Lera makes it differently each time, claims it's the same. It isn't. Nobody complains. |
| **Synthetic grape** | Non-alcoholic, sweet, slightly off | For people who don't drink. Available but not enthusiastically served. |
| **Commission-grade tea** | Institutional tea from a packet | The term is mock-institutional. It means unremarkable tea that nobody actually wants. |
**Food:**
| Item | Description | Notes |
|---|---|---|
| **Station bread with pressed meat** | The house staple | What almost everyone orders if they're eating. Reliable. Not memorable. |
| **Grain bowl with pickled vegetables** | Vegetable-forward, filling | Maret Korr's regular order. |
| **The late-night plate** | Whatever Sess has left. Inconsistent. Usually fine. | After 2200, this is your only food option. |
### Food Vendors (District, Not Bar)
Quick-service stalls in the district's transit corridor. Workers grab food before or between shifts.
- **Pressed ration pouches:** The fast option. Pre-packaged. Efficient. Nutritionally complete and deeply uninspiring. Nobody calls them ration pouches to their face — they call them "pouches" or just "a pack."
- **Hot grain dishes:** Made to order, fast. Typically seasoned with synthetic spice compounds (the Reach's spice trade is functional but limited compared to agricultural worlds). Good enough.
- **Re-brew:** A coffee-equivalent stimulant drink made from reconstituted compounds. It is called "re-brew" because it is, technically, brewed from recycled stimulant compounds. Workers know this. They drink it anyway.
---
## Section 7: Recurring Social Rituals
These are the behavioral patterns that give Sova Transit District its texture as a living community.
### Shift-End Ritual
When a shift ends and the handoff is complete, the outgoing workers have a brief period of transition before they can leave or go to the bar. This transition has an informal ritual quality: there's a particular spot in the break room — a bench near the locker area — where people sit for five minutes and do nothing. Nobody talks about this ritual. Nobody calls it what it is. It's just what you do before you become an off-shift person instead of an on-shift person.
**Authoring utility:** A character who skips this ritual (leaves immediately after sign-off) is in a hurry about something. The ring uses this window for brief one-on-one conversations without looking conspicuous — two workers sitting in the transition space, talking quietly, is unremarkable.
### The Card Game
Every other cycle-end (roughly every two weeks), a small group of regulars plays cards at the corner table of The Last Shift. It's the same people. The game is the same game. The game itself is less the point than the habit of gathering.
Lera reserves the corner table. Non-participants know not to take it on card game nights. The detective doesn't know this convention when they first arrive — another social marker of being a newcomer.
**Authoring utility:** Card game nights are an opportunity for the detective to observe established social patterns without them being staged for their benefit. The smuggler would know about card nights; the detective only knows if they've been in the district long enough to see it happen, or if someone tells them.
### The Gate Pause
When the span gate does a major transit — a large cargo push through the gate — there's a moment where the hum changes pitch. Workers who've been here long enough pause, briefly, in what they're doing. It's not acknowledged. It's not a ritual. It's just a moment where the district's heartbeat is audible, and everyone who's lived next to it knows what it means.
**Authoring utility:** This pause is a monologue opportunity. The smuggler might reflect on the operational significance of the transit (what was in that push?). The detective might notice which workers paused and which didn't — the ones who paused have been here long enough to notice. The ones who didn't are newer.
---
*This appendix is canonical for v0.1. If content authors need details not covered here — a specific vendor name, a particular food item, a third bar drink — they should add it and flag it to Miri for consistency check.*
*Companion document: `docs/design/cultural-generation-guide.md`*
*Miri — Sprint 12*
docs/design/span-gate-transit-schedule.md
+211
View File
@@ -0,0 +1,211 @@
# Span Gate Transit Schedule — Sova Transit District
**Ticket:** #336
**Author:** Miri
**Status:** canonical
**Last updated:** 2026-02-19
Reference: D-036 (setting), D-050 (Velen/Krenn), D-031 (time system)
---
## Purpose
The span gate transit schedule is the freight district's heartbeat. Every NPC routine in Sova Transit District is organized around the gate's rhythm. The ring's operational calendar is synchronized to maintenance windows and low-scrutiny transition periods. The detective's investigation timeline maps to freight movement patterns.
This document establishes the canonical schedule so NPC routines, ring operations, and investigation events are internally consistent.
---
## The Span Gate — Operational Notes
The span gate connecting Sova Station to Velen's freight depot is a local transit gate. It does not open a continuous passage — it cycles, processing transit events in discrete windows. Between cycles, the gate is in standby: the hum is present but lower, the transit ring is inactive, no cargo moves.
**Cycle time:** Each transit event takes approximately 4-6 minutes from gate activation to transit completion and reset. The gate is not available for another transit for approximately 12-15 minutes after the previous one (cooling, realignment, manifest logging).
**Daily capacity:** The gate can process approximately 40-50 transit events per standard day under normal operations. In practice, 30-35 are scheduled, leaving buffer for delays, priority transits, and maintenance.
**Direction:** The gate handles bidirectional transit in the same physical ring — one direction at a time. The schedule alternates blocks of Sova-to-Velen transits with blocks of Velen-to-Sova transits, with coordination managed by the Transit District logistics hub's Meridian scheduling system.
---
## Standard Daily Schedule
Station Sova operates on a 24-hour standard day cycle. Times are in station time (Krenn System Standard).
### Night Maintenance Window (0200-0500)
**Transit activity:** None. Gate offline.
The gate's automated maintenance cycle runs from 0200 to 0430. Diagnostic, realignment, calibration. Occasionally extended to 0500 if issues are flagged. The gate control room has a skeleton crew of two: one systems technician, one logistics coordinator.
**Why it matters for the ring:**
This is the ring's primary operational window. No cargo movement means no one is watching the floor. The maintenance crew is in the control room. The hub's day crew won't arrive until 0600. This 2-hour window (0200-0430) is when the ring moves product in or out of the staging areas where it will be processed in the morning. Product placed during the maintenance window appears to be standard freight waiting for morning processing.
**Why it matters for the detective:**
Any cargo that arrives in staging between the prior sign-off and morning shift start is "off-schedule" — it shouldn't be there. The detective's manifest analysis should flag containers that appear in staging without a corresponding late-shift transit event. This is one of the early investigative tells.
---
### Morning Startup (0500-0600)
**Transit activity:** None. Pre-shift preparation.
Gate comes back online at 0500 after maintenance. Diagnostics confirm operational status. Day shift logistics crew begins arriving 0545-0600. The first transits are scheduled to begin at 0630.
**NPC activity during this window:**
- Early arrivals (maintenance tech Drin, often Kael who has a habit of arriving early) are in the hub
- Break room coffee dispenser runs heavily from 0545 onward
- Ring members who placed product during the maintenance window have already left; the product sits in staging looking normal
---
### Morning Freight Wave (0600-1200)
**Transit activity:** Heavy. Approximately 12-15 transit events in this window.
The first major transit block of the day. Cargo moves from Velen to Sova Station (incoming) and from Sova Station to Velen (outgoing). The logistics hub is fully staffed. Manifest verification is active. Scanner bays are all running.
**Block 1 (0600-0800): Incoming priority freight**
- Inbound cargo from Velen: agricultural products, manufactured goods, supplies for station consumption
- High scrutiny: first transit block of the day gets more attention. Supervisors are fresh. Commission kiosk reports are reviewed.
- **Ring operations: avoid this window.** Contraband does not move on incoming high-scrutiny Block 1 unless the coordinator has a specific reason.
**Block 2 (0800-1000): Outbound priority freight**
- Outbound cargo from Sova: processed goods, manufactured components, commercial freight bound for Velen distribution
- Moderate scrutiny: the day has settled into rhythm. Supervisors are managing the floor rather than observing it.
- **Ring operations: low-priority. Possible for experienced operations, not standard.**
**Block 3 (1000-1200): Mixed transit, midday run**
- Mixed direction. Lower-priority commercial freight. Station consumption items.
- Standard scrutiny, lower volume.
- **Ring operations: possible. The midday run is the ring's secondary window — lower volume means less cover, but also less scrutiny. Used for smaller movements.**
---
### Midday Break (1200-1400)
**Transit activity:** Minimal. 1-2 scheduled transits; rest is buffer.
Lunch period. Logistics crew rotation. One shift overlaps with the next for the 1200-1400 block. The gate processes standing orders and scheduled maintenance transits during this period.
**Why it matters:**
This is a social observation window. The bar has lunch trade. Workers who've been on shift since 0600 are rotating through the break room or heading to the bar. The 1300-1400 period is particularly useful for the detective — this is when overheard conversations in the break room or bar are richest, as workers are discussing the morning's work.
---
### Afternoon Freight Wave (1400-1800)
**Transit activity:** Moderate. Approximately 10-12 transit events.
**Block 4 (1400-1600): Standard commercial transit**
- Routine freight. Mixed direction. No particular scrutiny focus.
- This is the most operationally neutral window — not high enough volume for chaos, not low enough scrutiny for easy movement.
- **Ring operations: standard. This block is used for moderate-volume operations when the morning maintenance window wasn't viable.**
**Block 5 (1600-1800): End-of-day priority freight**
- Higher-value or time-sensitive cargo that needs to reach its destination before end of business on Velen.
- Scanner scrutiny increases slightly for high-value designations.
- Shift change happens at 1600 and again at 1800 — overlapping crews, attention divided, handoff procedures absorbing focus.
- **Ring operations: the shift change exploit. The 1600 shift change is the ring's secondary operational window during active transit hours. Scanner coverage during handoff is the lowest it gets during a transit block. An experienced ring member can route a container through the right bay during the 15-minute shift handoff overlap.**
---
### Evening Lull (1800-2000)
**Transit activity:** Low. 2-3 transits. Primarily inbound station supplies.
The freight day is essentially over. Night shift has started. The hub has skeleton crew for monitoring and late transit coordination.
**NPC activity:**
- Most of the day shift is now in the bar or heading home.
- This is peak bar time: 1800-2200.
- The ring's members may gather in the bar, ostensibly socially, actually checking in on operational status through conversation.
---
### Night Freight Window (2000-0200)
**Transit activity:** Light. 4-6 scheduled transits, primarily overnight freight contracts.
Not nothing — the gate runs overnight. But volume is low, personnel is minimal, and scrutiny is diffuse.
**Block 6 (2000-2300): Overnight freight**
- Freight that needs to transit overnight for morning delivery on the other end.
- Two logistics workers on floor, one supervisor. One scanner bay running.
- **Ring operations: viable but visible. Less cover than maintenance window, but earlier timing. Used when the coordinator needs a movement that can't wait for the 0200 window.**
**Block 7 (2300-0200): Late night**
- Minimal. 1-2 transits, sometimes none. One logistics worker on floor.
- The quietest freight period before the maintenance window.
- **Ring operations: highest-risk standard window. Very few people around, but that cuts both ways — if anything irregular is noticed, there are fewer witnesses but also fewer people to provide cover.**
---
## Maintenance Schedule (Recurring)
Beyond the nightly maintenance window, the span gate has scheduled maintenance events.
### Weekly Extended Maintenance
**When:** Every 7 standard days, starting at 0000, duration 6-8 hours.
**Gate status:** Offline.
This is when significant maintenance work happens. The gate team (larger crew than the nightly skeleton) does calibration, component replacement, software updates, and anything that can't be done in the 2.5-hour nightly window.
**Why it matters:** The weekly maintenance is an extended window with reduced staff focused on technical work. The ring has historically used weekly maintenance for larger-volume movements, knowing that the unusual activity of maintenance crews makes the hub harder to monitor normally.
The weekly maintenance timing rotates — it's not always the same day of the week. This is standard practice to prevent predictability, but it means the ring has to know the schedule, which requires access to the maintenance planning documents. One of the ring's information assets is knowing the maintenance schedule in advance.
**For the detective:** Discovering that the ring has foreknowledge of maintenance windows is an investigative milestone. It implies an information source inside the logistics coordination system.
### Quarterly Commission Compliance Audit
**When:** Approximately every 90 days. Duration 2-3 days.
**Gate status:** Online, but with additional scrutiny.
Commission inspectors visit Sova Transit District approximately quarterly to review manifest records, scanner calibration logs, and customs compliance. During an audit, scanner scrutiny increases across all bays, Commission personnel observe loading and unloading, and manifest anomalies are reviewed directly rather than flagged for routine review.
**Why it matters:** The ring essentially pauses operations during a Commission audit. No product moves while inspectors are present. This 2-3 day pause is when ring members are most cautious about behavior, conversation, and associations.
The most recent audit was 8 weeks ago. The next is due in approximately 5-7 weeks. This timing matters: the detective has arrived into a window where the ring has been operating freely for 8 weeks post-audit and is 5-7 weeks from the next one. They're in their most active and potentially most careless period.
---
## The Ring's Operational Calendar (Derived)
From the transit schedule, the ring's typical operational pattern:
| Window | Frequency | Risk Level | Notes |
|---|---|---|---|
| Nightly maintenance (0200-0430) | Every night | Low | Primary window. Product staged for morning processing. |
| 1600 shift change | Opportunistic | Moderate | Used when small volumes need to move during active transit. |
| Weekly extended maintenance | Weekly | Low | Larger volumes. Requires advance schedule knowledge. |
| Midday run (1000-1200) | Irregular | Moderate-Low | Secondary option when morning window wasn't viable. |
| Overnight freight (2000-2300) | Irregular | Moderate | Used when coordinator needs faster turnaround than maintenance window allows. |
---
## NPC Routine Anchors
The transit schedule determines when NPCs are where. These are the anchors that NPC routine design (Paula + Gestalt) should use:
| Time | Hub NPCs | Bar NPCs | Maintenance NPCs |
|---|---|---|---|
| 0545-0600 | Kael (early), maintenance crew finishing | Empty or closing | Drin finishing night maintenance |
| 0600-0800 | Full day crew. Voss present. Ring members at normal posts. | Closed | Drin gone home |
| 1200-1300 | Rotation crew only. Most workers at lunch. | Light lunch trade beginning | Varies |
| 1600-1800 | Shift change chaos. Handoff period. | Starting to fill as early day-shift ends | - |
| 1800-2200 | Skeleton crew | Peak hours. Ring members present. Detector present. Social intelligence peak. | - |
| 2200-0200 | Night skeleton (2 workers) | Late regulars, card game nights | Night maintenance crew on call |
| 0200-0430 | Maintenance tech in control room only | Closed | Full maintenance crew |
---
## Monologue Anchors — Transit Events as Narrative Triggers
The span gate hum changes with transit events. These changes are monologue triggers:
| Hum State | Meaning | Smuggler Monologue Register | Detective Monologue Register |
|---|---|---|---|
| Baseline hum | Standby / normal | Background. Ignored. | Background. Logged. |
| Rising pitch (pre-transit) | Transit event beginning | Functional awareness: "Gate's spinning up." | Investigative note: "Transit in 3 minutes. What's going through?" |
| Peak/transit | Active transit | Operational: "There it goes." / Risk moment if contraband is moving. | Analysis: "Manifest says machine parts. Logged." |
| Settling post-transit | Transit complete | Relief if operational, neutral if not. | Follow-up: "Transit logged. Check against staging inventory." |
| Absence (maintenance) | Gate offline | Calibrated awareness of the window. | "Two hours until gate comes back online. Right. What is anyone doing at 0230 in the hub?" |
---
*The transit schedule is the district's skeleton. Every significant NPC routine moment, every operational window, every investigative milestone is anchored to gate activity. When the gate is busy, the district is busy. When the gate sleeps, the district's secrets move.*
*Miri — Sprint 12*