From 56ec3c9f2a826b683023a2146c52a611e15c4695 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sun, 2 Aug 2026 15:29:08 -0700
Subject: [PATCH] docs: reconcile conversation feature guides

---
 README.md                 | 2 +-
 docs/README.md            | 2 +-
 docs/api/overview.md      | 2 ++
 docs/data-model.md        | 5 ++++-
 docs/features/messages.md | 2 +-
 5 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 6c289708..6fdf8aae 100644
--- a/README.md
+++ b/README.md
@@ -64,7 +64,7 @@ Per-feature docs:
 | Auth             | [docs/features/auth.md](docs/features/auth.md) |
 | Moderation       | [docs/features/moderation.md](docs/features/moderation.md) |
 | Workspaces       | [docs/features/workspaces.md](docs/features/workspaces.md) |
-| Messages         | [docs/features/messages.md](docs/features/messages.md) |
+| Messages, topics, pins, and channel attention | [docs/features/messages.md](docs/features/messages.md) |
 | Threads          | [docs/features/threads.md](docs/features/threads.md) |
 | Reactions        | [docs/features/reactions.md](docs/features/reactions.md) |
 | Realtime         | [docs/features/realtime.md](docs/features/realtime.md) |
diff --git a/docs/README.md b/docs/README.md
index c6418425..0b826563 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -50,7 +50,7 @@ it for anything that isn't a local clone.
 
 | Feature | Doc |
 | --- | --- |
-| Channels, messages, edits, soft-delete | [Messages](features/messages.md) |
+| Channels, messages, topics, pins, mentions, edits | [Messages](features/messages.md) |
 | Slack-style threads, one level deep | [Threads](features/threads.md) |
 | Iframe-ready standalone thread panels | [Embedded threads](features/embedding.md) |
 | Reactions on every message | [Reactions](features/reactions.md) |
diff --git a/docs/api/overview.md b/docs/api/overview.md
index d1a6d526..ef592933 100644
--- a/docs/api/overview.md
+++ b/docs/api/overview.md
@@ -47,6 +47,8 @@ The value is not stored on message rows or exported as a metrics label.
 | Topics        | `/api/workspaces/{id}/topics` | [messages](../features/messages.md) |
 | Channels      | `/api/workspaces/{id}/channels`, `/api/channels/{id}` | [workspaces](../features/workspaces.md) |
 | Messages      | `/api/channels/{id}/messages`, `/api/messages/by-nonce`, `/api/messages/{id}` | [messages](../features/messages.md) |
+| Channel attention | `/api/channels/{id}/notification-settings` | [channel notifications](../features/channel-notifications.md) |
+| Pinned messages | `/api/channels/{id}/pins` | [pinned messages](../features/pinned-messages.md) |
 | Threads       | `/api/messages/{id}/thread`, `/api/messages/{id}/thread/replies` | [threads](../features/threads.md) |
 | Replies       | `quoted_message_id` on any message-create endpoint | [replies](../features/replies.md) |
 | Reactions     | `/api/messages/{id}/reactions` | [reactions](../features/reactions.md) |
diff --git a/docs/data-model.md b/docs/data-model.md
index 7250de99..65351ae4 100644
--- a/docs/data-model.md
+++ b/docs/data-model.md
@@ -41,6 +41,8 @@ workspaces                         workspace_members
 workspace_member_moderation
 channels
 messages                           thread_state
+topics                             pinned_messages
+channel_notification_settings
 reactions
 events                             auth_magic_links / sessions
 event_recipients
@@ -55,7 +57,8 @@ Full SQLite SQL is in
 and
 [`0002_auth.sql`](../apps/api/internal/store/sqlite/migrations/0002_auth.sql);
 later migrations add auth/session hardening, upload metadata, public route IDs,
-read receipts, bot records, Postgres parity, and member moderation.
+read receipts, bot records, Postgres parity, member moderation, channel
+notification preferences, resolved-mention event metadata, and pinned messages.
 Full Postgres SQL is in
 [`apps/api/internal/store/postgres/migrations/0001_schema.sql`](../apps/api/internal/store/postgres/migrations/0001_schema.sql).
 
diff --git a/docs/features/messages.md b/docs/features/messages.md
index 00796db2..2264020d 100644
--- a/docs/features/messages.md
+++ b/docs/features/messages.md
@@ -196,6 +196,6 @@ clients don't need a second round-trip. Avatar URLs are passed through as-is.
 ## What is intentionally missing
 
 - Hard delete. The soft-delete row stays for cursor stability.
-- Pinning and bookmarks.
+- Per-user message bookmarks. Channel pins are shared workspace state.
 - Per-message permissions beyond author edit/delete and workspace-owner channel
   deletion.