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.