diff --git a/docs/design/archetype-evidence-presentation.md b/docs/design/archetype-evidence-presentation.md new file mode 100644 index 000000000..2dbb1019c --- /dev/null +++ b/docs/design/archetype-evidence-presentation.md @@ -0,0 +1,1230 @@ +# Archetype Evidence Presentation Spec + +**Ticket:** #443 | **Sprint:** 7 | **Decision:** D-065, D-034, D-033 +**Authors:** Mellanie (voice/copy), Paula (narrative structure), Gestalt (systems) +**Date:** 2026-02-15 +**Revised:** 2026-02-15 (Paula -- narrative depth pass: THE FRIEND arcs, contradiction timeline, authoring guidelines) +**Revised:** 2026-02-16 (Gestalt -- systems design pass: mechanical framework, data flow, systems interaction map, contradiction pipeline, fun factor analysis, implementation notes) +**Revised:** 2026-02-16 (Gestalt -- systems review: fix verb priority per interaction-verbs spec, fix confidence bar/label mismatch, use detective labels not raw enums, fix section numbering, flag Take/Place as v0.2+, resolve color semantic collision with insert-palette blues, clarify DSC-002 source types per D-041, add notebook curated-content design statement) +**Revised:** 2026-02-16 (Lead -- final pass: rename KnowsOf label from "Corroborated" to "Noted Facts", resolve strikethrough timing open question per Paula, add non-confrontation/resolution states to Section 6.3) + +--- + +## 1. Purpose + +Both archetypes share the same 3x3 inventory grid (D-065), the same knowledge graph, and the same underlying simulation. What differs is the **presentation layer** -- how evidence looks, reads, and feels to each character. + +The detective sees a case file. The smuggler sees a notebook. Same facts. Different frames. This spec defines the visual language, copy tone, labeling conventions, and contradiction presentation for each archetype. + +**This is a design specification.** No code, no sprites. It informs: +- Client inventory UI rendering (future item sprites and text styling) +- Copy authoring (item descriptions, tooltip text, monologue reactions) +- Visual design (aesthetic direction for Araminta's future sprite work) + +--- + +## 2. Design Principles + +### 2.1 Same Grid, Different Skin + +Both archetypes use the D-065 3x3 grid (bottom-right, 40x40px pocket icons, 1-9 hotkeys). The grid structure is identical. The difference is entirely in: +- **Item names** (what the character calls things) +- **Descriptions** (how the character describes what they're holding) +- **Tooltip text** (quick-reference when hovering) +- **Contradiction markers** (how conflicting information surfaces) +- **Visual styling** (sprite aesthetic, text treatment, color cues) + +### 2.2 Voice Rules Apply + +All inventory text follows the established voice patterns (`docs/design/voice-patterns.md`): +- **Smuggler text:** contractions, first names, fragments, concrete/physical language, no institutional vocabulary +- **Detective text:** mixed contractions (analytical = no, personal = yes), surnames, complete sentences, institutional labeling + +### 2.3 Diegetic Frame + +Inventory presentation is diegetic (D-013). The detective's case file is rendered through the neural insert -- it's Commission software running on institutional hardware. The smuggler's notebook is personal -- scratched notes on a private lattice partition, no Commission formatting, no analytical tools. + +### 2.4 Mechanical Framework: Evidence as Knowledge Graph Projection + +Evidence items are **not** separate data structures. They are presentation-layer projections of knowledge graph state ([D-041](../../decisions/architecture.md#d-041-knowledge-graph-data-model)). The server stores facts, observations, and relationship states in the KG. The client reads that data and renders it through the character's lens. + +``` +Knowledge Graph (server, per-entity Component, BTreeMap) + | + v +Observer Snapshot (per-character KG view, sent every tick) + | + v +Evidence Presentation Layer (client-side, archetype-specific) + | + +-- Detective: Case file format, structured fields, insert overlay + +-- Smuggler: Notebook format, personal voice, no overlay +``` + +**Critical rule:** The server sends identical `ObserverSnapshot` data regardless of archetype. All presentation differences are client-side rendering decisions. The server does not know or care whether it's serving a detective or smuggler -- it serves knowledge graph entries, and the client applies archetype-specific formatting. + +**Physical items are the exception.** The smuggler's 3 physical items (D-065: manifest copy, corridor access token, personal comm log) and the detective's 2 institutional tools exist as ECS `InventoryItem` components in addition to their KG entries. Physical items carry risk: they can be detected if scanned by security, confiscated, or lost. Pure KG knowledge carries no physical risk. This asymmetry is mechanically load-bearing -- the smuggler must manage objects, the detective manages information. + +### 2.5 D-033 Entity Color Integration + +Evidence entries that reference entities inherit [D-033](../../decisions/perception.md#d-033-entity-color--relationship-to-player) color associations. This creates a visual thread between the world view and the evidence view: + +| Context | Detective | Smuggler | +|---------|-----------|----------| +| **World view** | Entity sprite tinted with relationship color | Same | +| **Evidence entries** | D-033 color dot `[o]` next to entity surname | No color dot -- notebook is physical/analog, not digital | +| **Color shift propagation** | All case file entries referencing an entity update their color dots when `RelationshipState` changes | No notebook change -- color shift experienced through world view + monologue | + +**Why the smuggler doesn't see entity colors in the notebook:** + +1. **The notebook is analog.** Not rendered through the insert. The detective's case file IS the insert -- digital, connected, live. The smuggler's notes are personal, disconnected, static until she edits them. +2. **The smuggler reads relationships, not data.** She knows Kael is her friend because he's her friend, not because a color dot says so. D-033 color is visible on Kael's *sprite* in the world. The notebook doesn't have metadata. +3. **Player decision impact:** The detective can scan case file entries and see amber dots accumulating -- a visual pattern of suspicion forming. The smuggler has to remember. This creates different investigation rhythms and different cognitive load on the player. + +When an entity's `RelationshipState` changes (e.g., Kael: Friendly -> PersonOfInterest at contradiction discovery): +- **Detective case file:** Every entry mentioning "Davan, K." updates its color dot from teal `#4a9ebb` to amber `#e8c547` (0.5s fade matching D-033 transition). The accumulation of amber dots across multiple entries is itself information. +- **Smuggler notebook:** No visual change. The player re-reads Kael's entries and sees the old warm notes alongside the new doubt annotations. The contrast is textual, not chromatic. + +### 2.6 Verb System Integration + +Per [D-057](../../decisions/perception.md#d-057-entity-interaction--vertical-list-insert-styled), the two-phase verb computation produces different verb sets per archetype for the same objects: + +| Object | Detective Verb | Smuggler Verb | Mechanical Difference | +|--------|---------------|---------------|----------------------| +| Cargo manifest | `Scan` | `Grab a copy` | Detective: KG entry with `authority` source, no physical risk. Smuggler: physical item + KG entry, detectable. | +| Access token | `Flag` / `Confiscate` | `Pocket` | Detective: marks it in case file (KG-only). Smuggler: takes it (physical, carries risk). | +| Comm terminal | `Access logs` | `Check messages` | Detective: queries institutional records. Smuggler: reads personal messages. | +| Suspicious container | `Scan` / `Tag` | `Move` / `Stash` | Detective: creates evidence chain. Smuggler: manages physical contraband. | + +These verb differences are **Phase 2 observer filter rules** (D-057). The server computes the maximum verb set from `ObjectType` components (Phase 1), then applies archetype-specific filter rules (Phase 2). Same object, same server tick, different verb options. No separate verb systems per archetype -- one system, two filter configurations. + +### 2.7 Confidence Level Mapping + +The detective's case file displays confidence using [D-041](../../decisions/architecture.md#d-041-knowledge-graph-data-model) confidence tiers mapped to institutional language: + +| KG Confidence | Detective Label | Visual | Dialogue Gate (D-028) | +|---------------|----------------|--------|-----------------------| +| `Suspects` | Unconfirmed | `██░░░░░░` grey text, dashed border | `surface` access only | +| `KnowsOf` | Noted Facts | `████░░░░` white text, solid border | `real` access unlocked, topic-specific dialogue | +| `KnowsDetails` | Verified | `██████░░` bold text, highlight border | `secret` access unlocked, `Confront` verb available | +| `Direct` | Direct observation | `████████` blue-white text, no border | Live observation, maximum fidelity | + +The smuggler sees **no confidence indicators**. Items appear when she has the knowledge. The presence of the entry IS her confidence. Design rationale: + +1. **Voice consistency:** The smuggler doesn't think in evidence tiers. She knows what she saw. (Anti-pattern: "Confidence: Suspects") +2. **Decision framing:** Without confidence labels, the smuggler decides based on gut + relationships, not institutional metrics. This produces genuinely different player decisions. +3. **Asymmetric information about information:** The detective knows how strong their evidence is. The smuggler knows what she knows but not how it would hold up institutionally. The smuggler might confront Kael based on a gut feeling and a notebook scrawl. The detective would wait for corroboration. Different rhythms, different risk profiles. + +--- + +## 3. Detective: The Case File + +### 3.1 Aesthetic + +**Frame:** Commission Evidence Management System. Clean. Structured. The insert formats everything into institutional templates whether the detective asks it to or not. Fields, labels, timestamps. The training runs in the background. + +**Visual language:** +- Thin ruled lines, cool white-blue palette (insert aesthetic per D-048) +- Monospaced labels left-aligned, values right-aligned +- Geometric insert styling: thin borders, precise spacing, no ornamentation +- Confidence indicators as fill bars (not numbers) -- the insert quantifies certainty visually +- Cross-reference links rendered as subtle underlines (insert suggests connections) + +**Color cues (evidence confidence states — distinct from D-033 entity colors):** +- Default evidence: insert white-blue `#c8d0e0` +- Flagged discrepancy: amber `#e8c547` (shared with D-033 Person of Interest — intentional, discrepancy IS suspicion) +- Confirmed contradiction: muted red `#d45d5d` (shared with D-033 Hostile/Dangerous — intentional, contradiction IS threat) +- Noted Facts: cool blue-white `#a8c8e8` (insert-palette blue — NOT green `#6bc9a6`, which is D-033 Known/Friendly for entity dots) + +> **Visual design note for Araminta:** Evidence confidence colors must NOT collide with D-033 entity relationship colors. Entity dots in case file entries use D-033 colors (teal/green/amber/red) to show relationship state. Evidence confidence uses the insert's blue-white palette to show evidentiary strength. Two separate color vocabularies, two separate meanings. Formalize the insert confidence palette in the visual style guide. + +### 3.2 Item Presentation Template + +Every item in the detective's inventory renders in a standardized case-file entry: + +``` +[ITEM LABEL] +Category: [type classification] +Acquired: [location, time] +Source: [how obtained] +Confidence: [bar indicator] +Relevance: [case connection] +--- +[Description: 1-2 sentences, analytical voice] +``` + +### 3.3 Detective Inventory Items (v0.1) + +The detective's physical inventory is minimal (D-065: 2 slots). Knowledge is the primary evidence system. The two physical items are institutional tools, not contraband. + +#### Item: Commission Datapad + +**Display name:** `Commission Datapad` + +**Description:** +> Standard-issue field unit. Case file #STC-4471, manifest irregularity investigation. Access logs, shift records, and flagged discrepancies auto-synced from the district relay. + +**Tooltip:** `Field datapad. Case #STC-4471. Synced.` + +**Flavor text:** `Assigned equipment. The case file that brought me here.` + +**Monologue on examine:** +> *"Case file's current. Fourteen flagged entries. Let's see which ones hold up in person."* + +**Visual direction:** Slim rectangular device. Commission blue-grey housing. Small status indicator (green = synced). No personal marks. Institutional object. + +#### Item: Credential Badge + +**Display name:** `Commission Badge` + +**Description:** +> Lattice Commission field investigator credentials. Grants authority-tier access to station systems and personnel interviews. Visible display recommended per protocol. + +**Tooltip:** `Commission credentials. Authority access.` + +**Flavor text:** `Opens doors. Closes others.` + +**Monologue on examine:** +> *"Still gets a reaction when I flash it. That reaction tells me more than the interview will."* + +**Visual direction:** Small metallic badge. Commission insignia (geometric, clean). Subtle insert-reactive edge (glows faintly when scanned). Official object. The kind of thing you show, not hide. + +### 3.4 Knowledge Graph Presentation (Case File View) + +The detective's primary evidence is knowledge, not physical items. The insert renders the knowledge graph as case-file entries. + +#### Evidence Entry Format + +When the detective discovers a fact (via observation, dialogue, or examination), the insert files it: + +``` +EVIDENCE ENTRY — [auto-generated ID] +Subject: Davan, K. +Category: Behavioral anomaly +Observed: The Terminal, Shift 2, 14:22 +Source: Direct observation +Confidence: ████░░░░ Noted Facts +--- +Subject observed in Corridor B-7 outside scheduled shift window. +No registered maintenance assignment for this period. +Cross-ref: Manifest discrepancy #7 (container weight, same date). +``` + +#### Key Copy Conventions (Detective Evidence) + +| Element | Convention | Example | +|---------|-----------|---------| +| **Subject naming** | Surname, Initial | `Davan, K.` / `Venn, S.` / `Lintar, T.` | +| **Category labels** | Institutional classification | `Behavioral anomaly` / `Schedule deviation` / `Financial irregularity` | +| **Source types** | Formal evidence sourcing | `Direct observation` / `Overheard exchange` / `Terminal access log` / `Informant statement` | +| **Confidence display** | Fill bar + detective label | `████░░░░ Noted Facts` | +| **Description tone** | Clinical, third-person | "Subject observed in..." not "I saw him in..." | +| **Time references** | Shift-relative, precise | `Shift 2, 14:22` not `afternoon` | +| **Cross-references** | Insert-generated links | `Cross-ref: Manifest discrepancy #7` | + +#### Example Evidence Entries + +**Manifest discrepancy (from examining terminal):** +``` +EVIDENCE ENTRY — MFD-007 +Subject: Station logistics (Sova Transit) +Category: Documentation irregularity +Observed: The Terminal, Shift 1, 09:14 +Source: Terminal access log +Confidence: ██████░░ KnowsDetails +--- +Container 4471: logged weight 240kg, reconciled weight 283kg. +43kg discrepancy exceeds standard variance (±5kg). +Overnight hold in temp storage (standard turnaround: sub-8hr). +Cross-ref: Davan, K. — shift assignment overlap. +``` + +**Behavioral observation (from watching Sera):** +``` +EVIDENCE ENTRY — BEH-003 +Subject: Venn, S. +Category: Avoidance pattern +Observed: The Last Shift, Shift 3, 19:47 +Source: Direct observation (3rd occurrence) +Confidence: ██████░░ KnowsDetails +--- +Subject departed venue within 4 minutes of Lintar, T. arrival. +Third occurrence. Three distinct excuses provided. +Correlation: 1.00. Coincidence threshold exceeded. +Cross-ref: Lintar, T. — financial indicators (BEH-001). +``` + +### 3.5 Contradiction Presentation (Detective) + +When the knowledge graph contains conflicting entries, the insert flags a **DISCREPANCY**. + +#### Visual Treatment +- Amber highlight border around the conflicting entries +- `DISCREPANCY FLAGGED` header in amber `#e8c547` +- Both conflicting entries displayed side-by-side (or stacked) +- Insert auto-generates a confidence-weighted assessment + +#### Example Contradiction + +``` +══════════════════════════════════════ + DISCREPANCY FLAGGED — DSC-002 +══════════════════════════════════════ +Entry A: BEH-003 (Venn, S. — avoidance pattern) + Source: DirectObservation (3 occurrences) + "Subject avoids Lintar, T. Three recorded departures." + +Entry B: SOC-011 (Venn, S. — social profile) + Source: ToldBy (Venn, S. — direct conversation) + "Subject described as socially integrated. No recorded + conflicts or avoidance behaviors with district residents." +--- +Assessment: ToldBy statement contradicts DirectObservation +pattern re: Lintar, T. specifically. D-041 contradiction +detection: source type mismatch triggers Contradicted state. +Confidence in avoidance: KnowsDetails. Recommend direct +inquiry or extended surveillance. +══════════════════════════════════════ +``` + +#### Monologue on Contradiction Discovery + +> *"There it is. She says she's fine with everyone here. The data says otherwise. Three times, Sera. That is not social discomfort."* + +Note: contractions appear ("she's," "she's") because this is personal -- Sera is an ally. The uncontracted "That is not" is the institutional frame reasserting itself. Voice pattern checks out per `voice-patterns.md` Section 2.1. + +--- + +## 4. Smuggler: The Notebook + +### 4.1 Aesthetic + +**Frame:** Personal lattice partition. No institutional software. No templates. The smuggler's notes are organized the way a person organizes things -- by who, not by what. Handwritten feel. Margins full of second thoughts. The formatting is whatever made sense at the time. + +**Visual language:** +- Warm amber-cream palette (smuggler character tint `#f0e0c8` base) +- Irregular spacing, left-aligned, no grid structure +- Handwritten-style typeface (not monospaced -- variable, slightly uneven) +- Crossed-out text for revised information (strikethrough, not deletion) +- Question marks and underlines as emphasis (not color-coded flags) +- No auto-generated cross-references -- the smuggler makes connections manually or not at all + +**Color cues:** +- Default notes: warm cream `#f0e0c8` +- Personal emphasis: brighter amber `#e8c547` (underline, not highlight) +- Scratched out / wrong: muted grey strikethrough `#8b8ba0` +- Danger: no special color -- danger is expressed through word choice, not formatting + +### 4.2 Item Presentation Template + +The smuggler's items don't have templates. Each item reads like a personal note -- different lengths, different structures, whatever the smuggler would actually think when looking at the thing. + +``` +[ITEM NAME — what the smuggler calls it] + +[Description: 1-2 sentences, first person, concrete] + +[Flavor text: gut reaction, one line] +``` + +No category. No confidence bar. No cross-references. The smuggler doesn't file. The smuggler remembers. + +### 4.3 Smuggler Inventory Items (v0.1) + +The smuggler's three physical items are defined in `content/.../items/smuggler-inventory.yaml` (Sprint 6, #441). This spec adds the presentation-layer copy and visual direction. + +#### Item: Manifest Copy + +**Display name:** `Manifest Copy` + +**Description:** +> Cargo manifest from last cycle. Three containers that don't match the dock log. Kael's handwriting on the margins -- weight corrections that never got filed. + +**Tooltip:** `Last cycle's manifest. Kael's notes.` + +**Flavor text:** `Should've burned this weeks ago.` + +**Monologue on examine:** +> *"Kael's handwriting. Forty kilos over on three containers. He corrected the numbers but never filed the update. Sloppy? Or on purpose?"* + +**Visual direction:** Folded printout, slightly creased. Handwritten margin notes in different ink. The kind of thing you'd keep in a jacket pocket. Dog-eared corner. Not precious -- functional. + +#### Item: Access Token + +**Display name:** `Access Token` + +**Description:** +> Maintenance corridor keycard. Kael slipped it to me three weeks ago. Gets you past the service hatches into B-7. No legitimate reason to have this. + +**Tooltip:** `Corridor B-7. Kael's spare.` + +**Flavor text:** `Hope it still works.` + +**Monologue on examine:** +> *"Three weeks and it hasn't been revoked. Either nobody's checking, or Kael made sure they wouldn't."* + +**Visual direction:** Small physical card, slightly scuffed. Generic-looking -- could be any maintenance keycard. That's the point. No markings that say "smuggling ring credential." Unremarkable object that opens remarkable doors. + +#### Item: Comm Log + +**Display name:** `Comm Log` + +**Description:** +> Three months of messages. Times, names, drop schedules. Nils arranging volumes, Kael confirming routes, Renn reporting handoffs. Everything the ring said it never said. + +**Tooltip:** `Three months. All of it.` + +**Flavor text:** `Should've wiped these. Didn't.` + +**Monologue on examine:** +> *"Nils would kill me if he knew I kept these. Kael stopped answering three weeks ago. The silence is louder than the messages."* + +**Visual direction:** Not a physical object -- this renders as a lattice data icon (personal comm archive). Small, warm-toned, slightly pulsing (data is live, messages keep accumulating). The most dangerous thing the smuggler carries, and it looks like nothing. + +### 4.4 Knowledge Presentation (Notebook View) + +The smuggler's knowledge is organized by **person**, not by category. When the smuggler learns something, it's filed under who it's about. + +#### Notebook Entry Format + +``` +KAEL + +- Shift partner. Two years. Solid. +- Handles the dock-side routing. Knows the schedule + better than Voss. +- ~~Same old Kael~~ Something's off. Checking his + lattice too much. Won't say why. +- Corridor B-7. Late. Talking to someone I don't + know. Didn't tell me about a meeting. + Who was that? +``` + +No timestamps. No evidence IDs. No confidence bars. The smuggler writes like a person keeping track of a life that's getting complicated. + +#### Key Copy Conventions (Smuggler Notebook) + +| Element | Convention | Example | +|---------|-----------|---------| +| **Subject naming** | First name only | `Kael` / `Naia` / `Voss` / `Lera` | +| **Organization** | By person, not category | `KAEL` section, `VOSS` section | +| **Observations** | First-person, concrete | `Won't make eye contact` not `Avoidance behavior noted` | +| **Revisions** | Strikethrough, not deletion | `~~Same old Kael~~` | +| **Uncertainty** | Question marks, not confidence tiers | `Who was that?` not `Confidence: Suspects` | +| **Time references** | Relative, informal | `Last cycle` / `Three weeks ago` / `Late` | +| **Connections** | Manual, if present at all | The smuggler doesn't cross-reference -- she remembers, or she doesn't | + +#### Example Notebook Entries + +**About Voss (from observation + dialogue):** +``` +VOSS + +- Shift supervisor. Takes a cut. Gets nervous when + the volume goes up. +- Changed the rotation twice this cycle. Didn't + tell anyone why. +- Snapped at the new hire again. Third time today. + Something's eating him. +``` + +**About Naia (from conversation with Kael):** +``` +NAIA + +- Kael's partner. Worries about him -- can see it + in her face when she comes by the dock. +- Kael says she doesn't know. I don't think that's + true anymore. +- ~~She's fine, Kael takes care of it~~ She talked + to Sera. Commission field tech. Why Sera? +``` + +**About Sera (from observation at the bar):** +``` +SERA + +- Commission field tech. Stationed here a year. +- Drinks at Lera's. Keeps to herself mostly. +- One less Commission presence in the room when + she leaves. Fine by me. +- Naia talks to her. That's new. Or I just + never noticed. +``` + +### 4.5 Contradiction Presentation (Smuggler) + +The smuggler doesn't get contradiction flags. There's no system that says "DISCREPANCY DETECTED." Instead, the smuggler's notebook accumulates notes that contradict each other, and the **monologue** is what connects them. + +#### Visual Treatment +- No special formatting for contradictions +- Old information stays visible but struck through +- New information appears below with question marks +- The contradiction is visible to the player through the juxtaposition -- the system doesn't highlight it + +#### Example Contradiction + +``` +KAEL + +- Shift partner. Two years. Solid. +- ~~Tells me everything. That's how it works.~~ +- Corridor B-7. Someone I don't know. Kael didn't + mention a meeting. + He looked left when I asked. + He always looks left when he's lying. + Who is this person? What's Kael doing? +``` + +No amber border. No "DISCREPANCY FLAGGED." The smuggler notices contradictions the way a person notices them -- the old certainty and the new evidence sit next to each other, and the gap is obvious to anyone reading. The emotional weight does the work, not the formatting. + +#### Monologue on Contradiction Discovery + +> *"Two years. Two years and he's meeting people behind my back. Not ring. Not anyone I know. Who, Kael?"* + +Note: no institutional framing, no analytical distance. The hurt is the analysis. Fragments. First name. Dash for interruption. Voice checks out per smuggler patterns. + +--- + +## 5. Contradiction Presentation: Side-by-Side Comparison + +The same contradiction (Kael in Corridor B-7 with an unknown contact) presented through both lenses: + +### Detective Sees: + +``` +══════════════════════════════════════ + DISCREPANCY FLAGGED — DSC-004 +══════════════════════════════════════ +Entry A: RTN-008 (Davan, K. — routine profile) + "Subject's shift ends 14:00. No registered + maintenance assignments in Corridor B-7." + +Entry B: OBS-019 (Davan, K. — direct observation) + "Subject observed in Corridor B-7 at 22:15. + Unidentified contact present. Contact departed + before visual identification possible." +--- +Assessment: Off-schedule presence in restricted +corridor with unregistered contact. Consistent with +covert operational activity. Priority: elevated. +Cross-ref: Manifest discrepancy #7 (same subject). +══════════════════════════════════════ +``` + +**Monologue:** *"Davan in Corridor B-7. Off-schedule. Unregistered contact. That is not routine."* + +### Smuggler Sees: + +``` +KAEL + +- Corridor B-7. Late. Wasn't on the schedule. +- Talking to someone I don't recognize. They left + before I got close. +- ~~Kael tells me everything~~ + He didn't mention this meeting. He didn't mention + this person. + Who was that? +``` + +**Monologue:** *"That wasn't anyone from our rotation. And Kael didn't tell me about a meeting."* + +### What's Different + +| Dimension | Detective | Smuggler | +|-----------|-----------|----------| +| **Framing** | Evidence entry with ID, timestamp, classification | Personal note under a first name | +| **Subject** | `Davan, K.` | `Kael` | +| **Time** | `22:15` | `Late` | +| **Location** | `Corridor B-7 (restricted, no registered maintenance assignment)` | `Corridor B-7` (no explanation needed -- she knows it's restricted) | +| **Unknown contact** | `Unidentified contact. Contact departed before visual identification possible.` | `Someone I don't recognize. They left before I got close.` | +| **Contradiction source** | Routine profile vs. direct observation (auto-cross-referenced) | Struck-through trust vs. new evidence (manually juxtaposed) | +| **Marker** | `DISCREPANCY FLAGGED` in amber with assessment | Nothing. Question marks. Strikethrough. Silence. | +| **Emotional register** | Professional priority escalation | Personal betrayal crystallizing | +| **Insert involvement** | Full -- insert auto-generates cross-refs, confidence bars, assessment | None -- the smuggler's lattice doesn't do analysis | + +--- + +## 6. THE FRIEND Contradiction Arcs + +THE FRIEND's contradiction (D-034, wow moment #3 from D-039) is the single most important evidence presentation moment in v0.1. The side-by-side comparison in Section 5 shows the *format*. This section shows the *arc* -- how the notebook and case file evolve across the full session as THE FRIEND relationship moves through its phases. + +### 6.1 Smuggler -- Kael's Arc in the Notebook + +**Phase 1: Comfort (minutes 0-10)** + +The notebook is sparse and warm. The smuggler doesn't take many notes about Kael because there's nothing to note. Trust is the default. Absence of entries IS the trust. + +``` +KAEL + +- Shift partner. Two years. Solid. +- Already at the dock when I got here. Good. +``` + +Two entries. No questions. The notebook barely registers Kael because Kael is safe. This baseline matters -- the contrast with what comes later is the emotional payload. + +**Phase 2: First Crack (minutes 10-15)** + +New entries accumulate. The smuggler notices but dismisses. + +``` +KAEL + +- Shift partner. Two years. Solid. +- Already at the dock when I got here. Good. +- Keeps checking his lattice. Third time in five + minutes. Waiting for something? +- Left lunch early. Said he had to check a manifest. + ~~Probably nothing.~~ +``` + +The first strikethrough appears -- but it's the smuggler crossing out *her own dismissal*, not her trust. "Probably nothing" gets struck because the gut is already ahead of the conscious mind. The notebook records the smuggler starting to argue with herself. + +**Phase 3: Contradiction Discovery (minutes 15-20)** + +The notebook breaks open. + +``` +KAEL + +- Shift partner. Two years. ~~Solid.~~ +- Already at the dock when I got here. Good. +- ~~Keeps checking his lattice. Probably nothing.~~ + Not nothing. +- Corridor B-7. Off shift. Talking to someone I + don't recognize. They left before I got close. +- ??? +- Not ring. Not dock crew. Nobody from our rotation. +- He didn't tell me about a meeting. + He didn't tell me. +``` + +Two previous entries get strikethrough -- "Solid" and "Probably nothing." The smuggler's trust assessment is literally crossed out. New entries are shorter, more fragmented. The voice tightens. Question marks appear. The repeated "He didn't tell me" (once as observation, once as emotional statement) is the smuggler processing betrayal in real time. + +**D-033 color shift:** Green `#6bc9a6` fades to amber `#e8c547`. This should be the first entity color change in the entire session -- maximum impact per D-033 design notes. + +**Monologue fires with urgent chime:** *"That's Kael. But who's he talking to? I don't know that face."* + +**Phase 4: Confrontation Window (minutes 20-25)** + +If the smuggler confronts Kael, the notebook records the intention and result: + +``` +KAEL (continued) + +- *I saw you in B-7. Who was that?* +- He said "Just a thing. Don't worry about it." + He looked left. + He always looks left when he's making something up. + Two years I've known that tell. + Kael is lying to me. +``` + +The italicized entry is the confrontation line (D-063 format). What follows is the smuggler's observation of Kael's response. The tell system (D-034) surfaces here -- the "looks left" tell that the smuggler has known for two years is now weaponized against a friend. The final line is a flat declarative -- when the smuggler is hurt, fragments stop and sentences land whole (per voice card Anchor 4). + +**Phase 5: Contaminated Trust (minutes 25-30)** + +Every subsequent Kael entry carries a parenthetical shadow: + +``` +KAEL (continued) + +- Back at the dock. Same jokes, same routine. + (B-7. The face I didn't recognize.) +- Offered to cover my break. + (Too nice? Or just Kael being Kael?) +- Checked his lattice again. Once. Normal? + (What's normal anymore?) +``` + +The parenthetical voice is the contamination. Every warm observation now gets a cold follow-up in brackets. The notebook can't be trusted anymore because the person in it can't be trusted. The smuggler is maintaining two simultaneous readings of Kael -- the friend she wants to believe in and the liar she can't ignore. + +### 6.2 Detective -- Sera's Arc in the Case File + +**Phase 1: Trust (minutes 0-10)** + +The case file has a single entry for Sera, filed as "background resource." The detective doesn't investigate allies. + +``` +SUBJECT: Venn, S. +ROLE: Commission Field Technician +ASSESSMENT: Reliable institutional contact +STATUS: Active — background resource + + ENTRY 1: + OBSERVATION: District orientation briefing. Subject provided + social mapping of bar regulars and hub personnel. + SOURCE: Direct conversation + CONFIDENCE: ████████ Direct +``` + +Clean. Professional. Sera is cataloged as a tool, not a target. "Background resource" -- the detective's way of saying "friend" without saying "friend." + +**Phase 2: Background Data (minutes 10-15)** + +New entries accumulate. Sera mentions Naia. The detective files it. + +``` + ENTRY 2: + OBSERVATION: Subject identified Tamm, N. as personal acquaintance. + Introduced during bar visit. Rapport appears genuine. + SOURCE: Direct observation (in conversation) + CONFIDENCE: ████░░░░ Noted Facts + + ENTRY 3: + OBSERVATION: Departed Last Shift early. Stated reason: early shift. + TIMESTAMP: Cycle 12, 21:15 + SOURCE: Direct observation + CONFIDENCE: ████████ Direct +``` + +The departure is logged but not flagged. One data point is not a pattern. The insert files it without priority. This entry becomes retroactively significant after Phase 3 -- the insert will add CORRELATION fields when the pattern is detected. + +**Phase 3: Contradiction Discovery (minutes 15-20)** + +The case file transforms. + +``` +SUBJECT: Venn, S. +ASSESSMENT: !! UNDER REVIEW !! +STATUS: Active — person of interest + + !! DISCREPANCY FLAGGED — DSC-002 !! + + ENTRY 3 (amended): + OBSERVATION: Departed Last Shift. Reason: early shift. + TIMESTAMP: Cycle 12, 21:15 + CORRELATION: Lintar, T. arrived 21:12 [auto-detected] + + ENTRY 4: + OBSERVATION: Departed Last Shift. Reason: headache. + TIMESTAMP: Cycle 13, 20:40 + CORRELATION: Lintar, T. arrived 20:37 [auto-detected] + + ENTRY 5: + OBSERVATION: Departed Last Shift. Reason: kiosk check. + TIMESTAMP: Cycle 14, 21:05 + CORRELATION: Lintar, T. arrived 21:01 [auto-detected] + + CONFLICT: 3 departures correlated with arrival of Lintar, T. + 3 distinct stated reasons. Pattern inconsistent + with coincidence. + ACTION: Investigate relationship Venn-Lintar. + Cross-ref Lintar associations. +``` + +Key differences from the smuggler's experience: + +1. **ASSESSMENT changes** -- "Reliable institutional contact" becomes "!! UNDER REVIEW !!" The detective's institutional framework overwrites the personal assessment. The friend becomes a subject. +2. **CORRELATION fields auto-populate** -- The analytical lattice retroactively adds timing data to previous entries. Entry 3 gains "[auto-detected]" correlation. The insert is doing work the detective didn't ask for -- and that's a capability the smuggler doesn't have. +3. **Probability language** -- "Pattern inconsistent with coincidence." The detective processes a friend's avoidance pattern through statistical analysis. + +**D-033 color shift:** Green `#6bc9a6` fades to amber `#e8c547`. Same timing as the smuggler's FRIEND shift. + +**Monologue fires with urgent chime:** *"That's the third time. Sera leaves when Torek arrives. Three different excuses, same result. That's not coincidence."* + +**Phase 4: The Question (minutes 20-25)** + +The detective's confrontation option is institutional: + +``` + ACTION: Direct inquiry — Venn, S. + Topic: relationship to Lintar, T. + Approach: authority access (institutional leverage) +``` + +In the dialogue UI (D-063), the confrontation option is in the detective's internal voice: *"I've noticed a pattern, Sera. Three times Torek walks in, you walk out."* + +The gap between the case file's clinical "Direct inquiry" and the monologue's personal "Sera" is where the detective's internal conflict lives. The case file doesn't use first names. The monologue does. That shift IS the crack in the professional surface. + +**Phase 5: Contaminated Trust (minutes 25-30)** + +The case file continues with clinical precision, but NOTE fields start carrying analytical doubt: + +``` + ENTRY 6: + OBSERVATION: Subject offered extended district briefing. + Volunteered information on Korr, M. without prompt. + TIMESTAMP: Cycle 14, 22:10 + SOURCE: Direct conversation + CONFIDENCE: ████████ Direct + NOTE: Disclosure rate increased post-Cycle 14 encounter. + Possible compensation behavior. Pattern consistent + with concealment + overcorrection. +``` + +"Possible compensation behavior" -- the detective's analytical training turns Sera's friendliness into data. Every helpful gesture is now flagged as potential overcorrection. The case file remains clinical. But the NOTE field reveals a professional mind processing a personal hurt through the only framework it has. + +### 6.3 Non-Confrontation and Resolution States + +**If the player doesn't confront:** The notebook/case file stays frozen at Phase 3. The smuggler's question marks remain unanswered; the detective's `!! UNDER REVIEW !!` and `ACTION: Recommend direct inquiry` persist indefinitely. Phase 5 (contaminated trust) still applies — the parenthetical shadows (smuggler) and analytical doubt NOTEs (detective) accumulate regardless. Avoidance is a valid player choice, and the evidence presentation should reflect it as unresolved tension, not a failure state. + +**Post-confrontation resolution:** v0.1 ends at contamination. The 30-minute session is unlikely to reach clean resolution, and D-034 deliberately avoids providing one. Evidence presentation for resolution states (detective `RESOLVED` status, smuggler warm re-annotation) is a v0.2 consideration. + +### 6.4 The Monologue-Presentation Gap + +**This is the most important authoring principle in the evidence presentation spec.** + +The evidence presentation (case file / notebook) and the monologue (D-032) serve different narrative functions. The presentation is the *record*. The monologue is the *reaction*. The gap between them is where the character lives. + +- The detective's case file says "DISCREPANCY FLAGGED." The monologue says: *"Sera, what do you know?"* +- The smuggler's notebook says "???" The monologue says: *"Two years I've known that tell. Kael is lying to me."* + +Never duplicate the monologue's emotional content in the evidence presentation. Never duplicate the evidence presentation's factual content in the monologue. They are complementary layers, not redundant channels. + +The evidence presentation is what the character *documents*. +The monologue is what the character *feels*. +The player holds both simultaneously. That's the game. + +### 6.5 Asymmetric Storytelling: What Sustains the Difference + +The honest truth is that the presentation layer difference isn't cosmetic. It changes what story the player tells themselves across the full 30-minute session. + +**The detective's story:** "I'm building a case. Evidence accumulates. Patterns emerge. The insert helps me see connections. When the case file flags a discrepancy, my investigation advances. The challenge is: do I follow the evidence even when it points at my friend?" + +The detective's presentation *empowers*. The insert is a tool. Cross-references are assistance. Discrepancy flags are the system working as intended. The detective has an analytical partner -- and that partner doesn't care about friendship. + +**The smuggler's story:** "I'm watching my world crack. People I trust are doing things I don't understand. My notebook fills up with crossed-out certainties and unanswered questions. I don't have an insert telling me what's connected -- I have to figure it out myself. The challenge is: what do I do with what I know?" + +The smuggler's presentation *isolates*. No automated connections. No confidence labels. No flags. Just a notebook full of personal observations and the growing realization that the people you trusted are not who you thought they were. The cognitive load is the player's. That's the point. + +This asymmetry is load-bearing for D-027 success criterion #2: "both playthroughs feel like fundamentally different games." The evidence presentation is one of the primary mechanisms by which the same knowledge graph produces two fundamentally different emotional experiences. + +--- + +## 7. UI Copy Reference + +### 7.1 Grid Labels + +When the player hovers over a filled inventory slot: + +**Detective:** +> `[1] Commission Datapad` +> `[2] Commission Badge` + +**Smuggler:** +> `[1] Manifest Copy` +> `[2] Access Token` +> `[3] Comm Log` + +Labels are plain text, left-aligned below the slot icon. Detective labels are formal (full institutional name). Smuggler labels are practical (what the thing is, not what it's called on a form). + +### 7.2 Empty Grid Behavior + +Per D-065: no empty slots displayed. Icons appear only when items are carried. Hovering over empty space produces no tooltip. The grid doesn't announce its own capacity. + +### 7.3 Tooltip Format + +Tooltips appear on hover, persist for 2 seconds or until cursor moves. + +**Detective tooltips** are structured: +> `Field datapad. Case #STC-4471. Synced.` +> `Commission credentials. Authority access.` + +Complete information in compressed form. The insert summarizes. + +**Smuggler tooltips** are personal: +> `Last cycle's manifest. Kael's notes.` +> `Corridor B-7. Kael's spare.` +> `Three months. All of it.` + +Fragments. Context a stranger wouldn't understand. Because the smuggler isn't explaining things to a stranger. + +### 7.4 Examine Action Copy + +When the player examines an item (verb: Examine Object on inventory item): + +**Detective examines Commission Datapad:** +> *"Case file's current. Fourteen flagged entries. Let's see which ones hold up in person."* + +**Smuggler examines Manifest Copy:** +> *"Kael's handwriting. Forty kilos over on three containers. He corrected the numbers but never filed the update. Sloppy? Or on purpose?"* + +Both fire as monologue lines (character tint, same display constraints as D-016). Max 160 characters, 2 visual lines, 4-6 second display. + +### 7.5 Take/Place Verb Copy (v0.2+) + +> **Note:** Take/Place verbs are not in the v0.1 verb system (7 verbs: Move, Look, Examine Object, Examine NPC, Talk, Overhear, Monologue). This copy is forward-looking for when physical item interaction verbs are added. + +When the player takes or places a physical item: + +**Detective:** +> Take: `Evidence secured.` +> Place: `Evidence placed. Location logged.` + +**Smuggler:** +> Take: `Got it.` +> Place: `Should be safe here. Should be.` + +Detective's take/place text is procedural. Smuggler's is personal and hedged. + +### 7.6 Confrontation Labels + +When an inventory item can be used in confrontation (D-063), the dialogue option is written in character voice: + +**Detective using datapad evidence against Voss:** +> *"These manifests do not reconcile, Supervisor. Three containers, three discrepancies. Your shift window."* + +**Smuggler using manifest copy against Kael:** +> *"I've got the manifest, Kael. Your handwriting. Forty kilos you never filed."* + +Both are italicized, first-person (per D-063 confrontation styling). Detective: uncontracted, formal address ("Supervisor"), evidence-chain structure. Smuggler: contracted, first name, direct. + +--- + +## 8. Evidence Discovery Flow + +How evidence feels when the player first encounters it, per archetype. + +### 8.1 Detective Discovery + +1. **Observation triggers insert flag.** The insert does the initial work -- pattern recognition, anomaly detection, confidence thresholds. A soft amber pulse in the insert overlay signals new evidence. +2. **Case file entry auto-generates.** The evidence entry appears in the KG view, pre-formatted, with cross-references the insert has already computed. +3. **Monologue confirms.** The detective's internal voice contextualizes: *"That's data."* or *"Flag it."* or *"Worth a second look."* +4. **Contradiction, if present, is flagged explicitly.** `DISCREPANCY FLAGGED` appears immediately. The insert does not wait for the detective to notice -- it highlights. + +**Emotional arc of detective discovery:** Curiosity (new data) -> Classification (insert files it) -> Connection (cross-reference to existing case) -> Determination (next investigative step). + +The detective's evidence discovery is **assisted**. The insert is a partner. The cognitive load is managed. The detective's job is interpretation, not organization. + +### 8.2 Smuggler Discovery + +1. **Observation triggers gut reaction.** No insert flag. No pattern recognition software. The smuggler sees something wrong and feels it before naming it. +2. **No auto-filing. The notebook is curated, not auto-populated.** Entries appear in the notebook only when (a) a monologue fires for significant observations, or (b) the player actively examines something. The KG may contain facts the notebook doesn't show — the smuggler writes things down when they hit her, not when the system updates. This is a deliberate design choice: the notebook feels authored by the character, not generated by the engine. +3. **Monologue is the discovery.** The monologue line IS the moment of evidence discovery. *"That wasn't anyone from our rotation."* There's no separate system confirmation. +4. **Contradiction is not flagged.** Old notes stay. New notes accumulate. The player sees the gap. The smuggler's monologue might name it: *"He didn't tell me."* But the notebook itself doesn't highlight. + +**Emotional arc of smuggler discovery:** Unease (something's wrong) -> Observation (what exactly?) -> Personal cost (this involves someone I trust) -> Question (what do I do with this?). + +The smuggler's evidence discovery is **unassisted**. No analytical tools. No cross-references. The smuggler relies on memory, instinct, and the relationships that are now under strain. The cognitive load is the player's. That's the point. + +--- + +## 9. Visual Direction Summary (For Araminta) + +### Detective Case File + +- **Sprite style:** Clean, geometric, insert-aesthetic. Thin lines, precise spacing. +- **Palette:** Cool white-blue `#c8d0e0` primary, amber `#e8c547` for flags, red `#d45d5d` for confirmed contradictions, green `#6bc9a6` for corroborated. +- **Text treatment:** Monospaced labels. Structured fields. Fill bars for confidence. Auto-generated cross-reference links (subtle underlines). +- **Item sprites:** Institutional objects. Clean surfaces. Commission branding (geometric insignia). No personal marks, no wear. +- **Contradiction marker:** Double-line amber border. `DISCREPANCY FLAGGED` header. Side-by-side entry comparison. + +### Smuggler Notebook + +- **Sprite style:** Warm, personal, slightly rough. Variable spacing, handwritten feel. +- **Palette:** Warm amber-cream `#f0e0c8` primary, muted grey `#8b8ba0` for struck-through text. No color-coded flags. +- **Text treatment:** Variable-width typeface. Left-aligned, irregular. Strikethroughs visible. Question marks as emphasis. No structured fields. +- **Item sprites:** Worn objects. Creased paper. Scuffed surfaces. Things that live in pockets and get handled. Personal. +- **Contradiction marker:** None. Strikethrough on old certainty. New observations below. The gap speaks for itself. + +--- + +## 10. Cross-References + +| Decision | Relevance | +|----------|-----------| +| D-065 | Inventory mechanics: 3x3 grid, capacity per archetype, knowledge-primary, physical items as exception | +| D-034 | THE FRIEND: contradiction discovery is the emotional payload both presentations must serve | +| D-033 | Entity color as relationship: contradiction markers use the same color language | +| D-028 | Dialogue architecture: confrontation options use evidence as leverage | +| D-032 | Separate monologue pools: evidence discovery monologue is character-specific | +| D-016 | Monologue system: evidence monologue follows all display constraints | +| D-048 | Insert overlay: detective case file renders on insert layer (z-layer 6) | +| D-013 | Diegetic UI: both presentations are in-world, not game-UI | +| D-063 | Confrontation: inventory items usable as evidence, same dialogue box, different weight | + +--- + +## 11. Contradiction Detection Pipeline (Mechanical Detail) + +The narrative presentation in Sections 3.5, 4.5, and 5 defines *what the player sees*. This section defines *how that happens mechanically*, tracing the full pipeline from knowledge graph state change through to evidence presentation update. + +### 11.1 Pipeline Steps + +``` +Step 1: Server — Knowledge Graph Contradiction Detection (D-041) + Input: ToldBy entry ("Kael said he was at the dock during shift 2") + + DirectObservation entry ("Player sees Kael in Corridor B-7 during shift 2") + Output: Both entries receive KnowledgeState::Contradicted + Timing: Same tick the DirectObservation is created + +Step 2: Server — Event Emission + ContradictionDetected { + subject: StableId, // Kael's stable entity ID + entry_a: KnowledgeKey, // The ToldBy entry + entry_b: KnowledgeKey, // The DirectObservation entry + tick: u64 // When detected + } + Side effects: + - RelationshipState shift (Friendly -> PersonOfInterest) + - FriendArc phase advance (if applicable) + - Monologue event queued (observe_anomaly, priority 1) + +Step 3: Server — ObserverSnapshot Update + - KG entries marked Contradicted included in snapshot + - Entity RelationshipState updated -> D-033 color derivation changes + - Monologue event included in snapshot.monologue field + - Verb set updated: Confront becomes available at KnowsDetails+ + +Step 4: Client — Receives ObserverSnapshot + 4a: Entity color transitions (D-033, 0.5s fade, green -> amber) + 4b: Monologue fires (urgent chime, character-specific pool) + 4c: Evidence presentation updates on next inventory open +``` + +### 11.2 Six Atomic State Changes at THE FRIEND Contradiction + +When THE FRIEND contradiction fires (D-034, wow moment #3), six state changes happen in rapid succession. All are mechanically coupled: + +| # | State Change | Where | What Changes | +|---|-------------|-------|--------------| +| 1 | KG entries receive `Contradicted` state | Server (KG component) | Source of truth updated | +| 2 | `FriendArc` phase advances | Server (FriendArc component) | Trust/Doubt -> Conflict | +| 3 | `RelationshipState` shifts | Server (Relationship component) | Friendly -> PersonOfInterest | +| 4 | Monologue event queued | Server (MonologueQueue) | `observe_anomaly` trigger, priority 1 (highest), urgent chime | +| 5 | Entity color shifts | Client (sprite rendering) | Green `#6bc9a6` -> amber `#e8c547`, 0.5s fade | +| 6 | Evidence entry gains contradiction marker | Client (evidence panel) | Detective: `DISCREPANCY FLAGGED`. Smuggler: strikethrough + doubt annotation. | + +**Timing:** Changes 1-4 are server-side, same tick. Changes 5-6 are client-side, triggered by the next ObserverSnapshot. Change 5 (color shift) is visible immediately. Change 6 (evidence marker) is visible when the player next opens their inventory. The monologue chime (change 4) is the player's first signal -- before they see the color shift, before they check their evidence. + +### 11.3 Verb Unlocks at Contradiction + +| Pre-contradiction | Post-contradiction | +|-------------------|--------------------| +| **Detective on Kael:** `[E] Observe` (mid-range) / `[E] Talk` (close range) | `[E] Observe` (priority rises above Talk for PersonOfInterest per interaction-verbs spec Section 4). `Confront` available in dialogue if KnowsDetails+ reached. | +| **Smuggler on Kael:** `[E] Talk` (close range, insider/peer warmth) | `[E] Observe` (priority rises above Talk for PersonOfInterest per interaction-verbs spec Section 4 — smuggler shifts from trust to suspicion). `Confront` available in dialogue: *"I saw you in corridor B-7"* (D-063 confrontation format, italicized first-person). | + +Note the asymmetry: both archetypes shift from `[E] Talk` to `[E] Observe` post-contradiction (per interaction-verbs spec Section 4). But the *meaning* of Observe differs. The detective enters surveillance mode — clinical distance, gathering more data. The smuggler enters suspicion mode — watching a friend for signs of betrayal. Same verb, same priority shift, different emotional frame. The further asymmetry: the smuggler's insider/peer dialogue lines lock out (only public/surface remain), while the detective's authority access opens new lines. Same mechanical trigger, different access consequences. + +--- + +## 12. Systems Interaction Map + +Evidence presentation is not an isolated system. It connects to every major pillar. This map shows how evidence presentation reads from and writes to other systems: + +``` + +-------------------+ + | KNOWLEDGE GRAPH | + | (D-041) | + | Source of truth | + +--------+----------+ + | + +--------------+--------------+ + | | + +--------v---------+ +---------v--------+ + | CONTRADICTION | | CONFIDENCE | + | DETECTION | | LEVELS | + | ToldBy vs Direct | | Suspects -> | + | | | KnowsDetails | + +--------+---------+ +--------+---------+ + | | + +-------------+-------------+ + | + +--------v---------+ + | EVIDENCE | + | PRESENTATION | + | (this spec) | + +--------+---------+ + | + +------------------+------------------+ + | | | ++--------v------+ +--------v------+ +--------v------+ +| ENTITY COLOR | | MONOLOGUE | | DIALOGUE | +| (D-033) | | (D-032) | | (D-028) | +| Visual thread | | Emotional | | Confrontation | +| world <-> inv | | processing | | unlocks | ++--------+------+ +-------+-------+ +-------+-------+ + | | | + +-----------------+-------------------+ + | + +--------v---------+ + | VERB SYSTEM | + | (D-057) | + | Scan vs Grab | + | Flag vs Pocket | + | Confront unlock | + +------------------+ +``` + +### 12.1 Interaction Details + +| System | Reads From Evidence | Writes To Evidence | +|--------|--------------------|--------------------| +| **Knowledge Graph** (D-041) | -- | KG entries ARE evidence. Every fact, observation, and relationship state in the KG is potential evidence content. | +| **Contradiction Detection** (D-041) | -- | `Contradicted` state on KG entries triggers archetype-specific contradiction markers. | +| **Entity Color** (D-033) | Detective case file shows D-033 color dots for referenced entities. | -- | +| **Monologue** (D-032) | Monologue lines reference evidence content ("Kael's handwriting. Forty kilos over."). | Evidence discovery triggers `discover_evidence` monologue (priority 3). Contradiction triggers `observe_anomaly` (priority 1). | +| **Dialogue** (D-028) | Confrontation options cite evidence. Evidence at `KnowsDetails`+ unlocks `secret`-tier dialogue. | Dialogue can grant new KG entries (which become evidence). | +| **Verb System** (D-057) | `Confront` verb availability depends on evidence confidence level. | Acquisition verbs (Scan/Grab/Flag/Pocket) create new evidence entries. | +| **Fog of Perception** (D-011) | -- | Evidence can only be discovered through observation within LOS. Physical evidence objects must be in the vision cone. | +| **Insert Overlay** (D-048) | Detective case file renders on z-layer 6 (insert layer). | -- | + +### 12.2 Feedback Loops + +Two feedback loops make evidence presentation mechanically interesting: + +**Loop 1: Evidence -> Confrontation -> New Evidence** +``` +Observe anomaly -> Evidence entry created -> Confront verb unlocks -> +Confrontation dialogue reveals new information -> New evidence entry -> +NPC behavior changes -> New observations -> More evidence +``` +This loop drives the investigation forward. Each piece of evidence opens doors to more evidence. The rate of loop iteration differs per archetype: the detective's insert cross-references accelerate the loop; the smuggler's unassisted observation slows it but makes each discovery feel more personal. + +**Loop 2: Evidence -> Relationship Shift -> Dialogue Change -> Evidence Quality** +``` +Contradiction discovered -> RelationshipState shifts -> +Access tier changes (insider locks out OR authority unlocks) -> +Available dialogue lines change -> Information quality changes -> +Evidence entries reflect new relationship context +``` +This loop makes relationships mechanically load-bearing. Burning a relationship (confrontation) changes what information is available. The detective's `authority` tier can unlock new lines but NPC cooperation decreases. The smuggler's `insider` tier locks out entirely post-contradiction. Evidence quality is gated by social state. + +--- + +## 13. Fun Factor Analysis + +*Does this create interesting player decisions? Let me break down what this actually means mechanically.* + +### 13.1 Decision Points Created by Archetype Divergence + +| Decision | Detective Experience | Smuggler Experience | Why This Is Interesting | +|----------|---------------------|---------------------|-------------------------| +| **"Should I investigate this?"** | Confidence meter says "Unconfirmed." Wait for corroboration or act now? | Gut says something's wrong. No confidence meter. Trust the feeling or ignore it? | Different information about their own information. The detective knows the strength of their evidence. The smuggler doesn't. | +| **"Should I confront?"** | Case file has structured evidence + cross-references. Risk: burning an institutional source. | Notebook has a scrawled note and a crossed-out entry. Risk: losing a friend. | Same mechanical action (Confront verb), wildly different risk calculus. | +| **"Should I pick this up?"** | Scan/Flag = KG entry, no physical risk. Clean. Institutional. | Grab/Pocket = physical item, detectable by security. If caught, smuggler is implicated. | Physical evidence carries genuine mechanical risk (detection, confiscation). KG evidence does not. The smuggler's evidence loop has stakes the detective's doesn't. | +| **"What does this evidence mean?"** | Insert suggests cross-references. Patterns highlighted. The system helps. | No cross-references. The smuggler connects dots manually. The player IS the detective. | Different cognitive load on the player. Detective players are guided. Smuggler players are on their own. | + +### 13.2 Emergent Interactions + +The best moments will come from systems colliding. These are the interactions the design didn't explicitly plan but the mechanical rules produce: + +1. **Evidence accumulation as narrative.** The detective opens the case file and sees three amber dots where there used to be one. The investigation is widening. The *density* of evidence entries is itself a story -- this community is being documented, cataloged, reduced to data. The detective may feel the institutional weight of their own methodology. + +2. **Physical evidence + confrontation risk.** The smuggler confronts Kael while carrying the manifest copy. Showing it means admitting she took it. The *possession* of evidence is itself an incriminating act. The smuggler's evidence is double-edged in a way the detective's KG entries never are. + +3. **Notebook as emotional timeline.** The smuggler re-reads an early notebook entry about Kael -- warm, casual, trusting. Below it: the strikethrough and "??" annotation she wrote 10 minutes ago. The contrast between past-self and present-self is visible in her own handwriting. The *notebook remembers who she used to be.* + +4. **Entity color accumulation in case file.** As the detective investigates, amber dots accumulate across case file entries. Each individual entry is clinical and controlled. But the *pattern of amber* across the full case file tells a story the detective didn't write -- suspicion is spreading, and the evidence trail is converging on people who were initially neutral. + +### 13.3 Why This Isn't Just Cosmetic + +If both archetypes saw the same evidence presentation, players would make the same decisions. The presentation layer creates genuinely different decision contexts: + +- The detective is **guided by systems.** Cross-references, confidence levels, color-coded entity dots -- the institutional apparatus helps. The interesting decision: *do I trust the system, or trust the people it's flagging?* +- The smuggler is **guided by relationships.** First names, personal annotations, gut feelings -- the emotional connection provides context. The interesting decision: *do I trust my people, or trust what my eyes are telling me?* + +Same knowledge graph. Same facts. Different frames. Different decisions. Different games. That's not cosmetic -- that's a system creating divergent player behavior from identical underlying data. + +--- + +## 14. Implementation Notes + +### 14.1 Client-Side Rendering (No Server Logic Required) + +All presentation differences are client-side: + +| Responsibility | Server | Client | +|---------------|--------|--------| +| Knowledge graph storage | Yes | No | +| Contradiction detection | Yes | No | +| Confidence level tracking | Yes | No | +| ObserverSnapshot generation | Yes | No | +| Archetype-specific labels | No | Yes -- loads from YAML dictionary | +| Archetype-specific layout | No | Yes -- case file template vs notebook template | +| D-033 color dots in evidence | No | Yes -- reads color from snapshot, renders per archetype rules | +| Strikethrough/doubt annotations | No | Yes -- applies when contradicted entries detected | + +### 14.2 Content File Structure + +Evidence presentation copy lives in client data alongside UI strings (D-042 pattern: YAML via GDScript autoload): + +``` +client/data/ + evidence-labels-detective.yaml # Formal labels, tooltips + evidence-labels-smuggler.yaml # Informal labels, tooltips + evidence-descriptions-detective.yaml # Case file entry templates + evidence-descriptions-smuggler.yaml # Notebook entry text + evidence-verbs-detective.yaml # Archetype-specific verb labels (Scan, Flag, etc.) + evidence-verbs-smuggler.yaml # Archetype-specific verb labels (Grab, Pocket, etc.) +``` + +Each file is keyed by `item_id` and loaded at session start. The client reads the archetype from the player character's component and loads the appropriate dictionary set. + +### 14.3 Minimal Implementation Path (v0.1) + +For v0.1, evidence presentation can be implemented with: + +1. **Inventory icons:** 3-6 static sprites per archetype (40x40px per D-065). Total: ~12 sprites. +2. **Item inspection panel:** Reuse dialogue box space (bottom 20% per D-061). Switch layout template (case file vs notebook) based on archetype. One scene, two layout scripts. +3. **Contradiction markers:** Boolean flag from KG `Contradicted` state -> archetype-specific visual treatment (banner vs strikethrough). Trivial conditional rendering. +4. **Label/description text:** YAML lookup keyed by `item_id` + archetype. Same pattern as D-042 UI strings. +5. **D-033 color dots:** Detective only. Read D-033 color from ObserverSnapshot, render as small circle in case file entries. ~5 lines of GDScript per entry. +6. **Confidence bars:** Detective only. Map `ConfidenceLevel` enum to fill bar width. 4 values, 4 bar states. + +**No new server-side systems required.** The evidence presentation is entirely a client rendering concern over existing server data (KG entries, RelationshipState, ConfidenceLevel, Contradicted state). The verb differences (Scan vs Grab) are Phase 2 observer filter rules already designed in D-057. + +**Estimated effort:** 1-2 sprints for basic implementation. Icons and layout are the bulk. The data flow already exists. + +--- + +## 15. Authoring Guidelines + +### 15.1 Writing Item Descriptions + +**Smuggler items:** Write in first person. Use the smuggler voice card parameters (short fragments, sensory vocabulary, first names, feeling-first). The description should sound like the smuggler looking at the item and commenting to herself. + +- **Do:** "Kael's handwriting on the margins." +- **Don't:** "Manifest containing annotations by dock worker Davan." + +**Detective items:** Write in third person passive. Use institutional vocabulary. The description should sound like a field report entry. + +- **Do:** "Margin annotations in hand consistent with dock worker Davan, K." +- **Don't:** "Kael wrote on this." + +### 15.2 Writing Contradiction Markers + +**Smuggler contradictions:** Show the smuggler arguing with herself. Use strikethrough for revised beliefs. Use question marks for unresolved uncertainty. Keep fragments short -- the voice tightens under stress. + +- The struck-through text is what the smuggler *used to believe*. +- The new text is what the smuggler *can't deny*. +- The question marks are the gap between the two. + +**Detective contradictions:** Show the system flagging the discrepancy. Use institutional language. Let the clinical precision carry the emotional weight by contrast with the monologue. + +- The DISCREPANCY FLAGGED label is what the insert reports. +- The CONFLICT summary is what the analytical training concludes. +- The monologue is where the detective *feels* it. + +### 15.3 The Monologue-Presentation Rule + +Restated from Section 6.4 for emphasis -- this is the authoring rule that content writers must internalize: + +1. **Never duplicate the monologue's emotional content in the evidence presentation.** The case file says "DISCREPANCY FLAGGED." The monologue says *"Sera, what do you know?"* These are not the same information. +2. **Never duplicate the evidence presentation's factual content in the monologue.** The notebook says "Corridor B-7. Off shift." The monologue says *"That wasn't anyone from our rotation."* The notebook documents; the monologue interprets. +3. **The gap between the two layers IS the character.** The detective's case file is precise where her monologue is personal. The smuggler's notebook is uncertain where her monologue is certain. The contradiction between layers is how the player reads the character's psychology. + +### 15.4 Checklist Before Submitting Evidence Content + +1. **Voice check:** Does the detective text use surnames? Does the smuggler text use first names? +2. **Diegetic check:** Does the text sound like something the character would write/file, or does it sound like game UI? +3. **Dual-lens check:** If the other character could see this item, would the description still make sense? (It shouldn't -- that's the point.) +4. **Monologue gap check:** Does the evidence entry duplicate anything the monologue already says? If yes, cut one. +5. **Contradiction check:** If this entry contradicts a previous one, is the contradiction presented in the character's style (strikethrough for smuggler, DISCREPANCY FLAGGED for detective)? + +--- + +## 16. Open Questions + +- **Q: Detective evidence view -- separate screen or overlay?** The case file could render as a full-screen overlay (pause + review) or as insert data layered on the game view. Full-screen is easier to read; overlay maintains the diegetic frame. Recommend: start with full-screen, test overlay in playtesting. +- **Q: Smuggler notebook -- scrollable or paginated?** As the notebook accumulates entries, does the player scroll through a continuous page or flip between person-pages? Recommend: person-pages (tab per name), since the smuggler organizes by relationship. This also reinforces the person-first framing mechanically. +- **~~Q: Strikethrough timing~~ RESOLVED:** Strikethrough appears in real-time when the monologue fires, not on next notebook open. D-034's wow moment #3 requires everything hitting at once: D-033 color shift + monologue + evidence contamination. Delaying the strikethrough splits the impact. The Phase 3 examples in Section 6 are authoritative. +- **Q: Cross-reference density for detective case file?** The insert can auto-generate cross-references, but too many links could create information overload. Recommend: max 3 cross-references per entry, prioritized by confidence level. Playtest to calibrate. +- **Q: Evidence-based confrontation -- show the item?** When the detective confronts using datapad evidence, does the item icon appear in the dialogue? When the smuggler confronts with the manifest, does it show? Recommend: yes for smuggler (physical object, makes the risk visible), no for detective (KG reference, the knowledge IS the weapon). This reinforces the physical vs informational asymmetry. + +--- + +**End Archetype Evidence Presentation Spec**