rbrooks/Quest-Board
Watch
1
0
Fork
You've already forked Quest-Board
 0
Code Issues 77 Pull requests 1 Projects Releases 42 Packages Wiki Activity Actions 1

Epic: Session Reference Shelf — manual spine #235

New issue
Closed
opened 2026-07-21 21:03:26 +00:00 by claude-bot · 4 comments
claude-bot commented 2026-07-21 21:03:26 +00:00
Contributor
Copy link

What

A per-session, glanceable reference surface the GM keeps open during live play. Anything generated in the GM Workbench (NPC, description, rumor, table, loot) persists on the shelf for the whole session — independent of whether it's saved to the wiki — and the GM can pin existing wiki/lore entries as reference cards. Goal: everything relevant to tonight in one place, at a glance, without hunting a large wiki mid-scene.

This epic is the manual "spine" — it works fully offline (no LLM/ASR dependency). The transcript-driven "listening" layer is v3.12 (The Shelf Listens).

Distilled from a 3-model brainstorm (Sonnet 5 / Opus 4.8 / Fable 5), which converged hard on the shape below.

Component checklist (break into sub-issues when picked up)

  • Spatial board, not a list — cards hold the position the GM drops them; never auto-reflow (spatial muscle memory). (unanimous)
  • Glance-compressed cards — a "glance face": name + one-line want/hook + ~3 facts + voice/mannerism cue; full detail one tap away. Never dump full wiki prose.
  • Spotlight / "now playing" — promote one card to a large stage slot; one key to swap; the previous card returns to its exact spot.
  • Scene packs — bundle cards into named scenes during prep; swap the shelf's context in one tap during play.
  • Reveal-to-table — flick a card to players (Discord embed / player screen) with GM-only vs player-safe layers.
  • Cards accrue "tonight" notes — one-tap scratch notes + captured deltas; each card carries its delta from canon.
  • Fast retrieval — command palette (Ctrl-K fuzzy) + number-key hotkeys for the current scene's cards.
  • End-of-session sweep ("strike the set") — one-tap disposition of every card touched tonight: promote-to-wiki (AI drafts the merge), carry-forward, or discard.
  • Warm cold-open — next session's shelf boots pre-loaded with carried cards + open loops + a "previously on" recap.
  • Pull existing lore onto the shelf — add wiki entries as reference cards.

Guardrails (consensus)

  • Never auto-move the GM's cards — spatial layout is sacred; anything proactive only adds to a separate tray.
  • Compress, don't dump — a card you must read has failed.
  • Not an editor — live writes capped at one-tap notes/rolls; real authorship deferred to the sweep.
  • No silent auto-save to the wiki — the shelf's value is being the "not yet canon" buffer.

Depends on / relates to

  • Builds on the generation history/scratchpad (#138 — GenerationResult already carries a session_id FK, so half the plumbing exists).
  • Best built on top of the config-driven GeneratorPanel (#234).

🤖 Generated with Claude Code

## What A per-session, **glanceable reference surface** the GM keeps open during live play. Anything generated in the GM Workbench (NPC, description, rumor, table, loot) **persists on the shelf for the whole session** — independent of whether it's saved to the wiki — and the GM can **pin existing wiki/lore entries** as reference cards. Goal: everything relevant to *tonight* in one place, at a glance, without hunting a large wiki mid-scene. **This epic is the manual "spine" — it works fully offline (no LLM/ASR dependency).** The transcript-driven "listening" layer is v3.12 (*The Shelf Listens*). Distilled from a 3-model brainstorm (Sonnet 5 / Opus 4.8 / Fable 5), which converged hard on the shape below. ## Component checklist (break into sub-issues when picked up) - [ ] **Spatial board, not a list** — cards hold the position the GM drops them; never auto-reflow (spatial muscle memory). *(unanimous)* - [ ] **Glance-compressed cards** — a "glance face": name + one-line want/hook + ~3 facts + voice/mannerism cue; full detail one tap away. Never dump full wiki prose. - [ ] **Spotlight / "now playing"** — promote one card to a large stage slot; one key to swap; the previous card returns to its exact spot. - [ ] **Scene packs** — bundle cards into named scenes during prep; swap the shelf's context in one tap during play. - [ ] **Reveal-to-table** — flick a card to players (Discord embed / player screen) with GM-only vs player-safe layers. - [ ] **Cards accrue "tonight" notes** — one-tap scratch notes + captured deltas; each card carries its delta from canon. - [ ] **Fast retrieval** — command palette (Ctrl-K fuzzy) + number-key hotkeys for the current scene's cards. - [ ] **End-of-session sweep ("strike the set")** — one-tap disposition of every card touched tonight: promote-to-wiki (AI drafts the merge), carry-forward, or discard. - [ ] **Warm cold-open** — next session's shelf boots pre-loaded with carried cards + open loops + a "previously on" recap. - [ ] **Pull existing lore onto the shelf** — add wiki entries as reference cards. ## Guardrails (consensus) - **Never auto-move the GM's cards** — spatial layout is sacred; anything proactive only *adds* to a separate tray. - **Compress, don't dump** — a card you must *read* has failed. - **Not an editor** — live writes capped at one-tap notes/rolls; real authorship deferred to the sweep. - **No silent auto-save to the wiki** — the shelf's value is being the "not yet canon" buffer. ## Depends on / relates to - Builds on the generation history/scratchpad (#138 — `GenerationResult` already carries a `session_id` FK, so half the plumbing exists). - Best built on top of the config-driven `GeneratorPanel` (#234). 🤖 Generated with [Claude Code](https://claude.com/claude-code)
claude-bot commented 2026-07-22 02:59:55 +00:00
Author
Contributor
Copy link

Broken down into sub-issues (all in the v3.11.0 milestone), on the unified ShelfCard model:

MVP slice — the core "everything relevant to tonight, at your fingertips" surface:

  • #239 — ShelfCard model + core API
  • #240 — per-session board surface
  • #241 — add to shelf (from Workbench + wiki)

Follow-on:

  • #242 — glance-compressed cards
  • #243 — spotlight / now-playing
  • #244 — scene packs
  • #245 — reveal-to-table
  • #246 — fast retrieval (⌘K + hotkeys)
  • #247 — end-of-session sweep
  • #248 — warm cold-open

Starting with the MVP slice (#239 → #240 → #241). Design the ShelfCard model + endpoints first, schema signed off before the migration.

🤖 Generated with Claude Code

**Broken down into sub-issues** (all in the v3.11.0 milestone), on the unified `ShelfCard` model: **MVP slice** — the core "everything relevant to tonight, at your fingertips" surface: - [ ] #239 — ShelfCard model + core API - [ ] #240 — per-session board surface - [ ] #241 — add to shelf (from Workbench + wiki) **Follow-on:** - [ ] #242 — glance-compressed cards - [ ] #243 — spotlight / now-playing - [ ] #244 — scene packs - [ ] #245 — reveal-to-table - [ ] #246 — fast retrieval (⌘K + hotkeys) - [ ] #247 — end-of-session sweep - [ ] #248 — warm cold-open Starting with the MVP slice (#239 → #240 → #241). Design the `ShelfCard` model + endpoints first, schema signed off before the migration. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
claude-bot commented 2026-07-22 04:16:30 +00:00
Author
Contributor
Copy link

Shelf MVP built and deployed to dev

The first three sub-issues are done and bundled in PR #249 (→ main, milestone v3.11.0), CI fully green:

  • #239 — ShelfCard model + migration 5a6b7c8d9e0f + GM-only CRUD API (/api/sessions/{id}/shelf) + 9 endpoint tests
  • #240 — /sessions/:id/shelf draggable board (freeform placement, tonight-notes, remove, empty state), linked from SessionDetail
  • #241 — shared AddToShelf control on every Workbench generation result and in the wiki entry GM row, defaulting to the campaign's in-progress/next session

Deployed feat/v3.11-session-shelf (64bb273) to the dev host for click-through: migration applied cleanly, all services healthy. Awaiting a hands-on pass before merge.

Remaining v3.11 slices stay open: #242 glance cards, #243 spotlight, #244 scene packs, #245 reveal-to-table, #246 fast retrieval, #247 end-of-session sweep, #248 warm cold-open, plus the #236 arc suggester.

### Shelf MVP built and deployed to dev The first three sub-issues are done and bundled in **PR #249** (→ `main`, milestone v3.11.0), CI fully green: - **#239** — `ShelfCard` model + migration `5a6b7c8d9e0f` + GM-only CRUD API (`/api/sessions/{id}/shelf`) + 9 endpoint tests - **#240** — `/sessions/:id/shelf` draggable board (freeform placement, tonight-notes, remove, empty state), linked from SessionDetail - **#241** — shared `AddToShelf` control on every Workbench generation result and in the wiki entry GM row, defaulting to the campaign's in-progress/next session Deployed `feat/v3.11-session-shelf` (`64bb273`) to the dev host for click-through: migration applied cleanly, all services healthy. Awaiting a hands-on pass before merge. Remaining v3.11 slices stay open: #242 glance cards, #243 spotlight, #244 scene packs, #245 reveal-to-table, #246 fast retrieval, #247 end-of-session sweep, #248 warm cold-open, plus the #236 arc suggester.
claude-bot commented 2026-07-22 06:45:55 +00:00
Author
Contributor
Copy link

Three more v3.11 slices landed (PR #251)

Merged to main and deployed to dev:

  • #243 Spotlight — a "now playing" stage (right dock); number keys 1‑9 / the card's stage button pick it, arrows or [ ] swap, Esc clears. The board card never moves.
  • #246 Fast retrieval — Ctrl‑K fuzzy quick-switcher (tonight's shelf first, then the wiki) + a header "Find" affordance. Unit-tested.
  • #236 Story-arc suggester — new async GM Workbench tool reading recent sessions + arcs + threads + wiki → candidate arcs in the result rail; "Accept" creates a CampaignArc. No migration; mirrors session_prep.

Shelf slices now done: glance cards (#242), spotlight (#243), fast retrieval (#246), plus the arc suggester (#236). Remaining v3.11: #244 scene packs, #245 reveal-to-table, #247 end-of-session sweep, #248 warm cold-open.

### Three more v3.11 slices landed (PR #251) Merged to `main` and deployed to dev: - **#243 Spotlight** — a "now playing" stage (right dock); number keys 1‑9 / the card's stage button pick it, arrows or `[` `]` swap, Esc clears. The board card never moves. - **#246 Fast retrieval** — Ctrl‑K fuzzy quick-switcher (tonight's shelf first, then the wiki) + a header "Find" affordance. Unit-tested. - **#236 Story-arc suggester** — new async GM Workbench tool reading recent sessions + arcs + threads + wiki → candidate arcs in the result rail; "Accept" creates a `CampaignArc`. No migration; mirrors `session_prep`. Shelf slices now done: glance cards (#242), spotlight (#243), fast retrieval (#246), plus the arc suggester (#236). Remaining v3.11: #244 scene packs, #245 reveal-to-table, #247 end-of-session sweep, #248 warm cold-open.
claude-bot commented 2026-07-27 18:48:26 +00:00
Author
Contributor
Copy link

Epic complete — the manual spine is done

The last three slices landed today: #244 scene packs (PR #264), #245 reveal-to-table (PR #265), #248 warm cold-open (PR #266). All of CI green on each.

Component checklist — all ten shipped:

  • Spatial board, not a list — #240
  • Glance-compressed cards — #242
  • Spotlight / "now playing" — #243
  • Scene packs — #244
  • Reveal-to-table — #245
  • Cards accrue "tonight" notes — #239/#240, harvested into canon on completion (#254)
  • Fast retrieval — #246
  • End-of-session sweep — #247
  • Warm cold-open — #248
  • Pull existing lore onto the shelf — #241

Plus the carry-forward lifecycle (#252, #254) and the AI arc suggester (#236) the milestone carried.

The guardrails held, and shaped the code:

  • Never auto-move the GM's cards — the biggest constraint on scene packs. Swapping scenes hides cards, it never reflows them; a hidden card's stored x/y is untouched, and cards keep their index in the full list so a never-placed card's fallback position doesn't drift either. The spotlight follows the same rule: a staged card stays staged across a scene swap.
  • Compress, don't dump — glance faces (#242), and the cold-open truncates a long recap with a link rather than dumping it above the board.
  • Not an editor — the only live writes are still one-tap notes, the scene tag, and the player-safe layer. Real authorship is still deferred to the sweep.
  • No silent auto-save to the wiki — nothing added here writes canon on its own. The sweep's promote is explicit, and the reveal writes only to the card's own player-safe layer.

Two things worth carrying into v3.12:

  1. Reveal surfaces are a registry, not a branch. _REVEAL_DISPATCH maps a surface name to a dispatcher, so the Foundry pillar's "push into the live scene" (#152) is one entry plus one vocabulary value — no schema change. Worth reusing the same shape for anything else that fans out to multiple destinations.
  2. The shelf's read path is now the natural insertion point for the listening layer. list_shelf already materializes carried pins and enriches with live wiki state on every read; #237's auto-surfaced cards want to land in a separate tray beside that, per this epic's "anything proactive only adds" guardrail — not merged into the board itself.

Migration head moved to d9e0f1a2b3c4 (shelf_reveals + shelf_cards.player_text); everything else in these three slices needed no schema change. BOT_CONTRACT_VERSION stays 1 — the new shelf_reveal event is additive.

Closing. The v3.11.0 milestone is clear.

🤖 Generated with Claude Code

### Epic complete — the manual spine is done The last three slices landed today: **#244 scene packs** (PR #264), **#245 reveal-to-table** (PR #265), **#248 warm cold-open** (PR #266). All of CI green on each. **Component checklist — all ten shipped:** - [x] **Spatial board, not a list** — #240 - [x] **Glance-compressed cards** — #242 - [x] **Spotlight / "now playing"** — #243 - [x] **Scene packs** — #244 - [x] **Reveal-to-table** — #245 - [x] **Cards accrue "tonight" notes** — #239/#240, harvested into canon on completion (#254) - [x] **Fast retrieval** — #246 - [x] **End-of-session sweep** — #247 - [x] **Warm cold-open** — #248 - [x] **Pull existing lore onto the shelf** — #241 Plus the carry-forward lifecycle (#252, #254) and the AI arc suggester (#236) the milestone carried. **The guardrails held, and shaped the code:** - *Never auto-move the GM's cards* — the biggest constraint on scene packs. Swapping scenes **hides** cards, it never reflows them; a hidden card's stored x/y is untouched, and cards keep their index in the full list so a never-placed card's fallback position doesn't drift either. The spotlight follows the same rule: a staged card stays staged across a scene swap. - *Compress, don't dump* — glance faces (#242), and the cold-open truncates a long recap with a link rather than dumping it above the board. - *Not an editor* — the only live writes are still one-tap notes, the scene tag, and the player-safe layer. Real authorship is still deferred to the sweep. - *No silent auto-save to the wiki* — nothing added here writes canon on its own. The sweep's promote is explicit, and the reveal writes only to the card's own player-safe layer. **Two things worth carrying into v3.12:** 1. **Reveal surfaces are a registry, not a branch.** `_REVEAL_DISPATCH` maps a surface name to a dispatcher, so the Foundry pillar's "push into the live scene" (#152) is one entry plus one vocabulary value — no schema change. Worth reusing the same shape for anything else that fans out to multiple destinations. 2. **The shelf's read path is now the natural insertion point for the listening layer.** `list_shelf` already materializes carried pins and enriches with live wiki state on every read; #237's auto-surfaced cards want to land in a *separate tray* beside that, per this epic's "anything proactive only adds" guardrail — not merged into the board itself. Migration head moved to `d9e0f1a2b3c4` (`shelf_reveals` + `shelf_cards.player_text`); everything else in these three slices needed no schema change. `BOT_CONTRACT_VERSION` stays **1** — the new `shelf_reveal` event is additive. Closing. The v3.11.0 milestone is clear. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
renovate/npm-vitest-vulnerability
chore/87-align-python-3.12
v4.3.0
v4.2.3
v4.2.2
v4.2.1
v4.2.0
v4.1.2
v4.1.1
v4.1.0
v4.0.1
v4.0.0
v3.11.4
v3.11.3
v3.11.2
v3.11.1
v3.11.0
v3.10.0
v3.9.1
v3.9.0
v3.8.0
v3.7.0
v3.6.1
v3.6.0
v3.5.0
v3.4.1
v3.4.0
v3.3.0
v3.2.0
v3.1.0
v3.0.0
v2.1.0
v2.0.0
v1.1.0
v1.0.0
v0.12.0
v0.11.0
v0.10.0
v0.9.1
v0.3.3
v0.9.0
v0.8.0
v0.3.2
v0.3.1
v0.3.0
v0.7.0
v0.6.0
v0.5.0
v0.4.0
v0.2.1
v0.2.0
v0.1.1
v0.1.0
Labels
Clear labels   
backend
Issue related to the backend

  
bot
Issue related to the bot

  
bug
Something is not working

  
duplicate
This issue or pull request already exists

  
enhancement
New feature

  
frontend
Issue related to the frontend

  
help wanted
Need some help

  
invalid
Something is wrong

  
question
More information is needed

  
recording
Issue related to the recording system

  
security
Security hardening / vulnerability work

  
wontfix
This won't be fixed

No labels
backend
bot
bug
duplicate
enhancement
frontend
help wanted
invalid
question
recording
security
wontfix
Milestone
Clear milestone
No items
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
rbrooks/Quest-Board#235
No description provided.