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

[Feature] Rules and bestiary lookup at the table and in Prep #553

New issue
Open
opened 2026-09-08 00:44:58 +00:00 by claude-bot · 4 comments
claude-bot commented 2026-09-08 00:44:58 +00:00
Contributor
Copy link

Requested by the owner in the v4.4.0 checkpoint A feedback (#535, GM answers, 2026-09-07): "I also would love it if I could reference rules / search bestiaries, which isn't currently a supported feature in Quest Board but I would love to have added." Alongside it, the same answer names the things a GM needs at the table: the beats and arcs laid out, name generation, and a fast way back into the wiki's history. This issue is the reference half.

What

A search over the rules and creatures of the campaign's game system, reachable from where a GM already works: Prep, the Shelf's search (Ctrl-K), and the live table surface of the redesign. A hit renders as Quest Board already renders game-aware content (a stat block in the structured schema from #130; a rule, condition or action as text with its source), can be put on the Shelf as a card with a GM side and a player-safe side, and carries its licence attribution.

Why it belongs here

Quest Board is already game-aware (v3.9.0: a game-system registry, structured stat blocks, a stat-conversion wizard) and already has the card and search surfaces a lookup would land on. What it lacks is the content and a way to search it. Self-hosting shapes the answer: content must be either bundled under a licence that allows redistribution or fetched from a source the operator can point at, and the lookup must work offline at a table with no dependence on a third party being up.

Open questions the investigation answers first

  • Which datasets exist for the systems Quest Board knows, under which licences, in which shapes (Pathfinder 2e remaster under ORC; D&D 5e SRD 5.1 under CC-BY-4.0; others).
  • Bundle, download-on-demand, or live API, and what each means for a self-hosted operator and for an in-person table with no internet.
  • How a monster maps onto the existing stat-block schema, and how a rule maps onto a Shelf card.
  • Whether the configured LLM should answer rules questions from the retrieved text, with citations, the way /ask answers from campaign history.

Not in scope

Anything that requires paid or non-redistributable content; a full rules engine; character sheets.

Milestone candidate: v4.5.0 Table & Safety Tools, on top of the v4.4.0 design system. The investigation is filed against this issue as a committed report under docs/design/, not the gitignored internal folder.

Requested by the owner in the v4.4.0 checkpoint A feedback (#535, GM answers, 2026-09-07): *"I also would love it if I could reference rules / search bestiaries, which isn't currently a supported feature in Quest Board but I would love to have added."* Alongside it, the same answer names the things a GM needs at the table: the beats and arcs laid out, name generation, and a fast way back into the wiki's history. This issue is the reference half. ## What A search over the rules and creatures of the campaign's game system, reachable from where a GM already works: Prep, the Shelf's search (Ctrl-K), and the live table surface of the redesign. A hit renders as Quest Board already renders game-aware content (a stat block in the structured schema from #130; a rule, condition or action as text with its source), can be put on the Shelf as a card with a GM side and a player-safe side, and carries its licence attribution. ## Why it belongs here Quest Board is already game-aware (v3.9.0: a game-system registry, structured stat blocks, a stat-conversion wizard) and already has the card and search surfaces a lookup would land on. What it lacks is the content and a way to search it. Self-hosting shapes the answer: content must be either bundled under a licence that allows redistribution or fetched from a source the operator can point at, and the lookup must work offline at a table with no dependence on a third party being up. ## Open questions the investigation answers first - Which datasets exist for the systems Quest Board knows, under which licences, in which shapes (Pathfinder 2e remaster under ORC; D&D 5e SRD 5.1 under CC-BY-4.0; others). - Bundle, download-on-demand, or live API, and what each means for a self-hosted operator and for an in-person table with no internet. - How a monster maps onto the existing stat-block schema, and how a rule maps onto a Shelf card. - Whether the configured LLM should answer rules questions from the retrieved text, with citations, the way `/ask` answers from campaign history. ## Not in scope Anything that requires paid or non-redistributable content; a full rules engine; character sheets. Milestone candidate: v4.5.0 Table & Safety Tools, on top of the v4.4.0 design system. The investigation is filed against this issue as a committed report under `docs/design/`, not the gitignored internal folder.
claude-bot commented 2026-09-08 01:02:13 +00:00
Author
Contributor
Copy link

Investigation done, committed as docs/design/rules-reference-investigation-2026-09.md (PR to follow). The short version:

Licences allow bundling, for two sources. Pathfinder 2e's remaster line is under the ORC licence (mechanics may be copied into software, commercially, with the ORC Notice and Paizo's attribution; proper nouns, lore and art are reserved). D&D's SRD 5.1 and 5.2.1 are CC-BY-4.0, irrevocably. Machine-readable forms: the Foundry pf2e packs (each record carries publication.license, so an ORC-only filter is trivial) and Open5e's data (per-document licences; srd-2014 and srd-2024). The Paizo Community Use Policy, which Archives of Nethys and pf2ools rely on, forbids commercial use, so neither is a foundation for a hosted product. The 2026-07 decision not to bundle content was right about that policy and is reversed here only for ORC and CC-BY material.

The codebase is close. The registry and versioned stat schemas already hold exactly a Monster Core or SRD creature's headline numbers; the stat-block renderer, the Shelf card and reveal pipeline, the Prep tool registry and the LLM call surface are reusable as they are. Missing: content, a table with a real index (the session tsvector search is the pattern to copy; the wiki search is a Python substring match that ignores stats), a reference snapshot kind on the Shelf, and structured citations.

Design: repo import scripts pull pinned upstream commits, filter by licence, drop reserved material (mechanics and rules text in, creature flavour paragraphs out), and write committed packs with a manifest; a reference_entries table seeded idempotently like the builtin schemas; GET /api/game-systems/{key}/reference?q=&kind=&level…; a "Look up" Prep tool, a third Ctrl-K section, a reference Shelf card (a condition's text is player-safe by default, a creature's stat block never is), a licences page, the same search inside the v4.4.0 Table mode, and later an ask-the-rules tool with {answer, citations[]} under json_schema.

Phases: 1 data and search (backend-only, can start now beside the redesign); 2 surfaces; 3 table and ask; 4 optional operator packs for OGL third-party books. Milestone candidate v4.5.0 for 2 and 3.

Decisions to confirm with the owner: bundle in the image rather than download-on-demand; start phase 1 now; the reserved-material rule as stated.

**Investigation done**, committed as `docs/design/rules-reference-investigation-2026-09.md` (PR to follow). The short version: **Licences allow bundling, for two sources.** Pathfinder 2e's remaster line is under the ORC licence (mechanics may be copied into software, commercially, with the ORC Notice and Paizo's attribution; proper nouns, lore and art are reserved). D&D's SRD 5.1 and 5.2.1 are CC-BY-4.0, irrevocably. Machine-readable forms: the Foundry pf2e packs (each record carries `publication.license`, so an ORC-only filter is trivial) and Open5e's data (per-document licences; `srd-2014` and `srd-2024`). The Paizo Community Use Policy, which Archives of Nethys and pf2ools rely on, forbids commercial use, so neither is a foundation for a hosted product. The 2026-07 decision not to bundle content was right about that policy and is reversed here only for ORC and CC-BY material. **The codebase is close.** The registry and versioned stat schemas already hold exactly a Monster Core or SRD creature's headline numbers; the stat-block renderer, the Shelf card and reveal pipeline, the Prep tool registry and the LLM call surface are reusable as they are. Missing: content, a table with a real index (the session `tsvector` search is the pattern to copy; the wiki search is a Python substring match that ignores `stats`), a `reference` snapshot kind on the Shelf, and structured citations. **Design:** repo import scripts pull pinned upstream commits, filter by licence, drop reserved material (mechanics and rules text in, creature flavour paragraphs out), and write committed packs with a manifest; a `reference_entries` table seeded idempotently like the builtin schemas; `GET /api/game-systems/{key}/reference?q=&kind=&level…`; a "Look up" Prep tool, a third Ctrl-K section, a `reference` Shelf card (a condition's text is player-safe by default, a creature's stat block never is), a licences page, the same search inside the v4.4.0 Table mode, and later an ask-the-rules tool with `{answer, citations[]}` under `json_schema`. **Phases:** 1 data and search (backend-only, can start now beside the redesign); 2 surfaces; 3 table and ask; 4 optional operator packs for OGL third-party books. Milestone candidate v4.5.0 for 2 and 3. **Decisions to confirm with the owner:** bundle in the image rather than download-on-demand; start phase 1 now; the reserved-material rule as stated.
claude-bot commented 2026-09-08 05:57:08 +00:00
Author
Contributor
Copy link

Direction confirmed by the owner (2026-09-08): importer-first. Quest Board ships no game content. People load content they have, in formats already in use, and affirm at import (a required checkbox backed by a versioned, server-recorded affirmation) that they are allowed to; starter packs built from ORC and CC-BY sources are release assets fetched on request, never bundled; exports carry licences forward and withhold what may not be shared; and a host can act on rightsholder notices (#555, filed).

Formats in phase 1: the native Quest Board pack (also the export format; a bare JSON array and a CSV for hand-written homebrew), Foundry VTT documents (the common denominator of every system the owner plays: PF2e, D&D 5e, Ryuutama, Discworld, Ember), 5etools homebrew JSON, Dungeon Master's Vault .orcbrew, and Open5e JSON. Two scopes (instance by an admin, campaign by a GM), campaign wins on a name clash, GM-only visibility by default for campaign packs, sanitised HTML, size caps, a private-address guard on URL fetches.

The contract is docs/design/content-packs-spec.md (PR to follow). Phase 1 is starting now as six lanes: foundation; Foundry adapter; 5etools and orcbrew adapters; Open5e adapter and starter scripts; notices (#555); the minimal Content packs screen. Backend-first, beside the redesign.

**Direction confirmed by the owner (2026-09-08): importer-first.** Quest Board ships no game content. People load content they have, in formats already in use, and **affirm at import** (a required checkbox backed by a versioned, server-recorded affirmation) that they are allowed to; starter packs built from ORC and CC-BY sources are release assets fetched on request, never bundled; exports carry licences forward and withhold what may not be shared; and a host can act on rightsholder notices (#555, filed). Formats in phase 1: the native Quest Board pack (also the export format; a bare JSON array and a CSV for hand-written homebrew), **Foundry VTT documents** (the common denominator of every system the owner plays: PF2e, D&D 5e, Ryuutama, Discworld, Ember), 5etools homebrew JSON, Dungeon Master's Vault `.orcbrew`, and Open5e JSON. Two scopes (instance by an admin, campaign by a GM), campaign wins on a name clash, GM-only visibility by default for campaign packs, sanitised HTML, size caps, a private-address guard on URL fetches. The contract is `docs/design/content-packs-spec.md` (PR to follow). Phase 1 is starting now as six lanes: foundation; Foundry adapter; 5etools and orcbrew adapters; Open5e adapter and starter scripts; notices (#555); the minimal Content packs screen. Backend-first, beside the redesign.
claude-bot commented 2026-09-08 07:03:05 +00:00
Author
Contributor
Copy link

Phase 1 foundation merged (PR #557, 531c2a9): the content_packs and reference_entries tables (migration 1c2d3e4f5a6b), the import pipeline with the server-enforced affirmation, format detection, the native .qbpack / JSON array / CSV adapter, sanitisation and caps, URL fetch with the private-address guard, full-text search with campaign-over-instance precedence and GM-only visibility, export with a withheld list, and every endpoint for members, admins and GMs. 118 new tests; the whole backend suite passes. docs/CONTENT-PACKS.md documents the format and the affirmation.

Adapter lanes are built and rebasing onto it: Foundry VTT documents (PF2e and 5e maps, generic fallback, licence read from all four publication paths), 5etools JSON and .orcbrew (EDN), Open5e JSON plus the two starter-pack build scripts. The notices lane (#555) and the Content packs screen are in progress on the same base. The spec is updated with the conventions the build settled (PR #558).

**Phase 1 foundation merged** (PR #557, `531c2a9`): the `content_packs` and `reference_entries` tables (migration `1c2d3e4f5a6b`), the import pipeline with the server-enforced affirmation, format detection, the native `.qbpack` / JSON array / CSV adapter, sanitisation and caps, URL fetch with the private-address guard, full-text search with campaign-over-instance precedence and GM-only visibility, export with a withheld list, and every endpoint for members, admins and GMs. 118 new tests; the whole backend suite passes. `docs/CONTENT-PACKS.md` documents the format and the affirmation. Adapter lanes are built and rebasing onto it: Foundry VTT documents (PF2e and 5e maps, generic fallback, licence read from all four publication paths), 5etools JSON and `.orcbrew` (EDN), Open5e JSON plus the two starter-pack build scripts. The notices lane (#555) and the Content packs screen are in progress on the same base. The spec is updated with the conventions the build settled (PR #558).
claude-bot commented 2026-09-08 08:38:18 +00:00
Author
Contributor
Copy link

Phase 1 (import, search, export, the screen) is on main and deployed to dev (main d87c08c, dev at https://questboard-dev.rhoving.com/).

PRs, in merge order

  • #557 foundation: content_packs + reference_entries (migration 1c2d3e4f5a6b), the adapter contract, the import pipeline with the affirmation gate, local search, export with per-record licence withholding, the endpoints.
  • #558 spec: the conventions the build settled, recorded in docs/design/content-packs-spec.md.
  • #559 Foundry VTT reader (pf2e and dnd5e mapped, generic fallback, licence read from all four places Foundry keeps it), plus the first fix to questboard.sniff, which had been claiming every bare JSON array.
  • #560 5etools and Dungeon Master's Vault .orcbrew readers, adapter warnings reaching the importer, a CRLF fix for .orcbrew files saved on Windows.
  • #561 rightsholder notices and takedown (closes #555).
  • #562 Foundry fixes found by the starter build: Statistics and Defences sections, bare enrichers rendered as prose, and the native-array detection rule closed (a truncated first record is native only when kind is inside the sniff window; the writer emits kind first and a test pins that).
  • #563 the ContentPacks screen (Admin → Content packs tab; a GM panel on the campaign page), plus the affirmation 422 brought back to the project's one error shape (detail string, wording under affirmation).
  • #564 Open5e reader and the two starter-pack build scripts under scripts/content/ (SRD 5.1/5.2.1 under CC-BY, and the ORC-licensed Pathfinder 2e records with flavour text removed). Starter packs are release assets fetched on request, never bundled.

Dev check: migration head 2d3e4f5a6b7c applied, DETECT_ORDER = questboard, foundry, fivetools, orcbrew, open5e, the content-pack and notice routes answer 401 unauthenticated, the frontend bundle carries the screen, no worker or beat errors. An import through the UI on dev still wants a human with an OIDC login; the invented fixtures under webapp/backend/tests/fixtures/reference/ are safe files to try.

Decisions worth keeping

  • Quest Board ships no game content; people import what they have, affirm they are entitled to at the point of import, and the affirmation version they accepted is stored on the pack.
  • Adapters never guess a licence the file does not declare; the exporter withholds anything without one.
  • The .qbpack format is the native and export shape; a hand-written bare JSON array must put kind first (documented in docs/CONTENT-PACKS.md).

Still open under this issue

  • Phase 2: player-facing lookup surfaces (search from the session shelf, the "ask the rules" box) and the campaign lookup screen restyled by the v4.4.0 rebuild.
  • Phase 3: table integration (reveal a looked-up creature to the table, stat conversion from an imported block).
  • Follow-ups noted on the PRs: publishing the two starter packs as release assets on the next release; a notices screen in the admin area (#555 comment); the 5e proficiency-only saves/skills if we ever decide to derive bonuses.
**Phase 1 (import, search, export, the screen) is on main and deployed to dev** (main `d87c08c`, dev at https://questboard-dev.rhoving.com/). **PRs, in merge order** - #557 foundation: `content_packs` + `reference_entries` (migration `1c2d3e4f5a6b`), the adapter contract, the import pipeline with the affirmation gate, local search, export with per-record licence withholding, the endpoints. - #558 spec: the conventions the build settled, recorded in `docs/design/content-packs-spec.md`. - #559 Foundry VTT reader (pf2e and dnd5e mapped, generic fallback, licence read from all four places Foundry keeps it), plus the first fix to `questboard.sniff`, which had been claiming every bare JSON array. - #560 5etools and Dungeon Master's Vault `.orcbrew` readers, adapter warnings reaching the importer, a CRLF fix for `.orcbrew` files saved on Windows. - #561 rightsholder notices and takedown (closes #555). - #562 Foundry fixes found by the starter build: Statistics and Defences sections, bare enrichers rendered as prose, and the native-array detection rule closed (a truncated first record is native only when `kind` is inside the sniff window; the writer emits `kind` first and a test pins that). - #563 the `ContentPacks` screen (Admin → Content packs tab; a GM panel on the campaign page), plus the affirmation 422 brought back to the project's one error shape (`detail` string, wording under `affirmation`). - #564 Open5e reader and the two starter-pack build scripts under `scripts/content/` (SRD 5.1/5.2.1 under CC-BY, and the ORC-licensed Pathfinder 2e records with flavour text removed). Starter packs are release assets fetched on request, never bundled. **Dev check**: migration head `2d3e4f5a6b7c` applied, `DETECT_ORDER` = questboard, foundry, fivetools, orcbrew, open5e, the content-pack and notice routes answer 401 unauthenticated, the frontend bundle carries the screen, no worker or beat errors. An import through the UI on dev still wants a human with an OIDC login; the invented fixtures under `webapp/backend/tests/fixtures/reference/` are safe files to try. **Decisions worth keeping** - Quest Board ships no game content; people import what they have, affirm they are entitled to at the point of import, and the affirmation version they accepted is stored on the pack. - Adapters never guess a licence the file does not declare; the exporter withholds anything without one. - The `.qbpack` format is the native and export shape; a hand-written bare JSON array must put `kind` first (documented in `docs/CONTENT-PACKS.md`). **Still open under this issue** - Phase 2: player-facing lookup surfaces (search from the session shelf, the "ask the rules" box) and the campaign lookup screen restyled by the v4.4.0 rebuild. - Phase 3: table integration (reveal a looked-up creature to the table, stat conversion from an imported block). - Follow-ups noted on the PRs: publishing the two starter packs as release assets on the next release; a notices screen in the admin area (#555 comment); the 5e proficiency-only saves/skills if we ever decide to derive bonuses.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
ui/table-notes-label
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
No milestone
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#553
No description provided.