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

---
title: "Sprint 2 — Copy Briefing"
description: "Knowledge vocabulary definition, FactId categories, entity-attributes keys"
type: sprint
status: archived
sprint: 2
team: "copy"
---

# Sprint 2: See — Copy Tasks

**Goal:** Define the knowledge vocabulary that content authoring requires. Deliver the FactId categories, known_attributes keys, and RelationshipState transition patterns for v0.1.

**Branch:** Content work feeds into multiple branches (server knowledge graph, client dialogue system, design documents)
**Agents:** Mellanie (authoring), Paula (narrative design), Gestalt (systems design)

## Context

Sprint 2 delivers the knowledge graph data structures on the server side (tickets #361-367). The knowledge graph is THE mechanism that gates dialogue, triggers monologue, and drives THE FRIEND contradiction arc. But the server team is implementing empty containers — they need the content team to define what goes in those containers.

Your role this sprint: **define the controlled vocabulary for v0.1 content.**

When Mellanie writes a monologue line with `prerequisite: { suspects: "manifest_discrepancy" }`, the server needs to know that `manifest_discrepancy` is a valid FactId. When Paula designs Kael Davan's profile with `known_attributes: { role: "dock_worker", faction: "ring_member" }`, the dialogue system needs to know those are the canonical keys. When the contradiction detection system marks an entry as `Contradicted`, the content needs to know what relationship state transitions make sense.

This ticket unblocks content authoring (#309) and is the bridge between the knowledge graph implementation and actual gameplay 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 the categories and 15-25 concrete FactIds for v0.1 scope. Categories must cover:
- **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. Must include:

- **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 Van Maanen's Star) 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:**
- Skip PersonOfInterest if threat is immediate and unambiguous
- Cover blown scenario
- Direct aggression observed

Provide 2-3 concrete examples mapping to v0.1 narrative beats (e.g., Kael's arc for smuggler, Sera's arc for detective).

### 4. KnowledgeState Usage for v0.1

`KnowledgeState` is `Active` / `Contradicted` / `Stale` (see `server/src/knowledge/types.rs` lines 73-89).

Sprint 2 implementation only uses `Active`. But content must plan for Sprint 3 contradiction detection. Define:

- **What triggers Contradicted state:** Conflict between `DirectObservation` and `ToldBy` source on the same FactId or EntityKnowledge attribute. Example: Kael tells smuggler he's meeting partner Hael, but smuggler sees Kael meeting unknown contact in B-7.
- **Content requirements for contradiction arcs:** Each FRIEND NPC (D-034) needs at least one Contradicted trigger. List the 2 primary contradictions for v0.1 (Kael for smuggler, Sera for detective).
- **Stale handling:** Note that Stale is set by decay system (default: 3600 ticks = 6 game-hours per D-041), not by content. Content should assume Direct observation downgrades to KnowsDetails → KnowsOf → Suspects over time if not refreshed.

### 5. Integration with D-035 Tag Taxonomy

The `prerequisite` tag on monologue lines (D-035) references FactIds. Show 5-10 example monologue prerequisites using the vocabulary you've defined:

```yaml
# Example format (do not include in final document — reference only)
- id: sova_m_001
  character: smuggler
  trigger: observe_npc
  prerequisite:
    knows_of: "contraband.ring_exists"
    entity:
      target: kael_davan
      min_confidence: KnowsOf
  text: "Kael's moving with purpose. Shift doesn't start for another hour."
```

Define which FactIds map to which monologue triggers (per D-035: enter_location, observe_npc, hear_sound, observe_anomaly, post_conversation, discover_evidence, witness_interaction, time_idle, return_visit).

## Type Definitions to Conform To

Read `server/src/knowledge/types.rs` for canonical struct definitions. Key types:

- `FactId(String)` — lines 21-25
- `KnowledgeConfidence` enum — lines 28-67
- `KnowledgeState` enum — lines 73-89
- `KnowledgeSource` enum — lines 95-107
- `RelationshipState` enum — lines 117-140
- `EntityKnowledge` struct — lines 145-165 (note `known_attributes: BTreeMap<String, String>` at line 164)
- `FactKnowledge` struct — lines 169-179
- `KnowledgeGraph` component — see full definitions at `docs/workshops/knowledge-graph-information-boundaries/round2-synthesis.md` lines 320-520

## Good Vocabulary Entries Look Like This

**FactId example (good):**
```
investigation.manifest_discrepancy
  - Suspects: "The cargo manifests don't add up"
  - KnowsOf: "Dock worker signatures don't match logged shifts"
  - KnowsDetails: "Kael signed for 18 containers on a day he was off-shift"
```
What makes this good: specific, maps to confidence levels, ties to investigation mechanic, references concrete NPC (Kael).

**FactId example (bad):**
```
smuggling.general
  - KnowsOf: "There's smuggling happening"
```
What makes this bad: vague category, no confidence progression, no mechanical hook, too generic.

**EntityKnowledge attributes example (good):**
```yaml
kael_davan:
  name: "Kael Davan"
  role: "dock_worker"
  faction: "ring_member"
  relationship_type: "colleague"
  trust_level: "high"
  routine_pattern: "shift_worker"
  behavior_flags: "reliable, quiet"
  secret_held: "meeting unknown contact in B-7, not partner Hael"
  secret_confidence: "Suspects"
  tell_observed: "avoids eye contact when Hael is mentioned"
  contradiction_flagged: "no"
```
What makes this good: complete identity, behavioral hooks, secret with confidence level, observable tell, ties to THE FRIEND arc.

**RelationshipState transition example (good):**
```
Smuggler + Kael Davan:
  Initial: Friendly (colleague, trusted, high trust_level)
  Trigger: observe Kael entering B-7 at off-hours → PersonOfInterest
  Monologue: "Kael's here? He's not on shift. And he's avoiding the main corridor."
  Progression: PersonOfInterest → contradiction detected (sees Kael with unknown contact, not Hael) → Contradicted state set → Hostile
```
What makes this good: clear initial state, specific trigger, ties to monologue, maps to THE FRIEND arc beats (D-034, D-039).

## Dependencies and Constraints

**Blocks:**
- #309 (Knowledge state vocabulary for v0.1) — Mellanie cannot write monologue prerequisites until this vocabulary exists
- #299 (Opening hook content — smuggler)
- #300 (Opening hook content — detective)

**Requires:**
- D-041 (Knowledge Graph Data Model) — read `decisions/architecture.md` lines 117-134
- D-034 (THE FRIEND) — read `decisions/content.md`, provides Kael Davan and Sera Venn as reference NPCs
- D-035 (Tag taxonomy) — read `decisions/content.md`, defines `prerequisite` tag format
- D-036 (Sova Transit District) — read `decisions/content.md`, provides setting context
- D-037 (Contraband specification) — read `decisions/content.md`, defines what the ring is smuggling
- D-028 (Dialogue architecture) — read `decisions/content.md`, defines access tiers that map to confidence levels

**Constraints:**
- v0.1 scope only — 15 NPCs, 3 social sites (Logistics Hub, Bar, Ring spaces per D-027)
- No procedural generation of FactIds — all must be hand-authored and stable across playthroughs
- FactId strings must be machine-parseable (no spaces, lowercase, dot-separated)
- Attribute keys must be consistent across all EntityKnowledge entries (BTreeMap keys are strings, but use the same keys for the same concepts)
- Sprint 2 server implementation only uses `Active` state and `DirectObservation` source — but vocabulary must plan for Sprint 3 expansion

## Deliverable Format

Markdown document at `docs/design/knowledge-vocabulary-v0.1.md` with sections:

1. **FactId Catalog** — table with category, FactId, confidence progressions, mechanical purpose
2. **EntityKnowledge Attribute Keys** — table with key name, type, purpose, example values
3. **Example EntityKnowledge Entries** — 3-5 complete examples for v0.1 NPCs
4. **RelationshipState Transition Triggers** — table with transition, trigger condition, example scenario
5. **Contradiction Patterns for v0.1** — 2 concrete THE FRIEND contradictions (Kael, Sera)
6. **Monologue Prerequisite Examples** — 5-10 lines showing FactId → monologue mapping
7. **Integration Notes** — how this vocabulary feeds into D-035 tag taxonomy and dialogue authoring

Keep it practical. This is a reference document for Mellanie's authoring work and Gestalt's dialogue system implementation. No narrative prose — tables, bullet points, concrete examples.

## Key References

- `server/src/knowledge/types.rs` — type definitions
- `decisions/architecture.md` D-041 — knowledge graph architecture
- `decisions/content.md` D-034 — THE FRIEND NPC profiles
- `decisions/content.md` D-035 — tag taxonomy and prerequisite format
- `decisions/content.md` D-036 — Sova Transit District setting
- `decisions/content.md` D-037 — contraband specification
- `docs/workshops/knowledge-graph-information-boundaries/round2-synthesis.md` — full design context

Estimate: 0.5 day. Unblocked — start immediately.