feat(leads+verification): wire Leads & Lead Verification to be-crm data door

Integrates the Leads and Lead Verification screens with the live be-crm
backend (crm.lead.* / crm.leadVerification.* / crm.media.*) behind a
mode-agnostic data layer that still falls back to the local mock when the
Shell isn't configured.

Data layer (new)
- src/lib/leads-api.ts    — crm.lead.search/get/stats/create/update/
  updateStatus/assign/sendForVerification + media (presign upload/download)
- src/lib/verify-api.ts   — crm.leadVerification.search/get/stats/verify/
  markUnverified/assign/reassign/moveToPending

Backend → FE wiring
- Assignee / creator names: read the resolved DTO fields and, as a safety
  net, resolve member ids → real names against crm.team.member.search
  (be-crm currently echoes the raw principalId as the name).
- Created By: read the createdBy object the backend returns (was blank).
- Site photos: upload via crm.media.presignUpload → PUT, persist through
  crm.lead.attachment.add (per photo, after create), render in the detail
  popup via crm.media.presignDownload.
- Duplicate guard: surface the backend's real error (detail / duplicate_lead)
  instead of the SDK's opaque "data command failed: 400".

UX
- Leads detail: Property Photos gallery + edit-mode photo add/remove.
- Verification: "Change Assignee" now opens a searchable, scrollable popup
  instead of a long inline dropdown.
- Removed the static "Storm Zone" tag from lead cards/detail; storm banner
  only renders when the lead carries storm data.

Reference / follow-ups
- leads.http, leads.postman_collection.json — be-crm data-door requests.
- LEADS_BACKEND_CHANGES.md — required be-crm changes (name resolution,
  assignee carry-over on sendForVerification) verified against :4010.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

LEADS_BACKEND_CHANGES.md

@@ -0,0 +1,99 @@
+# Leads — Backend Changes Required (be-crm)
+
+Follow-ups the **frontend now depends on**. The frontend side of each item below is
+already implemented and shipped on branch `integration-lead-and-verification-be`; these
+are the matching changes needed in **be-crm** (`crm.lead.*` / `crm.media.*`) for the
+features to work end-to-end.
+
+Companion to `LEADS_BACKEND_REQUIREMENTS.md` (the full contract). Section refs (§) point there.
+
+**How this was found:** integration testing the live data door at `http://localhost:4010`
+(trust-headers dev mode: `X-Tenant-ID: tnt_demo`, `X-Principal-ID: prn_owner`).
+
+---
+
+## 1. Resolve assignee / creator IDs to member display names in `LeadDTO`
+
+**Status:** IDs are stored correctly; **display names are not resolved.**
+
+### What we observed
+`crm.lead.create` with `assignment.assigneeId` → the id persists, and `crm.lead.get`
+returns the assignee/creator — but the `name` is just the **raw principal id echoed back**,
+and the dedicated `*Name` fields come back empty:
+
+```jsonc
+// crm.lead.get response (relevant fields)
+"assignedToId":  "prn_owner",
+"assignedToName": "",                                             // ← empty, not resolved
+"assignee":      { "id": "prn_owner", "name": "prn_owner", "initials": "P" },  // name = the id
+"createdById":   "prn_owner",
+"createdByName": "",                                             // ← empty, not resolved
+"createdBy":     { "id": "prn_owner", "name": "prn_owner", "initials": "P" }   // name = the id
+```
+
+The contract (§6.2) says the detail projection must carry **"resolved assignee / canvasser /
+creator display names."** Today they are unresolved, so the detail popup's **Assigned To** and
+**Created By** show a raw id (or nothing) instead of a person's name.
+
+### Required change
+In the `crm.lead.get` (and any `LeadDTO`-returning command) projection, **join the member
+FKs to the `members` table** and populate the real `displayName`:
+
+- `assigned_to_id` → `assignedToName` **and** `assignee.name` = member `displayName`
+- `created_by_id`  → `createdByName`  **and** `createdBy.name` = member `displayName`
+- `canvasser_id`   → `canvasserName`  (same treatment, §5 note 5)
+
+Fall back to the id only when the member can't be resolved. Note the dev tenant `tnt_demo`
+returns **0 members** from `crm.team.member.search` — seed members there so assignment can be
+exercised (§12 note 5 / "[Seed/link required]").
+
+### Frontend interim (already shipped — remove once backend resolves names)
+`src/lib/leads-api.ts` now resolves the returned id against the local reps list
+(`crm.team.member.search`, principalId → name) as a safety net, and reads the `createdBy`
+**object** (previously the reader only looked at the never-populated `createdByName`, so
+"Created By" rendered blank). Backend resolution is still the correct long-term source of truth.
+
+---
+
+## 2. Site photos — NO backend change (uses existing `crm.lead.attachment.add`)
+
+**Status:** No new backend work. The endpoints already exist; the frontend was wired to them.
+
+### Decision: photos persist via `crm.lead.attachment.add` AFTER create (NOT in `crm.lead.create`)
+Photos are **not** sent in the create payload. The frontend creates the lead first, then calls the
+existing `crm.lead.attachment.add` command once per photo, keyed by the new lead's id (postman **#24**).
+
+### Frontend flow (already shipped)
+1. User picks images in the full form → Property step.
+2. Each file is uploaded to storage via the shared Media module:
+   `crm.media.presignUpload { mime, sizeBytes }` → `{ objectKey, uploadUrl }`, then browser `PUT`s the bytes (§11.5).
+3. On submit: `crm.lead.create` (WITHOUT photos) → then per photo:
+   ```jsonc
+   { "action": "crm.lead.attachment.add",
+     "variables": { "id": "<newLeadId>",
+       "attachment": { "contentRef": "<objectKey>", "mimeType": "image/jpeg", "sizeBytes": 12345, "filename": "roof.jpg" } } }
+   ```
+4. Detail popup reads `attachments[]` from `crm.lead.get` and renders each via `crm.media.presignDownload { contentRef }`.
+
+### Backend expectations (should already hold — just confirm)
+- `crm.lead.attachment.add` inserts a `lead_attachments` row and enforces the 25 MB cap → `413 file_too_large` (§4.4).
+- `crm.lead.get` returns the stored photos as **`attachments: Attachment[]`**, each with at least
+  `{ id, contentRef, mimeType, sizeBytes, filename }` (postman #3 / #24 already reference `j.attachments`).
+- `crm.media.presignUpload` / `crm.media.presignDownload` are registered for this app/tenant (shared Media module).
+
+### Not verified live
+Could **not** confirm against `:4010` (dev backend intermittently down during testing). When stable, run:
+`crm.media.presignUpload` → `crm.lead.create` → `crm.lead.attachment.add` → `crm.lead.get` and confirm
+`attachments[]` comes back.
+
+---
+
+## Quick verification checklist (run against `:4010` when backend is up)
+
+- [ ] Seed members in `tnt_demo`; `crm.team.member.search` returns > 0 items.
+- [ ] `crm.lead.create` with `assignment.assigneeId = <member principalId>` → `crm.lead.get`
+      returns `assignedToName` = that member's real display name.
+- [ ] `crm.lead.get` returns `createdByName` = the creating caller's display name.
+- [ ] `crm.media.presignUpload` returns `{ objectKey, uploadUrl }`; PUT to `uploadUrl` succeeds.
+- [ ] `crm.lead.attachment.add { id, attachment }` → `crm.lead.get` returns matching `attachments[]`.
+- [ ] `crm.media.presignDownload { contentRef }` returns a working signed URL for a stored photo.

leads.http

@@ -0,0 +1,340 @@
+###############################################################################
+# Leads & Lead Verification — data-door requests (VS Code "REST Client" / JetBrains HTTP).
+# Install the REST Client extension, then click "Send Request" above each block.
+# Requests are chained: run the "@name" reads/writes in order so the id variables
+# below resolve. The cleanest end-to-end path is:
+#   #10 intake → #11 assign → #12 reassign → #15 verify (promotes to a Lead).
+# Dev trust-headers mode — change @principal to test different callers.
+###############################################################################
+
+@baseUrl = http://localhost:4010
+@tenant = tnt_demo
+@principal = prn_owner
+
+# Shared headers are repeated per request (the format has no header includes).
+
+### Health — see every registered action (crm.lead.* + crm.leadVerification.*)
+GET {{baseUrl}}/health
+
+# ─────────────────────────────── LEADS: READS (POST /query) ─────────────────────
+
+### 1. Lead stats  (header stat strip: total + byStatus)
+POST {{baseUrl}}/query
+Authorization: Bearer dev
+X-App-ID: crm-web
+X-Tenant-ID: {{tenant}}
+X-Principal-ID: {{principal}}
+Content-Type: application/json
+
+{ "action": "crm.lead.stats", "variables": {} }
+
+### 2. Lead search  (RUN THIS — provides @leadId). Supports query/status/priority/source/assigneeId/page/perPage.
+# @name leadSearch
+POST {{baseUrl}}/query
+Authorization: Bearer dev
+X-App-ID: crm-web
+X-Tenant-ID: {{tenant}}
+X-Principal-ID: {{principal}}
+Content-Type: application/json
+
+{ "action": "crm.lead.search", "variables": { "status": "new", "page": 1, "perPage": 50 } }
+
+@leadId = {{leadSearch.response.body.$.items[0].id}}
+
+### 3. Lead get (full detail incl. phones/emails/attachments + resolved names)
+POST {{baseUrl}}/query
+Authorization: Bearer dev
+X-App-ID: crm-web
+X-Tenant-ID: {{tenant}}
+X-Principal-ID: {{principal}}
+Content-Type: application/json
+
+{ "action": "crm.lead.get", "variables": { "id": "{{leadId}}" } }
+
+# ────────────────────── LEAD VERIFICATION: READS (POST /query) ──────────────────
+
+### 4. Verification stats  (the clickable stat tiles)
+POST {{baseUrl}}/query
+Authorization: Bearer dev
+X-App-ID: crm-web
+X-Tenant-ID: {{tenant}}
+X-Principal-ID: {{principal}}
+Content-Type: application/json
+
+{ "action": "crm.leadVerification.stats", "variables": {} }
+
+### 5. Verification search  (RUN THIS — provides @verificationId)
+# @name vSearch
+POST {{baseUrl}}/query
+Authorization: Bearer dev
+X-App-ID: crm-web
+X-Tenant-ID: {{tenant}}
+X-Principal-ID: {{principal}}
+Content-Type: application/json
+
+{ "action": "crm.leadVerification.search", "variables": { "page": 1, "perPage": 50 } }
+
+@verificationId = {{vSearch.response.body.$.items[0].id}}
+
+### 6. Verification get (detail + activity timeline)
+POST {{baseUrl}}/query
+Authorization: Bearer dev
+X-App-ID: crm-web
+X-Tenant-ID: {{tenant}}
+X-Principal-ID: {{principal}}
+Content-Type: application/json
+
+{ "action": "crm.leadVerification.get", "variables": { "id": "{{verificationId}}" } }
+
+### 7. Verification activity list (also embedded in .get)
+POST {{baseUrl}}/query
+Authorization: Bearer dev
+X-App-ID: crm-web
+X-Tenant-ID: {{tenant}}
+X-Principal-ID: {{principal}}
+Content-Type: application/json
+
+{ "action": "crm.leadVerification.activity.list", "variables": { "id": "{{verificationId}}" } }
+
+# ─────────────── VERIFICATION: WRITES (POST /command + unique key) ───────────────
+# Commands require a UNIQUE X-Idempotency-Key each time (reuse ⇒ 409).
+# Records "arrive" via intake (§12.11) — start the working flow at #10.
+
+### 10. Intake — seed a verification record  (RUN — provides @seedVerificationId)
+# @name intake
+POST {{baseUrl}}/command
+Authorization: Bearer dev
+X-App-ID: crm-web
+X-Tenant-ID: {{tenant}}
+X-Principal-ID: {{principal}}
+X-Idempotency-Key: lv-intake-001
+Content-Type: application/json
+
+{ "action": "crm.leadVerification.intake", "variables": {
+  "name": "Kevin Hartley",
+  "phone": "(972) 413-8902",
+  "email": "kevin.hartley@example.com",
+  "address": "2814 Ravenswood Dr, Plano, TX 75023",
+  "source": "Door Knock"
+} }
+
+@seedVerificationId = {{intake.response.body.$.id}}
+
+### 11. Assign (Change Assignee) — pending → assigned
+POST {{baseUrl}}/command
+Authorization: Bearer dev
+X-App-ID: crm-web
+X-Tenant-ID: {{tenant}}
+X-Principal-ID: {{principal}}
+X-Idempotency-Key: lv-assign-001
+Content-Type: application/json
+
+{ "action": "crm.leadVerification.assign", "variables": { "id": "{{seedVerificationId}}", "assigneeId": "{{principal}}" } }
+
+### 12. Reassign → In Progress
+POST {{baseUrl}}/command
+Authorization: Bearer dev
+X-App-ID: crm-web
+X-Tenant-ID: {{tenant}}
+X-Principal-ID: {{principal}}
+X-Idempotency-Key: lv-reassign-001
+Content-Type: application/json
+
+{ "action": "crm.leadVerification.reassign", "variables": { "id": "{{seedVerificationId}}", "assigneeId": "{{principal}}" } }
+
+### 13. Update status + sub-status (generic; cannot set 'verified' here — use #15)
+POST {{baseUrl}}/command
+Authorization: Bearer dev
+X-App-ID: crm-web
+X-Tenant-ID: {{tenant}}
+X-Principal-ID: {{principal}}
+X-Idempotency-Key: lv-updatestatus-001
+Content-Type: application/json
+
+{ "action": "crm.leadVerification.updateStatus", "variables": { "id": "{{seedVerificationId}}", "status": "in_progress", "subStatus": "Reviewing Insurance" } }
+
+### 14. Add a verification note (appends + timeline entry)
+POST {{baseUrl}}/command
+Authorization: Bearer dev
+X-App-ID: crm-web
+X-Tenant-ID: {{tenant}}
+X-Principal-ID: {{principal}}
+X-Idempotency-Key: lv-note-001
+Content-Type: application/json
+
+{ "action": "crm.leadVerification.note.add", "variables": { "id": "{{seedVerificationId}}", "text": "Ownership confirmed via county records." } }
+
+### 15. Verify — PROMOTES to a new Lead (status = new). Returns { verification, lead }.
+# @name verify
+POST {{baseUrl}}/command
+Authorization: Bearer dev
+X-App-ID: crm-web
+X-Tenant-ID: {{tenant}}
+X-Principal-ID: {{principal}}
+X-Idempotency-Key: lv-verify-001
+Content-Type: application/json
+
+{ "action": "crm.leadVerification.verify", "variables": { "id": "{{seedVerificationId}}", "notes": "Verified — insurance + damage confirmed." } }
+
+@promotedLeadId = {{verify.response.body.$.lead.id}}
+
+### 16. Get the promoted Lead (created by #15)
+POST {{baseUrl}}/query
+Authorization: Bearer dev
+X-App-ID: crm-web
+X-Tenant-ID: {{tenant}}
+X-Principal-ID: {{principal}}
+Content-Type: application/json
+
+{ "action": "crm.lead.get", "variables": { "id": "{{promotedLeadId}}" } }
+
+### 17. Move to Pending (send an assigned/in_progress record back). Seed a second record first if needed.
+POST {{baseUrl}}/command
+Authorization: Bearer dev
+X-App-ID: crm-web
+X-Tenant-ID: {{tenant}}
+X-Principal-ID: {{principal}}
+X-Idempotency-Key: lv-topending-001
+Content-Type: application/json
+
+{ "action": "crm.leadVerification.moveToPending", "variables": { "id": "{{verificationId}}" } }
+
+### 18. Mark Unverified (any non-terminal record)
+POST {{baseUrl}}/command
+Authorization: Bearer dev
+X-App-ID: crm-web
+X-Tenant-ID: {{tenant}}
+X-Principal-ID: {{principal}}
+X-Idempotency-Key: lv-unverified-001
+Content-Type: application/json
+
+{ "action": "crm.leadVerification.markUnverified", "variables": { "id": "{{verificationId}}", "reason": "Could not confirm ownership." } }
+
+# ─────────────────────── LEADS: WRITES (POST /command + unique key) ──────────────
+
+### 20. Create Lead — Full Form payload  (RUN — provides @createdLeadId)
+# @name createLead
+POST {{baseUrl}}/command
+Authorization: Bearer dev
+X-App-ID: crm-web
+X-Tenant-ID: {{tenant}}
+X-Principal-ID: {{principal}}
+X-Idempotency-Key: lead-create-001
+Content-Type: application/json
+
+{ "action": "crm.lead.create", "variables": {
+  "firstName": "John",
+  "lastName": "Martinez",
+  "phones": [
+    { "number": "(469) 500-1000", "type": "Mobile", "primary": true },
+    { "number": "(469) 500-2000", "type": "Home" }
+  ],
+  "emails": [ { "address": "john.martinez@example.com", "primary": true } ],
+  "property": { "address": "4821 Spring Creek Pkwy", "city": "Plano", "state": "TX", "zip": "75023", "type": "Single Family" },
+  "job": { "source": "Door Knock", "canvasserId": "{{principal}}", "leadType": "Insurance", "workType": "Roof Replacement", "tradeType": "Roofing", "urgency": "High", "notes": "Significant granule loss on the south slope." },
+  "insurance": { "company": "State Farm", "claimStatus": "Filed", "claimNumber": "CLM-2026-1000", "policyNumber": "POL-080000", "adjusterName": "Marcus Powell", "adjusterPhone": "(972) 700-3000" },
+  "assignment": { "assigneeId": "{{principal}}", "priority": "High", "followUp": "2026-06-04" }
+} }
+
+@createdLeadId = {{createLead.response.body.$.id}}
+
+### 21. Update Lead (partial patch; priority title-case is normalized to lowercase)
+POST {{baseUrl}}/command
+Authorization: Bearer dev
+X-App-ID: crm-web
+X-Tenant-ID: {{tenant}}
+X-Principal-ID: {{principal}}
+X-Idempotency-Key: lead-update-001
+Content-Type: application/json
+
+{ "action": "crm.lead.update", "variables": { "id": "{{createdLeadId}}", "patch": { "priority": "Medium", "jobNotes": "Adjuster meeting scheduled." } } }
+
+### 22. Update Status (audited → lead_status_history)
+POST {{baseUrl}}/command
+Authorization: Bearer dev
+X-App-ID: crm-web
+X-Tenant-ID: {{tenant}}
+X-Principal-ID: {{principal}}
+X-Idempotency-Key: lead-status-001
+Content-Type: application/json
+
+{ "action": "crm.lead.updateStatus", "variables": { "id": "{{createdLeadId}}", "status": "contacted", "note": "Spoke with homeowner." } }
+
+### 23. Assign a rep (or null for Unassigned)
+POST {{baseUrl}}/command
+Authorization: Bearer dev
+X-App-ID: crm-web
+X-Tenant-ID: {{tenant}}
+X-Principal-ID: {{principal}}
+X-Idempotency-Key: lead-assign-001
+Content-Type: application/json
+
+{ "action": "crm.lead.assign", "variables": { "id": "{{createdLeadId}}", "assigneeId": "{{principal}}" } }
+
+### 24. Attachment add (site photo) — contentRef comes from crm.media.presignUpload (§11.5)
+POST {{baseUrl}}/command
+Authorization: Bearer dev
+X-App-ID: crm-web
+X-Tenant-ID: {{tenant}}
+X-Principal-ID: {{principal}}
+X-Idempotency-Key: lead-attach-add-001
+Content-Type: application/json
+
+{ "action": "crm.lead.attachment.add", "variables": { "id": "{{createdLeadId}}", "attachment": { "contentRef": "obj/site-photo-1.jpg", "mimeType": "image/jpeg", "sizeBytes": 1048576, "filename": "roof-south.jpg" } } }
+
+### 25. Attachment remove (attachmentId from the lead's attachments[] in #3/#16)
+POST {{baseUrl}}/command
+Authorization: Bearer dev
+X-App-ID: crm-web
+X-Tenant-ID: {{tenant}}
+X-Principal-ID: {{principal}}
+X-Idempotency-Key: lead-attach-remove-001
+Content-Type: application/json
+
+{ "action": "crm.lead.attachment.remove", "variables": { "id": "{{createdLeadId}}", "attachmentId": "REPLACE_WITH_ATTACHMENT_ID" } }
+
+# ─────────────────────────── NEGATIVE / GUARD CHECKS ────────────────────────────
+
+### Verify an already-verified record (expect 409 already_verified)
+POST {{baseUrl}}/command
+Authorization: Bearer dev
+X-App-ID: crm-web
+X-Tenant-ID: {{tenant}}
+X-Principal-ID: {{principal}}
+X-Idempotency-Key: guard-alreadyverified-001
+Content-Type: application/json
+
+{ "action": "crm.leadVerification.verify", "variables": { "id": "{{seedVerificationId}}" } }
+
+### Create with no name (expect 422 name_required)
+POST {{baseUrl}}/command
+Authorization: Bearer dev
+X-App-ID: crm-web
+X-Tenant-ID: {{tenant}}
+X-Principal-ID: {{principal}}
+X-Idempotency-Key: guard-noname-001
+Content-Type: application/json
+
+{ "action": "crm.lead.create", "variables": { "firstName": "", "lastName": "  " } }
+
+### Create with a bad email (expect 400 validation)
+POST {{baseUrl}}/command
+Authorization: Bearer dev
+X-App-ID: crm-web
+X-Tenant-ID: {{tenant}}
+X-Principal-ID: {{principal}}
+X-Idempotency-Key: guard-bademail-001
+Content-Type: application/json
+
+{ "action": "crm.lead.create", "variables": { "firstName": "Jane", "emails": [ { "address": "not-an-email" } ] } }
+
+### Invalid state transition — verified is terminal via generic updateStatus (expect 409 / 422)
+POST {{baseUrl}}/command
+Authorization: Bearer dev
+X-App-ID: crm-web
+X-Tenant-ID: {{tenant}}
+X-Principal-ID: {{principal}}
+X-Idempotency-Key: guard-transition-001
+Content-Type: application/json
+
+{ "action": "crm.leadVerification.updateStatus", "variables": { "id": "{{seedVerificationId}}", "status": "pending" } }

leads.postman_collection.json

@@ -0,0 +1,554 @@
+{
+  "info": {
+    "name": "be-crm — Leads & Lead Verification (data door)",
+    "description": "All Leads (crm.lead.*) and Lead Verification (crm.leadVerification.*) data-door actions — for local testing against be-crm on :4010 (trust-headers mode).\n\nHOW TO USE:\n1. Import this file into Postman.\n2. Run 'Verification writes / 10. intake' FIRST — its test script captures the new record id into {{seedVerificationId}}, which the assign/verify chain references. The cleanest end-to-end path is: 10 intake → 11 assign → 12 reassign → 15 verify (promotes to a Lead, captured into {{promotedLeadId}}).\n3. The read folders ('Leads reads' / 'Verification reads') capture {{leadId}} / {{verificationId}} from search results when data exists.\n\nVERIFICATION STATE MACHINE (enforced server-side, §3.1): a record flows pending → assigned → in_progress, and ends at ONE terminal outcome — either verified (via 15. verify, which promotes a Lead) OR unverified (via 17. markUnverified). 'verified' is TERMINAL: markUnverified / moveToPending / updateStatus against a verified record return 409 invalid_state_transition. So run ONE terminal action per record. To exercise markUnverified or moveToPending, run 10. intake to seed a FRESH pending record (repoints {{verificationId}}) and act on it BEFORE verifying — e.g. intake → assign → moveToPending, or intake → markUnverified. Valid: markUnverified from pending/assigned/in_progress; moveToPending from assigned/in_progress.\n\nNOTE: everything is POST except GET /health. Reads hit /query, writes hit /command (action+data in the JSON body). Commands auto-generate a fresh X-Idempotency-Key ({{$guid}}). In dev, the identity headers stand in for what the Shell BFF injects in real environments — never ship them from the frontend. Both modules are gated by the leads.manage permission.",
+    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
+  },
+  "variable": [
+    { "key": "baseUrl", "value": "http://localhost:4010" },
+    { "key": "tenant", "value": "tnt_demo" },
+    { "key": "principal", "value": "prn_owner" },
+    { "key": "leadId", "value": "" },
+    { "key": "verificationId", "value": "" },
+    { "key": "seedVerificationId", "value": "" },
+    { "key": "promotedLeadId", "value": "" },
+    { "key": "createdLeadId", "value": "" },
+    { "key": "attachmentId", "value": "" }
+  ],
+  "item": [
+    {
+      "name": "0. Health (the only GET)",
+      "request": {
+        "method": "GET",
+        "header": [],
+        "url": { "raw": "{{baseUrl}}/health", "host": ["{{baseUrl}}"], "path": ["health"] },
+        "description": "Liveness + the full list of registered actions (crm.lead.* + crm.leadVerification.*). Works in a browser."
+      }
+    },
+    {
+      "name": "Leads reads (POST /query)",
+      "item": [
+        {
+          "name": "1. lead.stats (header stat strip)",
+          "request": {
+            "method": "POST",
+            "header": [
+              { "key": "Authorization", "value": "Bearer dev" },
+              { "key": "X-App-ID", "value": "crm-web" },
+              { "key": "X-Tenant-ID", "value": "{{tenant}}" },
+              { "key": "X-Principal-ID", "value": "{{principal}}" },
+              { "key": "Content-Type", "value": "application/json" }
+            ],
+            "body": { "mode": "raw", "raw": "{\n  \"action\": \"crm.lead.stats\",\n  \"variables\": {}\n}" },
+            "url": { "raw": "{{baseUrl}}/query", "host": ["{{baseUrl}}"], "path": ["query"] },
+            "description": "Returns { total, byStatus: { new, contacted, appointed, closed } }."
+          }
+        },
+        {
+          "name": "2. lead.search  (captures leadId)",
+          "event": [
+            {
+              "listen": "test",
+              "script": {
+                "type": "text/javascript",
+                "exec": [
+                  "const j = pm.response.json();",
+                  "if (j.items && j.items[0]) pm.collectionVariables.set('leadId', j.items[0].id);",
+                  "pm.test('has paging meta', () => pm.expect(j.meta).to.have.property('total'));"
+                ]
+              }
+            }
+          ],
+          "request": {
+            "method": "POST",
+            "header": [
+              { "key": "Authorization", "value": "Bearer dev" },
+              { "key": "X-App-ID", "value": "crm-web" },
+              { "key": "X-Tenant-ID", "value": "{{tenant}}" },
+              { "key": "X-Principal-ID", "value": "{{principal}}" },
+              { "key": "Content-Type", "value": "application/json" }
+            ],
+            "body": { "mode": "raw", "raw": "{\n  \"action\": \"crm.lead.search\",\n  \"variables\": { \"status\": \"new\", \"page\": 1, \"perPage\": 50 }\n}" },
+            "url": { "raw": "{{baseUrl}}/query", "host": ["{{baseUrl}}"], "path": ["query"] },
+            "description": "Board list + search + status/priority/source/assigneeId filters. Returns { items: LeadCardDTO[], meta }."
+          }
+        },
+        {
+          "name": "3. lead.get (full detail)",
+          "event": [
+            {
+              "listen": "test",
+              "script": {
+                "type": "text/javascript",
+                "exec": [
+                  "const j = pm.response.json();",
+                  "if (j.attachments && j.attachments[0]) pm.collectionVariables.set('attachmentId', j.attachments[0].id);"
+                ]
+              }
+            }
+          ],
+          "request": {
+            "method": "POST",
+            "header": [
+              { "key": "Authorization", "value": "Bearer dev" },
+              { "key": "X-App-ID", "value": "crm-web" },
+              { "key": "X-Tenant-ID", "value": "{{tenant}}" },
+              { "key": "X-Principal-ID", "value": "{{principal}}" },
+              { "key": "Content-Type", "value": "application/json" }
+            ],
+            "body": { "mode": "raw", "raw": "{\n  \"action\": \"crm.lead.get\",\n  \"variables\": { \"id\": \"{{leadId}}\" }\n}" },
+            "url": { "raw": "{{baseUrl}}/query", "host": ["{{baseUrl}}"], "path": ["query"] },
+            "description": "Full record incl. phones/emails/attachments + resolved assignee/canvasser/creator names + storm/property/job/insurance groupings."
+          }
+        }
+      ]
+    },
+    {
+      "name": "Verification reads (POST /query)",
+      "item": [
+        {
+          "name": "4. leadVerification.stats (stat tiles)",
+          "request": {
+            "method": "POST",
+            "header": [
+              { "key": "Authorization", "value": "Bearer dev" },
+              { "key": "X-App-ID", "value": "crm-web" },
+              { "key": "X-Tenant-ID", "value": "{{tenant}}" },
+              { "key": "X-Principal-ID", "value": "{{principal}}" },
+              { "key": "Content-Type", "value": "application/json" }
+            ],
+            "body": { "mode": "raw", "raw": "{\n  \"action\": \"crm.leadVerification.stats\",\n  \"variables\": {}\n}" },
+            "url": { "raw": "{{baseUrl}}/query", "host": ["{{baseUrl}}"], "path": ["query"] },
+            "description": "Returns { verified, in_progress, assigned, pending, unverified }."
+          }
+        },
+        {
+          "name": "5. leadVerification.search  (captures verificationId)",
+          "event": [
+            {
+              "listen": "test",
+              "script": {
+                "type": "text/javascript",
+                "exec": [
+                  "const j = pm.response.json();",
+                  "if (j.items && j.items[0]) pm.collectionVariables.set('verificationId', j.items[0].id);",
+                  "pm.test('has paging meta', () => pm.expect(j.meta).to.have.property('total'));"
+                ]
+              }
+            }
+          ],
+          "request": {
+            "method": "POST",
+            "header": [
+              { "key": "Authorization", "value": "Bearer dev" },
+              { "key": "X-App-ID", "value": "crm-web" },
+              { "key": "X-Tenant-ID", "value": "{{tenant}}" },
+              { "key": "X-Principal-ID", "value": "{{principal}}" },
+              { "key": "Content-Type", "value": "application/json" }
+            ],
+            "body": { "mode": "raw", "raw": "{\n  \"action\": \"crm.leadVerification.search\",\n  \"variables\": { \"page\": 1, \"perPage\": 50 }\n}" },
+            "url": { "raw": "{{baseUrl}}/query", "host": ["{{baseUrl}}"], "path": ["query"] },
+            "description": "Queue table + search + status/source/assignee filters. Returns { items: VerificationRowDTO[], meta }."
+          }
+        },
+        {
+          "name": "6. leadVerification.get (detail + timeline)",
+          "request": {
+            "method": "POST",
+            "header": [
+              { "key": "Authorization", "value": "Bearer dev" },
+              { "key": "X-App-ID", "value": "crm-web" },
+              { "key": "X-Tenant-ID", "value": "{{tenant}}" },
+              { "key": "X-Principal-ID", "value": "{{principal}}" },
+              { "key": "Content-Type", "value": "application/json" }
+            ],
+            "body": { "mode": "raw", "raw": "{\n  \"action\": \"crm.leadVerification.get\",\n  \"variables\": { \"id\": \"{{verificationId}}\" }\n}" },
+            "url": { "raw": "{{baseUrl}}/query", "host": ["{{baseUrl}}"], "path": ["query"] }
+          }
+        },
+        {
+          "name": "7. leadVerification.activity.list",
+          "request": {
+            "method": "POST",
+            "header": [
+              { "key": "Authorization", "value": "Bearer dev" },
+              { "key": "X-App-ID", "value": "crm-web" },
+              { "key": "X-Tenant-ID", "value": "{{tenant}}" },
+              { "key": "X-Principal-ID", "value": "{{principal}}" },
+              { "key": "Content-Type", "value": "application/json" }
+            ],
+            "body": { "mode": "raw", "raw": "{\n  \"action\": \"crm.leadVerification.activity.list\",\n  \"variables\": { \"id\": \"{{verificationId}}\" }\n}" },
+            "url": { "raw": "{{baseUrl}}/query", "host": ["{{baseUrl}}"], "path": ["query"] }
+          }
+        }
+      ]
+    },
+    {
+      "name": "Verification writes (POST /command)",
+      "item": [
+        {
+          "name": "10. leadVerification.intake  (RUN FIRST — captures seedVerificationId)",
+          "event": [
+            {
+              "listen": "test",
+              "script": {
+                "type": "text/javascript",
+                "exec": [
+                  "const j = pm.response.json();",
+                  "if (j && j.id) { pm.collectionVariables.set('seedVerificationId', j.id); pm.collectionVariables.set('verificationId', j.id); }",
+                  "pm.test('starts pending', () => pm.expect(j.status).to.eql('pending'));"
+                ]
+              }
+            }
+          ],
+          "request": {
+            "method": "POST",
+            "header": [
+              { "key": "Authorization", "value": "Bearer dev" },
+              { "key": "X-App-ID", "value": "crm-web" },
+              { "key": "X-Tenant-ID", "value": "{{tenant}}" },
+              { "key": "X-Principal-ID", "value": "{{principal}}" },
+              { "key": "X-Idempotency-Key", "value": "{{$guid}}" },
+              { "key": "Content-Type", "value": "application/json" }
+            ],
+            "body": { "mode": "raw", "raw": "{\n  \"action\": \"crm.leadVerification.intake\",\n  \"variables\": {\n    \"name\": \"Kevin Hartley\",\n    \"phone\": \"(972) 413-8902\",\n    \"email\": \"kevin.hartley@example.com\",\n    \"address\": \"2814 Ravenswood Dr, Plano, TX 75023\",\n    \"source\": \"Door Knock\"\n  }\n}" },
+            "url": { "raw": "{{baseUrl}}/command", "host": ["{{baseUrl}}"], "path": ["command"] },
+            "description": "Records 'arrive' via intake (§12.11) — the ingestion path outside the two UI screens. Seeds the queue and captures {{seedVerificationId}} for the working flow below."
+          }
+        },
+        {
+          "name": "11. leadVerification.assign (pending → assigned)",
+          "request": {
+            "method": "POST",
+            "header": [
+              { "key": "Authorization", "value": "Bearer dev" },
+              { "key": "X-App-ID", "value": "crm-web" },
+              { "key": "X-Tenant-ID", "value": "{{tenant}}" },
+              { "key": "X-Principal-ID", "value": "{{principal}}" },
+              { "key": "X-Idempotency-Key", "value": "{{$guid}}" },
+              { "key": "Content-Type", "value": "application/json" }
+            ],
+            "body": { "mode": "raw", "raw": "{\n  \"action\": \"crm.leadVerification.assign\",\n  \"variables\": { \"id\": \"{{seedVerificationId}}\", \"assigneeId\": \"{{principal}}\" }\n}" },
+            "url": { "raw": "{{baseUrl}}/command", "host": ["{{baseUrl}}"], "path": ["command"] },
+            "description": "Change Assignee. A pending record moves to 'assigned'; otherwise only the assignee changes."
+          }
+        },
+        {
+          "name": "12. leadVerification.reassign (→ In Progress)",
+          "request": {
+            "method": "POST",
+            "header": [
+              { "key": "Authorization", "value": "Bearer dev" },
+              { "key": "X-App-ID", "value": "crm-web" },
+              { "key": "X-Tenant-ID", "value": "{{tenant}}" },
+              { "key": "X-Principal-ID", "value": "{{principal}}" },
+              { "key": "X-Idempotency-Key", "value": "{{$guid}}" },
+              { "key": "Content-Type", "value": "application/json" }
+            ],
+            "body": { "mode": "raw", "raw": "{\n  \"action\": \"crm.leadVerification.reassign\",\n  \"variables\": { \"id\": \"{{seedVerificationId}}\", \"assigneeId\": \"{{principal}}\" }\n}" },
+            "url": { "raw": "{{baseUrl}}/command", "host": ["{{baseUrl}}"], "path": ["command"] }
+          }
+        },
+        {
+          "name": "13. leadVerification.updateStatus (generic; not 'verified')",
+          "request": {
+            "method": "POST",
+            "header": [
+              { "key": "Authorization", "value": "Bearer dev" },
+              { "key": "X-App-ID", "value": "crm-web" },
+              { "key": "X-Tenant-ID", "value": "{{tenant}}" },
+              { "key": "X-Principal-ID", "value": "{{principal}}" },
+              { "key": "X-Idempotency-Key", "value": "{{$guid}}" },
+              { "key": "Content-Type", "value": "application/json" }
+            ],
+            "body": { "mode": "raw", "raw": "{\n  \"action\": \"crm.leadVerification.updateStatus\",\n  \"variables\": { \"id\": \"{{seedVerificationId}}\", \"status\": \"in_progress\", \"subStatus\": \"Reviewing Insurance\" }\n}" },
+            "url": { "raw": "{{baseUrl}}/command", "host": ["{{baseUrl}}"], "path": ["command"] },
+            "description": "Generic status + sub-status set. Setting 'verified' here → 422 (use 15. verify, which promotes a Lead). Disallowed transitions → 409."
+          }
+        },
+        {
+          "name": "14. leadVerification.note.add",
+          "request": {
+            "method": "POST",
+            "header": [
+              { "key": "Authorization", "value": "Bearer dev" },
+              { "key": "X-App-ID", "value": "crm-web" },
+              { "key": "X-Tenant-ID", "value": "{{tenant}}" },
+              { "key": "X-Principal-ID", "value": "{{principal}}" },
+              { "key": "X-Idempotency-Key", "value": "{{$guid}}" },
+              { "key": "Content-Type", "value": "application/json" }
+            ],
+            "body": { "mode": "raw", "raw": "{\n  \"action\": \"crm.leadVerification.note.add\",\n  \"variables\": { \"id\": \"{{seedVerificationId}}\", \"text\": \"Ownership confirmed via county records.\" }\n}" },
+            "url": { "raw": "{{baseUrl}}/command", "host": ["{{baseUrl}}"], "path": ["command"] }
+          }
+        },
+        {
+          "name": "15. leadVerification.verify  (PROMOTES to Lead — captures promotedLeadId)",
+          "event": [
+            {
+              "listen": "test",
+              "script": {
+                "type": "text/javascript",
+                "exec": [
+                  "const j = pm.response.json();",
+                  "if (j.lead && j.lead.id) pm.collectionVariables.set('promotedLeadId', j.lead.id);",
+                  "pm.test('verification is verified', () => pm.expect(j.verification.status).to.eql('verified'));",
+                  "pm.test('promoted lead is new', () => pm.expect(j.lead.status).to.eql('new'));"
+                ]
+              }
+            }
+          ],
+          "request": {
+            "method": "POST",
+            "header": [
+              { "key": "Authorization", "value": "Bearer dev" },
+              { "key": "X-App-ID", "value": "crm-web" },
+              { "key": "X-Tenant-ID", "value": "{{tenant}}" },
+              { "key": "X-Principal-ID", "value": "{{principal}}" },
+              { "key": "X-Idempotency-Key", "value": "{{$guid}}" },
+              { "key": "Content-Type", "value": "application/json" }
+            ],
+            "body": { "mode": "raw", "raw": "{\n  \"action\": \"crm.leadVerification.verify\",\n  \"variables\": { \"id\": \"{{seedVerificationId}}\", \"notes\": \"Verified — insurance + damage confirmed.\" }\n}" },
+            "url": { "raw": "{{baseUrl}}/command", "host": ["{{baseUrl}}"], "path": ["command"] },
+            "description": "The critical cross-module command: flips the record to verified and creates a new Lead (status=new) in one transaction, linking both records. Returns { verification, lead }. A second call → 409 already_verified."
+          }
+        },
+        {
+          "name": "16. leadVerification.moveToPending",
+          "request": {
+            "method": "POST",
+            "header": [
+              { "key": "Authorization", "value": "Bearer dev" },
+              { "key": "X-App-ID", "value": "crm-web" },
+              { "key": "X-Tenant-ID", "value": "{{tenant}}" },
+              { "key": "X-Principal-ID", "value": "{{principal}}" },
+              { "key": "X-Idempotency-Key", "value": "{{$guid}}" },
+              { "key": "Content-Type", "value": "application/json" }
+            ],
+            "body": { "mode": "raw", "raw": "{\n  \"action\": \"crm.leadVerification.moveToPending\",\n  \"variables\": { \"id\": \"{{verificationId}}\" }\n}" },
+            "url": { "raw": "{{baseUrl}}/command", "host": ["{{baseUrl}}"], "path": ["command"] },
+            "description": "Send an assigned/in_progress record back to pending (keeps the assignee). Point at a non-verified {{verificationId}}."
+          }
+        },
+        {
+          "name": "17. leadVerification.markUnverified",
+          "request": {
+            "method": "POST",
+            "header": [
+              { "key": "Authorization", "value": "Bearer dev" },
+              { "key": "X-App-ID", "value": "crm-web" },
+              { "key": "X-Tenant-ID", "value": "{{tenant}}" },
+              { "key": "X-Principal-ID", "value": "{{principal}}" },
+              { "key": "X-Idempotency-Key", "value": "{{$guid}}" },
+              { "key": "Content-Type", "value": "application/json" }
+            ],
+            "body": { "mode": "raw", "raw": "{\n  \"action\": \"crm.leadVerification.markUnverified\",\n  \"variables\": { \"id\": \"{{verificationId}}\", \"reason\": \"Could not confirm ownership.\" }\n}" },
+            "url": { "raw": "{{baseUrl}}/command", "host": ["{{baseUrl}}"], "path": ["command"] },
+            "description": "Terminal outcome. Allowed from pending/assigned/in_progress; a verified record → 409. Point {{verificationId}} at a NON-verified record (run 10. intake to seed a fresh pending one)."
+          }
+        }
+      ]
+    },
+    {
+      "name": "Leads writes (POST /command)",
+      "item": [
+        {
+          "name": "20. lead.create (Full Form — captures createdLeadId)",
+          "event": [
+            {
+              "listen": "test",
+              "script": {
+                "type": "text/javascript",
+                "exec": [
+                  "const j = pm.response.json();",
+                  "if (j && j.id) { pm.collectionVariables.set('createdLeadId', j.id); pm.collectionVariables.set('leadId', j.id); }",
+                  "pm.test('priority normalized to lowercase', () => pm.expect(j.priority).to.eql('high'));"
+                ]
+              }
+            }
+          ],
+          "request": {
+            "method": "POST",
+            "header": [
+              { "key": "Authorization", "value": "Bearer dev" },
+              { "key": "X-App-ID", "value": "crm-web" },
+              { "key": "X-Tenant-ID", "value": "{{tenant}}" },
+              { "key": "X-Principal-ID", "value": "{{principal}}" },
+              { "key": "X-Idempotency-Key", "value": "{{$guid}}" },
+              { "key": "Content-Type", "value": "application/json" }
+            ],
+            "body": { "mode": "raw", "raw": "{\n  \"action\": \"crm.lead.create\",\n  \"variables\": {\n    \"firstName\": \"John\",\n    \"lastName\": \"Martinez\",\n    \"phones\": [\n      { \"number\": \"(469) 500-1000\", \"type\": \"Mobile\", \"primary\": true },\n      { \"number\": \"(469) 500-2000\", \"type\": \"Home\" }\n    ],\n    \"emails\": [ { \"address\": \"john.martinez@example.com\", \"primary\": true } ],\n    \"property\": { \"address\": \"4821 Spring Creek Pkwy\", \"city\": \"Plano\", \"state\": \"TX\", \"zip\": \"75023\", \"type\": \"Single Family\" },\n    \"job\": { \"source\": \"Door Knock\", \"canvasserId\": \"{{principal}}\", \"leadType\": \"Insurance\", \"workType\": \"Roof Replacement\", \"tradeType\": \"Roofing\", \"urgency\": \"High\", \"notes\": \"Significant granule loss on the south slope.\" },\n    \"insurance\": { \"company\": \"State Farm\", \"claimStatus\": \"Filed\", \"claimNumber\": \"CLM-2026-1000\", \"policyNumber\": \"POL-080000\", \"adjusterName\": \"Marcus Powell\", \"adjusterPhone\": \"(972) 700-3000\" },\n    \"assignment\": { \"assigneeId\": \"{{principal}}\", \"priority\": \"High\", \"followUp\": \"2026-06-04\" }\n  }\n}" },
+            "url": { "raw": "{{baseUrl}}/command", "host": ["{{baseUrl}}"], "path": ["command"] },
+            "description": "Quick + Full form intake. Only a non-empty name (firstName OR lastName) is required (else 422 name_required). Title-case priority is normalized to lowercase; the first phone is marked primary when none is flagged. DUPLICATE GUARD: if an active (non-closed) lead in the tenant has BOTH the same normalized primary phone AND the same address, the create is REJECTED with 409 duplicate_lead (the response's duplicateOf lists the existing lead) and no lead is inserted."
+          }
+        },
+        {
+          "name": "21. lead.update (partial patch)",
+          "request": {
+            "method": "POST",
+            "header": [
+              { "key": "Authorization", "value": "Bearer dev" },
+              { "key": "X-App-ID", "value": "crm-web" },
+              { "key": "X-Tenant-ID", "value": "{{tenant}}" },
+              { "key": "X-Principal-ID", "value": "{{principal}}" },
+              { "key": "X-Idempotency-Key", "value": "{{$guid}}" },
+              { "key": "Content-Type", "value": "application/json" }
+            ],
+            "body": { "mode": "raw", "raw": "{\n  \"action\": \"crm.lead.update\",\n  \"variables\": { \"id\": \"{{createdLeadId}}\", \"patch\": { \"priority\": \"Medium\", \"jobNotes\": \"Adjuster meeting scheduled.\" } }\n}" },
+            "url": { "raw": "{{baseUrl}}/command", "host": ["{{baseUrl}}"], "path": ["command"] }
+          }
+        },
+        {
+          "name": "22. lead.updateStatus (audited)",
+          "request": {
+            "method": "POST",
+            "header": [
+              { "key": "Authorization", "value": "Bearer dev" },
+              { "key": "X-App-ID", "value": "crm-web" },
+              { "key": "X-Tenant-ID", "value": "{{tenant}}" },
+              { "key": "X-Principal-ID", "value": "{{principal}}" },
+              { "key": "X-Idempotency-Key", "value": "{{$guid}}" },
+              { "key": "Content-Type", "value": "application/json" }
+            ],
+            "body": { "mode": "raw", "raw": "{\n  \"action\": \"crm.lead.updateStatus\",\n  \"variables\": { \"id\": \"{{createdLeadId}}\", \"status\": \"contacted\", \"note\": \"Spoke with homeowner.\" }\n}" },
+            "url": { "raw": "{{baseUrl}}/command", "host": ["{{baseUrl}}"], "path": ["command"] },
+            "description": "Appends a row to lead_status_history."
+          }
+        },
+        {
+          "name": "23. lead.assign (rep; null for Unassigned)",
+          "request": {
+            "method": "POST",
+            "header": [
+              { "key": "Authorization", "value": "Bearer dev" },
+              { "key": "X-App-ID", "value": "crm-web" },
+              { "key": "X-Tenant-ID", "value": "{{tenant}}" },
+              { "key": "X-Principal-ID", "value": "{{principal}}" },
+              { "key": "X-Idempotency-Key", "value": "{{$guid}}" },
+              { "key": "Content-Type", "value": "application/json" }
+            ],
+            "body": { "mode": "raw", "raw": "{\n  \"action\": \"crm.lead.assign\",\n  \"variables\": { \"id\": \"{{createdLeadId}}\", \"assigneeId\": \"{{principal}}\" }\n}" },
+            "url": { "raw": "{{baseUrl}}/command", "host": ["{{baseUrl}}"], "path": ["command"] }
+          }
+        },
+        {
+          "name": "24. lead.attachment.add (site photo — captures attachmentId)",
+          "event": [
+            {
+              "listen": "test",
+              "script": {
+                "type": "text/javascript",
+                "exec": [
+                  "const j = pm.response.json();",
+                  "if (j.attachments && j.attachments.length) pm.collectionVariables.set('attachmentId', j.attachments[j.attachments.length - 1].id);"
+                ]
+              }
+            }
+          ],
+          "request": {
+            "method": "POST",
+            "header": [
+              { "key": "Authorization", "value": "Bearer dev" },
+              { "key": "X-App-ID", "value": "crm-web" },
+              { "key": "X-Tenant-ID", "value": "{{tenant}}" },
+              { "key": "X-Principal-ID", "value": "{{principal}}" },
+              { "key": "X-Idempotency-Key", "value": "{{$guid}}" },
+              { "key": "Content-Type", "value": "application/json" }
+            ],
+            "body": { "mode": "raw", "raw": "{\n  \"action\": \"crm.lead.attachment.add\",\n  \"variables\": { \"id\": \"{{createdLeadId}}\", \"attachment\": { \"contentRef\": \"obj/site-photo-1.jpg\", \"mimeType\": \"image/jpeg\", \"sizeBytes\": 1048576, \"filename\": \"roof-south.jpg\" } }\n}" },
+            "url": { "raw": "{{baseUrl}}/command", "host": ["{{baseUrl}}"], "path": ["command"] },
+            "description": "contentRef is the object key returned by crm.media.presignUpload after the browser PUTs the bytes (§11.5). Files over 25 MB → 413 file_too_large."
+          }
+        },
+        {
+          "name": "25. lead.attachment.remove",
+          "request": {
+            "method": "POST",
+            "header": [
+              { "key": "Authorization", "value": "Bearer dev" },
+              { "key": "X-App-ID", "value": "crm-web" },
+              { "key": "X-Tenant-ID", "value": "{{tenant}}" },
+              { "key": "X-Principal-ID", "value": "{{principal}}" },
+              { "key": "X-Idempotency-Key", "value": "{{$guid}}" },
+              { "key": "Content-Type", "value": "application/json" }
+            ],
+            "body": { "mode": "raw", "raw": "{\n  \"action\": \"crm.lead.attachment.remove\",\n  \"variables\": { \"id\": \"{{createdLeadId}}\", \"attachmentId\": \"{{attachmentId}}\" }\n}" },
+            "url": { "raw": "{{baseUrl}}/command", "host": ["{{baseUrl}}"], "path": ["command"] },
+            "description": "Run 24 first so {{attachmentId}} is captured."
+          }
+        }
+      ]
+    },
+    {
+      "name": "Negative / guard checks",
+      "item": [
+        {
+          "name": "Verify an already-verified record (expect 409 already_verified)",
+          "request": {
+            "method": "POST",
+            "header": [
+              { "key": "Authorization", "value": "Bearer dev" },
+              { "key": "X-App-ID", "value": "crm-web" },
+              { "key": "X-Tenant-ID", "value": "{{tenant}}" },
+              { "key": "X-Principal-ID", "value": "{{principal}}" },
+              { "key": "X-Idempotency-Key", "value": "{{$guid}}" },
+              { "key": "Content-Type", "value": "application/json" }
+            ],
+            "body": { "mode": "raw", "raw": "{\n  \"action\": \"crm.leadVerification.verify\",\n  \"variables\": { \"id\": \"{{seedVerificationId}}\" }\n}" },
+            "url": { "raw": "{{baseUrl}}/command", "host": ["{{baseUrl}}"], "path": ["command"] },
+            "description": "Run 15. verify first — a second verify on the same record is rejected (no duplicate Lead)."
+          }
+        },
+        {
+          "name": "Create with no name (expect 422 name_required)",
+          "request": {
+            "method": "POST",
+            "header": [
+              { "key": "Authorization", "value": "Bearer dev" },
+              { "key": "X-App-ID", "value": "crm-web" },
+              { "key": "X-Tenant-ID", "value": "{{tenant}}" },
+              { "key": "X-Principal-ID", "value": "{{principal}}" },
+              { "key": "X-Idempotency-Key", "value": "{{$guid}}" },
+              { "key": "Content-Type", "value": "application/json" }
+            ],
+            "body": { "mode": "raw", "raw": "{\n  \"action\": \"crm.lead.create\",\n  \"variables\": { \"firstName\": \"\", \"lastName\": \"  \" }\n}" },
+            "url": { "raw": "{{baseUrl}}/command", "host": ["{{baseUrl}}"], "path": ["command"] }
+          }
+        },
+        {
+          "name": "Create with a bad email (expect 400 validation)",
+          "request": {
+            "method": "POST",
+            "header": [
+              { "key": "Authorization", "value": "Bearer dev" },
+              { "key": "X-App-ID", "value": "crm-web" },
+              { "key": "X-Tenant-ID", "value": "{{tenant}}" },
+              { "key": "X-Principal-ID", "value": "{{principal}}" },
+              { "key": "X-Idempotency-Key", "value": "{{$guid}}" },
+              { "key": "Content-Type", "value": "application/json" }
+            ],
+            "body": { "mode": "raw", "raw": "{\n  \"action\": \"crm.lead.create\",\n  \"variables\": { \"firstName\": \"Jane\", \"emails\": [ { \"address\": \"not-an-email\" } ] }\n}" },
+            "url": { "raw": "{{baseUrl}}/command", "host": ["{{baseUrl}}"], "path": ["command"] }
+          }
+        },
+        {
+          "name": "Verify via generic updateStatus (expect 422 — use verify)",
+          "request": {
+            "method": "POST",
+            "header": [
+              { "key": "Authorization", "value": "Bearer dev" },
+              { "key": "X-App-ID", "value": "crm-web" },
+              { "key": "X-Tenant-ID", "value": "{{tenant}}" },
+              { "key": "X-Principal-ID", "value": "{{principal}}" },
+              { "key": "X-Idempotency-Key", "value": "{{$guid}}" },
+              { "key": "Content-Type", "value": "application/json" }
+            ],
+            "body": { "mode": "raw", "raw": "{\n  \"action\": \"crm.leadVerification.updateStatus\",\n  \"variables\": { \"id\": \"{{verificationId}}\", \"status\": \"verified\" }\n}" },
+            "url": { "raw": "{{baseUrl}}/command", "host": ["{{baseUrl}}"], "path": ["command"] },
+            "description": "The generic status setter refuses 'verified' — verification must go through crm.leadVerification.verify (which promotes a Lead)."
+          }
+        }
+      ]
+    }
+  ]
+}

src/app/dashboard/dashboard.css

@@ -1278,8 +1278,23 @@
   .dash-root .nl-photos-s { font-size: 11px; }
   .dash-root .nl-photo-chips { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 10px; }
   .dash-root .nl-photo-chip { display: inline-flex; align-items: center; gap: 5px; font-size: 11.5px; font-weight: 600; padding: 5px 10px; border-radius: 99px; background: color-mix(in srgb, var(--green) 15%, transparent); color: var(--green); }
+  .dash-root .nl-photo-chip-x { display: inline-flex; align-items: center; justify-content: center; margin-left: 2px; padding: 0; border: none; background: none; color: inherit; opacity: 0.65; cursor: pointer; }
+  .dash-root .nl-photo-chip-x:hover { opacity: 1; }
   .dash-root .ds-select.is-placeholder { color: var(--faint, var(--muted)); }
 
+  /* Detail popup — property photo gallery */
+  .dash-root .ld-photo-block { margin-bottom: 14px; }
+  .dash-root .ld-photo-block .ld-section-head { margin-bottom: 8px; }
+  .dash-root .ld-photos { display: grid; grid-template-columns: repeat(auto-fill, minmax(112px, 1fr)); gap: 8px; }
+  .dash-root .ld-photo { position: relative; display: block; aspect-ratio: 1; border-radius: 10px; overflow: hidden; border: 1px solid var(--border-2); background: var(--panel-2); cursor: pointer; }
+  .dash-root .ld-photo img { width: 100%; height: 100%; object-fit: cover; display: block; }
+  .dash-root .ld-photo-ph { position: absolute; inset: 0; display: flex; align-items: center; justify-content: center; color: var(--muted); }
+  /* Edit mode — photo tile with a remove badge */
+  .dash-root .nl-edit-photos { margin-bottom: 8px; }
+  .dash-root .ld-photo-edit { position: relative; }
+  .dash-root .ld-photo-x { position: absolute; top: 4px; right: 4px; display: inline-flex; align-items: center; justify-content: center; width: 20px; height: 20px; border: none; border-radius: 99px; background: rgba(0,0,0,0.6); color: #fff; cursor: pointer; }
+  .dash-root .ld-photo-x:hover { background: var(--red, #e5484d); }
+
   /* Canvasser search (Door Knock source) */
   .dash-root .nl-canvasser { position: relative; }
   .dash-root .nl-canvasser-menu { position: absolute; top: calc(100% + 4px); left: 0; right: 0; z-index: 30; max-height: 220px; overflow-y: auto; border: 1px solid var(--border-2); border-radius: 12px; background: var(--panel); box-shadow: 0 12px 32px rgba(0,0,0,0.28); padding: 5px; }
@@ -1358,6 +1373,21 @@
   .lv-menu-item svg { color: var(--muted, #8c8c8c); flex: 0 0 auto; }
   .lv-menu-item:hover svg { color: var(--orange, #fda913); }
 
+  /* ---- change-assignee popup ---- */
+  .dash-root .lv-assign { display: flex; flex-direction: column; gap: 12px; }
+  .dash-root .lv-assign-search { display: flex; align-items: center; gap: 8px; padding: 9px 11px; border-radius: 11px; border: 1px solid var(--border); background: var(--panel-2); }
+  .dash-root .lv-assign-search svg { color: var(--muted); flex: 0 0 auto; }
+  .dash-root .lv-assign-search input { flex: 1; min-width: 0; border: 0; background: none; color: var(--text); font-family: inherit; font-size: 13px; outline: none; }
+  .dash-root .lv-assign-x { display: inline-flex; border: 0; background: none; color: var(--muted); cursor: pointer; padding: 0; }
+  .dash-root .lv-assign-x:hover { color: var(--text); }
+  .dash-root .lv-assign-list { display: flex; flex-direction: column; gap: 2px; max-height: 320px; overflow-y: auto; margin: -4px; padding: 4px; }
+  .dash-root .lv-assign-opt { display: flex; align-items: center; gap: 10px; width: 100%; padding: 8px 10px; border: 0; border-radius: 10px; background: none; color: var(--text-2); font-family: inherit; font-size: 13px; font-weight: 600; cursor: pointer; text-align: left; }
+  .dash-root .lv-assign-opt:hover { background: var(--panel-3, #1b1b22); color: var(--text); }
+  .dash-root .lv-assign-opt.current { background: color-mix(in srgb, var(--orange) 12%, transparent); }
+  .dash-root .lv-assign-name { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .dash-root .lv-assign-opt.current > svg { color: var(--orange); flex: 0 0 auto; }
+  .dash-root .lv-assign-empty { padding: 20px 10px; text-align: center; color: var(--muted); font-size: 12.5px; }
+
   /* ---- verification detail popup ---- */
   .dash-root .lv-detail { display: flex; flex-direction: column; gap: 16px; }
   .dash-root .lv-d-identity { display: flex; align-items: center; gap: 14px; }

src/components/dashboard/leads-data.ts

@@ -12,9 +12,16 @@ export type LeadPriority = "high" | "medium" | "low";
 
 export type Phone = { number: string; type: "Mobile" | "Home" | "Work"; primary?: boolean };
 export type Email = { address: string; type?: string; primary?: boolean };
+/** A site photo (or other file) stored via the media presign flow (§11.5).
+ *  `contentRef` is the IIOS object key — render it through a signed download URL. */
+export type Attachment = { id?: string; contentRef: string; mimeType: string; sizeBytes: number; filename: string };
 
 export type Lead = {
-  id: string;            // SAL-001
+  id: string;            // SAL-001 (display code)
+  refId?: string;        // opaque server id (live mode); commands target this — falls back to `id`
+  /** Set once the lead has been pushed to the verification queue — blocks a duplicate send.
+   *  Populated from the backend (e.g. LeadDTO.verificationId) when available. */
+  verificationId?: string;
   initials: string;
   name: string;
   gradient: string;
@@ -31,6 +38,9 @@ export type Lead = {
   phones: Phone[];
   emails: Email[];
 
+  // site photos (uploaded via the media presign flow; shown in the detail popup)
+  attachments?: Attachment[];
+
   // property
   property: { address: string; city: string; state: string; zip: string; type: string };
 

src/components/dashboard/leads.tsx

@@ -11,13 +11,15 @@
 // Data comes from leads-data.ts (client-side mock).
 // ============================================================
 
-import { useMemo, useState, type ReactNode } from "react";
+import { useEffect, useMemo, useRef, useState, type ReactNode } from "react";
 import { Avatar, Btn, Field, Icon, Modal, PageHead, Pill, Segmented, SegTabs, useToast } from "./ui";
 import {
-  LEADS, TOTAL_LEADS, STATUS_META, PRIORITY_META,
+  STATUS_META, PRIORITY_META,
-  REPS, LEAD_SOURCES, WORK_TYPES, TRADE_TYPES, CLAIM_STATUSES,
+  LEAD_SOURCES, LEAD_TYPES, PROPERTY_TYPES, WORK_TYPES, TRADE_TYPES, CLAIM_STATUSES,
-  type Lead, type LeadStatus,
+  type Lead, type LeadStatus, type Rep, type Attachment,
 } from "./leads-data";
+import { useLeadsData, type CreateLeadInput, type LeadsData } from "@/lib/leads-api";
+import { MAX_ATTACHMENT_BYTES, isImage, type UploadedAttachment } from "@/lib/media-api";
 
 const STATUS_TABS: { value: "all" | LeadStatus; label: string }[] = [
   { value: "all", label: "All" },
@@ -28,44 +30,50 @@ const STATUS_TABS: { value: "all" | LeadStatus; label: string }[] = [
 ];
 
 export function Leads() {
-  const toast = useToast();
+  const data = useLeadsData();
+  const { leads, total, byStatus, loading, error } = data;
   const [query, setQuery] = useState("");
   const [filter, setFilter] = useState<"all" | LeadStatus>("all");
   const [selected, setSelected] = useState<Lead | null>(null);
   const [newOpen, setNewOpen] = useState(false);
-
+  // Leads already pushed to the verification queue this session — blocks a second send
-  const countByStatus = useMemo(() => {
+  // (interim guard until the backend exposes a persistent verification status; see notes).
-    const m: Record<string, number> = {};
+  const [sentIds, setSentIds] = useState<Set<string>>(() => new Set());
-    for (const l of LEADS) m[l.status] = (m[l.status] ?? 0) + 1;
+  const idOf = (l: Lead) => l.refId ?? l.id;
-    return m;
-  }, []);
 
   const filtered = useMemo(() => {
     const q = query.trim().toLowerCase();
-    return LEADS.filter((l) => {
+    return leads.filter((l) => {
       const matchStatus = filter === "all" || l.status === filter;
       const hay = `${l.name} ${l.property.address} ${l.property.city} ${l.job.source} ${l.job.canvasser}`.toLowerCase();
       return matchStatus && (!q || hay.includes(q));
     });
-  }, [query, filter]);
+  }, [leads, query, filter]);
+
+  // Open a card immediately with its list-level data, then hydrate the full detail (live mode
+  // list rows carry card fields only). Ignore hydration errors — the card data still renders.
+  const openLead = (l: Lead) => {
+    setSelected(l);
+    data.getLead(l).then((full) => setSelected((cur) => (cur && cur.id === l.id ? full : cur))).catch(() => {});
+  };
 
   return (
     <div className="view leads">
       <PageHead
         eyebrow="Sales"
         title="Leads"
-        subtitle={`${TOTAL_LEADS} total leads · Plano hail zone · storm 2026-04-28`}
+        subtitle={`${total} total leads`}
         icon="leads"
         actions={<Btn icon="plus" onClick={() => setNewOpen(true)}>New Lead</Btn>}
       />
 
       {/* ---- stat strip ---------------------------------------- */}
       <div className="leads-stats">
-        <StatCard label="Total leads" value={TOTAL_LEADS} icon="leads" tone="orange" />
+        <StatCard label="Total leads" value={total} icon="leads" tone="orange" />
-        <StatCard label="New" value={countByStatus.new ?? 0} icon="star" tone="blue" />
+        <StatCard label="New" value={byStatus.new} icon="star" tone="blue" />
-        <StatCard label="Contacted" value={countByStatus.contacted ?? 0} icon="phone" tone="orange" />
+        <StatCard label="Contacted" value={byStatus.contacted} icon="phone" tone="orange" />
-        <StatCard label="Appointed" value={countByStatus.appointed ?? 0} icon="clock" tone="purple" />
+        <StatCard label="Appointed" value={byStatus.appointed} icon="clock" tone="purple" />
-        <StatCard label="Closed" value={countByStatus.closed ?? 0} icon="check-circle" tone="green" />
+        <StatCard label="Closed" value={byStatus.closed} icon="check-circle" tone="green" />
       </div>
 
       {/* ---- toolbar ------------------------------------------- */}
@@ -96,7 +104,19 @@ export function Leads() {
       </div>
 
       {/* ---- board --------------------------------------------- */}
-      {filtered.length === 0 ? (
+      {error ? (
+        <div className="card leads-empty">
+          <Icon name="alert" size={30} />
+          <h3>Couldn’t load leads</h3>
+          <p>{error}</p>
+        </div>
+      ) : loading && filtered.length === 0 ? (
+        <div className="card leads-empty">
+          <Icon name="refresh" size={30} />
+          <h3>Loading leads…</h3>
+          <p>Fetching the Plano pipeline.</p>
+        </div>
+      ) : filtered.length === 0 ? (
         <div className="card leads-empty">
           <Icon name="search" size={30} />
           <h3>No leads match</h3>
@@ -105,13 +125,21 @@ export function Leads() {
       ) : (
         <div className="leads-grid">
           {filtered.map((l) => (
-            <LeadCard key={l.id} lead={l} onOpen={() => setSelected(l)} />
+            <LeadCard key={l.id} lead={l} onOpen={() => openLead(l)} />
           ))}
         </div>
       )}
 
-      <LeadDetail lead={selected} onClose={() => setSelected(null)} />
+      <LeadDetail
-      <NewLead open={newOpen} onClose={() => setNewOpen(false)} />
+        lead={selected}
+        onClose={() => setSelected(null)}
+        data={data}
+        reps={data.reps}
+        onHydrate={setSelected}
+        sent={!!selected && sentIds.has(idOf(selected))}
+        onSent={() => selected && setSentIds((s) => new Set(s).add(idOf(selected)))}
+      />
+      <NewLead open={newOpen} onClose={() => setNewOpen(false)} createLead={data.createLead} reps={data.reps} uploadPhoto={data.uploadPhoto} />
     </div>
   );
 }
@@ -149,7 +177,7 @@ function LeadCard({ lead, onOpen }: { lead: Lead; onOpen: () => void }) {
         </span>
         <div className="lead-card-id">
           <div className="lead-card-name">{lead.name}</div>
-          <div className="lead-card-sub"><span className="lead-code">{lead.id}</span> · <Icon name="storm" size={12} /> {lead.tag}</div>
+          <div className="lead-card-sub"><span className="lead-code">{lead.id}</span></div>
         </div>
         <Pill tone={priority.tone}><Icon name="alert" size={11} /> {priority.label}</Pill>
       </div>
@@ -172,27 +200,261 @@ function LeadCard({ lead, onOpen }: { lead: Lead; onOpen: () => void }) {
 /* Lead detail popup                                           */
 /* ---------------------------------------------------------- */
 
-function LeadDetail({ lead, onClose }: { lead: Lead | null; onClose: () => void }) {
+type LeadEdit = {
+  firstName: string; lastName: string;
+  phones: PhoneRow[]; emails: EmailRow[];
+  address: string; city: string; state: string; zip: string; propertyType: string;
+  source: string; leadType: string; workType: string; tradeType: string; urgency: string; notes: string;
+  insCompany: string; claimStatus: string; claimNumber: string; policyNumber: string; adjusterName: string; adjusterPhone: string;
+  assignRep: string; priority: string; followUp: string;
+  photos: Attachment[];
+};
+
+// Convert a pretty date ("Jun 4, 2026") — or "—"/"" — to a yyyy-mm-dd value for <input type=date>.
+function toDateInput(s: string): string {
+  if (!s || s === "—") return "";
+  const t = Date.parse(s);
+  if (Number.isNaN(t)) return "";
+  const d = new Date(t);
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+}
+
+function initEdit(lead: Lead, reps: Rep[]): LeadEdit {
+  const [firstName, ...rest] = lead.name.split(/\s+/);
+  const rep = reps.find((r) => r.name === lead.assignment.assignedTo);
+  return {
+    firstName: firstName ?? "", lastName: rest.join(" "),
+    phones: lead.phones.length ? lead.phones.map((p) => ({ number: p.number, type: p.type })) : [{ number: "", type: "Mobile" }],
+    emails: lead.emails.map((e) => ({ address: e.address })),
+    address: lead.property.address, city: lead.property.city, state: lead.property.state, zip: lead.property.zip, propertyType: lead.property.type,
+    source: lead.job.source, leadType: lead.job.leadType, workType: lead.job.workType, tradeType: lead.job.tradeType, urgency: lead.job.urgency || "Standard", notes: lead.job.notes,
+    insCompany: lead.insurance.company, claimStatus: lead.insurance.claimStatus, claimNumber: lead.insurance.claimNumber,
+    policyNumber: lead.insurance.policyNumber, adjusterName: lead.insurance.adjusterName, adjusterPhone: lead.insurance.adjusterPhone,
+    assignRep: rep?.id ?? "", priority: lead.assignment.priority || "Medium", followUp: toDateInput(lead.assignment.followUp),
+    photos: lead.attachments ?? [],
+  };
+}
+
+function buildPatch(f: LeadEdit): import("@/lib/leads-api").LeadPatch {
+  return {
+    firstName: f.firstName.trim(), lastName: f.lastName.trim(),
+    phones: f.phones.filter((p) => p.number.trim()).map((p, i) => ({ number: p.number.trim(), type: p.type, primary: i === 0 })),
+    emails: f.emails.filter((e) => e.address.trim()).map((e, i) => ({ address: e.address.trim(), primary: i === 0 })),
+    propertyAddress: f.address, propertyCity: f.city, propertyState: f.state, propertyZip: f.zip, propertyType: f.propertyType || undefined,
+    source: f.source || undefined, leadType: f.leadType || undefined, workType: f.workType || undefined,
+    tradeType: f.tradeType || undefined, urgency: f.urgency || undefined, jobNotes: f.notes,
+    insuranceCompany: f.insCompany, insuranceClaimStatus: f.claimStatus || undefined, insuranceClaimNumber: f.claimNumber,
+    insurancePolicyNumber: f.policyNumber, insuranceAdjusterName: f.adjusterName, insuranceAdjusterPhone: f.adjusterPhone,
+    assignedToId: f.assignRep || null, followUpDate: f.followUp || undefined, priority: f.priority,
+  };
+}
+
+function LeadDetail({ lead, onClose, data, reps, onHydrate, sent, onSent }: { lead: Lead | null; onClose: () => void; data: LeadsData; reps: Rep[]; onHydrate: (l: Lead) => void; sent: boolean; onSent: () => void }) {
   if (!lead) return null;
+  // Keyed by id so edit state resets when a different lead opens.
+  return <LeadDetailBody key={lead.refId ?? lead.id} lead={lead} onClose={onClose} data={data} reps={reps} onHydrate={onHydrate} sent={sent} onSent={onSent} />;
+}
+
+function LeadDetailBody({ lead, onClose, data, reps, onHydrate, sent, onSent }: { lead: Lead; onClose: () => void; data: LeadsData; reps: Rep[]; onHydrate: (l: Lead) => void; sent: boolean; onSent: () => void }) {
+  const toast = useToast();
+  const [editing, setEditing] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const [sending, setSending] = useState(false);
+  const [f, setF] = useState<LeadEdit | null>(null);
+  const [uploading, setUploading] = useState(0);
+  const editFileRef = useRef<HTMLInputElement>(null);
+
   const status = STATUS_META[lead.status];
   const priority = PRIORITY_META[lead.priority];
+  const primaryPhone = lead.phones.find((p) => p.primary) ?? lead.phones[0];
+  const primaryEmail = lead.emails.find((e) => e.primary) ?? lead.emails[0];
+  const repOptions = [{ id: "", initials: "—", name: "Unassigned", email: "" }, ...reps];
+
+  const call = () => {
+    if (!primaryPhone?.number) { toast.push({ tone: "error", title: "No phone", desc: "This lead has no phone number." }); return; }
+    window.location.href = `tel:${primaryPhone.number.replace(/[^\d+]/g, "")}`;
+  };
+  const email = () => {
+    if (!primaryEmail?.address) { toast.push({ tone: "error", title: "No email", desc: "This lead has no email address." }); return; }
+    window.location.href = `mailto:${primaryEmail.address}`;
+  };
+
+  const startEdit = () => { setF(initEdit(lead, reps)); setEditing(true); };
+  const cancelEdit = () => { setEditing(false); setF(null); };
+  const setField = (k: keyof LeadEdit) => (e: { target: { value: string } }) => setF((s) => (s ? { ...s, [k]: e.target.value } : s));
+  const addPhone = () => setF((s) => (s ? { ...s, phones: [...s.phones, { number: "", type: "Mobile" }] } : s));
+  const setPhone = (i: number, key: "number" | "type", v: string) => setF((s) => (s ? { ...s, phones: s.phones.map((p, j) => (j === i ? { ...p, [key]: v } : p)) } : s));
+  const removePhone = (i: number) => setF((s) => (s ? { ...s, phones: s.phones.filter((_, j) => j !== i) } : s));
+  const addEmail = () => setF((s) => (s ? { ...s, emails: [...s.emails, { address: "" }] } : s));
+  const setEmail = (i: number, v: string) => setF((s) => (s ? { ...s, emails: s.emails.map((e, j) => (j === i ? { address: v } : e)) } : s));
+  const removeEmail = (i: number) => setF((s) => (s ? { ...s, emails: s.emails.filter((_, j) => j !== i) } : s));
+  const removeEditPhoto = (contentRef: string) => setF((s) => (s ? { ...s, photos: s.photos.filter((p) => p.contentRef !== contentRef) } : s));
+
+  // Upload picked files to storage (presign → PUT), then stage them on the edit form. They're
+  // attached to the lead on Save via crm.lead.attachment.add (see the reconcile in save()).
+  async function onPickEditPhotos(e: React.ChangeEvent<HTMLInputElement>) {
+    const files = Array.from(e.target.files ?? []);
+    e.target.value = "";
+    for (const file of files) {
+      if (!isImage(file.type)) { toast.push({ tone: "error", title: "Not an image", desc: `${file.name} isn't an image file.` }); continue; }
+      if (file.size > MAX_ATTACHMENT_BYTES) { toast.push({ tone: "error", title: "Too large", desc: `${file.name} exceeds the 25 MB limit.` }); continue; }
+      setUploading((n) => n + 1);
+      try {
+        const up = await data.uploadPhoto(file);
+        setF((s) => (s ? { ...s, photos: [...s.photos, up] } : s));
+      } catch (err) {
+        toast.push({ tone: "error", title: "Upload failed", desc: err instanceof Error ? err.message : `Couldn't upload ${file.name}.` });
+      } finally {
+        setUploading((n) => n - 1);
+      }
+    }
+  }
+
+  async function save() {
+    if (!f) return;
+    if (!`${f.firstName} ${f.lastName}`.trim()) { toast.push({ tone: "error", title: "Name required", desc: "Enter the homeowner's first or last name." }); return; }
+    setSaving(true);
+    try {
+      await data.updateLead(lead, buildPatch(f));
+      // Reconcile photos against what the lead had: attach the newly-added, detach the removed.
+      const orig = lead.attachments ?? [];
+      const toAdd = f.photos.filter((p) => !orig.some((o) => o.contentRef === p.contentRef));
+      const toRemove = orig.filter((o) => !f.photos.some((p) => p.contentRef === o.contentRef));
+      for (const a of toAdd) await data.addPhoto(lead, a);
+      for (const r of toRemove) await data.removePhoto(lead, r);
+      try { onHydrate(await data.getLead(lead)); } catch { /* keep current view if re-fetch fails */ }
+      toast.push({ tone: "success", title: "Lead updated", desc: `${`${f.firstName} ${f.lastName}`.trim()} saved.` });
+      setEditing(false); setF(null);
+    } catch (e) {
+      toast.push({ tone: "error", title: "Update failed", desc: e instanceof Error ? e.message : "Please try again." });
+    } finally { setSaving(false); }
+  }
+
+  // Already in the verification queue if the backend says so (verificationId) or we sent it this session.
+  const alreadySent = sent || !!lead.verificationId;
+
+  async function sendForVerification() {
+    if (alreadySent) return;
+    setSending(true);
+    try {
+      await data.sendForVerification(lead);
+      onSent();
+      toast.push({ tone: "success", title: "Sent for verification", desc: `${lead.name} added to the verification queue.` });
+    } catch (e) {
+      toast.push({ tone: "error", title: "Couldn’t send", desc: e instanceof Error ? e.message : "Please try again." });
+    } finally { setSending(false); }
+  }
 
   return (
     <Modal
-      open={!!lead}
+      open
       onClose={onClose}
       size="lg"
       title={lead.name}
-      subtitle={`${lead.id} · ${lead.tag}`}
+      subtitle={lead.id}
       icon="leads"
-      footer={
+      footer={editing ? (
         <>
-          <Btn variant="ghost" icon="phone">Call</Btn>
+          <Btn variant="ghost" onClick={cancelEdit} disabled={saving}>Cancel</Btn>
-          <Btn variant="outline" icon="mail">Email</Btn>
+          <Btn icon="check" onClick={save} disabled={saving}>{saving ? "Saving…" : "Save Changes"}</Btn>
-          <Btn icon="check-circle">Update Status</Btn>
         </>
-      }
+      ) : (
+        <>
+          <Btn variant="ghost" icon="edit" onClick={startEdit}>Edit</Btn>
+          <Btn variant="ghost" icon="phone" onClick={call}>Call</Btn>
+          <Btn variant="outline" icon="mail" onClick={email}>Email</Btn>
+          <Btn icon={alreadySent ? "check-circle" : "verify"} onClick={sendForVerification} disabled={sending || alreadySent}>
+            {alreadySent ? "Sent for Verification" : sending ? "Sending…" : "Send for Verification"}
+          </Btn>
+        </>
+      )}
     >
+      {editing && f ? (
+        <div className="nl-form lead-edit">
+          <div className="ld-section-head"><Icon name="user" size={15} /> Contact</div>
+          <div className="nl-grid">
+            <Field label="First Name" required><input className="ds-input" value={f.firstName} onChange={setField("firstName")} placeholder="John" /></Field>
+            <Field label="Last Name"><input className="ds-input" value={f.lastName} onChange={setField("lastName")} placeholder="Smith" /></Field>
+            <div className="nl-full">
+              <div className="ds-field-lbl">Phone Numbers</div>
+              {f.phones.map((p, i) => (
+                <div className="nl-multirow" key={i}>
+                  <input className="ds-input" value={p.number} onChange={(e) => setPhone(i, "number", e.target.value)} placeholder="(555) 000-0000" />
+                  <select className="ds-select nl-typesel" value={p.type} onChange={(e) => setPhone(i, "type", e.target.value)}>
+                    {["Mobile", "Home", "Work"].map((t) => <option key={t} value={t}>{t}</option>)}
+                  </select>
+                  {f.phones.length > 1 && <button type="button" className="nl-rowx" aria-label="Remove phone" onClick={() => removePhone(i)}><Icon name="trash" size={15} /></button>}
+                </div>
+              ))}
+              <button type="button" className="nl-add" onClick={addPhone}><Icon name="plus" size={14} /> Add Phone</button>
+            </div>
+            <div className="nl-full">
+              <div className="ds-field-lbl">Email Addresses</div>
+              {f.emails.length === 0 && <div className="nl-empty">No emails added yet.</div>}
+              {f.emails.map((em, i) => (
+                <div className="nl-multirow" key={i}>
+                  <input className="ds-input" type="email" value={em.address} onChange={(e) => setEmail(i, e.target.value)} placeholder="name@email.com" />
+                  <button type="button" className="nl-rowx" aria-label="Remove email" onClick={() => removeEmail(i)}><Icon name="trash" size={15} /></button>
+                </div>
+              ))}
+              <button type="button" className="nl-add" onClick={addEmail}><Icon name="plus" size={14} /> Add Email</button>
+            </div>
+          </div>
+
+          <div className="ld-section-head"><Icon name="owners" size={15} /> Property</div>
+          <div className="nl-grid">
+            <div className="nl-full"><Field label="Street Address"><input className="ds-input" value={f.address} onChange={setField("address")} placeholder="123 Main St" /></Field></div>
+            <Field label="City"><input className="ds-input" value={f.city} onChange={setField("city")} placeholder="Plano" /></Field>
+            <Field label="State"><input className="ds-input" value={f.state} onChange={setField("state")} placeholder="TX" /></Field>
+            <Field label="ZIP"><input className="ds-input" value={f.zip} onChange={setField("zip")} placeholder="75023" /></Field>
+            <Field label="Property Type"><Select value={f.propertyType} onChange={setField("propertyType")} options={PROPERTY_TYPE_OPTS} placeholder="Select type…" /></Field>
+            <div className="nl-full">
+              <div className="ds-field-lbl">Site Photos</div>
+              <input ref={editFileRef} type="file" accept="image/*" multiple hidden onChange={onPickEditPhotos} />
+              {f.photos.length > 0 && (
+                <div className="ld-photos nl-edit-photos">
+                  {f.photos.map((p) => (
+                    <div key={p.contentRef} className="ld-photo-edit">
+                      <LeadPhoto att={p} getUrl={data.getPhotoUrl} />
+                      <button type="button" className="ld-photo-x" aria-label={`Remove ${p.filename}`} onClick={() => removeEditPhoto(p.contentRef)}><Icon name="x" size={13} /></button>
+                    </div>
+                  ))}
+                </div>
+              )}
+              <button type="button" className="nl-add" onClick={() => editFileRef.current?.click()}>
+                <Icon name="camera" size={14} /> {uploading > 0 ? `Uploading ${uploading}…` : "Add Photos"}
+              </button>
+            </div>
+          </div>
+
+          <div className="ld-section-head"><Icon name="projects" size={15} /> Job Details</div>
+          <div className="nl-grid">
+            <Field label="Lead Source"><Select value={f.source} onChange={setField("source")} options={LEAD_SOURCES} placeholder="Source…" /></Field>
+            <Field label="Lead Type"><Select value={f.leadType} onChange={setField("leadType")} options={LEAD_TYPE_OPTS} placeholder="Type…" /></Field>
+            <Field label="Work Type"><Select value={f.workType} onChange={setField("workType")} options={WORK_TYPES} placeholder="Work…" /></Field>
+            <Field label="Trade Type"><Select value={f.tradeType} onChange={setField("tradeType")} options={TRADE_TYPES} placeholder="Trade…" /></Field>
+            <Field label="Urgency"><Select value={f.urgency} onChange={setField("urgency")} options={["Standard", "High", "Emergency"]} /></Field>
+            <div className="nl-full"><Field label="Field Notes"><textarea className="ds-textarea" rows={3} value={f.notes} onChange={setField("notes")} /></Field></div>
+          </div>
+
+          <div className="ld-section-head"><Icon name="shield" size={15} /> Insurance</div>
+          <div className="nl-grid">
+            <div className="nl-full"><Field label="Insurance Company"><input className="ds-input" value={f.insCompany} onChange={setField("insCompany")} placeholder="State Farm" /></Field></div>
+            <Field label="Claim Number"><input className="ds-input" value={f.claimNumber} onChange={setField("claimNumber")} /></Field>
+            <Field label="Claim Status"><Select value={f.claimStatus} onChange={setField("claimStatus")} options={CLAIM_STATUSES} placeholder="Status…" /></Field>
+            <Field label="Adjuster Name"><input className="ds-input" value={f.adjusterName} onChange={setField("adjusterName")} /></Field>
+            <Field label="Adjuster Phone"><input className="ds-input" value={f.adjusterPhone} onChange={setField("adjusterPhone")} /></Field>
+            <div className="nl-full"><Field label="Policy Number"><input className="ds-input" value={f.policyNumber} onChange={setField("policyNumber")} /></Field></div>
+          </div>
+
+          <div className="ld-section-head"><Icon name="team" size={15} /> Assignment</div>
+          <div className="nl-grid">
+            <div className="nl-full"><Field label="Assign Rep"><RepSelect value={f.assignRep} onChange={setField("assignRep")} options={repOptions} /></Field></div>
+            <Field label="Priority"><Select value={f.priority} onChange={setField("priority")} options={["Low", "Medium", "High"]} /></Field>
+            <Field label="Follow-up Date"><input className="ds-input" type="date" value={f.followUp} onChange={setField("followUp")} /></Field>
+          </div>
+        </div>
+      ) : (
         <div className="lead-detail">
           {/* identity strip */}
           <div className="ld-identity">
@@ -206,14 +468,28 @@ function LeadDetail({ lead, onClose }: { lead: Lead | null; onClose: () => void
             </div>
           </div>
 
-        {/* storm banner */}
+          {/* storm banner — only when the lead actually carries storm data */}
+          {(lead.storm.zone || lead.storm.date || lead.storm.detail) && (
             <div className="ld-storm">
               <span className="ld-storm-ic"><Icon name="storm" size={18} /></span>
               <div>
                 <div className="ld-storm-zone">{lead.storm.zone}</div>
-            <div className="ld-storm-meta">{lead.storm.date} · {lead.storm.detail}</div>
+                <div className="ld-storm-meta">{[lead.storm.date, lead.storm.detail].filter(Boolean).join(" · ")}</div>
               </div>
             </div>
+          )}
+
+          {/* Property photos */}
+          {(lead.attachments?.length ?? 0) > 0 && (
+            <div className="ld-photo-block">
+              <div className="ld-section-head"><Icon name="camera" size={15} /> Property Photos</div>
+              <div className="ld-photos">
+                {lead.attachments!.map((a) => (
+                  <LeadPhoto key={a.contentRef} att={a} getUrl={data.getPhotoUrl} />
+                ))}
+              </div>
+            </div>
+          )}
 
           <div className="ld-grid">
             {/* Contact */}
@@ -282,6 +558,7 @@ function LeadDetail({ lead, onClose }: { lead: Lead | null; onClose: () => void
             </Section>
           </div>
         </div>
+      )}
     </Modal>
   );
 }
@@ -304,6 +581,28 @@ function Dl({ label, value }: { label: string; value: string }) {
   );
 }
 
+// Renders a stored site photo. `contentRef` is an opaque object key, so we mint a short-lived
+// signed URL on mount (mock mode passes the object URL straight through). Clicking opens full-size.
+function LeadPhoto({ att, getUrl }: { att: Attachment; getUrl: (contentRef: string, mime?: string) => Promise<string> }) {
+  const [url, setUrl] = useState<string | null>(null);
+  const [failed, setFailed] = useState(false);
+  useEffect(() => {
+    let alive = true;
+    getUrl(att.contentRef, att.mimeType)
+      .then((u) => { if (alive) setUrl(u); })
+      .catch(() => { if (alive) setFailed(true); });
+    return () => { alive = false; };
+  }, [att.contentRef, att.mimeType, getUrl]);
+
+  return (
+    <a className="ld-photo" href={url ?? undefined} target="_blank" rel="noreferrer" title={att.filename} onClick={(e) => { if (!url) e.preventDefault(); }}>
+      {url
+        ? <img src={url} alt={att.filename} loading="lazy" />
+        : <span className="ld-photo-ph"><Icon name={failed ? "alert" : "camera"} size={18} /></span>}
+    </a>
+  );
+}
+
 /* ---------------------------------------------------------- */
 /* New Lead — Quick / Full Form intake                         */
 /* ---------------------------------------------------------- */
@@ -321,25 +620,29 @@ const FULL_STEPS = [
   { value: "assignment", label: "Assignment", icon: "team" },
 ];
 
-const LEAD_TYPE_OPTS = ["Residential", "Commercial", "Multi-Family"];
+// Option lists must match the be-crm enums, or crm.lead.create rejects the value (§8.1–8.4).
-const PROPERTY_TYPE_OPTS = ["Residential", "Commercial", "Multi-Family", "Industrial"];
+const LEAD_TYPE_OPTS = LEAD_TYPES;          // Insurance | Retail
+const PROPERTY_TYPE_OPTS = PROPERTY_TYPES;  // Single Family | Multi Family | Commercial
 
 const BLANK = {
   firstName: "", lastName: "",
   phones: [{ number: "", type: "Mobile" }] as PhoneRow[],
   emails: [] as EmailRow[],
   address: "", city: "", state: "TX", zip: "", propertyType: "",
-  photos: [] as string[],
+  photos: [] as UploadedAttachment[],
   source: "", referralNote: "", canvasser: "", leadType: "", workType: "", tradeType: "", urgency: "Standard" as Urgency, notes: "",
   insCompany: "", claimNumber: "", claimStatus: "", adjusterName: "", adjusterPhone: "", policyNumber: "",
   assignRep: "", priority: "Medium" as Priority, followUp: "",
 };
 
-function NewLead({ open, onClose }: { open: boolean; onClose: () => void }) {
+function NewLead({ open, onClose, createLead, reps, uploadPhoto }: { open: boolean; onClose: () => void; createLead: (input: CreateLeadInput) => Promise<void>; reps: Rep[]; uploadPhoto: (file: File) => Promise<UploadedAttachment> }) {
   const toast = useToast();
   const [mode, setMode] = useState<"quick" | "full">("quick");
   const [section, setSection] = useState("contact");
   const [f, setF] = useState({ ...BLANK });
+  const [saving, setSaving] = useState(false);
+  const [uploading, setUploading] = useState(0);
+  const fileRef = useRef<HTMLInputElement>(null);
 
   const set = (k: string) => (e: { target: { value: string } }) =>
     setF((s) => ({ ...s, [k]: e.target.value }) as typeof BLANK);
@@ -351,19 +654,72 @@ function NewLead({ open, onClose }: { open: boolean; onClose: () => void }) {
   const addEmail = () => setF((s) => ({ ...s, emails: [...s.emails, { address: "" }] }));
   const setEmail = (i: number, v: string) => setF((s) => ({ ...s, emails: s.emails.map((e, j) => (j === i ? { address: v } : e)) }));
   const removeEmail = (i: number) => setF((s) => ({ ...s, emails: s.emails.filter((_, j) => j !== i) }));
-  const addPhoto = () => setF((s) => ({ ...s, photos: [...s.photos, `Photo ${s.photos.length + 1}`] }));
+  const removePhoto = (i: number) => setF((s) => ({ ...s, photos: s.photos.filter((_, j) => j !== i) }));
+
+  // Upload each picked file straight to storage (presign → PUT). The returned {contentRef,…}
+  // rides along in crm.lead.create's `photos`, so the photo persists with the lead itself.
+  async function onPickPhotos(e: React.ChangeEvent<HTMLInputElement>) {
+    const files = Array.from(e.target.files ?? []);
+    e.target.value = "";  // let the same file be re-picked after a remove
+    for (const file of files) {
+      if (!isImage(file.type)) { toast.push({ tone: "error", title: "Not an image", desc: `${file.name} isn't an image file.` }); continue; }
+      if (file.size > MAX_ATTACHMENT_BYTES) { toast.push({ tone: "error", title: "Too large", desc: `${file.name} exceeds the 25 MB limit.` }); continue; }
+      setUploading((n) => n + 1);
+      try {
+        const up = await uploadPhoto(file);
+        setF((s) => ({ ...s, photos: [...s.photos, up] }));
+      } catch (err) {
+        toast.push({ tone: "error", title: "Upload failed", desc: err instanceof Error ? err.message : `Couldn't upload ${file.name}.` });
+      } finally {
+        setUploading((n) => n - 1);
+      }
+    }
+  }
 
   function reset() { setF({ ...BLANK, phones: [{ number: "", type: "Mobile" }], emails: [], photos: [] }); setMode("quick"); setSection("contact"); }
   function close() { reset(); onClose(); }
 
-  function submit() {
+  function buildPayload(): CreateLeadInput {
-    const name = `${f.firstName} ${f.lastName}`.trim();
+    return {
-    if (!name) { toast.push({ tone: "error", title: "Name required", desc: "Enter the homeowner's first or last name." }); return; }
+      firstName: f.firstName.trim(),
-    toast.push({ tone: "success", title: "Lead created", desc: `${name} added to the Plano pipeline.` });
+      lastName: f.lastName.trim() || undefined,
-    close();
+      phones: f.phones
+        .filter((p) => p.number.trim())
+        .map((p, i) => ({ number: p.number.trim(), type: (p.type as "Mobile" | "Home" | "Work"), primary: i === 0 })),
+      emails: f.emails.filter((e) => e.address.trim()).map((e, i) => ({ address: e.address.trim(), primary: i === 0 })),
+      property: { address: f.address, city: f.city, state: f.state, zip: f.zip, type: f.propertyType || undefined },
+      photos: f.photos.length ? f.photos : undefined,
+      job: {
+        source: f.source || undefined,
+        referralNote: f.source === "Referral" ? f.referralNote || undefined : undefined,
+        canvasserId: f.source === "Door Knock" ? f.canvasser || undefined : undefined,
+        leadType: f.leadType || undefined, workType: f.workType || undefined, tradeType: f.tradeType || undefined,
+        urgency: f.urgency, notes: f.notes || undefined,
+      },
+      insurance: {
+        company: f.insCompany || undefined, claimNumber: f.claimNumber || undefined, claimStatus: f.claimStatus || undefined,
+        adjusterName: f.adjusterName || undefined, adjusterPhone: f.adjusterPhone || undefined, policyNumber: f.policyNumber || undefined,
+      },
+      assignment: { assigneeId: f.assignRep || null, priority: f.priority, followUp: f.followUp || undefined },
+    };
   }
 
-  const repOptions = [{ id: "", initials: "—", name: "Unassigned" }, ...REPS];
+  async function submit() {
+    const name = `${f.firstName} ${f.lastName}`.trim();
+    if (!name) { toast.push({ tone: "error", title: "Name required", desc: "Enter the homeowner's first or last name." }); return; }
+    setSaving(true);
+    try {
+      await createLead(buildPayload());
+      toast.push({ tone: "success", title: "Lead created", desc: `${name} added to the Plano pipeline.` });
+      close();
+    } catch (e) {
+      toast.push({ tone: "error", title: "Couldn’t create lead", desc: e instanceof Error ? e.message : "Please try again." });
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  const repOptions = [{ id: "", initials: "—", name: "Unassigned", email: "" }, ...reps];
 
   const stepIdx = FULL_STEPS.findIndex((s) => s.value === section);
   const isFirstStep = stepIdx <= 0;
@@ -385,13 +741,13 @@ function NewLead({ open, onClose }: { open: boolean; onClose: () => void }) {
             <Btn variant="ghost" onClick={close}>Cancel</Btn>
             {!isFirstStep && <Btn variant="ghost" onClick={goBack}>Back</Btn>}
             {isLastStep
-              ? <Btn icon="check" onClick={submit}>Create Lead</Btn>
+              ? <Btn icon="check" onClick={submit} disabled={saving}>{saving ? "Creating…" : "Create Lead"}</Btn>
               : <Btn icon="arrow" onClick={goNext}>Next</Btn>}
           </>
         ) : (
           <>
             <Btn variant="ghost" onClick={close}>Cancel</Btn>
-            <Btn icon="check" onClick={submit}>Create Lead</Btn>
+            <Btn icon="check" onClick={submit} disabled={saving}>{saving ? "Creating…" : "Create Lead"}</Btn>
           </>
         )
       }
@@ -417,7 +773,7 @@ function NewLead({ open, onClose }: { open: boolean; onClose: () => void }) {
               <div className="nl-full"><Field label="Referral note"><textarea className="ds-textarea" rows={3} value={f.referralNote} onChange={set("referralNote")} placeholder="Who referred this lead? Any details…" /></Field></div>
             )}
             {f.source === "Door Knock" && (
-              <div className="nl-full"><Field label="Canvasser"><CanvasserSearch value={f.canvasser} onChange={(v) => setF((s) => ({ ...s, canvasser: v }))} options={REPS} /></Field></div>
+              <div className="nl-full"><Field label="Canvasser"><CanvasserSearch value={f.canvasser} onChange={(v) => setF((s) => ({ ...s, canvasser: v }))} options={reps} /></Field></div>
             )}
             <div className="nl-full"><PriorityPicker value={f.priority} onChange={(p) => setF((s) => ({ ...s, priority: p }))} /></div>
             <Field label="Follow-up date"><input className="ds-input" type="date" value={f.followUp} onChange={set("followUp")} /></Field>
@@ -472,14 +828,27 @@ function NewLead({ open, onClose }: { open: boolean; onClose: () => void }) {
                 <Field label="Property Type"><Select value={f.propertyType} onChange={set("propertyType")} options={PROPERTY_TYPE_OPTS} placeholder="Residential, Commercial…" /></Field>
                 <div className="nl-full">
                   <div className="ds-field-lbl">Site Photos</div>
-                  <button type="button" className="nl-photos" onClick={addPhoto}>
+                  <input
+                    ref={fileRef}
+                    type="file"
+                    accept="image/*"
+                    multiple
+                    hidden
+                    onChange={onPickPhotos}
+                  />
+                  <button type="button" className="nl-photos" onClick={() => fileRef.current?.click()}>
                     <Icon name="camera" size={22} />
-                    <span className="nl-photos-t">Tap to add photos</span>
+                    <span className="nl-photos-t">{uploading > 0 ? `Uploading ${uploading}…` : "Tap to add photos"}</span>
-                    <span className="nl-photos-s">Camera · Gallery · Multiple allowed</span>
+                    <span className="nl-photos-s">Camera · Gallery · Multiple allowed · max 25 MB</span>
                   </button>
                   {f.photos.length > 0 && (
                     <div className="nl-photo-chips">
-                      {f.photos.map((p, i) => <span key={i} className="nl-photo-chip"><Icon name="check" size={12} /> {p}</span>)}
+                      {f.photos.map((p, i) => (
+                        <span key={p.contentRef} className="nl-photo-chip">
+                          <Icon name="check" size={12} /> {p.filename}
+                          <button type="button" className="nl-photo-chip-x" aria-label={`Remove ${p.filename}`} onClick={() => removePhoto(i)}><Icon name="x" size={12} /></button>
+                        </span>
+                      ))}
                     </div>
                   )}
                 </div>

src/components/dashboard/verify-data.ts

@@ -10,13 +10,14 @@ export type VStatus = "verified" | "in_progress" | "assigned" | "pending" | "unv
 export type VActivity = { text: string; time: string; who: string };
 
 export type VLead = {
-  id: string;
+  id: string;             // LD-V-001 (display code)
+  refId?: string;         // opaque server id (live mode); commands target this — falls back to `id`
   initials: string;
   name: string;
   address: string;
   phone: string;
   source: string;
-  assignee: { initials: string; name: string } | null;
+  assignee: { id?: string; initials: string; name: string } | null;
   status: VStatus;
   verification: string;   // sub-status text
   created: string;

src/components/dashboard/verify.tsx

@@ -16,7 +16,8 @@
 import { useMemo, useState, useEffect } from "react";
 import { createPortal } from "react-dom";
 import { Avatar, Btn, Icon, Modal, PageHead, Pill, useToast } from "./ui";
-import { V_LEADS, V_STATUS_META, V_SOURCES, V_ASSIGNEES, type VStatus, type VLead, type VActivity } from "./verify-data";
+import { V_STATUS_META, V_SOURCES, type VStatus, type VLead, type VActivity } from "./verify-data";
+import { useVerifyData, type Assignee } from "@/lib/verify-api";
 
 const STAT_ORDER: VStatus[] = ["verified", "in_progress", "assigned", "pending", "unverified"];
 const STAT_ICON: Record<VStatus, string> = {
@@ -42,36 +43,70 @@ function buildActivity(l: VLead): VActivity[] {
 
 type MenuState = { lead: VLead; x: number; y: number } | null;
 
+// Which transitions the backend accepts from a given status. `verified` is re-openable now, so the
+// only guard is "you can't move a record to the status it's already in" — every other transition is
+// allowed and the backend has the final say (a rejected one surfaces a friendly 409 + auto-refresh).
+function allowed(status: VStatus) {
+  return {
+    verify: status !== "verified",
+    unverify: status !== "unverified",
+    moveToPending: status !== "pending",
+  };
+}
+
 export function Verify() {
   const toast = useToast();
+  const data = useVerifyData();
+  const { leads, total, counts, assignees, loading, error } = data;
   const [query, setQuery] = useState("");
   const [status, setStatus] = useState("all");
   const [source, setSource] = useState("all");
   const [assignee, setAssignee] = useState("all");
   const [selected, setSelected] = useState<VLead | null>(null);
   const [menu, setMenu] = useState<MenuState>(null);
-
+  const [assignFor, setAssignFor] = useState<VLead | null>(null);
-  const counts = useMemo(() => {
-    const m: Record<string, number> = {};
-    for (const l of V_LEADS) m[l.status] = (m[l.status] ?? 0) + 1;
-    return m;
-  }, []);
 
   const rows = useMemo(() => {
     const q = query.trim().toLowerCase();
-    return V_LEADS.filter((l) => {
+    return leads.filter((l) => {
       const matchQ = !q || `${l.name} ${l.id} ${l.phone} ${l.source} ${l.address}`.toLowerCase().includes(q);
       const matchStatus = status === "all" || l.status === status;
       const matchSource = source === "all" || l.source === source;
       const matchAssignee = assignee === "all" || l.assignee?.name === assignee;
       return matchQ && matchStatus && matchSource && matchAssignee;
     });
-  }, [query, status, source, assignee]);
+  }, [leads, query, status, source, assignee]);
 
-  function act(l: VLead, title: string, desc: string, tone: "success" | "info" = "info") {
+  // Run a command, surface success/failure as a toast, and close any open menu.
+  async function run(work: Promise<void>, title: string, desc: string) {
     setMenu(null);
-    toast.push({ tone, title, desc });
+    try {
+      await work;
+      toast.push({ tone: "success", title, desc });
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : "";
+      // 409 = the record's current state doesn't allow this transition (e.g. it's already
+      // verified/unverified but the list read was stale). Refetch so the row shows its real status.
+      const conflict = /\b409\b/.test(msg);
+      if (conflict) data.refetch();
+      const friendly = conflict ? "This lead's status already changed — refreshing the queue." : (msg || "Please try again.");
+      toast.push({ tone: "error", title: "Action failed", desc: friendly });
     }
+  }
+
+  const doVerify = (l: VLead) => run(data.verify(l), "Verified", `${l.name} verified and pushed to New Leads.`);
+  // markUnverified (#17) carries a reason — send a default so the command satisfies a required field.
+  const doUnverify = (l: VLead) => run(data.markUnverified(l, "Marked unverified from the verification desk."), "Marked unverified", `${l.name} moved to Unverified.`);
+  const doPending = (l: VLead) => run(data.moveToPending(l), "Moved to pending", `${l.name} is now Pending review.`);
+  // assign (#11) requires an assigneeId — pick one, then run the command.
+  const doAssign = (l: VLead, a: Assignee) => run(data.assign(l, a.id), "Assignee changed", `${l.name} assigned to ${a.name}.`);
+
+  // Open a row with its list data, then hydrate detail (notes/activity) — ignore hydration errors.
+  const openDetail = (l: VLead) => {
+    setSelected(l);
+    setMenu(null);
+    data.getVerification(l).then((full) => setSelected((cur) => (cur && cur.id === l.id ? full : cur))).catch(() => {});
+  };
 
   return (
     <div className="view lv">
@@ -80,7 +115,7 @@ export function Verify() {
         title="Lead Verification"
         subtitle="Identity & insurance checks before a lead becomes a working deal."
         icon="verify"
-        actions={<Btn variant="outline" icon="refresh" onClick={() => toast.push({ tone: "info", title: "Queue refreshed", desc: "Verification queue is up to date." })}>Refresh</Btn>}
+        actions={<Btn variant="outline" icon="refresh" onClick={() => { data.refetch(); toast.push({ tone: "info", title: "Queue refreshed", desc: "Verification queue is up to date." }); }}>Refresh</Btn>}
       />
 
       {/* ---- stat tiles ---- */}
@@ -114,7 +149,7 @@ export function Verify() {
         </select>
         <select className="ds-select lv-filter" value={assignee} onChange={(e) => setAssignee(e.target.value)} aria-label="Filter by assignee">
           <option value="all">All assignees</option>
-          {V_ASSIGNEES.map((a) => <option key={a} value={a}>{a}</option>)}
+          {assignees.map((a) => <option key={a.id} value={a.name}>{a.name}</option>)}
         </select>
       </div>
 
@@ -129,7 +164,11 @@ export function Verify() {
             </tr>
           </thead>
           <tbody>
-            {rows.length === 0 ? (
+            {error ? (
+              <tr><td colSpan={9} className="lv-empty">Couldn’t load the queue: {error}</td></tr>
+            ) : loading && rows.length === 0 ? (
+              <tr><td colSpan={9} className="lv-empty">Loading verification queue…</td></tr>
+            ) : rows.length === 0 ? (
               <tr><td colSpan={9} className="lv-empty">No leads match your filters.</td></tr>
             ) : rows.map((l) => {
               const meta = V_STATUS_META[l.status];
@@ -160,8 +199,8 @@ export function Verify() {
                   <td className="lv-created">{l.created}</td>
                   <td>
                     <div className="lv-rowacts">
-                      <button className="lv-act" aria-label="View details" title="View details" onClick={() => setSelected(l)}><Icon name="eye" size={15} /></button>
+                      <button className="lv-act" aria-label="View details" title="View details" onClick={() => openDetail(l)}><Icon name="eye" size={15} /></button>
-                      <button className="lv-act primary" aria-label="Verify" title="Verify lead" onClick={() => act(l, "Marked verified", `${l.name} moved to Verified.`, "success")}><Icon name="check-circle" size={15} /></button>
+                      <button className="lv-act primary" aria-label="Verify" title={allowed(l.status).verify ? "Verify lead" : "Already resolved"} onClick={() => doVerify(l)} disabled={!allowed(l.status).verify}><Icon name="check-circle" size={15} /></button>
                       <button className="lv-act" aria-label="More actions" title="More actions" onClick={(e) => setMenu(menu?.lead.id === l.id ? null : { lead: l, x: e.clientX, y: e.clientY })}><Icon name="dots" size={15} /></button>
                     </div>
                   </td>
@@ -171,10 +210,24 @@ export function Verify() {
           </tbody>
         </table>
       </div>
-      <div className="lv-count">{rows.length} of {V_LEADS.length} leads</div>
+      <div className="lv-count">{rows.length} of {total} leads</div>
 
-      <ActionsMenu menu={menu} onClose={() => setMenu(null)} onAct={act} onView={(l) => { setSelected(l); setMenu(null); }} />
+      <ActionsMenu
-      <VerifyDetail lead={selected} onClose={() => setSelected(null)} />
+        menu={menu}
+        onClose={() => setMenu(null)}
+        onView={openDetail}
+        onVerify={doVerify}
+        onUnverify={doUnverify}
+        onPending={doPending}
+        onOpenAssign={(l) => { setMenu(null); setAssignFor(l); }}
+      />
+      <AssignModal
+        lead={assignFor}
+        assignees={assignees}
+        onClose={() => setAssignFor(null)}
+        onPick={(l, a) => { setAssignFor(null); doAssign(l, a); }}
+      />
+      <VerifyDetail lead={selected} onClose={() => setSelected(null)} onVerify={doVerify} />
     </div>
   );
 }
@@ -183,10 +236,13 @@ export function Verify() {
 /* Row actions dropdown (portalled, fixed-positioned)          */
 /* ---------------------------------------------------------- */
 
-function ActionsMenu({ menu, onClose, onAct, onView }: {
+function ActionsMenu({ menu, onClose, onView, onVerify, onUnverify, onPending, onOpenAssign }: {
   menu: MenuState; onClose: () => void;
-  onAct: (l: VLead, title: string, desc: string, tone?: "success" | "info") => void;
   onView: (l: VLead) => void;
+  onVerify: (l: VLead) => void;
+  onUnverify: (l: VLead) => void;
+  onPending: (l: VLead) => void;
+  onOpenAssign: (l: VLead) => void;
 }) {
   const [mounted, setMounted] = useState(false);
   useEffect(() => { setMounted(true); }, []);
@@ -202,27 +258,85 @@ function ActionsMenu({ menu, onClose, onAct, onView }: {
   const left = Math.max(8, menu.x - 196);
   const top = Math.min(menu.y + 8, window.innerHeight - 260);
 
-  const items = [
-    { icon: "eye", label: "View Details", run: () => onView(l) },
-    { icon: "check-circle", label: "Verify Lead", run: () => onAct(l, "Verified", `${l.name} marked as verified.`, "success") },
-    { icon: "alert", label: "Mark Unverified", run: () => onAct(l, "Marked unverified", `${l.name} moved to Unverified.`) },
-    { icon: "user", label: "Change Assignee", run: () => onAct(l, "Change assignee", `Pick a new rep for ${l.name}.`) },
-    { icon: "refresh", label: "Reassign (In Progress)", run: () => onAct(l, "Reassigned", `${l.name} set to In Progress.`) },
-    { icon: "clock", label: "Move to Pending", run: () => onAct(l, "Moved to pending", `${l.name} is now Pending review.`) },
-  ];
-
   return createPortal(
     <>
       <div className="lv-menu-scrim" onClick={onClose} />
+      <MenuBody
+        key={l.id} lead={l} left={left} top={top}
+        onView={onView} onVerify={onVerify} onUnverify={onUnverify}
+        onPending={onPending} onOpenAssign={onOpenAssign}
+      />
+    </>,
+    document.body,
+  );
+}
+
+function MenuBody({ lead: l, left, top, onView, onVerify, onUnverify, onPending, onOpenAssign }: {
+  lead: VLead; left: number; top: number;
+  onView: (l: VLead) => void; onVerify: (l: VLead) => void; onUnverify: (l: VLead) => void;
+  onPending: (l: VLead) => void; onOpenAssign: (l: VLead) => void;
+}) {
+  const can = allowed(l.status);
+
+  // Immediate-fire actions are gated by status (prevents a pointless 409). "Change Assignee" opens
+  // the assign popup (the command fires after you pick), so it always opens.
+  const items = [
+    { icon: "eye", label: "View Details", enabled: true, run: () => onView(l) },
+    { icon: "check-circle", label: "Verify Lead", enabled: can.verify, run: () => onVerify(l) },
+    { icon: "alert", label: "Mark Unverified", enabled: can.unverify, run: () => onUnverify(l) },
+    { icon: "user", label: "Change Assignee", enabled: true, run: () => onOpenAssign(l) },
+    { icon: "clock", label: "Move to Pending", enabled: can.moveToPending, run: () => onPending(l) },
+  ];
+
+  return (
     <div className="lv-menu" style={{ left, top }} role="menu">
       {items.map((it) => (
-          <button key={it.label} className="lv-menu-item" role="menuitem" onClick={it.run}>
+        <button key={it.label} className="lv-menu-item" role="menuitem" onClick={it.run} disabled={!it.enabled}>
           <Icon name={it.icon} size={14} /> {it.label}
         </button>
       ))}
     </div>
-    </>,
+  );
-    document.body,
+}
+
+/* ---------------------------------------------------------- */
+/* Change-assignee popup (searchable, scrollable)             */
+/* ---------------------------------------------------------- */
+
+function AssignModal({ lead, assignees, onClose, onPick }: {
+  lead: VLead | null; assignees: Assignee[]; onClose: () => void; onPick: (l: VLead, a: Assignee) => void;
+}) {
+  const [q, setQ] = useState("");
+  if (!lead) return null;
+  const query = q.trim().toLowerCase();
+  const matches = query ? assignees.filter((a) => a.name.toLowerCase().includes(query)) : assignees;
+
+  return (
+    <Modal open={!!lead} onClose={onClose} size="sm" title="Change Assignee" subtitle={lead.name} icon="user">
+      <div className="lv-assign">
+        <div className="lv-assign-search">
+          <Icon name="search" size={15} />
+          <input autoFocus value={q} onChange={(e) => setQ(e.target.value)} placeholder="Search team members…" aria-label="Search team members" />
+          {q && <button className="lv-assign-x" aria-label="Clear" onClick={() => setQ("")}><Icon name="x" size={14} /></button>}
+        </div>
+        <div className="lv-assign-list">
+          {assignees.length === 0 ? (
+            <div className="lv-assign-empty">No team members available.</div>
+          ) : matches.length === 0 ? (
+            <div className="lv-assign-empty">No members match “{q}”.</div>
+          ) : matches.map((a) => {
+            const current = lead.assignee?.id === a.id || lead.assignee?.name === a.name;
+            return (
+              <button key={a.id} className={`lv-assign-opt ${current ? "current" : ""}`} onClick={() => onPick(lead, a)}>
+                <Avatar initials={a.initials} size={30} gradient="linear-gradient(135deg,#4f8cff,#2c5cff)" />
+                <span className="lv-assign-name">{a.name}</span>
+                {current && <Icon name="check" size={16} />}
+              </button>
+            );
+          })}
+        </div>
+      </div>
+    </Modal>
   );
 }
 
@@ -230,16 +344,23 @@ function ActionsMenu({ menu, onClose, onAct, onView }: {
 /* Verification detail popup                                   */
 /* ---------------------------------------------------------- */
 
-function VerifyDetail({ lead, onClose }: { lead: VLead | null; onClose: () => void }) {
+function VerifyDetail({ lead, onClose, onVerify }: { lead: VLead | null; onClose: () => void; onVerify: (l: VLead) => void }) {
+  const toast = useToast();
   if (!lead) return null;
   const meta = V_STATUS_META[lead.status];
   const activity = buildActivity(lead);
 
+  const call = () => {
+    if (!lead.phone) { toast.push({ tone: "error", title: "No phone", desc: "This lead has no phone number." }); return; }
+    window.location.href = `tel:${lead.phone.replace(/[^\d+]/g, "")}`;
+  };
+  const verify = () => { onVerify(lead); onClose(); };
+
   return (
     <Modal open={!!lead} onClose={onClose} size="lg" title={lead.name} subtitle={`${lead.id} · ${lead.verification}`} icon="verify"
       footer={<>
-        <Btn variant="ghost" icon="phone">Call</Btn>
+        <Btn variant="ghost" icon="phone" onClick={call}>Call</Btn>
-        <Btn icon="check-circle">Verify Lead</Btn>
+        <Btn icon="check-circle" onClick={verify} disabled={!allowed(lead.status).verify}>Verify Lead</Btn>
       </>}
     >
       <div className="lv-detail">

src/lib/leads-api.ts

@@ -0,0 +1,568 @@
+"use client";
+
+// Leads data layer. Serves EITHER the local mock (when the Shell isn't configured — the
+// polished demo keeps working) OR the live be-crm data door (crm.lead.*), behind one
+// interface so the Leads board is mode-agnostic. Mirrors team-api.ts exactly.
+//
+// Live contract (be-crm):
+//   query crm.lead.search { query?, status?, priority?, source?, assigneeId?, page?, perPage? }
+//                                                    -> { items: LeadCardDTO[], meta }
+//   query crm.lead.get    { id }                     -> LeadDTO (full detail)
+//   query crm.lead.stats  {}                         -> { total, byStatus }
+//   cmd   crm.lead.create <payload>                  -> LeadDTO
+//   cmd   crm.lead.updateStatus { id, status, note? } -> LeadDTO
+//   cmd   crm.lead.assign { id, assigneeId | null }  -> LeadDTO
+
+import { useCallback, useMemo, useState } from "react";
+import { useAppShell, useQuery } from "@abe-kap/appshell-sdk/react";
+import { isShellConfigured } from "./appshell";
+import { useUploadAttachment, useDownloadUrl, type UploadedAttachment } from "./media-api";
+import {
+  LEADS as seedLeads, TOTAL_LEADS, REPS as seedReps,
+  type Lead, type LeadStatus, type LeadPriority, type Phone, type Email, type Rep, type Attachment,
+} from "@/components/dashboard/leads-data";
+
+/* ---- create payload (union of Quick + Full form; §6.3) ------------------ */
+
+export interface CreateLeadInput {
+  firstName: string;
+  lastName?: string;
+  phones: { number: string; type: "Mobile" | "Home" | "Work"; primary?: boolean }[];
+  emails?: { address: string; primary?: boolean }[];
+  property?: { address?: string; city?: string; state?: string; zip?: string; type?: string };
+  photos?: { contentRef: string; mimeType: string; sizeBytes: number; filename: string }[];
+  job?: {
+    source?: string; referralNote?: string; canvasserId?: string;
+    leadType?: string; workType?: string; tradeType?: string;
+    urgency?: "Standard" | "High" | "Emergency"; notes?: string;
+  };
+  insurance?: {
+    company?: string; claimNumber?: string; claimStatus?: string;
+    adjusterName?: string; adjusterPhone?: string; policyNumber?: string;
+  };
+  assignment?: { assigneeId?: string | null; priority?: "Low" | "Medium" | "High"; followUp?: string };
+}
+
+/** Partial update patch — flat camelCase fields (matches the tested `crm.lead.update` #21). */
+export interface LeadPatch {
+  firstName?: string; lastName?: string;
+  priority?: string;
+  propertyAddress?: string; propertyCity?: string; propertyState?: string; propertyZip?: string; propertyType?: string;
+  source?: string; leadType?: string; workType?: string; tradeType?: string; urgency?: string; jobNotes?: string;
+  insuranceCompany?: string; insuranceClaimStatus?: string; insuranceClaimNumber?: string;
+  insurancePolicyNumber?: string; insuranceAdjusterName?: string; insuranceAdjusterPhone?: string;
+  assignedToId?: string | null; followUpDate?: string;
+  phones?: { number: string; type: string; primary?: boolean }[];
+  emails?: { address: string; primary?: boolean }[];
+}
+
+export interface LeadsData {
+  live: boolean; loading: boolean; error: string | null;
+  leads: Lead[];
+  total: number;
+  byStatus: Record<LeadStatus, number>;
+  /** Rep / canvasser / assignee picker options. In live mode `id` is the member's principalId
+   *  (the value be-crm resolves assignee/canvasser references against), not the mock REP code. */
+  reps: Rep[];
+  /** Hydrate a single lead's full detail (list rows carry card-level fields only in live mode). */
+  getLead: (lead: Lead) => Promise<Lead>;
+  createLead: (input: CreateLeadInput) => Promise<void>;
+  /** Upload a site photo → {contentRef,…}. Feed the results into `createLead`'s `photos`. */
+  uploadPhoto: (file: File) => Promise<UploadedAttachment>;
+  /** Mint a short-lived signed URL to render a stored photo by its contentRef. */
+  getPhotoUrl: (contentRef: string, mime?: string) => Promise<string>;
+  /** Attach an already-uploaded photo to an existing lead (Edit mode) — crm.lead.attachment.add. */
+  addPhoto: (lead: Lead, attachment: UploadedAttachment) => Promise<void>;
+  /** Detach a stored photo from a lead (Edit mode) — crm.lead.attachment.remove. */
+  removePhoto: (lead: Lead, attachment: Attachment) => Promise<void>;
+  /** Edit an existing lead (Edit button on the detail popup). */
+  updateLead: (lead: Lead, patch: LeadPatch) => Promise<void>;
+  updateStatus: (lead: Lead, status: LeadStatus, note?: string) => Promise<void>;
+  assign: (lead: Lead, assigneeId: string | null) => Promise<void>;
+  /** Push the lead into the Lead Verification queue (crm.lead.sendForVerification). Idempotent server-side. */
+  sendForVerification: (lead: Lead) => Promise<void>;
+  refetch: () => void;
+}
+
+/* ---- helpers ------------------------------------------------------------ */
+
+const GRADIENTS = [
+  "linear-gradient(135deg,#fda913,#fd6d13)", "linear-gradient(135deg,#4f8cff,#2c5cff)",
+  "linear-gradient(135deg,#b07bf2,#7b53e0)", "linear-gradient(135deg,#33c98a,#1fa46c)",
+  "linear-gradient(135deg,#34c9d6,#1f9aa4)",
+];
+const gradientFor = (id: string) => GRADIENTS[[...id].reduce((a, c) => a + c.charCodeAt(0), 0) % GRADIENTS.length];
+const initialsOf = (name: string) =>
+  name.split(/\s+/).filter(Boolean).slice(0, 2).map((p) => p[0]).join("").toUpperCase() || "?";
+const firstNameOf = (name: string) => name.split(/\s+/)[0] ?? "";
+
+const relTime = (iso?: string | null): string => {
+  if (!iso) return "—";
+  const then = Date.parse(iso);
+  if (Number.isNaN(then)) return iso;
+  const diff = Date.now() - then;
+  const day = 86_400_000;
+  if (diff >= 0 && diff < 7 * day) {
+    const d = Math.floor(diff / day);
+    if (d <= 0) return "today";
+    return `${d}d ago`;
+  }
+  return new Date(then).toLocaleDateString(undefined, { day: "numeric", month: "short", year: "numeric" });
+};
+const prettyDate = (iso?: string | null): string => {
+  if (!iso) return "—";
+  const then = Date.parse(iso);
+  if (Number.isNaN(then)) return iso;
+  return new Date(then).toLocaleDateString(undefined, { day: "numeric", month: "short", year: "numeric" });
+};
+const lc = (p?: string | null): LeadPriority =>
+  (String(p ?? "medium").toLowerCase() as LeadPriority);
+
+const EMPTY_BY_STATUS: Record<LeadStatus, number> = { new: 0, contacted: 0, appointed: 0, closed: 0 };
+
+/* ---- be-crm DTO types (defensive: backend is greenfield) ---------------- */
+
+interface LeadCardDTO {
+  id: string; code: string; name: string; initials?: string; gradient?: string;
+  priority?: string; status?: LeadStatus; tag?: string;
+  primaryPhone?: string; propertyAddress?: string; propertyCity?: string; propertyState?: string;
+  source?: string; canvasserName?: string; updatedAt?: string;
+  // Set once the lead has an associated verification record (blocks a duplicate send).
+  verificationId?: string | null; verificationStatus?: string | null;
+}
+interface LeadDTO extends LeadCardDTO {
+  phones?: Phone[]; emails?: Email[];
+  propertyZip?: string; propertyType?: string;
+  leadType?: string; workType?: string; tradeType?: string; urgency?: string; jobNotes?: string;
+  referralNote?: string; canvasserId?: string;
+  insuranceCompany?: string; insuranceClaimStatus?: string; insuranceClaimNumber?: string;
+  insurancePolicyNumber?: string; insuranceAdjusterName?: string; insuranceAdjusterPhone?: string;
+  assignedToName?: string; createdByName?: string; followUpDate?: string; createdAt?: string;
+  assignedToId?: string | null; createdById?: string | null;
+  stormZone?: string; stormDate?: string; stormDetail?: string;
+  // assignee / creator can come back under several field names depending on the DTO projection.
+  // The object form carries an `id` (be-crm currently echoes the principalId as `name`, unresolved).
+  assignedTo?: string | { id?: string; name?: string; displayName?: string } | null;
+  assignee?: string | { id?: string; name?: string; displayName?: string } | null;
+  createdBy?: string | { id?: string; name?: string; displayName?: string } | null;
+  creatorName?: string;
+  // site photos — LeadDTO detail projection carries attachments[] (§6.2)
+  attachments?: Attachment[];
+  // tolerate an already-grouped detail shape too
+  property?: Lead["property"]; job?: Partial<Lead["job"]>;
+  insurance?: Partial<Lead["insurance"]>; assignment?: Partial<Lead["assignment"]>;
+  storm?: Partial<Lead["storm"]>;
+}
+
+/** Pull a display name out of whatever shape the backend returns the assignee in. */
+function nameOf(v: string | { name?: string; displayName?: string } | null | undefined): string {
+  if (!v) return "";
+  if (typeof v === "string") return v;
+  return v.displayName?.trim() || v.name?.trim() || "";
+}
+
+/** Pull the member id out of an object-shaped member reference (string refs carry no id). */
+function idOf(v: string | { id?: string } | null | undefined): string {
+  if (!v || typeof v === "string") return "";
+  return v.id?.trim() ?? "";
+}
+
+/** Resolve a member reference to a display name. be-crm currently echoes the raw principalId
+ *  as the `name`, so prefer the local reps list (principalId → real name); fall back to a
+ *  backend name only when it isn't just the id, then to the id itself. */
+function resolveMemberName(id: string, backendName: string, reps: Rep[]): string {
+  const rep = id ? reps.find((r) => r.id === id) : undefined;
+  if (rep) return rep.name;
+  if (backendName && backendName !== id) return backendName;
+  return backendName || id;
+}
+
+/* ---- DTO → UI Lead ------------------------------------------------------ */
+
+function cardToLead(d: LeadCardDTO): Lead {
+  const name = d.name ?? "";
+  return {
+    id: d.code || d.id,
+    refId: d.id,
+    verificationId: d.verificationId ?? (d.verificationStatus ? String(d.verificationStatus) : undefined) ?? undefined,
+    initials: d.initials || initialsOf(name),
+    name,
+    gradient: d.gradient || gradientFor(d.id),
+    priority: lc(d.priority),
+    status: (d.status ?? "new") as LeadStatus,
+    tag: d.tag ?? "Storm Zone",
+    updated: relTime(d.updatedAt),
+    setter: firstNameOf(d.canvasserName ?? ""),
+    storm: { zone: "", date: "", detail: "" },
+    phones: d.primaryPhone ? [{ number: d.primaryPhone, type: "Mobile", primary: true }] : [],
+    emails: [],
+    property: {
+      address: d.propertyAddress ?? "", city: d.propertyCity ?? "",
+      state: d.propertyState ?? "", zip: "", type: "",
+    },
+    job: {
+      source: d.source ?? "", leadType: "", workType: "", tradeType: "",
+      urgency: "", canvasser: d.canvasserName ?? "", notes: "",
+    },
+    insurance: { company: "", claimStatus: "", claimNumber: "", policyNumber: "", adjusterName: "", adjusterPhone: "" },
+    assignment: { assignedTo: "", priority: "", followUp: "", createdBy: "", createdAt: "" },
+  };
+}
+
+function detailToLead(d: LeadDTO, fallback: Lead, reps: Rep[]): Lead {
+  const base = cardToLead(d);
+  const assigneeId = d.assignedToId || idOf(d.assignedTo) || idOf(d.assignee) || "";
+  const assigneeName = d.assignedToName || nameOf(d.assignedTo) || nameOf(d.assignee) || "";
+  const creatorId = d.createdById || idOf(d.createdBy) || "";
+  const creatorName = d.createdByName || d.creatorName || nameOf(d.createdBy) || "";
+  return {
+    ...base,
+    storm: d.storm
+      ? { zone: d.storm.zone ?? "", date: d.storm.date ?? "", detail: d.storm.detail ?? "" }
+      : { zone: d.stormZone ?? fallback.storm.zone, date: d.stormDate ?? fallback.storm.date, detail: d.stormDetail ?? fallback.storm.detail },
+    phones: d.phones?.length ? d.phones : base.phones.length ? base.phones : fallback.phones,
+    emails: d.emails ?? [],
+    attachments: d.attachments ?? fallback.attachments ?? [],
+    property: d.property ?? {
+      address: d.propertyAddress ?? "", city: d.propertyCity ?? "", state: d.propertyState ?? "",
+      zip: d.propertyZip ?? "", type: d.propertyType ?? "",
+    },
+    job: {
+      source: d.job?.source ?? d.source ?? "",
+      leadType: d.job?.leadType ?? d.leadType ?? "",
+      workType: d.job?.workType ?? d.workType ?? "",
+      tradeType: d.job?.tradeType ?? d.tradeType ?? "",
+      urgency: d.job?.urgency ?? d.urgency ?? "",
+      canvasser: d.job?.canvasser ?? d.canvasserName ?? "",
+      notes: d.job?.notes ?? d.jobNotes ?? "",
+    },
+    insurance: {
+      company: d.insurance?.company ?? d.insuranceCompany ?? "",
+      claimStatus: d.insurance?.claimStatus ?? d.insuranceClaimStatus ?? "",
+      claimNumber: d.insurance?.claimNumber ?? d.insuranceClaimNumber ?? "",
+      policyNumber: d.insurance?.policyNumber ?? d.insurancePolicyNumber ?? "",
+      adjusterName: d.insurance?.adjusterName ?? d.insuranceAdjusterName ?? "",
+      adjusterPhone: d.insurance?.adjusterPhone ?? d.insuranceAdjusterPhone ?? "",
+    },
+    assignment: {
+      assignedTo: d.assignment?.assignedTo
+        || resolveMemberName(assigneeId, assigneeName, reps)
+        || "Unassigned",
+      priority: d.assignment?.priority ?? (d.priority ?? ""),
+      followUp: d.assignment?.followUp ?? prettyDate(d.followUpDate),
+      createdBy: d.assignment?.createdBy
+        || resolveMemberName(creatorId, creatorName, reps),
+      createdAt: d.assignment?.createdAt ?? prettyDate(d.createdAt),
+    },
+  };
+}
+
+/* ======================================================================== */
+/* Mock implementation (no Shell configured)                                */
+/* ======================================================================== */
+
+function useMockLeads(): LeadsData {
+  const [leads, setLeads] = useState<Lead[]>(() => seedLeads);
+
+  const byStatus = useMemo(() => {
+    const m = { ...EMPTY_BY_STATUS };
+    for (const l of leads) m[l.status] += 1;
+    return m;
+  }, [leads]);
+
+  const getLead = useCallback(async (lead: Lead) => lead, []);
+
+  const createLead = useCallback(async (input: CreateLeadInput) => {
+    const name = `${input.firstName} ${input.lastName ?? ""}`.trim();
+    const phones: Phone[] = input.phones
+      .filter((p) => p.number.trim())
+      .map((p, i) => ({ number: p.number, type: p.type, primary: p.primary ?? i === 0 }));
+    const seq = seedLeads.length + leads.length + 1;
+    const lead: Lead = {
+      id: `SAL-${String(seq).padStart(3, "0")}`,
+      initials: initialsOf(name),
+      name,
+      gradient: gradientFor(name),
+      priority: lc(input.assignment?.priority),
+      status: "new",
+      tag: "Storm Zone",
+      updated: "today",
+      setter: firstNameOf(input.job?.canvasserId ?? ""),
+      storm: { zone: "", date: "", detail: "" },
+      phones,
+      emails: (input.emails ?? []).filter((e) => e.address.trim()).map((e, i) => ({ address: e.address, primary: e.primary ?? i === 0 })),
+      attachments: input.photos ?? [],
+      property: {
+        address: input.property?.address ?? "", city: input.property?.city ?? "",
+        state: input.property?.state ?? "TX", zip: input.property?.zip ?? "", type: input.property?.type ?? "",
+      },
+      job: {
+        source: input.job?.source ?? "", leadType: input.job?.leadType ?? "",
+        workType: input.job?.workType ?? "", tradeType: input.job?.tradeType ?? "",
+        urgency: input.job?.urgency ?? "Standard", canvasser: input.job?.canvasserId ?? "", notes: input.job?.notes ?? "",
+      },
+      insurance: {
+        company: input.insurance?.company ?? "", claimStatus: input.insurance?.claimStatus ?? "",
+        claimNumber: input.insurance?.claimNumber ?? "", policyNumber: input.insurance?.policyNumber ?? "",
+        adjusterName: input.insurance?.adjusterName ?? "", adjusterPhone: input.insurance?.adjusterPhone ?? "",
+      },
+      assignment: {
+        assignedTo: input.assignment?.assigneeId ?? "Unassigned",
+        priority: input.assignment?.priority ?? "Medium",
+        followUp: input.assignment?.followUp || "—",
+        createdBy: "You", createdAt: "today",
+      },
+    };
+    setLeads((l) => [lead, ...l]);
+  }, [leads.length]);
+
+  const updateLead = useCallback(async (lead: Lead, patch: LeadPatch) => {
+    setLeads((l) => l.map((x) => (x.id === lead.id ? applyPatch(x, patch) : x)));
+  }, []);
+  const updateStatus = useCallback(async (lead: Lead, status: LeadStatus) => {
+    setLeads((l) => l.map((x) => (x.id === lead.id ? { ...x, status } : x)));
+  }, []);
+  const assign = useCallback(async (lead: Lead, assigneeId: string | null) => {
+    setLeads((l) => l.map((x) => (x.id === lead.id ? { ...x, assignment: { ...x.assignment, assignedTo: assigneeId ?? "Unassigned" } } : x)));
+  }, []);
+  // No shared store between the mock leads/verify hooks, so this is a no-op in demo mode
+  // (the component still toasts success). Live mode does the real intake.
+  const sendForVerification = useCallback(async (_lead: Lead) => {}, []);
+
+  // Demo mode has no storage door — keep the bytes in-browser via an object URL so the
+  // uploaded photo still renders in the detail popup. `getPhotoUrl` passes it straight through.
+  const uploadPhoto = useCallback(async (file: File): Promise<UploadedAttachment> => ({
+    contentRef: URL.createObjectURL(file), mimeType: file.type || "image/jpeg", sizeBytes: file.size, filename: file.name,
+  }), []);
+  const getPhotoUrl = useCallback(async (contentRef: string) => contentRef, []);
+  const addPhoto = useCallback(async (lead: Lead, attachment: UploadedAttachment) => {
+    setLeads((l) => l.map((x) => (x.id === lead.id ? { ...x, attachments: [...(x.attachments ?? []), attachment] } : x)));
+  }, []);
+  const removePhoto = useCallback(async (lead: Lead, attachment: Attachment) => {
+    setLeads((l) => l.map((x) => (x.id === lead.id ? { ...x, attachments: (x.attachments ?? []).filter((a) => a.contentRef !== attachment.contentRef) } : x)));
+  }, []);
+
+  return {
+    live: false, loading: false, error: null,
+    leads, total: TOTAL_LEADS, byStatus, reps: seedReps,
+    getLead, createLead, updateLead, updateStatus, assign, sendForVerification,
+    uploadPhoto, getPhotoUrl, addPhoto, removePhoto, refetch: () => {},
+  };
+}
+
+/** Apply a flat LeadPatch onto the nested UI Lead (mock mode only). */
+function applyPatch(lead: Lead, p: LeadPatch): Lead {
+  const name = p.firstName !== undefined || p.lastName !== undefined
+    ? `${p.firstName ?? lead.name.split(" ")[0] ?? ""} ${p.lastName ?? lead.name.split(" ").slice(1).join(" ")}`.trim()
+    : lead.name;
+  return {
+    ...lead,
+    name,
+    initials: name ? initialsOf(name) : lead.initials,
+    priority: p.priority ? lc(p.priority) : lead.priority,
+    phones: p.phones?.length ? p.phones.map((x, i) => ({ number: x.number, type: x.type as Phone["type"], primary: x.primary ?? i === 0 })) : lead.phones,
+    emails: p.emails ? p.emails.map((x, i) => ({ address: x.address, primary: x.primary ?? i === 0 })) : lead.emails,
+    property: {
+      address: p.propertyAddress ?? lead.property.address,
+      city: p.propertyCity ?? lead.property.city,
+      state: p.propertyState ?? lead.property.state,
+      zip: p.propertyZip ?? lead.property.zip,
+      type: p.propertyType ?? lead.property.type,
+    },
+    job: {
+      ...lead.job,
+      source: p.source ?? lead.job.source,
+      leadType: p.leadType ?? lead.job.leadType,
+      workType: p.workType ?? lead.job.workType,
+      tradeType: p.tradeType ?? lead.job.tradeType,
+      urgency: p.urgency ?? lead.job.urgency,
+      notes: p.jobNotes ?? lead.job.notes,
+    },
+    insurance: {
+      company: p.insuranceCompany ?? lead.insurance.company,
+      claimStatus: p.insuranceClaimStatus ?? lead.insurance.claimStatus,
+      claimNumber: p.insuranceClaimNumber ?? lead.insurance.claimNumber,
+      policyNumber: p.insurancePolicyNumber ?? lead.insurance.policyNumber,
+      adjusterName: p.insuranceAdjusterName ?? lead.insurance.adjusterName,
+      adjusterPhone: p.insuranceAdjusterPhone ?? lead.insurance.adjusterPhone,
+    },
+    assignment: {
+      ...lead.assignment,
+      assignedTo: p.assignedToId !== undefined ? (p.assignedToId ?? "Unassigned") : lead.assignment.assignedTo,
+      priority: p.priority ?? lead.assignment.priority,
+      followUp: p.followUpDate ?? lead.assignment.followUp,
+    },
+  };
+}
+
+/* ======================================================================== */
+/* Live implementation (be-crm data door)                                   */
+/* ======================================================================== */
+
+interface Page<T> { items: T[]; meta?: { total?: number } }
+interface MemberDTO { id: string; principalId?: string; displayName?: string | null; firstName?: string | null; lastName?: string | null; jobTitle?: string | null; email?: string | null }
+
+/* ---- error surfacing ---------------------------------------------------- */
+// appshell's DataClient throws an opaque "data command failed: <status>" and DROPS the response
+// body, so the backend's real error (e.g. the duplicate_lead guard) never reaches the UI. For
+// writes where the exact server message matters, `bffCommand` uses the same BFF transport but
+// parses the error body and throws the backend's own message.
+
+const BFF_BASE = (process.env.NEXT_PUBLIC_BFF_BASE_URL ?? "/shell").replace(/\/$/, "");
+
+// Observed be-crm error body (Fastify style):
+//   { statusCode, error: "Conflict", message: "duplicate_lead",
+//     detail: "A lead with the same primary phone and address already exists (SAL-010).",
+//     duplicateOf: [{ id, code, name }] }
+// i.e. `message` is a CODE slug, `detail` is the human sentence, `duplicateOf` is an array.
+// Also tolerate a nested `{ error: { code, message } }` shape from other services.
+type DupRef = { id?: string; code?: string; name?: string };
+interface BackendError {
+  statusCode?: number; code?: string; error?: string | BackendError;
+  message?: string; detail?: string;
+  duplicateOf?: DupRef[] | DupRef | null;
+  details?: { duplicateOf?: DupRef[] | DupRef | null };
+}
+
+function firstDup(body: BackendError): DupRef | null {
+  const d = body.duplicateOf ?? body.details?.duplicateOf ?? null;
+  if (!d) return null;
+  return Array.isArray(d) ? (d[0] ?? null) : d;
+}
+
+/** Show the backend's own human sentence verbatim; map a bare code slug otherwise. */
+function leadErrorText(code: string, human: string, body: BackendError, status: number): string {
+  if (human) return human;                           // e.g. `detail` — exactly what the server said
+  switch (code) {                                    // slug with no human sentence
+    case "duplicate_lead": {
+      const who = firstDup(body)?.name || firstDup(body)?.code;
+      return who
+        ? `A lead with the same primary phone and address already exists (${who}).`
+        : "A lead with the same primary phone and address already exists.";
+    }
+    case "name_required": return "Enter the homeowner's first or last name.";
+    case "invalid_assignee": return "The selected rep isn't a valid team member.";
+    case "file_too_large": return "That photo is too large (max 25 MB).";
+    default: return `Couldn’t complete the request (${status}).`;
+  }
+}
+
+async function bffCommand<T>(action: string, variables: Record<string, unknown>): Promise<T> {
+  const res = await fetch(`${BFF_BASE}/data/command`, {
+    method: "POST",
+    credentials: "include",
+    headers: {
+      "Content-Type": "application/json",
+      "X-Idempotency-Key": globalThis.crypto?.randomUUID?.() ?? Math.random().toString(36).slice(2),
+    },
+    body: JSON.stringify({ action, variables }),
+  });
+  if (res.status === 401) throw new Error("SESSION_EXPIRED");
+  if (res.ok) return (await res.json()) as T;
+  let body: BackendError = {};
+  try { body = (await res.json()) as BackendError; } catch { /* non-JSON error body */ }
+  const inner = (body.error && typeof body.error === "object" ? body.error : body) as BackendError;
+  const raw = inner.message ?? "";
+  const isSlug = /^[a-z][a-z0-9_]*$/.test(raw);       // "duplicate_lead" is a code, not a sentence
+  const code = inner.code ?? (isSlug ? raw : "");
+  const human = inner.detail ?? (isSlug ? "" : raw);
+  const e = new Error(leadErrorText(code, human, inner, res.status));
+  (e as unknown as { code?: string }).code = code;
+  throw e;
+}
+
+function useLiveLeads(): LeadsData {
+  const { sdk } = useAppShell();
+  const uploadPhoto = useUploadAttachment();   // presignUpload → PUT bytes → { contentRef, … }
+  const getPhotoUrl = useDownloadUrl();         // presignDownload → signed URL
+  // useQuery re-runs only on `action` change, so fetch a broad page and let the
+  // board filter/search client-side (same shape team-api uses).
+  const listQ = useQuery<Page<LeadCardDTO>>("crm.lead.search", { perPage: 100 });
+  const statsQ = useQuery<{ total?: number; byStatus?: Partial<Record<LeadStatus, number>> }>("crm.lead.stats", {});
+  // Rep/canvasser/assignee picker source (§6.6). be-crm resolves assignee/canvasser refs by
+  // principalId, so that — not the opaque member id — is the value the form must send.
+  const membersQ = useQuery<{ items: MemberDTO[] }>("crm.team.member.search", { perPage: 100 });
+
+  const reps: Rep[] = useMemo(() => (membersQ.data?.items ?? []).map((m) => {
+    const name = m.displayName?.trim()
+      || [m.firstName, m.lastName].filter(Boolean).join(" ").trim()
+      || m.jobTitle?.trim()
+      || `Member ${(m.principalId ?? m.id).replace(/^pp_/, "").slice(0, 6)}`;
+    return {
+      id: m.principalId ?? m.id,
+      initials: name.split(/\s+/).filter(Boolean).slice(0, 2).map((p) => p[0]).join("").toUpperCase() || "?",
+      name,
+      email: m.email ?? "",
+    };
+  }), [membersQ.data]);
+
+  const refetch = useCallback(() => { listQ.refetch(); statsQ.refetch(); }, [listQ, statsQ]);
+  const cmd = useCallback(async (action: string, variables: Record<string, unknown>) => {
+    await sdk.command(action, variables);
+    refetch();
+  }, [sdk, refetch]);
+
+  const leads = useMemo(() => (listQ.data?.items ?? []).map(cardToLead), [listQ.data]);
+
+  const byStatus = useMemo(() => {
+    if (statsQ.data?.byStatus) return { ...EMPTY_BY_STATUS, ...statsQ.data.byStatus };
+    const m = { ...EMPTY_BY_STATUS };
+    for (const l of leads) m[l.status] += 1;
+    return m;
+  }, [statsQ.data, leads]);
+
+  const getLead = useCallback(async (lead: Lead): Promise<Lead> => {
+    const dto = await sdk.query<LeadDTO>("crm.lead.get", { id: lead.refId ?? lead.id });
+    return detailToLead(dto, lead, reps);
+  }, [sdk, reps]);
+
+  return {
+    live: true,
+    loading: listQ.loading || statsQ.loading,
+    error: (listQ.error ?? statsQ.error)?.message ?? null,
+    leads,
+    total: statsQ.data?.total ?? listQ.data?.meta?.total ?? leads.length,
+    byStatus,
+    reps,
+    getLead,
+    uploadPhoto,
+    getPhotoUrl,
+    addPhoto: async (lead, attachment) => {
+      await sdk.command("crm.lead.attachment.add", { id: lead.refId ?? lead.id, attachment });
+    },
+    removePhoto: async (lead, attachment) => {
+      await sdk.command("crm.lead.attachment.remove", { id: lead.refId ?? lead.id, attachmentId: attachment.id });
+    },
+    // Photos are NOT sent in the create payload — they persist via the dedicated
+    // crm.lead.attachment.add command, keyed by the freshly-created lead's id (§ postman #24).
+    createLead: async (input) => {
+      const { photos, ...rest } = input;
+      // bffCommand (not sdk.command) so the backend's duplicate_lead / validation message
+      // reaches the toast instead of the SDK's opaque "data command failed: 400".
+      const created = await bffCommand<{ id: string }>("crm.lead.create", rest);
+      for (const attachment of photos ?? []) {
+        await sdk.command("crm.lead.attachment.add", { id: created.id, attachment });
+      }
+      refetch();
+    },
+    updateLead: (lead, patch) => cmd("crm.lead.update", { id: lead.refId ?? lead.id, patch }),
+    updateStatus: (lead, status, note) => cmd("crm.lead.updateStatus", { id: lead.refId ?? lead.id, status, ...(note ? { note } : {}) }),
+    assign: (lead, assigneeId) => cmd("crm.lead.assign", { id: lead.refId ?? lead.id, assigneeId }),
+    // Push into the verification queue. Idempotent server-side (returns the existing verification
+    // if the lead was already sent). Refetch so the lead's verificationId lands and the guard persists.
+    sendForVerification: async (lead) => {
+      await sdk.command("crm.lead.sendForVerification", { id: lead.refId ?? lead.id });
+      refetch();
+    },
+    refetch,
+  };
+}
+
+/* ---- public hook: pick the implementation at module-config time --------- */
+
+const SHELL = isShellConfigured();
+
+export function useLeadsData(): LeadsData {
+  // SHELL is a build-time constant, so the same hook path runs every render (Rules-of-Hooks safe).
+  return SHELL ? useLiveLeads() : useMockLeads();
+}

src/lib/verify-api.ts

@@ -0,0 +1,276 @@
+"use client";
+
+// Lead Verification data layer. Serves EITHER the local mock (when the Shell isn't configured —
+// the demo keeps working) OR the live be-crm data door (crm.leadVerification.*), behind one
+// interface so the verification desk is mode-agnostic. Mirrors team-api.ts / leads-api.ts.
+//
+// Live contract (be-crm):
+//   query crm.leadVerification.search { query?, status?, source?, assigneeId?, page?, perPage? }
+//                                                        -> { items: VerificationRowDTO[], meta }
+//   query crm.leadVerification.get    { id }             -> VerificationDTO (+ activities)
+//   query crm.leadVerification.stats  {}                 -> { verified, in_progress, assigned, pending, unverified }
+//   cmd   crm.leadVerification.verify        { id, notes? }      -> { verification, lead }  (promotes → Lead)
+//   cmd   crm.leadVerification.markUnverified { id, reason? }    -> VerificationDTO
+//   cmd   crm.leadVerification.assign        { id, assigneeId }  -> VerificationDTO
+//   cmd   crm.leadVerification.reassign      { id, assigneeId? } -> VerificationDTO (→ in_progress)
+//   cmd   crm.leadVerification.moveToPending { id }              -> VerificationDTO
+//   query crm.team.member.search { perPage }  (reused) -> assignee picker options
+
+import { useCallback, useMemo, useState } from "react";
+import { useAppShell, useQuery } from "@abe-kap/appshell-sdk/react";
+import { isShellConfigured } from "./appshell";
+import {
+  V_LEADS as seedVLeads, V_ASSIGNEES,
+  type VLead, type VStatus, type VActivity,
+} from "@/components/dashboard/verify-data";
+
+export interface Assignee { id: string; name: string; initials: string }
+
+export interface VerifyData {
+  live: boolean; loading: boolean; error: string | null;
+  leads: VLead[];
+  total: number;
+  counts: Record<VStatus, number>;
+  assignees: Assignee[];
+  /** Hydrate a single record's detail (notes, activity, verifiedAt) — synthesized in mock mode. */
+  getVerification: (lead: VLead) => Promise<VLead>;
+  verify: (lead: VLead, notes?: string) => Promise<void>;
+  markUnverified: (lead: VLead, reason?: string) => Promise<void>;
+  assign: (lead: VLead, assigneeId: string) => Promise<void>;
+  reassign: (lead: VLead, assigneeId?: string) => Promise<void>;
+  moveToPending: (lead: VLead) => Promise<void>;
+  refetch: () => void;
+}
+
+/* ---- helpers ------------------------------------------------------------ */
+
+const initialsOf = (name: string) =>
+  name.split(/\s+/).filter(Boolean).slice(0, 2).map((p) => p[0]).join("").toUpperCase() || "?";
+
+/** Resolve an assignee ref to a display name. be-crm echoes the raw principalId as the `name`,
+ *  so prefer the local assignee list (principalId → real name); fall back to a backend name only
+ *  when it isn't just the id, then to the id itself. Mirrors leads-api's resolveMemberName. */
+function resolveAssigneeName(id: string, backendName: string, assignees: Assignee[]): string {
+  const a = id ? assignees.find((x) => x.id === id) : undefined;
+  if (a) return a.name;
+  if (backendName && backendName !== id) return backendName;
+  return backendName || id;
+}
+const prettyDate = (iso?: string | null): string => {
+  if (!iso) return "—";
+  const then = Date.parse(iso);
+  if (Number.isNaN(then)) return iso;
+  return new Date(then).toLocaleDateString(undefined, { day: "numeric", month: "short", year: "numeric" });
+};
+const prettyDateTime = (iso?: string | null): string | undefined => {
+  if (!iso) return undefined;
+  const then = Date.parse(iso);
+  if (Number.isNaN(then)) return iso;
+  return new Date(then).toLocaleString(undefined, { day: "numeric", month: "short", year: "numeric", hour: "numeric", minute: "2-digit" });
+};
+
+const EMPTY_COUNTS: Record<VStatus, number> = { verified: 0, in_progress: 0, assigned: 0, pending: 0, unverified: 0 };
+
+const SUB_STATUS_DEFAULT: Record<VStatus, string> = {
+  verified: "Verified", in_progress: "Verifying Identity", assigned: "Assigned",
+  pending: "Pending Review", unverified: "Unverified",
+};
+
+/* ---- be-crm DTO types (defensive: backend is greenfield) ---------------- */
+
+interface VerificationRowDTO {
+  id: string; code: string; name: string; initials?: string;
+  address?: string; phone?: string; source?: string;
+  assignee?: { id?: string; initials?: string; name: string } | null;
+  status?: VStatus; verification?: string; createdAt?: string;
+}
+interface ActivityDTO { text: string; occurredAt?: string; time?: string; actorLabel?: string; who?: string }
+interface VerificationDTO extends VerificationRowDTO {
+  email?: string; notes?: string; verifiedAt?: string; activities?: ActivityDTO[];
+}
+
+/* ---- DTO → UI VLead ----------------------------------------------------- */
+
+function rowToVLead(d: VerificationRowDTO, assignees: Assignee[] = []): VLead {
+  const status = (d.status ?? "pending") as VStatus;
+  let assignee: VLead["assignee"] = null;
+  if (d.assignee) {
+    const id = d.assignee.id ?? "";
+    const name = resolveAssigneeName(id, d.assignee.name, assignees);
+    assignee = { id, initials: d.assignee.initials || initialsOf(name), name };
+  }
+  return {
+    id: d.code || d.id,
+    refId: d.id,
+    initials: d.initials || (d.name ? d.name[0].toUpperCase() : "?"),
+    name: d.name ?? "",
+    address: d.address ?? "",
+    phone: d.phone ?? "",
+    source: d.source ?? "",
+    assignee,
+    status,
+    verification: d.verification ?? SUB_STATUS_DEFAULT[status],
+    created: prettyDate(d.createdAt),
+  };
+}
+
+function detailToVLead(d: VerificationDTO, fallback: VLead, assignees: Assignee[] = []): VLead {
+  const base = rowToVLead(d, assignees);
+  return {
+    ...base,
+    email: d.email,
+    notes: d.notes,
+    verifiedAt: prettyDateTime(d.verifiedAt),
+    createdAt: prettyDateTime(d.createdAt) ?? fallback.createdAt,
+    activity: d.activities?.length
+      ? d.activities.map<VActivity>((a) => ({
+          text: a.text,
+          time: prettyDateTime(a.occurredAt) ?? a.time ?? "",
+          who: a.actorLabel ?? a.who ?? "System",
+        }))
+      : undefined,
+  };
+}
+
+/* ======================================================================== */
+/* Mock implementation (no Shell configured)                                */
+/* ======================================================================== */
+
+function useMockVerify(): VerifyData {
+  const [leads, setLeads] = useState<VLead[]>(() => seedVLeads);
+
+  const counts = useMemo(() => {
+    const m = { ...EMPTY_COUNTS };
+    for (const l of leads) m[l.status] += 1;
+    return m;
+  }, [leads]);
+
+  const assignees = useMemo<Assignee[]>(
+    () => V_ASSIGNEES.map((name) => ({ id: name, name, initials: initialsOf(name) })),
+    [],
+  );
+
+  const patch = useCallback((lead: VLead, next: Partial<VLead>) => {
+    setLeads((l) => l.map((x) => (x.id === lead.id ? { ...x, ...next } : x)));
+  }, []);
+
+  const getVerification = useCallback(async (lead: VLead) => lead, []);
+  const verify = useCallback(async (lead: VLead) => {
+    patch(lead, { status: "verified", verification: "Verified" });
+  }, [patch]);
+  const markUnverified = useCallback(async (lead: VLead) => {
+    patch(lead, { status: "unverified", verification: "Unverified" });
+  }, [patch]);
+  const assign = useCallback(async (lead: VLead, assigneeId: string) => {
+    const a = assignees.find((x) => x.id === assigneeId);
+    patch(lead, { status: "assigned", verification: "Assigned", assignee: a ? { id: a.id, initials: a.initials, name: a.name } : lead.assignee });
+  }, [assignees, patch]);
+  const reassign = useCallback(async (lead: VLead, assigneeId?: string) => {
+    const a = assigneeId ? assignees.find((x) => x.id === assigneeId) : undefined;
+    patch(lead, { status: "in_progress", verification: "Verifying Identity", ...(a ? { assignee: { id: a.id, initials: a.initials, name: a.name } } : {}) });
+  }, [assignees, patch]);
+  const moveToPending = useCallback(async (lead: VLead) => {
+    patch(lead, { status: "pending", verification: "Pending Review" });
+  }, [patch]);
+
+  return {
+    live: false, loading: false, error: null,
+    leads, total: leads.length, counts, assignees,
+    getVerification, verify, markUnverified, assign, reassign, moveToPending, refetch: () => {},
+  };
+}
+
+/* ======================================================================== */
+/* Live implementation (be-crm data door)                                   */
+/* ======================================================================== */
+
+interface Page<T> { items: T[]; meta?: { total?: number } }
+interface MemberDTO { id: string; principalId?: string; displayName?: string | null; firstName?: string | null; lastName?: string | null; jobTitle?: string | null }
+
+function useLiveVerify(): VerifyData {
+  const { sdk } = useAppShell();
+  // A collection read may come back as { items, meta } OR as a bare array (§6) — tolerate both.
+  const listQ = useQuery<Page<VerificationRowDTO> | VerificationRowDTO[]>("crm.leadVerification.search", { perPage: 100 });
+  const statsQ = useQuery<Partial<Record<VStatus, number>>>("crm.leadVerification.stats", {});
+  const membersQ = useQuery<{ items: MemberDTO[] }>("crm.team.member.search", { perPage: 100 });
+
+  const refetch = useCallback(() => { listQ.refetch(); statsQ.refetch(); }, [listQ, statsQ]);
+
+  // be-crm resolves the assignee ref by principalId, so send that (not the opaque member id).
+  // This list also lets us resolve an assignee id → real name for display (be-crm echoes the id).
+  const assignees = useMemo<Assignee[]>(() => (membersQ.data?.items ?? []).map((m) => {
+    const name = m.displayName?.trim()
+      || [m.firstName, m.lastName].filter(Boolean).join(" ").trim()
+      || m.jobTitle?.trim()
+      || `Member ${(m.principalId ?? m.id).slice(0, 6)}`;
+    return { id: m.principalId ?? m.id, name, initials: initialsOf(name) };
+  }), [membersQ.data]);
+
+  const rawItems = useMemo(
+    () => (Array.isArray(listQ.data) ? listQ.data : listQ.data?.items ?? []),
+    [listQ.data],
+  );
+  const base = useMemo(() => rawItems.map((d) => rowToVLead(d, assignees)), [rawItems, assignees]);
+
+  // Optimistic status overrides keyed by lead id. After a transition command we patch the row
+  // locally so the Status column updates immediately, even if the server's search read lags
+  // (read-after-write). An override always reflects the user's last action, so it stays correct
+  // whether the refetch is stale or fresh — no reconciliation needed.
+  const [overrides, setOverrides] = useState<Record<string, Partial<VLead>>>({});
+
+  const leads = useMemo(
+    () => base.map((l) => (overrides[l.id] ? { ...l, ...overrides[l.id] } : l)),
+    [base, overrides],
+  );
+
+  // Run a transition command, then optimistically patch the row + refetch to reconcile.
+  const mutate = useCallback(async (lead: VLead, patch: Partial<VLead>, action: string, variables: Record<string, unknown>) => {
+    await sdk.command(action, variables);
+    setOverrides((o) => ({ ...o, [lead.id]: { ...o[lead.id], ...patch } }));
+    refetch();
+  }, [sdk, refetch]);
+
+  // Derive tile counts from the (optimistically patched) rows so they move in lockstep with the
+  // table. With perPage 100 this covers the loaded queue; a transition reflects immediately.
+  const counts = useMemo(() => {
+    const m = { ...EMPTY_COUNTS };
+    for (const l of leads) m[l.status] += 1;
+    return m;
+  }, [leads]);
+
+  const getVerification = useCallback(async (lead: VLead): Promise<VLead> => {
+    const dto = await sdk.query<VerificationDTO>("crm.leadVerification.get", { id: lead.refId ?? lead.id });
+    return detailToVLead(dto, lead, assignees);
+  }, [sdk, assignees]);
+
+  return {
+    live: true,
+    loading: listQ.loading || statsQ.loading,
+    error: (listQ.error ?? statsQ.error)?.message ?? null,
+    leads,
+    total: (Array.isArray(listQ.data) ? undefined : listQ.data?.meta?.total) ?? leads.length,
+    counts,
+    assignees,
+    getVerification,
+    verify: (lead, notes) => mutate(lead, { status: "verified", verification: "Verified" },
+      "crm.leadVerification.verify", { id: lead.refId ?? lead.id, ...(notes ? { notes } : {}) }),
+    markUnverified: (lead, reason) => mutate(lead, { status: "unverified", verification: "Unverified" },
+      "crm.leadVerification.markUnverified", { id: lead.refId ?? lead.id, ...(reason ? { reason } : {}) }),
+    assign: (lead, assigneeId) => mutate(lead, { status: "assigned", verification: "Assigned" },
+      "crm.leadVerification.assign", { id: lead.refId ?? lead.id, assigneeId }),
+    reassign: (lead, assigneeId) => mutate(lead, { status: "in_progress", verification: "Verifying Identity" },
+      "crm.leadVerification.reassign", { id: lead.refId ?? lead.id, ...(assigneeId ? { assigneeId } : {}) }),
+    moveToPending: (lead) => mutate(lead, { status: "pending", verification: "Pending Review" },
+      "crm.leadVerification.moveToPending", { id: lead.refId ?? lead.id }),
+    refetch,
+  };
+}
+
+/* ---- public hook: pick the implementation at module-config time --------- */
+
+const SHELL = isShellConfigured();
+
+export function useVerifyData(): VerifyData {
+  // SHELL is a build-time constant, so the same hook path runs every render (Rules-of-Hooks safe).
+  return SHELL ? useLiveVerify() : useMockVerify();
+}