#593 - [UX] Wiki redesign — design record - rbrooks/Quest-Board

claude-bot commented

2026-09-11 00:02:30 +00:00

Collaborator

The wiki design agreed with the owner on 2026-09-10, over a long back-and-forth. This issue records what the wiki becomes and why. Build issues get split from it when #366 plans the lanes. Mockups of it are being added to the round-two comparison (#363).

Ground rules

No data is lost. Every field an article has today survives. Some move to a better home, and each move is listed under "Storage" below.
Quest Board is hosted for other groups, not only the owner's. Where tables differ, the design offers settings with presets rather than hard-coded behaviour. Reputation levels and edit permissions are examples.
Players will be heavy readers. Today the GM does most of the reading, but that changes as players adopt Quest Board and the Foundry integration. So articles are designed to be read first, and editing is a mode you switch into.

What the wiki is for

Remembering: "who was that?" This needs fast search, a good one-line summary, and when someone was last seen.
Exploring: following a thread from one article to the next. This needs links everywhere, "Mentioned in" lists, and hover previews.
Running: the GM mid-session needing a save DC or the party's location. This needs stat blocks and the map one tap away, including wiki search inside Table mode (round-one feedback).

For navigation, the 13 existing types are grouped as People, Places, Groups, Things, Events, Lore. Quest is added as a type (see below).

One article, different visibility

GM blocks in the text (:::gm … :::) sit wherever the secret belongs. The server removes them before an article is sent to a player; hiding them in the browser is not enough.
GM blocks replace the separate GM notes box. Existing gm_notes move into a GM block at the top of the text, so nothing is lost.
GM blocks are visually distinct, so the GM can always tell at a glance that players can't see them.
The existing per-item visibility on sidebar and timeline items (everyone / GM / owning player) stays.
View as player: a toggle that shows the GM exactly what players see.
A GM block can later be revealed at the table, using the existing reveal feature (shelf_reveals).

Links

Syntax: [[Title]], [[Title|shown text]], and new [[Title#Section]].
Links are saved as records whenever an article is saved. That powers "Mentioned in", connection views, "related" and hover previews without scanning every article's text.
Links to missing articles get their own style, and clicking one creates the article with the title filled in.
Linking to rules entries: [[Frightened]] links to the rulebook entry (see Rules).
Existing behaviour kept: renaming keeps the old title as an alias, so old links still work. The rename can now also offer to update links in other articles.

Editor

Owner decision: a Markdown editor with preview.

Layout: preview side by side on a computer; a Write/Preview switch on a phone. The toolbar stays for people who don't know Markdown. Syntax highlighting and keyboard shortcuts (Ctrl+B, I, K).
[[ autocomplete: matches titles and aliases, shows each article's type and summary, and ends with a "Create '…'" option.
Full Markdown: tables, strikethrough, checkboxes, footnotes, callout boxes.
Embeds: ![[Map: Otari]], ![[Goblin Warrior]] and ![[handout]] place a map, stat block or handout inside an article.
Pasting:
- A pasted or dragged-in image uploads through image_service (the existing checks and re-encoding).
- Rich text pasted from Docs or Word becomes Markdown.
Templates for each type, which each campaign can edit. For example, a new NPC starts with Appearance, Personality, Wants and a Secrets GM block.
Your edit is saved on your device as you type, with a warning before leaving unsaved changes.
Section editing: edit a single heading's section, which also suits phones.
Warning when two people edit (owner decision; no live co-editing). If someone saved after you opened the article, you see both versions and choose.
History: a side-by-side comparison of versions, plus a campaign-wide recent changes list. That list also feeds the front page.

Edit permissions, a campaign setting

Owner decision: four options.

GM only.
Players edit their own pages. This is the default and today's behaviour.
Players edit everything.
Players suggest edits for GM approval, reusing the existing approval list for suggestions from recordings.

Wiki health

A GM page that small groups can ignore:

Wanted pages: linked but not written.
Unlinked mentions, in both directions.
Duplicate titles, with a way to tell them apart.
Orphan pages that nothing links to.
Stale pages, e.g. "last edited in session 3, appeared in session 12".
Merge duplicates: keep both names as aliases and repoint their links. Suggestions from recordings do produce duplicates.

Stat blocks: shaped for Foundry

Owner's goal: a complete copy of the Foundry character sheet, kept in sync both ways in real time. Create a character in the wiki, flesh them out, and find them ready in Foundry. The sync itself is v5.x work (#13, #14, #157), not this redesign, but the redesign must not block it.

Store the game system's own character record (Foundry's actor document, including its embedded items: strikes, actions, spells, feats, gear) as the source of truth. Draw the stat block from it. Don't invent our own format and translate both ways: every translation drops fields, and a two-way sync through a lossy format slowly damages characters.
Step before sync: import a Foundry actor's Export Data JSON onto an article. That's the same format the sync will use, so nothing is redone later.
The rulebook importer must keep the whole record. Today foundry_maps/pf2e.py:extra() keeps system minus the consumed keys and drops the embedded items, turning them into text. That's readable, but it can't round-trip back to Foundry.
Existing stat blocks stay: the 12-field schema (#139) becomes the simple stat block for campaigns without Foundry.
Players' characters get a stat block too, mirrored from Foundry. Who may edit it should follow Foundry's ownership rules; decide in v5.x.

Rules content

Keep it in reference_entries (#553), not as wiki articles, for three reasons:

Size: thousands of entries against a campaign's dozens.
Licensing: material that can't be redistributed must stay out of campaign exports.
Updates: re-importing a pack would fight with edits.

It should still feel like part of the wiki:

One search box, with rules results tagged.
[[links]] and hover previews work for rules entries.
The wiki gets a Rules section.
"Make it mine" copies a rules entry into an editable campaign article that remembers its source.
House rules are ordinary articles.

Maps

An atlas is a chain of zoom links: a map, then more detailed maps of parts of it. A trail leads back up, and the party's location carries upward.
Travel links connect any map to any map, with no parent–child relationship. That covers portals, teleport circles and ship routes, with a marker at each end so it works both ways. This is how a portal leads to another continent's atlas with its own 1–4 levels.
No depth limit; designed for 3–4 levels (the owner mostly expects 3). Uneven branching is normal: a marker with no map behind it just opens its article.
Underground is a separate atlas reached through entrance markers. A Surface/Underground layer switch is a later option.
Maps are images the group uploads, from Inkarnate, Wonderdraft, purchased maps or scans. No drawing tool.
Markers point to articles (a place, event, quest or rumour) and have kinds and visibility. A GM-only marker stays hidden until revealed.
Player markers (owner decision): players add their own and choose "Only me and the GM", "The party" or "Everyone". The GM always sees every marker, and the labels say so.
Party marker and trail:
- The GM records where the party ended each session, and each waypoint links to that session.
- The GM sets it on the most detailed map and higher levels follow.
- The trail continues across portals.
- Later: the event log suggests "the party moved to X" for the GM to confirm.
Filters, e.g. "show the Guild's holdings" or "show quest markers".
Practical needs:
- Uploads, and tiling large images so they stay smooth on phones.
- Map images must be included in backups. Check whether the media volume is covered today.

Organizations

Member list built from relationships, with role or rank, alive or dead, and last seen.
Relationships gain a start and end session ("member of, until session 9"), the way aliases already can.
Sub-groups and links between groups (allied, rival, at war), shown as a small diagram.
Territory shown on the map.
The party's reputation with each organization (owner: yes). PF2e's levels are the default preset: Revered, Admired, Liked, Ignored, Disliked, Hated, Hunted. Campaigns can set their own levels. Each change is recorded against a session.
GM-only sections for true goals and the real leader.

Timelines

Owner decision: in-world dates, without a full custom calendar.

An in-world date is shown the way the setting writes it ("3 Rainmonth, 812"), plus a hidden number that keeps the order correct.
Two clocks on one event: "happened in 4412, the party learned of it in session 7".
Sessions record their in-world start and end dates, so time visibly passes. The map trail can then say "12 days on the road".
A campaign timeline: every article's timeline items plus session events, merged, and filterable by type or article.
This covers most of #126. #126's full calendar definition (months, weekdays) stays there as a later option.

Handouts

Owner: a mix of images, text and PDFs, sometimes given to a single player.

A handout is a document article with a file attached.
It's revealed through the existing reveal feature, which already supports choosing players and withdrawing a reveal.
Players get a Handouts collection sorted by session, with their personal handouts marked.
A torn letter is revealed in pieces as several reveals.
Handouts can join Foundry journal sync later.
This reshapes #123: no separate handout table, and reveals are reused. The new design allows handouts players upload, which #123 had ruled out.

Quests

Owner: yes, quests become wiki articles.

Quests become articles of type Quest, with quest-specific details on top.
- Status: rumoured, active, completed, failed, abandoned.
- An objectives checklist with visibility per objective, so a hidden objective appears once discovered.
- Who gave it, the reward (links to items and gold), and where (quest markers on the map).
Main quests and side quests, with arcs (campaign_arcs) as the chapters above them.
Status changes on the quest's timeline.
A quest log for players, showing only what they know, with their own notes. Players can post a rumour for the GM to confirm.
Migration from plot_threads, one to one:
- title stays the title
- notes become a GM block
- player_summary becomes the summary
- status carries over
- player_visible becomes visibility
- the introduced and resolved sessions carry over
- linked_lore_entry_id becomes a relationship

Parties

Owner: yes, several per campaign.

Several parties per campaign (West Marches, split parties). One is created by default, so most groups never notice.
Membership over time (owner request): members join and leave at a session, with an optional in-world date and a reason: joined, left, retired, died, captured, or swapped characters.
- The party page shows current members, then former members with their dates.
- A player leaving the game is distinct from a player swapping characters.
- This builds on campaign_characters and the per-session character record (#330).
- Characters can move between parties.
The party page is where players land in the wiki:
- members, with companions, mounts and vehicles
- location, trail and home base
- active quests
- shared loot and the party fund
- XP and level
- reputation
- allies and enemies
- a party timeline

Items

Owner: include unidentified items.

Two tiers: everyday loot stays a ledger line; notable items get an article, and any ledger line can be turned into one.
Holders are characters, the party pool, an NPC, or a place. Today loot_entries.holder_user_id is a user, so a player with two characters can't say which one has it.
Custody history over time: found, given, stolen, each with a session.
Unidentified items: players see the apparent name and description, and the GM sees the truth. Identifying reveals it.
"Make it mine" from a rules entry brings the real stats.
When Foundry sync arrives, a character's inventory mirrors Foundry and the party pool stays Quest Board's.

Front page

A map showing where the party is, recently revealed and updated articles, and the people the party has met.

Storage (nothing lost)

Articles (lore_entries) stay the core.
New:
- saved links between articles
- maps, map links (zoom and travel) and markers
- parties and party memberships (with time spans)
- quest details
- reputation levels and reputation changes
- item custody
Changed:
- relationships gain start and end sessions
- loot holders become characters
- the stat block can hold a system's own character record (versioned, as today)
- timeline items gain world_date {label, sort}
- sessions gain in-world dates
Moved: gm_notes into a GM block, and plot_threads into quest articles.
Export and import must carry all of it, including aliases (#580).

Broken today: fix in the rebuild, not separately

Owner decision: fix these as part of the rebuild.

Table and underline toolbar buttons. The article text is displayed by react-markdown with no GFM extension, so tables don't render, and <u> isn't converted into underlining. Found by reading the code; confirm in the rebuild.
Missing link targets render as grey dead text.
No [[ autocomplete.
No conflict check on PATCH /campaigns/{id}/lore/{entry_id}; the last save wins silently.
Duplicate titles resolve arbitrarily: buildWikiEntryLookup keeps whichever comes last.
The toolbar's image button only accepts a URL.

Mockups (#363)

Wiki screens are being added to both round-two designs, each in phone and desktop frames:

Wiki home and search.
An NPC article with its stat block (GM on the desktop, player on the phone).
Editing.
The map.
The party.
A quest.

UX milestone: #363, #364, #366
Reshaped by this design: #123, #126
Rulebook imports and stat blocks: #553, #139
Foundry: #13, #14, #157
Also affected: #330, #580

The wiki design agreed with the owner on 2026-09-10, over a long back-and-forth. This issue records *what* the wiki becomes and *why*. Build issues get split from it when #366 plans the lanes. Mockups of it are being added to the round-two comparison (#363). **Ground rules** - **No data is lost.** Every field an article has today survives. Some move to a better home, and each move is listed under "Storage" below. - **Quest Board is hosted for other groups**, not only the owner's. Where tables differ, the design offers settings with presets rather than hard-coded behaviour. Reputation levels and edit permissions are examples. - **Players will be heavy readers.** Today the GM does most of the reading, but that changes as players adopt Quest Board and the Foundry integration. So articles are designed to be read first, and editing is a mode you switch into. --- ## What the wiki is for 1. **Remembering:** "who was that?" This needs fast search, a good one-line summary, and when someone was last seen. 2. **Exploring:** following a thread from one article to the next. This needs links everywhere, "Mentioned in" lists, and hover previews. 3. **Running:** the GM mid-session needing a save DC or the party's location. This needs stat blocks and the map one tap away, including wiki search inside Table mode (round-one feedback). For navigation, the 13 existing types are grouped as **People, Places, Groups, Things, Events, Lore**. **Quest** is added as a type (see below). ## One article, different visibility - **GM blocks in the text** (`:::gm … :::`) sit wherever the secret belongs. **The server removes them** before an article is sent to a player; hiding them in the browser is not enough. - GM blocks **replace the separate GM notes box**. Existing `gm_notes` move into a GM block at the top of the text, so nothing is lost. - GM blocks are **visually distinct**, so the GM can always tell at a glance that players can't see them. - The existing per-item visibility on sidebar and timeline items (everyone / GM / owning player) stays. - **View as player:** a toggle that shows the GM exactly what players see. - A GM block can later be revealed at the table, using the existing reveal feature (`shelf_reveals`). ## Links - **Syntax:** `[[Title]]`, `[[Title|shown text]]`, and new `[[Title#Section]]`. - **Links are saved as records** whenever an article is saved. That powers "Mentioned in", connection views, "related" and hover previews without scanning every article's text. - **Links to missing articles** get their own style, and clicking one creates the article with the title filled in. - **Linking to rules entries:** `[[Frightened]]` links to the rulebook entry (see Rules). - **Existing behaviour kept:** renaming keeps the old title as an alias, so old links still work. The rename can now also offer to update links in other articles. ## Editor **Owner decision: a Markdown editor with preview.** - **Layout:** preview side by side on a computer; a Write/Preview switch on a phone. The toolbar stays for people who don't know Markdown. Syntax highlighting and keyboard shortcuts (Ctrl+B, I, K). - **`[[` autocomplete:** matches titles and aliases, shows each article's type and summary, and ends with a "Create '…'" option. - **Full Markdown:** tables, strikethrough, checkboxes, footnotes, callout boxes. - **Embeds:** `![[Map: Otari]]`, `![[Goblin Warrior]]` and `![[handout]]` place a map, stat block or handout inside an article. - **Pasting:** - A pasted or dragged-in image uploads through `image_service` (the existing checks and re-encoding). - Rich text pasted from Docs or Word becomes Markdown. - **Templates for each type,** which each campaign can edit. For example, a new NPC starts with Appearance, Personality, Wants and a Secrets GM block. - **Your edit is saved on your device as you type,** with a warning before leaving unsaved changes. - **Section editing:** edit a single heading's section, which also suits phones. - **Warning when two people edit** (owner decision; no live co-editing). If someone saved after you opened the article, you see both versions and choose. - **History:** a side-by-side comparison of versions, plus a campaign-wide **recent changes** list. That list also feeds the front page. ### Edit permissions, a campaign setting Owner decision: four options. 1. GM only. 2. Players edit their own pages. **This is the default and today's behaviour.** 3. Players edit everything. 4. Players suggest edits for GM approval, reusing the existing approval list for suggestions from recordings. ### Wiki health A GM page that small groups can ignore: - Wanted pages: linked but not written. - Unlinked mentions, in both directions. - Duplicate titles, with a way to tell them apart. - Orphan pages that nothing links to. - Stale pages, e.g. "last edited in session 3, appeared in session 12". - **Merge duplicates:** keep both names as aliases and repoint their links. Suggestions from recordings do produce duplicates. ## Stat blocks: shaped for Foundry **Owner's goal:** a complete copy of the Foundry character sheet, kept in sync both ways in real time. Create a character in the wiki, flesh them out, and find them ready in Foundry. The sync itself is v5.x work (#13, #14, #157), not this redesign, but the redesign must not block it. - **Store the game system's own character record** (Foundry's actor document, *including its embedded items*: strikes, actions, spells, feats, gear) as the source of truth. Draw the stat block from it. Don't invent our own format and translate both ways: every translation drops fields, and a two-way sync through a lossy format slowly damages characters. - **Step before sync:** import a Foundry actor's **Export Data** JSON onto an article. That's the same format the sync will use, so nothing is redone later. - **The rulebook importer must keep the whole record.** Today `foundry_maps/pf2e.py:extra()` keeps `system` minus the consumed keys and **drops the embedded items**, turning them into text. That's readable, but it can't round-trip back to Foundry. - **Existing stat blocks stay:** the 12-field schema (#139) becomes the simple stat block for campaigns without Foundry. - **Players' characters get a stat block too,** mirrored from Foundry. Who may edit it should follow Foundry's ownership rules; decide in v5.x. ## Rules content Keep it in `reference_entries` (#553), not as wiki articles, for three reasons: - **Size:** thousands of entries against a campaign's dozens. - **Licensing:** material that can't be redistributed must stay out of campaign exports. - **Updates:** re-importing a pack would fight with edits. It should still feel like part of the wiki: - One search box, with rules results tagged. - `[[links]]` and hover previews work for rules entries. - The wiki gets a Rules section. - **"Make it mine"** copies a rules entry into an editable campaign article that remembers its source. - House rules are ordinary articles. ## Maps - **An atlas is a chain of zoom links:** a map, then more detailed maps of parts of it. A trail leads back up, and the party's location carries upward. - **Travel links connect any map to any map,** with no parent–child relationship. That covers portals, teleport circles and ship routes, with a marker at each end so it works both ways. This is how a portal leads to another continent's atlas with its own 1–4 levels. - **No depth limit;** designed for 3–4 levels (the owner mostly expects 3). Uneven branching is normal: a marker with no map behind it just opens its article. - **Underground** is a separate atlas reached through entrance markers. A Surface/Underground layer switch is a later option. - **Maps are images the group uploads,** from Inkarnate, Wonderdraft, purchased maps or scans. No drawing tool. - **Markers point to articles** (a place, event, quest or rumour) and have kinds and visibility. A GM-only marker stays hidden until revealed. - **Player markers** (owner decision): players add their own and choose "Only me and the GM", "The party" or "Everyone". **The GM always sees every marker,** and the labels say so. - **Party marker and trail:** - The GM records where the party ended each session, and each waypoint links to that session. - The GM sets it on the most detailed map and higher levels follow. - The trail continues across portals. - Later: the event log suggests "the party moved to X" for the GM to confirm. - **Filters,** e.g. "show the Guild's holdings" or "show quest markers". - **Practical needs:** - Uploads, and tiling large images so they stay smooth on phones. - Map images must be **included in backups**. Check whether the media volume is covered today. ## Organizations - **Member list** built from relationships, with role or rank, alive or dead, and last seen. - **Relationships gain a start and end session** ("member of, until session 9"), the way aliases already can. - **Sub-groups and links between groups** (allied, rival, at war), shown as a small diagram. - **Territory** shown on the map. - **The party's reputation** with each organization (owner: yes). PF2e's levels are the default preset: Revered, Admired, Liked, Ignored, Disliked, Hated, Hunted. **Campaigns can set their own levels.** Each change is recorded against a session. - GM-only sections for true goals and the real leader. ## Timelines Owner decision: in-world dates, **without** a full custom calendar. - **An in-world date** is shown the way the setting writes it ("3 Rainmonth, 812"), plus a hidden number that keeps the order correct. - **Two clocks on one event:** "happened in 4412, the party learned of it in session 7". - **Sessions record their in-world start and end dates,** so time visibly passes. The map trail can then say "12 days on the road". - **A campaign timeline:** every article's timeline items plus session events, merged, and filterable by type or article. - This covers most of **#126**. #126's full calendar definition (months, weekdays) stays there as a later option. ## Handouts Owner: a mix of images, text and PDFs, sometimes given to a single player. - A handout is a **document article with a file attached**. - It's revealed through the existing reveal feature, which already supports **choosing players** and withdrawing a reveal. - Players get a **Handouts collection** sorted by session, with their personal handouts marked. - A torn letter is revealed in pieces as several reveals. - Handouts can join Foundry journal sync later. - This reshapes **#123**: no separate handout table, and reveals are reused. The new design allows handouts players upload, which #123 had ruled out. ## Quests Owner: yes, quests become wiki articles. - **Quests become articles** of type Quest, with quest-specific details on top. - Status: rumoured, active, completed, failed, abandoned. - An objectives checklist with **visibility per objective**, so a hidden objective appears once discovered. - Who gave it, the reward (links to items and gold), and where (quest markers on the map). - **Main quests and side quests,** with arcs (`campaign_arcs`) as the chapters above them. - **Status changes on the quest's timeline.** - **A quest log for players**, showing only what they know, with their own notes. Players can post a rumour for the GM to confirm. - **Migration from `plot_threads`, one to one:** - title stays the title - `notes` become a GM block - `player_summary` becomes the summary - `status` carries over - `player_visible` becomes visibility - the introduced and resolved sessions carry over - `linked_lore_entry_id` becomes a relationship ## Parties Owner: yes, several per campaign. - **Several parties per campaign** (West Marches, split parties). One is created by default, so most groups never notice. - **Membership over time** (owner request): members join and leave at a session, with an optional in-world date and a reason: joined, left, retired, died, captured, or swapped characters. - The party page shows current members, then **former members** with their dates. - A player leaving the game is distinct from a player swapping characters. - This builds on `campaign_characters` and the per-session character record (#330). - Characters can move between parties. - **The party page** is where players land in the wiki: - members, with companions, mounts and vehicles - location, trail and home base - active quests - shared loot and the party fund - XP and level - reputation - allies and enemies - a party timeline ## Items Owner: include unidentified items. - **Two tiers:** everyday loot stays a ledger line; notable items get an article, and any ledger line can be turned into one. - **Holders are characters,** the party pool, an NPC, or a place. Today `loot_entries.holder_user_id` is a *user*, so a player with two characters can't say which one has it. - **Custody history over time:** found, given, stolen, each with a session. - **Unidentified items:** players see the apparent name and description, and the GM sees the truth. Identifying reveals it. - **"Make it mine"** from a rules entry brings the real stats. - When Foundry sync arrives, a character's inventory mirrors Foundry and the party pool stays Quest Board's. ## Front page A map showing where the party is, recently revealed and updated articles, and the people the party has met. --- ## Storage (nothing lost) - **Articles (`lore_entries`) stay the core.** - **New:** - saved links between articles - maps, map links (zoom and travel) and markers - parties and party memberships (with time spans) - quest details - reputation levels and reputation changes - item custody - **Changed:** - relationships gain start and end sessions - loot holders become characters - the stat block can hold a system's own character record (versioned, as today) - timeline items gain `world_date {label, sort}` - sessions gain in-world dates - **Moved:** `gm_notes` into a GM block, and `plot_threads` into quest articles. - **Export and import** must carry all of it, including aliases (#580). ## Broken today: fix in the rebuild, not separately Owner decision: fix these as part of the rebuild. - **Table and underline toolbar buttons.** The article text is displayed by react-markdown with **no GFM extension**, so tables don't render, and `<u>` isn't converted into underlining. Found by reading the code; confirm in the rebuild. - **Missing link targets** render as grey dead text. - **No `[[` autocomplete.** - **No conflict check** on `PATCH /campaigns/{id}/lore/{entry_id}`; the last save wins silently. - **Duplicate titles** resolve arbitrarily: `buildWikiEntryLookup` keeps whichever comes last. - **The toolbar's image button** only accepts a URL. ## Mockups (#363) Wiki screens are being added to both round-two designs, each in phone and desktop frames: 1. Wiki home and search. 2. An NPC article with its stat block (GM on the desktop, player on the phone). 3. Editing. 4. The map. 5. The party. 6. A quest. ## Related - **UX milestone:** #363, #364, #366 - **Reshaped by this design:** #123, #126 - **Rulebook imports and stat blocks:** #553, #139 - **Foundry:** #13, #14, #157 - **Also affected:** #330, #580

Rows
Columns

[UX] Wiki redesign — design record #593