gupi-osint-board/docs/narrative-todo.md

# Narrative layer: campaigns, NPC cutscenes, and authoring

This roadmap covers the narrative layer end to end: the **campaign** that chains
levels into a mystery, the **NPCs / poses / cutscenes** the player watches
between levels, and the **admin authoring panel** that lets a game designer build
all of it in-app. Work generally proceeds top to bottom.

**Design intent.** These mysteries are real-world scam cases that must actually be
investigated to be understood. Such cases cannot be simplified, they 
can only be staged for didactic discovery into levels.

The LLM is not a decoration on the cutscenes — it
is a **cognitive shim**: the assistant that keeps a player oriented as case
complexity grows. A player can use this feature many times, but some very bright
players might get it right on the first go. 
This is what lets a mystery be as intricate as the real case
demands without the player getting lost. The scripted narrative layer below is the
delivery channel and the fallback; the LLM is the layer that scales comprehension.
Section 9 is deferred in build order but primary in intent, so the model is shaped
now to accommodate it (the `generated` step kind, the read-only context contract,
and the authored case model).

## Working agreement

- All narrative content — campaigns, NPCs, poses, cutscenes, dialogue text — is
  authored template data frozen through supported operations. None of it is
  hard-coded into React components or SQL seed literals. The exception to this rule is 
  custom cutscenes (react components) which are registered as components and referenced by the node.
- The admin panel is a GUI over the **same** operations available to the manifest
  importer; both paths freeze the same immutable template data.
- A cutscene never mutates a board. The professor's scene *narrates* the new
  document and goal; those exhibits and the updated brief already live in the
  next chapter's template.
- A narrative behavior is complete only when its PostgreSQL representation, API
  behavior, frontend presentation, persistence, and focused tests agree.
- Pose portraits are immutable shared bytes, stored and cloned exactly like
  document image assets (MinIO + `objectStorage`); scenes reference assets, they
  never duplicate them.

## First vertical slice: "The Glass Harbour Diversion"

Build the smallest end-to-end narrative loop before generalizing. Ship these in
order; each is playable on its own.

- [ ] Add the **splash screen** — "PRINCIPAL INVESTIGATOR", Glitch University —
  with a single **New Game** action that creates a playthrough and launches the
  first scene (sections 1, 6, 7).
- [ ] Create a mystery named **The Glass Harbour Diversion** as a one-chapter
  campaign wrapping the existing Glass Harbor level template (sections 1–2).
- [ ] Add a **briefing NPC** (the Glitch University professor) and a
  `mystery_intro` cutscene that briefs the player, using at least two poses to
  prove pose-per-utterance (sections 2–3, 7).
- [ ] Wire the briefing to play once on load and mark itself seen, then reveal the
  first level's board (sections 1, 6, 7).
- [ ] Author **two `level_debrief` end-scenes** the player reaches by reporting
  back: one that **sends them back to the board** and one that **concludes the
  mystery**. Model these as two end-of-scene outcomes (buttons), not branching.
- [ ] Leave the back-to-board scene as **scripted** for now, but author it as a
  `generated`-ready step (section 9) so the professor's hint can later be produced
  from the player's Case Report explanation.

## 1. Campaign / progression backbone

- [ ] Define a **cutscene** node as something a) references a custom react component. 
  That react can use potential **utterances** such that for example, it can play 
  an ordered sequence utterance that brief the player: `(speaker NPC, pose, text)`. 
  A node can be marked has_utterances which permits the admin user to add utterances in order.
  [ ] A dialogue is another type of node that invokes the standard NPC dialogue component. This
  has utterances, and consist of a graph where utterances either are spoken by the NPC or available for selection.
  Example :  if the NPC utters "Are you ready?" this has two child utterances marked "player" which could be "yes" and no. The user may select these. "No" could in principle point back to the same utterance and "yes" to the next. If an utterance has a non NULL terminal id, then the game advances to the node pointed to by that terminal. Available terminals are only those who have the current dialogue node as it parent.
- [ ] There exists "det_gate" nodes and "llm_gate" nodes. We begin with the deterministic gate only. The end result of a level is sent to a "det_gate". The det gate can inspect the output of the level and determine if the story should advance through one of its terminals. For now, the det-gate always returns the happy path terminal leading to the mystery being solved.

## 2. NPC and pose catalog

- [ ] Add an **NPC** entity (display name, short role e.g. "Glitch University
  professor", default pose) owned by the mystery/template family, so casts are
  authored rather than global magic strings.
- [ ] Add **poses** as named portrait variants of an NPC (`pose_key` such as
  `neutral`, `concerned`, `wry`, `pointing`), each backed by one immutable image
  asset via the existing `assets` table + MinIO path.
- [ ] Clone NPCs and pose→asset references (asset bytes reused, not copied) during
  template freeze and instantiation, mirroring document image cloning.
- [ ] Enforce that every dialogue step names an NPC that exists in the mystery's
  cast; a **missing pose is never an error**.
- [ ] Resolve a step's portrait at render time with graceful fallback: the
  requested `pose_key`, else the NPC's **`default`** pose, else **no artwork**
  (speaker name + text only). This lets authors add poses incrementally and keeps
  the first slice playable with zero uploaded art.

## 6. API contract

- [ ] **New Game / session:** add `POST …/playthroughs` (create for the current
  `user_id`, per section 1) and `GET …/playthroughs/current` so the splash can
  offer New Game or Resume; scope every playthrough read/write to the caller's
  `user_id` so one player cannot touch another's game state.
- [ ] **Play mode:** return a compact `pendingCutscene` payload (slot, ordered
  steps with resolved NPC name + pose asset URL) when one is due and unseen; add
  `POST …/playthroughs/:id/cutscenes/:cutsceneId/seen` (idempotent) and
  `POST …/playthroughs/:id/advance` implementing section 1's transactional advance.
- [ ] **Admin mode:** add authenticated CRUD for mysteries, chapter ordering,
  NPCs and poses, and dialogue scenes/steps, plus the campaign freeze operation —
  all behind the existing admin JWT and `edit=1` gate.
- [ ] Keep authoring-only fields (raw pose keys, expected-solution data, unfrozen
  drafts) out of play-mode responses, consistent with how brief concept
  `expectedPartyKind` is already hidden in play mode.


## Definition of done

A game designer can, in the admin panel, create a mystery, select existing levels
as ordered chapters, create NPCs and upload named poses, craft dialogue scenes
choosing a pose per step, and attach those scenes to chapter slots — then freeze
it. A player lands on the "PRINCIPAL INVESTIGATOR" splash, chooses New Game to
create a playthrough bound to their identity, watches the professor speak
line-by-line with a
changing portrait, investigates each board, reports back to advance a chapter that
introduces a new document and goal, and reloads at any point without replaying
seen scenes — with no dialogue text hard-coded in React and no cutscene mutating a
board.