jpmschweitzerandClaude Opus 4.6
934d4df4b0
Standardized YAML frontmatter on all 40 docs/design/ files with title, description, type, status, ticket, decision_refs, and author fields. Covers specs, wireframes, voice cards, spatial layouts, and system designs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
286 lines
12 KiB
Markdown
286 lines
12 KiB
Markdown
---
|
|
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*
|