docs: reconcile conversation feature guides

[steipete]

Summary

• make the central Messages guide discoverable as the unified home for topics, pins, mentions, and channel attention
• add notification-preference and pin endpoints to the API index
• add the new persistence tables and migration responsibilities to the data-model guide
• remove the stale claim that pinning is intentionally missing

Validation

• pnpm docs:site
• git diff --check
• local Codex autoreview: clean, no accepted/actionable findings

This is the final cross-PR consistency sweep after #121, #116, #137, #117, and #138.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed August 2, 2026, 6:33 PM ET / 22:33 UTC.

ClawSweeper review

What this changes

The PR updates conversation documentation so Messages, API, and data-model guides reflect topics, channel notification preferences, mentions, and pinned messages.

Merge readiness

⚠️ Ready for maintainer review - 1 item remains

This PR remains necessary: current main has the newly merged conversation features, but its top-level indexes and the Messages guide still omit them or state that pinning is unavailable. The five-file docs-only patch accurately reconciles those entry points with current routes, storage migrations, and feature guides; no correctness or security blocker was found.

Priority: P3
Reviewed head: 56ec3c9f2a826b683023a2146c52a611e15c4695

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A small, coherent documentation patch with source-verified claims and no behavior change.
Proof confidence	🌊 off-meta tidepool	Not applicable: This PR changes only documentation files, so runtime proof is not required; source-to-doc consistency is the relevant validation.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This PR changes only documentation files, so runtime proof is not required; source-to-doc consistency is the relevant validation.
Evidence reviewed	5 items	Repository policy applied: The full repository AGENTS.md was read. Its sqlc guidance does not apply because the proposed patch changes documentation only and does not touch schema, queries, or generated store code. Current route registration: Current main registers the exact GET/PATCH notification-settings and GET/POST/DELETE pins endpoints added to the API overview. Current persisted model: Both storage backends contain topic, notification, and pinned-message migrations; PostgreSQL defines channel_notification_settings and pinned_messages as documented by the proposed data-model update.
Findings	None	None.
Security	None	None.

How this fits together

ClickClack’s conversation system persists messages, topics, channel-level notification preferences, and shared pins in SQLite/Postgres. REST endpoints and durable events expose that state to web and desktop clients, while the docs index directs users to the appropriate feature guide.

flowchart LR
  Clients[Web and desktop clients] --> API[Conversation REST API]
  API --> Store[SQLite or Postgres store]
  Store --> State[Messages topics pins preferences]
  State --> Events[Durable and realtime events]
  Events --> Clients
  Docs[Feature and API guides] --> Clients

Loading

Before merge

• Add real behavior proof - Not applicable: This PR changes only documentation files, so runtime proof is not required; source-to-doc consistency is the relevant validation.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Documentation scope	5 files affected; 9 added, 4 removed	The branch is limited to cross-reference and product-boundary wording.

Technical review

Best possible solution:

Merge this narrow documentation update so the main entry points accurately direct users to existing conversation features and no longer describe channel pinning as unavailable.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this PR changes documentation only; its claims were checked against current route registration, migrations, feature guides, and endpoint tests.

Is this the best way to solve the issue?

Yes: extending the existing Messages guide and indexes is the narrowest maintainable way to reconcile documentation for the merged conversation features.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 59b617d7465a.

Labels

Label changes:

• add P3: This is a low-risk documentation consistency update with no runtime behavior change.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: This PR changes only documentation files, so runtime proof is not required; source-to-doc consistency is the relevant validation.

Label justifications:

• P3: This is a low-risk documentation consistency update with no runtime behavior change.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: This PR changes only documentation files, so runtime proof is not required; source-to-doc consistency is the relevant validation.

Evidence

What I checked:

• Repository policy applied: The full repository AGENTS.md was read. Its sqlc guidance does not apply because the proposed patch changes documentation only and does not touch schema, queries, or generated store code. (AGENTS.md:1, 59b617d7465a)
• Current route registration: Current main registers the exact GET/PATCH notification-settings and GET/POST/DELETE pins endpoints added to the API overview. (apps/api/internal/httpapi/server.go:206, 59b617d7465a)
• Current persisted model: Both storage backends contain topic, notification, and pinned-message migrations; PostgreSQL defines channel_notification_settings and pinned_messages as documented by the proposed data-model update. (apps/api/internal/store/postgres/migrations/0032_mentions_and_notifications.sql:4, 59b617d7465a)
• Feature-history provenance: The current Messages guide received the relevant topic, notification, resolved-mention, and pin behavior through recent merged feature commits. This PR fills the remaining navigation and stale unsupported-feature wording. (docs/features/messages.md:127, 961e46f7f2b0)
• Patch consistency: The branch changes five documentation files, adds existing feature-guide links and API paths, and replaces the obsolete claim that pinning is intentionally missing; the diff is whitespace-clean. (docs/features/messages.md:199, 56ec3c9f2a82)

Likely related people:

• jjjhenriksen: Authored the recent merged notification, pin, and resolved-mention feature work that established most of the behavior documented here. (role: recent conversation-feature contributor; confidence: high; commits: ca3c86ff6a8b, 961e46f7f2b0, b409a28f8ab4; files: docs/features/messages.md, apps/api/internal/httpapi/server.go, apps/api/internal/store/postgres/migrations/0032_mentions_and_notifications.sql)
• PollyBot13: Authored the merged topic UI feature that updated the Messages guide and supplies the topic behavior reflected in the index wording. (role: recent topic-feature contributor; confidence: high; commits: 187131ccbbda; files: docs/features/messages.md, apps/api/internal/httpapi/server.go, apps/api/internal/store/postgres/migrations/0010_topics.sql)
• Shakker: Blame attributes the surrounding README, docs index, API overview, data-model, and Messages-guide lines to the original documentation commit. (role: original documentation author; confidence: medium; commits: b3b5e3ba6168; files: README.md, docs/README.md, docs/api/overview.md)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.