--- title: "Knowledge Flags — v0.1 Quick Reference" description: "Quick reference of valid fact IDs, prerequisite formats, and starting knowledge for monologue content authoring" type: design status: active ticket: "#309" decision_refs: [D-028, D-035, D-041, D-075] author: "" created: 2026-02-19 updated: 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 ```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*