docs(audit): align documentation with post-remediation backend reality

- Update data model enums to match backend models
- Update API reference auth requirements
- Add dispute module references and warning blocks
- Add 2026-05-24 audit remediation callout to Overview
- Generate task breakdowns and audit artifacts
- Add doc alignment report (.taskmaster/reports/)

02 - Data Models/Data Model Overview.md

@@ -10,6 +10,18 @@ This section documents every Mongoose model that backs the marketplace. The pers
 
 > [!note] Scope
 > Sixteen models are documented here. The "File" concept exists only at the service layer (`backend/src/services/file/`) and is not persisted as its own Mongoose collection, so it is not listed below.
+>
+> [!warning] Implementation gap
+> As of the 2026-05-24 audit, the following documented models **do not yet have Mongoose schema files** in `backend/src/models/`:
+> - [[Dispute]]
+> - [[BlogPost]]
+> - [[Review]]
+> - [[PointTransaction]]
+> - [[LevelConfig]]
+> - [[ShopSettings]]
+> The following *are* implemented in code and are documented accurately:
+> - [[User]], [[PurchaseRequest]], [[SellerOffer]], [[Payment]], [[Chat]], [[Notification]], [[RequestTemplate]], [[Address]], [[Category]], [[TempVerification]]
+> Additionally, `FundsLedgerEntry.ts` and `TrezorAccount.ts` exist in `backend/src/models/` but are not yet documented in this vault.
 
 ## Index of Models
 
@@ -95,7 +107,7 @@ The dominant happy-path flow exercises five collections in order:
 4. The seller marks the request `delivery` → `delivered`; the buyer confirms with the 6-digit `deliveryCode` and the request becomes `completed`.
 5. The escrow `Payment` flips to `released` and a payout `Payment` (`direction: 'out'`) is issued. Optionally the buyer writes a `Review` and earns a `PointTransaction`.
 
-If anything goes sideways, the buyer can open a `Dispute`, which freezes the flow until an admin resolves it (refund, replacement, compensation, or no-action).
+If anything goes sideways, the buyer can open a `Dispute` (planned but not yet implemented), which would freeze the flow until an admin resolves it (refund, replacement, compensation, or no-action).
 
 ## How to Navigate
 

02 - Data Models/Dispute.md

@@ -8,8 +8,10 @@ aliases: [Complaint, IDispute]
 
 Buyer-raised complaint tied to a [[PurchaseRequest]]. Captures the reason, priority, category, an array of evidence uploads, a chronological `timeline` of actions, an optional resolution, and SLA deadlines. An admin (`adminId`) is assigned during triage and resolves the dispute with a structured action (`refund`, `replacement`, `compensation`, `warning_seller`, `ban_seller`, or `no_action`).
 
-> [!note] Source
-> `backend/src/models/Dispute.ts:69` — schema definition
+> [!warning] Missing model
+> **`backend/src/models/Dispute.ts` does not exist** as of the 2026-05-24 audit. The `Dispute` model, service layer, and API routes are **documented but not yet implemented** in the backend. The schema below reflects the *intended* design only.
+>
+> Source (intended): `backend/src/models/Dispute.ts:69` — schema definition
 > `backend/src/models/Dispute.ts:238` — model export
 
 ## Schema
@@ -57,7 +59,7 @@ None defined.
 
 ## Indexes
 
-Defined at `backend/src/models/Dispute.ts:212-223`:
+Defined at `backend/src/models/Dispute.ts:212-223` *(intended)*:
 
 - `{ purchaseRequestId: 1 }`
 - `{ buyerId: 1 }`
@@ -74,7 +76,7 @@ Defined at `backend/src/models/Dispute.ts:212-223`:
 
 | Hook | Behaviour |
 | --- | --- |
-| `pre('save')` (`backend/src/models/Dispute.ts:226`) | On new documents pushes a `dispute_created` entry into `timeline` attributed to `buyerId`. |
+| `pre('save')` (`backend/src/models/Dispute.ts:226` *(intended)*) | On new documents pushes a `dispute_created` entry into `timeline` attributed to `buyerId`. |
 
 ## Instance Methods
 

02 - Data Models/Payment.md

@@ -25,7 +25,7 @@ Records every monetary movement in the marketplace: buyer pay-ins, seller payout
 | `sellerId` | Mixed (ObjectId or String) | yes | — | — | yes (compound) | Seller receiving (or template seller). |
 | `amount.amount` | Number | yes | — | — | — | Numeric amount. |
 | `amount.currency` | String | yes | `USDT` | — | — | Settlement currency. |
-| `provider` | String | no | `shkeeper` | enum: `shkeeper` / `other` | yes (compound, partial) | Payment processor. |
+| `provider` | String | no | `shkeeper` | enum: `shkeeper` / `request.network` / `request-network` / `other` | yes (compound, partial) | Payment processor. |
 | `direction` | String | no | `in` | enum: `in` / `out` / `refund` | yes (compound, partial) | Flow direction. |
 | `blockchain.network` | String | no | — | — | — | Network identifier. |
 | `blockchain.transactionHash` | String | no | — | — | yes (sparse) | On-chain tx hash. |
@@ -36,7 +36,7 @@ Records every monetary movement in the marketplace: buyer pay-ins, seller payout
 | `blockchain.confirmedAt` | Date | no | — | — | — | When tx confirmed. |
 | `blockchain.confirmations` | Number | no | `0` | — | — | Confirmation count. |
 | `status` | String | no | `pending` | enum: `pending` / `processing` / `confirmed` / `completed` / `failed` / `cancelled` / `refunded` | yes (compound) | Lifecycle status. |
-| `escrowState` | String | no | — | enum: `funded` / `releasable` / `released` / `refunded` / `releasing` / `failed` | — | Escrow lifecycle. |
+| `escrowState` | String | no | — | enum: `funded` / `releasable` / `released` / `refunded` / `releasing` / `failed` / `cancelled` / `partial` | — | Escrow lifecycle. |
 | `providerPaymentId` | String | no | — | — | yes (sparse) | External provider id for idempotency. |
 | `metadata.userAgent` | String | no | — | — | — | Browser UA. |
 | `metadata.ipAddress` | String | no | — | — | — | Client IP. |
@@ -51,6 +51,10 @@ Records every monetary movement in the marketplace: buyer pay-ins, seller payout
 | `metadata.cryptoName` | String | no | — | — | — | Crypto label. |
 | `metadata.walletAddress` | String | no | — | — | — | Wallet address. |
 | `metadata.shkeeperTaskId` | String | no | — | — | — | Payout task id. |
+| `metadata.requestNetworkRequestId` | String | no | — | — | — | Request Network request id. |
+| `metadata.requestNetworkPaymentReference` | String | no | — | — | — | Request Network payment reference. |
+| `metadata.requestNetworkSecurePaymentUrl` | String | no | — | — | — | Request Network secure payment URL. |
+| `metadata.requestNetworkData` | Mixed | no | — | — | — | Raw Request Network payload. |
 | `metadata.lastWebhookAt` | Date | no | — | — | — | Last webhook timestamp. |
 | `metadata.webhookPayload` | Mixed | no | — | — | — | Last webhook body. |
 | `metadata.createdVia` | String | no | — | — | — | Origin marker. |

02 - Data Models/User.md

@@ -56,15 +56,15 @@ The core identity document for every actor in the marketplace: buyers, sellers,
 | `status` | String | no | `"active"` | enum: `active` / `suspended` / `deleted` | yes | Soft-delete and moderation flag. |
 | `lastLoginAt` | Date | no | — | — | — | Updated by auth middleware. |
 | `refreshTokens[]` | String[] | no | `[]` | — | — | Outstanding JWT refresh tokens. |
-| `referralCode` | String | no | — | — | unique, sparse | Personal invite code. |
-| `referredBy` | ObjectId → User | no | — | — | yes | Who invited this user. |
-| `points.total` | Number | no | `0` | — | — | Lifetime points earned. |
-| `points.available` | Number | no | `0` | — | — | Currently spendable. |
-| `points.used` | Number | no | `0` | — | — | Cumulative spent. |
-| `points.level` | Number | no | `1` | — | yes (`points.level`) | Resolved against [[LevelConfig]]. |
-| `referralStats.totalReferrals` | Number | no | `0` | — | — | Count of invited users. |
-| `referralStats.activeReferrals` | Number | no | `0` | — | — | Subset that became active buyers. |
-| `referralStats.totalEarned` | Number | no | `0` | — | — | Cumulative reward earnings. |
+| `referralCode` | String | no | — | — | unique, sparse | **Not yet implemented** in `User.ts` — planned for referral programme. |
+| `referredBy` | ObjectId → User | no | — | — | yes | **Not yet implemented** in `User.ts` — planned for referral programme. |
+| `points.total` | Number | no | `0` | — | — | **Not yet implemented** in `User.ts` — planned for loyalty system. |
+| `points.available` | Number | no | `0` | — | — | **Not yet implemented** in `User.ts`. |
+| `points.used` | Number | no | `0` | — | — | **Not yet implemented** in `User.ts`. |
+| `points.level` | Number | no | `1` | — | yes (`points.level`) | **Not yet implemented** in `User.ts` — planned for [[LevelConfig]] lookup. |
+| `referralStats.totalReferrals` | Number | no | `0` | — | — | **Not yet implemented** in `User.ts`. |
+| `referralStats.activeReferrals` | Number | no | `0` | — | — | **Not yet implemented** in `User.ts`. |
+| `referralStats.totalEarned` | Number | no | `0` | — | — | **Not yet implemented** in `User.ts`. |
 | `createdAt` | Date | auto | — | — | — | Mongoose timestamp. |
 | `updatedAt` | Date | auto | — | — | — | Mongoose timestamp. |
 
@@ -78,11 +78,11 @@ The core identity document for every actor in the marketplace: buyers, sellers,
 
 Defined explicitly (in addition to the implicit `email` unique index):
 
-- `{ role: 1 }` — `backend/src/models/User.ts:231`
-- `{ status: 1 }` — `backend/src/models/User.ts:232`
-- `{ referralCode: 1 }` — `backend/src/models/User.ts:233`
-- `{ referredBy: 1 }` — `backend/src/models/User.ts:234`
-- `{ 'points.level': 1 }` — `backend/src/models/User.ts:235`
+- `{ role: 1 }` — `backend/src/models/User.ts:178`
+- `{ status: 1 }` — `backend/src/models/User.ts:179`
+
+> [!warning] Missing indexes
+> The schema currently defines only `role` and `status` indexes. The `referralCode`, `referredBy`, and `points.level` indexes documented below are **not yet present** in `User.ts`:
 
 ## Pre/Post Hooks