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/Dispute API.md

@@ -5,13 +5,21 @@ tags: [api, dispute, reference]
 
 # Dispute 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))
+
 > [!note] Current implementation
 > The Dispute module now has a Mongoose model, controller routes, dashboard routes, and release-hold helper routes mounted under `/api/disputes`. Keep this page aligned with both `backend/src/routes/disputeRoutes.ts` and `backend/src/services/dispute/disputeRoutes.ts`.
 
 Endpoints live under `/api/disputes/*`. `backend/src/routes/disputeRoutes.ts` delegates to `DisputeController` (`backend/src/controllers/disputeController.ts`) for CRUD/triage. `backend/src/services/dispute/disputeRoutes.ts` provides lightweight release-hold endpoints (`raise`, `resolve`, `status`) used by escrow release gating. The routers apply `authenticateToken` globally — every endpoint requires `Bearer JWT`.
 
-> [!warning] Route overlap to verify
-> Both route modules define a `POST /:id-or-purchaseRequestId/resolve` shape. Because `app.ts` mounts the full controller router before the lightweight hold router, confirm the intended handler before wiring automation to the lightweight resolve endpoint.
+> [!warning] Route shadowing — both dispute routers are mounted at `/api/disputes`
+> The dashboard router is mounted **first** in `app.ts`. Its `POST /:id/resolve` intercepts requests before the admin-guarded release-hold router's resolve handler. Confirm which handler will run before wiring automation to either resolve endpoint.
+
+> [!danger] Security issues — see individual endpoint notes below
+> Several endpoints that are documented as admin-only have **no role guard** in the current codebase. Any authenticated user can call them. These are noted per-endpoint.
+
+> [!note] Real-time events
+> All socket events from `DisputeService` are currently **TODO stubs**. No real-time events fire from dispute mutations. Notifications are delivered via `POST /api/notifications` → `new-notification` socket event only.
 
 Model: [[Dispute]]. A dispute references a [[PurchaseRequest]] plus optional [[Payment]] context and is the input to the mediation workflow that can lead to refund, replacement, compensation, warning/ban, or no-action. Release/refund execution should go through the ledger-gated [[Payment API]] and [[Payout Flow]].
 
@@ -25,12 +33,15 @@ Model: [[Dispute]]. A dispute references a [[PurchaseRequest]] plus optional [[P
 ```ts
 {
   purchaseRequestId: string;
-  reason: "not_delivered" | "wrong_item" | "damaged" | "quality" | "other";
+  reason: "product_quality" | "delivery_delay" | "wrong_item" | "payment_issue" | "seller_behavior" | "other";
   description: string;
   evidence?: string[];          // URLs from [[File API]]
   paymentId?: string;
 }
 ```
+
+> **Note:** Valid `reason` values are `product_quality | delivery_delay | wrong_item | payment_issue | seller_behavior | other`. The value `fraud` does not exist.
+
 **Response 201:** `{ success: true, data: { dispute } }`
 **Errors:** `400` validation, `403` not a participant of the request, `409` dispute already open for this request.
 **Side effects:**
@@ -39,14 +50,14 @@ Model: [[Dispute]]. A dispute references a [[PurchaseRequest]] plus optional [[P
 
 ### POST /api/disputes/:purchaseRequestId/raise
 
-**Description:** Lightweight release-hold endpoint that marks a purchase request and related payments as disputed.
+**Description:** Lightweight release-hold endpoint that marks a purchase request and related payments as disputed. Exists in the backend but has no corresponding frontend action.
 **Auth required:** Bearer JWT (buyer who owns the request or admin)
 **Request body:** `{ reason?: string }`
 **Response 200:** `{ success, message, data }`
 
 ### GET /api/disputes/:purchaseRequestId/status
 
-**Description:** Returns release-hold flags for a purchase request, including whether release is currently blocked.
+**Description:** Returns release-hold flags for a purchase request, including whether release is currently blocked. Exists in the backend but has no corresponding frontend action.
 **Auth required:** Bearer JWT (buyer, preferred seller, or admin)
 
 ## Read
@@ -56,9 +67,13 @@ Model: [[Dispute]]. A dispute references a [[PurchaseRequest]] plus optional [[P
 **Description:** List disputes the caller can see (their own as buyer/seller, all for admins).
 **Auth required:** Bearer JWT
 **Query params:**
-- `status` (`open` | `under_review` | `resolved_buyer` | `resolved_seller` | `closed`)
+- `status` (`open` | `in_progress` | `resolved_buyer` | `resolved_seller` | `closed`)
+
+  > **Note:** The status value `under_review` does not exist. Use `in_progress`.
+
 - `purchaseRequestId`
 - `page`, `limit`, `sortBy`, `sortOrder`
+
 **Response 200:** `{ success, data: { disputes, pagination } }`
 
 ### GET /api/disputes/statistics
@@ -77,41 +92,53 @@ Model: [[Dispute]]. A dispute references a [[PurchaseRequest]] plus optional [[P
 
 ### POST /api/disputes/:id/assign
 
-**Description:** Assign an admin moderator to the dispute. Sets `assignedAdminId` and transitions status to `under_review`.
-**Auth required:** Bearer JWT (admin)
+**Description:** Assign an admin moderator to the dispute. Sets `assignedAdminId` and transitions status to `in_progress`.
+**Auth required:** Bearer JWT
+
+> ⚠️ **SECURITY — NO ROLE GUARD:** Despite being documented as admin-only, there is no role guard on this endpoint. Any authenticated user can self-assign as mediator on any dispute.
+
 **Request body:** `{ adminId: string }`
 **Side effects:** Notifies all participants.
 
 ### PATCH /api/disputes/:id/status
 
 **Description:** Generic status update (e.g. close without resolution).
-**Auth required:** Bearer JWT (admin)
+**Auth required:** Bearer JWT
+
+> ⚠️ **SECURITY — NO ROLE GUARD:** There is no role guard on this endpoint. Any authenticated user can change dispute status despite documentation claiming admin-only access.
+
 **Request body:** `{ status: string; note?: string }`
 
 ### POST /api/disputes/:id/resolve
 
 **Description:** Final adjudication. Records the decision and triggers the appropriate escrow action.
-**Auth required:** Bearer JWT (admin)
+**Auth required:** Bearer JWT
+
+> ⚠️ **SECURITY — NO ROLE GUARD:** This is the dashboard router's resolve handler (mounted first). There is no role guard. Any authenticated user can resolve a dispute, including issuing `action=ban_seller`.
+
+> ⚠️ **ROUTE SHADOWING:** Because the dashboard router is mounted before the admin-guarded release-hold router, this handler intercepts all `POST /api/disputes/:id/resolve` requests. The admin-guarded release-hold resolve endpoint is unreachable at this path.
+
 **Request body:**
 ```ts
 {
-  decision: "buyer" | "seller" | "split";
-  refundAmount?: number;        // required when "split"
-  releaseAmount?: number;       // required when "split"
-  reasoning: string;
+  action: "refund" | "replacement" | "compensation" | "warning_seller" | "ban_seller" | "no_action";
+  amount?: string;       // optional, e.g. for partial refund or compensation amount
+  notes?: string;
 }
 ```
 **Response 200:** `{ success, data: { dispute, paymentAction } }`
 **Side effects:**
 - `action === "refund"` → create/approve the corresponding refund instruction through the ledger-gated payment release/refund flow.
 - `action === "no_action"` or seller-favorable outcome → clear hold only after release checks pass.
-- split outcomes require explicit partial release/refund instructions.
 - Notifies both participants and updates [[PurchaseRequest]] status to `disputed_resolved`.
 
 ### POST /api/disputes/:purchaseRequestId/resolve
 
 **Description:** Lightweight release-hold endpoint that clears the disputed hold flags on a purchase request and related payments.
 **Auth required:** Bearer JWT (admin)
+
+> ⚠️ **ROUTE SHADOWING:** This endpoint is on the release-hold router which is mounted **after** the dashboard router. The dashboard router's `POST /:id/resolve` matches first, making this handler unreachable in practice. See the route shadowing warning at the top of this page.
+
 **Response 200:** `{ success, message, data }`
 
 ## Evidence and messages
@@ -136,7 +163,7 @@ Direct messages between disputants and the admin moderator are handled via a ded
 
 ## Real-time
 
-Dispute mutations emit notifications via `POST /api/notifications` which delivers `new-notification` socket events to each participant's `user-<userId>` room. See [[Socket Events]] for payload shape.
+> ⚠️ All socket events from `DisputeService` are currently **TODO stubs** — no real-time events fire from dispute mutations. Dispute notifications are delivered only via `POST /api/notifications`, which in turn emits `new-notification` to the relevant `user-<userId>` room. See [[Socket Events]] for payload shape.
 
 ## Related