Skip to main content

Journal

This page owns the player-facing Journal for Game 1. The Journal is the persistent, day-based memory layer that lets the player reread what the MC noticed, what changed, and why a thread still matters after the immediate pressure of the current queue has passed.

The Journal is not a one-time popup, a raw event dump, or the combat Chronicle. It is the durable narrative readback surface for survival, discovery, objectives, clues, missions, locations, sites, and lore artefacts.

Role​

The Journal should answer three questions:

  • What happened today that the MC would remember or write down?
  • What does that change about the player's current understanding?
  • What can the player reopen later when they need context, mood, or evidence?

The Journal keeps the Act 0 through Act 7 campaign readable across long play sessions. It preserves first-person or close-perspective uncertainty without turning hidden cosmology into omniscient exposition.

Ownership Boundaries​

  • Journal owns persistent day-based memory, written entries, annotations, rereadable discoveries, and cross-links back into planning and world surfaces.
  • Current Plan owns urgency and short-horizon synthesis.
  • Objectives owns active objective, clue, and mission structure.
  • Location Dossier owns deep place inspection for the currently selected Location.
  • Combat Chronicle owns encounter-by-encounter combat readback and remains distinct from Journal.

Day-Based Structure​

Journal entries are grouped by in-world day. A day page is the stable reread surface; individual updates land inside that day rather than replacing earlier notes.

Each day page should support:

  • a day header with date, broad state, and place context
  • ordered entries that preserve when the MC learned or decided something
  • expandable linked records for objectives, clues, missions, locations, sites, features, threats, and lore artefacts mentioned that day
  • a running annotations area where the player can pin, mark, or comment on unresolved details

The Journal must remain useful even when the player returns many in-game days later. Day grouping is the persistence spine; filters and links sit on top of it rather than replacing it.

Entry Classes​

The Journal supports multiple entry classes. These are Journal types, not new runtime planning nouns.

  • Day Opening - the day's opening condition, pressure, and immediate state
  • Observation - what the MC noticed in the field without claiming more than the MC knows
  • Objective Shift - a meaningful change to an objective, clue, or mission
  • Discovery - a site, feature, person, artefact, route, or truth newly made legible
  • Decision - the player's chosen approach, vow, priority, or working theory
  • Outcome - the outcome of a mission, expedition, night, or other bounded effort outside combat-round readback
  • Lore Record - a recovered book, inscription, journal, map, relic, or other readable artefact plus the consequence it creates
  • Condition Record - a survival-state turn such as hunger, cold, exposure, fatigue, or loss that matters to the story memory of the day

Entries may link to:

  • objectives
  • clues or leads
  • missions
  • activities
  • locations
  • features
  • sites
  • characters
  • lore artefacts
  • threats or pressures

These links are metadata and navigation, not prose. The Journal may also carry tags for filtering and later recall, such as survival, weather, first-night, ward-sign, ruin, people, threat, or theory.

Annotations​

The player should be able to annotate Journal content without corrupting the base record. Supported annotation shapes include:

  • pinning an entry as strategically important
  • adding a player note or question
  • marking a theory as likely, doubtful, or disproved
  • bookmarking an entry for later narration or investigation

Annotations are layered over the Journal record. They do not rewrite the original day entry.

Journal-Triggered Modals​

Some Journal entry classes — specifically Decision entries that present a branching player choice, and Discovery entries that present a major narrative discovery — surface a FloatingSurface modal at the moment the corresponding entry is created. The modal is the canonical way to demand player attention for a story beat that should not be quietly logged.

The modals the Journal triggers are:

  • PendingChoiceModal — branching or story choice, where the player must pick a continuation before the Journal records the Decision entry. The Journal entry's downstream consequence depends on the chosen branch.
  • FeatureDiscoveryModal — major Discovery beat where the narrative surfaces a Feature, Site, lore artefact, or world fact the MC has just earned. The modal may present a choices array (becomes buttons) or fall back to a single Acknowledge button.

Routine Journal entries — Day Opening, Observation, Outcome (non-major), Condition Record — must not raise a modal. They land in the Journal directly. The modal allowlist for Valenar lives in gd-shell-screen-model.md § Modal Taxonomy; the Journal follows that allowlist without extension.

This page does not commit to which specific quests, lore branches, or world facts trigger which modal; that belongs to the story and quest design docs.

Readable Prose vs Voice Readback​

Each Journal entry can expose two different text surfaces:

  • readable on-screen prose for the Journal page
  • optional narration-safe prose shaped for spoken readback

The readable entry prose may sit beside metadata, links, tags, and structured consequence panels in the UI. The spoken-readback copy must stay clean. Do not put UI link chips, ids, tag clutter, or metadata labels into spoken prose.

This page defines the separation between those surfaces, not committed runtime field names. Implementation naming stays deferred until a schema or ADR makes it explicit.

Voice-readback prose should use short scene beats, readable paragraphing, and the MC's limited knowledge. If the MC only suspects something, the spoken-readback copy states suspicion, not truth.

Design Rules​

  • Journal is persistent. Never reduce it to a one-time popup or an ephemeral banner feed.
  • Journal is authored memory, not a raw telemetry log.
  • Journal should preserve uncertainty-first narrative framing, especially in Act 0 and early mystery chains.
  • Journal entries must create or clarify playable context. A lore artefact with no downstream consequence belongs outside this surface.
  • Journal should let the player move from prose to the linked objective, mission, dossier, or queue row that now matters.
  • Combat blow-by-blow belongs in Chronicle, not in Journal.

Runtime Status​

The current implementation already ships a dedicated Journal query/version/client path and keeps Journal separate from the combat Chronicle at the accepted baseline. That runtime slice is still narrower than the full contract above, and the remaining follow-through is explicit:

  • separate narration-safe prose for spoken readback remains deferred
  • annotations and player-authored notes remain deferred
  • deeper Current Plan linking back into Journal context remains deferred
  • richer site, lore artefact, and faction metadata remains deferred
  • broader wording cleanup, including remaining legacy Core Base phrasing, remains deferred

Cross-surface runtime constraint. The Journal, Objectives, Queue, and Location Dossier have live runtime counterparts that constrain doc updates: Host/ReadModels/JournalReadModel.cs, Host/ReadModels/ObjectivesReadModel.cs, Host/ReadModels/PlayerActivityQueueReadModel.cs, and Host/ReadModels/LocationDossierReadModel.cs. The client surfaces are Client/src/hooks/useJournalDossier.ts, Client/src/hooks/useObjectivesDossier.ts, Client/src/hooks/useLocationDossier.ts, and Client/src/api/types.ts. Doc updates that introduce new fields, drop existing fields, or change surface semantics must be checked against these paths before dispatch.