docs: AML scope note, human-blocked items, Task #11 pre-flight inventory

- Add AML scope note to Handoff - RN Multichain Probe (sanctions-only vs full KYT)
- Add human-blocked section with 3 precise next steps for owner
- Create Task 11 Pre-flight Inventory: library choice, dev/prod flow, admin UI gaps, backend gaps, risks, acceptance criteria

03 - API Reference/Dispute API.md

@@ -5,12 +5,12 @@ tags: [api, dispute, reference]
 
 # Dispute API
 
-> [!warning] Not implemented
-> The Dispute module is **documented but not yet implemented** in the backend. There is no `backend/src/services/dispute/` directory, no `backend/src/routes/disputeRoutes.ts`, and no `/api/disputes` mount in `app.ts`. The API specification below reflects the *intended* design only.
+> [!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 are planned to live under `/api/disputes/*`. The router would be `backend/src/routes/disputeRoutes.ts` and delegate to `DisputeController` (`backend/src/controllers/disputeController.ts`). The router would apply `authenticateToken` globally — every endpoint requires `Bearer JWT`.
+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`.
 
-Model: [[Dispute]]. A dispute references a [[PurchaseRequest]] plus optional [[Payment]] and is the input to the mediation workflow that ends in either a `resolved_buyer` or `resolved_seller` decision and triggers an escrow release or refund via the [[Payment API]].
+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]].
 
 ## Create
 
@@ -34,6 +34,18 @@ Model: [[Dispute]]. A dispute references a [[PurchaseRequest]] plus optional [[P
 - Notifies the counter-party via `POST /api/notifications` (`new-notification` socket event).
 - Pauses any in-flight payout (sets a hold flag on the related [[Payment]]).
 
+### POST /api/disputes/:purchaseRequestId/raise
+
+**Description:** Lightweight release-hold endpoint that marks a purchase request and related payments as disputed.
+**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.
+**Auth required:** Bearer JWT (buyer, preferred seller, or admin)
+
 ## Read
 
 ### GET /api/disputes
@@ -88,11 +100,17 @@ Model: [[Dispute]]. A dispute references a [[PurchaseRequest]] plus optional [[P
 ```
 **Response 200:** `{ success, data: { dispute, paymentAction } }`
 **Side effects:**
-- `decision === "buyer"` → triggers `POST /api/payment/shkeeper/:id/refund` flow.
-- `decision === "seller"` → triggers `POST /api/payment/shkeeper/:id/release` flow.
-- `decision === "split"` → admin executes both partial release and partial refund manually.
+- `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)
+**Response 200:** `{ success, message, data }`
+
 ## Evidence and messages
 
 ### POST /api/disputes/:id/evidence