settled-reach/docs/sprints/sprint-3/copy.md

Sprint 3: Know — Copy Tasks

Goal: Complete the knowledge vocabulary document to unblock content authoring.

Branch: Content work feeds into multiple branches (no code branch) Agents: Mellanie (authoring), Paula (narrative design), Gestalt (systems design)

Carry-over from Sprint 2

#	Title	Status	Notes
#368	Knowledge vocabulary for v0.1 content	in_progress	Started Sprint 2, carries to Sprint 3

Context

Sprint 2 started the knowledge vocabulary document (docs/design/knowledge-vocabulary-v0.1.md). Sprint 3 completes it.

The knowledge graph data structures are implemented (Sprint 2, tickets #361-367). The observation event pipeline is being built (Sprint 3, ticket #239). The content team needs to define what goes into those containers — the FactIds, EntityKnowledge attribute keys, and RelationshipState transition triggers that actual gameplay content will reference.

Without this vocabulary:

• Mellanie can't write monologue prerequisites (prerequisite: { suspects: "manifest_discrepancy" } — is manifest_discrepancy a valid FactId?)
• Paula can't design NPC profiles with knowledge gates (what known_attributes keys exist?)
• The observation event generator (#239) can't map NPC behaviors to meaningful triggers (what counts as a "social anomaly"?)

This ticket unblocks content authoring ticket #309 (Sprint 4+) and is the bridge between knowledge graph implementation and actual content.

Assigned Ticket

#	Title	Priority	Est.	Blocked by
#368	Knowledge vocabulary for v0.1 content (#309)	high	0.5d	—

Use db/connectors/ticket show 368 for full details.

What You're Delivering

A design document: docs/design/knowledge-vocabulary-v0.1.md

The document must define:

1. FactId Categories for v0.1

FactId is the identifier for non-entity knowledge (see server/src/knowledge/types.rs lines 21-25). Format: "category.topic" (e.g., "contraband.ring_exists").

Define 15-25 concrete FactIds for v0.1 scope covering:

• Contraband knowledge (ring existence, lattice components, medical-grade replacements, Severance tech per D-037)
• Location knowledge (restricted corridors, smuggling routes, surveillance coverage, span gate schedules)
• Event knowledge (manifest discrepancies, suspicious meetings, evidence discoveries)
• World knowledge (Commission regulations, Syndic supply chains, Sova District context per D-036)
• Relationship knowledge (trust networks, faction allegiances, personal connections)
• Investigation progress (investigation stages, evidence collected, confrontation triggers)

Each FactId must map to the 4-level confidence hierarchy (Suspects / KnowsOf / KnowsDetails / Direct). Example:

contraband.ring_exists
  - Suspects: "There's off-the-books cargo moving through here"
  - KnowsOf: "There's a smuggling ring operating in Sova"
  - KnowsDetails: "Kael, Voss, and Drin are running lattice components through customs bypass"

location.corridor_b7_restricted
  - Suspects: "B-7 access is tighter than it should be"
  - KnowsOf: "B-7 requires dock credentials after 18:00"
  - KnowsDetails: "B-7 is the primary smuggling handoff point, Commission sweeps at shift change"

2. EntityKnowledge Attribute Keys

EntityKnowledge.known_attributes is a BTreeMap<String, String> (see server/src/knowledge/types.rs lines 163-165). Define the canonical keys for v0.1:

• Identity: name, role, faction, species (human assumed for v0.1)
• Social: relationship_type (colleague, friend, regular, contact, rival), trust_level (low/medium/high)
• Behavioral: routine_pattern (shift worker, bar regular, transient), behavior_flags (avoidant, talkative, nervous, defensive)
• Secrets: secret_held (freeform description), secret_confidence (Suspects/KnowsOf/KnowsDetails)
• Investigation: tell_observed (description of observable tell), contradiction_flagged (yes/no)

Provide 3-5 example EntityKnowledge entries for v0.1 NPCs (Kael Davan, Sera Venn, Lera Sessik, Torek Lintar, Voss Krenn) showing how these keys populate. Use D-034 FRIEND profiles as reference.

3. RelationshipState Transition Patterns

RelationshipState drives entity color rendering (see D-033, server/src/knowledge/types.rs lines 117-140). The enum is:

• Unknown (teal)
• Known (soft green)
• Friendly (soft green, trusted)
• PersonOfInterest (amber, flagged by investigation)
• Hostile (red, character knows there is danger)

Define the canonical transition triggers for v0.1:

Unknown → Known:

• First direct observation with name attribution
• Told about entity by trusted source

Known → Friendly:

• Trust-gated dialogue completed (D-028 Layer 3 "real" tier accessed)
• Multiple positive interactions without contradictions
• Entity provides useful information

Known/Friendly → PersonOfInterest:

• Monologue triggers "something's off" (Suspects-level knowledge about this entity's contradiction)
• Observable tell detected (D-034 tell system)
• Entity avoids specific topics or NPCs

PersonOfInterest → Hostile:

• KnowsDetails-level knowledge of entity's threat to player
• Direct observation of hostile action
• Contradiction confirmed (THE FRIEND arc climax, D-034)

Known/Friendly → Hostile:

• Direct observation of hostile action with no warning
• Emergency trust collapse (rare)

4. Observation Event Trigger Definitions

The observation event generator (#239) needs to know what counts as a "meaningful observation." Define the 5 trigger types with concrete examples:

1. Routine deviation: NPC not at expected location during their scheduled time
2. Absence detection: Expected NPC missing from usual location
3. Social anomaly: Unexpected NPC pairing or avoidance behavior
4. New information: First observation of an entity/location/behavior
5. Contradiction: Observed behavior conflicts with told information

Each trigger type should map to specific NPC axis data (D-024) and monologue tone.

Key Decisions

• decisions/architecture.md — D-041 (Knowledge Graph Data Model — canonical structs)
• decisions/content.md — D-024 (10-axis NPC model), D-034 (THE FRIEND pattern), D-035 (tag taxonomy), D-036 (Sova setting), D-037 (contraband)
• decisions/perception.md — D-016 (internal monologue), D-033 (entity color = relationship)

Canonical References

• Knowledge graph structs: server/src/knowledge/types.rs
• Knowledge graph canonical design: docs/workshops/knowledge-graph-information-boundaries/round2-synthesis.md (Part 3, lines 320-752)
• THE FRIEND profiles: D-034 (Kael Davan, Sera Venn)
• Setting details: D-036 (Sova Transit District, Krenn System)
• Contraband details: D-037 (lattice components)

Completion Criteria

The document is complete when:

1. All 4 sections (FactIds, EntityKnowledge keys, RelationshipState triggers, Observation triggers) are filled with concrete examples
2. Each FactId has confidence-level descriptions
3. EntityKnowledge examples cover at least 3 v0.1 NPCs
4. RelationshipState transitions map to specific gameplay events
5. Observation triggers reference specific NPC axis combinations

This unblocks #309 (content authoring), which is the first monologue/dialogue writing ticket.

Notes

• Sprint 2 progress: If significant work was done in Sprint 2, review and complete remaining sections. If minimal progress, prioritize FactIds and EntityKnowledge keys first (those block #309 most directly).
• Cross-team coordination: Observation event trigger definitions should align with server ticket #239 implementation. Gestalt should coordinate with Dudley on trigger semantics.
• Authoring ergonomics: The vocabulary should be author-friendly. FactIds should read like natural language. Attribute keys should be memorable. Avoid cryptic codes.