settled-reach/docs/design/knowledge-flags-v01.md

title, description, type, status, ticket, decision_refs, author, created, updated

title	description	type	status	ticket	decision_refs	author	created	updated
Knowledge Flags — v0.1 Quick Reference	Quick reference of valid fact IDs, prerequisite formats, and starting knowledge for monologue content authoring	design	active	#309	D-028 D-035 D-041 D-075		2026-02-19	2026-02-19

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

# 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:

# 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:

# 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