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

@@ -5,6 +5,8 @@ tags: [api, admin, reference]
 
 # Admin 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))
+
 There is no single `/api/admin` namespace — admin-only endpoints are scattered across the service routers. This page catalogs them in one place. All require `Bearer JWT` with `req.user.role === 'admin'`. The two enforcement patterns are:
 
 - Middleware: `authorizeRoles('admin')` after `authenticateToken` (used by the dispute, data-cleanup, blog routers).
@@ -17,7 +19,7 @@ See full descriptions in [[User API]].
 | Endpoint | Action |
 | --- | --- |
 | `POST /api/user/admin/create` | Create user with role/status |
-| `DELETE /api/user/admin/:userId` | Delete user (admins cannot delete each other) |
+| `DELETE /api/user/admin/:userId` | Soft delete user — sets `status='deleted'` (admins cannot delete each other) |
 | `PATCH /api/user/admin/:userId/status` | Activate / suspend |
 | `PATCH /api/user/admin/:userId/toggle-status` | Flip active flag |
 | `PATCH /api/user/admin/:userId/role` | Change role |
@@ -30,6 +32,12 @@ See full descriptions in [[User API]].
 | `PATCH /api/users/admin/:userId/password` | Force password reset (wipes refresh tokens) |
 | `POST /api/users/admin/:userId/resend-verification` | Resend verification email |
 
+**⚠️ KNOWN BUG — HTTP verb mismatch (status/role updates):** The frontend Redux actions for `updateUserStatus` and `updateUserRole` send `PUT` requests, but the backend registers these handlers under `PATCH`. These calls will receive `404 Method Not Found` responses until the frontend is corrected to use `PATCH`.
+
+**⚠️ KNOWN BUG — Status value mismatch:** The frontend sends `'inactive'` and `'pending'` as status values when updating user status. The backend only accepts `'active'`, `'suspended'`, or `'deleted'`. Sending `'inactive'` or `'pending'` will be rejected or silently ignored.
+
+**Hard vs. soft delete note:** The legacy route `DELETE /users/admin/:id` performs a **hard delete** (`findByIdAndDelete`). The current route `DELETE /api/user/admin/:userId` performs a **soft delete** (sets `status='deleted'`). Always use the current `/api/user/admin/:userId` route to preserve data integrity.
+
 ## Listing / marketplace moderation
 
 See [[Marketplace API]]. Admins can use most marketplace endpoints with elevated privileges (e.g. delete any purchase request, override offer status). Specific admin-only actions:
@@ -62,14 +70,16 @@ See [[Payment API]].
 | `POST /api/payment/payments/cleanup-pending` | Delete stale pending payments |
 | `POST /api/payment/payments/:id/fetch-tx` | Re-query chain for missing tx hash |
 | `POST /api/payment/payments/auto-fetch-missing` | Batch tx-hash backfill |
-| `POST /api/payment/shkeeper/:id/release` | Build escrow-release tx |
-| `POST /api/payment/shkeeper/:id/release/confirm` | Confirm release tx hash |
-| `POST /api/payment/shkeeper/:id/refund` | Build refund tx |
-| `POST /api/payment/shkeeper/:id/refund/confirm` | Confirm refund tx hash |
+| `POST /api/payment/:id/release` | Build escrow-release tx |
+| `POST /api/payment/:id/release/confirm` | Confirm release tx hash |
+| `POST /api/payment/:id/refund` | Build refund tx |
+| `POST /api/payment/:id/refund/confirm` | Confirm refund tx hash |
 | `POST /api/payment/shkeeper/payout` | Create payout task |
 | `GET /api/payment/shkeeper/webhook-stats` | Webhook telemetry |
 | `POST /api/payment/decentralized/admin-payout` | Direct admin-wallet payout |
 
+**⚠️ Path correction:** Release/refund routes do **not** include a `/shkeeper/` segment. The correct paths are `/api/payment/:id/release`, `/api/payment/:id/release/confirm`, etc. (Previously documented incorrectly as `/api/payment/shkeeper/:id/…`.)
+
 ## Points (admin)
 
 See [[Points API]].
@@ -125,12 +135,24 @@ Router: [`backend/src/services/admin/dataCleanupRoutes.ts`](../../backend/src/se
 
 **Description:** Seeds users, addresses, and templates in dependency order. Used to bootstrap a fresh staging environment.
 
+## Scanner / monitoring
+
+### GET /api/admin/scanner/status
+
+**Description:** Returns the current state of the blockchain scanner / wallet monitor.
+**⚠️ SECURITY BUG — NO AUTHENTICATION:** Despite being mounted under `/api/admin/` and documented as admin-only, this endpoint has **no** `authenticateToken` or `authorizeRoles` guard. Any unauthenticated request can read scanner state.
+
+> ⚠️ **NOT IMPLEMENTED:** The following endpoints do not exist in the codebase:
+> - `GET /api/admin/settings/confirmation-thresholds/history` — only the current-values `GET /api/admin/settings/confirmation-thresholds` and per-chain `PATCH /api/admin/settings/confirmation-thresholds/:chainId` exist.
+> - `POST /api/admin/rn/networks/reload` — the network registry cannot be reloaded at runtime via HTTP.
+> - `POST /api/admin/rn/networks/probe/:chainId` — no per-chain probe endpoint exists.
+
 ## Analytics
 
 There is no dedicated analytics router. Admin dashboards stitch together:
 
 - `GET /api/users/admin/stats` (user metrics)
-- `GET /api/payment/stats` (payment aggregates)
+- `GET /api/payment/stats` (payment aggregates — note: `'completed'` status is excluded from `successfulPayments` count)
 - `GET /api/disputes/statistics` (dispute KPIs)
 - `GET /api/admin/cleanup/stats` (collection sizes)
 - `GET /api/payment/shkeeper/webhook-stats` (provider health)