docs: align API reference and data model docs with code reality

API Reference (9 files updated):
- Marketplace API: corrected offer endpoints (scoped under /purchase-requests/:id/offers),
  marked phantom /search /stats /seller/:sellerId /withdraw routes as NOT IMPLEMENTED,
  documented PUT→PATCH mismatches, removed invalid SellerOffer 'active' status
- Dispute API: corrected resolve schema (action enum), categories (no 'fraud'),
  removed 'under_review' status, added security callouts (3 unguarded endpoints),
  route shadowing documented, all socket events marked as TODO stubs
- Notification API: corrected mark-all-read method+path, fixed broken GET /:id,
  added unread-count-update event, 90-day TTL documented
- Payment API: /create→/save, removed 10+ phantom endpoints, fixed release/refund
  paths (no /shkeeper/ segment), added 3 unauthenticated endpoint security warnings,
  stats undercounting documented, export privilege gap documented
- Authentication API: 8-digit→6-digit code, no-complexity warning on reset-with-code,
  rate limiter counts all attempts, passkey stub claims removed, deleteAccount bug noted
- Admin API: PUT→PATCH bug documented, wrong status values documented, hard vs soft
  delete clarified, scanner no-auth security bug, 3 NOT IMPLEMENTED endpoints
- Chat API: file upload wrong endpoint bug, archive PUT→PATCH bug, rate limits added
- Points API: corrected redeem schema, referral triggers on 'completed' only,
  leaderboard period ignored, removed 'refund' PointTransaction type
- Socket Events: removed request-cancelled, notification-read; added unread-count-update;
  dispute events all stubs; referral-signup is auth-domain not points-domain

Data Models (3 files updated):
- SellerOffer: removed 'active' from status enum, withdrawOffer() is dead code
- PurchaseRequest: added pending_payment/active statuses, added 'urgent' urgency,
  corrected description minimum (5 chars), removed finalized/archived
- Dispute: corrected action enum, categories (no fraud), removed under_review,
  security callout on unguarded status/resolve endpoints

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

03 - API Reference/Chat API.md

@@ -5,10 +5,20 @@ tags: [api, chat, reference]
 
 # Chat API
 
+> **Last updated:** 2026-05-29 — aligned with code (see [Doc vs Code Audit Report](../09%20-%20Audits/Doc%20vs%20Code%20Audit%20Report%20-%202026-05-29.md))
+
 All chat endpoints live under `/api/chat/*`. The router is [`backend/src/services/chat/chatRoutes.ts`](../../backend/src/services/chat/chatRoutes.ts), controller is `chatController`, service is `ChatService`. Every endpoint requires `Bearer JWT` — the router applies `authenticateToken` globally.
 
 Model: [[Chat]]. Real-time delivery happens over Socket.IO rooms named `chat-<chatId>`. Clients must call `join-chat-room` after connecting. See [[Socket Events]] for `new-message`, `messages-read`, `message-edited`, `message-deleted`, `participants-added`, `participant-removed`, and `user-typing` payloads.
 
+## Rate limits and constraints
+
+| Rule | Value |
+| --- | --- |
+| Messages per user per minute | **20** |
+| Edit window | **15 minutes** after send |
+| Maximum message length | **5 000 characters** |
+
 ## Conversations
 
 ### POST /api/chat
@@ -61,9 +71,11 @@ Model: [[Chat]]. Real-time delivery happens over Socket.IO rooms named `chat-<ch
 
 ### PATCH /api/chat/:id/archive
 
-**Description:** Toggle archived state for the caller (per-user flag).
+**Description:** Toggle archived state for the caller (per-user flag). Calling this endpoint on an already-archived chat **unarchives** it (toggle semantics).
 **Auth required:** Bearer JWT (participant)
 
+> ⚠️ **KNOWN BUG** — The frontend `archiveConversation` helper sends `PUT /api/chat/:id/archive` but the backend route is registered as `PATCH`. The request will receive a `404` until the frontend is corrected to use `PATCH`.
+
 ### POST /api/chat/:id/participants
 
 **Description:** Add a participant to a group chat.
@@ -112,16 +124,18 @@ Model: [[Chat]]. Real-time delivery happens over Socket.IO rooms named `chat-<ch
 
 **Response 201:** `{ success, data: { message: { attachments: [{ url, filename, mimeType, size }] } } }`
 
+> ⚠️ **KNOWN BUG** — The frontend `sendFileMessage` function incorrectly posts to `POST /api/chat/:id/messages` (the plain-text endpoint) instead of `POST /api/chat/:id/messages/file`. File uploads are currently broken as a result; the attachment is silently dropped or the request is rejected.
+
 ### PATCH /api/chat/:id/messages/read
 
-**Description:** Mark all unread messages up to the latest as read for the caller.
+**Description:** Mark messages as read for the caller. Passing an empty `messageIds` array (or omitting it) marks **all** messages in the chat as read.
 **Auth required:** Bearer JWT (participant)
 **Response 200:** `{ success, data: { modifiedCount } }`
 **Side effects:** Emits `messages-read` on `chat-<id>`.
 
 ### PUT /api/chat/:id/messages/:messageId
 
-**Description:** Edit an existing message (author only, within edit window).
+**Description:** Edit an existing message (author only, within the 15-minute edit window).
 **Auth required:** Bearer JWT (message author)
 **Request body:** `{ content: string }`
 **Side effects:** Emits `message-edited` on `chat-<id>`.