Skip to main content

Features

A running log of what Tome of Sessions can do. Update this file whenever you add, change, or remove a feature (see AGENTS.md).

Status key: ✅ done · 🚧 in progress · 📋 planned

Last updated: 2026-07-02 · Recent changes are logged in the Changelog at the bottom of this page.

Authentication & accounts​

  • ✅ Email + password sign up (bcrypt-hashed passwords, 12-character minimum)
  • ✅ Login issuing a JWT (7-day default expiry) delivered as an httpOnly session cookie — never stored in localStorage; Authorization: Bearer still works for API clients and tests
  • ✅ Sign out with real revocation — POST /auth/logout clears the cookie and bumps the user's tokenVersion, invalidating every outstanding token (all devices). Password reset bumps the version too, so a hijacked session dies with the reset.
  • ✅ GET /me — current user + derived profile stats (campaigns, sessions, weekly streak)
  • ✅ PATCH /me — update display name / character / avatar colors
  • ✅ Frontend auth context with cookie-based sessions and route guards
  • ✅ Abuse hardening — rate-limited public invite preview, per-account daily cap (3) on password-reset emails, HSTS when served over HTTPS, server-side logging of 401/403s for intrusion spotting
  • ✅ Password reset — /forgot-password requests a single-use link (SHA-256-hashed in DB, 1-hour TTL); /reset-password/:token sets a new password. Delivered via Resend (falls back to console in dev).
  • ✅ Email verification on signup — auto-issued at signup, confirmed via /verify-email/:token. Unverified accounts can still sign in but see a dismissible banner with a "Resend link" action. Delivered via Resend (falls back to console in dev).
  • ✅ Discord SSO — Sign in with Discord button auto-appears on Login / Signup when DISCORD_CLIENT_ID + DISCORD_CLIENT_SECRET are set. Signed short-lived OAuth state for CSRF; auto-links to an existing tome account with the same email, otherwise creates a passwordless SSO account (verified inheritor of Discord's email-verification flag).

Campaigns​

  • ✅ Create a campaign (creator becomes DM)
  • ✅ List campaigns the user belongs to, with their role per campaign
  • ✅ Campaign detail (members, schedule, system, tagline)
  • ✅ Tabbed campaign detail — Overview (campaign art slimmed to cover + table-size pill, above an inline-editable Campaign details card) hosts a sub-tab bar: The Party (roster + DM management forms, visible to all members) and Sessions (the session list with mark-played-with-notes / delete) for everyone, plus DM-only Setting (campaign preferences) and Rules Docs (the document upload/index UI) sub-tabs. Top-level tabs are a DM-only Rules Chat (placed right after Overview), Schedule (the Scrying Pool + add-a-session form), Active Session (when an upcoming session exists), a player-only My Character tab (set the name + class/role shown for you in this campaign), and a DM-only Combat Tracker. Each tab is its own route (/campaigns/:id/overview · /ruleschat · /schedule · /session · /character · /combat) and the Overview sub-views deep-link their own segment too (/overview/party, /overview/sessions, /overview/setting, /overview/documents) so any view can be linked directly; the bare /campaigns/:id redirects to Overview. The Overview > Sessions "Schedule" button jumps to the Schedule tab. The tab selector hides itself when only one tab is visible.
  • ✅ Update campaign (DM only): name, tagline, system, status, status note, schedule
  • ✅ Inline-editable Campaign details on the Overview tab — a CampaignOverview card lists Name, Tagline, Game System (shared SYSTEMS dropdown with an "Other…" free-text fallback), and How the party gathers (Scheduled day/time/venue vs. on-demand "Scryed ad hoc"). Each row has its own Edit/Save that patches just that field via PATCH /campaigns/:id; players see the values read-only (no Edit buttons)
  • ✅ DM-only campaign Setting sub-tab (inside Overview) — a preferences panel holding an AI improve Session Notes toggle, a persisted campaign boolean (aiImproveSessionNotes, default off) saved via PATCH /api/campaigns/:id. When on, the mark-as-played modal gains the Review with the Sage AI notes-improvement step (see Sessions). The rules-doc upload/index UI is its own sibling Rules Docs sub-tab.
  • ✅ Delete campaign (DM only)
  • ✅ Campaign status: active / paused / concluded, with a free-text status note (e.g. "Resumes after July")
  • ✅ Schedule kinds: unset / scheduled / recurring / scrying / on-demand
  • ✅ Campaign cover image upload — DM uploads PNG / JPEG / WebP / GIF (max 5 MB) from the campaign header; files served from /uploads/covers/...
  • ✅ Campaign duplication — DM duplicates a campaign from Overview (POST /api/campaigns/:id/duplicate), copying settings, rulebook opt-ins, documents with embeddings, monsters/items, NPCs, entities, and encounters (with session links stripped); excludes players, sessions, polls, invites, combat, chat history, and recap extractions; new campaign starts ACTIVE under the duplicating DM

Party / members​

  • ✅ Add a player to a campaign by email (DM only)
  • ✅ Static (offline) members — DM adds a player who isn't on the platform by name + class/role. They show in the party and are auto-added to the combat tracker, but are excluded from the Scrying Pool vote (no account to vote with)
  • ✅ Remove a player (DM only; DM cannot remove themselves)
  • ✅ DM handover — transfer a campaign to another member (POST /campaigns/:id/transfer with toUserId + keepAsPlayer); the outgoing DM either stays on as a PLAYER or leaves the campaign
  • ✅ Per-campaign character names; roles (DM / player) — a player sets their own on the My Character tab; the DM can set any member's character name / role from a roster action on the Overview > The Party sub-tab
  • ✅ Per-player character level (1–20) — a Membership.level defaulting to 1 when a member is added, editable (number input, clamped 1–20) in the same character forms (the player's own and the DM's edit-member modal) and shown in the party roster subtitle (e.g. "Wood Elf Wizard · Lv 5"). Saved via the shared CharacterPatchBody on PATCH /campaigns/:id/me and /memberships/:mid
  • ✅ Invite links — DM generates a shareable URL from the campaign screen (copy / revoke pending invites), addressee or open links both supported
  • ✅ Player-side "join with invite" screen at /join/:token — previews the campaign and inviter, bounces logged-out viewers through /login (preserving the return path) and creates the membership on accept
  • ✅ Real-time invite removal — when a player accepts an invite the DM's pending invite list updates instantly via SSE (invite_accepted event) and the new member appears in the members list without a page reload

Sessions​

  • ✅ List a campaign's sessions
  • ✅ Create a session (DM only)
  • ✅ Update / delete a session (DM only)
  • ✅ Session fields: title, scheduled time, duration, platform, agenda, number, status
  • ✅ Cross-campaign "Upcoming Sessions" feed for the signed-in user
  • ✅ "The Scrying Pool" scheduler UI — DM proposes candidate nights (datetime picker, add/remove rows) directly from the campaign detail screen
  • ✅ Session scheduled notification — all non-DM campaign members receive an email when the DM creates a session.

Encounters & the Active Session tab​

  • ✅ Encounters are campaign-level (DM only) — prepared with a name, optional notes, and monster rows (name, count, AC, max HP, initiative modifier), they live on the campaign and can be created and run at any time, with or without an active session. An encounter can optionally be linked to the active session via a checkbox shown only while a session is active; a linked encounter's card shows "Linked to Session #N · Title". Deleting a session unlinks its encounters (they survive). Templates: running one never changes it, so it can be re-run after a reset. Each card shows the name with its difficulty badge, the monster summary, optional notes, the "Linked to …" line when linked, and a "Prepared <date>" line (createdAt).
  • ✅ Encounter difficulty estimate (2024 DMG XP budget) — each encounter response embeds a difficulty object: tier (Trivial / Low / Moderate / High / Deadly), total encounterXp, the XP budget thresholds (low / moderate / high), party size, and an unratedCount for monsters without a CR. Tier is derived from the campaign's player levels (no encounter-size multiplier, per 2024 rules); Deadly triggers at 1.5× the party's High budget (there is no official 2024 Deadly budget). Per-monster Challenge Rating is auto-filled from the SRD when a monster is selected, and editable via a CR dropdown (values "0" "1/8" "1/4" "1/2" "1" … "30") for custom/homebrew monsters. Encounters with unrated monsters display the difficulty as a lower bound. The encounter editor shows a live difficulty badge as the DM edits rows — computed client-side from the current rows + the party's levels (mirroring the server in web/src/lib/encounterDifficulty.ts) — and both the live badge and the saved-encounter badge use a green (Trivial/Low) / yellow (Moderate) / red (High) / solid-red (Deadly) traffic-light scheme.
  • ✅ AI-suggested encounters (DM only) — a "Suggest with AI" control next to Prepare encounter opens an inline bar (optional theme hint + tier selector) and calls POST /campaigns/:id/encounters/suggest. The server splits math from judgment: the LLM only picks a thematically coherent subset of the campaign's own monsters (falling back to stored core-rule monsters within the party's CR band) + counts + a name/flavor note, while all stats and the recomputed difficulty come from the Monster records and the deterministic 2024 budget math (XP derived from CR via cr_to_xp, never the stored xp). Theme matches are ranked first (a multi-word hint matches on any single word — "Kobold Warren Ambush" surfaces a Kobold). The chosen tier is an enforced ceiling, not just a hint: the server trims counts so the total XP never exceeds the tier's budget (dropping a creature that alone exceeds it), so a Moderate request can't come back High/Deadly. The unsaved suggestion pre-fills the normal create form for the DM to review, edit, and save — nothing persists until they hit save. 400 when no party levels are set; 503 (with the control hidden afterwards) when AI generation isn't configured — fake picks are honored only when explicitly enabled, never as the implicit no-key fallback.
  • ✅ Source-labeled monster autocomplete (SRD + local DB) — the monster name field in both the encounter builder and the Combat Tracker add-combatant row autocompletes across three sources at once: the campaign's own extracted monsters (Campaign), the shared core rules (Core), and the D&D 5e SRD proxy (SRD), each result shown with an inline source badge. Sources are queried in parallel and fail soft independently. Picking any result autofills the stats (AC, HP, initiative modifier; CR too in the encounter builder); in the Combat Tracker the chosen monster's initiative modifier rides onto the combatant so its per-row d20 die rolls d20 + modifier. Local results come from GET /api/campaigns/:id/monsters/search (now returning a source of "campaign" / "core"); SRD results from the dnd5eapi.co proxy.
  • ✅ One-click run — POST /encounters/:id/run rebuilds the War Table: party re-seeded as blank rows, monster counts expanded into numbered copies ("Goblin 1, Goblin 2, …", HP pre-filled), round reset. If a fight is mid-round the server answers 409 and the UI asks before replacing it.
  • ✅ "Active Session" campaign tab — appears only while an upcoming session exists (earliest not-played, not-cancelled; flips forward automatically as sessions are played). Everyone sees the session header (title, date, platform, agenda) and, for the DM, the full-width live session notes editor. (Spec: docs/superpowers/specs/2026-06-11-session-encounters-design.md)
  • ✅ "Encounters" campaign tab — a DM-only tab listed directly under Active Session (in both the desktop rail and the mobile tab bar), always visible to the DM (no longer gated on an active session). Hosts the campaign's encounter prep list with Run / Edit / Delete (and the AI-suggest / difficulty tooling). Running an encounter jumps straight to the Combat Tracker tab.
  • ✅ NPC roster — DM-only tab with AI generation via Sage chat (prep mode) or a dedicated "Generate NPC" button and manual CRUD; campaign-grounded or generic generation; saveable NPC card in chat.
  • ✅ NPC profile page — each NPC opens at its own DM-only URL (/campaigns/:id/npcs/:npcId) as a full read+edit profile (replacing the view/edit modals), with an uploadable profile photo stored under /uploads/npc/ (POST/DELETE /api/campaigns/:id/npcs/:npcId/photo, reusing the cover upload pattern) and a new nullable NPC.photoUrl column (Alembic d5c6e7f8a9b1).
  • ✅ Rollable tables in chat — DMs can ask the Sage (prep mode) for a random table (e.g. "a table of tavern rumors", "effects of a mysterious flask", "a d100 table of deities in my campaign"). A new "table" prep sub-task (classify_plan_subtask + extract_table_request) routes to _table_dispatch in graph.py, which optionally grounds the table in retrieved campaign notes (RAG, like NPCs), streams a table SSE event, and persists the card on a new RulesChatMessage.table column. app/lib/table_suggest.py normalizes the die to a standard size and guarantees rows tile 1..die (math split from LLM judgment, like loot). The <TableCard> renders the numbered table inline with a client-side, re-rollable Roll button that highlights the matching row.
  • ✅ Live session notes in Active Session tab — a full-width rich-markdown editor panel in the DM's Active Session tab. Typing autosaves to session.notes via PATCH /sessions/:id with a "Saving…" / "Saved" status indicator, debounced to avoid chat-like flurry. Notes persist across reload and render as Markdown in played-session list previews (2-line clamped). The toolbar is themed to the tome palette — icon buttons adopt the app's muted→ink hover and an accent-tinted active state, with a tome-coloured divider replacing the library's default bar.
  • ✅ Mark as played, with title — the DM-only button on the Active Session tab and the "Mark played" action on any Sessions-list row both open a dedicated wide modal (SessionEditorModal in play mode) with an editable title and the same full rich-markdown notes editor below it (shared NOTES_COMMANDS toolbar), so the DM can review and edit the notes before committing. Saving writes title + notes and flips the session to played via PATCH /sessions/:id; the Active Session tab advances to the next upcoming session and a 2-line Markdown-rendered preview of the notes shows under the played session in the list. New sessions are inserted client-side in the server's chronological order and de-duplicated by id, so a just-added session lands in its correct place rather than doubling up at the bottom until refresh (the create response and the session_scheduled broadcast previously raced — both now route through a shared upsertSession). When the campaign's AI improve Session Notes setting is on, the modal adds a Review with the Sage step alongside Save as-is (only if notes exist): Review calls POST /campaigns/:id/notes/improve (with the sessionId), which retrieves the campaign rules/adventure and has the generator polish the notes — fixing grammar/structure (light Markdown) and filling in proper names (places, NPCs, monsters) grounded in the retrieved sources, never fabricating. It passes the session's position (number/title/agenda) and earlier-session notes as context, so e.g. a first session biases toward the opening chapter. The result is rendered as Markdown (via a small Markdown component) in a readonly pane with Done (save) or Back to edit. The improve call persists nothing; the session is written only on save. Works with zero indexed documents (rules context is optional).
  • ✅ Edit any played session (DM only) — an Edit button on every played-session row opens SessionEditorModal in edit mode: the DM can update the title and notes at any time, with an optional Review with the Sage AI-improve step (same flow as mark-played, available when the campaign's aiImproveSessionNotes is on). The Re-open button is hidden (not disabled) when another session is already active, so it only appears when re-opening is actually possible. Long played-session notes expand/collapse inline — a "Show more" / "Show less" toggle appears when the notes preview exceeds the 2-line clamp, so the list stays compact by default.

Combat tracker (DM only)​

  • ✅ Per-campaign initiative tracker — DM adds combatants (initiative — with a d20 auto-roll — name, AC, HP). Each combatant carries an initiative modifier (from its encounter monster); a per-row die rolls d20 + the modifier and writes the result. The DM also edits initiative/AC/HP inline, drags rows to reorder turn order in real time (or one-click Auto-order by initiative), and tags color-coded 5e status conditions from a dropdown
  • ✅ Party auto-seeded — the campaign's players are added as blank combatants (name only) when the tracker is first opened and again after a clear, so the DM only fills in their initiative / AC / HP
  • ✅ Turn order — start combat, advance turn (auto-incrementing the round on wrap), end combat, and clear the encounter; state is server-persisted and invisible to players
  • ✅ Bloodied indicator — each combatant row has an editable Max HP field beside current HP; when current HP drops below half of max, a crimson Bloodied tag appears by the name and the HP value turns crimson, so the DM spots hurt creatures at a glance (frontend-derived from the existing hpCurrent/hpMax; combatants with no known max are never flagged)

Availability ("The Roll Call")​

  • ✅ DM proposes candidate dates (creates an availability poll); campaign flips to "scrying"
  • ✅ Members set their own availability marks (yes / maybe / no) per candidate date
  • ✅ Availability grid (players × dates) rendered on the campaign detail screen
  • ✅ Close a poll (DM only)
  • ✅ Auto-highlight the best date based on responses (weighted yes/maybe score, with per-night tally surfaced in the Roll Call grid)
  • ✅ Promote a poll's winning date into a scheduled session in one click (DM only; creates the session, closes the poll, marks the campaign scheduled)
  • ✅ Scrying Pool opened notification — all non-DM members receive an email when the DM opens an availability poll.
  • ✅ All votes in notification — DM receives an email (with best-date tally) when every player has submitted their Roll Call responses.
  • ✅ Scrying promoted notification — all non-DM members receive an email when the DM promotes a scrying result to a confirmed session.

Real-time updates​

  • ✅ Server-Sent Events (SSE) endpoint — GET /campaigns/:id/events streams named events to connected clients; campaign-scoped, authenticated via the session cookie (no more token-in-URL), with 30-second keep-alive pings and automatic browser reconnection
  • ✅ scrying_opened — broadcast to all campaign clients when the DM opens a new availability poll
  • ✅ vote_cast — broadcast with the full updated poll DTO when a player submits availability marks
  • ✅ poll_promoted — broadcast with the new session DTO when the DM promotes a poll to a confirmed session
  • ✅ session_scheduled — broadcast when the DM creates a session directly
  • ✅ session_ended — broadcast when the DM marks a session as played or cancelled
  • ✅ useCampaignEvents React hook — opens an EventSource per campaign, dispatches events to caller-supplied handlers, and triggers a full re-fetch on reconnect

Profile​

  • ✅ Profile screen with avatar, name, character, stat trio, account rows, sign out
  • ✅ Edit profile from the UI — display name, character, and avatar gradient (6 presets) editable inline on the Profile screen

Admin / Platform Settings​

  • ✅ Admin role + Platform Settings — boolean User.isAdmin (bootstrapped via ADMIN_EMAILS); admin-only User Management (promote/demote/delete with guardrails) and Core Rule Management (private PDF/Markdown corpus per setting, D&D for now; future RAG source) — multi-file upload with the filename used as the title. Endpoints under /api/admin/*.

Rules chat & document ingestion​

  • ✅ Persisted extraction + "Process" action — ingest now saves the extracted Markdown as a sidecar next to the source file (<token>.extracted.md in private storage) and stamps extractedAt on the doc. A new Process button beside Re-index (and POST /admin/core-rules/:id/process / POST /campaigns/:id/documents/:docId/process, 400 until first indexed) re-derives chunks/overview/monsters from that saved Markdown without re-parsing the source — so newly-added extractors or changed chunk settings can be applied without re-running PDF extraction. Monster extraction is now resilient: a mid-run API/rate-limit error keeps the monsters already parsed (the loop stops and persists the partial set) instead of discarding the whole run, so an interrupted Monster-Manual ingest no longer loses everything.
  • ✅ Monster extraction during ingest — Core Rules and Campaign documents now have their stat blocks extracted (LLM structured extraction, best-effort so it never fails indexing; cheap Armor Class/Hit Points prefilter skips narrative pages) into the dedicated Monster table, tagged by source and flagged needsReview when AC/HP/CR are missing. A campaign-scoped API (GET /api/campaigns/:id/monsters/search + /:monsterId) serves them in the encounter-builder autofill shape (UI wiring deferred).
  • ✅ Campaign document ingestion — a DM uploads campaign PDFs/Markdown (adventures, house rules) per campaign; each document is parsed via Docling → header-aware chunked → embedded (Voyage, with a deterministic fake when no key is set) → indexed into a pgvector-backed Chunk table, with index status, re-index, and delete. Core rules are indexed on upload too. DM panel under the campaign's Overview → Rules Docs sub-tab; endpoints under /api/campaigns/:id/documents. The uploaded-file list renders through a shared DocumentRow component (used by both the campaign-docs and platform core-rules screens): a leading book-icon tile, title + metadata, and a dot-based status pill vertically centered with the Download / Re-index / Delete actions — colour rides on the dot (accent = indexed, pulsing amber = pending/indexing, crimson = failed) so the pill aligns cleanly in every state and long titles truncate without breaking the row.
  • ✅ Whole-document Overview synopsis — at campaign-document ingest, Claude summarizes the full extracted text into a short synopsis (premise/plot, factions, NPCs, locations, hooks) stored as an Overview chunk (sectionPath="Overview", sentinel ordinal=-1). Retrieval guarantees the Overview a slot: as one chunk among hundreds it loses any plain ranking fight and starves out of the top-k, so retrieve() fetches the campaign's synopsis chunk(s) by the sentinel ordinal and reserves them a slot (trimming the lowest-ranked content). Without this, synthesis questions ("what's the plot of this campaign?") only saw fragmentary scene chunks and wrongly abstained — a query router was considered and rejected as overkill for a deterministic single-chunk fix. Best-effort: a summary failure (API/content-filter) is logged and skipped, and the document still indexes normally. Large docs are single-pass with a clip + truncation note.
  • ✅ Per-campaign rules chat (DM-only) — hybrid retrieval (dense + BM25 + RRF) over the core-rule + campaign-document index, with a curated query-expansion alias map that bridges D&D vocabulary gaps before retrieval (e.g. "wizard subclasses" → "Arcane Tradition / School of Magic"); the map is a checked-in, comment-friendly Python data file (server/app/lib/rag/aliases.py) edited to close new gaps. Played-session recaps are always injected as citeable sources (chronological, budget-clipped), so the chat answers campaign-history questions like "What happened so far in this campaign?" — synthesised from the session notes and cited as "Session #N · Title" — and can answer them even when no documents are indexed. Anthropic cite-or-abstain generation with a citation guardrail, conversation history; abstains when the rules don't cover it. The Claude model is configurable via GENERATION_MODEL (defaults to Sonnet; set to claude-opus-4-8 to test Opus). PDF ingestion is tunable from a platform-admin Ingestion tab, per source type (Core Rules vs Campaign Rules): an extraction method selector — local (Docling), local_ocr (Docling + OCR), or anthropic (Claude reads each page with vision; far better for image-heavy PDFs, uses the API at PARSING_MODEL). Anthropic parsing falls back to local Docling only when no API key is configured; a parse error fails the ingest with the real cause instead of silently committing a broken text-layer extraction (which on a PDF with bad font encoding would index unreadable garbage that looks "indexed"). A content-filter block is the exception: when Anthropic's output filter blocks a page batch (invalid_request_error: "Output blocked by content filtering policy"), that batch is retried a page at a time so one offending page doesn't fail the whole document; a page still blocked alone is replaced with a visible placeholder and the rest indexes. Plus linked Max-chars / Overlap sliders (overlap auto-clamps to half of max chars). Settings are stored in the DB and apply to the next upload or re-index. Anthropic parsing transcribes page batches concurrently (reassembled in page order). Ingests interrupted by a server restart/crash (in-process background tasks don't survive one) are recovered at startup — any document left in processing/pending is flipped to failed with a note so it can be re-indexed, instead of hanging forever. Generation is fed the full retrieved chunk text, not the short citation snippet, so answers that sit past the snippet preview aren't invisible to the model (it no longer falsely abstains on rules that are in the corpus). The chat streams the answer (SSE): retrieved sources appear first, then the answer types in token-by-token, in a real chat-bubble UI with persistent history (Enter to send, Shift+Enter for newline). If generation fails mid-stream (API billing/rate-limit/network), the server emits a terminal error SSE event (logging the real cause, persisting nothing) and the client surfaces a calm error instead of hanging on "Consulting the tomes…" forever — the consumer also treats a stream that ends without a done event as an error, so a dropped connection can't leave the UI stuck loading. Inline citations render as small superscript footnote numbers so they don't break the reading flow; the cited sources are listed as numbered pills in a Sources footer beneath each answer, each revealing a styled hover popover (the Sage card aesthetic) with the document title, section breadcrumb, and source snippet. The chat view is locked to the viewport height — only the message thread scrolls; the header, question counter, and input stay fixed and the card never expands.
  • ✅ Stat-block tool in chat — asking the Sage to "show me the stat block for <monster>" triggers a genuine LLM tool call (get_stat_block, bound via the Anthropic tool-use API). The orchestrator reads the monster from this campaign's Monster table plus the shared core rules (exact case-insensitive match, then alphabetical prefix fallback; never another campaign's rows), emits a new stat_block SSE event carrying a full stat-block DTO (serialize_monster_stat_block) plus the monster's source document as its self-citation, persists a card-only assistant turn (RulesChatMessage.statBlock, nullable JSON), and finishes — no prose, no abstention. A miss falls through to the normal retrieve→stream→guardrail path so no empty card appears. The card renders via a reusable presentational <StatBlock> component, styled as an aged grimoire bestiary page (parchment, crimson illuminated headers, the signature tapered 5e divider bars, engraved display type) with full + compact variants and UI-derived ability modifiers. Free-form extractor entries (traits/actions/legendary stored as plain strings) are normalized to {name, desc} at extraction and serialization time (with a data migration backfilling existing rows), so the card always renders named entries. Endpoint GET /api/campaigns/{id}/monsters/{monsterId}/statblock (member-scoped) exposes the same DTO; a sibling GET …/monsters/statblock?name= resolves by name.
  • ✅ Stat block in the Combat Tracker — a monster/NPC combatant's name is clickable (dotted accent underline, firming to a solid accent underline on hover) and opens its stat block in a modal; player-character names render plain since they have no stat block. Resolved by name through the by-name endpoint (combatants carry a name, not a monster id; a name with no matching monster shows a friendly empty state). First reuse of the <StatBlock> component outside chat. The modal opens in a new bare mode (<Modal bare>) that drops the card chrome and sizes the dialog to fit-content, so the self-framed grimoire card is centered and hugged tightly instead of stranded left-aligned inside an over-wide dialog with empty space on the right. The button is hidden for player characters — combatants now carry a persisted isPlayer flag (Combatant.isPlayer, set true for party-seeded rows, false for monsters/manual adds; an Alembic migration adds the column and backfills existing party rows by name), so only monsters show the stat-block button.
  • ✅ Stat blocks resolve by reference — encounter monsters and combatants now carry a statBlockRef locator (campaign:<id> / core:<id> / srd:<index>) captured at monster selection in the encounter builder; the War Table's stat-block button resolves the right creature for numbered copies ("Goblin 1") and SRD monsters via GET /api/campaigns/:id/monsters/statblock/by-ref, with SRD blocks mapped from the full dnd5eapi payload. Hand-typed combatants and legacy encounters fall back to name resolution.
  • ✅ Dice-roller tool in chat — asking the Sage to "roll 2d6+3", "roll a d20", or "roll 2 d10" triggers a roll_dice LLM tool call: the orchestrator parses standard XdY±Z notation (count 1–100, sides 1–1000, modifier ±1000), rolls server-side, and emits a new dice_roll SSE event with each die face, the modifier, and the total — card only, no prose, no citation. The card-only assistant turn persists (RulesChatMessage.diceRoll) so reloads re-render it, and unparseable/out-of-bounds notation returns a friendly error card instead of falling through to retrieval. Rendered by a new <DiceRollCard>.
  • ✅ Optional Langfuse LLM tracing: when LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY are set, the Anthropic SDK is auto-instrumented and each user-facing operation is one grouped trace with its LLM calls nested underneath — no orphan/scattered traces. Rules-chat turns (streaming and non-streaming) trace retrieve→generate→guardrail, tagged with the conversation as the Langfuse session and the campaign as metadata; the streaming path holds one span across the whole turn (including persistence) so it isn't a detached generation. Per-mode trace tagging: the chat mode (rules / prep / recap) is stamped on each trace as both a first-class Langfuse tag and mode metadata, so traces are filterable per mode. The streaming adapter resolves the mode up front (shared resolve_mode helper, app/lib/rag/ graph.py) — before the trace opens, since Langfuse only tags spans created after the trace starts — and passes the resolved value into the graph so the router doesn't re-classify; the non-streaming path is tagged rules. Document ingest is one trace tagged with the document/campaign, with each per-batch Anthropic-vision parsing call nested under it — the parser's ThreadPoolExecutor re-attaches the trace context into its workers so batches don't scatter. Each trace also records a legible input/output on its root span — the question/answer for chat turns, the document descriptor and {status, chunks} for ingests — so the Langfuse trace list's Input/Output columns are readable without drilling into child spans. Shared, no-op-when-off helpers live in server/app/lib/rag/tracing.py. Disabled and zero-overhead when keys are absent; tracing failures never affect behaviour. Self-hosting: set LANGFUSE_HOST.

Platform / infrastructure​

  • ✅ Branch + PR workflow with CI — direct pushes to main are disallowed; GitHub Actions (.github/workflows/ci.yml) runs server lint (ruff) + pytest (with a pgvector Postgres service), the web type-check/build + vitest, and the docs-site build on every pull request
  • ✅ Backend rewritten in Python/FastAPI (SQLAlchemy 2 async + Alembic, Pydantic v2, managed with uv) — the HTTP API contract is unchanged; the React frontend works as-is. pytest suite replaces the previous vitest/supertest setup.
  • ✅ PostgreSQL schema via SQLAlchemy models + Alembic (models in app/models.py, migrations in server/alembic/) covering all entities
  • ✅ Seed script with the prototype's sample world (uv run python seed.py)
  • ✅ FastAPI app with centralized error handling + Pydantic validation
  • ✅ Vite + React + TypeScript SPA, responsive (mobile bottom tabs + desktop side rail)
  • ✅ Centered desktop content column — --content-max width ladder shared by the screen body and the appbar's inner wrapper, so whitespace splits evenly on wide monitors and the title stays over the column's left edge (spec: docs/superpowers/specs/2026-06-11-centered-desktop-layout-design.md). The appbar is fully constrained to the column: a shared --pad-x gutter ladder keeps the header text, back button, and scrolled bottom border/shadow aligned with the content's text edge at every breakpoint; only full-bleed elements (the unverified-email notifications banner) span the viewport
  • ✅ Contextual navigation — campaign tabs live in the chrome: in the desktop rail between "Campaigns" and "Upcoming" (divider-separated, with the campaign name as an eyebrow), and as the mobile bottom bar while on a campaign. CampaignDetail publishes its computed tabs through CampaignNavContext; the in-page segmented selector is gone (spec: docs/superpowers/specs/2026-06-12-contextual-sidebar-nav-design.md). Creating a campaign is reached from a + action in the Your Campaigns header (plus the empty-state button); the standalone "Create" rail/bottom-bar tab was removed. Every tabbed surface is URL-driven so it deep-links: the campaign tabs and their Overview sub-tabs (Sessions, Setting, Rules Docs) and Platform Settings sections (/admin/:tab). The desktop side rail can be collapsed to an icon-only strip via a hamburger toggle next to the logo (which replaces the logo when collapsed); labels become hover tooltips, each nav icon gets its own square container, the choice persists in localStorage, and the reclaimed width extends the content column
  • ✅ UI consistency layer — shared ErrorAlert / EmptyState / BackBtn / PasswordField / Select components (the Select replaces the OS dropdown arrow with a consistently-aligned caret), Modal with focus trap, a CSS radius scale + .btn-small / .seal.danger / .seal.suggest variants, :focus-visible rings on all interactive elements, and Modal-based confirmation for every destructive action (no window.confirm). Tracked in Improvements.md.
  • ✅ Docker Compose for local Postgres
  • ✅ Root dev helpers: ./start.sh launches the Vite web app on port 5559 and the FastAPI API on port 4000; ./stop.sh frees those ports by terminating any listener processes left behind after development runs.
  • ✅ CI pipeline — GitHub Actions runs server tests + lint and web build on every push / PR (.github/workflows/ci.yml)
  • ✅ NPC eval harness (server/evals/) — offline LLM-judge scoring of generated NPC quality: a versioned decomposed-binary rubric (rubric.py), a Claude Opus 4.8 judge with structured output so malformed verdicts raise instead of silently scoring 0 (judge.py), and golden-set validation reporting judge-vs-human Cohen's kappa (validate.py). run_llm_judge.py scores the full case set and writes evals/out/npc_eval.json; --push-langfuse ships results to Langfuse. Offline tests run with FakeGenerator + FakeJudge. Closes the NPC slice of deliverable #7.
  • ✅ Citation-accuracy eval (server/evals/) — 50 frozen PHB rules questions (rules_questions.jsonl, ~8–9 per topic; required + acceptable sectionPaths) scored over the live rules-chat pipeline (run_citation_eval.py calling answer_rules_question): precision / recall / F1 + abstention rate, macro and per-topic. Matching is tolerant (normalize.py absorbs OCR-noisy breadcrumbs — leaked page numbers, duplicated segments, depth — but not character errors); scoring/aggregation is pure and offline-tested (citation_metrics.py). Pipeline errors are recorded per-row and excluded from aggregates, never scored 0. Run: EVAL_CAMPAIGN_ID=<id> evals/calibrate.sh citation; writes evals/out/citation_eval.json. No judge → no calibration. Closes deliverables #3 / #4.
  • ✅ Encounter-math eval (server/evals/) — 10 frozen scenarios (encounter_scenarios.jsonl, Trivial→Deadly, varied party sizes/levels) whose expected_tier / expected_xp are hand-computed from the published 2024 tables. run_encounter_eval.py feeds each through the production estimate_difficulty and asserts an exact tier + XP match — deterministic pass/fail, no network, no key, CI-runnable. Run: evals/calibrate.sh encounter; writes evals/out/encounter_eval.json. Closes deliverables #5 / #6.
  • ✅ Integration tests against a real Postgres — env -u NODE_ENV uv run pytest tests in server/. Uses pytest + httpx against the docker-compose Postgres, truncates all tables between tests, and covers signup → campaign → invite → poll → promote → upcoming. GitHub Actions runs them on every push against an ephemeral postgres:16 service.
  • ✅ Deployment via Forge — root-level install:all / build / start scripts; npm start drives uv run python -m app.run which runs ensure-db + alembic upgrade head on boot then starts uvicorn; the API serves the built web app from web/dist/; GET /health for Forge health checks; binds to $HOST:$PORT (defaults 0.0.0.0:4000)

Notes​

  • The original design prototype lives in prototype/Tome of Sessions.html for reference.
  • API reference and setup steps are in README.md.
  • Post-rewrite bug-fix pass (2026-06-13): DELETE /campaigns/:id/combat now commits the reset (was discarded on session close); signup / password-reset accept passwords up to the 200-char schema limit again (bcrypt 5 rejects

    72 bytes — now truncated like the old bcryptjs); fire-and-forget notification emails hold a task reference so they can't be GC'd mid-send.

Changelog​

One dated line per feature change, newest first. Add a bullet here (and bump the Last updated date) whenever you ship a change; keep it to a single sentence. Full implementation detail lives in this file's git history, the topic pages of this docs site, and docs/superpowers/.

  • 2026-07-02 · AI-suggested encounters keep stat-block refs — suggestion rows now carry statBlockRef, so combatants from AI-generated encounters open their stat block in the combat tracker (previously "No stat block found" for numbered names like "Owlbear 1").
  • 2026-07-02 · PR template — pull requests are pre-filled with What / Why / How sections and a definition-of-done checklist (.github/PULL_REQUEST_TEMPLATE.md).
  • 2026-07-02 · Branch + PR workflow and rebuilt CI — direct pushes to main are disallowed (feature branch → push → PR); the stale Node/Prisma GitHub Actions were replaced with jobs for server lint + tests (pgvector service), the web build + tests, and the docs build.
  • 2026-07-02 · Feature ledger moved into the docs site — the root FEATURES.md now lives here as docs-site/docs/features.md; ./start.sh also serves the docs dev server (DOCS_PORT, default 3050).
  • 2026-07-02 · Developer documentation site — Docusaurus maintainer manual in docs-site/ covering the whole system; root npm run build/npm run start build and serve it.
  • 2026-07-02 · Campaign duplication — DMs duplicate a campaign (settings, documents with embeddings, monsters, NPCs, plot entities, encounters) while players, sessions, and history are excluded.
  • 2026-07-01 · Per-user AI access gating — User.aiAccess (or admin) gates every AI endpoint via require_ai_access; admins toggle it per user in Platform Settings.
  • 2026-07-01 · Sage note review is always on — the per-campaign toggle is removed; "Review with the Sage" is offered whenever a played session has notes.
  • 2026-06-30 · Core rule usage policy — rulebooks carry a required/optional/tools usage; optional books need a per-campaign opt-in (DM "Core Sources" sub-tab) before the Sage retrieves them.
  • 2026-06-30 · AI encounter difficulty matches the requested tier — the builder now targets the same XP band the difficulty badge reads, fixing one-tier-low results.
  • 2026-06-30 · Wax-seal brand mark — new SealMark spark-seal logo in the side rail, onboarding shell, and favicon.
  • 2026-06-30 · Uploaded images show in dev — the Vite dev server now proxies /uploads to the API.
  • 2026-06-30 · Codex loads fast while a recap is processing — recap extraction runs off the event loop so the app stays responsive during LLM calls.
  • 2026-06-30 · Tracing stays silent when unconfigured — Langfuse tracing is a true no-op without keys instead of logging auth errors.
  • 2026-06-30 · Citation & encounter-math evals — judge-free citation-accuracy and encounter-math measurements added to server/evals/.
  • 2026-06-30 · Recap-review rows show the referenced entity/NPC — display names are backfilled onto update/link/close ops before a changeset is persisted.
  • 2026-06-30 · Live NPC trace instrumentation — production NPC generation emits a filterable npc.generate Langfuse observation for LLM-judge evaluators.
  • 2026-06-29 · NPC eval harness — offline LLM-judge harness scoring generated-NPC quality against a versioned rubric, with golden-set kappa validation.
  • 2026-06-29 · Per-mode Langfuse trace tags — chat traces are tagged with their resolved mode (rules/prep/recap).
  • 2026-06-29 · Generate NPC button — the NPCs tab generates a campaign-grounded NPC from free-text ideas, with save/regenerate.
  • 2026-06-29 · AI / Sage visual language — one shared treatment for generative controls: gradient CTA, tonal secondary button, ✦ Sage chip, fixed --ai-* tokens.
  • 2026-06-29 · Icons migrated to FontAwesome — hand-rolled SVGs replaced behind the unchanged <Icon> wrapper; FontAwesome-only rule adopted.
  • 2026-06-29 · NPC profile page — per-NPC route with a full read/edit profile and photo upload.
  • 2026-06-29 · Codex recap processing panel — recap extraction has a persisted lifecycle plus SSE events; the Codex shows live processing/failure states.
  • 2026-06-29 · NPC living state — NPC status, per-session appearances, and directed relationships, populated by the recap extractor and editable in the UI.
  • 2026-06-28 · Recap entity extraction → living Codex — played-session recaps become DM-reviewed changesets maintaining plot threads/quests/locations in a new Codex tab.
  • 2026-06-28 · Rollable tables in chat — prep-mode Sage generates rollable tables rendered with a client-side Roll button.
  • 2026-06-26 · Loot generation — loot from Sage prep chat and a Combat Tracker modal, sharing one budget-math + LLM brain.
  • 2026-06-26 · NPC roster — NPCs generated in prep chat or managed manually on a new NPCs tab, backed by a new NPC table.
  • 2026-06-26 · Encounter-in-chat (prep mode) — prep chat builds saveable encounter cards using the encounter-suggest brain, streamed as SSE events.
  • 2026-06-25 · LangGraph chat modes — Rules Chat runs through a LangGraph router (rules/prep/recap) with the SSE contract unchanged.
  • 2026-06-25 · Dice-roller tool in Rules Chat — a roll_dice tool returns result cards for XdY±Z rolls.
  • 2026-06-25 · Combat Tracker UI pass — creature names open stat blocks; FontAwesome d20 and blood-drop icons; distinct nav glyphs.
  • 2026-06-25 · Party folded into Overview — the party roster and DM management became "The Party" sub-tab under Overview.
  • 2026-06-25 · Consistency + query-optimization pass — N+1 list endpoints batched and repeated inline styles extracted; behavior-preserving.
  • 2026-06-25 · Stat block in the Combat Tracker — combatant rows open a full stat-block modal via a by-name lookup endpoint.
  • 2026-06-25 · Stat-block card redesign + entry normalization — grimoire-styled stat block; trait/action entries normalized to named objects with a data backfill.
  • 2026-06-25 · Stat-block tool in chat — "show me the stat block for X" triggers a real tool call rendering a card-only answer.
  • 2026-06-24 · Source-labeled monster autocomplete — encounter/combat monster fields autocomplete across Campaign/Core/SRD with source badges.
  • 2026-06-24 · Encounters decoupled from sessions — encounters are campaign-level with an optional session link; routes moved under /campaigns.
  • 2026-06-24 · Persisted extraction + "Process" action — ingest saves the extracted Markdown; Process re-derives chunks/overview/monsters without re-parsing the source.
  • 2026-06-24 · Notes editor in mark-played modal — the full rich-markdown notes editor appears in the mark-played flow.
  • 2026-06-24 · Overview/Party split + editable campaign settings — inline-editable campaign-details card on Overview; party briefly its own tab (later re-folded into Overview).
  • 2026-06-24 · Session edit modal + inline notes expand/collapse — DMs edit played sessions any time; Re-open hides while another session is active; long notes collapse inline.
  • 2026-06-24 · Encounters moved to their own campaign tab — DM-only Encounters tab; the Active Session editor gets the full width.
  • 2026-06-24 · Live session notes in Active Session tab — an autosaving rich-markdown notes panel.
  • 2026-06-24 · AI-suggested encounters — "Suggest with AI" assembles tier-budgeted encounters from campaign/core monsters; deterministic math, LLM judgment.
  • 2026-06-19 · Encounter difficulty estimate — 2024 XP-budget difficulty badge, SRD-autofilled CR, and a per-monster initiative modifier with a d20 roll.
  • Earlier (June 2026) · Rules Chat & ingestion foundations — hybrid retrieval with cite-or-abstain generation, streaming answers with footnote citations and hover popovers, crash-safe streams, per-document Overview synopsis chunks, query-expansion aliases, the admin Ingestion tab, Anthropic PDF parsing with per-page retries, grouped Langfuse traces, and a configurable generation model.
  • Earlier (June 2026) · Sessions & campaign polish — the mark-played modal with grounded "Review with the Sage", Markdown note previews, campaign-history answers sourced from session recaps, per-campaign character levels, the sessions-list dedupe fix, the DocumentRow redesign, and removal of the obsolete nested Next.js/Prisma scaffold.