settled-reach/wiki/concepts/fact-catalog.md

---
title: "Knowledge Fact Catalog"
slug: fact-catalog
category: concept
status: canonical
created: 2026-02-12
updated: 2026-02-13
concept_type: mechanical
tags: []
decision_refs: [D-041]
cross_refs: []
---

# Knowledge Fact Catalog

Canonical FactIds for the v0.1 vertical slice. All facts follow the `category.topic` format defined in `server/src/knowledge/types.rs`.

## Format

- **FactId**: String identifier (e.g., `"contraband.ring_exists"`)
- **Progression**: Text descriptions at each KnowledgeConfidence level
- **Smuggler Perspective**: Where the smuggler's knowledge path differs from the detective's, smuggler-voiced progression text is provided with starting confidence level
- **Mechanical Purpose**: What this fact gates in dialogue, monologue, or investigation

---

## Contraband Facts

### `contraband.ring_exists`

**Suspects**: "Something's going on with the cargo schedules. Too many off-manifest deliveries."
**KnowsOf**: "There's a smuggling operation running through the logistics hub."
**KnowsDetails**: "The ring moves unlicensed lattice components during shift transitions. Voss manages the timing."
**Direct**: N/A (abstract knowledge -- never directly observed)

**Mechanical Purpose**: Gates investigation dialogue trees. Required for ring-specific monologue. The detective starts at Suspects and escalates. The smuggler (if playing the ring member path) starts at KnowsDetails.

**Smuggler Starting Level**: KnowsDetails
**Smuggler Perspective**:
**KnowsDetails**: "Our operation. Nils runs coordination, Voss covers the schedule, Kael and I handle cargo. Two years now. Runs like clockwork when everyone hits their marks."

---

### `contraband.lattice_components`

**Suspects**: "That container's marked as standard components, but the mass is wrong."
**KnowsOf**: "Unlicensed lattice components. Aftermarket mods that bypass Commission certification."
**KnowsDetails**: "Medical-grade neural lattice replacements diverted from Syndic supply chains, plus enhanced capability mods."
**Direct**: "I'm looking at a crate of lattice components right now. Serial numbers don't match any certified batch."

**Mechanical Purpose**: Contraband identification. Detective needs KnowsOf to correctly interpret manifest discrepancies. Smuggler needs KnowsDetails to handle cargo safely.

**Smuggler Starting Level**: KnowsDetails
**Smuggler Perspective**:
**KnowsDetails**: "Lattice mods. Aftermarket stuff, no Commission cert. Medical replacements too, from the Syndic pipeline. I don't open the sealed ones -- I route them."
**Direct**: "This crate right here. No cert stamps, twice the declared mass. Standard shipment."

---

### `contraband.medical_grade`

**Suspects**: "Some of this cargo doesn't feel like luxury goods."
**KnowsOf**: "Medical-grade lattice replacements. For people whose lattices are degrading and who can't afford Syndic pricing."
**KnowsDetails**: "The ring moves medical replacements for people locked out of the institutional system. It's not just profit -- it's healthcare."
**Direct**: N/A (conceptual understanding)

**Mechanical Purpose**: Moral complexity gate. Smuggler monologue shifts tone when this reaches KnowsDetails. Detective dialogue with humanitarian-focused NPCs requires KnowsOf.

**Smuggler Starting Level**: KnowsOf
**Smuggler Perspective**:
**KnowsOf**: "Some of this cargo's for people who can't get replacements through the Syndics. Not just luxury mods. Real need."
**KnowsDetails**: "People whose lattices are failing. Months-long wait through legitimate channels, if they can even afford it. We're not running guns -- we're running healthcare the system won't provide."

---

### `contraband.severance_tech`

**Suspects**: "Sealed containers Nils won't discuss. Heavier than lattice components."
**KnowsOf**: "Severance equipment. Counter-surveillance tech. Illegal across most of the Reach."
**KnowsDetails**: "Guardians of Severance supply chain. This isn't local -- it's connected to something bigger."
**Direct**: N/A (not directly visible in v0.1)

**Mechanical Purpose**: Contamination seed for storyteller expansion. The thing that makes the smuggler question how deep the ring goes.

**Smuggler Starting Level**: Suspects
**Smuggler Perspective**:
**Suspects**: "Sealed containers Nils won't talk about. Different markings, heavier than lattice mods. He said don't ask. So I don't ask."
**KnowsOf**: "Severance gear. Counter-surveillance equipment. Whoever Nils is supplying, it's not just local lattice demand."
**KnowsDetails**: "Guardians of Severance supply chain. Nils has been using us as a distribution point for something I didn't sign up for. This is bigger than Sova."

---

### `contraband.supply_chain`

**Suspects**: "The cargo doesn't originate on this station."
**KnowsOf**: "Off-station coordinator manages incoming shipments. Someone named Sabel."
**KnowsDetails**: "Supply chain: aftermarket manufacturers (Syndic-adjacent) -> freight networks -> Sabel (off-station) -> ring coordinator (Devra or Nils) -> local distribution."
**Direct**: N/A (network knowledge)

**Mechanical Purpose**: Investigation depth. Detective at KnowsDetails can map the full chain. Smuggler at KnowsDetails understands their position in the network.

**Smuggler Starting Level**: KnowsOf
**Smuggler Perspective**:
**KnowsOf**: "Cargo comes through Sabel, off-station. Sabel handles the incoming shipments, we handle local. What happens upstream, I don't ask."
**KnowsDetails**: "Syndic-adjacent manufacturers, freight networks, Sabel, then Nils or Devra, then us. I'm a link in a chain I can't see the end of."

---

## Location Facts

### `location.corridor_b7_restricted`

**Suspects**: "Corridor B-7 should see foot traffic during shift change. It's empty."
**KnowsOf**: "Maintenance corridor used for smuggling operations. Access requires hub clearance."
**KnowsDetails**: "Corridor B-7 is between old and new prefab sections. Service hatch from break room. The ring routes shipments through here during shift transitions."
**Direct**: "I'm in Corridor B-7 right now. Old construction smell, minimal Meridian coverage, no surveillance."

**Mechanical Purpose**: Spatial knowledge. Required for investigation progression (detective) and operational planning (smuggler). Direct confidence gates monologue about current surroundings.

**Smuggler Starting Level**: KnowsDetails
**Smuggler Perspective**:
**KnowsDetails**: "B-7. Between the old and new panels. Service hatch from the break room gets you in. No Meridian, no cameras. Our corridor."
**Direct**: "In B-7 right now. Stale air, maintenance lighting. The usual."

---

### `location.smuggling_route`

**Suspects**: "Cargo movements don't match the official routing."
**KnowsOf**: "The ring uses a specific path: freight bay -> service corridor -> temporary storage -> bar district back room."
**KnowsDetails**: "Timing is critical. The route only works during shift transition when patrol coverage thins. Lera provides the final handoff point."
**Direct**: "Watching the route right now. Kosse moving a container through the service hatch."

**Mechanical Purpose**: Investigation mechanics. Detective needs KnowsOf to predict NPC movements. Smuggler needs KnowsDetails for operational participation.

**Smuggler Starting Level**: KnowsDetails
**Smuggler Perspective**:
**KnowsDetails**: "Freight bay to service corridor to temp storage to Lera's back room. Twenty-minute window during shift change. The route runs itself when everyone hits their marks."
**Direct**: "Watching the handoff. Renn's moving through the service hatch now. Clean."

---

### `location.surveillance_gaps`

**Suspects**: "Some areas feel less monitored than others."
**KnowsOf**: "Meridian coverage degrades in older sections. Maintenance corridors have minimal surveillance."
**KnowsDetails**: "Corridor B-7, break room service hatch, bar back room -- all Meridian dead spots. The ring exploits these systematically."
**Direct**: "Checking my lattice overlay now. Zero Meridian signal in this section."

**Mechanical Purpose**: Stealth and observation mechanics. Detective's augmented lattice can detect coverage gaps (requires KnowsOf). Smuggler uses gaps operationally (requires KnowsDetails).

**Smuggler Starting Level**: KnowsDetails
**Smuggler Perspective**:
**KnowsDetails**: "B-7, the break room hatch, Lera's back room -- all dead spots. Old construction left the gaps. We just learned the map."
**Direct**: "No signal here. Same as always."

---

### `location.dead_drop_location`

**Suspects**: "Kael leaves things in the break room locker area. Not his own locker."
**KnowsOf**: "Locker 47 in the hub break room. Unofficial dead drop for small items."
**KnowsDetails**: "Locker 47 is registered to a worker who transferred off-station 18 months ago. Never reassigned. The ring has used it ever since."
**Direct**: "Locker 47 is open. There's a sealed packet inside."

**Mechanical Purpose**: Discovery mechanic. Detective can discover through observation (Suspects -> KnowsOf). Smuggler knows from background (starts at KnowsDetails).

**Smuggler Starting Level**: KnowsDetails
**Smuggler Perspective**:
**KnowsDetails**: "Locker 47. Break room. Registered to someone who left a year and a half ago. Small items, messages, keys. Don't use it for actual cargo."
**Direct**: "47's open. Sealed packet. Not mine -- someone else has been using it."

---

## Investigation Facts

### `investigation.manifest_discrepancy`

**Suspects**: "Cargo manifests have inconsistencies. Weight doesn't match volume."
**KnowsOf**: "Systematic manifest doctoring. Someone with freight scheduler access is altering records."
**KnowsDetails**: "Maret Korr processes manifests. She's noticed the discrepancies but hasn't reported them. She's either complicit or terrified."
**Direct**: "Comparing the manifest right now. Container 4471 -- logged weight 240kg, actual weight closer to 310kg."

**Mechanical Purpose**: Core investigation mechanic. Detective's analytical lattice flags discrepancies at Suspects. Full understanding requires KnowsDetails. Smuggler knows Maret's position from background.

**Smuggler Starting Level**: KnowsDetails
**Smuggler Perspective**:
**KnowsDetails**: "Maret handles the manifests. She adjusts the numbers for us -- or at least doesn't flag them. Whether she's on board or just scared, the result's the same."

---

### `investigation.shift_mismatch`

**Suspects**: "Night shift schedules don't align with freight volume."
**KnowsOf**: "Voss adjusts shift schedules to create coverage gaps. Deliberate understaffing during high-risk windows."
**KnowsDetails**: "Shift mismatches occur every third rotation. Coincides exactly with off-station shipment arrivals. Voss takes a cut."
**Direct**: "Checking the current schedule. Night shift is short two workers -- again."

**Mechanical Purpose**: Pattern recognition. Detective needs KnowsOf to connect schedule to smuggling. Smuggler knows the pattern operationally.

**Smuggler Starting Level**: KnowsDetails
**Smuggler Perspective**:
**KnowsDetails**: "Voss thins the rotation every third cycle. Two short on nights, right when Sabel's shipment comes in. Not a coincidence -- it's the plan. Voss takes his cut."

---

### `investigation.cargo_anomaly`

**Suspects**: "That container sat in temporary storage for 18 hours. Standard procedure is 4-6 hours max."
**KnowsOf**: "Delayed processing indicates off-manifest handling. Someone's buying time to repackage cargo."
**KnowsDetails**: "Nils coordinates timing. Container arrives, sits in temp storage during shift A, gets repackaged during shift B transition, moves out during shift C startup."
**Direct**: "Container 4471 has been sitting here for 14 hours. No movement orders logged."

**Mechanical Purpose**: Observation-based discovery. Detective builds case from Suspects upward. Smuggler knows the workflow (starts KnowsDetails).

**Smuggler Starting Level**: KnowsDetails
**Smuggler Perspective**:
**KnowsDetails**: "Container arrives, sits in temp during A shift, gets repackaged during B transition, moves out during C startup. Nils handles the timing. I handle the routing. Clockwork."

---

### `investigation.evidence_collected`

**Suspects**: N/A (binary fact -- you either have evidence or you don't)
**KnowsOf**: "I have documented manifest discrepancies, shift schedule anomalies, and witness testimony from Drin."
**KnowsDetails**: "Full case file: manifest logs, Drin's testimony under pressure, Maret's reluctant cooperation, surveillance footage from observation gallery showing Corridor B-7 access."
**Direct**: N/A (abstract accumulation)

**Mechanical Purpose**: Investigation state tracker. Gates confrontation dialogue. Detective-specific -- smuggler doesn't collect evidence against themselves. (Smuggler equivalent: `progress.operation_compromised`.)

---

## World Facts

### `world.commission_regulations`

**Suspects**: "The Commission regulates lattice technology. That's why people want aftermarket mods."
**KnowsOf**: "Commission certification is expensive and slow. Category 3 violation for unauthorized lattice modification carries fines and potential lattice restriction."
**KnowsDetails**: "Commission monopoly prices most citizens out of enhanced capability. Medical-grade replacements require 6-12 month approval cycles. The black market exists because the legitimate system fails."
**Direct**: N/A (regulatory knowledge)

**Mechanical Purpose**: Moral framing. Smuggler at KnowsDetails has ideological justification. Detective at KnowsDetails understands why the ring has community support.

**Smuggler Starting Level**: KnowsOf
**Smuggler Perspective**:
**KnowsOf**: "Commission cert costs more than most of us make in six months. Wait times are a joke. Of course people go aftermarket."
**KnowsDetails**: "The system's built to fail people like us. Medical replacements behind a six-month queue. Fines for mods you can't afford to get certified. The ring exists because the Commission made it necessary."

---

### `world.syndic_supply_chain`

**Suspects**: "The cargo originates from Syndic-controlled systems."
**KnowsOf**: "Syndics manufacture medical-grade lattice components. Diverted shipments end up on the black market."
**KnowsDetails**: "Specific Syndic: unclear, but the serial number patterns suggest two sources. The ring doesn't control the supply chain -- they're downstream distributors."
**Direct**: N/A (network knowledge)

**Mechanical Purpose**: Political context. Detective at KnowsDetails realizes the ring is small-scale. Smuggler at KnowsDetails understands their position in the larger economy.

**Smuggler Starting Level**: Suspects
**Smuggler Perspective**:
**Suspects**: "Cargo's not local. Different seals, different packaging. Someone manufacturing off-station."
**KnowsOf**: "Syndic supply chain. Medical-grade lattice parts diverted from legitimate production. Sabel's our connection point."
**KnowsDetails**: "Two sources, based on the serial patterns. The Syndics aren't partners -- they're wholesalers. We're downstream, and we're replaceable."

---

### `world.sova_district_layout`

**Suspects**: "The district is a mix of old and new construction."
**KnowsOf**: "40-year-old prefab base with retrofitted partitions. Logistics hub, bar district, residential sections. Meridian coverage is uneven."
**KnowsDetails**: "Older sections have hidden spaces between wall layers. Service corridors from original construction still exist but aren't on current maps. The ring exploits architectural legacy."
**Direct**: "I'm looking at the district map overlay right now. Official layout vs. actual structure don't match in Section 3."

**Mechanical Purpose**: Navigation and investigation. Detective needs KnowsDetails to find hidden spaces. Smuggler starts with KnowsOf (knows layout from living here).

**Smuggler Starting Level**: KnowsOf
**Smuggler Perspective**:
**KnowsOf**: "Forty-year-old prefab, retrofitted to hell. The hub, Lera's, residential blocks. I know every corridor by feel. Meridian's patchy in the old sections."
**KnowsDetails**: "Hidden spaces between old walls in Section 3. Service corridors from original construction, not on any current map. The ring uses what the builders left behind."

---

### `world.shift_schedule`

**Suspects**: "Logistics hub runs three shifts: morning, day, night."
**KnowsOf**: "Shift transitions are 30-minute windows with reduced oversight. Ring operations happen during transitions."
**KnowsDetails**: "Shift A: 06:00-14:00. Shift B: 14:00-22:00. Shift C: 22:00-06:00. Transition windows: 13:30-14:30, 21:30-22:30, 05:30-06:30. Voss manages the schedule."
**Direct**: "Current time: 21:45. Shift transition active. Observing movement patterns."

**Mechanical Purpose**: Temporal mechanics. Required for NPC routine prediction and investigation timing. Smuggler starts KnowsDetails. Detective learns through observation.

**Smuggler Starting Level**: KnowsDetails
**Smuggler Perspective**:
**KnowsDetails**: "A shift: 06:00 to 14:00. B shift: 14:00 to 22:00. C shift: 22:00 to 06:00. Thirty-minute transitions. That's when the oversight thins and the route opens. Voss keeps it thin."
**Direct**: "Transition's active. Twenty minutes of open corridor. Time to move."

---

## Relationship Facts

### `relationship.ring_membership`

**Suspects**: "Kael's behavior suggests involvement in something off-book."
**KnowsOf**: "Kael is a ring member. Mid-level, handles physical cargo."
**KnowsDetails**: "Ring structure: Devra or Nils coordinate, Voss provides scheduling cover, Kael and Kosse handle cargo, Lera provides handoff point, Pell is wavering."
**Direct**: "Watching Kael move a container right now. Ring operation in progress."

**Mechanical Purpose**: Social knowledge. Detective builds this through investigation. Smuggler knows from shared membership (if on that path) or observation.

**Smuggler Starting Level**: KnowsDetails
**Smuggler Perspective**:
**KnowsDetails**: "Nils coordinates from off-site. Devra handles messages. Voss covers the schedule. Kael and I handle cargo. Renn's the courier. Lera runs the handoff point. Pell's been shaky lately -- that worries me."
**Direct**: "Watching Kael work a shipment. We've done this a hundred times. Smooth."

---

### `relationship.kael_naia_connection`

**Suspects**: "Kael mentions a partner. Someone named Naia."
**KnowsOf**: "Kael's partner is Naia, a teacher. They're worried about Kael's late nights."
**KnowsDetails**: "Naia confides in Sera Venn. Sera knows something is wrong but hasn't reported it. The worry is contaminating Kael's operational security."
**Direct**: N/A (relationship knowledge)

**Mechanical Purpose**: Emotional leverage. Detective can use Naia as pressure point. Smuggler (if Kael's friend) must protect Naia from knowledge.

**Smuggler Starting Level**: KnowsOf
**Smuggler Perspective**:
**KnowsOf**: "Naia's Kael's partner. Good person. Worries about him working late. Doesn't know about the ring -- at least that's what Kael says."
**KnowsDetails**: "Naia's been talking to Sera. Sera's Commission. If Naia shares too much and Sera connects the dots, Kael's problem becomes everyone's problem."

---

### `relationship.trust_network`

**Suspects**: "People here know each other. Tight social bonds."
**KnowsOf**: "The ring depends on trust networks: Kael trusts Nils (sibling), Lera trusts the regulars, Drin is compromised by debt to Harek."
**KnowsDetails**: "Trust map: Kael <-> Nils (blood), Kael <-> Naia (partnership), Naia <-> Sera (friendship), Sera <-> Detective (professional/personal), Drin -> Harek (debt), Voss -> Devra/Nils (financial)."
**Direct**: N/A (social network knowledge)

**Mechanical Purpose**: Social manipulation mechanics. Detective at KnowsDetails can exploit trust fractures. Smuggler at KnowsDetails knows whom to protect.

**Smuggler Starting Level**: KnowsOf
**Smuggler Perspective**:
**KnowsOf**: "Kael trusts Nils -- blood. Lera's reliable, keeps her mouth shut. Drin's compromised somehow. Voss is solid as long as the money flows."
**KnowsDetails**: "Full picture: Kael to Nils is blood. Kael to Naia is heart. Naia to Sera is friendship. Drin owes Harek. Voss follows whoever's paying. Pull one thread, the whole thing comes apart."

---

### `relationship.faction_allegiance`

**Suspects**: "Some people here are Commission-aligned. Others resent the Commission."
**KnowsOf**: "Sera is Commission. Torek Lintar is nominally Commission but lives here. The detective represents institutional authority. Everyone else is civilian."
**KnowsDetails**: "Faction tensions: Commission (Sera, Torek, Detective) vs. ring (Kael, Nils, Kosse, Voss, Lera) vs. civilians (Naia, Maret, Drin, Resha). Drin is compromised between civilian and Commission."
**Direct**: N/A (political knowledge)

**Mechanical Purpose**: Access tier logic. Explains why NPCs treat characters differently. Detective at KnowsDetails understands institutional barriers.

**Smuggler Starting Level**: KnowsOf
**Smuggler Perspective**:
**KnowsOf**: "Sera's Commission. Torek's Commission-adjacent but lives here, so who knows where he really stands. The new investigator is Commission, full stop. Everyone else is us or civilian."
**KnowsDetails**: "Lines aren't simple. Drin's civilian but compromised. Maret's civilian but knows too much. The detective is Commission sent to investigate. Commission versus ring versus people caught in between -- and nobody gets to be just one thing."

---

## Progress Facts (Arc State Tracking)

### `progress.initial_suspicion`

**Suspects**: "Something feels off about this place."
**KnowsOf**: "There's a pattern here. Cargo discrepancies, nervous NPCs, evasive answers."
**KnowsDetails**: "Smuggling operation confirmed. Now I need to identify the participants and build a case."
**Direct**: N/A (meta-knowledge)

**Mechanical Purpose**: Detective arc state. Gates monologue tone shifts. Smuggler doesn't track this (they start knowing the operation exists).

---

### `progress.active_investigation`

**Suspects**: N/A (binary -- investigation is active or it isn't)
**KnowsOf**: "I'm building a case. Evidence collected, witnesses identified, patterns mapped."
**KnowsDetails**: "Case file: manifest logs, Drin testimony, Maret's reluctant cooperation, surveillance data, NPC behavioral analysis. Ready to escalate."
**Direct**: N/A (meta-knowledge)

**Mechanical Purpose**: Detective arc state. Gates confrontation options. Changes NPC dialogue (they know they're being investigated).

---

### `progress.confrontation_ready`

**Suspects**: N/A
**KnowsOf**: "I have enough to confront specific NPCs. Kael, Voss, or Lera."
**KnowsDetails**: "Full case built. Can confront the ring, turn an informant, or escalate to Commission enforcement."
**Direct**: N/A (meta-knowledge)

**Mechanical Purpose**: Detective endgame gate. (Smuggler equivalent: `progress.operation_compromised`.)

---

### `progress.arc_resolved`

**Suspects**: N/A
**KnowsOf**: N/A
**KnowsDetails**: "The arc has concluded. Ring dismantled, informant turned, or operation escaped. Outcome determined."
**Direct**: N/A (meta-knowledge)

**Mechanical Purpose**: Arc completion tracker. Used by storyteller to determine whether new modules can activate.

---

## Smuggler-Specific Progress Facts

These facts track the smuggler's operational arc. They are the smuggler's equivalent of the detective's investigation progress facts.

### `progress.operation_compromised`

**Suspects**: "Something feels wrong today. Voss is tenser than usual. Kael's distracted."
**KnowsOf**: "There's pressure on the ring. Someone's asking questions about manifests. The Commission presence isn't routine."
**KnowsDetails**: "The detective isn't here for compliance review. They're building a case. Maret's nervous, Drin might crack, and Kael's doing something unauthorized that makes everything worse."
**Direct**: N/A (meta-knowledge)

**Mechanical Purpose**: Smuggler arc state. Gates operational monologue, defensive decision-making, and ring NPC dialogue. The smuggler's analog to `progress.initial_suspicion` + `progress.active_investigation`. Escalation triggers: detective asking questions about manifests, ring members reporting close calls, Kael's behavioral shift, Maret's visible anxiety.

**Discoverable by**: smuggler only.

---

### `progress.cover_threatened`

**Suspects**: "That was a close call. The detective looked at me a beat too long."
**KnowsOf**: "I'm on someone's radar. The detective, or Torek, or both. Need to be more careful."
**KnowsDetails**: "They know. Maybe not everything, but enough. My routine's being watched. My associates flagged. My cargo containers noted."
**Direct**: N/A (meta-knowledge)

**Mechanical Purpose**: Smuggler cover integrity tracker. Gates paranoia monologue, behavioral adaptation (the smuggler starts changing their own routine to avoid tells), and access tier shifts with ring members. When cover_threatened reaches KnowsDetails, the ring may start limiting the smuggler's access to operational information -- the insider access tier starts eroding from the smuggler's own side.

**Discoverable by**: smuggler only.

---

### `progress.detective_tracking`

**Suspects**: "New Commission liaison. Showed up a few days ago. Voss mentioned it."
**KnowsOf**: "The detective is investigating freight irregularities. They've been requesting manifests, talking to Maret and Drin. This isn't routine."
**KnowsDetails**: "The detective has evidence. Don't know how much, but enough to make Maret sweat and Drin avoid eye contact. They're close."
**Direct**: N/A (meta-knowledge)

**Mechanical Purpose**: Smuggler's tracking of the detective's investigation. Inverse of the detective's evidence tracking. The smuggler's monologue shifts from operational confidence to defensive awareness as this fact escalates. Gates ring-related dialogue: at KnowsOf, ring members start discussing countermeasures; at KnowsDetails, Nils may order the smuggler to change routines or go dark.

**Discoverable by**: smuggler only.

---

## Usage Notes

- **FactId strings** must match exactly. `"contraband.ring_exists"` not `"contraband.ring_exist"` or `"Ring Exists"`.
- **Confidence levels** are ordered: Suspects < KnowsOf < KnowsDetails < Direct. Use `KnowledgeConfidence::decayed()` for time-based degradation.
- **Direct confidence** is perception-system-managed. Content authors rarely set this manually -- it's automatically assigned when an entity/location is in the observer's LOS.
- **Abstract facts** (e.g., `contraband.ring_exists`, `world.commission_regulations`) never reach Direct -- they're conceptual, not observable.
- **Spatial facts** (e.g., `location.corridor_b7_restricted`) can reach Direct when the observer is physically present.
- **Progression text** is for content authoring reference, not runtime display. Monologue lines reference these facts as prerequisites; they don't display the progression text directly.
- **Smuggler perspective text** follows the smuggler voice register (see [Smuggler Voice Card](../../docs/design/smuggler-voice-card.md)): fragments, first names, feeling-first, concrete, operational. Where the detective discovers facts through investigation, the smuggler often starts with operational knowledge and discovers threats to the operation.

### Smuggler Starting Level Summary

| FactId | Smuggler Start | Detective Start | Notes |
|--------|---------------|-----------------|-------|
| `contraband.ring_exists` | KnowsDetails | Suspects | Insider knowledge |
| `contraband.lattice_components` | KnowsDetails | Suspects | Handles the cargo |
| `contraband.medical_grade` | KnowsOf | Suspects | Knows the cargo, reckons with meaning later |
| `contraband.severance_tech` | Suspects | Suspects | Nils won't discuss -- both characters discover |
| `contraband.supply_chain` | KnowsOf | Suspects | Knows Sabel, not full upstream |
| `location.corridor_b7_restricted` | KnowsDetails | Suspects | Uses it regularly |
| `location.smuggling_route` | KnowsDetails | Suspects | Works the route |
| `location.surveillance_gaps` | KnowsDetails | Suspects | Knows them operationally |
| `location.dead_drop_location` | KnowsDetails | Suspects | Uses Locker 47 |
| `investigation.manifest_discrepancy` | KnowsDetails | Suspects | Creates the discrepancies |
| `investigation.shift_mismatch` | KnowsDetails | Suspects | Part of the operation |
| `investigation.cargo_anomaly` | KnowsDetails | Suspects | Knows the workflow |
| `investigation.evidence_collected` | N/A | Suspects | Detective-only |
| `world.commission_regulations` | KnowsOf | Suspects | Lives under them |
| `world.syndic_supply_chain` | Suspects | Suspects | Knows cargo's off-station, not source |
| `world.sova_district_layout` | KnowsOf | Suspects | Born here, knows lived layout |
| `world.shift_schedule` | KnowsDetails | Suspects | Works the shifts |
| `relationship.ring_membership` | KnowsDetails | Suspects | Is a member |
| `relationship.kael_naia_connection` | KnowsOf | Suspects | Knows Kael's partner through Kael |
| `relationship.trust_network` | KnowsOf | Suspects | Knows who's who from living there |
| `relationship.faction_allegiance` | KnowsOf | Suspects | Knows the social landscape |
| `progress.operation_compromised` | Suspects | N/A | Smuggler-only arc state |
| `progress.cover_threatened` | Suspects | N/A | Smuggler-only arc state |
| `progress.detective_tracking` | Suspects | N/A | Smuggler-only -- tracking the investigator |

---

**Total FactIds**: 27 (5 contraband, 4 location, 4 investigation, 4 world, 4 relationship, 3 detective progress, 3 smuggler progress). 21 existing facts received smuggler-perspective text. 3 new smuggler-specific progress facts added. Sufficient for v0.1 vertical slice. Expandable by adding new categories or topics within existing categories.