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

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

# 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

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

- id: pc-smuggler_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.

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:

prerequisites:
  facts:
    - fact_id: investigation.kael_corridor_meeting
      min_confidence: suspects

Pattern 3: Progressive revelation — late

Line fires with actionable evidence in hand:

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

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

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

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