docs: forum archive search phase 55 and v0.8.20 roadmap

Add FORUM_ARCHIVE_SEARCH.md, update SEARCH, FORUM_CHANNELS, PLATFORM_ROADMAP,
PEARCORD_PARITY, and GITEA_DEVELOPER for pearcord-forum-search module.

Co-authored-by: Cursor <[email protected]>

FORUM_ARCHIVE_SEARCH.md

@@ -0,0 +1,40 @@
+# Forum archive search
+
+P2P forum channels can hide archived posts from the default list while still finding them via search or an explicit toggle.
+
+## Modules
+
+| Package | Role |
+|---------|------|
+| `pearcord-threads` | `listForumPostsForParent(channels, parentId, { includeArchived })` |
+| `pearcord-forum-search` | `forumPostHaystack`, `matchesForumQuery` |
+| `pearcord-platform` | `setForumIncludeArchived`, `searchForumPosts`, guild search thread titles |
+
+## Platform API
+
+- `setForumIncludeArchived(include)` — when true, `view.forumPosts` includes `archived === true` threads
+- `searchForumPosts(guildId, forumChannelId, query, { limit?, includeArchived? })` — title, starter body, tags, `archived` marker
+- `setSearch({ query, scope })` — `scope` may be `channel`, `guild`, or `forum`
+- `_resolveSearchResults()` — populates `view.searchResults` for `guild` and `forum` scopes
+
+Guild-wide search (`searchGuildMessages`) also matches thread channel names and includes archived thread messages when the channel row is archived.
+
+## IPC
+
+| type | fields |
+|------|--------|
+| `set-forum-include-archived` | `include` (boolean) |
+| `update-search` | `query`, `scope` (`channel` \| `guild` \| `forum`) |
+
+## UI
+
+- Forum header: **Show archived** / **Hide archived** toggle
+- Search scope **Forum posts** (visible only on forum channels)
+- Archived rows: muted style + **Archived** badge
+- Forum scope search replaces the post list with `view.searchResults`
+
+## Tests
+
+```bash
+cd apps/pearcord && npm run test:forum-archive-search
+```

FORUM_CHANNELS.md

@@ -33,8 +33,21 @@ P2P sync uses existing `CHANNEL_CREATE` / `CHANNEL_UPDATE` / `MESSAGE_CREATE` go
 
 ## View fields
 
-- `forumPosts` — sorted posts when `activeChannel.type === 'forum'`
+- `forumPosts` — sorted posts when `activeChannel.type === 'forum'` (archived hidden unless `forumIncludeArchived`)
-- `threadsByParent[forumId]` — same threads, sidebar nesting
+- `forumIncludeArchived` — when true, archived posts appear in the list
+- `threadsByParent[forumId]` — same threads, sidebar nesting (active only)
+
+## Archive search (v0.8.20)
+
+- `setForumIncludeArchived(include)` — toggle archived posts in the forum list
+- `searchForumPosts` + search scope **Forum posts** — finds archived posts by title, body, tags
+- Guild-wide search also matches thread channel names (forum post titles)
+
+See [FORUM_ARCHIVE_SEARCH.md](./FORUM_ARCHIVE_SEARCH.md).
+
+```bash
+npm run test:forum-archive-search   # FORUM_ARCHIVE_SEARCH_SMOKE_OK
+```
 
 ## Forum slowmode (v0.7.4)
 

GITEA_DEVELOPER.md

@@ -114,6 +114,7 @@ git remote -v
 | `pearcord-settings` | User appearance prefs + `USER_PREFS_UPDATE` gossip |
 | `pearcord-step-up` | Local step-up PIN for sensitive actions |
 | `pearcord-forum` | Forum post tags + palette helpers |
+| `pearcord-forum-search` | Forum post search haystack helpers |
 | `pearcord-stage` | Stage channel speaker roles + `STAGE_SPEAKER_UPDATE` gossip |
 | `pearcord-automod` | Local automod rules + `AUTOMOD_CONFIG_UPDATE` gossip |
 | `pearcord-voice-codec` | Opus/pcm voice frames for live P2P audio |

PEARCORD_PARITY.md

@@ -129,7 +129,9 @@ Phases **0–2** and **4** are largely complete; **3** (live audio) and **5** (n
 | P53-1 | Multi-sticker composer picker (max 3, v0.8.18) | [x] |
 | P54-1 | Live mesh profile banner fetch (`smoke-banner-mesh`, v0.8.19) | [x] |
 
-**Next tranches:** Forum archive search · sticker soundboard · server-wide emoji slots UI.
+| P11-2 | Forum archive search — P5-3 | [x] v0.8.20 `searchForumPosts`, show-archived toggle |
+
+**Next tranches:** Sticker soundboard · Bare attach-mesh byte roundtrip · server-wide emoji slots UI.
 
 When Phase 5 checklist is `[x]`, copy open items here into tracked rows in `PLATFORM_ROADMAP.md`.
 

PLATFORM_ROADMAP.md

@@ -247,6 +247,20 @@ When completing work, change `[ ]` → `[x]` and add a one-line note under **Cha
 
 ---
 
+### Phase 55 — Forum archive search (v0.8.20)
+
+| ID | Item | Status |
+|----|------|--------|
+| P55-1 | `pearcord-forum-search` haystack helpers | [x] |
+| P55-2 | `listForumPostsForParent` + `setForumIncludeArchived` | [x] |
+| P55-3 | `searchForumPosts` + guild search thread titles | [x] |
+| P55-4 | Forum UI toggle + forum search scope + archived badges | [x] |
+| P55-5 | smoke-forum-archive-search + FORUM_ARCHIVE_SEARCH.md | [x] |
+
+**Next:** Sticker soundboard · Bare attach-mesh byte roundtrip · onboarding mesh E2E extension.
+
+---
+
 ### Phase 54 — Live mesh banner fetch (v0.8.19)
 
 | ID | Item | Status |
@@ -255,7 +269,7 @@ When completing work, change `[ ]` → `[x]` and add a one-line note under **Cha
 | P54-2 | `_ensureBannerAttachmentReady` prefetches via mesh before drive read | [x] |
 | P54-3 | smoke-banner-mesh + attach-mesh/gossip reliability fixes + docs | [x] |
 
-**Next:** Forum archive search · sticker soundboard · onboarding mesh E2E extension.
+**Next:** ~~Forum archive search~~ (Phase 55) · sticker soundboard · onboarding mesh E2E extension.
 
 ---
 
@@ -658,6 +672,7 @@ When completing work, change `[ ]` → `[x]` and add a one-line note under **Cha
 
 ### Changelog
 
+- **2026-05-21** — v0.8.20: forum archive search (`pearcord-forum-search`, `searchForumPosts`, show-archived toggle, forum search scope, smoke-forum-archive-search).
 - **2026-05-21** — v0.8.15: profile banner images (`setProfileBannerImage`, hub card author avatars, smoke-profile-banner).
 - **2026-05-21** — v0.8.14: profile cosmetics (`pearcord-profile-cosmetics`, RPC 56, banner/bio/avatar ring, smoke-profile-cosmetics).
 - **2026-05-21** — v0.8.13: rich hub mirror cards (`pearcord-hub-cards`, `hubMirrorJson`, UI card layout, smoke-hub-cards).

SEARCH.md

@@ -7,14 +7,17 @@ Pearcord supports local message search without a central search index. All queri
 | Scope | UI label | Behavior |
 |-------|----------|----------|
 | `channel` | This channel | Filters `view.messages` in the active text channel (client-side) |
-| `guild` | All channels | Sidecar runs `searchGuildMessages` across text + thread channels |
+| `guild` | All channels | Sidecar runs `searchGuildMessages` across text + thread channels (includes archived thread titles) |
+| `forum` | Forum posts | Sidecar runs `searchForumPosts` on the active forum channel (includes archived posts) |
 
-Guild scope is only available in server (`guild`) mode.
+Guild and forum scopes are only available in server (`guild`) mode. Forum scope requires the active channel to be `type: forum`.
 
 ## Platform API
 
 - `setSearch({ query, scope })` — stores `_searchQuery` / `_searchScope` for `view()`
 - `searchGuildMessages(guildId, query, { limit? })` — returns hits with `channelName` attached
+- `searchForumPosts(guildId, forumChannelId, query, { limit?, includeArchived? })` — forum post hits with `snippet`, `tags`
+- `setForumIncludeArchived(include)` — toggles archived posts in `view.forumPosts`
 
 HyperDB engine scans per `channelId` (no guild-wide index yet). JSON engine uses `{ guildId }` find.
 
@@ -22,9 +25,12 @@ HyperDB engine scans per `channelId` (no guild-wide index yet). JSON engine uses
 
 | type | fields |
 |------|--------|
-| `update-search` | `query`, `scope` (`channel` \| `guild`) |
+| `update-search` | `query`, `scope` (`channel` \| `guild` \| `forum`) |
+| `set-forum-include-archived` | `include` |
 
-`view.searchResults` is populated when `scope === 'guild'` and `query` is non-empty.
+`view.searchResults` is populated when `scope` is `guild` or `forum` and `query` is non-empty.
+
+See also [FORUM_ARCHIVE_SEARCH.md](./FORUM_ARCHIVE_SEARCH.md).
 
 ## UI