document for leads backend req

- Add Lead source dropdown options (Door Knock, Referral, Storm Chase,
  Mailer/Postcard, Sign Call, Insurance Agent Referral, Repeat Customer,
  Social Media, Other)
- Quick form: Referral shows a referral-note textarea; Door Knock shows a
  canvasser search (by name or email) with picker + chip
- Full form is now a Next/Back wizard ending in Create Lead
- Reps gain email for canvasser search

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

.gitignore

@@ -41,3 +41,8 @@ yarn-error.log*
 next-env.d.ts
 
 .vercel
+.env*.local
+
+certificates
+AI_ASSISTANT_BACKEND_PLAN.md
+TEAM_MANAGEMENT_BACKEND_PLAN.md

.npmrc

@@ -1,2 +1,6 @@
 @abe-kap:registry=https://npm.pkg.github.com
 //npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
+# @insignia/* (iios-kernel-client — the MessageSocket live stream) resolve from the
+# self-hosted Gitea npm registry. Install needs a token with `read:package` in GITEA_TOKEN.
+@insignia:registry=https://git.lynkedup.cloud/api/packages/insignia/npm/
+//git.lynkedup.cloud/api/packages/insignia/npm/:_authToken=${GITEA_TOKEN}

LEADS_BACKEND_REQUIREMENTS.md

@@ -0,0 +1,827 @@
+# Leads & Lead Verification — Backend Requirements
+
+**Project:** LynkedUp Pro CRM (`lynkeduppro-crm`)
+**Domain service:** `be-crm` (the CRM "data door")
+**Modules covered:** `Leads`, `Lead Verification`
+**Document status:** Implementation-ready. Derived entirely from the current frontend.
+**Author basis:** Reverse-engineered from the completed frontend + the existing backend integration conventions already used by the Team, Mail, Inbox, Messenger, Media and Account modules.
+
+---
+
+> ## ⚠️ Read this first — current state of the frontend
+>
+> Both modules are **fully built on the UI side but wired to client-side mock data only**. There is **no live backend call anywhere** in `leads.tsx`, `leads-data.ts`, `verify.tsx`, or `verify-data.ts`. Every "write" today (Create Lead, Verify, Mark Unverified, Change Assignee, Update Status, Call, Email, Refresh) only pushes a **toast notification** — no persistence, no network request.
+>
+> This means the **entire** Leads and Lead Verification backend is greenfield. However, the frontend precisely defines the required **fields, enums, filters, sub-statuses, actions and workflows**, so this document treats the mock shapes as the authoritative contract.
+>
+> Wherever a control exists visually but has no behaviour yet, it is tagged **`[Frontend Placeholder / Backend Pending]`** so you know it is a real requirement even though the UI does not call it yet.
+>
+> The design below deliberately **reuses the existing `be-crm` architecture** (query/command data door, not REST). Do **not** invent a REST API — see §11 (Existing Backend Integration) for the mandatory conventions.
+
+---
+
+## Table of Contents
+
+1. [Module Overview](#1-module-overview)
+2. [Existing Frontend Features (exhaustive)](#2-existing-frontend-features-exhaustive)
+3. [User Flows](#3-user-flows)
+4. [Database Models](#4-database-models)
+5. [Entity Relationships](#5-entity-relationships)
+6. [API Contract — Actions (Queries & Commands)](#6-api-contract--actions-queries--commands)
+7. [Validation Rules](#7-validation-rules)
+8. [Reference / Enum Data](#8-reference--enum-data)
+9. [Backend Services](#9-backend-services)
+10. [Error Handling](#10-error-handling)
+11. [Existing Backend Integration (mandatory conventions)](#11-existing-backend-integration-mandatory-conventions)
+12. [Gaps, Discrepancies & Backend-Pending Items](#12-gaps-discrepancies--backend-pending-items)
+
+---
+
+## 1. Module Overview
+
+### 1.1 Leads module
+
+**Purpose:** The **Leads** module is the storm-restoration sales pipeline board. It holds prospective roofing jobs (door-knocked, referred, storm-chased, etc.) inside a hail-storm territory (the demo is the Plano, TX hail zone, storm event `2026-04-28`). Each lead is a rich record combining **contact**, **property**, **job details**, **insurance** and **assignment** information, and moves through a sales status pipeline.
+
+**Frontend surface:** `src/components/dashboard/leads.tsx` (+ `leads-data.ts`), rendered inside the dashboard shell when the `leads` nav key is active.
+
+**Core capabilities visible in the UI:**
+- A **stat strip** (Total / New / Contacted / Appointed / Closed counts).
+- A **board of lead cards** (avatar, priority ring, status pill, address, primary phone, source, canvasser, "updated" relative time).
+- **Search** (by name / address / city / source / canvasser) and **status filter tabs**.
+- A **lead detail modal** (Contact, Property, Job Details, Insurance, Assignment, storm banner).
+- A **New Lead intake** with two modes: **Quick** (single condensed form) and **Full Form** (a 5-step wizard: Contact → Property → Job Details → Insurance → Assignment).
+
+### 1.2 Lead Verification module
+
+**Purpose:** The **Lead Verification** module is the verification desk that sits **upstream of Leads**. Freshly captured leads (door-knock / web form / storm canvass / referral / call-in) must pass an **identity + insurance + ownership + damage** verification workflow before they become working sales leads. The desk's terminal success action is literally *"Verified and pushed to New Leads"* — i.e., a verified verification record becomes a Lead with status `new`.
+
+**Frontend surface:** `src/components/dashboard/verify.tsx` (+ `verify-data.ts`), rendered when the `verify` nav key is active.
+
+**Core capabilities visible in the UI:**
+- **Clickable stat tiles** (Verified / In Progress / Assigned / Pending / Unverified) that also act as status filters.
+- A **data table** (Lead ID · Customer · Phone · Source · Assigned To · Status · Verification sub-status · Created · Actions).
+- **Search** + **status / source / assignee** dropdown filters.
+- A **row action set** (View, Verify, and a `⋯` menu: View Details, Verify Lead, Mark Unverified, Change Assignee, Reassign → In Progress, Move to Pending).
+- A **verification detail modal** (Contact, Assignment, Verification Notes, and an **Activity timeline**).
+- A **Refresh** button.
+
+### 1.3 Relationship between the two modules
+
+```
+   Intake sources                    Lead Verification desk                 Leads pipeline
+ (door knock, web form,   ─────►   verify identity / ownership /   ─────►   status = "new"
+  storm canvass, referral,          insurance / damage                      → contacted → appointed
+  call-in)                          (verified | in_progress |                → closed
+                                     assigned | pending | unverified)
+```
+
+- A **Lead Verification** record is the *pre-lead*. When it reaches `verified`, the system **creates / promotes** it into a **Lead** (`status = "new"`). This is the single hard link between the two modules and the most important cross-module command to implement (see `crm.leadVerification.verify` in §6).
+- Both modules are gated by the **same** CRM permission: **`leads.manage`** (see `NAV_PERMISSION` in `sidebar.tsx`). There is no separate verification permission in the frontend.
+- Both are **tenant-scoped** — every record belongs to the signed-in user's organization/tenant (the demo boots as `tenant-acme-01`).
+
+### 1.4 User journey (end-to-end)
+
+1. A lead is **captured** at an intake source and lands in the **Verification** queue as `pending` (unassigned) or `assigned`.
+2. A **verification specialist** (Wade Hollis, Darlene Brooks, Roy Schaefer in the mock) is assigned and works the record through sub-statuses (`Verifying Identity` → `Confirming Ownership` → `Reviewing Insurance` → `Confirming Damage`).
+3. The specialist either **Verifies** it (→ becomes a Lead, `status = new`) or **Marks Unverified**.
+4. In the **Leads** module, a sales rep / canvasser works the new lead: **Contacted** → **Appointed** → **Closed**, updating status, priority, follow-up date, insurance/claim details and assignment along the way.
+
+---
+
+## 2. Existing Frontend Features (exhaustive)
+
+Only features actually present in the code are listed. Each is tagged **Wired** (has real logic, even if only client-side state) or **`[Placeholder / Backend Pending]`** (UI exists, no behaviour beyond a toast).
+
+### 2.1 Leads module features
+
+| # | Feature | State | Notes / source |
+|---|---------|-------|----------------|
+| L1 | Lead board / card list | Wired (mock) | `LEADS` array rendered as `LeadCard`s |
+| L2 | Header stat strip (Total, New, Contacted, Appointed, Closed) | Wired (mock) | `countByStatus`; `TOTAL_LEADS = 35` shown as total |
+| L3 | Text search (name, address, city, source, canvasser) | Wired (mock) | `filtered` memo, case-insensitive substring |
+| L4 | Status filter tabs (All / New / Contacted / Appointed / Closed) | Wired (mock) | `STATUS_TABS` |
+| L5 | Lead detail modal (Contact, Property, Job, Insurance, Assignment, storm banner) | Wired (mock, read-only) | `LeadDetail` |
+| L6 | Create Lead — Quick mode | **Placeholder** | `submit()` only validates name then toasts; no persistence |
+| L7 | Create Lead — Full Form wizard (5 steps) | **Placeholder** | steps: Contact / Property / Job / Insurance / Assignment |
+| L8 | Multiple phone numbers (with type Mobile/Home/Work + primary) | Wired (form state) | `addPhone/setPhone/removePhone` |
+| L9 | Multiple email addresses | Wired (form state) | `addEmail/setEmail/removeEmail` |
+| L10 | Site photos upload | **Placeholder** | `addPhoto()` just appends a label string `"Photo N"` — no real upload |
+| L11 | Conditional field: Referral note (source = Referral) | Wired (form state) | `f.source === "Referral"` |
+| L12 | Conditional field: Canvasser search (source = Door Knock) | Wired (form state) | `CanvasserSearch` typeahead over `REPS` |
+| L13 | Priority picker (Low / Medium / High) | Wired (form state) | `PriorityPicker` |
+| L14 | Urgency picker (Standard / High / Emergency) | Wired (form state) | `UrgencyPicker` |
+| L15 | Rep assignment select (incl. "Unassigned") | Wired (form state) | `RepSelect`, options from `REPS` |
+| L16 | Detail action: **Update Status** | **Placeholder** | footer button, no handler |
+| L17 | Detail action: **Call** / **Email** | **Placeholder** | footer buttons, no handler |
+| L18 | Empty state ("No leads match") | Wired | shown when `filtered.length === 0` |
+
+**Not present in Leads (do not build unless requested):** edit-existing-lead form, delete, archive, bulk actions, tags editor (only a single static `tag` string exists), notes/comments thread, per-lead activity timeline, attachments list, pagination controls, sorting controls, export.
+
+### 2.2 Lead Verification module features
+
+| # | Feature | State | Notes / source |
+|---|---------|-------|----------------|
+| V1 | Stat tiles (Verified / In Progress / Assigned / Pending / Unverified) | Wired (mock) | `STAT_ORDER`, counts from `V_LEADS` |
+| V2 | Stat tile click = status filter toggle | Wired (mock) | `setStatus(status === s ? "all" : s)` |
+| V3 | Verification table (9 columns) | Wired (mock) | see column list in §1.2 |
+| V4 | Text search (name, lead ID, phone, source, address) | Wired (mock) | `rows` memo |
+| V5 | Status filter dropdown | Wired (mock) | mirrors stat tiles |
+| V6 | Source filter dropdown | Wired (mock) | `V_SOURCES` |
+| V7 | Assignee filter dropdown | Wired (mock) | `V_ASSIGNEES` |
+| V8 | Row action: **View details** | Wired (mock) | opens `VerifyDetail` |
+| V9 | Row action: **Verify** (quick) | **Placeholder** | toast only |
+| V10 | Row `⋯` menu | Wired (open/close) | portalled dropdown |
+| V11 | Menu: Verify Lead | **Placeholder** | toast only |
+| V12 | Menu: Mark Unverified | **Placeholder** | toast only |
+| V13 | Menu: Change Assignee | **Placeholder** | toast only |
+| V14 | Menu: Reassign (→ In Progress) | **Placeholder** | toast only |
+| V15 | Menu: Move to Pending | **Placeholder** | toast only |
+| V16 | Detail modal — Contact / Assignment sections | Wired (mock, read) | `VerifyDetail` |
+| V17 | Detail modal — Verification Notes | Wired (mock, read) | shown when `notes` present |
+| V18 | Detail modal — Activity timeline | Wired (mock, read + derived) | `buildActivity()` synthesizes when absent |
+| V19 | Detail footer: Verify Lead / Call | **Placeholder** | buttons, no handler |
+| V20 | Refresh button | **Placeholder** | toast only ("Queue refreshed") |
+| V21 | Row count "X of Y leads" | Wired (mock) | implies server total vs filtered count |
+| V22 | Derived email / created-at when absent | Wired (mock) | `deriveEmail`, `deriveCreatedAt` |
+
+**Not present in Verification (do not build unless requested):** create-verification-from-UI (records arrive via intake, never created here — mirrors the Inbox "items are never created here" pattern), delete, bulk verify, attachments, document upload, editable contact fields.
+
+---
+
+## 3. User Flows
+
+### 3.1 Lead Verification status flow
+
+Statuses (`VStatus`): `unverified`, `pending`, `assigned`, `in_progress`, `verified`.
+Each status also carries a human **sub-status** string (`verification`).
+
+```
+      intake (door knock / web form / storm canvass / referral / call-in)
+                                   │
+                                   ▼
+        ┌──────────── pending ("Pending Review", unassigned) ────────────┐
+        │                          │                                     │
+        │                  [Change Assignee]                             │
+        │                          ▼                                     │
+        │                     assigned ("Assigned")                      │
+        │                          │                                     │
+        │                 [Reassign / start work]                        │
+        │                          ▼                                     │
+        │            in_progress ("Verifying Identity" /                 │
+        │             "Confirming Ownership" /                           │
+        │             "Reviewing Insurance" /                            │
+        │             "Confirming Damage")                               │
+        │                     │            │                             │
+        │             [Verify]│            │[Mark Unverified]            │
+        │                     ▼            ▼                             │
+        │               verified       unverified ◄─────────────────────┘
+        │            ("Verified")     ("Unverified")
+        │                     │
+        │                     ▼
+        │     ┌───────────────────────────────┐
+        └────►│ PROMOTE → create Lead(status = │
+              │ "new") + activity "Verified    │
+              │ and pushed to New Leads."      │
+              └───────────────────────────────┘
+
+  [Move to Pending] can send an assigned/in_progress record back to pending.
+```
+
+**Allowed transitions (enforce server-side):**
+
+| From | To | Trigger command |
+|------|----|-----------------|
+| `pending` | `assigned` | `assign` (set assignee) |
+| `pending` / `assigned` / `in_progress` | `in_progress` | `reassign` / `setInProgress` |
+| `assigned` / `in_progress` | `pending` | `moveToPending` |
+| `pending` / `assigned` / `in_progress` | `verified` | `verify` (→ promotes to Lead) |
+| `pending` / `assigned` / `in_progress` | `unverified` | `markUnverified` |
+| any | (assignee change) | `assign` / `changeAssignee` |
+
+> The frontend does not restrict transitions (every action is available on every row), so treat the table above as the **recommended** guard set; at minimum, forbid transitions out of a terminal `verified` record except via an explicit re-open (backend-pending, not in UI).
+
+### 3.2 Lead sales status flow
+
+Statuses (`LeadStatus`): `new`, `contacted`, `appointed`, `closed`.
+
+```
+  (created directly OR promoted from a verified verification)
+                         │
+                         ▼
+                        new
+                         │  [Update Status] / rep works the lead
+                         ▼
+                     contacted
+                         │
+                         ▼
+                     appointed   (adjuster / inspection appointment set)
+                         │
+                         ▼
+                      closed      (won/installed/paid — mock leans "won")
+```
+
+`priority` (`high` / `medium` / `low`) and `job.urgency` (`Standard` / `High` / `Emergency`) are independent of status and set at creation / update.
+
+### 3.3 Create Lead (Full Form wizard) flow
+
+```
+ Step 1 Contact   → firstName*, lastName, phones[] (type + primary), emails[]
+ Step 2 Property  → address, city, state (default "TX"), zip, propertyType, photos[]
+ Step 3 Job       → source, leadType, workType, tradeType, urgency, notes
+                    (source=Referral → referralNote; source=Door Knock → canvasser)
+ Step 4 Insurance → insCompany, claimNumber, claimStatus, adjusterName,
+                    adjusterPhone, policyNumber
+ Step 5 Assignment→ assignRep (or Unassigned), priority, followUp date
+                    → [Create Lead] → crm.lead.create
+```
+
+Quick mode collects a condensed subset (firstName*, lastName, phone[0], address, city, state, zip, source, [referralNote|canvasser], priority, followUp) and submits the same `crm.lead.create`.
+
+`*` = the only field the frontend currently enforces is a non-empty **name** (first or last).
+
+---
+
+## 4. Database Models
+
+Storage assumptions follow the existing `be-crm` domain service (relational, multi-tenant). **Every table carries `tenant_id`** and is always filtered by it. Primary keys are opaque server IDs; the human-facing **codes** (`SAL-001`, `LD-V-001`) are separate, per-tenant, monotonic display identifiers.
+
+Timestamps are stored as `timestamptz` (UTC, ISO-8601 on the wire). Relative strings like `"3d ago"` and pretty dates like `"Jun 4, 2026"` seen in the mock are **presentation-only** — the API returns ISO timestamps and the client formats them (see `relTime()` in `team-api.ts`).
+
+### 4.1 `leads`
+
+**Purpose:** One row per sales lead (the Leads board card + detail modal).
+
+| Field | Type | Null | Default | Notes |
+|-------|------|------|---------|-------|
+| `id` | uuid / string PK | no | gen | opaque server id |
+| `tenant_id` | uuid/string FK → organizations | no | — | tenant scope; **indexed** |
+| `code` | text | no | seq | display code `SAL-001`; **unique per tenant** |
+| `first_name` | text | no | — | |
+| `last_name` | text | yes | null | name = `first + last`, trimmed |
+| `status` | enum `lead_status` | no | `'new'` | `new` \| `contacted` \| `appointed` \| `closed` |
+| `priority` | enum `lead_priority` | no | `'medium'` | `high` \| `medium` \| `low` (UI Quick default = Medium) |
+| `tag` | text | yes | `'Storm Zone'` | single label chip |
+| `property_address` | text | yes | null | |
+| `property_city` | text | yes | null | |
+| `property_state` | text | yes | `'TX'` | 2-letter; UI default TX |
+| `property_zip` | text | yes | null | |
+| `property_type` | text | yes | null | see `PROPERTY_TYPES` enum |
+| `source` | text | yes | null | see `LEAD_SOURCES` enum |
+| `referral_note` | text | yes | null | only when `source = 'Referral'` |
+| `lead_type` | text | yes | null | see §12 note on the enum conflict |
+| `work_type` | text | yes | null | see `WORK_TYPES` |
+| `trade_type` | text | yes | null | see `TRADE_TYPES` |
+| `urgency` | enum `lead_urgency` | no | `'Standard'` | `Standard` \| `High` \| `Emergency` |
+| `job_notes` | text | yes | null | "Field Notes" |
+| `canvasser_id` | FK → members | yes | null | door-knock canvasser (REP id, e.g. `LUP-1040`) |
+| `insurance_company` | text | yes | null | |
+| `insurance_claim_status` | enum `claim_status` | yes | null | `Not Filed`\|`Filed`\|`Approved`\|`Paid`\|`Denied` |
+| `insurance_claim_number` | text | yes | null | |
+| `insurance_policy_number` | text | yes | null | |
+| `insurance_adjuster_name` | text | yes | null | |
+| `insurance_adjuster_phone` | text | yes | null | |
+| `assigned_to_id` | FK → members | yes | null | rep working the lead |
+| `follow_up_date` | date | yes | null | |
+| `storm_zone` | text | yes | null | e.g. "E Plano / Spring Creek Pkwy" |
+| `storm_date` | date | yes | null | e.g. `2026-04-28` |
+| `storm_detail` | text | yes | null | e.g. `2.5" hail (severe)` |
+| `source_verification_id` | FK → lead_verifications | yes | null | set when promoted from a verification |
+| `created_by_id` | FK → members | yes | null | |
+| `created_at` | timestamptz | no | now() | |
+| `updated_at` | timestamptz | no | now() | drives "updated 3d ago" |
+
+**Indexes:** `(tenant_id)`, `(tenant_id, status)`, `(tenant_id, code)` unique, `(tenant_id, assigned_to_id)`, `(tenant_id, source)`, `(tenant_id, updated_at desc)`.
+**Search:** the board search covers name + property address + city + source + canvasser → back with a `tsvector` / trigram index over those columns.
+
+**Example row (from `SAL-001`):**
+```json
+{
+  "id": "ld_9f2c…", "code": "SAL-001",
+  "firstName": "John", "lastName": "Martinez",
+  "status": "contacted", "priority": "high", "tag": "Storm Zone",
+  "propertyAddress": "4821 Spring Creek Pkwy", "propertyCity": "Plano",
+  "propertyState": "TX", "propertyZip": "75023", "propertyType": "Single Family",
+  "source": "Door Knock", "leadType": "Insurance",
+  "workType": "Roof Replacement", "tradeType": "Roofing", "urgency": "High",
+  "jobNotes": "Homeowner showed significant granule loss…",
+  "canvasserId": "LUP-1040",
+  "insuranceCompany": "State Farm", "insuranceClaimStatus": "Filed",
+  "insuranceClaimNumber": "CLM-2026-1000", "insurancePolicyNumber": "POL-080000",
+  "insuranceAdjusterName": "Marcus Powell", "insuranceAdjusterPhone": "(972) 700-3000",
+  "assignedToId": "LUP-…", "followUpDate": "2026-06-04",
+  "stormZone": "E Plano / Spring Creek Pkwy", "stormDate": "2026-04-28",
+  "stormDetail": "2.5\" hail (severe)",
+  "createdById": "LUP-1040", "createdAt": "2026-05-28T15:00:00Z", "updatedAt": "…"
+}
+```
+
+### 4.2 `lead_phones`
+
+**Purpose:** A lead has 1..N phone numbers, one primary.
+
+| Field | Type | Null | Default | Notes |
+|-------|------|------|---------|-------|
+| `id` | PK | no | gen | |
+| `tenant_id` | FK | no | — | |
+| `lead_id` | FK → leads | no | — | **on delete cascade** |
+| `number` | text | no | — | free-form display, e.g. `(469) 500-1000` |
+| `type` | enum `phone_type` | no | `'Mobile'` | `Mobile` \| `Home` \| `Work` |
+| `is_primary` | bool | no | false | exactly one true per lead (enforce) |
+| `position` | int | no | 0 | display order |
+
+**Indexes:** `(lead_id)`. **Constraint:** partial unique `(lead_id) where is_primary` to guarantee a single primary.
+
+### 4.3 `lead_emails`
+
+| Field | Type | Null | Default | Notes |
+|-------|------|------|---------|-------|
+| `id` | PK | no | gen | |
+| `tenant_id` | FK | no | — | |
+| `lead_id` | FK → leads | no | — | cascade |
+| `address` | text | no | — | validate email format |
+| `type` | text | yes | null | optional label |
+| `is_primary` | bool | no | false | |
+| `position` | int | no | 0 | |
+
+### 4.4 `lead_attachments` (site photos) — `[Backend Pending]`
+
+**Purpose:** Backs the "Site Photos" uploader (L10). The frontend currently only stores placeholder labels; the real implementation must use the existing media presign flow (§11.5).
+
+| Field | Type | Null | Default | Notes |
+|-------|------|------|---------|-------|
+| `id` | PK | no | gen | |
+| `tenant_id` | FK | no | — | |
+| `lead_id` | FK → leads | no | — | cascade |
+| `content_ref` | text | no | — | IIOS object key from `crm.media.presignUpload` |
+| `mime_type` | text | no | — | |
+| `size_bytes` | bigint | no | — | ≤ `26_214_400` (25 MB) |
+| `filename` | text | yes | null | |
+| `uploaded_by_id` | FK → members | yes | null | |
+| `created_at` | timestamptz | no | now() | |
+
+### 4.5 `lead_status_history` (audit) — recommended
+
+**Purpose:** Backs "Update Status" auditing (no dedicated Leads timeline UI exists yet, but status changes must be auditable and this feeds a future timeline). Mirrors the verification activity concept.
+
+| Field | Type | Null | Notes |
+|-------|------|------|-------|
+| `id` | PK | no | |
+| `tenant_id` | FK | no | |
+| `lead_id` | FK → leads | no | cascade |
+| `from_status` | enum | yes | null on create |
+| `to_status` | enum | no | |
+| `actor_id` | FK → members | yes | |
+| `note` | text | yes | |
+| `created_at` | timestamptz | no | |
+
+### 4.6 `lead_verifications`
+
+**Purpose:** One row per verification-desk record (the Verification table row + detail).
+
+| Field | Type | Null | Default | Notes |
+|-------|------|------|---------|-------|
+| `id` | PK | no | gen | |
+| `tenant_id` | FK | no | — | indexed |
+| `code` | text | no | seq | display code `LD-V-001`; **unique per tenant** |
+| `name` | text | no | — | customer full name (single field in UI) |
+| `phone` | text | yes | null | |
+| `email` | text | yes | null | derived client-side when absent (see `deriveEmail`) |
+| `address` | text | yes | null | single-line address string in UI |
+| `source` | text | no | — | see `V_SOURCES` (`Door Knock`, `Web Form`, `Storm Canvass`, `Referral`, `Call-In`) |
+| `status` | enum `verification_status` | no | `'pending'` | `verified`\|`in_progress`\|`assigned`\|`pending`\|`unverified` |
+| `sub_status` | text | no | `'Pending Review'` | the `verification` label, see §8.6 |
+| `assignee_id` | FK → members | yes | null | verification specialist |
+| `notes` | text | yes | null | "Verification Notes" |
+| `promoted_lead_id` | FK → leads | yes | null | set when verified → Lead created |
+| `verified_at` | timestamptz | yes | null | |
+| `created_at` | timestamptz | no | now() | drives "Created" column |
+| `updated_at` | timestamptz | no | now() | |
+
+**Indexes:** `(tenant_id)`, `(tenant_id, status)`, `(tenant_id, source)`, `(tenant_id, assignee_id)`, `(tenant_id, code)` unique, `(tenant_id, created_at desc)`.
+**Search:** name + code + phone + source + address → trigram/tsvector.
+
+**Example rows (from `LD-V-001` and a lean one):**
+```json
+{ "id":"lv_1…","code":"LD-V-001","name":"Kevin Hartley",
+  "phone":"(972) 413-8902","email":"kevin.hartley@gmail.com",
+  "address":"2814 Ravenswood Dr, Plano, TX 75023","source":"Door Knock",
+  "status":"verified","subStatus":"Verified","assigneeId":"…Wade…",
+  "notes":"Ownership confirmed via county records…",
+  "verifiedAt":"2026-05-16T19:55:00Z","createdAt":"2026-05-14T14:40:00Z" }
+
+{ "id":"lv_11…","code":"LD-V-011","name":"Aaron Blake",
+  "phone":"(469) 471-3350","address":"1188 Alma Dr, Plano, TX 75075",
+  "source":"Door Knock","status":"pending","subStatus":"Pending Review",
+  "assigneeId":null,"createdAt":"2026-05-27T…" }
+```
+
+### 4.7 `lead_verification_activities`
+
+**Purpose:** The Activity timeline in the verification detail (V18). The frontend synthesizes these when absent (`buildActivity`), but the backend should persist real ones.
+
+| Field | Type | Null | Notes |
+|-------|------|------|-------|
+| `id` | PK | no | |
+| `tenant_id` | FK | no | |
+| `verification_id` | FK → lead_verifications | no | cascade |
+| `text` | text | no | e.g. "Assigned to Wade Hollis." |
+| `actor_id` | FK → members | yes | maps to `who` (name shown; "System" when null) |
+| `actor_label` | text | yes | denormalized display name / "System" |
+| `occurred_at` | timestamptz | no | maps to `time` |
+| `kind` | text | yes | optional: `submitted`\|`assigned`\|`in_progress`\|`verified`\|`unverified`\|`note` |
+
+**Index:** `(verification_id, occurred_at)`.
+
+### 4.8 Referenced existing tables (do **not** recreate)
+
+- **`organizations` / tenant** — tenant scope (`tenant_id`). Established at boot / registration (`crm.account.register`).
+- **`members`** — CRM team members (reps, canvassers, verification specialists). Already served by `crm.team.member.search` and carry ids like `LUP-1040` plus `principalId`. Leads/verifications reference members for `assigned_to`, `canvasser`, `assignee`, `created_by`, and activity `actor`. In the mock these are free-text names — the backend must resolve them to member ids (see §12).
+- **Account/permissions** — `crm.account.me` drives `leads.manage` gating.
+
+---
+
+## 5. Entity Relationships
+
+```
+organizations (tenant)
+   1 ──────────────< leads
+   1 ──────────────< lead_verifications
+   1 ──────────────< members
+
+members
+   1 ──< leads.assigned_to_id
+   1 ──< leads.canvasser_id
+   1 ──< leads.created_by_id
+   1 ──< lead_verifications.assignee_id
+   1 ──< lead_verification_activities.actor_id
+   1 ──< lead_status_history.actor_id
+
+leads
+   1 ──< lead_phones           (cascade)
+   1 ──< lead_emails           (cascade)
+   1 ──< lead_attachments      (cascade)   [backend-pending]
+   1 ──< lead_status_history   (cascade)
+
+lead_verifications
+   1 ──< lead_verification_activities (cascade)
+   1 ──0..1 leads              (promotion: lead_verifications.promoted_lead_id
+                                ⇆ leads.source_verification_id)
+```
+
+**Cardinality summary**
+
+| Relationship | Type | Notes |
+|--------------|------|-------|
+| tenant → lead | 1‑to‑many | all leads tenant-scoped |
+| tenant → verification | 1‑to‑many | |
+| lead → phones | 1‑to‑many | ≥1, exactly one primary |
+| lead → emails | 1‑to‑many | 0..N |
+| lead → attachments | 1‑to‑many | 0..N (pending) |
+| lead → status history | 1‑to‑many | audit |
+| verification → activities | 1‑to‑many | timeline |
+| verification → lead | 1‑to‑(0..1) | promotion link, bidirectional FK |
+| member → lead (assigned/canvasser/creator) | many‑to‑1 each | nullable |
+| member → verification (assignee) | many‑to‑1 | nullable |
+
+**Embedded value objects (not separate tables — stored as columns on `leads`):** `storm { zone, date, detail }`, `property { … }`, `job { … }`, `insurance { … }`, `assignment { … }`. They are grouped only for UI sectioning; there is no reuse that justifies separate tables. Phones and emails **are** separate tables because they are 1‑to‑many.
+
+---
+
+## 6. API Contract — Actions (Queries & Commands)
+
+> **Transport & style (mandatory):** These are **not REST routes**. They are `be-crm` **data-door actions** invoked through the AppShell SDK exactly like every other module:
+> - **Reads:** `useQuery<T>("<action>", variables)` → resolves to `T` (or `null` while loading). Errors surface as an `Error` with `.message`.
+> - **Writes:** `sdk.command<T>("<action>", variables)` → resolves to `T`. Commands carry an auto-generated idempotency key.
+> - **Action naming:** `crm.<entity>.<verb>` — dot-namespaced, camelCase segments (matches `crm.team.member.setRoles`, `crm.inbox.transition`, `crm.mail.reply`).
+> - **Collection reads** return either a bare array (like `crm.mail.list`, `crm.inbox.list`) or `{ items: T[], meta }` (like `crm.team.member.search`). For Leads/Verification use **`{ items, meta }`** because the UI needs totals + pagination (§6.1).
+
+### 6.1 Standard collection envelope
+
+```ts
+interface Meta { total: number; page: number; perPage: number; }
+interface Page<T> { items: T[]; meta: Meta; }
+```
+- `verify.tsx` renders `"{rows.length} of {V_LEADS.length} leads"` → `rows.length` is the filtered page length, `meta.total` is the (filtered or overall) count. Return the **filtered** total so the "X of Y" reads correctly, plus the unfiltered stat counts via the dedicated `*.stats` action.
+- `leads.tsx` shows `TOTAL_LEADS = 35` while only rendering 5 cards → the board is paginated/capped server-side; provide `perPage` (UI has no pager control yet, so default a sensible `perPage`, e.g. 50, and return `meta.total` for the header).
+
+### 6.2 Leads — Queries
+
+| Action | Variables | Returns | Backs |
+|--------|-----------|---------|-------|
+| `crm.lead.search` | `{ query?, status?, priority?, source?, assigneeId?, page?, perPage? }` | `Page<LeadCardDTO>` | board list L1, search L3, tabs L4 |
+| `crm.lead.get` | `{ id }` | `LeadDTO` (full detail incl. phones/emails/attachments) | detail modal L5 |
+| `crm.lead.stats` | `{}` | `{ total: number, byStatus: { new, contacted, appointed, closed } }` | stat strip L2 |
+
+`LeadCardDTO` (list projection — only what the card needs):
+```ts
+{ id, code, name, initials, gradient, priority, status, tag,
+  primaryPhone, propertyAddress, propertyCity, propertyState,
+  source, canvasserName, updatedAt }
+```
+`LeadDTO` (detail projection): all §4.1 columns + `phones: Phone[]` + `emails: Email[]` + `attachments: Attachment[]` + resolved assignee/canvasser/creator display names + `storm`, `property`, `job`, `insurance`, `assignment` groupings.
+
+### 6.3 Leads — Commands
+
+| Action | Variables | Returns | Backs |
+|--------|-----------|---------|-------|
+| `crm.lead.create` | full create payload (below) | `LeadDTO` | Create Lead L6/L7 |
+| `crm.lead.update` | `{ id, patch: Partial<LeadInput> }` | `LeadDTO` | edit (backend-pending; UI edit form not built) |
+| `crm.lead.updateStatus` | `{ id, status, note? }` | `LeadDTO` | detail "Update Status" L16 |
+| `crm.lead.assign` | `{ id, assigneeId \| null }` | `LeadDTO` | rep assignment L15 |
+| `crm.lead.attachment.add` | `{ id, attachment: { contentRef, mimeType, sizeBytes, filename } }` | `LeadDTO` | site photos L10 (pending) |
+| `crm.lead.attachment.remove` | `{ id, attachmentId }` | `LeadDTO` | pending |
+| `crm.lead.archive` | `{ id }` | `{ id }` | **pending** — no UI yet; include only if requested |
+| `crm.lead.delete` | `{ id }` | `{ id }` | **pending** — no UI yet; include only if requested |
+
+**`crm.lead.create` payload** (union of Quick + Full form, all optional except `firstName`/`lastName` where at least one non-empty):
+```ts
+{
+  firstName: string, lastName?: string,
+  phones: { number: string, type: "Mobile"|"Home"|"Work", primary?: boolean }[],
+  emails?: { address: string, primary?: boolean }[],
+  property?: { address?, city?, state?, zip?, type? },
+  photos?: { contentRef, mimeType, sizeBytes, filename }[],   // real uploads (pending)
+  job?: { source?, referralNote?, canvasserId?, leadType?, workType?, tradeType?,
+          urgency?: "Standard"|"High"|"Emergency", notes? },
+  insurance?: { company?, claimNumber?, claimStatus?, adjusterName?,
+                adjusterPhone?, policyNumber? },
+  assignment?: { assigneeId?: string|null, priority?: "Low"|"Medium"|"High",
+                 followUp?: string /* ISO date */ }
+}
+```
+> Note the **priority casing mismatch**: the create form emits `"Low"|"Medium"|"High"` (title-case) while list/detail data uses `"low"|"medium"|"high"`. Normalize to lowercase on write (see §12).
+
+### 6.4 Lead Verification — Queries
+
+| Action | Variables | Returns | Backs |
+|--------|-----------|---------|-------|
+| `crm.leadVerification.search` | `{ query?, status?, source?, assigneeId?, page?, perPage? }` | `Page<VerificationRowDTO>` | table V3, search V4, filters V5–V7 |
+| `crm.leadVerification.get` | `{ id }` | `VerificationDTO` (+ activities) | detail V16–V18 |
+| `crm.leadVerification.stats` | `{}` | `{ verified, in_progress, assigned, pending, unverified }` | stat tiles V1 |
+| `crm.leadVerification.activity.list` | `{ id }` | `VerificationActivity[]` | timeline V18 (or embed in `.get`) |
+
+`VerificationRowDTO`:
+```ts
+{ id, code, name, initials, address, phone, source,
+  assignee: { id, initials, name } | null,
+  status, verification /* sub_status */, createdAt }
+```
+`VerificationDTO`: adds `email`, `notes`, `verifiedAt`, `promotedLeadId`, `activities[]`.
+
+### 6.5 Lead Verification — Commands
+
+| Action | Variables | Returns | Backs |
+|--------|-----------|---------|-------|
+| `crm.leadVerification.verify` | `{ id, notes? }` | `{ verification: VerificationDTO, lead: LeadDTO }` | Verify V9/V11/V19 — **promotes to Lead** |
+| `crm.leadVerification.markUnverified` | `{ id, reason? }` | `VerificationDTO` | Mark Unverified V12 |
+| `crm.leadVerification.assign` | `{ id, assigneeId }` | `VerificationDTO` | Change Assignee V13 |
+| `crm.leadVerification.reassign` | `{ id, assigneeId? }` | `VerificationDTO` | Reassign → In Progress V14 |
+| `crm.leadVerification.moveToPending` | `{ id }` | `VerificationDTO` | Move to Pending V15 |
+| `crm.leadVerification.updateStatus` | `{ id, status, subStatus? }` | `VerificationDTO` | generic status set (covers sub-status changes) |
+| `crm.leadVerification.note.add` | `{ id, text }` | `VerificationDTO` | verification notes (pending edit UI) |
+
+**`crm.leadVerification.verify` behaviour (the critical cross-module command):**
+1. Load verification; guard status is not already `verified`.
+2. Set `status = 'verified'`, `sub_status = 'Verified'`, `verified_at = now()`, persist `notes` if provided.
+3. **Create a `leads` row** (`status = 'new'`) from the verification's contact/address/source, linking `leads.source_verification_id = verification.id` and `verification.promoted_lead_id = lead.id`.
+4. Append activity: `"Verified and pushed to New Leads."` (actor = current user).
+5. Return both records so the UI can refresh both queues.
+6. Idempotent: a second call with the same idempotency key must not create a duplicate Lead.
+
+### 6.6 Shared / reused actions (already exist — reuse, don't rebuild)
+
+| Action | Use in Leads/Verification |
+|--------|---------------------------|
+| `crm.account.me` | `leads.manage` permission gate for both modules |
+| `crm.team.member.search { perPage }` | rep / canvasser / assignee pickers (`REPS`, `V_ASSIGNEES`) |
+| `crm.media.presignUpload { mime, sizeBytes }` → `{ objectKey, uploadUrl }` | site-photo upload (browser PUTs bytes directly) |
+| `crm.media.presignDownload { contentRef }` → `{ url }` | render/download a lead photo |
+
+---
+
+## 7. Validation Rules
+
+### 7.1 `crm.lead.create` / `crm.lead.update`
+
+| Field | Required | Rule |
+|-------|----------|------|
+| name (`firstName`/`lastName`) | **Yes** (at least one non-empty after trim) | matches the only current UI guard: `` `${first} ${last}`.trim() `` must be non-empty → else error `name_required` |
+| `phones[].number` | No | free-form; if present, strip to digits server-side for storage/dedupe (form already does `phone.replace(/\D/g,"")` in registration) |
+| `phones[].type` | with phone | enum `Mobile\|Home\|Work` |
+| `phones` primary | — | at most one `primary: true`; if none set, mark the first as primary |
+| `emails[].address` | No | RFC-5322-ish email format when present |
+| `property.state` | No | 2-letter US state; default `TX` |
+| `property.zip` | No | 5-digit (or ZIP+4) when present |
+| `property.type` | No | one of `PROPERTY_TYPES` (§8.4) |
+| `source` | No | one of `LEAD_SOURCES` (§8.1) |
+| `referralNote` | Conditional | accept only when `source = 'Referral'` (UI shows it only then) |
+| `canvasserId` | Conditional | resolve to a member; UI surfaces the picker only when `source = 'Door Knock'`, but accept whenever provided |
+| `leadType` | No | see §12 enum conflict — accept the UI's `Residential\|Commercial\|Multi-Family` **and** the data model's `Insurance\|Retail`; store raw, do not hard-reject |
+| `workType` | No | one of `WORK_TYPES` |
+| `tradeType` | No | one of `TRADE_TYPES` |
+| `urgency` | No | enum `Standard\|High\|Emergency`; default `Standard` |
+| `insurance.claimStatus` | No | enum `Not Filed\|Filed\|Approved\|Paid\|Denied` |
+| `priority` | No | accept `Low\|Medium\|High` (form) → normalize to `low\|medium\|high`; default `medium` |
+| `assignment.followUp` | No | valid ISO date; may be null/`"—"` |
+| `assignment.assigneeId` | No | resolve to a member or `null` (Unassigned) |
+
+**Business validations:**
+- `code` (`SAL-###`) is server-generated, unique per tenant — never accepted from the client.
+- Duplicate detection (recommended, not in UI): warn (not block) if an active lead exists with the same primary phone **or** same property address within the tenant.
+- All member references (`assigneeId`, `canvasserId`) must belong to the same tenant.
+
+### 7.2 Verification commands
+
+| Command | Rule |
+|---------|------|
+| `verify` | reject if already `verified` (`already_verified`); require the record exists in tenant; create exactly one Lead (idempotent) |
+| `assign` / `reassign` | `assigneeId` must be a tenant member; `assign` moves `pending → assigned` (or updates assignee); `reassign` sets `in_progress` |
+| `markUnverified` | allowed from any non-terminal state; optional `reason` recorded as activity |
+| `moveToPending` | allowed from `assigned` / `in_progress`; clears/keeps assignee per product choice (UI does not specify — keep assignee, set `status=pending`, `sub_status='Pending Review'`) |
+| `updateStatus` | `status ∈ verification_status`; if `subStatus` omitted, default it from the status (§8.6 mapping) |
+| `note.add` | `text` non-empty, trimmed, reasonable max length (e.g. 5 000 chars) |
+
+**Enums must be validated server-side even though the frontend does not enforce them** — the frontend is permissive (free selects), so the backend is the source of truth.
+
+---
+
+## 8. Reference / Enum Data
+
+Exact values, copied from `leads-data.ts` and `verify-data.ts`. Provide these either as DB enums or as a reference-data query (`crm.lead.options` — optional) so the UI selects stay in sync.
+
+### 8.1 `LEAD_SOURCES`
+`Door Knock`, `Referral`, `Storm Chase`, `Mailer / Postcard`, `Sign Call`, `Insurance Agent Referral`, `Repeat Customer`, `Social Media`, `Other`
+
+### 8.2 `WORK_TYPES`
+`Roof Replacement`, `Roof Repair`, `Inspection`, `Gutter Install`
+
+### 8.3 `TRADE_TYPES`
+`Roofing`, `Gutters`, `Siding`, `Windows`
+
+### 8.4 `PROPERTY_TYPES`
+`Single Family`, `Multi Family`, `Commercial`
+*(the Full-form Property step also offers `Residential`, `Commercial`, `Multi-Family`, `Industrial` via `PROPERTY_TYPE_OPTS` — accept the superset; see §12)*
+
+### 8.5 `CLAIM_STATUSES`
+`Not Filed`, `Filed`, `Approved`, `Paid`, `Denied`
+
+### 8.6 Verification statuses → default sub-status label
+
+| `status` | default `sub_status` | other observed sub-status labels |
+|----------|----------------------|----------------------------------|
+| `verified` | `Verified` | — |
+| `in_progress` | `Verifying Identity` | `Reviewing Insurance`, `Confirming Ownership`, `Confirming Damage` |
+| `assigned` | `Assigned` | — |
+| `pending` | `Pending Review` | — |
+| `unverified` | `Unverified` | — |
+
+### 8.7 Verification sources (`V_SOURCES`)
+`Door Knock`, `Web Form`, `Storm Canvass`, `Referral`, `Call-In`
+*(note: different set from Lead sources §8.1 — keep them as separate reference lists)*
+
+### 8.8 Lead statuses / priorities / urgency
+- `lead_status`: `new`, `contacted`, `appointed`, `closed`
+- `lead_priority`: `high`, `medium`, `low` (create form emits title-case `Low`/`Medium`/`High`)
+- `lead_urgency`: `Standard`, `High`, `Emergency`
+- `phone_type`: `Mobile`, `Home`, `Work`
+- `lead_type`: **conflicting** — `Insurance`/`Retail` (data) vs `Residential`/`Commercial`/`Multi-Family` (form). See §12.
+
+### 8.9 Seed members (reps / canvassers / verification specialists)
+
+Reps (`REPS`, ids are real member codes): `LUP-1040 Cody Tatum`, `LUP-1041 Hannah Reyes`, `LUP-1042 Travis Boone`, `LUP-1043 Shelby Greer`, `LUP-1044 Dalton Pruitt`.
+Verification specialists (`V_ASSIGNEES`): `Wade Hollis`, `Darlene Brooks`, `Roy Schaefer`.
+
+---
+
+## 9. Backend Services
+
+Break the implementation into services mirroring the existing `be-crm` module layout (one bounded context per data-door namespace).
+
+| Service | Namespace | Responsibilities |
+|---------|-----------|------------------|
+| **LeadService** | `crm.lead.*` | CRUD + search + stats for leads; owns phones/emails child collections; code generation (`SAL-###`); status transitions; assignment. |
+| **LeadVerificationService** | `crm.leadVerification.*` | Verification queue search/stats; status & sub-status transitions; assign/reassign/pending; note management; code generation (`LD-V-###`). |
+| **LeadPromotionService** (or a method on LeadVerificationService) | part of `crm.leadVerification.verify` | The cross-module promotion: verified verification → new Lead, bidirectional linking, idempotency. Owns the transaction that touches both `leads` and `lead_verifications`. |
+| **LeadActivityService** | activities/history | Append + list `lead_verification_activities` and `lead_status_history`; generates the timeline the UI reads (replaces the client-side `buildActivity` synthesis). |
+| **LeadAssignmentService** | assignment concerns | Resolve member ids for `assignedTo` / `canvasser` / `assignee`; validate tenant membership; (future) round-robin. Can be a thin helper over the existing member/team module rather than a standalone service. |
+| **MediaService (existing — reuse)** | `crm.media.*` | Presign upload/download for site photos. **Do not reimplement** — see media-api.ts. |
+| **Account/AccessService (existing — reuse)** | `crm.account.me` | `leads.manage` authorization for every action here. |
+| **NotificationService** — `[Backend Pending]` | — | The frontend today only toasts locally. No server notification is required for parity, but promotion/verify events are natural triggers if/when the Inbox projection (`crm.inbox.*`) should surface them. Do not build unless requested. |
+
+**Layering convention (match existing modules):** Controller/handler (validates action variables, applies auth) → Service (business rules, transitions) → Repository (tenant-scoped data access). DTO projections are shaped for the UI (list vs detail) exactly as the current modules return purpose-built DTOs (e.g. `MemberDTO`, `MailThread`).
+
+---
+
+## 10. Error Handling
+
+Errors propagate to the UI as a thrown `Error`; the SDK hooks expose `error.message` (see `q.error?.message ?? null` throughout the API layer). Permission failures use the SDK's `PermissionError` (OPA). Provide a **stable machine `code` + human `message`**; the UI currently shows the message in a toast/inline state.
+
+| Scenario | When | Suggested code | HTTP-equivalent | UI effect |
+|----------|------|----------------|-----------------|-----------|
+| Unauthenticated | no/expired session | `unauthenticated` | 401 | `auth-gate` redirects to `/portal/login` |
+| Forbidden | member lacks `leads.manage` | `forbidden` / `PermissionError` | 403 | nav item hidden; action rejected |
+| Validation — name required | create with empty name | `name_required` | 422 | matches current client guard toast |
+| Validation — bad enum | invalid status/source/type | `invalid_value` | 422 | inline/toast |
+| Validation — bad email/zip/phone | format fails | `invalid_format` | 422 | |
+| Not found | unknown `id` / wrong tenant | `not_found` | 404 | toast; row disappears on refetch |
+| Conflict — already verified | `verify` on a verified record | `already_verified` | 409 | toast |
+| Conflict — invalid transition | disallowed status change | `invalid_state_transition` | 409 | toast |
+| Conflict — duplicate lead | dup phone/address (if enforced) | `duplicate_lead` | 409 | warn (prefer soft-warn, not block) |
+| Conflict — duplicate code | code collision (should be internal) | `duplicate_code` | 409 | internal retry |
+| Assignee invalid | assignee not a tenant member | `invalid_assignee` | 422 | toast |
+| Upload too large | photo > 25 MB | `file_too_large` | 413 | matches media-api guard ("max 25 MB") |
+| Upload failed | presigned PUT fails | `upload_failed` | 502 | toast |
+| Rate / idempotency replay | duplicate command key | (return original result) | 200 | no-op, safe |
+| Server error | unexpected | `internal_error` | 500 | generic toast |
+
+**Error envelope (recommended, consistent with a thrown Error carrying structured data):**
+```json
+{ "error": { "code": "already_verified",
+             "message": "This lead has already been verified.",
+             "details": { "verificationId": "lv_1…" } } }
+```
+
+---
+
+## 11. Existing Backend Integration (mandatory conventions)
+
+The new backend **must** follow the patterns already used by Team, Mail, Inbox, Messenger, Media and Account. Never invent a different architecture.
+
+### 11.1 Data door, not REST
+The frontend never calls REST endpoints. It calls **actions** through the AppShell SDK:
+```ts
+// read
+const q = useQuery<Page<LeadCardDTO>>("crm.lead.search", { status, query, page, perPage });
+// write
+await sdk.command("crm.leadVerification.verify", { id, notes });
+```
+`DataClient.query(action, variables)` and `DataClient.command(action, variables)` call the **Shell BFF's cookie-authed `/data` proxy**; the BFF attaches the session token server-side and forwards to `be-crm`. Apps never hold a token, set an `Authorization` header, or know the domain endpoint.
+
+### 11.2 Transport path
+```
+browser (SDK) ──► Next rewrite  /shell/:path*  ──►  BFF (BFF_ORIGIN, default http://localhost:4000)/api/:path*  ──►  be-crm domain API
+```
+(from `next.config.ts` `rewrites()` and `providers.tsx` `bffBaseUrl = "/shell"`). The session is an **HttpOnly cookie**; that is why the same-origin `/shell` prefix is used (never `/api`, to avoid clobbering the local `/api/geo` route).
+
+### 11.3 Authentication & authorization
+- Auth is Supabase-backed via the SDK (`appId: "crm-web"`); the BFF exchanges it for a domain session. When `NEXT_PUBLIC_SUPABASE_URL` is unset the app runs in **mock mode** (see §11.6).
+- Authorization is **permission-based** via `crm.account.me` → `{ registered, isMember, roleSlugs, permissions, isSuperadmin }`. Both modules require **`leads.manage`** (already declared in `access.ts` `ALL_CRM_PERMISSIONS` and mapped in `sidebar.tsx` `NAV_PERMISSION`). Enforce it on **every** `crm.lead.*` and `crm.leadVerification.*` action — the frontend gate is UX-only ("be-crm still enforces every action").
+- OPA/IIOS may additionally gate row visibility; keep everything **tenant-scoped**.
+
+### 11.4 Response & naming conventions
+- **Actions:** `crm.<entity>.<verb>` dot-namespaced; segments camelCase (e.g. `member.setRoles`, `invitation.create`, `inbox.transition`, `mail.reply`). Use `search`/`list` for reads, imperative verbs for writes.
+- **DTOs:** server returns UI-shaped DTOs (list vs detail projections). Fields are **camelCase**. Timestamps are **ISO-8601 strings**; the client formats relative/pretty (`relTime`). Nullable fields are `null`, not omitted, where the UI reads them.
+- **Collections:** `{ items: T[], meta: { total, page, perPage } }` for paginated sets (Team pattern) — used here for `search`. Bare arrays are acceptable for small always-full lists (Mail/Inbox pattern) but Leads/Verification use the envelope for totals.
+- **Commands** are idempotent (idempotency key auto-attached); write-then-refetch is the client norm (`cmd(...)` then `refetch()`), so commands should return the updated entity to allow optimistic UI too.
+
+### 11.5 Media / attachments (reuse exactly)
+Site photos must use the existing two-step flow (from `media-api.ts`):
+1. `sdk.command("crm.media.presignUpload", { mime, sizeBytes })` → `{ objectKey, uploadUrl }`.
+2. Browser `PUT`s the file bytes **directly** to `uploadUrl` (IIOS storage) — be-crm only mints the URL.
+3. Store `{ contentRef: objectKey, mimeType, sizeBytes, filename }` on the lead via `crm.lead.attachment.add`.
+4. Display via `crm.media.presignDownload { contentRef }` → `{ url }`.
+Enforce the **25 MB** cap (`MAX_ATTACHMENT_BYTES = 26_214_400`).
+
+### 11.6 Mock-mode parity (important)
+Every existing data-layer file (`team-api`, `mail-api`, `inbox-api`, `messenger-api`, `access`) chooses **mock vs live at module load** via `isShellConfigured()` (`Boolean(process.env.NEXT_PUBLIC_SUPABASE_URL)`). When you wire Leads/Verification to the live door, follow the same shape: create `src/lib/leads-api.ts` and `src/lib/verify-api.ts` exposing one hook per module that returns `{ live, loading, error, …data, …commands, refetch }`, serving the current mock (`LEADS`, `V_LEADS`) when the Shell isn't configured and the live `crm.lead.*` / `crm.leadVerification.*` actions when it is. This keeps the demo working and matches the established convention. *(Frontend wiring task — noted for completeness; the backend itself only needs to implement the live actions.)*
+
+### 11.7 DTO / repository / service pattern summary
+- **DTO:** dedicated interfaces per projection (`LeadCardDTO`, `LeadDTO`, `VerificationRowDTO`, `VerificationDTO`) — do not leak raw table rows.
+- **Repository:** always parameterize by `tenantId`; never a query without tenant scope.
+- **Service:** owns transitions, code generation, promotion transaction, activity emission.
+- **Controller/handler:** maps the action name + variables to a service call, validates, applies auth. One handler per action, matching the `crm.<entity>.<verb>` registry the BFF forwards to.
+
+---
+
+## 12. Gaps, Discrepancies & Backend-Pending Items
+
+Explicitly flagged so the backend developer is not surprised.
+
+1. **Everything is mock today.** No `crm.lead.*` or `crm.leadVerification.*` action is called anywhere yet. All actions in §6 are new. Frontend wiring (§11.6) is a separate follow-up task.
+
+2. **`leadType` enum conflict.** `leads-data.ts` defines `LEAD_TYPES = ["Insurance","Retail"]` and mock rows use `"Insurance"`, but the Full-form Job step's `LEAD_TYPE_OPTS = ["Residential","Commercial","Multi-Family"]`. **Recommendation:** store `lead_type` as free text (do not hard-reject), accept both sets, and raise with product which taxonomy is canonical. **[Needs product decision]**
+
+3. **`propertyType` superset.** `PROPERTY_TYPES` (data) = `Single Family / Multi Family / Commercial`; the form offers `Residential / Commercial / Multi-Family / Industrial`. Accept the union.
+
+4. **Priority casing.** Create form emits `Low/Medium/High`; list/detail use `low/medium/high`. **Normalize to lowercase** on write; return lowercase.
+
+5. **Assignee/canvasser/creator are free-text names in the mock** (`"Jesus Gonzales"`, `"Cody Tatum"`, `"Wade Hollis"`). The backend must model these as **member FKs** and resolve display names in DTOs. The verification specialists (`Wade Hollis`, `Darlene Brooks`, `Roy Schaefer`) are not in the `REPS` list — they must exist as members/records too. **[Seed/link required]**
+
+6. **Site photos are placeholders.** `addPhoto()` stores label strings (`"Photo 1"`). Real upload via the media presign flow (§11.5) is **backend-pending** but fully specified.
+
+7. **Detail actions are inert.** Leads "Call / Email / Update Status" and Verification "Call / Verify" footer buttons have **no handlers**. `updateStatus`, `verify` etc. are specified in §6 but the buttons must be wired (frontend task).
+
+8. **Activity timeline is client-synthesized.** `buildActivity()` fabricates timeline entries when a verification lacks `activity[]`. The backend should persist **real** activities (`lead_verification_activities`) and the client should stop synthesizing once live.
+
+9. **No pagination controls in the UI**, yet `TOTAL_LEADS = 35` (only 5 loaded) and the verification footer shows "X of Y". Implement server pagination + `meta.total`; pick a sane default `perPage`. A pager UI is a future frontend task.
+
+10. **No edit / delete / archive / bulk / tags-editor / sort UI.** Endpoints for update/archive/delete are included as **optional/pending** — implement `crm.lead.update` (needed for status/assignment) but treat `archive`/`delete`/bulk as **do-not-build-unless-requested**.
+
+11. **Verification records are never created from the UI** (like the Inbox, they "arrive"). Provide an intake ingestion path (webhook / internal command) **outside** these two module screens — its exact source is not defined by the frontend. **[Needs definition]**
+
+12. **Single-line vs structured address.** Leads store structured address (address/city/state/zip); verifications store a single `address` string (`"2814 Ravenswood Dr, Plano, TX 75023"`). When promoting a verification → lead, parse or carry the single string into `property_address` (best-effort parse; keep the raw string too). **[Parsing rule needed]**
+
+---
+
+*End of document.*

package.json

@@ -9,7 +9,8 @@
     "lint": "eslint"
   },
   "dependencies": {
-    "@abe-kap/appshell-sdk": "^0.2.3",
+    "@abe-kap/appshell-sdk": "^0.2.6",
+    "@insignia/iios-kernel-client": "^0.1.4",
     "clsx": "^2.1.1",
     "lucide-react": "^1.21.0",
     "next": "16.2.9",

src/app/(legal)/layout.tsx

@@ -0,0 +1,45 @@
+import type { Metadata } from "next";
+import Link from "next/link";
+import "@/components/portal/portal.css";
+import "./legal.css";
+import { COMPANY } from "./legal-config";
+
+export const metadata: Metadata = {
+  title: `${COMPANY} — Legal & SMS`,
+  description: `${COMPANY} SMS program opt-in, Privacy Policy and Terms of Service.`,
+};
+
+export default function LegalLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <>
+      <link rel="preconnect" href="https://fonts.googleapis.com" />
+      <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />
+      <link
+        href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap"
+        rel="stylesheet"
+      />
+      <div className="legal-root">
+        <header className="legal-bar">
+          <Link href="/portal/login" aria-label={`${COMPANY} home`}>
+            {/* eslint-disable-next-line @next/next/no-img-element */}
+            <img src="/image/logo.png" alt={`${COMPANY} logo`} />
+          </Link>
+          <nav>
+            <Link href="/sms-opt-in">SMS Alerts</Link>
+            <Link href="/privacy">Privacy</Link>
+            <Link href="/terms">Terms</Link>
+          </nav>
+        </header>
+        {children}
+        <footer className="legal-foot">
+          <div>© {new Date().getFullYear()} {COMPANY}. All rights reserved.</div>
+          <div style={{ marginTop: 8 }}>
+            <Link href="/sms-opt-in">SMS Alerts</Link>
+            <Link href="/privacy">Privacy Policy</Link>
+            <Link href="/terms">Terms of Service</Link>
+          </div>
+        </footer>
+      </div>
+    </>
+  );
+}

src/app/(legal)/legal-config.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared business details for the public compliance pages (SMS opt-in, Privacy,
+ * Terms). Edit these in one place to keep every page and disclosure consistent.
+ * Replace SMS_SENDER with your live Twilio number once the campaign is approved.
+ */
+export const COMPANY = "LynkedUp Pro";
+export const SUPPORT_EMAIL = "support@lynkeduppro.com";
+export const PRIVACY_EMAIL = "privacy@lynkeduppro.com";
+export const SMS_SENDER = "(555) 010-0100"; // TODO: replace with your Twilio A2P number
+export const SITE_URL = "https://lynkeduppro-crmnew.vercel.app";
+export const LAST_UPDATED = "July 13, 2026";

src/app/(legal)/legal.css

@@ -0,0 +1,125 @@
+/* Public compliance pages (SMS opt-in, Privacy, Terms). Reuses the portal design
+   tokens (--bg, --text, --primary…) from portal.css for a consistent look, with
+   prose styling tuned for long-form legal copy. */
+
+.legal-root {
+  min-height: 100vh;
+  background: var(--bg, #0b0c11);
+  color: var(--text, #f3f4f8);
+  font-family: var(--font-ui, "Inter", system-ui, sans-serif);
+  display: flex;
+  flex-direction: column;
+}
+
+.legal-bar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+  padding: 18px 24px;
+  border-bottom: 1px solid var(--line, rgba(255, 255, 255, 0.09));
+  position: sticky;
+  top: 0;
+  background: color-mix(in srgb, var(--bg, #0b0c11) 88%, transparent);
+  backdrop-filter: blur(10px);
+  z-index: 5;
+}
+.legal-bar img { height: 30px; width: auto; }
+.legal-bar nav { display: flex; gap: 20px; flex-wrap: wrap; }
+.legal-bar nav a {
+  color: var(--muted, #a3a8b5);
+  text-decoration: none;
+  font-size: 14px;
+  font-weight: 600;
+}
+.legal-bar nav a:hover { color: var(--text, #f3f4f8); }
+.legal-bar nav a.on { color: var(--primary-2, #fb923c); }
+
+.legal-wrap { flex: 1; width: 100%; max-width: 820px; margin: 0 auto; padding: 44px 24px 80px; }
+
+.legal-wrap h1 { font-size: 32px; font-weight: 800; letter-spacing: -0.02em; margin: 0 0 6px; }
+.legal-wrap .updated { color: var(--faint, #6c7280); font-size: 13px; margin: 0 0 30px; }
+.legal-wrap h2 {
+  font-size: 19px; font-weight: 700; margin: 34px 0 10px;
+  padding-top: 20px; border-top: 1px solid var(--line, rgba(255, 255, 255, 0.09));
+}
+.legal-wrap h2:first-of-type { border-top: none; padding-top: 0; }
+.legal-wrap p, .legal-wrap li { color: var(--muted, #a3a8b5); font-size: 15px; line-height: 1.7; }
+.legal-wrap p { margin: 0 0 12px; }
+.legal-wrap ul { margin: 0 0 12px; padding-left: 20px; }
+.legal-wrap li { margin: 0 0 6px; }
+.legal-wrap strong { color: var(--text, #f3f4f8); font-weight: 600; }
+.legal-wrap a { color: var(--primary-2, #fb923c); }
+
+/* Callout box for the mandatory SMS disclosures — makes them easy for a reviewer to find. */
+.legal-callout {
+  border: 1px solid var(--line-2, rgba(255, 255, 255, 0.15));
+  background: var(--surface, rgba(255, 255, 255, 0.04));
+  border-radius: var(--radius-sm, 13px);
+  padding: 16px 18px;
+  margin: 8px 0 18px;
+}
+.legal-callout p:last-child { margin-bottom: 0; }
+
+.legal-foot {
+  border-top: 1px solid var(--line, rgba(255, 255, 255, 0.09));
+  padding: 22px 24px;
+  text-align: center;
+  color: var(--faint, #6c7280);
+  font-size: 13px;
+}
+.legal-foot a { color: var(--muted, #a3a8b5); text-decoration: none; margin: 0 10px; }
+.legal-foot a:hover { color: var(--text, #f3f4f8); }
+
+/* SMS opt-in form */
+.optin-card {
+  border: 1px solid var(--line, rgba(255, 255, 255, 0.09));
+  background: var(--surface, rgba(255, 255, 255, 0.04));
+  border-radius: var(--radius-sm, 13px);
+  padding: 22px;
+  margin-top: 22px;
+}
+.optin-field { margin-bottom: 16px; }
+.optin-field label { display: block; font-weight: 600; font-size: 14px; margin-bottom: 7px; color: var(--text, #f3f4f8); }
+.optin-input {
+  width: 100%;
+  background: var(--ink, #121319);
+  border: 1px solid var(--line-2, rgba(255, 255, 255, 0.15));
+  border-radius: 10px;
+  padding: 13px 14px;
+  color: var(--text, #f3f4f8);
+  font-size: 15px;
+  font-family: inherit;
+}
+.optin-input:focus { outline: 2px solid var(--primary, #f97316); outline-offset: 1px; border-color: transparent; }
+
+.optin-consent { display: flex; gap: 11px; align-items: flex-start; margin: 6px 0 4px; }
+.optin-consent input { margin-top: 3px; width: 18px; height: 18px; flex: none; accent-color: var(--primary, #f97316); }
+.optin-consent label { font-size: 13.5px; line-height: 1.6; color: var(--muted, #a3a8b5); }
+
+.optin-submit {
+  width: 100%;
+  margin-top: 18px;
+  background: var(--primary, #f97316);
+  color: #fff;
+  border: none;
+  border-radius: 10px;
+  padding: 14px;
+  font-size: 15px;
+  font-weight: 700;
+  cursor: pointer;
+  font-family: inherit;
+}
+.optin-submit:disabled { opacity: 0.5; cursor: not-allowed; }
+
+.optin-fine { font-size: 12.5px; color: var(--faint, #6c7280); line-height: 1.6; margin-top: 14px; }
+.optin-done {
+  border: 1px solid color-mix(in srgb, var(--green, #34d399) 45%, transparent);
+  background: color-mix(in srgb, var(--green, #34d399) 12%, transparent);
+  color: #a7f3d0;
+  border-radius: var(--radius-sm, 13px);
+  padding: 18px 20px;
+  margin-top: 22px;
+  font-size: 14.5px;
+  line-height: 1.6;
+}

src/app/(legal)/privacy/page.tsx

@@ -0,0 +1,98 @@
+import type { Metadata } from "next";
+import Link from "next/link";
+import { COMPANY, SUPPORT_EMAIL, PRIVACY_EMAIL, LAST_UPDATED } from "../legal-config";
+
+export const metadata: Metadata = {
+  title: `Privacy Policy — ${COMPANY}`,
+  description: `How ${COMPANY} collects, uses, and protects your information, including SMS/text messaging.`,
+};
+
+export default function PrivacyPage() {
+  return (
+    <main className="legal-wrap">
+      <h1>Privacy Policy</h1>
+      <p className="updated">Last updated: {LAST_UPDATED}</p>
+
+      <p>
+        This Privacy Policy explains how {COMPANY} (&quot;{COMPANY},&quot; &quot;we,&quot;
+        &quot;us&quot;) collects, uses, and protects your information when you use our
+        website, portal, and services, including our text message (SMS) program.
+      </p>
+
+      <h2>Information we collect</h2>
+      <ul>
+        <li><strong>Account information</strong> — name, email address, and mobile phone number you provide when registering or signing in.</li>
+        <li><strong>Property and service information</strong> — details you share to request roof inspections, estimates, and reports.</li>
+        <li><strong>Usage and device information</strong> — log data, device and browser type, and similar technical information collected automatically.</li>
+      </ul>
+
+      <h2>How we use your information</h2>
+      <ul>
+        <li>To create and secure your account, including sending one-time verification codes (OTP).</li>
+        <li>To provide, maintain, and improve our services.</li>
+        <li>To communicate with you about your account, appointments, estimates, and support requests.</li>
+        <li>To comply with legal obligations and protect against fraud and abuse.</li>
+      </ul>
+
+      <h2>SMS / text messaging</h2>
+      <div className="legal-callout">
+        <p>
+          <strong>
+            We do not sell, rent, or share your mobile phone number, or your SMS opt-in
+            consent, with any third parties or affiliates for their marketing or
+            promotional purposes.
+          </strong>
+        </p>
+        <p>
+          Mobile information collected for the purpose of sending text messages is used
+          only to deliver the messages you opted into and is not shared with third parties
+          for marketing. We may share your number only with service providers (such as our
+          messaging platform) strictly to deliver the messages, and as required by law.
+        </p>
+        <p>
+          <strong>Message frequency varies</strong> — verification codes are sent when you
+          request them (for example, each time you sign in or register), and account or
+          service notifications are occasional. <strong>Message and data rates may
+          apply</strong>, depending on your mobile carrier and plan.
+        </p>
+        <p>
+          You can opt out at any time by replying <strong>STOP</strong> to any message, and
+          get help by replying <strong>HELP</strong>. See our{" "}
+          <Link href="/terms">Terms of Service</Link> and the{" "}
+          <Link href="/sms-opt-in">SMS opt-in page</Link> for full program details.
+        </p>
+      </div>
+
+      <h2>How we share information</h2>
+      <p>
+        We do not sell your personal information. We share information only with service
+        providers who help us operate the service (for example, cloud hosting,
+        authentication, and messaging providers), and when required by law or to protect
+        our rights. As stated above, mobile phone numbers and SMS consent are never shared
+        with third parties or affiliates for marketing purposes.
+      </p>
+
+      <h2>Data retention and security</h2>
+      <p>
+        We retain personal information for as long as your account is active or as needed to
+        provide the service and meet legal obligations. We use administrative, technical,
+        and physical safeguards designed to protect your information; no method of
+        transmission or storage is completely secure.
+      </p>
+
+      <h2>Your choices and rights</h2>
+      <p>
+        You may access or update your account information at any time, opt out of SMS by
+        replying STOP, and request deletion of your account by contacting us. Depending on
+        your location, you may have additional rights under applicable privacy laws.
+      </p>
+
+      <h2>Contact us</h2>
+      <p>
+        Questions about this Privacy Policy? Email us at{" "}
+        <a href={`mailto:${PRIVACY_EMAIL}`}>{PRIVACY_EMAIL}</a> or{" "}
+        <a href={`mailto:${SUPPORT_EMAIL}`}>{SUPPORT_EMAIL}</a>.
+      </p>
+    </main>
+  );
+}

src/app/(legal)/sms-opt-in/page.tsx

@@ -0,0 +1,125 @@
+"use client";
+
+import { useState } from "react";
+import Link from "next/link";
+import { COMPANY, SMS_SENDER, SUPPORT_EMAIL } from "../legal-config";
+
+/**
+ * Public SMS opt-in web form for A2P 10DLC campaign verification. Contains every
+ * element Twilio/CTIA require: phone field, an un-pre-checked consent checkbox, a
+ * description of the messages, frequency, rates disclaimer, HELP/STOP instructions,
+ * and links to the Terms and Privacy Policy.
+ */
+export default function SmsOptInPage() {
+  const [phone, setPhone] = useState("");
+  const [consent, setConsent] = useState(false);
+  const [done, setDone] = useState(false);
+
+  const digits = phone.replace(/\D/g, "");
+  const valid = digits.length >= 10 && consent;
+
+  function onSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    if (!valid) return;
+    // Records the opt-in. Consent + timestamp should be persisted server-side for your
+    // records; this confirmation is the user-facing acknowledgement.
+    setDone(true);
+  }
+
+  return (
+    <main className="legal-wrap">
+      <h1>{COMPANY} SMS Alerts</h1>
+      <p className="updated">Sign up to receive text messages from {COMPANY}.</p>
+
+      <p>
+        At {COMPANY}, we send text messages to help you use and secure your account. By
+        opting in below you&apos;ll receive <strong>account and service messages</strong>,
+        including:
+      </p>
+      <ul>
+        <li>One-time verification codes (OTP) when you sign in or register</li>
+        <li>Sign-in and security alerts</li>
+        <li>Roof inspection scheduling and status updates</li>
+        <li>Estimate and report notifications</li>
+      </ul>
+
+      {done ? (
+        <div className="optin-done" role="status">
+          <strong>You&apos;re signed up.</strong>{" "}We&apos;ll text account and service
+          messages to {phone}. Reply <strong>STOP</strong>{" "}at any time to unsubscribe,
+          or <strong>HELP</strong>{" "}for help.
+        </div>
+      ) : (
+        <form className="optin-card" onSubmit={onSubmit}>
+          <div className="optin-field">
+            <label htmlFor="sms-phone">Mobile phone number</label>
+            <input
+              id="sms-phone"
+              className="optin-input"
+              type="tel"
+              inputMode="tel"
+              autoComplete="tel"
+              placeholder="+1 (555) 010-0100"
+              value={phone}
+              onChange={(e) => setPhone(e.target.value)}
+              required
+            />
+          </div>
+
+          {/* Consent checkbox — MUST NOT be pre-checked (starts false). */}
+          <div className="optin-consent">
+            <input
+              id="sms-consent"
+              type="checkbox"
+              checked={consent}
+              onChange={(e) => setConsent(e.target.checked)}
+            />
+            <label htmlFor="sms-consent">
+              I agree to receive account and service text messages (including one-time
+              verification codes) from {COMPANY} at the number provided. Consent is not a
+              condition of purchase. Message frequency varies. Message and data rates may
+              apply. Reply HELP for help and STOP to unsubscribe. See our{" "}
+              <Link href="/terms">Terms of Service</Link> and{" "}
+              <Link href="/privacy">Privacy Policy</Link>.
+            </label>
+          </div>
+
+          <button className="optin-submit" type="submit" disabled={!valid}>
+            Yes, sign me up!
+          </button>
+
+          <p className="optin-fine">
+            Message frequency varies. Message and data rates may apply. Reply{" "}
+            <strong>HELP</strong>{" "}for help or <strong>STOP</strong>{" "}to cancel at any
+            time. Carriers are not liable for delayed or undelivered messages.
+          </p>
+        </form>
+      )}
+
+      <h2>Program details</h2>
+      <ul>
+        <li><strong>Program name:</strong> {COMPANY} Account &amp; Service Alerts</li>
+        <li><strong>Message types:</strong> verification codes (OTP), security alerts, appointment and inspection updates, estimate notifications</li>
+        <li><strong>Message frequency:</strong> varies — codes are sent when you request them (e.g. each sign-in or registration); notifications are occasional</li>
+        <li><strong>Cost:</strong> Message and data rates may apply, per your mobile plan</li>
+      </ul>
+
+      <h2>How to opt out or get help</h2>
+      <p>
+        Reply <strong>STOP</strong>{" "}to any message to unsubscribe — you&apos;ll get one
+        confirmation and no further texts. Reply <strong>HELP</strong>{" "}for help, or
+        contact us at <a href={`mailto:${SUPPORT_EMAIL}`}>{SUPPORT_EMAIL}</a>
+        {SMS_SENDER ? <> or {SMS_SENDER}</> : null}. Messages are sent from {COMPANY}.
+      </p>
+
+      <h2>Your privacy</h2>
+      <p>
+        <strong>
+          We do not sell, rent, or share your mobile phone number or your SMS opt-in
+          consent with any third parties or affiliates for their marketing purposes.
+        </strong>{" "}
+        See our <Link href="/privacy">Privacy Policy</Link>{" "}for full details.
+      </p>
+    </main>
+  );
+}

src/app/(legal)/terms/page.tsx

@@ -0,0 +1,85 @@
+import type { Metadata } from "next";
+import Link from "next/link";
+import { COMPANY, SUPPORT_EMAIL, LAST_UPDATED } from "../legal-config";
+
+export const metadata: Metadata = {
+  title: `Terms of Service — ${COMPANY}`,
+  description: `The terms governing your use of ${COMPANY}, including the SMS/text messaging program.`,
+};
+
+export default function TermsPage() {
+  return (
+    <main className="legal-wrap">
+      <h1>Terms of Service</h1>
+      <p className="updated">Last updated: {LAST_UPDATED}</p>
+
+      <p>
+        These Terms of Service (&quot;Terms&quot;) govern your access to and use of the {COMPANY}{" "}
+        website, portal, and services (the &quot;Service&quot;). By using the
+        Service you agree to these Terms.
+      </p>
+
+      <h2>Use of the Service</h2>
+      <p>
+        You must provide accurate information, keep your credentials secure, and use the
+        Service only for lawful purposes and in accordance with these Terms. You are
+        responsible for activity that occurs under your account.
+      </p>
+
+      <h2>Accounts and verification</h2>
+      <p>
+        To protect your account we may verify your identity, including by sending one-time
+        codes to your email or mobile number. You agree to receive these verification
+        messages as part of using the Service.
+      </p>
+
+      <h2>SMS / text messaging program</h2>
+      <div className="legal-callout">
+        <p>
+          By opting in on our <Link href="/sms-opt-in">SMS opt-in page</Link> or by
+          providing your mobile number and agreeing to receive texts, you consent to
+          receive <strong>account and service text messages</strong> from {COMPANY},
+          including one-time verification codes (OTP), security alerts, appointment and
+          inspection updates, and estimate notifications.
+        </p>
+        <p>
+          <strong>Message frequency varies.</strong> <strong>Message and data rates may
+          apply.</strong> Reply <strong>HELP</strong> for help or <strong>STOP</strong> to
+          unsubscribe at any time; after you send STOP we will send one confirmation and no
+          further messages. Carriers are not liable for delayed or undelivered messages.
+        </p>
+        <p>
+          We do not sell, rent, or share your mobile number or SMS consent with third
+          parties or affiliates for marketing. See our{" "}
+          <Link href="/privacy">Privacy Policy</Link> for details.
+        </p>
+      </div>
+
+      <h2>Acceptable use</h2>
+      <p>
+        You may not misuse the Service, attempt to access accounts or data you are not
+        authorized to access, interfere with the Service&apos;s operation, or use it to
+        send unlawful, harmful, or infringing content.
+      </p>
+
+      <h2>Disclaimers and limitation of liability</h2>
+      <p>
+        The Service is provided &quot;as is&quot; without warranties of any kind. To the
+        fullest extent permitted by law, {COMPANY} is not liable for any indirect,
+        incidental, or consequential damages arising from your use of the Service.
+      </p>
+
+      <h2>Changes to these Terms</h2>
+      <p>
+        We may update these Terms from time to time. Continued use of the Service after
+        changes take effect constitutes acceptance of the updated Terms.
+      </p>
+
+      <h2>Contact us</h2>
+      <p>
+        Questions about these Terms? Email us at{" "}
+        <a href={`mailto:${SUPPORT_EMAIL}`}>{SUPPORT_EMAIL}</a>.
+      </p>
+    </main>
+  );
+}

src/app/api/invite/lookup/route.ts

@@ -0,0 +1,28 @@
+import { NextResponse } from "next/server";
+
+// Server-side proxy to be-crm's public invitation lookup, so the invite landing page
+// can learn the invited email + roles and whether an account exists — before the
+// invitee has a session. Server-to-server avoids CORS. No secrets involved (the token
+// is the only credential, and it was emailed to the invitee).
+
+export const runtime = "nodejs";
+
+const CRM_BASE_URL = (process.env.CRM_BASE_URL ?? "https://crm.lynkedup.cloud").replace(/\/$/, "");
+
+export async function GET(request: Request) {
+  const token = new URL(request.url).searchParams.get("token") ?? "";
+  if (token.length < 16 || token.length > 256) {
+    return NextResponse.json({ ok: false, status: "invalid" }, { status: 400 });
+  }
+  try {
+    const res = await fetch(`${CRM_BASE_URL}/public/invitations/lookup?token=${encodeURIComponent(token)}`, {
+      headers: { Accept: "application/json" },
+      cache: "no-store",
+    });
+    if (!res.ok) return NextResponse.json({ ok: false, status: "unavailable" }, { status: 502 });
+    const data = await res.json();
+    return NextResponse.json(data);
+  } catch {
+    return NextResponse.json({ ok: false, status: "unavailable" }, { status: 502 });
+  }
+}

src/app/dashboard/dashboard.css

@@ -437,7 +437,7 @@
   .dash-root .ds-modal-ic { width: 38px; height: 38px; border-radius: 11px; flex: 0 0 auto; display: grid; place-items: center; color: var(--orange); background: color-mix(in srgb, var(--orange) 14%, transparent); }
   .dash-root .ds-modal-head h3 { font-size: 16px; font-weight: 700; }
   .dash-root .ds-modal-head p { font-size: 12.5px; color: var(--muted); margin-top: 3px; }
-  .dash-root .ds-modal-body { padding: 18px 20px; overflow-y: auto; }
+  .dash-root .ds-modal-body { padding: 18px 20px; overflow-y: auto; flex: 1 1 auto; min-height: 0; }
   .dash-root .ds-modal-foot { display: flex; justify-content: flex-end; gap: 10px; padding: 14px 20px; border-top: 1px solid var(--border); }
   
   /* ---- Toasts ---- */
@@ -1141,3 +1141,246 @@
     .dash-root .ai-view { height: calc(100vh - 150px); }
   }
 
+  /* ========================================================== */
+  /* Leads — pipeline board + rich detail popup                 */
+  /* ========================================================== */
+
+  /* ---- stat strip ---- */
+  .dash-root .leads-stats { display: grid; grid-template-columns: repeat(5, 1fr); gap: 12px; margin-bottom: 18px; }
+  .dash-root .leads-stat { display: flex; align-items: center; gap: 12px; padding: 14px 16px; border-radius: 16px; border: 1px solid var(--border); background: var(--card-grad); box-shadow: var(--card-hi); position: relative; overflow: hidden; }
+  .dash-root .leads-stat::before { content: ""; position: absolute; left: 0; top: 0; bottom: 0; width: 3px; background: var(--orange); }
+  .dash-root .leads-stat.tone-blue::before { background: var(--blue); }
+  .dash-root .leads-stat.tone-purple::before { background: var(--purple); }
+  .dash-root .leads-stat.tone-green::before { background: var(--green); }
+  .dash-root .leads-stat.tone-orange::before { background: var(--orange); }
+  .dash-root .leads-stat-ic { width: 38px; height: 38px; border-radius: 11px; display: grid; place-items: center; background: color-mix(in srgb, var(--orange) 14%, transparent); color: var(--orange); flex: 0 0 auto; }
+  .dash-root .leads-stat.tone-blue .leads-stat-ic { background: color-mix(in srgb, var(--blue) 16%, transparent); color: #6f9bff; }
+  .dash-root .leads-stat.tone-purple .leads-stat-ic { background: color-mix(in srgb, var(--purple) 16%, transparent); color: #b07bf2; }
+  .dash-root .leads-stat.tone-green .leads-stat-ic { background: color-mix(in srgb, var(--green) 16%, transparent); color: var(--green); }
+  .dash-root .leads-stat-val { font-size: 22px; font-weight: 800; line-height: 1; letter-spacing: -0.02em; }
+  .dash-root .leads-stat-lbl { font-size: 11.5px; color: var(--muted); font-weight: 600; margin-top: 4px; }
+
+  /* ---- toolbar ---- */
+  .dash-root .leads-toolbar { display: flex; align-items: center; gap: 12px; margin-bottom: 16px; flex-wrap: wrap; }
+  .dash-root .leads-search { display: flex; align-items: center; gap: 9px; flex: 1 1 260px; min-width: 220px; height: 42px; padding: 0 12px; border-radius: 12px; border: 1px solid var(--border); background: var(--panel); color: var(--muted); }
+  .dash-root .leads-search:focus-within { border-color: color-mix(in srgb, var(--orange) 55%, var(--border)); box-shadow: 0 0 0 3px color-mix(in srgb, var(--orange) 14%, transparent); }
+  .dash-root .leads-search input { flex: 1; border: 0; background: none; outline: none; color: var(--text); font-family: inherit; font-size: 13.5px; }
+  .dash-root .leads-search input::placeholder { color: var(--muted); }
+  .dash-root .leads-search-x { border: 0; background: none; color: var(--muted); cursor: pointer; display: grid; place-items: center; padding: 2px; border-radius: 6px; }
+  .dash-root .leads-search-x:hover { color: var(--text); background: var(--panel-3); }
+  .dash-root .leads-tabs { display: inline-flex; gap: 3px; padding: 4px; border-radius: 12px; border: 1px solid var(--border); background: var(--panel); }
+  .dash-root .leads-tab { border: 0; background: none; color: var(--muted); font-family: inherit; font-size: 12.5px; font-weight: 600; padding: 7px 13px; border-radius: 9px; cursor: pointer; transition: 0.14s; }
+  .dash-root .leads-tab:hover { color: var(--text-2); }
+  .dash-root .leads-tab.active { background: var(--orange); color: #1a1205; box-shadow: 0 4px 12px -4px color-mix(in srgb, var(--orange) 60%, transparent); }
+
+  /* ---- board ---- */
+  .dash-root .leads-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(320px, 1fr)); gap: 14px; }
+  .dash-root .lead-card { text-align: left; width: 100%; cursor: pointer; display: flex; flex-direction: column; gap: 11px; padding: 16px 17px; border-radius: 18px; border: 1px solid var(--border); background: var(--card-grad); box-shadow: var(--card-hi), 0 1px 2px rgba(0,0,0,0.18); font-family: inherit; color: var(--text); transition: transform 0.16s ease, border-color 0.16s ease, box-shadow 0.16s ease; }
+  .dash-root .lead-card:hover { transform: translateY(-3px); border-color: color-mix(in srgb, var(--orange) 40%, var(--border)); box-shadow: var(--shadow), 0 14px 34px -20px color-mix(in srgb, var(--orange) 50%, transparent); }
+  .dash-root .lead-card-top { display: flex; align-items: center; gap: 12px; }
+  .dash-root .lead-ava { position: relative; border-radius: 50%; padding: 3px; display: inline-flex; }
+  .dash-root .lead-ava.prio-high { box-shadow: 0 0 0 2px color-mix(in srgb, var(--red) 70%, transparent); }
+  .dash-root .lead-ava.prio-medium { box-shadow: 0 0 0 2px color-mix(in srgb, var(--orange) 70%, transparent); }
+  .dash-root .lead-ava.prio-low { box-shadow: 0 0 0 2px var(--border-2); }
+  .dash-root .lead-card-id { flex: 1; min-width: 0; }
+  .dash-root .lead-card-name { font-size: 15px; font-weight: 700; letter-spacing: -0.01em; }
+  .dash-root .lead-card-sub { display: flex; align-items: center; gap: 4px; font-size: 11.5px; color: var(--muted); margin-top: 2px; }
+  .dash-root .lead-card-sub svg { color: var(--orange); }
+  .dash-root .lead-code { font-family: ui-monospace, monospace; font-size: 11px; color: var(--text-2); }
+  .dash-root .lead-card-row { display: flex; align-items: center; gap: 8px; font-size: 12.5px; color: var(--text-2); }
+  .dash-root .lead-card-row svg { color: var(--muted); flex: 0 0 auto; }
+  .dash-root .lead-card-row span { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .dash-root .lead-card-foot { display: flex; align-items: center; gap: 8px; margin-top: 3px; padding-top: 11px; border-top: 1px solid var(--border); }
+  .dash-root .lead-source { display: inline-flex; align-items: center; gap: 4px; font-size: 11px; color: var(--muted); }
+  .dash-root .lead-card-spacer { flex: 1; }
+  .dash-root .lead-rep { font-size: 11.5px; color: var(--text-2); font-weight: 600; }
+  .dash-root .lead-updated { font-size: 10.5px; color: var(--faint, var(--muted)); }
+
+  .dash-root .leads-empty { display: flex; flex-direction: column; align-items: center; text-align: center; gap: 6px; padding: 48px 20px; color: var(--muted); }
+  .dash-root .leads-empty svg { color: var(--muted); margin-bottom: 6px; }
+  .dash-root .leads-empty h3 { font-size: 16px; color: var(--text); }
+
+  /* ---- detail popup ---- */
+  .dash-root .lead-detail { display: flex; flex-direction: column; gap: 16px; }
+  .dash-root .ld-identity { display: flex; align-items: center; gap: 14px; }
+  .dash-root .ld-identity-name { font-size: 18px; font-weight: 800; letter-spacing: -0.01em; }
+  .dash-root .ld-identity-pills { display: flex; gap: 6px; margin-top: 6px; }
+  .dash-root .ld-storm { display: flex; align-items: center; gap: 12px; padding: 12px 14px; border-radius: 14px; border: 1px solid color-mix(in srgb, var(--orange) 30%, var(--border)); background: color-mix(in srgb, var(--orange) 9%, transparent); }
+  .dash-root .ld-storm-ic { width: 36px; height: 36px; border-radius: 10px; display: grid; place-items: center; background: color-mix(in srgb, var(--orange) 18%, transparent); color: var(--orange); flex: 0 0 auto; }
+  .dash-root .ld-storm-zone { font-size: 13.5px; font-weight: 700; }
+  .dash-root .ld-storm-meta { font-size: 12px; color: var(--muted); margin-top: 2px; }
+
+  .dash-root .ld-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 12px; }
+  .dash-root .ld-section { border: 1px solid var(--border); border-radius: 14px; background: var(--panel-2); padding: 14px 15px; }
+  .dash-root .ld-section.wide { grid-column: 1 / -1; }
+  .dash-root .ld-section-head { display: flex; align-items: center; gap: 8px; font-size: 12px; font-weight: 700; text-transform: uppercase; letter-spacing: 0.04em; color: var(--orange); margin-bottom: 12px; }
+  .dash-root .ld-section-body { display: flex; flex-direction: column; gap: 3px; }
+  .dash-root .ld-dl { display: flex; align-items: baseline; justify-content: space-between; gap: 12px; padding: 6px 0; border-bottom: 1px dashed var(--border); }
+  .dash-root .ld-dl:last-child { border-bottom: 0; }
+  .dash-root .ld-dl-k { font-size: 12px; color: var(--muted); flex: 0 0 auto; }
+  .dash-root .ld-dl-v { font-size: 12.5px; color: var(--text); font-weight: 600; text-align: right; }
+  .dash-root .ld-assign { display: grid; grid-template-columns: 1fr 1fr; gap: 0 18px; }
+  .dash-root .ld-sublabel { font-size: 10.5px; text-transform: uppercase; letter-spacing: 0.05em; color: var(--faint, var(--muted)); font-weight: 700; margin: 8px 0 6px; }
+  .dash-root .ld-sublabel:first-child { margin-top: 0; }
+  .dash-root .ld-contact-row { display: flex; align-items: center; gap: 8px; padding: 5px 0; font-size: 12.5px; color: var(--text); }
+  .dash-root .ld-contact-row svg { color: var(--muted); flex: 0 0 auto; }
+  .dash-root .ld-contact-val { font-weight: 600; }
+  .dash-root .ld-contact-tag { font-size: 10.5px; color: var(--muted); padding: 2px 7px; border-radius: 99px; background: var(--panel-3); }
+  .dash-root .ld-notes p { font-size: 12.5px; color: var(--text-2); line-height: 1.5; margin-top: 2px; }
+
+  /* ---- New Lead form ---- */
+  .dash-root .nl-form { display: flex; flex-direction: column; gap: 16px; }
+  .dash-root .nl-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 0 14px; }
+  .dash-root .nl-grid .ds-field { margin-bottom: 0; }
+  .dash-root .nl-grid > .ds-field, .dash-root .nl-grid > .nl-full { margin-bottom: 14px; }
+  .dash-root .nl-full { grid-column: 1 / -1; }
+  .dash-root .nl-full .ds-field { margin-bottom: 0; }
+  .dash-root .nl-prio { display: flex; gap: 8px; }
+  .dash-root .nl-prio-btn { flex: 1; height: 42px; border-radius: 11px; border: 1px solid var(--border-2); background: var(--panel-2); color: var(--muted); font-family: inherit; font-size: 13px; font-weight: 700; cursor: pointer; transition: 0.14s; }
+  .dash-root .nl-prio-btn:hover { color: var(--text-2); border-color: var(--muted); }
+  .dash-root .nl-prio-btn.active.low { background: color-mix(in srgb, var(--muted) 22%, transparent); color: var(--text); border-color: var(--muted); }
+  .dash-root .nl-prio-btn.active.medium { background: color-mix(in srgb, var(--orange) 18%, transparent); color: var(--orange); border-color: color-mix(in srgb, var(--orange) 55%, transparent); }
+  .dash-root .nl-prio-btn.active.high { background: color-mix(in srgb, var(--red) 18%, transparent); color: var(--red); border-color: color-mix(in srgb, var(--red) 55%, transparent); }
+  .dash-root .nl-prio-btn.urg.active.standard { background: color-mix(in srgb, var(--muted) 20%, transparent); color: var(--text); border-color: var(--muted); }
+  .dash-root .nl-prio-btn.urg.active.high { background: color-mix(in srgb, var(--orange) 18%, transparent); color: var(--orange); border-color: color-mix(in srgb, var(--orange) 55%, transparent); }
+  .dash-root .nl-prio-btn.urg.active.emergency { background: color-mix(in srgb, var(--red) 20%, transparent); color: var(--red); border-color: color-mix(in srgb, var(--red) 60%, transparent); }
+
+  /* multi-value rows (phones / emails) */
+  .dash-root .nl-multirow { display: flex; gap: 8px; margin-bottom: 8px; }
+  .dash-root .nl-multirow .ds-input { flex: 1; }
+  .dash-root .nl-typesel { flex: 0 0 108px; width: 108px; }
+  .dash-root .nl-rowx { flex: 0 0 auto; width: 42px; border-radius: 11px; border: 1px solid var(--border-2); background: var(--panel-2); color: var(--muted); cursor: pointer; display: grid; place-items: center; transition: 0.14s; }
+  .dash-root .nl-rowx:hover { color: var(--red); border-color: color-mix(in srgb, var(--red) 50%, transparent); }
+  .dash-root .nl-add { display: inline-flex; align-items: center; gap: 6px; margin-top: 2px; padding: 8px 13px; border-radius: 10px; border: 1px dashed var(--border-2); background: none; color: var(--orange); font-family: inherit; font-size: 12.5px; font-weight: 700; cursor: pointer; transition: 0.14s; }
+  .dash-root .nl-add:hover { background: color-mix(in srgb, var(--orange) 10%, transparent); border-color: color-mix(in srgb, var(--orange) 45%, transparent); }
+  .dash-root .nl-empty { font-size: 12.5px; color: var(--faint, var(--muted)); padding: 8px 0 10px; }
+
+  /* site photos dropzone */
+  .dash-root .nl-photos { width: 100%; display: flex; flex-direction: column; align-items: center; gap: 3px; padding: 22px; border-radius: 14px; border: 1.5px dashed var(--border-2); background: var(--panel-2); color: var(--muted); cursor: pointer; transition: 0.14s; }
+  .dash-root .nl-photos:hover { border-color: color-mix(in srgb, var(--orange) 50%, transparent); color: var(--orange); background: color-mix(in srgb, var(--orange) 7%, transparent); }
+  .dash-root .nl-photos-t { font-size: 13px; font-weight: 700; color: var(--text-2); }
+  .dash-root .nl-photos:hover .nl-photos-t { color: var(--orange); }
+  .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 .ds-select.is-placeholder { color: var(--faint, var(--muted)); }
+
+  /* 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; }
+  .dash-root .nl-canvasser-opt { display: flex; align-items: center; gap: 9px; width: 100%; padding: 7px 9px; border: none; border-radius: 9px; background: transparent; color: var(--text); font-family: inherit; font-size: 13px; text-align: left; cursor: pointer; transition: 0.12s; }
+  .dash-root .nl-canvasser-opt:hover { background: var(--panel-2); }
+  .dash-root .nl-canvasser-name { font-weight: 700; }
+  .dash-root .nl-canvasser-email { color: var(--muted); font-size: 12px; }
+  .dash-root .nl-canvasser-opt .nl-canvasser-email { margin-left: auto; }
+  .dash-root .nl-canvasser-empty { padding: 10px; color: var(--muted); font-size: 12.5px; text-align: center; }
+  .dash-root .nl-canvasser-chip { display: flex; align-items: center; gap: 9px; padding: 7px 10px; border: 1px solid var(--border-2); border-radius: 12px; background: var(--panel-2); }
+  .dash-root .nl-canvasser-chip .nl-canvasser-email { margin-left: 2px; }
+  .dash-root .nl-canvasser-clear { margin-left: auto; display: grid; place-items: center; width: 26px; height: 26px; border: none; border-radius: 8px; background: transparent; color: var(--muted); cursor: pointer; transition: 0.12s; }
+  .dash-root .nl-canvasser-clear:hover { background: color-mix(in srgb, var(--red) 15%, transparent); color: var(--red); }
+
+  /* ========================================================== */
+  /* Lead Verification — stat tiles + filters + table           */
+  /* ========================================================== */
+  .dash-root .lv-stats { display: grid; grid-template-columns: repeat(5, 1fr); gap: 12px; margin-bottom: 18px; }
+  .dash-root .lv-stat { display: flex; flex-direction: column; align-items: flex-start; gap: 2px; padding: 14px 16px; border-radius: 16px; border: 1px solid var(--border); background: var(--card-grad); box-shadow: var(--card-hi); cursor: pointer; text-align: left; font-family: inherit; transition: 0.15s; position: relative; }
+  .dash-root .lv-stat:hover { border-color: var(--border-2); transform: translateY(-2px); }
+  .dash-root .lv-stat.active { border-color: color-mix(in srgb, var(--accent, var(--orange)) 60%, transparent); box-shadow: var(--card-hi), 0 0 0 1px color-mix(in srgb, var(--accent, var(--orange)) 40%, transparent); }
+  .dash-root .lv-stat-ic { width: 32px; height: 32px; border-radius: 9px; display: grid; place-items: center; margin-bottom: 6px; }
+  .dash-root .lv-stat-val { font-size: 22px; font-weight: 800; line-height: 1; letter-spacing: -0.02em; }
+  .dash-root .lv-stat-lbl { font-size: 11.5px; color: var(--muted); font-weight: 600; }
+  .dash-root .lv-stat.tone-green { --accent: var(--green); } .dash-root .lv-stat.tone-green .lv-stat-ic { background: color-mix(in srgb, var(--green) 16%, transparent); color: var(--green); }
+  .dash-root .lv-stat.tone-orange { --accent: var(--orange); } .dash-root .lv-stat.tone-orange .lv-stat-ic { background: color-mix(in srgb, var(--orange) 16%, transparent); color: var(--orange); }
+  .dash-root .lv-stat.tone-blue { --accent: var(--blue); } .dash-root .lv-stat.tone-blue .lv-stat-ic { background: color-mix(in srgb, var(--blue) 18%, transparent); color: #6f9bff; }
+  .dash-root .lv-stat.tone-purple { --accent: var(--purple); } .dash-root .lv-stat.tone-purple .lv-stat-ic { background: color-mix(in srgb, var(--purple) 18%, transparent); color: #b07bf2; }
+  .dash-root .lv-stat.tone-red { --accent: var(--red); } .dash-root .lv-stat.tone-red .lv-stat-ic { background: color-mix(in srgb, var(--red) 16%, transparent); color: var(--red); }
+
+  .dash-root .lv-toolbar { display: flex; align-items: center; gap: 10px; margin-bottom: 14px; flex-wrap: wrap; }
+  .dash-root .lv-search { display: flex; align-items: center; gap: 9px; flex: 1 1 240px; min-width: 200px; height: 42px; padding: 0 12px; border-radius: 12px; border: 1px solid var(--border); background: var(--panel); color: var(--muted); }
+  .dash-root .lv-search:focus-within { border-color: color-mix(in srgb, var(--orange) 55%, var(--border)); box-shadow: 0 0 0 3px color-mix(in srgb, var(--orange) 14%, transparent); }
+  .dash-root .lv-search input { flex: 1; border: 0; background: none; outline: none; color: var(--text); font-family: inherit; font-size: 13.5px; }
+  .dash-root .lv-search input::placeholder { color: var(--muted); }
+  .dash-root .lv-search-x { border: 0; background: none; color: var(--muted); cursor: pointer; display: grid; place-items: center; padding: 2px; border-radius: 6px; }
+  .dash-root .lv-search-x:hover { color: var(--text); background: var(--panel-3); }
+  .dash-root .lv-filter { height: 42px; flex: 0 0 auto; width: auto; min-width: 150px; }
+
+  .dash-root .lv-tablewrap { border: 1px solid var(--border); border-radius: 18px; background: var(--card-grad); box-shadow: var(--card-hi); overflow-x: auto; }
+  .dash-root .lv-table { width: 100%; border-collapse: collapse; min-width: 940px; }
+  .dash-root .lv-table thead th { text-align: left; font-size: 10.5px; font-weight: 700; text-transform: uppercase; letter-spacing: 0.05em; color: var(--muted); padding: 14px 16px; border-bottom: 1px solid var(--border); white-space: nowrap; }
+  .dash-root .lv-table tbody td { padding: 13px 16px; border-bottom: 1px solid var(--border); font-size: 12.5px; vertical-align: middle; }
+  .dash-root .lv-table tbody tr:last-child td { border-bottom: 0; }
+  .dash-root .lv-table tbody tr { transition: background 0.12s; }
+  .dash-root .lv-table tbody tr:hover { background: color-mix(in srgb, var(--orange) 5%, transparent); }
+  .dash-root .lv-id { font-family: ui-monospace, monospace; font-size: 12px; font-weight: 700; color: var(--text); white-space: nowrap; }
+  .dash-root .lv-id-date { font-size: 10.5px; color: var(--faint, var(--muted)); margin-top: 2px; }
+  .dash-root .lv-cust { display: flex; align-items: center; gap: 10px; min-width: 210px; }
+  .dash-root .lv-cust-name { font-weight: 700; font-size: 13px; color: var(--text); }
+  .dash-root .lv-cust-addr { font-size: 11px; color: var(--muted); margin-top: 1px; }
+  .dash-root .lv-phone { color: var(--text-2); white-space: nowrap; }
+  .dash-root .lv-source { display: inline-block; font-size: 11.5px; font-weight: 600; color: var(--text-2); padding: 4px 10px; border-radius: 99px; background: var(--panel-3); white-space: nowrap; }
+  .dash-root .lv-assignee { display: flex; align-items: center; gap: 8px; white-space: nowrap; }
+  .dash-root .lv-assignee span { font-weight: 600; color: var(--text-2); font-size: 12px; }
+  .dash-root .lv-unassigned { font-size: 11.5px; color: var(--faint, var(--muted)); }
+  .dash-root .lv-verif { display: inline-flex; align-items: center; gap: 5px; font-size: 11.5px; font-weight: 600; white-space: nowrap; color: var(--muted); }
+  .dash-root .lv-verif.v-verified { color: var(--green); }
+  .dash-root .lv-verif.v-in_progress { color: var(--orange); }
+  .dash-root .lv-verif.v-assigned { color: #6f9bff; }
+  .dash-root .lv-verif.v-pending { color: #b07bf2; }
+  .dash-root .lv-verif.v-unverified { color: var(--red); }
+  .dash-root .lv-created { color: var(--muted); white-space: nowrap; }
+  .dash-root .lv-rowacts { display: flex; gap: 6px; }
+  .dash-root .lv-act { width: 32px; height: 32px; border-radius: 9px; border: 1px solid var(--border-2); background: var(--panel-2); color: var(--muted); cursor: pointer; display: grid; place-items: center; transition: 0.14s; }
+  .dash-root .lv-act:hover { color: var(--text); border-color: var(--muted); }
+  .dash-root .lv-act.primary:hover { color: var(--green); border-color: color-mix(in srgb, var(--green) 50%, transparent); background: color-mix(in srgb, var(--green) 10%, transparent); }
+  .dash-root .lv-empty { text-align: center; color: var(--muted); padding: 40px 16px; font-size: 13px; }
+  .dash-root .lv-count { font-size: 11.5px; color: var(--muted); margin-top: 12px; text-align: right; }
+
+  /* ---- row actions dropdown (portalled to body) ---- */
+  .lv-menu-scrim { position: fixed; inset: 0; z-index: 90; }
+  .lv-menu { position: fixed; z-index: 91; width: 188px; padding: 6px; border-radius: 12px; border: 1px solid var(--border-2, rgba(255,255,255,0.12)); background: var(--panel, #0e0e13); box-shadow: 0 18px 44px -18px rgba(0,0,0,0.7); animation: ds-rise 0.13s ease; }
+  .lv-menu-item { display: flex; align-items: center; gap: 9px; width: 100%; padding: 9px 10px; border: 0; border-radius: 9px; background: none; color: var(--text-2, #eaeaea); font-family: inherit; font-size: 12.5px; font-weight: 600; cursor: pointer; text-align: left; }
+  .lv-menu-item:hover { background: var(--panel-3, #1b1b22); color: var(--text, #fff); }
+  .lv-menu-item svg { color: var(--muted, #8c8c8c); flex: 0 0 auto; }
+  .lv-menu-item:hover svg { color: var(--orange, #fda913); }
+
+  /* ---- 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; }
+  .dash-root .lv-d-name { font-size: 18px; font-weight: 800; letter-spacing: -0.01em; }
+  .dash-root .lv-d-pills { display: flex; align-items: center; gap: 8px; margin-top: 6px; }
+  .dash-root .lv-d-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 12px; }
+  .dash-root .lv-d-section, .dash-root .lv-d-notes, .dash-root .lv-d-activity { border: 1px solid var(--border); border-radius: 14px; background: var(--panel-2); padding: 14px 15px; }
+  .dash-root .lv-d-head { display: flex; align-items: center; gap: 8px; font-size: 12px; font-weight: 700; text-transform: uppercase; letter-spacing: 0.04em; color: var(--orange); margin-bottom: 12px; }
+  .dash-root .lv-d-row { display: flex; align-items: baseline; justify-content: space-between; gap: 12px; padding: 6px 0; border-bottom: 1px dashed var(--border); }
+  .dash-root .lv-d-row:last-child { border-bottom: 0; }
+  .dash-root .lv-d-k { font-size: 12px; color: var(--muted); flex: 0 0 auto; }
+  .dash-root .lv-d-v { font-size: 12.5px; color: var(--text); font-weight: 600; text-align: right; }
+  .dash-root .lv-d-notes p { font-size: 12.5px; color: var(--text-2); line-height: 1.55; margin-top: 2px; }
+
+  .dash-root .lv-timeline { list-style: none; margin: 0; padding: 0; }
+  .dash-root .lv-tl-item { position: relative; display: flex; gap: 12px; padding: 0 0 16px 4px; }
+  .dash-root .lv-tl-item::before { content: ""; position: absolute; left: 8px; top: 14px; bottom: -2px; width: 1.5px; background: var(--border-2); }
+  .dash-root .lv-tl-item:last-child { padding-bottom: 0; }
+  .dash-root .lv-tl-item:last-child::before { display: none; }
+  .dash-root .lv-tl-dot { position: relative; z-index: 1; flex: 0 0 auto; width: 10px; height: 10px; margin-top: 4px; border-radius: 50%; background: var(--orange); box-shadow: 0 0 0 3px color-mix(in srgb, var(--orange) 20%, transparent); }
+  .dash-root .lv-tl-text { font-size: 12.5px; color: var(--text); font-weight: 600; }
+  .dash-root .lv-tl-meta { font-size: 11px; color: var(--muted); margin-top: 2px; }
+
+  @media (max-width: 900px) {
+    .dash-root .lv-d-grid { grid-template-columns: 1fr; }
+  }
+
+  @media (max-width: 900px) {
+    .dash-root .leads-stats { grid-template-columns: repeat(2, 1fr); }
+    .dash-root .ld-grid { grid-template-columns: 1fr; }
+    .dash-root .ld-assign { grid-template-columns: 1fr; }
+    .dash-root .lv-stats { grid-template-columns: repeat(3, 1fr); }
+    .dash-root .lv-filter { flex: 1 1 45%; }
+  }
+  @media (max-width: 560px) {
+    .dash-root .leads-stats { grid-template-columns: 1fr; }
+    .dash-root .leads-grid { grid-template-columns: 1fr; }
+    .dash-root .nl-grid { grid-template-columns: 1fr; }
+    .dash-root .lv-stats { grid-template-columns: repeat(2, 1fr); }
+  }
+  

src/app/portal/invite/page.tsx

@@ -0,0 +1,113 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { useRouter } from "next/navigation";
+import { useAuth, useAppShell } from "@abe-kap/appshell-sdk/react";
+import { PortalAside, PanelBrand } from "@/components/portal/parts";
+import { CookieBanner, Spinner } from "@/components/portal/bits";
+import { isShellConfigured } from "@/lib/appshell";
+
+interface InviteInfo { ok: boolean; status?: string; email?: string; roleNames?: string[]; hasAccount?: boolean }
+
+/**
+ * Team invitation landing page (/portal/invite?token=…). It looks the token up
+ * (public, pre-auth) to learn the invited email and whether an account exists, then:
+ * - signed in + registered → accept now (creates the membership with the invited role);
+ * - signed in, no CRM profile → onboarding, which redeems the token on finish;
+ * - not signed in + email already has an account → sign in (email prefilled);
+ * - not signed in + first-time invitee → register (email prefilled + locked).
+ * The register/login/onboarding flows redeem the stashed token on completion.
+ */
+export default function InvitePage() {
+  const router = useRouter();
+  const { status, getUserEmail } = useAuth();
+  const { ready, sdk } = useAppShell();
+  const [error, setError] = useState("");
+  const started = useRef(false);
+
+  useEffect(() => {
+    let token = "";
+    try { token = new URLSearchParams(window.location.search).get("token") ?? ""; } catch { /* ignore */ }
+    if (!token) { setError("This invitation link is invalid or incomplete."); return; }
+    if (!isShellConfigured()) { try { sessionStorage.setItem("invite_token", token); } catch { /* ignore */ } router.replace("/portal/register"); return; }
+    if (!ready || started.current) return;
+    started.current = true;
+
+    (async () => {
+      try { sessionStorage.setItem("invite_token", token); } catch { /* ignore */ }
+
+      // Look the invitation up (pre-auth) to get the email + account state.
+      let info: InviteInfo = { ok: false };
+      try {
+        const res = await fetch(`/api/invite/lookup?token=${encodeURIComponent(token)}`, { cache: "no-store" });
+        info = await res.json();
+      } catch { /* treat as unavailable below */ }
+
+      if (!info.ok) {
+        const msg = info.status === "expired" ? "This invitation has expired. Ask for a new one."
+          : info.status === "accepted" ? "This invitation has already been used."
+          : info.status === "revoked" ? "This invitation was revoked."
+          : "This invitation link is invalid.";
+        setError(msg);
+        try { sessionStorage.removeItem("invite_token"); } catch { /* ignore */ }
+        return;
+      }
+      if (info.email) { try { sessionStorage.setItem("invite_email", info.email); } catch { /* ignore */ } }
+
+      // Signed in already: accept if registered, else finish onboarding first.
+      if (status === "authenticated") {
+        try {
+          const st = await sdk.query<{ registered: boolean }>("crm.account.registrationStatus");
+          if (!st?.registered) {
+            try { const em = await getUserEmail(); if (em) sessionStorage.setItem("onboard_email", em); } catch { /* ignore */ }
+            router.replace("/portal/onboarding");
+            return;
+          }
+        } catch { /* fall through to accept */ }
+        try {
+          await sdk.command("crm.team.invitation.accept", { token });
+          try { sessionStorage.removeItem("invite_token"); sessionStorage.removeItem("invite_email"); } catch { /* ignore */ }
+          router.replace("/dashboard");
+        } catch {
+          setError("We couldn't accept this invitation — it may have expired or already been used.");
+        }
+        return;
+      }
+
+      // Not signed in: existing account → sign in; first-time invitee → register.
+      router.replace(info.hasAccount ? "/portal/login" : "/portal/register");
+    })();
+  }, [ready, status, router, sdk, getUserEmail]);
+
+  return (
+    <main className="portal-main">
+      <span className="portal-grid" />
+      <div className="portal-split anim-in">
+        <PortalAside />
+        <section className="portal-panel">
+          <div style={{ width: "100%", maxWidth: 420 }}>
+            <PanelBrand />
+            <div className="card anim-fade-up" style={{ textAlign: "center" }}>
+              {error ? (
+                <>
+                  <h1>Invitation problem</h1>
+                  <p className="sub">{error}</p>
+                  <button className="btn btn-primary" style={{ marginTop: 16 }} onClick={() => router.replace("/portal/login")}>
+                    Go to sign in
+                  </button>
+                </>
+              ) : (
+                <div className="interstitial">
+                  <Spinner lg />
+                  <h1 style={{ fontSize: 20, marginTop: 8 }}>Checking your invitation…</h1>
+                  <p className="sub">One moment while we set things up.</p>
+                </div>
+              )}
+            </div>
+          </div>
+        </section>
+      </div>
+      <CookieBanner />
+    </main>
+  );
+}

src/app/portal/onboarding/page.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useEffect } from "react";
+import { useEffect, useState } from "react";
 import { useRouter } from "next/navigation";
 import { useAuth, useAppShell } from "@abe-kap/appshell-sdk/react";
 import { PortalAside, PanelBrand } from "@/components/portal/parts";
@@ -10,18 +10,34 @@ import { isShellConfigured } from "@/lib/appshell";
 
 /**
  * Post-OAuth onboarding — a first-time Google user completes their CRM profile
- * (everything except email, which Google already verified). Only reachable while
- * authenticated; unauthenticated visitors are sent back to sign in.
+ * (everything except email, which Google already verified).
+ *
+ * This screen is ONLY a step in the OAuth → onboarding handoff: the login page
+ * stashes the verified email in `sessionStorage` right before routing here. Any
+ * other way in — a typed URL, a fresh tab, a lost session — has no handoff hint
+ * (and possibly no session), so we bounce back to sign in rather than showing an
+ * empty form.
  */
 export default function OnboardingPage() {
   const router = useRouter();
   const { status } = useAuth();
   const { ready } = useAppShell();
+  const [allowed, setAllowed] = useState(false);
 
   useEffect(() => {
-    if (isShellConfigured() && ready && status === "unauthenticated") router.replace("/portal/login");
+    if (!isShellConfigured()) { setAllowed(true); return; } // local dev without the Shell
+    if (!ready) return;                                     // wait for session restore
+    let hasHandoff = false;
+    try { hasHandoff = !!sessionStorage.getItem("onboard_email"); } catch { /* ignore */ }
+    if (status === "unauthenticated" || !hasHandoff) {
+      router.replace("/portal/login");
+      return;
+    }
+    setAllowed(true);
   }, [ready, status, router]);
 
+  if (!allowed) return <main className="portal-main"><span className="portal-grid" /></main>;
+
   return (
     <main className="portal-main">
       <span className="portal-grid" />

src/components/dashboard/dashboard.tsx

@@ -15,6 +15,10 @@ import { Support } from "./support";
 import { Rules } from "./rules";
 import { AiAssistant } from "./ai-assistant";
 import { TeamManagement } from "./team-management";
+import { Messenger } from "./messenger";
+import { Inbox } from "./inbox";
+import { Leads } from "./leads";
+import { Verify } from "./verify";
 import "../../app/dashboard/dashboard.css";
 
 export function Dashboard() {
@@ -45,6 +49,10 @@ export function Dashboard() {
               : active === "support" ? <Support />
               : active === "rules" ? <Rules />
               : active === "ai" ? <AiAssistant />
+              : active === "messenger" ? <Messenger />
+              : active === "inbox" ? <Inbox />
+              : active === "leads" ? <Leads />
+              : active === "verify" ? <Verify />
               : active === "team" ? <TeamManagement />
               : <ComingSoon title={title} icon={item?.icon ?? "dashboard"} onGo={setActive} />}
           </ToastProvider>

src/components/dashboard/inbox.tsx

@@ -0,0 +1,152 @@
+"use client";
+
+// ============================================================
+// Inbox — the ONE unified communication surface. It lists everything
+// IIOS surfaces for you (mentions, needs-reply, system alerts, support
+// updates, …) AND the mail behind them: click an item tied to a thread
+// and its conversation opens on the right to read + reply. Compose new
+// mail from here too. Items come from crm.inbox.*; threads from crm.mail.*.
+// ============================================================
+
+import { useEffect, useState } from "react";
+import { Btn, Icon, PageHead, Pill, useToast } from "./ui";
+import { useInboxData, type InboxState, type UiInboxItem } from "@/lib/inbox-api";
+import { MailReader, NewMailModal } from "./mail";
+
+const KIND_LABEL: Record<string, string> = {
+  MAIL: "Mail",
+  MENTION: "Mention", NEEDS_REPLY: "Needs reply", NEEDS_REVIEW: "Needs review", NEEDS_APPROVAL: "Needs approval",
+  SUPPORT_UPDATE: "Support", MEETING_FOLLOWUP: "Meeting", DIGEST: "Digest", SYSTEM_ALERT: "Alert", CRM_OWNER_INTEREST: "Owner",
+};
+const FILTERS: { value: InboxState; label: string }[] = [
+  { value: "OPEN", label: "Open" }, { value: "SNOOZED", label: "Snoozed" }, { value: "DONE", label: "Done" }, { value: "ARCHIVED", label: "Archived" },
+];
+
+export function Inbox() {
+  const [filter, setFilter] = useState<InboxState>("OPEN");
+  const inbox = useInboxData(filter);
+  const toast = useToast();
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  const [newOpen, setNewOpen] = useState(false);
+
+  useEffect(() => {
+    if ((!selectedId || !inbox.items.some((i) => i.id === selectedId)) && inbox.items[0]) setSelectedId(inbox.items[0].id);
+  }, [inbox.items, selectedId]);
+
+  const selected = inbox.items.find((i) => i.id === selectedId) ?? null;
+
+  return (
+    <div className="view">
+      <PageHead
+        eyebrow="Communication" title="Inbox" subtitle="Mentions, messages, system alerts and mail — all in one place" icon="bell"
+        actions={<Btn icon="plus" onClick={() => setNewOpen(true)}>New mail</Btn>}
+      />
+      {!inbox.live && (
+        <div style={{ margin: "0 0 14px", padding: "8px 14px", borderRadius: 10, background: "var(--panel-2)", color: "var(--muted)", fontSize: 13, border: "1px solid var(--border)" }}>
+          Demo mode — running on mock data. It goes live once the Shell + be-crm are connected.
+        </div>
+      )}
+
+      <div style={{ display: "flex", gap: 6, marginBottom: 14, flexWrap: "wrap" }}>
+        {FILTERS.map((f) => (
+          <Btn key={f.value} variant={filter === f.value ? "primary" : "outline"} onClick={() => setFilter(f.value)}>{f.label}</Btn>
+        ))}
+      </div>
+
+      <div className="card" style={{ display: "flex", height: 620, padding: 0, overflow: "hidden" }}>
+        {/* Left — the unified item list */}
+        <aside style={{ width: 360, borderRight: "1px solid var(--border)", overflowY: "auto", background: "var(--panel)" }}>
+          {inbox.loading && <div style={{ padding: 20, color: "var(--muted)" }}>Loading…</div>}
+          {!inbox.loading && inbox.items.length === 0 && (
+            <div style={{ padding: 28, color: "var(--muted)", textAlign: "center" }}>Nothing here — you&apos;re all caught up 🎉</div>
+          )}
+          {inbox.items.map((it) => (
+            <ItemRow key={it.id} it={it} active={it.id === selectedId} onClick={() => setSelectedId(it.id)} />
+          ))}
+        </aside>
+
+        {/* Right — read the mail behind the item, or the item detail */}
+        <section style={{ flex: 1, display: "flex", flexDirection: "column", minWidth: 0, background: "var(--bg)" }}>
+          {selected ? (
+            <Detail
+              it={selected}
+              onError={(m) => toast.push({ tone: "error", title: "Failed", desc: m })}
+              onDone={() => inbox.transition(selected.id, "DONE")}
+              onSnooze={() => inbox.transition(selected.id, "SNOOZED")}
+              onArchive={() => inbox.transition(selected.id, "ARCHIVED")}
+            />
+          ) : (
+            <div style={{ margin: "auto", color: "var(--muted)", textAlign: "center" }}>
+              <Icon name="bell" size={38} /><p>Select an item to read</p>
+            </div>
+          )}
+        </section>
+      </div>
+
+      <NewMailModal
+        open={newOpen} onClose={() => setNewOpen(false)}
+        onSent={() => { setNewOpen(false); inbox.refetch(); toast.push({ tone: "success", title: "Sent" }); }}
+        onError={(m) => toast.push({ tone: "error", title: "Couldn't send", desc: m })}
+      />
+    </div>
+  );
+}
+
+function ItemRow({ it, active, onClick }: { it: UiInboxItem; active: boolean; onClick: () => void }) {
+  const isMention = it.kind === "MENTION";
+  return (
+    <button
+      onClick={onClick}
+      style={{
+        display: "flex", gap: 10, alignItems: "flex-start", width: "100%", textAlign: "left",
+        padding: "13px 16px", border: "none", borderBottom: "1px solid var(--border)", cursor: "pointer",
+        background: active ? "var(--panel-2)" : "transparent", color: "var(--text)",
+      }}
+    >
+      <span style={{ marginTop: 2, color: isMention ? "var(--orange)" : "var(--text-2)", flexShrink: 0 }}>
+        <Icon name={it.kind === "MAIL" ? "mail" : it.threadId ? "chat" : isMention ? "chat" : "bell"} size={18} />
+      </span>
+      <div style={{ flex: 1, minWidth: 0 }}>
+        <div style={{ display: "flex", gap: 6, alignItems: "center", flexWrap: "wrap" }}>
+          <Pill tone={isMention ? "warn" : "muted"}>{KIND_LABEL[it.kind] ?? it.kind}</Pill>
+          <span style={{ fontWeight: 600, whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" }}>{it.title}</span>
+        </div>
+        {it.summary && <div style={{ color: "var(--muted)", fontSize: 12.5, marginTop: 3, whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" }}>{it.summary}</div>}
+      </div>
+      {it.state !== "OPEN" && <Pill tone="muted">{it.state.toLowerCase()}</Pill>}
+    </button>
+  );
+}
+
+function Detail({ it, onError, onDone, onSnooze, onArchive }: {
+  it: UiInboxItem; onError: (m: string) => void; onDone: () => void; onSnooze: () => void; onArchive: () => void;
+}) {
+  return (
+    <>
+      {/* Item actions bar — only for real inbox work-items. Mail isn't an inbox item
+          (no crm.inbox.transition), so it gets read/reply only, no Done/Snooze/Archive. */}
+      {it.state === "OPEN" && it.kind !== "MAIL" && (
+        <div style={{ display: "flex", gap: 6, padding: "10px 16px", borderBottom: "1px solid var(--border)", justifyContent: "flex-end" }}>
+          <Btn variant="ghost" icon="clock" onClick={onSnooze}>Snooze</Btn>
+          <Btn variant="outline" icon="check" onClick={onDone}>Done</Btn>
+          <Btn variant="ghost" icon="x" onClick={onArchive}>Archive</Btn>
+        </div>
+      )}
+
+      {it.threadId ? (
+        // A message/mail item → open the conversation to read + reply.
+        // key by threadId: the SDK's useQuery only refetches when the ACTION changes, not the
+        // variables — so switching items must remount MailReader to load the new thread's history.
+        <div style={{ flex: 1, minHeight: 0 }}>
+          <MailReader key={it.threadId} threadId={it.threadId} subject={it.title} onError={onError} />
+        </div>
+      ) : (
+        // A non-threaded item (e.g. a system alert) → show its detail.
+        <div style={{ flex: 1, overflowY: "auto", padding: 22 }}>
+          <div style={{ fontWeight: 700, fontSize: 16, marginBottom: 6 }}>{it.title}</div>
+          {it.summary && <div style={{ color: "var(--muted)", fontSize: 14, lineHeight: 1.55 }}>{it.summary}</div>}
+        </div>
+      )}
+    </>
+  );
+}

src/components/dashboard/leads-data.ts

@@ -0,0 +1,220 @@
+// ============================================================
+// LynkedUp Pro — Leads mock data.
+// A storm-restoration roofing pipeline: door-knocked leads in
+// the Plano, TX hail zone. Each lead carries a rich detail
+// record (contact, property, job, insurance, assignment) that
+// powers the lead-detail popup. All client-side so the screen
+// is fully interactive without a backend.
+// ============================================================
+
+export type LeadStatus = "new" | "contacted" | "appointed" | "closed";
+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 };
+
+export type Lead = {
+  id: string;            // SAL-001
+  initials: string;
+  name: string;
+  gradient: string;
+  priority: LeadPriority;
+  status: LeadStatus;
+  tag: string;           // "Storm Zone"
+  updated: string;       // "3d ago"
+  setter: string;        // compact chip name
+
+  // storm banner
+  storm: { zone: string; date: string; detail: string };
+
+  // contact
+  phones: Phone[];
+  emails: Email[];
+
+  // property
+  property: { address: string; city: string; state: string; zip: string; type: string };
+
+  // job details
+  job: {
+    source: string; leadType: string; workType: string; tradeType: string;
+    urgency: string; canvasser: string; notes: string;
+  };
+
+  // insurance
+  insurance: {
+    company: string; claimStatus: string; claimNumber: string;
+    policyNumber: string; adjusterName: string; adjusterPhone: string;
+  };
+
+  // assignment
+  assignment: {
+    assignedTo: string; priority: string; followUp: string;
+    createdBy: string; createdAt: string;
+  };
+};
+
+const G = {
+  orange: "linear-gradient(135deg,#fda913,#fd6d13)",
+  blue: "linear-gradient(135deg,#4f8cff,#2c5cff)",
+  purple: "linear-gradient(135deg,#b07bf2,#7b53e0)",
+  green: "linear-gradient(135deg,#33c98a,#1fa46c)",
+  cyan: "linear-gradient(135deg,#34c9d6,#1f9aa4)",
+};
+
+export const LEADS: Lead[] = [
+  {
+    id: "SAL-001", initials: "JM", name: "John Martinez", gradient: G.orange,
+    priority: "high", status: "contacted", tag: "Storm Zone", updated: "3d ago", setter: "Cody",
+    storm: { zone: "E Plano / Spring Creek Pkwy", date: "2026-04-28", detail: '2.5" hail (severe)' },
+    phones: [
+      { number: "(469) 500-1000", type: "Mobile", primary: true },
+      { number: "(214) 600-2000", type: "Home" },
+    ],
+    emails: [{ address: "john.martinez@gmail.com", primary: true }],
+    property: { address: "4821 Spring Creek Pkwy", city: "Plano", state: "TX", zip: "75023", type: "Single Family" },
+    job: {
+      source: "Door Knock", leadType: "Insurance", workType: "Roof Replacement", tradeType: "Roofing",
+      urgency: "High", canvasser: "Cody Tatum",
+      notes: "Homeowner showed significant granule loss on south-facing slopes; agreed to inspection.",
+    },
+    insurance: {
+      company: "State Farm", claimStatus: "Filed", claimNumber: "CLM-2026-1000",
+      policyNumber: "POL-080000", adjusterName: "Marcus Powell", adjusterPhone: "(972) 700-3000",
+    },
+    assignment: {
+      assignedTo: "Jesus Gonzales", priority: "High", followUp: "Jun 4, 2026",
+      createdBy: "Cody Tatum", createdAt: "May 28, 2026",
+    },
+  },
+  {
+    id: "SAL-002", initials: "SK", name: "Sarah Kim", gradient: G.purple,
+    priority: "high", status: "appointed", tag: "Storm Zone", updated: "2d ago", setter: "Shelby",
+    storm: { zone: "E Plano / Custer Rd", date: "2026-04-28", detail: '2.5" hail (severe)' },
+    phones: [
+      { number: "(972) 501-1037", type: "Mobile", primary: true },
+      { number: "(214) 601-2044", type: "Home" },
+    ],
+    emails: [{ address: "sarah.kim@outlook.com", primary: true }],
+    property: { address: "4905 Custer Rd", city: "Plano", state: "TX", zip: "75023", type: "Single Family" },
+    job: {
+      source: "Door Knock", leadType: "Insurance", workType: "Roof Replacement", tradeType: "Roofing",
+      urgency: "High", canvasser: "Hannah Reyes",
+      notes: "Visible mat exposure on rear elevation. Appointment set for adjuster meet.",
+    },
+    insurance: {
+      company: "Allstate", claimStatus: "Approved", claimNumber: "CLM-2026-1037",
+      policyNumber: "POL-081037", adjusterName: "Dana Whitfield", adjusterPhone: "(972) 700-3037",
+    },
+    assignment: {
+      assignedTo: "Hannah Reyes", priority: "High", followUp: "Jun 6, 2026",
+      createdBy: "Shelby Greer", createdAt: "May 29, 2026",
+    },
+  },
+  {
+    id: "SAL-003", initials: "RC", name: "Robert Chen", gradient: G.green,
+    priority: "high", status: "closed", tag: "Storm Zone", updated: "2d ago", setter: "Dalton",
+    storm: { zone: "E Plano / Independence Pkwy", date: "2026-04-28", detail: '2.5" hail (severe)' },
+    phones: [
+      { number: "(469) 502-1074", type: "Mobile", primary: true },
+    ],
+    emails: [{ address: "robert.chen@gmail.com", primary: true }],
+    property: { address: "5012 Independence Pkwy", city: "Plano", state: "TX", zip: "75023", type: "Single Family" },
+    job: {
+      source: "Door Knock", leadType: "Insurance", workType: "Roof Replacement", tradeType: "Roofing",
+      urgency: "High", canvasser: "Travis Boone",
+      notes: "Full replacement approved and installed. Final invoice cleared.",
+    },
+    insurance: {
+      company: "Farmers", claimStatus: "Paid", claimNumber: "CLM-2026-1074",
+      policyNumber: "POL-081074", adjusterName: "Leah Ortiz", adjusterPhone: "(972) 700-3074",
+    },
+    assignment: {
+      assignedTo: "Travis Boone", priority: "High", followUp: "—",
+      createdBy: "Dalton Pruitt", createdAt: "May 20, 2026",
+    },
+  },
+  {
+    id: "SAL-004", initials: "MG", name: "Maria Garcia", gradient: G.cyan,
+    priority: "high", status: "closed", tag: "Storm Zone", updated: "2d ago", setter: "Hannah",
+    storm: { zone: "E Plano / Alma Dr", date: "2026-04-28", detail: '2.5" hail (severe)' },
+    phones: [
+      { number: "(972) 503-1111", type: "Mobile", primary: true },
+    ],
+    emails: [{ address: "maria.garcia@gmail.com", primary: true }],
+    property: { address: "4720 Alma Dr", city: "Plano", state: "TX", zip: "75023", type: "Single Family" },
+    job: {
+      source: "Door Knock", leadType: "Insurance", workType: "Roof Replacement", tradeType: "Roofing",
+      urgency: "High", canvasser: "Shelby Greer",
+      notes: "Signed contract; build complete. Awaiting review request.",
+    },
+    insurance: {
+      company: "USAA", claimStatus: "Paid", claimNumber: "CLM-2026-1111",
+      policyNumber: "POL-081111", adjusterName: "Grant Mueller", adjusterPhone: "(972) 700-3111",
+    },
+    assignment: {
+      assignedTo: "Shelby Greer", priority: "High", followUp: "—",
+      createdBy: "Hannah Reyes", createdAt: "May 18, 2026",
+    },
+  },
+  {
+    id: "SAL-005", initials: "DT", name: "David Thompson", gradient: G.blue,
+    priority: "high", status: "appointed", tag: "Storm Zone", updated: "1d ago", setter: "Travis",
+    storm: { zone: "E Plano / Spring Creek Pkwy", date: "2026-04-28", detail: '2.5" hail (severe)' },
+    phones: [
+      { number: "(469) 504-1148", type: "Mobile", primary: true },
+      { number: "(214) 604-2148", type: "Work" },
+    ],
+    emails: [{ address: "david.thompson@gmail.com", primary: true }],
+    property: { address: "5130 Spring Creek Pkwy", city: "Plano", state: "TX", zip: "75023", type: "Single Family" },
+    job: {
+      source: "Door Knock", leadType: "Insurance", workType: "Roof Replacement", tradeType: "Roofing",
+      urgency: "High", canvasser: "Dalton Pruitt",
+      notes: "Adjuster appointment confirmed for next week. Bring hail map + photos.",
+    },
+    insurance: {
+      company: "Liberty Mutual", claimStatus: "Filed", claimNumber: "CLM-2026-1148",
+      policyNumber: "POL-081148", adjusterName: "Priya Nair", adjusterPhone: "(972) 700-3148",
+    },
+    assignment: {
+      assignedTo: "Dalton Pruitt", priority: "High", followUp: "Jun 9, 2026",
+      createdBy: "Travis Boone", createdAt: "May 30, 2026",
+    },
+  },
+];
+
+// Header stat — the full book is larger than the loaded page.
+export const TOTAL_LEADS = 35;
+
+export const STATUS_META: Record<LeadStatus, { label: string; tone: string }> = {
+  new: { label: "New", tone: "blue" },
+  contacted: { label: "Contacted", tone: "orange" },
+  appointed: { label: "Appointed", tone: "purple" },
+  closed: { label: "Closed", tone: "green" },
+};
+
+export const PRIORITY_META: Record<LeadPriority, { label: string; tone: string }> = {
+  high: { label: "High", tone: "red" },
+  medium: { label: "Medium", tone: "orange" },
+  low: { label: "Low", tone: "muted" },
+};
+
+/* ---------------------------------------------------------- */
+/* Reps + option lists — power the New Lead form              */
+/* ---------------------------------------------------------- */
+
+export type Rep = { id: string; initials: string; name: string; email: string };
+
+export const REPS: Rep[] = [
+  { id: "LUP-1040", initials: "CT", name: "Cody Tatum", email: "cody.tatum@lynkeduppro.com" },
+  { id: "LUP-1041", initials: "HR", name: "Hannah Reyes", email: "hannah.reyes@lynkeduppro.com" },
+  { id: "LUP-1042", initials: "TB", name: "Travis Boone", email: "travis.boone@lynkeduppro.com" },
+  { id: "LUP-1043", initials: "SG", name: "Shelby Greer", email: "shelby.greer@lynkeduppro.com" },
+  { id: "LUP-1044", initials: "DP", name: "Dalton Pruitt", email: "dalton.pruitt@lynkeduppro.com" },
+];
+
+export const LEAD_SOURCES = ["Door Knock", "Referral", "Storm Chase", "Mailer / Postcard", "Sign Call", "Insurance Agent Referral", "Repeat Customer", "Social Media", "Other"];
+export const LEAD_TYPES = ["Insurance", "Retail"];
+export const WORK_TYPES = ["Roof Replacement", "Roof Repair", "Inspection", "Gutter Install"];
+export const TRADE_TYPES = ["Roofing", "Gutters", "Siding", "Windows"];
+export const PROPERTY_TYPES = ["Single Family", "Multi Family", "Commercial"];
+export const CLAIM_STATUSES = ["Not Filed", "Filed", "Approved", "Paid", "Denied"];

src/components/dashboard/leads.tsx

@@ -0,0 +1,615 @@
+"use client";
+
+// ============================================================
+// Leads — storm-restoration pipeline board.
+//   · Hero head : storm banner + headline stats (by status)
+//   · Toolbar   : search + status filter tabs
+//   · Board     : lead cards (avatar, priority ring, status,
+//                 address, phone, source, rep, updated)
+//   · Detail    : click a lead → rich popup with Contact,
+//                 Property, Job Details, Insurance, Assignment
+// Data comes from leads-data.ts (client-side mock).
+// ============================================================
+
+import { useMemo, 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,
+  REPS, LEAD_SOURCES, WORK_TYPES, TRADE_TYPES, CLAIM_STATUSES,
+  type Lead, type LeadStatus,
+} from "./leads-data";
+
+const STATUS_TABS: { value: "all" | LeadStatus; label: string }[] = [
+  { value: "all", label: "All" },
+  { value: "new", label: "New" },
+  { value: "contacted", label: "Contacted" },
+  { value: "appointed", label: "Appointed" },
+  { value: "closed", label: "Closed" },
+];
+
+export function Leads() {
+  const toast = useToast();
+  const [query, setQuery] = useState("");
+  const [filter, setFilter] = useState<"all" | LeadStatus>("all");
+  const [selected, setSelected] = useState<Lead | null>(null);
+  const [newOpen, setNewOpen] = useState(false);
+
+  const countByStatus = useMemo(() => {
+    const m: Record<string, number> = {};
+    for (const l of LEADS) m[l.status] = (m[l.status] ?? 0) + 1;
+    return m;
+  }, []);
+
+  const filtered = useMemo(() => {
+    const q = query.trim().toLowerCase();
+    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]);
+
+  return (
+    <div className="view leads">
+      <PageHead
+        eyebrow="Sales"
+        title="Leads"
+        subtitle={`${TOTAL_LEADS} total leads · Plano hail zone · storm 2026-04-28`}
+        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="New" value={countByStatus.new ?? 0} icon="star" tone="blue" />
+        <StatCard label="Contacted" value={countByStatus.contacted ?? 0} icon="phone" tone="orange" />
+        <StatCard label="Appointed" value={countByStatus.appointed ?? 0} icon="clock" tone="purple" />
+        <StatCard label="Closed" value={countByStatus.closed ?? 0} icon="check-circle" tone="green" />
+      </div>
+
+      {/* ---- toolbar ------------------------------------------- */}
+      <div className="leads-toolbar">
+        <div className="leads-search">
+          <Icon name="search" size={16} />
+          <input
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+            placeholder="Search by name, address, source…"
+            aria-label="Search leads"
+          />
+          {query && <button className="leads-search-x" aria-label="Clear" onClick={() => setQuery("")}><Icon name="x" size={14} /></button>}
+        </div>
+        <div className="leads-tabs" role="tablist">
+          {STATUS_TABS.map((t) => (
+            <button
+              key={t.value}
+              role="tab"
+              aria-selected={filter === t.value}
+              className={`leads-tab ${filter === t.value ? "active" : ""}`}
+              onClick={() => setFilter(t.value)}
+            >
+              {t.label}
+            </button>
+          ))}
+        </div>
+      </div>
+
+      {/* ---- board --------------------------------------------- */}
+      {filtered.length === 0 ? (
+        <div className="card leads-empty">
+          <Icon name="search" size={30} />
+          <h3>No leads match</h3>
+          <p>Try a different search or clear the status filter.</p>
+        </div>
+      ) : (
+        <div className="leads-grid">
+          {filtered.map((l) => (
+            <LeadCard key={l.id} lead={l} onOpen={() => setSelected(l)} />
+          ))}
+        </div>
+      )}
+
+      <LeadDetail lead={selected} onClose={() => setSelected(null)} />
+      <NewLead open={newOpen} onClose={() => setNewOpen(false)} />
+    </div>
+  );
+}
+
+/* ---------------------------------------------------------- */
+/* Stat card                                                   */
+/* ---------------------------------------------------------- */
+
+function StatCard({ label, value, icon, tone }: { label: string; value: number; icon: string; tone: string }) {
+  return (
+    <div className={`leads-stat tone-${tone}`}>
+      <span className="leads-stat-ic"><Icon name={icon} size={17} /></span>
+      <div className="leads-stat-body">
+        <div className="leads-stat-val">{value}</div>
+        <div className="leads-stat-lbl">{label}</div>
+      </div>
+    </div>
+  );
+}
+
+/* ---------------------------------------------------------- */
+/* Lead card                                                   */
+/* ---------------------------------------------------------- */
+
+function LeadCard({ lead, onOpen }: { lead: Lead; onOpen: () => void }) {
+  const status = STATUS_META[lead.status];
+  const priority = PRIORITY_META[lead.priority];
+  const primaryPhone = lead.phones.find((p) => p.primary) ?? lead.phones[0];
+
+  return (
+    <button className="lead-card" onClick={onOpen}>
+      <div className="lead-card-top">
+        <span className={`lead-ava prio-${lead.priority}`}>
+          <Avatar initials={lead.initials} gradient={lead.gradient} size={46} />
+        </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>
+        <Pill tone={priority.tone}><Icon name="alert" size={11} /> {priority.label}</Pill>
+      </div>
+
+      <div className="lead-card-row"><Icon name="pin" size={14} /><span>{lead.property.address}, {lead.property.city}, {lead.property.state}</span></div>
+      <div className="lead-card-row"><Icon name="phone" size={14} /><span>{primaryPhone?.number}</span></div>
+
+      <div className="lead-card-foot">
+        <Pill tone={status.tone}>{status.label}</Pill>
+        <span className="lead-source"><Icon name="pin" size={12} /> {lead.job.source}</span>
+        <span className="lead-card-spacer" />
+        <span className="lead-rep" title={`Canvasser: ${lead.job.canvasser}`}>{lead.job.canvasser}</span>
+        <span className="lead-updated">{lead.updated}</span>
+      </div>
+    </button>
+  );
+}
+
+/* ---------------------------------------------------------- */
+/* Lead detail popup                                           */
+/* ---------------------------------------------------------- */
+
+function LeadDetail({ lead, onClose }: { lead: Lead | null; onClose: () => void }) {
+  if (!lead) return null;
+  const status = STATUS_META[lead.status];
+  const priority = PRIORITY_META[lead.priority];
+
+  return (
+    <Modal
+      open={!!lead}
+      onClose={onClose}
+      size="lg"
+      title={lead.name}
+      subtitle={`${lead.id} · ${lead.tag}`}
+      icon="leads"
+      footer={
+        <>
+          <Btn variant="ghost" icon="phone">Call</Btn>
+          <Btn variant="outline" icon="mail">Email</Btn>
+          <Btn icon="check-circle">Update Status</Btn>
+        </>
+      }
+    >
+      <div className="lead-detail">
+        {/* identity strip */}
+        <div className="ld-identity">
+          <Avatar initials={lead.initials} gradient={lead.gradient} size={54} />
+          <div className="ld-identity-body">
+            <div className="ld-identity-name">{lead.name}</div>
+            <div className="ld-identity-pills">
+              <Pill tone={status.tone}>{status.label}</Pill>
+              <Pill tone={priority.tone}><Icon name="alert" size={11} /> {priority.label}</Pill>
+            </div>
+          </div>
+        </div>
+
+        {/* storm banner */}
+        <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>
+        </div>
+
+        <div className="ld-grid">
+          {/* Contact */}
+          <Section title="Contact" icon="user">
+            <div className="ld-sublabel">Phone Numbers</div>
+            {lead.phones.map((p, i) => (
+              <div className="ld-contact-row" key={i}>
+                <Icon name="phone" size={14} />
+                <span className="ld-contact-val">{p.number}</span>
+                <span className="ld-contact-tag">{p.type}</span>
+                {p.primary && <Pill tone="green">Primary</Pill>}
+              </div>
+            ))}
+            <div className="ld-sublabel">Email Addresses</div>
+            {lead.emails.map((e, i) => (
+              <div className="ld-contact-row" key={i}>
+                <Icon name="mail" size={14} />
+                <span className="ld-contact-val">{e.address}</span>
+                {e.primary && <Pill tone="green">Primary</Pill>}
+              </div>
+            ))}
+          </Section>
+
+          {/* Property */}
+          <Section title="Property" icon="owners">
+            <Dl label="Address" value={lead.property.address} />
+            <Dl label="City" value={lead.property.city} />
+            <Dl label="State" value={lead.property.state} />
+            <Dl label="ZIP" value={lead.property.zip} />
+            <Dl label="Property Type" value={lead.property.type} />
+          </Section>
+
+          {/* Job Details */}
+          <Section title="Job Details" icon="projects">
+            <Dl label="Lead Source" value={lead.job.source} />
+            <Dl label="Lead Type" value={lead.job.leadType} />
+            <Dl label="Work Type" value={lead.job.workType} />
+            <Dl label="Trade Type" value={lead.job.tradeType} />
+            <Dl label="Urgency" value={lead.job.urgency} />
+            <Dl label="Canvasser" value={lead.job.canvasser} />
+            <div className="ld-notes">
+              <div className="ld-sublabel">Field Notes</div>
+              <p>{lead.job.notes}</p>
+            </div>
+          </Section>
+
+          {/* Insurance */}
+          <Section title="Insurance" icon="shield">
+            <Dl label="Insurance Company" value={lead.insurance.company} />
+            <Dl label="Claim Status" value={lead.insurance.claimStatus} />
+            <Dl label="Claim Number" value={lead.insurance.claimNumber} />
+            <Dl label="Policy Number" value={lead.insurance.policyNumber} />
+            <Dl label="Adjuster Name" value={lead.insurance.adjusterName} />
+            <Dl label="Adjuster Phone" value={lead.insurance.adjusterPhone} />
+          </Section>
+
+          {/* Assignment */}
+          <Section title="Assignment" icon="team" wide>
+            <div className="ld-assign">
+              <Dl label="Assigned To" value={lead.assignment.assignedTo} />
+              <Dl label="Priority" value={lead.assignment.priority} />
+              <Dl label="Follow-Up Date" value={lead.assignment.followUp} />
+              <Dl label="Created By" value={lead.assignment.createdBy} />
+              <Dl label="Created At" value={lead.assignment.createdAt} />
+            </div>
+          </Section>
+        </div>
+      </div>
+    </Modal>
+  );
+}
+
+function Section({ title, icon, children, wide }: { title: string; icon: string; children: ReactNode; wide?: boolean }) {
+  return (
+    <div className={`ld-section ${wide ? "wide" : ""}`}>
+      <div className="ld-section-head"><Icon name={icon} size={15} /> {title}</div>
+      <div className="ld-section-body">{children}</div>
+    </div>
+  );
+}
+
+function Dl({ label, value }: { label: string; value: string }) {
+  return (
+    <div className="ld-dl">
+      <span className="ld-dl-k">{label}</span>
+      <span className="ld-dl-v">{value}</span>
+    </div>
+  );
+}
+
+/* ---------------------------------------------------------- */
+/* New Lead — Quick / Full Form intake                         */
+/* ---------------------------------------------------------- */
+
+type Priority = "Low" | "Medium" | "High";
+type Urgency = "Standard" | "High" | "Emergency";
+type PhoneRow = { number: string; type: string };
+type EmailRow = { address: string };
+
+const FULL_STEPS = [
+  { value: "contact", label: "Contact", icon: "user" },
+  { value: "property", label: "Property", icon: "owners" },
+  { value: "job", label: "Job Details", icon: "projects" },
+  { value: "insurance", label: "Insurance", icon: "shield" },
+  { value: "assignment", label: "Assignment", icon: "team" },
+];
+
+const LEAD_TYPE_OPTS = ["Residential", "Commercial", "Multi-Family"];
+const PROPERTY_TYPE_OPTS = ["Residential", "Commercial", "Multi-Family", "Industrial"];
+
+const BLANK = {
+  firstName: "", lastName: "",
+  phones: [{ number: "", type: "Mobile" }] as PhoneRow[],
+  emails: [] as EmailRow[],
+  address: "", city: "", state: "TX", zip: "", propertyType: "",
+  photos: [] as string[],
+  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 }) {
+  const toast = useToast();
+  const [mode, setMode] = useState<"quick" | "full">("quick");
+  const [section, setSection] = useState("contact");
+  const [f, setF] = useState({ ...BLANK });
+
+  const set = (k: string) => (e: { target: { value: string } }) =>
+    setF((s) => ({ ...s, [k]: e.target.value }) as typeof BLANK);
+
+  // multi-value handlers
+  const addPhone = () => setF((s) => ({ ...s, phones: [...s.phones, { number: "", type: "Mobile" }] }));
+  const setPhone = (i: number, key: "number" | "type", v: string) => setF((s) => ({ ...s, phones: s.phones.map((p, j) => (j === i ? { ...p, [key]: v } : p)) }));
+  const removePhone = (i: number) => setF((s) => ({ ...s, phones: s.phones.filter((_, j) => j !== i) }));
+  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}`] }));
+
+  function reset() { setF({ ...BLANK, phones: [{ number: "", type: "Mobile" }], emails: [], photos: [] }); setMode("quick"); setSection("contact"); }
+  function close() { reset(); onClose(); }
+
+  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; }
+    toast.push({ tone: "success", title: "Lead created", desc: `${name} added to the Plano pipeline.` });
+    close();
+  }
+
+  const repOptions = [{ id: "", initials: "—", name: "Unassigned" }, ...REPS];
+
+  const stepIdx = FULL_STEPS.findIndex((s) => s.value === section);
+  const isFirstStep = stepIdx <= 0;
+  const isLastStep = stepIdx === FULL_STEPS.length - 1;
+  const goNext = () => { if (!isLastStep) setSection(FULL_STEPS[stepIdx + 1].value); };
+  const goBack = () => { if (!isFirstStep) setSection(FULL_STEPS[stepIdx - 1].value); };
+
+  return (
+    <Modal
+      open={open}
+      onClose={close}
+      size="lg"
+      title="New Lead"
+      subtitle="Full lead profile with insurance and assignment details."
+      icon="plus"
+      footer={
+        mode === "full" ? (
+          <>
+            <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="arrow" onClick={goNext}>Next</Btn>}
+          </>
+        ) : (
+          <>
+            <Btn variant="ghost" onClick={close}>Cancel</Btn>
+            <Btn icon="check" onClick={submit}>Create Lead</Btn>
+          </>
+        )
+      }
+    >
+      <div className="nl-form">
+        <Segmented
+          value={mode}
+          onChange={(v) => setMode(v as "quick" | "full")}
+          options={[{ value: "quick", label: "Quick", icon: "star" }, { value: "full", label: "Full Form", icon: "edit" }]}
+        />
+
+        {mode === "quick" ? (
+          <div className="nl-grid">
+            <Field label="First name" required><input className="ds-input" value={f.firstName} onChange={set("firstName")} placeholder="John" /></Field>
+            <Field label="Last name"><input className="ds-input" value={f.lastName} onChange={set("lastName")} placeholder="Smith" /></Field>
+            <Field label="Phone"><input className="ds-input" value={f.phones[0]?.number ?? ""} onChange={(e) => setPhone(0, "number", e.target.value)} placeholder="(555) 000-0000" /></Field>
+            <div className="nl-full"><Field label="Street address"><input className="ds-input" value={f.address} onChange={set("address")} placeholder="123 Main St" /></Field></div>
+            <Field label="City"><input className="ds-input" value={f.city} onChange={set("city")} placeholder="Plano" /></Field>
+            <Field label="State"><input className="ds-input" value={f.state} onChange={set("state")} /></Field>
+            <Field label="ZIP"><input className="ds-input" value={f.zip} onChange={set("zip")} placeholder="75023" /></Field>
+            <Field label="Lead source"><Select value={f.source} onChange={set("source")} options={LEAD_SOURCES} placeholder="How did you find this lead?" /></Field>
+            {f.source === "Referral" && (
+              <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"><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>
+          </div>
+        ) : (
+          <>
+            <SegTabs
+              value={section}
+              onChange={setSection}
+              tabs={FULL_STEPS}
+            />
+
+            {section === "contact" && (
+              <div className="nl-grid">
+                <Field label="First Name" required><input className="ds-input" value={f.firstName} onChange={set("firstName")} placeholder="John" /></Field>
+                <Field label="Last Name"><input className="ds-input" value={f.lastName} onChange={set("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>
+            )}
+
+            {section === "property" && (
+              <div className="nl-grid">
+                <div className="nl-full"><Field label="Street Address"><input className="ds-input" value={f.address} onChange={set("address")} placeholder="123 Main St" /></Field></div>
+                <Field label="City"><input className="ds-input" value={f.city} onChange={set("city")} placeholder="Plano" /></Field>
+                <Field label="State"><input className="ds-input" value={f.state} onChange={set("state")} placeholder="TX" /></Field>
+                <Field label="ZIP"><input className="ds-input" value={f.zip} onChange={set("zip")} placeholder="75023" /></Field>
+                <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}>
+                    <Icon name="camera" size={22} />
+                    <span className="nl-photos-t">Tap to add photos</span>
+                    <span className="nl-photos-s">Camera · Gallery · Multiple allowed</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>)}
+                    </div>
+                  )}
+                </div>
+              </div>
+            )}
+
+            {section === "job" && (
+              <div className="nl-grid">
+                <Field label="Lead Source"><Select value={f.source} onChange={set("source")} options={LEAD_SOURCES} placeholder="How did you find this lead?" /></Field>
+                <Field label="Lead Type"><Select value={f.leadType} onChange={set("leadType")} options={LEAD_TYPE_OPTS} placeholder="Residential, Commercial…" /></Field>
+                <Field label="Work Type"><Select value={f.workType} onChange={set("workType")} options={WORK_TYPES} placeholder="Roof Replacement, Repair…" /></Field>
+                <Field label="Trade Type"><Select value={f.tradeType} onChange={set("tradeType")} options={TRADE_TYPES} placeholder="Roofing, Gutter, Siding…" /></Field>
+                <div className="nl-full"><UrgencyPicker value={f.urgency} onChange={(u) => setF((s) => ({ ...s, urgency: u }))} /></div>
+                <div className="nl-full"><Field label="Notes"><textarea className="ds-textarea" rows={3} value={f.notes} onChange={set("notes")} placeholder="First impression, visible damage, special circumstances…" /></Field></div>
+              </div>
+            )}
+
+            {section === "insurance" && (
+              <div className="nl-grid">
+                <div className="nl-full"><Field label="Insurance Company"><input className="ds-input" value={f.insCompany} onChange={set("insCompany")} placeholder="State Farm" /></Field></div>
+                <Field label="Claim Number"><input className="ds-input" value={f.claimNumber} onChange={set("claimNumber")} placeholder="e.g. CLM-2026-00482" /></Field>
+                <Field label="Claim Status"><Select value={f.claimStatus} onChange={set("claimStatus")} options={CLAIM_STATUSES} placeholder="Select status…" /></Field>
+                <Field label="Adjuster Name"><input className="ds-input" value={f.adjusterName} onChange={set("adjusterName")} placeholder="Full name" /></Field>
+                <Field label="Adjuster Phone"><input className="ds-input" value={f.adjusterPhone} onChange={set("adjusterPhone")} placeholder="(555) 000-0000" /></Field>
+                <div className="nl-full"><Field label="Policy Number"><input className="ds-input" value={f.policyNumber} onChange={set("policyNumber")} placeholder="e.g. POL-7734892-A" /></Field></div>
+              </div>
+            )}
+
+            {section === "assignment" && (
+              <div className="nl-grid">
+                <div className="nl-full"><Field label="Assign Rep"><RepSelect value={f.assignRep} onChange={set("assignRep")} options={repOptions} /></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>
+              </div>
+            )}
+          </>
+        )}
+      </div>
+    </Modal>
+  );
+}
+
+function Select({ value, onChange, options, placeholder }: { value: string; onChange: (e: { target: { value: string } }) => void; options: string[]; placeholder?: string }) {
+  return (
+    <select className={`ds-select ${!value && placeholder ? "is-placeholder" : ""}`} value={value} onChange={onChange}>
+      {placeholder && <option value="" disabled>{placeholder}</option>}
+      {options.map((o) => <option key={o} value={o}>{o}</option>)}
+    </select>
+  );
+}
+
+function RepSelect({ value, onChange, options }: { value: string; onChange: (e: { target: { value: string } }) => void; options: { id: string; initials: string; name: string }[] }) {
+  return (
+    <select className="ds-select" value={value} onChange={onChange}>
+      {options.map((r) => <option key={r.id || "none"} value={r.id}>{r.id ? `${r.name} · ${r.id}` : "— Unassigned"}</option>)}
+    </select>
+  );
+}
+
+function CanvasserSearch({ value, onChange, options }: { value: string; onChange: (v: string) => void; options: { id: string; initials: string; name: string; email: string }[] }) {
+  const [query, setQuery] = useState("");
+  const [open, setOpen] = useState(false);
+  const selected = options.find((o) => o.id === value);
+  const matches = useMemo(() => {
+    const q = query.trim().toLowerCase();
+    if (!q) return options;
+    return options.filter((o) => o.name.toLowerCase().includes(q) || o.email.toLowerCase().includes(q));
+  }, [query, options]);
+
+  if (selected) {
+    return (
+      <div className="nl-canvasser-chip">
+        <Avatar initials={selected.initials} size={28} />
+        <span className="nl-canvasser-name">{selected.name}</span>
+        <span className="nl-canvasser-email">{selected.email}</span>
+        <button type="button" className="nl-canvasser-clear" onClick={() => { onChange(""); setQuery(""); }} aria-label="Clear canvasser"><Icon name="x" size={14} /></button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="nl-canvasser">
+      <input
+        className="ds-input"
+        value={query}
+        onChange={(e) => { setQuery(e.target.value); setOpen(true); }}
+        onFocus={() => setOpen(true)}
+        onBlur={() => setTimeout(() => setOpen(false), 150)}
+        placeholder="Search canvasser by name or email"
+      />
+      {open && matches.length > 0 && (
+        <div className="nl-canvasser-menu">
+          {matches.map((o) => (
+            <button key={o.id} type="button" className="nl-canvasser-opt" onMouseDown={(e) => { e.preventDefault(); onChange(o.id); setQuery(""); setOpen(false); }}>
+              <Avatar initials={o.initials} size={26} />
+              <span className="nl-canvasser-name">{o.name}</span>
+              <span className="nl-canvasser-email">{o.email}</span>
+            </button>
+          ))}
+        </div>
+      )}
+      {open && matches.length === 0 && (
+        <div className="nl-canvasser-menu"><div className="nl-canvasser-empty">No canvasser found</div></div>
+      )}
+    </div>
+  );
+}
+
+function PriorityPicker({ value, onChange }: { value: Priority; onChange: (p: Priority) => void }) {
+  return (
+    <div className="ds-field">
+      <span className="ds-field-lbl">Priority</span>
+      <div className="nl-prio">
+        {(["Low", "Medium", "High"] as Priority[]).map((p) => (
+          <button key={p} type="button" className={`nl-prio-btn ${value === p ? `active ${p.toLowerCase()}` : ""}`} onClick={() => onChange(p)}>{p}</button>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function UrgencyPicker({ value, onChange }: { value: Urgency; onChange: (u: Urgency) => void }) {
+  return (
+    <div className="ds-field">
+      <span className="ds-field-lbl">Urgency</span>
+      <div className="nl-prio">
+        {(["Standard", "High", "Emergency"] as Urgency[]).map((u) => (
+          <button key={u} type="button" className={`nl-prio-btn urg ${value === u ? `active ${u.toLowerCase()}` : ""}`} onClick={() => onChange(u)}>{u}</button>
+        ))}
+      </div>
+    </div>
+  );
+}

src/components/dashboard/mail.tsx

@@ -0,0 +1,231 @@
+"use client";
+
+// ============================================================
+// Mail components used INSIDE the Inbox (not a separate tab).
+// The Inbox is the one unified surface — mentions, system messages
+// and mail all live there. These render the mail body + reply, and
+// compose a new message. HTML bodies render in a sandboxed iframe.
+// ============================================================
+
+import { type CSSProperties, useEffect, useRef, useState } from "react";
+import { Avatar, Btn, Field, Icon, Modal, Pill } from "./ui";
+import { useMailThread, useMailCompose, type MailAttachment, type MailPerson } from "@/lib/mail-api";
+import { useUploadAttachment, useDownloadUrl, isImage, type UploadedAttachment } from "@/lib/media-api";
+
+const timeOf = (iso?: string) => {
+  if (!iso) return "";
+  const d = new Date(iso);
+  return Number.isNaN(+d) ? "" : d.toLocaleString([], { month: "short", day: "numeric", hour: "2-digit", minute: "2-digit" });
+};
+const CUSTOMER_GRAD = "linear-gradient(135deg,#10b981,#059669)";
+const inputStyle: CSSProperties = {
+  width: "100%", padding: "9px 12px", borderRadius: 10, border: "1px solid var(--border)",
+  background: "var(--panel)", color: "var(--text)", fontSize: 14, outline: "none",
+};
+
+function fmtBytes(n: number): string {
+  if (!n) return "";
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(0)} KB`;
+  return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/** Resolves a signed URL for a stored attachment and renders it inline (image) or as a file chip. */
+function MailAttachmentView({ att }: { att: MailAttachment }) {
+  const getUrl = useDownloadUrl();
+  const [url, setUrl] = useState<string | null>(null);
+  useEffect(() => {
+    let alive = true;
+    getUrl(att.contentRef, att.mimeType).then((u) => { if (alive) setUrl(u); }).catch(() => {});
+    return () => { alive = false; };
+  }, [att.contentRef, att.mimeType, getUrl]);
+
+  const label = att.filename || "Attachment";
+  if (isImage(att.mimeType)) {
+    return url
+      ? <a href={url} target="_blank" rel="noreferrer" style={{ display: "inline-block" }}><img src={url} alt={label} style={{ maxWidth: 320, maxHeight: 240, borderRadius: 8, border: "1px solid var(--border)" }} /></a>
+      : <div style={{ color: "var(--muted)", fontSize: 13 }}>Loading image…</div>;
+  }
+  return (
+    <a href={url ?? "#"} target="_blank" rel="noreferrer"
+      style={{ display: "inline-flex", alignItems: "center", gap: 8, padding: "8px 12px", borderRadius: 10, border: "1px solid var(--border)", background: "var(--panel-2)", color: "var(--text)", textDecoration: "none", maxWidth: 320 }}>
+      <Icon name="paperclip" size={18} />
+      <span style={{ flex: 1, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>{label}</span>
+      {att.sizeBytes > 0 && <span style={{ color: "var(--muted)", fontSize: 12 }}>{fmtBytes(att.sizeBytes)}</span>}
+    </a>
+  );
+}
+
+/** A small staged-file chip shown in a composer before send, with a remove button. */
+function StagedChip({ file, onRemove }: { file: UploadedAttachment; onRemove: () => void }) {
+  return (
+    <div style={{ display: "inline-flex", alignItems: "center", gap: 8, padding: "5px 10px", borderRadius: 999, background: "var(--panel-2)", border: "1px solid var(--border)", fontSize: 13 }}>
+      <Icon name="paperclip" size={14} />
+      <span style={{ maxWidth: 160, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>{file.filename}</span>
+      <span style={{ color: "var(--muted)" }}>{fmtBytes(file.sizeBytes)}</span>
+      <button onClick={onRemove} title="Remove" style={{ background: "none", border: "none", color: "var(--muted)", cursor: "pointer", padding: 0, lineHeight: 1 }}>✕</button>
+    </div>
+  );
+}
+
+/** Reader + reply for one mail thread. Used in the Inbox detail pane when an item has a threadId. */
+export function MailReader({ threadId, subject, onError }: { threadId: string; subject: string; onError: (m: string) => void }) {
+  const t = useMailThread(threadId);
+  const upload = useUploadAttachment();
+  const [draft, setDraft] = useState("");
+  const [sending, setSending] = useState(false);
+  const [staged, setStaged] = useState<UploadedAttachment | null>(null);
+  const [uploading, setUploading] = useState(false);
+  const fileRef = useRef<HTMLInputElement>(null);
+
+  async function onPickFile(e: React.ChangeEvent<HTMLInputElement>) {
+    const file = e.target.files?.[0];
+    e.target.value = "";
+    if (!file) return;
+    setUploading(true);
+    try { setStaged(await upload(file)); }
+    catch (err) { onError((err as Error).message); }
+    finally { setUploading(false); }
+  }
+
+  async function reply() {
+    const text = draft.trim();
+    if ((!text && !staged) || sending) return;
+    const att = staged ?? undefined;
+    setDraft(""); setStaged(null); setSending(true);
+    try { await t.reply(text, att); }
+    catch (e) { setDraft(text); setStaged(att ?? null); onError((e as Error).message); }
+    finally { setSending(false); }
+  }
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", height: "100%", minHeight: 0 }}>
+      <header style={{ padding: "12px 18px", borderBottom: "1px solid var(--border)" }}>
+        <div style={{ fontWeight: 700, fontSize: 15 }}>{subject || "(no subject)"}</div>
+      </header>
+      <div style={{ flex: 1, overflowY: "auto", padding: 16, display: "flex", flexDirection: "column", gap: 12 }}>
+        {t.loading && t.messages.length === 0 && <div style={{ margin: "auto", color: "var(--muted)" }}>Loading…</div>}
+        {!t.loading && t.messages.length === 0 && <div style={{ margin: "auto", color: "var(--muted)" }}>No messages.</div>}
+        {t.messages.map((m) => (
+          <div key={m.interactionId} style={{ border: "1px solid var(--border)", borderRadius: 12, background: "var(--panel)", overflow: "hidden" }}>
+            <div style={{ padding: "7px 12px", borderBottom: "1px solid var(--border)", display: "flex", justifyContent: "space-between", fontSize: 12, color: "var(--muted)" }}>
+              <span>{m.kind === "EMAIL" ? "Email" : "Reply"}{m.actorId ? ` · ${m.actorId.replace(/^(pp_|cust_)/, "").slice(0, 8)}` : ""}</span>
+              <span>{timeOf(m.occurredAt)}</span>
+            </div>
+            {m.html
+              ? <iframe sandbox="" srcDoc={m.html} title="mail body" style={{ width: "100%", height: 200, border: "none", background: "#fff" }} />
+              : m.text
+                ? <div style={{ padding: 12, whiteSpace: "pre-wrap", wordBreak: "break-word", fontSize: 14 }}>{m.text}</div>
+                : null}
+            {m.attachment && <div style={{ padding: 12, paddingTop: m.html || m.text ? 0 : 12 }}><MailAttachmentView att={m.attachment} /></div>}
+          </div>
+        ))}
+      </div>
+      <footer style={{ display: "flex", flexDirection: "column", gap: 8, padding: 12, borderTop: "1px solid var(--border)" }}>
+        {staged && <div><StagedChip file={staged} onRemove={() => setStaged(null)} /></div>}
+        <div style={{ display: "flex", gap: 8 }}>
+          <input ref={fileRef} type="file" style={{ display: "none" }} onChange={onPickFile} />
+          <Btn variant="ghost" icon="paperclip" onClick={() => fileRef.current?.click()} disabled={uploading}>{uploading ? "…" : ""}</Btn>
+          <input
+            value={draft} onChange={(e) => setDraft(e.target.value)}
+            onKeyDown={(e) => { if (e.key === "Enter" && !e.shiftKey) { e.preventDefault(); void reply(); } }}
+            placeholder="Reply…" style={inputStyle}
+          />
+          <Btn icon="send" onClick={() => void reply()} disabled={sending || (!draft.trim() && !staged)}>Reply</Btn>
+        </div>
+      </footer>
+    </div>
+  );
+}
+
+/** Compose a new message — in-app (to a person) or external (to an email). */
+export function NewMailModal({ open, onClose, onSent, onError }: { open: boolean; onClose: () => void; onSent: () => void; onError: (m: string) => void }) {
+  const compose = useMailCompose(onSent);
+  const upload = useUploadAttachment();
+  const [mode, setMode] = useState<"internal" | "external">("internal");
+  const [recipient, setRecipient] = useState("");
+  const [subject, setSubject] = useState("");
+  const [body, setBody] = useState("");
+  const [q, setQ] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [staged, setStaged] = useState<UploadedAttachment[]>([]);
+  const [uploading, setUploading] = useState(false);
+  const fileRef = useRef<HTMLInputElement>(null);
+
+  useEffect(() => { if (!open) { setMode("internal"); setRecipient(""); setSubject(""); setBody(""); setQ(""); setBusy(false); setStaged([]); setUploading(false); } }, [open]);
+
+  async function onPickFile(e: React.ChangeEvent<HTMLInputElement>) {
+    const files = Array.from(e.target.files ?? []);
+    e.target.value = "";
+    if (!files.length) return;
+    setUploading(true);
+    try {
+      const uploaded = await Promise.all(files.map((f) => upload(f)));
+      setStaged((s) => [...s, ...uploaded].slice(0, 10));
+    } catch (err) { onError((err as Error).message); }
+    finally { setUploading(false); }
+  }
+
+  const filtered = compose.directory.filter((p) => p.name.toLowerCase().includes(q.trim().toLowerCase()));
+  const canSend = !!recipient && !!subject.trim() && !!body.trim() && !busy && !uploading;
+
+  async function send() {
+    if (!canSend) return;
+    setBusy(true);
+    try {
+      if (mode === "internal") await compose.sendInternal(recipient, subject.trim(), body.trim(), staged.length ? staged : undefined);
+      else await compose.sendExternal(recipient.trim(), subject.trim(), body.trim(), staged.length ? { attachments: staged } : undefined);
+    } catch (e) { onError((e as Error).message); }
+    finally { setBusy(false); }
+  }
+
+  return (
+    <Modal
+      open={open} onClose={onClose} title="New message" subtitle={mode === "internal" ? "To a team member or client (in-app)" : "To an email address"} icon="chat"
+      footer={<>
+        <Btn variant="ghost" onClick={onClose}>Cancel</Btn>
+        <Btn icon="send" onClick={() => void send()} disabled={!canSend}>{busy ? "Sending…" : "Send"}</Btn>
+      </>}
+    >
+      <div style={{ display: "flex", gap: 6, marginBottom: 12 }}>
+        <Btn variant={mode === "internal" ? "primary" : "outline"} onClick={() => { setMode("internal"); setRecipient(""); }}>In-app</Btn>
+        <Btn variant={mode === "external" ? "primary" : "outline"} onClick={() => { setMode("external"); setRecipient(""); }}>Email</Btn>
+      </div>
+
+      {mode === "internal" ? (
+        <Field label="To (person)">
+          <input value={q} onChange={(e) => setQ(e.target.value)} placeholder="Search people…" style={{ ...inputStyle, marginBottom: 8 }} />
+          <div style={{ maxHeight: 180, overflowY: "auto", display: "flex", flexDirection: "column", gap: 2 }}>
+            {filtered.length === 0 && <div style={{ color: "var(--muted)", padding: 8 }}>No people found.</div>}
+            {filtered.map((p: MailPerson) => (
+              <label key={p.id} style={{ display: "flex", alignItems: "center", gap: 10, padding: "7px 10px", borderRadius: 10, cursor: "pointer", background: recipient === p.id ? "var(--panel-2)" : "transparent" }}>
+                <input type="radio" checked={recipient === p.id} onChange={() => setRecipient(p.id)} />
+                <Avatar initials={(p.name.split(/\s+/).map((s) => s[0]).join("").slice(0, 2) || "?").toUpperCase()} size={26} gradient={p.kind === "customer" ? CUSTOMER_GRAD : undefined} />
+                <span style={{ flex: 1 }}>{p.name}</span>
+                <Pill tone="muted">{p.kind}</Pill>
+              </label>
+            ))}
+          </div>
+        </Field>
+      ) : (
+        <Field label="To (email)">
+          <input value={recipient} onChange={(e) => setRecipient(e.target.value)} placeholder="name@company.com" style={inputStyle} />
+        </Field>
+      )}
+
+      <Field label="Subject"><input value={subject} onChange={(e) => setSubject(e.target.value)} placeholder="Subject" style={inputStyle} /></Field>
+      <Field label="Message"><textarea value={body} onChange={(e) => setBody(e.target.value)} placeholder="Write your message…" rows={6} style={{ ...inputStyle, resize: "vertical" }} /></Field>
+
+      {/* NOT a <Field> (which is a <label>): a label wrapping the file input would hijack the
+          Attach button's click via label→input association and open the picker erratically. */}
+      <div className="ds-field">
+        <span className="ds-field-lbl">Attachments</span>
+        <input ref={fileRef} type="file" multiple style={{ display: "none" }} onChange={onPickFile} />
+        <div style={{ display: "flex", flexWrap: "wrap", gap: 8, alignItems: "center" }}>
+          <Btn variant="outline" icon="paperclip" onClick={() => fileRef.current?.click()} disabled={uploading || staged.length >= 10}>{uploading ? "Uploading…" : "Attach"}</Btn>
+          {staged.map((f, i) => <StagedChip key={`${f.contentRef}_${i}`} file={f} onRemove={() => setStaged((s) => s.filter((_, j) => j !== i))} />)}
+        </div>
+      </div>
+    </Modal>
+  );
+}

src/components/dashboard/messenger.tsx

@@ -0,0 +1,550 @@
+"use client";
+
+// ============================================================
+// Messenger — internal team + client chat, powered by IIOS via
+// the be-crm data door (crm.messenger.*). Conversation list ⇄
+// thread view + composer, with a "new chat" people picker that
+// creates a DM (1 person) or group (2+). DM-vs-group and who-can-
+// chat are enforced server-side by IIOS/OPA; this is just UI.
+// Live messages, typing, read receipts and reactions come over the
+// IIOS socket (Shell mode); mock keeps the demo working offline.
+// ============================================================
+
+import { type CSSProperties, useEffect, useMemo, useRef, useState } from "react";
+import { Avatar, Btn, Field, Icon, Modal, PageHead, Pill, useToast } from "./ui";
+import { useMessengerData, useThread, useGroupSettings, type Membership, type UiAttachment, type UiConversation, type UiMember, type UiMessage, type UiPerson } from "@/lib/messenger-api";
+import { MessengerSocketProvider, useMessengerSocket } from "@/lib/messenger-socket";
+import { useUploadAttachment, useDownloadUrl, isImage, type UploadedAttachment } from "@/lib/media-api";
+
+const fmtBytes = (n: number) => (n < 1024 ? `${n} B` : n < 1048576 ? `${(n / 1024).toFixed(0)} KB` : `${(n / 1048576).toFixed(1)} MB`);
+
+/** Renders a message attachment — an inline image thumbnail, or a downloadable file chip. */
+function AttachmentView({ att }: { att: UiAttachment }) {
+  const getUrl = useDownloadUrl();
+  const [url, setUrl] = useState<string | null>(null);
+  useEffect(() => {
+    let alive = true;
+    getUrl(att.contentRef, att.mimeType).then((u) => { if (alive) setUrl(u); }).catch(() => {});
+    return () => { alive = false; };
+  }, [att.contentRef, att.mimeType, getUrl]);
+
+  if (isImage(att.mimeType)) {
+    return url ? (
+      // eslint-disable-next-line @next/next/no-img-element
+      <a href={url} target="_blank" rel="noreferrer"><img src={url} alt="attachment" style={{ maxWidth: 240, maxHeight: 240, borderRadius: 10, display: "block", marginTop: 6, border: "1px solid var(--border)" }} /></a>
+    ) : <div style={{ marginTop: 6, color: "var(--muted)", fontSize: 12 }}>Loading image…</div>;
+  }
+  return (
+    <a href={url ?? "#"} target={url ? "_blank" : undefined} rel="noreferrer"
+       style={{ display: "flex", alignItems: "center", gap: 8, marginTop: 6, padding: "8px 12px", borderRadius: 10, background: "var(--panel-2)", border: "1px solid var(--border)", textDecoration: "none", color: "var(--text)", maxWidth: 240 }}>
+      <Icon name="paperclip" size={18} />
+      <span style={{ flex: 1, minWidth: 0, whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis", fontSize: 13 }}>Attachment</span>
+      <span style={{ color: "var(--muted)", fontSize: 12, flexShrink: 0 }}>{fmtBytes(att.sizeBytes)}</span>
+    </a>
+  );
+}
+
+const initialsOf = (name: string) =>
+  name.split(/\s+/).filter(Boolean).slice(0, 2).map((p) => p[0]).join("").toUpperCase() || "?";
+const timeOf = (iso?: string) => {
+  if (!iso) return "";
+  const d = new Date(iso);
+  return Number.isNaN(+d) ? "" : d.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+};
+const GROUP_GRAD = "linear-gradient(135deg,#6366f1,#8b5cf6)";
+const CUSTOMER_GRAD = "linear-gradient(135deg,#10b981,#059669)";
+const REACTION_EMOJIS = ["👍", "❤️", "😂", "😮", "😢", "🎉"];
+const inputStyle: CSSProperties = {
+  width: "100%", padding: "9px 12px", borderRadius: 10, border: "1px solid var(--border)",
+  background: "var(--panel)", color: "var(--text)", fontSize: 14, outline: "none",
+};
+
+export function Messenger() {
+  // One shared IIOS socket for the whole panel (live in Shell mode; no-op in mock).
+  return (
+    <MessengerSocketProvider>
+      <MessengerPanel />
+    </MessengerSocketProvider>
+  );
+}
+
+function MessengerPanel() {
+  const m = useMessengerData();
+  const toast = useToast();
+  const [selected, setSelected] = useState<string | null>(null);
+  const [newOpen, setNewOpen] = useState(false);
+
+  useEffect(() => {
+    if ((!selected || !m.conversations.some((c) => c.threadId === selected)) && m.conversations[0]) {
+      setSelected(m.conversations[0].threadId);
+    }
+  }, [m.conversations, selected]);
+
+  const current = m.conversations.find((c) => c.threadId === selected) ?? null;
+
+  return (
+    <div className="view">
+      <PageHead
+        eyebrow="Communication" title="Messenger" subtitle="Chat with your team and clients — direct or in groups" icon="send"
+        actions={<Btn icon="plus" onClick={() => setNewOpen(true)}>New chat</Btn>}
+      />
+      {!m.live && (
+        <div style={{ margin: "0 0 14px", padding: "8px 14px", borderRadius: 10, background: "var(--panel-2)", color: "var(--muted)", fontSize: 13, border: "1px solid var(--border)" }}>
+          Demo mode — running on mock data. It goes live once the Shell + be-crm are connected.
+        </div>
+      )}
+
+      <div className="card" style={{ display: "flex", height: 620, padding: 0, overflow: "hidden" }}>
+        <aside style={{ width: 296, borderRight: "1px solid var(--border)", overflowY: "auto", background: "var(--panel)" }}>
+          {m.loading && <div style={{ padding: 16, color: "var(--muted)" }}>Loading…</div>}
+          {!m.loading && m.conversations.length === 0 && (
+            <div style={{ padding: 16, color: "var(--muted)" }}>No conversations yet. Start a new chat.</div>
+          )}
+          {m.conversations.map((c) => (
+            <ConversationRow key={c.threadId} c={c} active={c.threadId === selected} onClick={() => setSelected(c.threadId)} />
+          ))}
+        </aside>
+
+        <section style={{ flex: 1, display: "flex", flexDirection: "column", minWidth: 0 }}>
+          {current ? (
+            <ThreadView key={current.threadId} conv={current} nameOf={m.nameOf} directory={m.directory} onError={(msg) => toast.push({ tone: "error", title: "Message failed", desc: msg })} />
+          ) : (
+            <div style={{ margin: "auto", color: "var(--muted)", textAlign: "center" }}>
+              <Icon name="send" size={38} />
+              <p>Select or start a conversation</p>
+            </div>
+          )}
+        </section>
+      </div>
+
+      <NewChatModal
+        open={newOpen} onClose={() => setNewOpen(false)} directory={m.directory}
+        onCreate={async (ids, opts) => {
+          try {
+            const id = await m.openConversation(ids, opts);
+            setSelected(id);
+            setNewOpen(false);
+          } catch (e) {
+            toast.push({ tone: "error", title: "Couldn't start chat", desc: (e as Error).message });
+          }
+        }}
+      />
+    </div>
+  );
+}
+
+function ConversationRow({ c, active, onClick }: { c: UiConversation; active: boolean; onClick: () => void }) {
+  return (
+    <button
+      onClick={onClick}
+      style={{
+        display: "flex", gap: 10, alignItems: "center", width: "100%", textAlign: "left",
+        padding: "10px 14px", border: "none", borderBottom: "1px solid var(--border)", cursor: "pointer",
+        background: active ? "var(--panel-2)" : "transparent", color: "var(--text)",
+      }}
+    >
+      <Avatar initials={initialsOf(c.title)} size={38} gradient={c.membership === "group" ? GROUP_GRAD : undefined} />
+      <div style={{ flex: 1, minWidth: 0 }}>
+        <div style={{ display: "flex", justifyContent: "space-between", gap: 8, alignItems: "center" }}>
+          <span style={{ fontWeight: 600, whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" }}>{c.title}</span>
+          <span style={{ color: "var(--muted)", fontSize: 11, flexShrink: 0 }}>{timeOf(c.lastAt)}</span>
+        </div>
+        <div style={{ display: "flex", justifyContent: "space-between", gap: 8, alignItems: "center" }}>
+          <span style={{ color: "var(--muted)", fontSize: 12.5, whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" }}>
+            {c.lastMessage ?? "No messages yet"}
+          </span>
+          {c.unread > 0 && (
+            <span style={{ background: "var(--orange)", color: "#fff", borderRadius: 999, fontSize: 11, padding: "1px 7px", flexShrink: 0 }}>{c.unread}</span>
+          )}
+        </div>
+      </div>
+    </button>
+  );
+}
+
+function ThreadView({ conv, nameOf, directory, onError }: { conv: UiConversation; nameOf: (id: string) => string; directory: UiPerson[]; onError: (m: string) => void }) {
+  const t = useThread(conv.threadId);
+  const socket = useMessengerSocket();
+  const [draft, setDraft] = useState("");
+  const [sending, setSending] = useState(false);
+  const [replyTo, setReplyTo] = useState<UiMessage | null>(null);
+  const [flashId, setFlashId] = useState<string | null>(null);
+  const endRef = useRef<HTMLDivElement>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const msgRefs = useRef<Map<string, HTMLElement>>(new Map());
+  const typingSentAt = useRef(0);
+
+  useEffect(() => { endRef.current?.scrollIntoView({ behavior: "smooth" }); }, [t.messages.length]);
+
+  const byId = useMemo(() => Object.fromEntries(t.messages.map((m) => [m.id, m])), [t.messages]);
+  const lastMineId = useMemo(() => [...t.messages].reverse().find((m) => m.mine)?.id ?? null, [t.messages]);
+
+  // Reply → focus the composer (bug: it didn't focus, forcing a manual click).
+  function startReply(msg: UiMessage) {
+    setReplyTo(msg);
+    requestAnimationFrame(() => inputRef.current?.focus());
+  }
+  // Click a quoted message → scroll to the original and flash it.
+  function jumpTo(id: string) {
+    const el = msgRefs.current.get(id);
+    if (!el) return;
+    el.scrollIntoView({ behavior: "smooth", block: "center" });
+    setFlashId(id);
+    setTimeout(() => setFlashId((f) => (f === id ? null : f)), 1200);
+  }
+
+  const uploadAttachment = useUploadAttachment();
+  const [staged, setStaged] = useState<UploadedAttachment | null>(null);
+  const [uploading, setUploading] = useState(false);
+  const fileRef = useRef<HTMLInputElement>(null);
+
+  function onDraftChange(v: string) {
+    setDraft(v);
+    const now = Date.now();
+    if (socket && now - typingSentAt.current > 2000) { socket.sendTyping(conv.threadId); typingSentAt.current = now; }
+  }
+
+  async function onPickFile(file: File | undefined) {
+    if (!file) return;
+    setUploading(true);
+    try { setStaged(await uploadAttachment(file)); }
+    catch (e) { onError((e as Error).message); }
+    finally { setUploading(false); if (fileRef.current) fileRef.current.value = ""; }
+  }
+
+  async function submit() {
+    const text = draft.trim();
+    if ((!text && !staged) || sending) return; // allow an attachment with no text
+    const parent = replyTo?.id;
+    const att = staged;
+    setDraft(""); setReplyTo(null); setStaged(null); setSending(true);
+    try {
+      await t.send(text, {
+        ...(parent ? { parentInteractionId: parent } : {}),
+        ...(att ? { attachment: { contentRef: att.contentRef, mimeType: att.mimeType, sizeBytes: att.sizeBytes } } : {}),
+      });
+    } catch (e) { setDraft(text); setStaged(att); onError((e as Error).message); }
+    finally { setSending(false); }
+  }
+
+  const [settingsOpen, setSettingsOpen] = useState(false);
+
+  const typingLabel = t.typingUserIds.length === 1
+    ? `${nameOf(t.typingUserIds[0])} is typing…`
+    : t.typingUserIds.length > 1 ? "Several people are typing…" : "";
+
+  return (
+    <>
+      <header style={{ display: "flex", alignItems: "center", gap: 10, padding: "12px 18px", borderBottom: "1px solid var(--border)" }}>
+        <Avatar initials={initialsOf(conv.title)} size={34} gradient={conv.membership === "group" ? GROUP_GRAD : undefined} />
+        <div style={{ flex: 1, minWidth: 0 }}>
+          <div style={{ fontWeight: 600 }}>{conv.title}</div>
+          <div style={{ color: "var(--muted)", fontSize: 12 }}>
+            {conv.membership === "group" ? `${conv.participants.length} people` : "Direct message"}
+          </div>
+        </div>
+        {conv.membership === "group" && (
+          <button onClick={() => setSettingsOpen(true)} title="Group settings" style={{ ...actionBtnStyle, width: 34, height: 34 }}>
+            <Icon name="settings" size={18} />
+          </button>
+        )}
+      </header>
+      {conv.membership === "group" && settingsOpen && (
+        <GroupSettingsModal conv={conv} directory={directory} onClose={() => setSettingsOpen(false)} onError={onError} />
+      )}
+
+      <div style={{ flex: 1, overflowY: "auto", padding: 18, display: "flex", flexDirection: "column", gap: 10, background: "var(--bg)" }}>
+        {t.loading && t.messages.length === 0 && <div style={{ margin: "auto", color: "var(--muted)" }}>Loading messages…</div>}
+        {!t.loading && t.messages.length === 0 && <div style={{ margin: "auto", color: "var(--muted)" }}>No messages yet — say hello 👋</div>}
+        {t.messages.map((msg) => (
+          <MessageBubble
+            key={msg.id} msg={msg}
+            parent={msg.parentInteractionId ? byId[msg.parentInteractionId] : undefined}
+            seen={msg.id === lastMineId && t.seenIds.has(msg.id)}
+            showStatus={msg.id === lastMineId}
+            flash={flashId === msg.id}
+            registerRef={(el) => { if (el) msgRefs.current.set(msg.id, el); else msgRefs.current.delete(msg.id); }}
+            onReact={(emoji) => t.react(msg.id, emoji)}
+            onReply={() => startReply(msg)}
+            onQuoteClick={jumpTo}
+          />
+        ))}
+        <div ref={endRef} />
+      </div>
+
+      <div style={{ minHeight: 18, padding: "0 18px", color: "var(--muted)", fontSize: 12, fontStyle: "italic" }}>{typingLabel}</div>
+
+      {replyTo && (
+        <div style={{ display: "flex", alignItems: "center", gap: 10, margin: "0 14px", padding: "8px 12px", borderRadius: 10, background: "var(--panel-2)", borderLeft: "3px solid var(--orange)" }}>
+          <div style={{ flex: 1, minWidth: 0 }}>
+            <div style={{ fontSize: 11, color: "var(--orange)", fontWeight: 600 }}>Replying to {replyTo.mine ? "yourself" : nameOf(replyTo.senderId ?? "")}</div>
+            <div style={{ fontSize: 12.5, color: "var(--muted)", whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" }}>{replyTo.text}</div>
+          </div>
+          <button onClick={() => setReplyTo(null)} style={{ background: "none", border: "none", color: "var(--muted)", cursor: "pointer", fontSize: 16 }} aria-label="Cancel reply">×</button>
+        </div>
+      )}
+
+      {staged && (
+        <div style={{ display: "flex", alignItems: "center", gap: 8, margin: "0 14px", padding: "8px 12px", borderRadius: 10, background: "var(--panel-2)", border: "1px solid var(--border)" }}>
+          <Icon name={isImage(staged.mimeType) ? "image" : "file"} size={16} />
+          <span style={{ flex: 1, minWidth: 0, whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis", fontSize: 13 }}>{staged.filename}</span>
+          <span style={{ color: "var(--muted)", fontSize: 12 }}>{fmtBytes(staged.sizeBytes)}</span>
+          <button onClick={() => setStaged(null)} style={{ background: "none", border: "none", color: "var(--muted)", cursor: "pointer", fontSize: 16 }} aria-label="Remove attachment">×</button>
+        </div>
+      )}
+
+      <footer style={{ display: "flex", gap: 8, padding: 14, borderTop: "1px solid var(--border)", alignItems: "center" }}>
+        <input ref={fileRef} type="file" hidden onChange={(e) => void onPickFile(e.target.files?.[0])} />
+        <button onClick={() => fileRef.current?.click()} disabled={uploading} title="Attach a file" style={{ ...actionBtnStyle, width: 38, height: 38, flexShrink: 0, opacity: uploading ? 0.5 : 1 }}>
+          {uploading ? "…" : "📎"}
+        </button>
+        <input
+          ref={inputRef}
+          value={draft} onChange={(e) => onDraftChange(e.target.value)}
+          onKeyDown={(e) => { if (e.key === "Enter" && !e.shiftKey) { e.preventDefault(); void submit(); } }}
+          placeholder="Type a message…" style={inputStyle}
+        />
+        <Btn icon="send" onClick={() => void submit()} disabled={sending || (!draft.trim() && !staged)}>Send</Btn>
+      </footer>
+    </>
+  );
+}
+
+function MessageBubble({
+  msg, parent, seen, showStatus, flash, registerRef, onReact, onReply, onQuoteClick,
+}: {
+  msg: UiMessage; parent?: UiMessage; seen: boolean; showStatus: boolean; flash?: boolean;
+  registerRef?: (el: HTMLElement | null) => void;
+  onReact: (emoji: string) => void; onReply: () => void; onQuoteClick?: (id: string) => void;
+}) {
+  const [hover, setHover] = useState(false);
+  const [picker, setPicker] = useState(false);
+
+  return (
+    <div
+      ref={registerRef}
+      onMouseEnter={() => setHover(true)}
+      onMouseLeave={() => { setHover(false); setPicker(false); }}
+      style={{
+        alignSelf: msg.mine ? "flex-end" : "flex-start", maxWidth: "72%", display: "flex", flexDirection: "column",
+        alignItems: msg.mine ? "flex-end" : "flex-start", position: "relative",
+        borderRadius: 14, padding: 2, transition: "background 0.4s",
+        background: flash ? "rgba(253,169,19,0.22)" : "transparent",
+      }}
+    >
+      {parent && (
+        <button
+          type="button"
+          onClick={() => parent.id && onQuoteClick?.(parent.id)}
+          title="Go to message"
+          style={{ maxWidth: "100%", padding: "4px 10px", marginBottom: 3, borderRadius: 8, background: "var(--panel-2)", borderLeft: "3px solid var(--orange)", border: "none", borderLeftWidth: 3, fontSize: 12, color: "var(--muted)", whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis", cursor: "pointer", textAlign: "left" }}
+        >
+          <span style={{ opacity: 0.8 }}>↩ {parent.text}</span>
+        </button>
+      )}
+
+      <div style={{ display: "flex", alignItems: "center", gap: 6, flexDirection: msg.mine ? "row-reverse" : "row" }}>
+        {(msg.text || !msg.attachment) && (
+          <div style={{
+            background: msg.mine ? "var(--grad-brand)" : "var(--panel)", color: msg.mine ? "#fff" : "var(--text)",
+            padding: "8px 12px", borderRadius: 14,
+            borderBottomRightRadius: msg.mine ? 4 : 14, borderBottomLeftRadius: msg.mine ? 14 : 4,
+            border: msg.mine ? "none" : "1px solid var(--border)",
+            whiteSpace: "pre-wrap", wordBreak: "break-word", fontSize: 14,
+          }}>
+            {msg.text}
+          </div>
+        )}
+        {hover && (
+          <div style={{ display: "flex", gap: 2, position: "relative" }}>
+            <button onClick={() => setPicker((p) => !p)} title="React" style={actionBtnStyle}>🙂</button>
+            <button onClick={onReply} title="Reply" style={actionBtnStyle}>↩</button>
+            {picker && (
+              <div style={{ position: "absolute", bottom: "100%", [msg.mine ? "right" : "left"]: 0, marginBottom: 4, display: "flex", gap: 2, padding: 4, borderRadius: 999, background: "var(--panel)", border: "1px solid var(--border)", boxShadow: "0 6px 20px rgba(0,0,0,0.35)", zIndex: 5 }}>
+                {REACTION_EMOJIS.map((e) => (
+                  <button key={e} onClick={() => { onReact(e); setPicker(false); }} style={{ ...actionBtnStyle, fontSize: 16 }}>{e}</button>
+                ))}
+              </div>
+            )}
+          </div>
+        )}
+      </div>
+
+      {msg.attachment && (
+        <div style={{ marginTop: 4, display: "flex", justifyContent: msg.mine ? "flex-end" : "flex-start" }}>
+          <AttachmentView att={msg.attachment} />
+        </div>
+      )}
+
+      {msg.reactions && msg.reactions.length > 0 && (
+        <div style={{ display: "flex", gap: 4, marginTop: 3, flexWrap: "wrap" }}>
+          {msg.reactions.map((r) => (
+            <button
+              key={r.emoji} onClick={() => onReact(r.emoji)}
+              style={{
+                display: "inline-flex", alignItems: "center", gap: 3, padding: "1px 7px", borderRadius: 999, fontSize: 12, cursor: "pointer",
+                background: r.mine ? "rgba(253,169,19,0.18)" : "var(--panel-2)",
+                border: `1px solid ${r.mine ? "var(--orange)" : "var(--border)"}`, color: "var(--text)",
+              }}
+            >
+              <span>{r.emoji}</span><span style={{ color: "var(--muted)" }}>{r.count}</span>
+            </button>
+          ))}
+        </div>
+      )}
+
+      <div style={{ fontSize: 10.5, color: "var(--muted)", marginTop: 2 }}>
+        {timeOf(msg.at)}{showStatus && msg.mine ? ` · ${seen ? "Seen" : "Sent"}` : ""}
+      </div>
+    </div>
+  );
+}
+
+const actionBtnStyle: CSSProperties = {
+  background: "var(--panel-2)", border: "1px solid var(--border)", borderRadius: 8,
+  width: 26, height: 26, display: "grid", placeItems: "center", cursor: "pointer", fontSize: 13, color: "var(--text)", padding: 0,
+};
+
+function NewChatModal({
+  open, onClose, directory, onCreate,
+}: {
+  open: boolean; onClose: () => void; directory: UiPerson[];
+  onCreate: (ids: string[], opts: { membership: Membership; subject?: string }) => Promise<void>;
+}) {
+  const [picked, setPicked] = useState<string[]>([]);
+  const [subject, setSubject] = useState("");
+  const [q, setQ] = useState("");
+  const [busy, setBusy] = useState(false);
+
+  useEffect(() => { if (!open) { setPicked([]); setSubject(""); setQ(""); setBusy(false); } }, [open]);
+
+  const membership: Membership = picked.length > 1 ? "group" : "dm";
+  const filtered = directory.filter((p) => p.name.toLowerCase().includes(q.trim().toLowerCase()));
+  const toggle = (id: string) => setPicked((l) => (l.includes(id) ? l.filter((x) => x !== id) : [...l, id]));
+
+  async function create() {
+    if (!picked.length || busy) return;
+    setBusy(true);
+    await onCreate(picked, { membership, ...(membership === "group" && subject.trim() ? { subject: subject.trim() } : {}) });
+    setBusy(false);
+  }
+
+  return (
+    <Modal
+      open={open} onClose={onClose} title="New conversation"
+      subtitle={membership === "group" ? "Group chat" : "Direct message"} icon="send"
+      footer={<>
+        <Btn variant="ghost" onClick={onClose}>Cancel</Btn>
+        <Btn icon="send" onClick={() => void create()} disabled={!picked.length || busy}>{busy ? "Starting…" : "Start chat"}</Btn>
+      </>}
+    >
+      <input value={q} onChange={(e) => setQ(e.target.value)} placeholder="Search people…" style={{ ...inputStyle, marginBottom: 10 }} />
+      {membership === "group" && (
+        <Field label="Group name (optional)">
+          <input value={subject} onChange={(e) => setSubject(e.target.value)} placeholder="e.g. Storm response" style={inputStyle} />
+        </Field>
+      )}
+      <div style={{ maxHeight: 320, overflowY: "auto", marginTop: 8, display: "flex", flexDirection: "column", gap: 2 }}>
+        {filtered.length === 0 && <div style={{ color: "var(--muted)", padding: 10 }}>No people found.</div>}
+        {filtered.map((p) => (
+          <label key={p.id} style={{
+            display: "flex", alignItems: "center", gap: 10, padding: "8px 10px", borderRadius: 10, cursor: "pointer",
+            background: picked.includes(p.id) ? "var(--panel-2)" : "transparent",
+          }}>
+            <input type="checkbox" checked={picked.includes(p.id)} onChange={() => toggle(p.id)} />
+            <Avatar initials={initialsOf(p.name)} size={30} gradient={p.kind === "customer" ? CUSTOMER_GRAD : undefined} />
+            <span style={{ flex: 1 }}>{p.name}</span>
+            <Pill tone="muted">{p.kind}</Pill>
+          </label>
+        ))}
+      </div>
+    </Modal>
+  );
+}
+
+/** Group settings: rename, member list with roles, add/remove — admin-gated (IIOS/OPA re-enforces). */
+function GroupSettingsModal({ conv, directory, onClose, onError }: {
+  conv: UiConversation; directory: UiPerson[]; onClose: () => void; onError: (m: string) => void;
+}) {
+  const g = useGroupSettings(conv.threadId);
+  const [name, setName] = useState(conv.subject ?? "");
+  const [savingName, setSavingName] = useState(false);
+  const [q, setQ] = useState("");
+  const [pendingId, setPendingId] = useState<string | null>(null);
+
+  useEffect(() => { setName(conv.subject ?? ""); }, [conv.subject]);
+
+  const memberIds = useMemo(() => new Set(g.members.map((m) => m.userId)), [g.members]);
+  const nameChanged = name.trim() && name.trim() !== (conv.subject ?? "").trim();
+  const addable = directory.filter((p) => !memberIds.has(p.id) && p.name.toLowerCase().includes(q.trim().toLowerCase()));
+
+  async function saveName() {
+    if (!nameChanged || savingName) return;
+    setSavingName(true);
+    try { await g.rename(name.trim()); }
+    catch (e) { onError((e as Error).message); }
+    finally { setSavingName(false); }
+  }
+  async function add(userId: string) {
+    setPendingId(userId);
+    try { await g.addMember(userId); }
+    catch (e) { onError((e as Error).message); }
+    finally { setPendingId(null); }
+  }
+  async function remove(userId: string) {
+    setPendingId(userId);
+    try { await g.removeMember(userId); }
+    catch (e) { onError((e as Error).message); }
+    finally { setPendingId(null); }
+  }
+
+  return (
+    <Modal
+      open onClose={onClose} title="Group settings" subtitle={conv.title} icon="settings"
+      footer={<Btn variant="ghost" onClick={onClose}>Done</Btn>}
+    >
+      <Field label="Group name">
+        <div style={{ display: "flex", gap: 8 }}>
+          <input value={name} onChange={(e) => setName(e.target.value)} disabled={!g.isAdmin}
+            placeholder="Group name" style={{ ...inputStyle, opacity: g.isAdmin ? 1 : 0.6 }} />
+          {g.isAdmin && <Btn onClick={() => void saveName()} disabled={!nameChanged || savingName}>{savingName ? "…" : "Save"}</Btn>}
+        </div>
+        {!g.isAdmin && <div style={{ color: "var(--muted)", fontSize: 12, marginTop: 4 }}>Only a group admin can rename the group.</div>}
+      </Field>
+
+      <Field label={`Members (${g.members.length})`}>
+        <div style={{ display: "flex", flexDirection: "column", gap: 2, maxHeight: 200, overflowY: "auto" }}>
+          {g.loading && g.members.length === 0 && <div style={{ color: "var(--muted)", padding: 8 }}>Loading…</div>}
+          {g.members.map((mem: UiMember) => (
+            <div key={mem.userId} style={{ display: "flex", alignItems: "center", gap: 10, padding: "7px 10px", borderRadius: 10 }}>
+              <Avatar initials={initialsOf(mem.displayName)} size={28} gradient={GROUP_GRAD} />
+              <span style={{ flex: 1 }}>{mem.displayName}</span>
+              {mem.role === "ADMIN" && <Pill tone="purple">admin</Pill>}
+              {g.isAdmin && mem.role !== "ADMIN" && (
+                <button onClick={() => void remove(mem.userId)} disabled={pendingId === mem.userId} title="Remove"
+                  style={{ ...actionBtnStyle, width: 28, height: 28 }}><Icon name="trash" size={15} /></button>
+              )}
+            </div>
+          ))}
+        </div>
+      </Field>
+
+      {g.isAdmin && (
+        <Field label="Add member">
+          <input value={q} onChange={(e) => setQ(e.target.value)} placeholder="Search people…" style={{ ...inputStyle, marginBottom: 8 }} />
+          <div style={{ display: "flex", flexDirection: "column", gap: 2, maxHeight: 180, overflowY: "auto" }}>
+            {addable.length === 0 && <div style={{ color: "var(--muted)", padding: 8 }}>No one to add.</div>}
+            {addable.map((p) => (
+              <button key={p.id} onClick={() => void add(p.id)} disabled={pendingId === p.id}
+                style={{ display: "flex", alignItems: "center", gap: 10, padding: "7px 10px", borderRadius: 10, cursor: "pointer", background: "transparent", border: "none", color: "var(--text)", textAlign: "left" }}>
+                <Avatar initials={initialsOf(p.name)} size={28} gradient={p.kind === "customer" ? CUSTOMER_GRAD : undefined} />
+                <span style={{ flex: 1 }}>{p.name}</span>
+                <Icon name="plus" size={16} />
+              </button>
+            ))}
+          </div>
+        </Field>
+      )}
+    </Modal>
+  );
+}

src/components/dashboard/sidebar.tsx

@@ -6,6 +6,7 @@ import { ChevronsUpDown, LogOut } from "lucide-react";
 import { useAuth } from "@abe-kap/appshell-sdk/react";
 import { Icon } from "./ui";
 import { user } from "./account-data";
+import { useMyAccess } from "@/lib/access";
 
 function initialsOf(name: string): string {
   return name.split(/\s+/).filter(Boolean).slice(0, 2).map((p) => p[0]).join("").toUpperCase() || "?";
@@ -28,6 +29,13 @@ export const NAV_GROUPS: NavGroup[] = [
       { key: "pipeline", label: "Pipeline", icon: "pipeline" },
     ],
   },
+  {
+    title: "Communication",
+    items: [
+      { key: "messenger", label: "Messenger", icon: "send", subtitle: "Chat with your team and clients" },
+      { key: "inbox", label: "Inbox", icon: "bell", subtitle: "Mentions, messages, alerts and mail — all in one" },
+    ],
+  },
   {
     title: "Workspace",
     items: [
@@ -67,10 +75,45 @@ export const NAV_GROUPS: NavGroup[] = [
 
 export const NAV_ITEMS: NavItem[] = NAV_GROUPS.flatMap((g) => g.items);
 
+// Nav visibility by CRM permission. Dashboard + Profile are always visible (even to a
+// brand-new user with no membership); every other item requires membership, and the
+// items mapped here additionally require the given permission. Unmapped items are
+// shown to any member. This is UX only — be-crm still enforces every action.
+const ALWAYS_VISIBLE = new Set(["dashboard", "profile", "messenger", "inbox"]);
+const NAV_PERMISSION: Record<string, string | undefined> = {
+  team: "team.manage",
+  people: "team.manage",
+  leads: "leads.manage",
+  verify: "leads.manage",
+  pipeline: "pipeline.manage",
+  estimates: "estimates.create",
+  procanvas: "estimates.create",
+  dispatch: "dispatch.manage",
+  schedule: "dispatch.manage",
+  storm: "dispatch.manage",
+  territory: "dispatch.manage",
+  leaderboard: "reports.view",
+  settings: "settings.manage",
+};
+
 export function Sidebar({ active, onSelect }: { active: string; onSelect: (k: string) => void }) {
   const router = useRouter();
   const { user: me, logout, context } = useAuth();
+  const access = useMyAccess();
   const [menuOpen, setMenuOpen] = useState(false);
+
+  // A new user with no membership sees only Dashboard + Profile. Members see the areas
+  // their permissions allow. While access is still loading, keep it minimal to avoid
+  // flashing items the user can't actually use.
+  const canSee = (key: string): boolean => {
+    if (ALWAYS_VISIBLE.has(key)) return true;
+    if (access.loading || !access.isMember) return false;
+    const perm = NAV_PERMISSION[key];
+    return perm ? access.can(perm) : true;
+  };
+  const visibleGroups = NAV_GROUPS
+    .map((g) => ({ ...g, items: g.items.filter((it) => canSee(it.key)) }))
+    .filter((g) => g.items.length > 0);
   // Real signed-in identity from the App Context Envelope; fall back to the static
   // demo user only when the Shell isn't wired.
   const roleLabel = context?.scope?.role ? context.scope.role.charAt(0).toUpperCase() + context.scope.role.slice(1) : "";
@@ -92,7 +135,7 @@ export function Sidebar({ active, onSelect }: { active: string; onSelect: (k: st
       </div>
 
       <nav className="dash-nav">
-        {NAV_GROUPS.map((g, gi) => (
+        {visibleGroups.map((g, gi) => (
           <div className="nav-section" key={gi}>
             <div className="nav-group">{g.title}</div>
             {g.items.map((it) => (

src/components/dashboard/team-management.tsx

@@ -301,8 +301,15 @@ export function TeamManagement() {
                   </div>
                   <RoleChips roleIds={inv.roleIds} roleById={roleById} />
                   <div className="tm-invite-actions">
+                    {inv.token && (
+                      <Btn variant="soft" size="sm" icon="copy" onClick={async () => {
+                        const link = `${window.location.origin}/portal/invite?token=${inv.token}`;
+                        try { await navigator.clipboard.writeText(link); toast.push({ tone: "success", title: "Invite link copied", desc: `Send it to ${inv.email} to join.` }); }
+                        catch { toast.push({ tone: "info", title: "Invite link", desc: link }); }
+                      }}>Copy link</Btn>
+                    )}
                     <Btn variant="soft" size="sm" icon="refresh" onClick={async () => {
-                      try { await team.resendInvite(inv.id); toast.push({ tone: "success", title: "Invite resent", desc: `A fresh link was sent to ${inv.email}.` }); }
+                      try { await team.resendInvite(inv.id); toast.push({ tone: "success", title: "Invite resent", desc: `A fresh link was emailed to ${inv.email}.` }); }
                       catch (e) { toast.push({ tone: "error", title: "Couldn't resend", desc: (e as Error).message }); }
                     }}>Resend</Btn>
                     <Btn variant="ghost" size="sm" icon="x" onClick={async () => {
@@ -326,7 +333,7 @@ export function TeamManagement() {
           try {
             await team.invite(email, roleIds);
             setTab("invites");
-            toast.push({ tone: "success", title: "Invitation sent", desc: `${email} was invited with ${roleIds.length} role${roleIds.length === 1 ? "" : "s"}.` });
+            toast.push({ tone: "success", title: "Invitation sent", desc: `We emailed an invite to ${email}. You can also copy the link.` });
           } catch (e) { toast.push({ tone: "error", title: "Couldn't send invite", desc: (e as Error).message }); }
         }}
       />

src/components/dashboard/ui.tsx

@@ -14,6 +14,7 @@ import {
   createContext, useCallback, useContext, useEffect, useId,
   useRef, useState, type ReactNode,
 } from "react";
+import { createPortal } from "react-dom";
 import {
   MessageCircle, Ticket, Phone, Mail, BookOpen, Rocket, Shield, ShieldCheck,
   Lock, CreditCard, User, Bell, Eye, EyeOff, Camera, Upload, Plus, Star, Send,
@@ -221,6 +222,11 @@ export function Modal({ open, onClose, title, subtitle, icon, children, footer,
   children: ReactNode; footer?: ReactNode; size?: "sm" | "md" | "lg";
 }) {
   const titleId = useId();
+  // Portal the overlay up to `.dash-root` so its position:fixed anchors to the viewport,
+  // not to a transformed/overflow panel ancestor (which would clip or offset the modal).
+  const [host, setHost] = useState<Element | null>(null);
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => { setHost(document.querySelector(".dash-root")); setMounted(true); }, []);
   useEffect(() => {
     if (!open) return;
     const onKey = (e: KeyboardEvent) => { if (e.key === "Escape") onClose(); };
@@ -228,8 +234,8 @@ export function Modal({ open, onClose, title, subtitle, icon, children, footer,
     return () => document.removeEventListener("keydown", onKey);
   }, [open, onClose]);
 
-  if (!open) return null;
-  return (
+  if (!open || !mounted) return null;
+  const overlay = (
     <div className="ds-modal-overlay" onMouseDown={onClose}>
       <div className={`ds-modal size-${size}`} role="dialog" aria-modal="true" aria-labelledby={titleId} onMouseDown={(e) => e.stopPropagation()}>
         <div className="ds-modal-head">
@@ -247,6 +253,7 @@ export function Modal({ open, onClose, title, subtitle, icon, children, footer,
       </div>
     </div>
   );
+  return host ? createPortal(overlay, host) : overlay;
 }
 
 /* ---------------------------------------------------------- */

src/components/dashboard/verify-data.ts

@@ -0,0 +1,72 @@
+// ============================================================
+// LynkedUp Pro — Lead Verification mock data.
+// The verification desk: door-knocked / web leads move through
+// an identity + insurance verification workflow before they
+// become working deals. All client-side.
+// ============================================================
+
+export type VStatus = "verified" | "in_progress" | "assigned" | "pending" | "unverified";
+
+export type VActivity = { text: string; time: string; who: string };
+
+export type VLead = {
+  id: string;
+  initials: string;
+  name: string;
+  address: string;
+  phone: string;
+  source: string;
+  assignee: { initials: string; name: string } | null;
+  status: VStatus;
+  verification: string;   // sub-status text
+  created: string;
+  // detail (optional — derived when absent)
+  email?: string;
+  createdAt?: string;     // date + time
+  verifiedAt?: string;
+  notes?: string;
+  activity?: VActivity[];
+};
+
+export const V_STATUS_META: Record<VStatus, { label: string; tone: string }> = {
+  verified: { label: "Verified", tone: "green" },
+  in_progress: { label: "In Progress", tone: "orange" },
+  assigned: { label: "Assigned", tone: "blue" },
+  pending: { label: "Pending", tone: "purple" },
+  unverified: { label: "Unverified", tone: "red" },
+};
+
+const WADE = { initials: "WH", name: "Wade Hollis" };
+const DARLENE = { initials: "DB", name: "Darlene Brooks" };
+const ROY = { initials: "RS", name: "Roy Schaefer" };
+
+export const V_LEADS: VLead[] = [
+  {
+    id: "LD-V-001", initials: "K", name: "Kevin Hartley", address: "2814 Ravenswood Dr, Plano, TX 75023", phone: "(972) 413-8902", source: "Door Knock", assignee: WADE, status: "verified", verification: "Verified", created: "May 14, 2026",
+    email: "kevin.hartley@gmail.com", createdAt: "May 14, 2026, 2:40 PM", verifiedAt: "May 16, 2026, 7:55 PM",
+    notes: "Ownership confirmed via county records. Hail damage from April 28 storm event verified.",
+    activity: [
+      { text: "Lead submitted via door knock intake.", time: "May 14, 2026, 2:40 PM", who: "System" },
+      { text: "Assigned to Wade Hollis.", time: "May 14, 2026, 3:10 PM", who: "Wade Hollis" },
+      { text: "First contact made — homeowner confirmed damage.", time: "May 15, 2026, 2:00 PM", who: "Wade Hollis" },
+      { text: "Verified and pushed to New Leads.", time: "May 16, 2026, 7:55 PM", who: "Wade Hollis" },
+    ],
+  },
+  { id: "LD-V-002", initials: "S", name: "Sandra Nguyen", address: "4817 Shady Brook Ln, Plano, TX 75093", phone: "(469) 551-7034", source: "Web Form", assignee: DARLENE, status: "verified", verification: "Verified", created: "May 17, 2026" },
+  { id: "LD-V-003", initials: "M", name: "Marcus Trevino", address: "1234 Oak Creek Blvd, Plano, TX 75075", phone: "(214) 837-4561", source: "Storm Canvass", assignee: WADE, status: "in_progress", verification: "Verifying Identity", created: "May 22, 2026" },
+  { id: "LD-V-004", initials: "B", name: "Brenda Kowalski", address: "890 Custer Rd, Plano, TX 75075", phone: "(972) 604-2817", source: "Referral", assignee: ROY, status: "in_progress", verification: "Reviewing Insurance", created: "May 20, 2026" },
+  { id: "LD-V-005", initials: "J", name: "James Whitaker", address: "3320 Parkhaven Dr, Plano, TX 75075", phone: "(469) 720-1188", source: "Door Knock", assignee: WADE, status: "in_progress", verification: "Confirming Ownership", created: "May 23, 2026" },
+  { id: "LD-V-006", initials: "P", name: "Priya Sharma", address: "5102 Mapleshade Ln, Plano, TX 75093", phone: "(972) 415-6620", source: "Web Form", assignee: DARLENE, status: "in_progress", verification: "Reviewing Insurance", created: "May 24, 2026" },
+  { id: "LD-V-007", initials: "C", name: "Carlos Mendez", address: "1470 Coit Rd, Plano, TX 75075", phone: "(214) 902-5533", source: "Storm Canvass", assignee: ROY, status: "in_progress", verification: "Confirming Damage", created: "May 25, 2026" },
+  { id: "LD-V-008", initials: "E", name: "Emily Carter", address: "2609 Rivercrest Dr, Plano, TX 75023", phone: "(469) 338-4471", source: "Door Knock", assignee: DARLENE, status: "assigned", verification: "Assigned", created: "May 26, 2026" },
+  { id: "LD-V-009", initials: "T", name: "Tyrone Jackson", address: "744 Legacy Dr, Plano, TX 75023", phone: "(972) 551-9042", source: "Referral", assignee: WADE, status: "assigned", verification: "Assigned", created: "May 26, 2026" },
+  { id: "LD-V-010", initials: "N", name: "Nicole Foster", address: "3901 Preston Meadow Dr, Plano, TX 75093", phone: "(214) 660-7719", source: "Web Form", assignee: ROY, status: "assigned", verification: "Assigned", created: "May 27, 2026" },
+  { id: "LD-V-011", initials: "A", name: "Aaron Blake", address: "1188 Alma Dr, Plano, TX 75075", phone: "(469) 471-3350", source: "Door Knock", assignee: null, status: "pending", verification: "Pending Review", created: "May 27, 2026" },
+  { id: "LD-V-012", initials: "G", name: "Grace Liu", address: "5540 Communications Pkwy, Plano, TX 75093", phone: "(972) 883-2201", source: "Web Form", assignee: null, status: "pending", verification: "Pending Review", created: "May 28, 2026" },
+  { id: "LD-V-013", initials: "D", name: "Derek Olsen", address: "902 Independence Pkwy, Plano, TX 75075", phone: "(214) 774-6690", source: "Call-In", assignee: null, status: "pending", verification: "Pending Review", created: "May 28, 2026" },
+  { id: "LD-V-014", initials: "M", name: "Monica Reyes", address: "3115 Rasor Blvd, Plano, TX 75093", phone: "(469) 205-8814", source: "Storm Canvass", assignee: null, status: "unverified", verification: "Unverified", created: "May 29, 2026" },
+  { id: "LD-V-015", initials: "S", name: "Sam Patterson", address: "677 Spring Creek Pkwy, Plano, TX 75023", phone: "(972) 330-1247", source: "Call-In", assignee: null, status: "unverified", verification: "Unverified", created: "May 29, 2026" },
+];
+
+export const V_SOURCES = ["Door Knock", "Web Form", "Storm Canvass", "Referral", "Call-In"];
+export const V_ASSIGNEES = ["Wade Hollis", "Darlene Brooks", "Roy Schaefer"];

src/components/dashboard/verify.tsx

@@ -0,0 +1,306 @@
+"use client";
+
+// ============================================================
+// Lead Verification — the verification desk.
+//   · Stat tiles : Verified / In Progress / Assigned / Pending
+//                  / Unverified counts (click to filter)
+//   · Toolbar    : search + status / source / assignee filters
+//   · Table      : Lead ID · Customer · Phone · Source ·
+//                  Assigned To · Status · Verification · Created
+//                  · Actions (view / verify / ⋯ menu)
+//   · Detail     : view → popup with Contact, Assignment,
+//                  Verification Notes and an Activity timeline
+// Data comes from verify-data.ts (client-side mock).
+// ============================================================
+
+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";
+
+const STAT_ORDER: VStatus[] = ["verified", "in_progress", "assigned", "pending", "unverified"];
+const STAT_ICON: Record<VStatus, string> = {
+  verified: "check-circle", in_progress: "refresh", assigned: "user", pending: "clock", unverified: "alert",
+};
+
+/* ---- derive detail when the row doesn't carry it ---------- */
+function deriveEmail(l: VLead) {
+  if (l.email) return l.email;
+  const [first, ...rest] = l.name.toLowerCase().split(" ");
+  return `${first}.${rest.join("")}@gmail.com`;
+}
+function deriveCreatedAt(l: VLead) { return l.createdAt ?? `${l.created}, 10:00 AM`; }
+function buildActivity(l: VLead): VActivity[] {
+  if (l.activity) return l.activity;
+  const who = l.assignee?.name ?? "System";
+  const a: VActivity[] = [{ text: `Lead submitted via ${l.source.toLowerCase()} intake.`, time: deriveCreatedAt(l), who: "System" }];
+  if (l.assignee) a.push({ text: `Assigned to ${l.assignee.name}.`, time: l.created, who: l.assignee.name });
+  if (l.status === "in_progress") a.push({ text: `Verification in progress — ${l.verification.toLowerCase()}.`, time: l.created, who });
+  if (l.status === "verified") a.push({ text: "Verified and pushed to New Leads.", time: l.verifiedAt ?? l.created, who });
+  return a;
+}
+
+type MenuState = { lead: VLead; x: number; y: number } | null;
+
+export function Verify() {
+  const toast = useToast();
+  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 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) => {
+      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]);
+
+  function act(l: VLead, title: string, desc: string, tone: "success" | "info" = "info") {
+    setMenu(null);
+    toast.push({ tone, title, desc });
+  }
+
+  return (
+    <div className="view lv">
+      <PageHead
+        eyebrow="Sales"
+        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>}
+      />
+
+      {/* ---- stat tiles ---- */}
+      <div className="lv-stats">
+        {STAT_ORDER.map((s) => {
+          const meta = V_STATUS_META[s];
+          return (
+            <button key={s} className={`lv-stat tone-${meta.tone} ${status === s ? "active" : ""}`} onClick={() => setStatus(status === s ? "all" : s)}>
+              <span className="lv-stat-ic"><Icon name={STAT_ICON[s]} size={16} /></span>
+              <span className="lv-stat-val">{counts[s] ?? 0}</span>
+              <span className="lv-stat-lbl">{meta.label}</span>
+            </button>
+          );
+        })}
+      </div>
+
+      {/* ---- toolbar ---- */}
+      <div className="lv-toolbar">
+        <div className="lv-search">
+          <Icon name="search" size={16} />
+          <input value={query} onChange={(e) => setQuery(e.target.value)} placeholder="Search name, lead ID, phone, source…" aria-label="Search verification leads" />
+          {query && <button className="lv-search-x" aria-label="Clear" onClick={() => setQuery("")}><Icon name="x" size={14} /></button>}
+        </div>
+        <select className="ds-select lv-filter" value={status} onChange={(e) => setStatus(e.target.value)} aria-label="Filter by status">
+          <option value="all">All statuses</option>
+          {STAT_ORDER.map((s) => <option key={s} value={s}>{V_STATUS_META[s].label}</option>)}
+        </select>
+        <select className="ds-select lv-filter" value={source} onChange={(e) => setSource(e.target.value)} aria-label="Filter by source">
+          <option value="all">All sources</option>
+          {V_SOURCES.map((s) => <option key={s} value={s}>{s}</option>)}
+        </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>)}
+        </select>
+      </div>
+
+      {/* ---- table ---- */}
+      <div className="lv-tablewrap">
+        <table className="lv-table">
+          <thead>
+            <tr>
+              <th>Lead ID</th><th>Customer</th><th>Phone</th><th>Source</th>
+              <th>Assigned To</th><th>Status</th><th>Verification</th><th>Created</th>
+              <th className="lv-actions-h">Actions</th>
+            </tr>
+          </thead>
+          <tbody>
+            {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];
+              return (
+                <tr key={l.id}>
+                  <td><div className="lv-id">{l.id}</div><div className="lv-id-date">{l.created}</div></td>
+                  <td>
+                    <div className="lv-cust">
+                      <Avatar initials={l.initials} size={34} />
+                      <div className="lv-cust-body">
+                        <div className="lv-cust-name">{l.name}</div>
+                        <div className="lv-cust-addr">{l.address}</div>
+                      </div>
+                    </div>
+                  </td>
+                  <td className="lv-phone">{l.phone}</td>
+                  <td><span className="lv-source">{l.source}</span></td>
+                  <td>
+                    {l.assignee ? (
+                      <div className="lv-assignee">
+                        <Avatar initials={l.assignee.initials} size={26} gradient="linear-gradient(135deg,#4f8cff,#2c5cff)" />
+                        <span>{l.assignee.name}</span>
+                      </div>
+                    ) : <span className="lv-unassigned">— Unassigned</span>}
+                  </td>
+                  <td><Pill tone={meta.tone}>{meta.label}</Pill></td>
+                  <td><span className={`lv-verif v-${l.status}`}><Icon name={STAT_ICON[l.status]} size={13} /> {l.verification}</span></td>
+                  <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 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" 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>
+                </tr>
+              );
+            })}
+          </tbody>
+        </table>
+      </div>
+      <div className="lv-count">{rows.length} of {V_LEADS.length} leads</div>
+
+      <ActionsMenu menu={menu} onClose={() => setMenu(null)} onAct={act} onView={(l) => { setSelected(l); setMenu(null); }} />
+      <VerifyDetail lead={selected} onClose={() => setSelected(null)} />
+    </div>
+  );
+}
+
+/* ---------------------------------------------------------- */
+/* Row actions dropdown (portalled, fixed-positioned)          */
+/* ---------------------------------------------------------- */
+
+function ActionsMenu({ menu, onClose, onAct, onView }: {
+  menu: MenuState; onClose: () => void;
+  onAct: (l: VLead, title: string, desc: string, tone?: "success" | "info") => void;
+  onView: (l: VLead) => void;
+}) {
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => { setMounted(true); }, []);
+  useEffect(() => {
+    if (!menu) return;
+    const onKey = (e: KeyboardEvent) => { if (e.key === "Escape") onClose(); };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [menu, onClose]);
+  if (!menu || !mounted) return null;
+
+  const l = menu.lead;
+  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} />
+      <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}>
+            <Icon name={it.icon} size={14} /> {it.label}
+          </button>
+        ))}
+      </div>
+    </>,
+    document.body,
+  );
+}
+
+/* ---------------------------------------------------------- */
+/* Verification detail popup                                   */
+/* ---------------------------------------------------------- */
+
+function VerifyDetail({ lead, onClose }: { lead: VLead | null; onClose: () => void }) {
+  if (!lead) return null;
+  const meta = V_STATUS_META[lead.status];
+  const activity = buildActivity(lead);
+
+  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 icon="check-circle">Verify Lead</Btn>
+      </>}
+    >
+      <div className="lv-detail">
+        <div className="lv-d-identity">
+          <Avatar initials={lead.initials} size={50} />
+          <div>
+            <div className="lv-d-name">{lead.name}</div>
+            <div className="lv-d-pills">
+              <Pill tone={meta.tone}>{meta.label}</Pill>
+              <span className={`lv-verif v-${lead.status}`}><Icon name={STAT_ICON[lead.status]} size={13} /> {lead.verification}</span>
+            </div>
+          </div>
+        </div>
+
+        <div className="lv-d-grid">
+          <div className="lv-d-section">
+            <div className="lv-d-head"><Icon name="user" size={15} /> Contact</div>
+            <Row label="Phone" value={lead.phone} />
+            <Row label="Email" value={deriveEmail(lead)} />
+            <Row label="Address" value={lead.address} />
+            <Row label="Source" value={lead.source} />
+          </div>
+          <div className="lv-d-section">
+            <div className="lv-d-head"><Icon name="team" size={15} /> Assignment</div>
+            <Row label="Assigned To" value={lead.assignee?.name ?? "Unassigned"} />
+            <Row label="Created" value={deriveCreatedAt(lead)} />
+            {lead.verifiedAt && <Row label="Verified At" value={lead.verifiedAt} />}
+          </div>
+        </div>
+
+        {lead.notes && (
+          <div className="lv-d-notes">
+            <div className="lv-d-head"><Icon name="edit" size={15} /> Verification Notes</div>
+            <p>{lead.notes}</p>
+          </div>
+        )}
+
+        <div className="lv-d-activity">
+          <div className="lv-d-head"><Icon name="clock" size={15} /> Activity</div>
+          <ul className="lv-timeline">
+            {activity.map((a, i) => (
+              <li key={i} className="lv-tl-item">
+                <span className="lv-tl-dot" />
+                <div className="lv-tl-body">
+                  <div className="lv-tl-text">{a.text}</div>
+                  <div className="lv-tl-meta">{a.time} · {a.who}</div>
+                </div>
+              </li>
+            ))}
+          </ul>
+        </div>
+      </div>
+    </Modal>
+  );
+}
+
+function Row({ label, value }: { label: string; value: string }) {
+  return (
+    <div className="lv-d-row">
+      <span className="lv-d-k">{label}</span>
+      <span className="lv-d-v">{value}</span>
+    </div>
+  );
+}

src/components/portal/login-flow.tsx

@@ -11,6 +11,7 @@ import {
 import { lookupAccount, maskEmail, type Account } from "./data";
 import { useAuth, useAppShell } from "@abe-kap/appshell-sdk/react";
 import { isShellConfigured } from "@/lib/appshell";
+import { MOCK_OTP } from "@/lib/otp";
 
 // Map the portal's social button ids to Supabase OAuth provider ids.
 const OAUTH_PROVIDER: Record<string, string> = { google: "google", microsoft: "azure", apple: "apple" };
@@ -24,7 +25,7 @@ const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 
 export function LoginFlow() {
   const router = useRouter();
-  const { login, loginWithOAuth, completeOAuthLogin } = useAuth();
+  const { login, loginWithOAuth, completeOAuthLogin, getUserEmail } = useAuth();
   const { ready, sdk } = useAppShell();
   const [step, setStep] = useState<Step>("identify");
   const [email, setEmail] = useState("");
@@ -33,6 +34,25 @@ export function LoginFlow() {
   const [remember, setRemember] = useState(false);
   const [flash, setFlash] = useState<string>("");
   const [otpChannel, setOtpChannel] = useState<"email" | "sms">("email");
+  const [invited, setInvited] = useState(false);
+
+  // Arriving from a team invite for an already-registered email → prefill it.
+  useEffect(() => {
+    try { const e = sessionStorage.getItem("invite_email"); if (e) { setEmail(e); setInvited(true); } } catch { /* ignore */ }
+  }, []);
+
+  // After a successful sign-in, redeem a pending team invite (if any), then go to the dashboard.
+  async function acceptPendingInviteThenDashboard() {
+    try {
+      const t = sessionStorage.getItem("invite_token");
+      if (t) {
+        await sdk.command("crm.team.invitation.accept", { token: t });
+        sessionStorage.removeItem("invite_token");
+        sessionStorage.removeItem("invite_email");
+      }
+    } catch { /* invite expired/used — proceed to the dashboard anyway */ }
+    router.replace("/dashboard");
+  }
 
   // Minimal account stand-in for passwordless entry points (Shell mode).
   function blankAccount(): Account {
@@ -42,7 +62,7 @@ export function LoginFlow() {
   function startPhoneLogin() {
     setAccount(blankAccount());
     setOtpChannel("sms");
-    replace("otp");
+    push("otp");   // push (not replace) so Back returns to the identify screen
   }
 
   /* ---- history hash sync ---- */
@@ -86,13 +106,16 @@ export function LoginFlow() {
           registered = !!st?.registered;
         } catch { registered = false; }
         window.history.replaceState({}, "", "/portal/login");
-        router.replace(registered ? "/dashboard" : "/portal/onboarding");
+        if (registered) { await acceptPendingInviteThenDashboard(); return; }
+        // Capture the verified email now (session is fresh) so onboarding prefills it.
+        try { const em = await getUserEmail(); if (em) sessionStorage.setItem("onboard_email", em); } catch { /* ignore */ }
+        router.replace("/portal/onboarding");
       })
       .catch(() => {
         setFlash("Google sign-in didn't complete. Please try again.");
         replace("identify");
       });
-  }, [ready, completeOAuthLogin, router, sdk]);
+  }, [ready, completeOAuthLogin, router, sdk, getUserEmail]);
 
   /* ---- auth resolution ---- */
   function afterAuth(factor: "password" | "passkey" | "otp" | "totp" | "push" | "social") {
@@ -131,7 +154,7 @@ export function LoginFlow() {
         maskedEmail: maskEmail(email), maskedPhone: "", maskedWa: "",
       });
       setOtpChannel("email");
-      replace("password");
+      push("password");   // push (not replace) so Back returns to the email screen, not off-page
       return;
     }
     push("connecting");
@@ -150,7 +173,7 @@ export function LoginFlow() {
       {step === "identify" && (
         <>
           {flash && <div style={{ marginBottom: 16 }}><FlashNote tone="error">{flash}</FlashNote></div>}
-          <Identify email={email} setEmail={setEmail} onSocial={onSocial} onEmail={identifyEmail} onPhone={startPhoneLogin} toRegister={() => router.push("/portal/register")} />
+          <Identify email={email} setEmail={setEmail} onSocial={onSocial} onEmail={identifyEmail} onPhone={startPhoneLogin} toRegister={() => router.push("/portal/register")} invited={invited} />
         </>
       )}
 
@@ -197,11 +220,11 @@ export function LoginFlow() {
       )}
 
       {step === "password" && account && (
-        <Password account={account} email={email} login={login} onAuthenticated={() => router.replace("/dashboard")} flash={flash} onBack={back} onForgot={() => push("fp_confirm")} onOtp={() => { setOtpChannel("email"); replace("otp"); }} onLocked={() => setFlash("This account is temporarily locked.")} onOk={() => afterAuth("password")} />
+        <Password account={account} email={email} login={login} onAuthenticated={acceptPendingInviteThenDashboard} flash={flash} onBack={back} onForgot={() => push("fp_confirm")} onOtp={() => { setOtpChannel("email"); replace("otp"); }} onLocked={() => setFlash("This account is temporarily locked.")} onOk={() => afterAuth("password")} />
       )}
 
       {step === "otp" && account && (
-        <OtpVerify account={account} email={email} initialChannel={otpChannel} remember={remember} setRemember={setRemember} onBack={back} onVerified={() => afterAuth("otp")} onAuthenticated={() => router.replace("/dashboard")} />
+        <OtpVerify account={account} email={email} initialChannel={otpChannel} remember={remember} setRemember={setRemember} onBack={back} onVerified={() => afterAuth("otp")} onAuthenticated={acceptPendingInviteThenDashboard} />
       )}
 
       {step === "another" && account && (
@@ -265,17 +288,17 @@ export function LoginFlow() {
 
 /* ============================ screens ============================ */
 
-function Identify({ email, setEmail, onSocial, onEmail, onPhone, toRegister }: {
+function Identify({ email, setEmail, onSocial, onEmail, onPhone, toRegister, invited }: {
   email: string; setEmail: (v: string) => void;
-  onSocial: (p: "google") => void; onEmail: () => void; onPhone: () => void; toRegister: () => void;
+  onSocial: (p: "google") => void; onEmail: () => void; onPhone: () => void; toRegister: () => void; invited?: boolean;
 }) {
-  const [showEmail, setShowEmail] = useState(false);
+  const [showEmail, setShowEmail] = useState(!!invited);
   const valid = EMAIL_RE.test(email);
   return (
     <div>
-      <div className="kicker">Welcome back</div>
-      <h1>Sign in to LynkedUp</h1>
-      <p className="sub">Drone inspections, AI estimates and insurance-ready reports — all in one place.</p>
+      <div className="kicker">{invited ? "You're invited" : "Welcome back"}</div>
+      <h1>{invited ? "Sign in to join the team" : "Sign in to LynkedUp"}</h1>
+      <p className="sub">{invited ? "You already have an account — sign in to accept your invitation." : "Drone inspections, AI estimates and insurance-ready reports — all in one place."}</p>
 
       <div style={{ marginTop: 22 }}>
         <SocialButtons onPick={onSocial} />
@@ -298,7 +321,10 @@ function Identify({ email, setEmail, onSocial, onEmail, onPhone, toRegister }: {
             </button>
           </form>
         )}
-        {isShellConfigured() && (
+        {/* Phone (SMS) sign-in needs a deliverable one-time code — hidden while SMS is
+            mocked, since a faked code can't mint a real session. Email + password + Google
+            all work without SMS. */}
+        {isShellConfigured() && !MOCK_OTP && (
           <button className="link" style={{ marginTop: 14, display: "block" }} onClick={onPhone}><Icon name="sms" size={15} /> Sign in with a phone number instead</button>
         )}
       </div>
@@ -428,7 +454,14 @@ function OtpVerify({ account, email, initialChannel = "email", remember, setReme
         if (!PHONE_RE.test(phone)) { setError("Enter your phone in international format, e.g. +14155550100."); return; }
         await sendPhoneOtp(phone); setSent(true);
       }
-    } catch (e) { setError((e as Error).message); }
+    } catch (e) {
+      // gotrue can throw an error whose message is an unhelpful "{}"/JSON blob (e.g. a
+      // 500 "Error sending magic link email" when SMTP isn't set up). Show something
+      // readable and actionable instead of the raw payload.
+      const raw = (e as { message?: unknown })?.message;
+      const readable = typeof raw === "string" && raw.trim() && !raw.trim().startsWith("{") ? raw.trim() : "";
+      setError(readable || "We couldn't send your sign-in code right now. Please try again shortly, or sign in with your password.");
+    }
   }
 
   async function complete(code: string) {
@@ -447,12 +480,22 @@ function OtpVerify({ account, email, initialChannel = "email", remember, setReme
     <div>
       <StepBack onClick={onBack} />
       <h1>{shell ? "One-time passcode" : "2-step verification"}</h1>
-      <p className="sub">{shell ? "We'll text or email you a 6-digit code to sign in." : "Enter the 6-digit code we sent you to finish signing in."}</p>
-      <div className="seg" style={{ margin: "16px 0 14px" }}>
-        <button className={channel === "email" ? "on" : ""} onClick={() => { setChannel("email"); setError(""); setSent(false); }}><Icon name="mail" size={15} /> Email</button>
-        <button className={channel === "sms" ? "on" : ""} onClick={() => { setChannel("sms"); setError(""); setSent(false); }}><Icon name="sms" size={15} /> SMS</button>
-        {!shell && <button className={channel === "wa" ? "on" : ""} onClick={() => { setChannel("wa"); setError(""); }}><Icon name="whatsapp" size={15} /> WhatsApp</button>}
-      </div>
+      <p className="sub">
+        {!shell
+          ? "Enter the 6-digit code we sent you to finish signing in."
+          : channel === "sms"
+            ? "We'll text a 6-digit code to sign in."
+            : "We'll email you a 6-digit code to sign in."}
+      </p>
+      {/* In Shell mode the channel is fixed by how you signed in (email vs phone) —
+          no toggle, so an email sign-in never shows a stray SMS option. */}
+      {!shell && (
+        <div className="seg" style={{ margin: "16px 0 14px" }}>
+          <button className={channel === "email" ? "on" : ""} onClick={() => { setChannel("email"); setError(""); setSent(false); }}><Icon name="mail" size={15} /> Email</button>
+          <button className={channel === "sms" ? "on" : ""} onClick={() => { setChannel("sms"); setError(""); setSent(false); }}><Icon name="sms" size={15} /> SMS</button>
+          <button className={channel === "wa" ? "on" : ""} onClick={() => { setChannel("wa"); setError(""); }}><Icon name="whatsapp" size={15} /> WhatsApp</button>
+        </div>
+      )}
 
       {shell && channel === "sms" && !sent ? (
         <form onSubmit={(e) => { e.preventDefault(); void send(); }}>

src/components/portal/register-flow.tsx

@@ -8,11 +8,12 @@ import {
   PasswordStrength, LegalModal,
 } from "./bits";
 import {
-  countryCodes, relationshipOptions, addressCountries,
+  countryCodes, addressCountries,
   TERMS, PRIVACY, passwordStrength, type AddrCountry,
 } from "./data";
 import { useAuth, useAppShell } from "@abe-kap/appshell-sdk/react";
 import { isShellConfigured } from "@/lib/appshell";
+import { MOCK_OTP, DEMO_OTP } from "@/lib/otp";
 
 type Addr = { line1?: string; line2?: string; city?: string; state?: string; postalCode?: string; country?: string; locality?: string };
 
@@ -25,10 +26,14 @@ export function RegisterFlow({ mode = "register" }: { mode?: "register" | "onboa
   // we only SET a password + persist the profile, and the OTP-verify step is skipped.
   const onboard = mode === "onboard";
   const router = useRouter();
-  const { register, setPassword, getUserEmail } = useAuth();
+  const { register, setPassword, getUserEmail, addPhone, verifyPhone } = useAuth();
   const { sdk } = useAppShell();
   const [step, setStep] = useState(0);
   const [submitErr, setSubmitErr] = useState("");
+  // Verifying a phone via Supabase needs a live session. Onboarding already has one
+  // (Google OAuth); registration creates the account when leaving the Account step,
+  // then attaches + verifies the phone on it. `creating` guards the Account button.
+  const [creating, setCreating] = useState(false);
 
   // address (lifted from StepAddress/AddressBlock so finish() can persist it)
   const [regAddr, setRegAddr] = useState<Addr>({});
@@ -43,38 +48,58 @@ export function RegisterFlow({ mode = "register" }: { mode?: "register" | "onboa
   const [cc, setCc] = useState("+1");
   const [phone, setPhone] = useState("");
   const [pw, setPw] = useState("");
-  const [relationship, setRelationship] = useState("Customer");
-  const [alloeNo, setAlloeNo] = useState("");
-  const [alloeFirst, setAlloeFirst] = useState("");
-  const [alloeLast, setAlloeLast] = useState("");
   const [termsOk, setTermsOk] = useState(false);
   const [privacyOk, setPrivacyOk] = useState(false);
 
-  // verify step
-  const [emailVerified, setEmailVerified] = useState(false);
+  // verify step (email is trusted without an OTP — see verifyValid below)
   const [phoneVerified, setPhoneVerified] = useState(false);
+  // When arriving from a team invite, the email is fixed to the invited address.
+  const [invitedEmail, setInvitedEmail] = useState("");
 
-  // Onboarding: prefill the verified email from the Google session (the ACE omits it).
+  useEffect(() => {
+    if (onboard) return;
+    try { const e = sessionStorage.getItem("invite_email"); if (e) { setEmail(e); setInvitedEmail(e); } } catch { /* ignore */ }
+  }, [onboard]);
+
+  // Onboarding: prefill the verified email — from the session-storage hint the login
+  // page stashed at OAuth time, then confirmed via the live Supabase session.
   useEffect(() => {
     if (!onboard) return;
+    try { const cached = sessionStorage.getItem("onboard_email"); if (cached) setEmail(cached); } catch { /* ignore */ }
     getUserEmail().then((e) => { if (e) setEmail(e); }).catch(() => { /* ignore */ });
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [onboard]);
 
-  const STEP_LABELS = onboard ? ["Profile", "Address"] : STEPS;
+  const STEP_LABELS = onboard ? ["Profile", "Verify", "Address"] : STEPS;
 
-  const isSelf = relationship === "Customer" || relationship === "Owner";
-  const isEmployee = relationship === "Employee";
   const country = countryCodes.find((c) => c.code === cc)!;
   const phoneOk = phone.replace(/\D/g, "").length === country.digits;
   const pwOk = sso ? true : passwordStrength(pw).score >= 3;
-  const alloeIdOk = /^(?=.*[a-zA-Z])(?=.*\d).{4,}$/.test(alloeNo);
 
   const step0Valid =
     first.trim() && last.trim() && EMAIL_RE.test(sso?.email || email) && phoneOk && pwOk &&
-    termsOk && privacyOk && (isSelf || (alloeIdOk && (isEmployee || (alloeFirst.trim() && alloeLast.trim()))));
+    termsOk && privacyOk;
 
-  const step2Valid = emailVerified && phoneVerified;
+  // Email is already trusted in both flows (registration: Supabase auto-confirms on
+  // signup; onboarding: Google-verified), so the Verify step only gates on the phone.
+  const verifyValid = phoneVerified;
+
+  // Registration: create the auth account when leaving the Account step, so the phone
+  // can be attached + verified against a live session at the Verify step. Onboarding
+  // is already authenticated, so it just advances.
+  async function leaveAccountStep() {
+    if (onboard || !isShellConfigured() || sso) { setStep(1); return; }
+    setSubmitErr("");
+    setCreating(true);
+    try {
+      await register(email, pw);
+      setStep(1);
+    } catch {
+      setSubmitErr("We couldn't create that account. The email may already be registered.");
+    } finally {
+      setCreating(false);
+    }
+  }
 
   async function finish() {
     const finalEmail = sso?.email || email;
@@ -82,32 +107,27 @@ export function RegisterFlow({ mode = "register" }: { mode?: "register" | "onboa
       name: `${first} ${last}`.trim(),
       initials: `${first[0] ?? ""}${last[0] ?? ""}`.toUpperCase(),
       email: finalEmail,
-      isAllottee: isSelf,
-      allotteeNames: isSelf ? null : `${alloeFirst} ${alloeLast}`.trim(),
     };
     try { localStorage.setItem("lup_profile", JSON.stringify(profile)); } catch { /* ignore */ }
 
     if (isShellConfigured()) {
       setSubmitErr("");
-      // 1) Auth account. Onboarding users are already authenticated via Google — set
-      //    a password so email+password login works too. Everyone else registers now.
-      if (onboard) {
-        try { if (pw) await setPassword(pw); } catch { /* non-fatal — the profile still saves */ }
-      } else if (!sso) {
-        try { await register(finalEmail, pw); }
-        catch { setSubmitErr("We couldn't create that account. The email may already be registered."); return; }
+      // 1) Auth account already exists at this point — registration created it when
+      //    leaving the Account step; onboarding users signed in via Google. Onboarding
+      //    additionally sets a password so email+password login works too (the phone was
+      //    just verified against the same live session).
+      if (onboard && pw) {
+        try { await setPassword(pw); } catch { /* non-fatal — the profile still saves */ }
       }
-      // 2) Persist the full CRM registration payload to be-crm (name, phone, persona,
-      //    allottee, both addresses, consent). Non-fatal: the auth account exists either way.
+      // 2) Persist the CRM registration payload to be-crm (name, phone, addresses,
+      //    consent). No role/persona — a new user has no permissions until invited.
+      //    Non-fatal: the auth account exists either way.
       try {
         const mailing = mailingSame ? regAddr : mailAddr;
         await sdk.command("crm.account.register", {
           email: finalEmail,
           firstName: first, lastName: last,
           phoneCc: cc, phoneNumber: phone.replace(/\D/g, ""),
-          persona: relationship,
-          isAllottee: isSelf,
-          ...(isSelf ? {} : { allotteeId: alloeNo, allotteeFirstName: alloeFirst, allotteeLastName: alloeLast }),
           registeredAddress: regAddr,
           mailingAddress: mailing,
           mailingSameAsRegistered: mailingSame,
@@ -117,7 +137,20 @@ export function RegisterFlow({ mode = "register" }: { mode?: "register" | "onboa
         if (onboard) { setSubmitErr("Couldn't save your profile. Please try again."); return; }
         // register mode: non-fatal — the auth account exists; the profile can be filled in later.
       }
+
+      // 3) If the user arrived from a team invitation link, redeem it now — this
+      //    creates their membership with the invited role(s). Non-fatal.
+      try {
+        const inviteToken = sessionStorage.getItem("invite_token");
+        if (inviteToken) {
+          await sdk.command("crm.team.invitation.accept", { token: inviteToken });
+          sessionStorage.removeItem("invite_token");
+          sessionStorage.removeItem("invite_email");
+        }
+      } catch { /* invitation expired/used — they can still be invited again */ }
     }
+    // Consume the OAuth→onboarding handoff so a stale hint can't re-open onboarding.
+    try { sessionStorage.removeItem("onboard_email"); } catch { /* ignore */ }
     router.push("/dashboard");
   }
 
@@ -126,34 +159,33 @@ export function RegisterFlow({ mode = "register" }: { mode?: "register" | "onboa
       <Stepper current={step} labels={STEP_LABELS} />
 
       {step === 0 && (
-        <StepAccount
-          onboard={onboard}
-          sso={sso} setSso={setSso} email={email} setEmail={setEmail}
-          first={first} setFirst={setFirst} last={last} setLast={setLast}
-          cc={cc} setCc={setCc} phone={phone} setPhone={setPhone} phoneOk={phoneOk} country={country}
-          pw={pw} setPw={setPw}
-          relationship={relationship} setRelationship={setRelationship} isSelf={isSelf}
-          alloeNo={alloeNo} setAlloeNo={setAlloeNo} alloeIdOk={alloeIdOk}
-          alloeFirst={alloeFirst} setAlloeFirst={setAlloeFirst} alloeLast={alloeLast} setAlloeLast={setAlloeLast}
-          termsOk={termsOk} setTermsOk={setTermsOk} privacyOk={privacyOk} setPrivacyOk={setPrivacyOk}
-          valid={!!step0Valid}
-          onContinue={() => setStep(1)} toLogin={() => router.push("/portal/login")}
-        />
-      )}
-
-      {step === 1 && !onboard && (
-        <StepVerify
-          emailValue={sso?.email || email} cc={cc} phone={phone} country={country}
-          emailVerified={emailVerified} setEmailVerified={setEmailVerified}
-          phoneVerified={phoneVerified} setPhoneVerified={setPhoneVerified}
-          valid={step2Valid} onBack={() => setStep(0)} onContinue={() => setStep(2)}
-        />
-      )}
-
-      {((onboard && step === 1) || (!onboard && step === 2)) && (
         <>
           {submitErr && <div style={{ marginBottom: 14 }}><FlashNote tone="error">{submitErr}</FlashNote></div>}
-          <StepAddress sameAs={mailingSame} setSameAs={setMailingSame} onRegAddr={setRegAddr} onMailAddr={setMailAddr} onBack={() => setStep(onboard ? 0 : 1)} onFinish={finish} />
+          <StepAccount
+            onboard={onboard} creating={creating} invited={!!invitedEmail}
+            sso={sso} setSso={setSso} email={email} setEmail={setEmail}
+            first={first} setFirst={setFirst} last={last} setLast={setLast}
+            cc={cc} setCc={setCc} phone={phone} setPhone={setPhone} phoneOk={phoneOk} country={country}
+            pw={pw} setPw={setPw}
+            termsOk={termsOk} setTermsOk={setTermsOk} privacyOk={privacyOk} setPrivacyOk={setPrivacyOk}
+            valid={!!step0Valid}
+            onContinue={leaveAccountStep} toLogin={() => router.push("/portal/login")}
+          />
+        </>
+      )}
+
+      {step === 1 && (
+        <StepVerify
+          cc={cc} phone={phone} country={country}
+          phoneVerified={phoneVerified} setPhoneVerified={setPhoneVerified}
+          valid={verifyValid} onBack={() => setStep(0)} onContinue={() => setStep(2)}
+        />
+      )}
+
+      {step === 2 && (
+        <>
+          {submitErr && <div style={{ marginBottom: 14 }}><FlashNote tone="error">{submitErr}</FlashNote></div>}
+          <StepAddress sameAs={mailingSame} setSameAs={setMailingSame} onRegAddr={setRegAddr} onMailAddr={setMailAddr} onBack={() => setStep(1)} onFinish={finish} />
         </>
       )}
     </div>
@@ -167,11 +199,8 @@ function StepAccount(p: {
   first: string; setFirst: (v: string) => void; last: string; setLast: (v: string) => void;
   cc: string; setCc: (v: string) => void; phone: string; setPhone: (v: string) => void; phoneOk: boolean; country: typeof countryCodes[number];
   pw: string; setPw: (v: string) => void;
-  relationship: string; setRelationship: (v: string) => void; isSelf: boolean;
-  alloeNo: string; setAlloeNo: (v: string) => void; alloeIdOk: boolean;
-  alloeFirst: string; setAlloeFirst: (v: string) => void; alloeLast: string; setAlloeLast: (v: string) => void;
   termsOk: boolean; setTermsOk: (v: boolean) => void; privacyOk: boolean; setPrivacyOk: (v: boolean) => void;
-  valid: boolean; onContinue: () => void; toLogin: () => void; onboard?: boolean;
+  valid: boolean; onContinue: () => void; toLogin: () => void; onboard?: boolean; creating?: boolean; invited?: boolean;
 }) {
   // Onboarding (OAuth) starts on the profile step — email is already known + verified.
   const [phase, setPhase] = useState<"sso" | "profile">(p.onboard ? "profile" : "sso");
@@ -181,36 +210,42 @@ function StepAccount(p: {
     const valid = EMAIL_RE.test(p.email);
     return (
       <div>
-        <h1>Create your account</h1>
-        <p className="sub">Enter your email to get started.</p>
+        <StepBack onClick={p.toLogin} />
+        <h1>{p.invited ? "Accept your invitation" : "Create your account"}</h1>
+        <p className="sub">{p.invited ? "You've been invited to the team. Set up your account to join." : "Enter your email to get started."}</p>
         <div style={{ marginTop: 20 }}>
           <form onSubmit={(e) => { e.preventDefault(); if (valid) { p.setSso(null); setPhase("profile"); } }}>
             <div className="field">
               <label className="label">Email address</label>
               <div className="input-wrap">
                 <span className="input-ico"><Icon name="mail" size={17} /></span>
-                <input className="input" type="email" value={p.email} onChange={(e) => p.setEmail(e.target.value)} placeholder="you@example.com" autoFocus />
+                <input className="input" type="email" value={p.email} onChange={(e) => p.setEmail(e.target.value)} placeholder="you@example.com" autoFocus={!p.invited} disabled={p.invited} readOnly={p.invited} />
               </div>
+              {p.invited && <span className="faint" style={{ fontSize: 12 }}>This is the address you were invited with.</span>}
             </div>
             <button className="btn btn-primary" style={{ marginTop: 12 }} disabled={!valid}>Continue <Icon name="arrowR" size={16} /></button>
           </form>
         </div>
-        <p className="foot-note">Already registered? <button className="link" onClick={p.toLogin}>Sign in</button></p>
+        {!p.invited && <p className="foot-note">Already registered? <button className="link" onClick={p.toLogin}>Sign in</button></p>}
       </div>
     );
   }
 
   return (
     <div>
+      {/* Non-onboarding users can step back to the email screen; onboarding starts
+          here (email came from Google), so there's nothing to go back to. */}
+      {!p.onboard && <StepBack onClick={() => setPhase("sso")} />}
       <h1>Complete your profile</h1>
       <p className="sub">Tell us a bit about you to set up your account.</p>
 
-      <div style={{ marginTop: 16 }}>
-        {p.sso ? (
-          <div className="conn-banner conn-green"><Icon name="check" size={16} /> Connected with {cap(p.sso.provider)} · {p.sso.email}</div>
-        ) : (
-          <div className="conn-banner conn-blue"><Icon name="mail" size={16} /> {p.onboard ? "Signed in as" : "Creating account for"} {p.email}</div>
-        )}
+      <div className="field" style={{ marginTop: 16 }}>
+        <label className="label">Email address</label>
+        <div className="input-wrap">
+          <span className="input-ico"><Icon name="mail" size={17} /></span>
+          <input className="input" type="email" value={p.email} disabled readOnly aria-label="Email address" />
+        </div>
+        <span className="faint" style={{ fontSize: 12 }}>{p.onboard ? "Verified with Google — this can't be changed." : "The email you're registering with."}</span>
       </div>
 
       <div className="row gap-3" style={{ marginTop: 18, alignItems: "center" }}>
@@ -254,47 +289,6 @@ function StepAccount(p: {
         </div>
       )}
 
-      <div className="field" style={{ marginTop: 14 }}>
-        <label className="label">Your role</label>
-        <select className="input" value={p.relationship} onChange={(e) => p.setRelationship(e.target.value)}>
-          {relationshipOptions.map((r) => <option key={r}>{r}</option>)}
-        </select>
-      </div>
-
-      {p.isSelf ? (
-        <div style={{ marginTop: 12 }}><FlashNote tone="success">{p.relationship === "Owner" ? "Owner" : "Customer"} account — you own this property.</FlashNote></div>
-      ) : (() => {
-        const isEmployee = p.relationship === "Employee";
-        const cfg = ({
-          Employee:  { banner: "Registering as a LynkedUp Pro team member.", title: "Employee details", idLabel: "Employee ID", idPh: "EMP-12345" },
-          Contractor:{ banner: "Registering on behalf of the property owner.", title: "Contractor details", idLabel: "Contractor ID", idPh: "Alphanumeric ID" },
-          "Sub-Con": { banner: "Registering on behalf of the property owner.", title: "Sub-contractor details", idLabel: "Sub-contractor ID", idPh: "Alphanumeric ID" },
-          Vendor:    { banner: "Registering on behalf of the property owner.", title: "Vendor details", idLabel: "Vendor ID", idPh: "Alphanumeric ID" },
-        } as Record<string, { banner: string; title: string; idLabel: string; idPh: string }>)[p.relationship]
-          ?? { banner: "Registering on behalf of the property owner.", title: "Property Owner Details", idLabel: "Owner / Property ID", idPh: "Alphanumeric ID" };
-        return (
-          <div style={{ marginTop: 12 }}>
-            <FlashNote tone="info">{cfg.banner}</FlashNote>
-            <div className="dashed-block" style={{ marginTop: 12 }}>
-              <div className="row between" style={{ marginBottom: 12 }}>
-                <strong style={{ fontSize: 13.5 }}>{cfg.title}</strong>
-                {p.alloeNo && (p.alloeIdOk ? <Badge tone="green"><Icon name="check" size={12} /> Valid</Badge> : <Badge tone="gray">Checking…</Badge>)}
-              </div>
-              <div className="field">
-                <label className="label">{cfg.idLabel}</label>
-                <input className="input" value={p.alloeNo} onChange={(e) => p.setAlloeNo(e.target.value.toUpperCase())} placeholder={cfg.idPh} />
-              </div>
-              {!isEmployee && (
-                <div className="row gap-3" style={{ marginTop: 12 }}>
-                  <div className="field grow"><label className="label">Owner first name</label><input className="input" value={p.alloeFirst} onChange={(e) => p.setAlloeFirst(e.target.value)} /></div>
-                  <div className="field grow"><label className="label">Owner last name</label><input className="input" value={p.alloeLast} onChange={(e) => p.setAlloeLast(e.target.value)} /></div>
-                </div>
-              )}
-            </div>
-          </div>
-        );
-      })()}
-
       <div className="col gap-2" style={{ marginTop: 16 }}>
         <label className="check-row">
           <input type="checkbox" checked={p.termsOk} disabled={!reviewed.terms} onChange={(e) => p.setTermsOk(e.target.checked)} />
@@ -308,7 +302,9 @@ function StepAccount(p: {
 
       {!p.valid && <p className="hint-line">Fill all required fields and accept both documents to continue.</p>}
 
-      <button className="btn btn-primary" style={{ marginTop: 14 }} disabled={!p.valid} onClick={p.onContinue}>{p.onboard ? "Continue" : "Create Account & Verify"} <Icon name="arrowR" size={16} /></button>
+      <button className="btn btn-primary" style={{ marginTop: 14 }} disabled={!p.valid || p.creating} onClick={p.onContinue}>
+        {p.creating ? "Creating account…" : p.onboard ? "Continue" : "Create Account & Verify"} {!p.creating && <Icon name="arrowR" size={16} />}
+      </button>
 
       {modal === "terms" && <LegalModal doc={TERMS} onClose={() => setModal(null)} onReviewed={() => { reviewed.terms = true; setModal(null); }} />}
       {modal === "privacy" && <LegalModal doc={PRIVACY} onClose={() => setModal(null)} onReviewed={() => { reviewed.privacy = true; setModal(null); }} />}
@@ -318,10 +314,13 @@ function StepAccount(p: {
 // module-level reviewed flags (per mount lifetime) — enables the checkboxes after a doc is read
 const reviewed = { terms: false, privacy: false };
 
-/* ====================== STEP 1 — VERIFY ====================== */
+/* ====================== STEP 1 — VERIFY PHONE ======================
+   Email is already trusted (registration: Supabase auto-confirms on signup;
+   onboarding: Google-verified), so this step only verifies the phone via a real
+   SMS OTP: addPhone() → Twilio texts a code → verifyPhone() confirms it. Both
+   run against the live Supabase session established in the previous step. */
 function StepVerify(p: {
-  emailValue: string; cc: string; phone: string; country: typeof countryCodes[number];
-  emailVerified: boolean; setEmailVerified: (v: boolean) => void;
+  cc: string; phone: string; country: typeof countryCodes[number];
   phoneVerified: boolean; setPhoneVerified: (v: boolean) => void;
   valid: boolean; onBack: () => void; onContinue: () => void;
 }) {
@@ -329,12 +328,11 @@ function StepVerify(p: {
   return (
     <div>
       <StepBack onClick={p.onBack} />
-      <h1>Verify email &amp; phone</h1>
-      <p className="sub">Confirm both so we can secure your account.</p>
+      <h1>Verify your phone</h1>
+      <p className="sub">We&apos;ll text a one-time code to confirm your number. Your email is already verified.</p>
 
       <div className="col gap-4" style={{ marginTop: 16 }}>
-        <VerifyChannel kind="email" initial={p.emailValue} country={p.country} cc={p.cc} initialPhone={p.phone} verified={p.emailVerified} onVerified={() => p.setEmailVerified(true)} />
-        <VerifyChannel kind="phone" initial={p.emailValue} country={p.country} cc={p.cc} initialPhone={p.phone} verified={p.phoneVerified} onVerified={() => p.setPhoneVerified(true)} />
+        <PhoneVerify cc={p.cc} country={p.country} initialPhone={p.phone} verified={p.phoneVerified} onVerified={() => p.setPhoneVerified(true)} />
       </div>
 
       <div style={{ marginTop: 14 }}><RememberDevice checked={remember} onChange={setRemember} /></div>
@@ -343,40 +341,53 @@ function StepVerify(p: {
   );
 }
 
-type SendState = "idle" | "sending" | "ok" | "invalid_email" | "mailbox_full" | "bounce_risk" | "invalid_mobile";
-function VerifyChannel({ kind, initial, country, cc, initialPhone, verified, onVerified }: {
-  kind: "email" | "phone"; initial: string; country: typeof countryCodes[number]; cc: string; initialPhone: string;
+type SendState = "idle" | "sending" | "sent" | "invalid_mobile" | "send_error";
+function PhoneVerify({ cc, country, initialPhone, verified, onVerified }: {
+  cc: string; country: typeof countryCodes[number]; initialPhone: string;
   verified: boolean; onVerified: () => void;
 }) {
-  const [value, setValue] = useState(kind === "email" ? initial : initialPhone);
-  const [via, setVia] = useState<"primary" | "wa">("primary");
+  const { addPhone, verifyPhone } = useAuth();
+  const [value, setValue] = useState(initialPhone);
   const [state, setState] = useState<SendState>("idle");
-  const [otpError, setOtpError] = useState(false);
-  const primaryLabel = kind === "email" ? "Email" : "SMS";
+  const [otpError, setOtpError] = useState("");
+  const e164 = `${cc}${value.replace(/\D/g, "")}`;
 
-  function send() {
+  async function send() {
+    if (value.replace(/\D/g, "").length !== country.digits) { setState("invalid_mobile"); return; }
     setState("sending");
-    setTimeout(() => {
-      if (kind === "email") {
-        if (!EMAIL_RE.test(value)) return setState("invalid_email");
-        if (value.includes("full")) return setState("mailbox_full");
-        if (value.includes("bo")) return setState("bounce_risk");
-        return setState("ok");
-      } else {
-        if (value.replace(/\D/g, "").length !== country.digits) return setState("invalid_mobile");
-        return setState("ok");
-      }
-    }, 700);
+    setOtpError("");
+    if (MOCK_OTP) { setState("sent"); return; }   // demo: skip Twilio entirely
+    try {
+      await addPhone(e164);         // Supabase → Twilio sends the SMS OTP
+      setState("sent");
+    } catch {
+      setState("send_error");
+    }
+  }
+
+  async function submit(code: string) {
+    setOtpError("");
+    if (MOCK_OTP) {
+      if (code === DEMO_OTP) onVerified();
+      else setOtpError(`Demo mode — enter ${DEMO_OTP} to verify.`);
+      return;
+    }
+    try {
+      await verifyPhone(e164, code); // confirm the OTP (phone_change)
+      onVerified();
+    } catch {
+      setOtpError("That code didn't match. Check the SMS and try again.");
+    }
   }
 
   if (verified) {
     return (
       <div className="vchannel verified">
         <div className="row between">
-          <span className="row gap-2" style={{ fontWeight: 600, fontSize: 14 }}><Icon name={kind === "email" ? "mail" : "phone"} size={16} /> {kind === "email" ? "Email" : "Mobile"}</span>
+          <span className="row gap-2" style={{ fontWeight: 600, fontSize: 14 }}><Icon name="phone" size={16} /> Mobile</span>
           <Badge tone="green"><Icon name="check" size={12} /> Verified</Badge>
         </div>
-        <p className="faint" style={{ fontSize: 12.5, marginTop: 8 }}>{kind === "email" ? value : `${cc} ${value}`}</p>
+        <p className="faint" style={{ fontSize: 12.5, marginTop: 8 }}>{cc} {value}</p>
       </div>
     );
   }
@@ -384,43 +395,34 @@ function VerifyChannel({ kind, initial, country, cc, initialPhone, verified, onV
   return (
     <div className="vchannel">
       <div className="row between" style={{ marginBottom: 12 }}>
-        <span className="row gap-2" style={{ fontWeight: 600, fontSize: 14 }}><Icon name={kind === "email" ? "mail" : "phone"} size={16} /> {kind === "email" ? "Email address" : "Mobile number"}</span>
+        <span className="row gap-2" style={{ fontWeight: 600, fontSize: 14 }}><Icon name="phone" size={16} /> Mobile number</span>
       </div>
 
-      {kind === "email" ? (
-        <input className="input" value={value} onChange={(e) => { setValue(e.target.value); setState("idle"); }} placeholder="you@example.com" />
-      ) : (
-        <div className="phone-row">
-          <span className="input cc-select" style={{ display: "flex", alignItems: "center", justifyContent: "center", gap: 7 }}>
-            {/* eslint-disable-next-line @next/next/no-img-element */}
-            <img className="cc-flag-img static" src={flagUrl(country.flag)} alt={country.name} width={22} height={16} />
-            {cc}
-          </span>
-          <input className="input grow" inputMode="numeric" value={value} onChange={(e) => { setValue(e.target.value.replace(/\D/g, "")); setState("idle"); }} placeholder={country.example} />
-        </div>
-      )}
+      <div className="phone-row">
+        <span className="input cc-select" style={{ display: "flex", alignItems: "center", justifyContent: "center", gap: 7 }}>
+          {/* eslint-disable-next-line @next/next/no-img-element */}
+          <img className="cc-flag-img static" src={flagUrl(country.flag)} alt={country.name} width={22} height={16} />
+          {cc}
+        </span>
+        <input className="input grow" inputMode="numeric" value={value} disabled={state === "sent"} onChange={(e) => { setValue(e.target.value.replace(/\D/g, "")); setState("idle"); }} placeholder={country.example} />
+      </div>
 
       <div className="row between" style={{ marginTop: 12 }}>
-        <div className="seg">
-          <button className={via === "primary" ? "on" : ""} onClick={() => setVia("primary")}>{primaryLabel}</button>
-          <button className={via === "wa" ? "on" : ""} onClick={() => setVia("wa")}><Icon name="whatsapp" size={14} /> WhatsApp</button>
-        </div>
-        <button className="btn btn-sm" style={{ width: "auto" }} disabled={state === "sending" || state === "ok"} onClick={send}>
-          {state === "sending" ? "Sending…" : "Send code"}
+        <span className="faint" style={{ fontSize: 12 }}>{MOCK_OTP ? "Demo verification (no SMS sent)." : "Standard SMS rates may apply."}</span>
+        <button className="btn btn-sm" style={{ width: "auto" }} disabled={state === "sending" || state === "sent"} onClick={send}>
+          {state === "sending" ? "Sending…" : state === "sent" ? "Sent" : "Send code"}
         </button>
       </div>
 
-      {state === "ok" && <p className="faint" style={{ fontSize: 12, marginTop: 10 }}>OTP sent via {via === "wa" ? "WhatsApp" : primaryLabel}.</p>}
-      {state === "invalid_email" && <div style={{ marginTop: 10 }}><FlashNote tone="error">That email address looks invalid.</FlashNote></div>}
-      {state === "mailbox_full" && <div style={{ marginTop: 10 }}><FlashNote tone="warn">This mailbox appears full — try another email.</FlashNote></div>}
-      {state === "bounce_risk" && <div style={{ marginTop: 10 }}><FlashNote tone="warn">High bounce risk for this address.</FlashNote></div>}
+      {state === "sent" && <p className="faint" style={{ fontSize: 12, marginTop: 10 }}>{MOCK_OTP ? `Demo mode — enter ${DEMO_OTP} to verify (SMS temporarily disabled).` : `Code sent to ${cc} ${value} by SMS.`}</p>}
       {state === "invalid_mobile" && <div style={{ marginTop: 10 }}><FlashNote tone="error">Enter a valid {country.digits}-digit mobile number.</FlashNote></div>}
+      {state === "send_error" && <div style={{ marginTop: 10 }}><FlashNote tone="error">Couldn&apos;t send the code. Check the number and try again.</FlashNote></div>}
 
-      {state === "ok" && (
+      {state === "sent" && (
         <div style={{ marginTop: 14 }}>
-          <OtpBoxes onComplete={(c) => { if (c === "000000") setOtpError(true); else { setOtpError(false); onVerified(); } }} error={otpError} />
-          {otpError && <div style={{ marginTop: 10 }}><FlashNote tone="error">Incorrect code.</FlashNote></div>}
-          <div style={{ marginTop: 12 }}><ResendLink seconds={60} /></div>
+          <OtpBoxes onComplete={submit} error={!!otpError} />
+          {otpError && <div style={{ marginTop: 10 }}><FlashNote tone="error">{otpError}</FlashNote></div>}
+          <div style={{ marginTop: 12 }}><ResendLink seconds={60} onResend={send} /></div>
         </div>
       )}
     </div>

src/lib/access.ts

@@ -0,0 +1,66 @@
+"use client";
+
+import { useQuery } from "@abe-kap/appshell-sdk/react";
+import { isShellConfigured } from "./appshell";
+
+/**
+ * The signed-in user's effective CRM access, from crm.account.me. Drives navigation
+ * gating: a user with no membership/permissions sees only Dashboard + Profile; members
+ * see the areas their permissions allow.
+ *
+ * Every CRM permission id, granted to superadmins / owners. Used as the mock default
+ * when the Shell isn't configured (local demo shows everything).
+ */
+export const ALL_CRM_PERMISSIONS = [
+  "leads.manage", "pipeline.manage", "estimates.create", "dispatch.manage",
+  "reports.view", "billing.view", "team.manage", "roles.manage", "settings.manage",
+] as const;
+
+export interface MyAccess {
+  registered: boolean;
+  isMember: boolean;
+  roleSlugs: string[];
+  permissions: string[];
+  isSuperadmin: boolean;
+  /** True while the access query is still resolving (nav stays minimal until then). */
+  loading: boolean;
+  can: (permission: string) => boolean;
+}
+
+interface MeDTO {
+  registered: boolean;
+  isMember: boolean;
+  roleSlugs: string[];
+  permissions: string[];
+  isSuperadmin: boolean;
+}
+
+function useLiveAccess(): MyAccess {
+  const { data, loading } = useQuery<MeDTO>("crm.account.me");
+  const permissions = data?.permissions ?? [];
+  return {
+    registered: data?.registered ?? false,
+    isMember: data?.isMember ?? false,
+    roleSlugs: data?.roleSlugs ?? [],
+    permissions,
+    isSuperadmin: data?.isSuperadmin ?? false,
+    loading,
+    can: (p: string) => permissions.includes(p),
+  };
+}
+
+function useMockAccess(): MyAccess {
+  // No Shell (local demo): show everything so the mock UI is fully browsable.
+  const permissions = [...ALL_CRM_PERMISSIONS];
+  return {
+    registered: true,
+    isMember: true,
+    roleSlugs: ["superadmin"],
+    permissions,
+    isSuperadmin: true,
+    loading: false,
+    can: () => true,
+  };
+}
+
+export const useMyAccess: () => MyAccess = isShellConfigured() ? useLiveAccess : useMockAccess;

src/lib/inbox-api.ts

@@ -0,0 +1,95 @@
+"use client";
+
+// Inbox data layer. The inbox is a personalized work/awareness feed IIOS projects from events
+// (NEEDS_REPLY, MENTION, …). The CRM lists it and transitions item state; items are never created
+// here. Mock when the Shell isn't configured; live via the be-crm data door (crm.inbox.*) otherwise.
+//
+// Live contract (be-crm):
+//   query crm.inbox.list       { state? }              -> InboxItem[]
+//   cmd   crm.inbox.transition { id, state, reason? }  -> InboxItem
+
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { useAppShell, useQuery } from "@abe-kap/appshell-sdk/react";
+import { isShellConfigured } from "./appshell";
+import type { MailThread } from "./mail-api";
+
+export type InboxState = "OPEN" | "SNOOZED" | "DONE" | "ARCHIVED" | "CANCELLED" | "STALE";
+export interface UiInboxItem {
+  id: string; kind: string; state: InboxState; title: string; summary?: string;
+  priority: string; threadId?: string; createdAt: string;
+}
+
+const SHELL = isShellConfigured();
+
+export interface InboxData {
+  live: boolean; loading: boolean; error: string | null;
+  items: UiInboxItem[];
+  transition: (id: string, state: InboxState) => Promise<void>;
+  refetch: () => void;
+}
+
+export function useInboxData(state?: InboxState): InboxData {
+  return SHELL ? useLiveInbox(state) : useMockInbox(state);
+}
+
+function useLiveInbox(state?: InboxState): InboxData {
+  const { sdk } = useAppShell();
+  const q = useQuery<UiInboxItem[]>("crm.inbox.list", state ? { state } : {});
+  // Mail lives in crm-mail threads, NOT the inbox projection — fold it into the one unified
+  // surface. Mail has no inbox work-item state, so it only shows in the Open (or unfiltered) view.
+  const showMail = !state || state === "OPEN";
+  const mq = useQuery<MailThread[]>("crm.mail.list", {});
+
+  // The SDK's useQuery only refetches when the ACTION changes, not the variables — so a filter
+  // change (same action, new { state }) wouldn't reload. Force a refetch when the filter changes.
+  const refetchInbox = q.refetch;
+  useEffect(() => { refetchInbox(); }, [state, refetchInbox]);
+
+  const items = useMemo<UiInboxItem[]>(() => {
+    const inboxItems = q.data ?? [];
+    const mailItems: UiInboxItem[] = showMail
+      ? (mq.data ?? []).map((t) => ({
+          id: `mail:${t.threadId}`,
+          kind: "MAIL",
+          state: "OPEN" as InboxState,
+          title: t.subject || "(no subject)",
+          ...(t.lastMessage ? { summary: t.lastMessage } : {}),
+          priority: t.unread > 0 ? "HIGH" : "LOW",
+          threadId: t.threadId,
+          createdAt: t.lastAt ?? "",
+        }))
+      : [];
+    // Newest first; mail and inbox items interleave by time.
+    return [...mailItems, ...inboxItems].sort((a, b) => (b.createdAt ?? "").localeCompare(a.createdAt ?? ""));
+  }, [q.data, mq.data, showMail]);
+
+  const transition = useCallback(async (id: string, next: InboxState) => {
+    await sdk.command("crm.inbox.transition", { id, state: next });
+    q.refetch();
+  }, [sdk, q]);
+
+  return {
+    live: true,
+    loading: q.loading || (showMail && mq.loading),
+    // Don't let a mail-list hiccup blank the whole inbox — surface only the inbox error.
+    error: q.error?.message ?? null,
+    items,
+    transition,
+    refetch: () => { q.refetch(); mq.refetch(); },
+  };
+}
+
+const MOCK_ITEMS: UiInboxItem[] = [
+  { id: "in_1", kind: "MENTION", state: "OPEN", title: "Sofia mentioned you", summary: "@you — can you confirm the Henderson scope?", priority: "HIGH", threadId: "th_mock_1", createdAt: new Date().toISOString() },
+  { id: "in_2", kind: "NEEDS_REPLY", state: "OPEN", title: "Reply needed — Storm response", summary: "Dan: Crew is rolling out at 7.", priority: "MEDIUM", threadId: "th_mock_2", createdAt: new Date().toISOString() },
+  { id: "in_3", kind: "SUPPORT_UPDATE", state: "OPEN", title: "Ticket TK-204 updated", summary: "Customer replied on the roof-leak case.", priority: "LOW", createdAt: new Date().toISOString() },
+];
+
+function useMockInbox(state?: InboxState): InboxData {
+  const [items, setItems] = useState<UiInboxItem[]>(MOCK_ITEMS);
+  const filtered = useMemo(() => (state ? items.filter((i) => i.state === state) : items), [items, state]);
+  const transition = useCallback(async (id: string, next: InboxState) => {
+    setItems((l) => l.map((i) => (i.id === id ? { ...i, state: next } : i)));
+  }, []);
+  return { live: false, loading: false, error: null, items: filtered, transition, refetch: () => {} };
+}

src/lib/mail-api.ts

@@ -0,0 +1,121 @@
+"use client";
+
+// Mail data layer. A dedicated Mail reader over the be-crm data door (crm.mail.*), distinct from
+// the Messenger chat and from the work-item Inbox. Live via the AppShell SDK; a small mock keeps the
+// demo working before the Shell + be-crm are connected.
+//
+// Live contract (be-crm):
+//   query crm.mail.list      {}                          -> MailThread[]
+//   query crm.mail.history   { threadId }                -> MailMessage[]
+//   cmd   crm.mail.reply     { threadId, content }       -> { interactionId, threadId }
+//   cmd   crm.mail.internal  { recipientUserId, subject?, text?, html? } -> { threadId }
+//   cmd   crm.mail.send      { target, subject?, text?, html?, mirrorToUserId? } -> { commandId }
+//   query crm.messenger.directory { kind, limit }        -> people to compose to (reused)
+
+import { useCallback, useMemo, useState } from "react";
+import { useAppShell, useQuery } from "@abe-kap/appshell-sdk/react";
+import { isShellConfigured } from "./appshell";
+
+export interface MailThread {
+  threadId: string; subject: string | null; participants: string[]; unread: number; lastMessage?: string; lastAt?: string;
+}
+export interface MailAttachment { contentRef: string; mimeType: string; sizeBytes: number; filename: string | null }
+export interface MailMessage {
+  interactionId: string; actorId: string | null; kind: string; occurredAt: string; html: string | null; text: string | null; attachment: MailAttachment | null;
+}
+export interface MailPerson { id: string; name: string; kind: "staff" | "customer" }
+
+/** Shape produced by media-api's useUploadAttachment, passed into a reply/compose. */
+export interface OutgoingAttachment { contentRef: string; mimeType: string; sizeBytes: number; filename: string }
+
+const SHELL = isShellConfigured();
+
+/* ============================ Thread list ============================ */
+
+export interface MailListData {
+  live: boolean; loading: boolean; error: string | null; threads: MailThread[]; refetch: () => void;
+}
+
+export function useMailThreads(): MailListData {
+  if (SHELL) {
+    const q = useQuery<MailThread[]>("crm.mail.list", {});
+    return { live: true, loading: q.loading, error: q.error?.message ?? null, threads: q.data ?? [], refetch: q.refetch };
+  }
+  return { live: false, loading: false, error: null, threads: MOCK_THREADS, refetch: () => {} };
+}
+
+/* ============================ One thread ============================ */
+
+export interface MailThreadData {
+  loading: boolean; error: string | null; messages: MailMessage[]; reply: (content: string, attachment?: OutgoingAttachment) => Promise<void>; refetch: () => void;
+}
+
+export function useMailThread(threadId: string | null): MailThreadData {
+  if (SHELL) return useLiveThread(threadId);
+  return useMockThread(threadId);
+}
+
+function useLiveThread(threadId: string | null): MailThreadData {
+  const { sdk } = useAppShell();
+  const q = useQuery<MailMessage[]>("crm.mail.history", threadId ? { threadId } : { threadId: "" });
+  const reply = useCallback(async (content: string, attachment?: OutgoingAttachment) => {
+    if (!threadId) return;
+    await sdk.command("crm.mail.reply", { threadId, content, ...(attachment ? { attachment } : {}) });
+    q.refetch();
+  }, [sdk, threadId, q]);
+  return { loading: q.loading, error: q.error?.message ?? null, messages: threadId ? (q.data ?? []) : [], reply, refetch: q.refetch };
+}
+
+/* ============================ Compose ============================ */
+
+export interface ComposeData {
+  directory: MailPerson[];
+  sendInternal: (recipientUserId: string, subject: string, text: string, attachments?: OutgoingAttachment[]) => Promise<void>;
+  sendExternal: (target: string, subject: string, text: string, opts?: { mirrorToUserId?: string; attachments?: OutgoingAttachment[] }) => Promise<void>;
+}
+
+export function useMailCompose(onSent: () => void): ComposeData {
+  if (SHELL) {
+    const { sdk } = useAppShell();
+    const dirQ = useQuery<MailPerson[]>("crm.messenger.directory", { kind: "all", limit: 100 });
+    const directory = useMemo(() => (dirQ.data ?? []).map((d) => ({ id: (d as unknown as { id: string }).id, name: (d as unknown as { displayName?: string; name?: string }).displayName ?? (d as unknown as { name?: string }).name ?? "", kind: (d as MailPerson).kind })), [dirQ.data]);
+    const sendInternal = useCallback(async (recipientUserId: string, subject: string, text: string, attachments?: OutgoingAttachment[]) => {
+      await sdk.command("crm.mail.internal", { recipientUserId, subject, text, html: `<p>${escapeHtml(text)}</p>`, ...(attachments && attachments.length ? { attachments } : {}) });
+      onSent();
+    }, [sdk, onSent]);
+    const sendExternal = useCallback(async (target: string, subject: string, text: string, opts?: { mirrorToUserId?: string; attachments?: OutgoingAttachment[] }) => {
+      await sdk.command("crm.mail.send", { target, subject, text, html: `<p>${escapeHtml(text)}</p>`, ...(opts?.mirrorToUserId ? { mirrorToUserId: opts.mirrorToUserId } : {}), ...(opts?.attachments && opts.attachments.length ? { attachments: opts.attachments } : {}) });
+      onSent();
+    }, [sdk, onSent]);
+    return { directory, sendInternal, sendExternal };
+  }
+  return { directory: MOCK_PEOPLE, sendInternal: async () => onSent(), sendExternal: async () => onSent() };
+}
+
+function escapeHtml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+/* ============================ Mock (demo mode) ============================ */
+
+const now = () => new Date().toISOString();
+const MOCK_PEOPLE: MailPerson[] = [
+  { id: "pp_sofia", name: "Sofia Ramirez", kind: "staff" },
+  { id: "cust_acme", name: "Acme Roofing (Client)", kind: "customer" },
+];
+const MOCK_THREADS: MailThread[] = [
+  { threadId: "mt_1", subject: "Welcome to the Founders Club", participants: ["you", "system"], unread: 1, lastMessage: "Thanks for joining…", lastAt: now() },
+  { threadId: "mt_2", subject: "Storm response — East side", participants: ["you", "pp_sofia"], unread: 0, lastMessage: "Crew rolling out at 7", lastAt: now() },
+];
+function useMockThread(threadId: string | null): MailThreadData {
+  const [extra, setExtra] = useState<MailMessage[]>([]);
+  const base: MailMessage[] = threadId === "mt_1"
+    ? [{ interactionId: "m1", actorId: "system", kind: "EMAIL", occurredAt: now(), html: "<p>Thanks for joining the <b>Founders Club</b>. Set up your account to get started.</p>", text: "Thanks for joining the Founders Club.", attachment: null }]
+    : threadId === "mt_2"
+      ? [{ interactionId: "m2", actorId: "pp_sofia", kind: "EMAIL", occurredAt: now(), html: "<p>Crew is rolling out at 7. Confirm the Henderson scope?</p>", text: "Crew rolling out at 7.", attachment: null }]
+      : [];
+  const reply = useCallback(async (content: string, attachment?: OutgoingAttachment) => {
+    setExtra((l) => [...l, { interactionId: `r_${l.length}`, actorId: "you", kind: "MESSAGE", occurredAt: now(), html: null, text: content, attachment: attachment ? { contentRef: attachment.contentRef, mimeType: attachment.mimeType, sizeBytes: attachment.sizeBytes, filename: attachment.filename } : null }]);
+  }, []);
+  return { loading: false, error: null, messages: threadId ? [...base, ...extra] : [], reply, refetch: () => {} };
+}

src/lib/media-api.ts

@@ -0,0 +1,37 @@
+"use client";
+
+// Media (attachment) helpers over the be-crm data door (crm.media.*). The browser transfers bytes
+// DIRECTLY to IIOS storage via the signed URLs — be-crm only mints them. Used by Messenger + Mail.
+
+import { useCallback } from "react";
+import { useAppShell } from "@abe-kap/appshell-sdk/react";
+
+export interface UploadedAttachment { contentRef: string; mimeType: string; sizeBytes: number; filename: string }
+
+export const MAX_ATTACHMENT_BYTES = 26 * 1024 * 1024; // matches IIOS's cap
+
+export function isImage(mime?: string | null): boolean {
+  return !!mime && mime.startsWith("image/");
+}
+
+/** Upload a File → { contentRef, mimeType, sizeBytes, filename }. Throws on oversize / failure. */
+export function useUploadAttachment() {
+  const { sdk } = useAppShell();
+  return useCallback(async (file: File): Promise<UploadedAttachment> => {
+    if (file.size > MAX_ATTACHMENT_BYTES) throw new Error("File is too large (max 25 MB).");
+    const mime = file.type || "application/octet-stream";
+    const { objectKey, uploadUrl } = (await sdk.command("crm.media.presignUpload", { mime, sizeBytes: file.size })) as { objectKey: string; uploadUrl: string };
+    const res = await fetch(uploadUrl, { method: "PUT", body: file });
+    if (!res.ok) throw new Error(`Upload failed (${res.status}).`);
+    return { contentRef: objectKey, mimeType: mime, sizeBytes: file.size, filename: file.name };
+  }, [sdk]);
+}
+
+/** Mint a short-lived signed URL to display/download an attachment by its contentRef. */
+export function useDownloadUrl() {
+  const { sdk } = useAppShell();
+  return useCallback(async (contentRef: string, mime?: string): Promise<string> => {
+    const { url } = (await sdk.command("crm.media.presignDownload", { contentRef, ...(mime ? { mime } : {}) })) as { url: string };
+    return url;
+  }, [sdk]);
+}

src/lib/messenger-api.ts

@@ -0,0 +1,435 @@
+"use client";
+
+// Messenger data layer. Serves EITHER a local mock (when the Shell isn't configured — the demo
+// keeps working) OR the live be-crm data door (crm.messenger.*), behind one interface so the UI is
+// mode-agnostic. DM-vs-group + who-can-chat are enforced server-side by IIOS/OPA; this is just glue.
+//
+// Live contract (be-crm):
+//   query crm.messenger.directory        { kind, query?, limit } -> DirectoryEntry[]
+//   query crm.messenger.conversation.list {}                     -> ConversationSummary[]
+//   cmd   crm.messenger.conversation.open { participantIds[], membership?, subject? } -> { threadId, ... }
+//   query crm.messenger.history          { threadId }            -> MessengerMessage[]
+//   cmd   crm.messenger.send             { threadId, content }   -> MessengerMessage
+//   cmd   crm.messenger.participant.add  { threadId, userId }
+//
+// v1 uses REST + polling for the live stream; v2 layers the IIOS MessageSocket (messenger-socket.tsx)
+// on top for live messages, typing, read receipts, and reactions.
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useAppShell, useAuth, useQuery } from "@abe-kap/appshell-sdk/react";
+import type { AnnotationEvent, AnnotationGroup } from "@insignia/iios-kernel-client";
+import { isShellConfigured } from "./appshell";
+import { useMessengerSocket } from "./messenger-socket";
+
+export type Membership = "dm" | "group";
+export interface UiPerson { id: string; name: string; kind: "staff" | "customer" }
+export interface UiConversation {
+  threadId: string; title: string; subject: string | null; membership: Membership | null;
+  participants: string[]; unread: number; lastMessage?: string; lastAt?: string;
+}
+export interface UiReaction { emoji: string; count: number; mine: boolean }
+export interface UiAttachment { contentRef: string; mimeType: string; sizeBytes: number }
+export interface UiMessage {
+  id: string; actorId: string | null; senderId?: string | null; text: string; at: string; mine: boolean;
+  parentInteractionId?: string | null;
+  attachment?: UiAttachment;
+  reactions?: UiReaction[];
+}
+
+interface DirectoryDTO { id: string; displayName: string; kind: "staff" | "customer" }
+interface ConversationDTO {
+  threadId: string; subject: string | null; membership: Membership | null;
+  participants: string[]; unread: number; lastMessage?: string; lastAt?: string;
+}
+interface MessageDTO { interactionId: string; actorId: string | null; kind: string; occurredAt: string; text: string | null }
+
+const SHELL = isShellConfigured();
+const POLL_MS = 4000;
+const TYPING_TTL_MS = 3500;
+
+const shortId = (id: string) => id.replace(/^(pp_|cust_)/, "").slice(0, 6);
+
+/** Turn the kernel's generic annotation aggregates into reaction chips. `users` may hold user or
+ *  actor ids depending on the source, so `mine` is best-effort; a fresh annotation event corrects it. */
+export function toReactions(annotations: AnnotationGroup[] | undefined, myId?: string): UiReaction[] {
+  if (!annotations) return [];
+  return annotations
+    .filter((a) => a.type === "reaction" && a.users.length > 0)
+    .map((a) => ({ emoji: a.value, count: a.users.length, mine: !!myId && a.users.includes(myId) }));
+}
+
+function applyAnnotation(prev: UiReaction[] | undefined, e: AnnotationEvent, myId?: string): UiReaction[] {
+  const base = (prev ?? []).filter((r) => r.emoji !== e.value);
+  if (e.type !== "reaction" || e.users.length === 0) return base;
+  return [...base, { emoji: e.value, count: e.users.length, mine: !!myId && e.users.includes(myId) }];
+}
+
+/* ======================================================================== */
+/* Public hooks                                                             */
+/* ======================================================================== */
+
+export interface MessengerData {
+  live: boolean; loading: boolean; error: string | null;
+  directory: UiPerson[];
+  conversations: UiConversation[];
+  nameOf: (id: string) => string;
+  openConversation: (participantIds: string[], opts?: { membership?: Membership; subject?: string }) => Promise<string>;
+  refetch: () => void;
+}
+
+export interface ThreadData {
+  loading: boolean; error: string | null;
+  messages: UiMessage[];
+  send: (content: string, opts?: { parentInteractionId?: string; attachment?: UiAttachment }) => Promise<void>;
+  react: (interactionId: string, emoji: string) => void;
+  typingUserIds: string[];
+  seenIds: Set<string>;
+  refetch: () => void;
+}
+
+export interface UiMember { userId: string; displayName: string; role: string }
+export interface GroupSettingsData {
+  loading: boolean; error: string | null;
+  members: UiMember[];
+  isAdmin: boolean;
+  rename: (subject: string) => Promise<void>;
+  addMember: (userId: string) => Promise<void>;
+  removeMember: (userId: string) => Promise<void>;
+  refetch: () => void;
+}
+
+export function useMessengerData(): MessengerData {
+  return SHELL ? useLiveMessenger() : useMockMessenger();
+}
+export function useThread(threadId: string): ThreadData {
+  return SHELL ? useLiveThread(threadId) : useMockThread(threadId);
+}
+export function useGroupSettings(threadId: string): GroupSettingsData {
+  return SHELL ? useLiveGroupSettings(threadId) : useMockGroupSettings(threadId);
+}
+
+/* ======================================================================== */
+/* Live implementation (be-crm data door + IIOS socket)                     */
+/* ======================================================================== */
+
+function useLiveMessenger(): MessengerData {
+  const { sdk } = useAppShell();
+  const { user } = useAuth();
+  const socket = useMessengerSocket();
+  const myId = user?.id;
+  const dirQ = useQuery<DirectoryDTO[]>("crm.messenger.directory", { kind: "all", limit: 100 });
+  const convQ = useQuery<ConversationDTO[]>("crm.messenger.conversation.list", {});
+
+  const directory: UiPerson[] = useMemo(
+    () => (dirQ.data ?? []).map((d) => ({ id: d.id, name: d.displayName, kind: d.kind })),
+    [dirQ.data],
+  );
+  const nameById = useMemo(() => Object.fromEntries(directory.map((p) => [p.id, p.name])), [directory]);
+  const nameOf = useCallback((id: string) => nameById[id] ?? `User ${shortId(id)}`, [nameById]);
+
+  // Live sidebar previews: patch lastMessage/lastAt the instant a message arrives on any thread,
+  // then reconcile authoritative unread/order with a debounced refetch.
+  const [previews, setPreviews] = useState<Record<string, { lastMessage: string; lastAt: string }>>({});
+  const refetchRef = useRef(convQ.refetch);
+  refetchRef.current = convQ.refetch;
+  useEffect(() => {
+    if (!socket) return;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    const off = socket.onAnyMessage((threadId, m) => {
+      setPreviews((p) => ({ ...p, [threadId]: { lastMessage: m.text, lastAt: m.at } }));
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(() => refetchRef.current(), 600);
+    });
+    return () => { off(); if (timer) clearTimeout(timer); };
+  }, [socket]);
+
+  const conversations: UiConversation[] = useMemo(
+    () => (convQ.data ?? []).map((c) => shape(c, nameOf, myId, previews[c.threadId])),
+    [convQ.data, nameOf, myId, previews],
+  );
+
+  const refetch = useCallback(() => { dirQ.refetch(); convQ.refetch(); }, [dirQ, convQ]);
+  const openConversation = useCallback(async (participantIds: string[], opts?: { membership?: Membership; subject?: string }) => {
+    const res = (await sdk.command("crm.messenger.conversation.open", {
+      participantIds, ...(opts?.membership ? { membership: opts.membership } : {}), ...(opts?.subject ? { subject: opts.subject } : {}),
+    })) as { threadId: string };
+    convQ.refetch();
+    return res.threadId;
+  }, [sdk, convQ]);
+
+  return {
+    live: true,
+    loading: dirQ.loading || convQ.loading,
+    error: (dirQ.error ?? convQ.error)?.message ?? null,
+    directory, conversations, nameOf, openConversation, refetch,
+  };
+}
+
+function useLiveThread(threadId: string): ThreadData {
+  const { sdk } = useAppShell();
+  const socket = useMessengerSocket();
+  const socketReady = socket?.ready ?? false;
+  const q = useQuery<MessageDTO[]>("crm.messenger.history", { threadId });
+  const [socketMsgs, setSocketMsgs] = useState<UiMessage[]>([]);
+  const [myActorId, setMyActorId] = useState<string | null>(null);
+  const myActorIdRef = useRef<string | null>(null);
+  myActorIdRef.current = myActorId;
+  const [typing, setTyping] = useState<Record<string, number>>({}); // userId -> expiry ts
+  const [seenIds, setSeenIds] = useState<Set<string>>(new Set());
+  const myId = socket?.myUserId;
+
+  // REST poll — the fallback whenever the live socket isn't connected.
+  const refetchRef = useRef(q.refetch);
+  refetchRef.current = q.refetch;
+  useEffect(() => {
+    if (socketReady) return;
+    const t = setInterval(() => refetchRef.current(), POLL_MS);
+    return () => clearInterval(t);
+  }, [socketReady, threadId]);
+
+  // Socket (primary): load history + subscribe to live messages, typing, receipts, reactions.
+  useEffect(() => {
+    if (!socket || !socketReady) return;
+    let alive = true;
+    setSocketMsgs([]); setSeenIds(new Set()); setTyping({});
+    void socket.openThread(threadId).then((hist) => { if (alive) setSocketMsgs(hist); }).catch(() => {});
+
+    const offMsg = socket.subscribe(threadId, (m) =>
+      setSocketMsgs((l) => (l.some((x) => x.id === m.id) ? l : [...l, m])),
+    );
+    const offTyping = socket.onTyping(threadId, (userId) =>
+      setTyping((t) => ({ ...t, [userId]: Date.now() + TYPING_TTL_MS })),
+    );
+    // Receipts are a global stream (no threadId). Count only reads by the OTHER side; seenMine then
+    // narrows to my messages in this thread.
+    const offReceipt = socket.onReceipt((e) => {
+      if (e.actorId === myActorIdRef.current) return;
+      setSeenIds((s) => (s.has(e.interactionId) ? s : new Set(s).add(e.interactionId)));
+    });
+    const offAnn = socket.onAnnotation(threadId, (e) =>
+      setSocketMsgs((l) => l.map((m) => (m.id === e.interactionId ? { ...m, reactions: applyAnnotation(m.reactions, e, myId) } : m))),
+    );
+    return () => { alive = false; offMsg(); offTyping(); offReceipt(); offAnn(); };
+  }, [socket, socketReady, threadId, myId]);
+
+  // Learn my own actor id from a message I sent, so receipts from OTHER actors read as "seen".
+  useEffect(() => {
+    const mine = socketMsgs.find((m) => m.mine && m.actorId);
+    if (mine?.actorId && mine.actorId !== myActorId) setMyActorId(mine.actorId);
+  }, [socketMsgs, myActorId]);
+
+  // Tell the server I've read the latest message (drives the other side's "seen" tick).
+  useEffect(() => {
+    if (!socket || !socketReady || socketMsgs.length === 0) return;
+    socket.markRead(threadId, socketMsgs[socketMsgs.length - 1].id);
+  }, [socket, socketReady, threadId, socketMsgs]);
+
+  // Expire stale typing entries.
+  const typingUserIds = useMemo(() => {
+    const now = Date.now();
+    return Object.entries(typing).filter(([, exp]) => exp > now).map(([u]) => u);
+  }, [typing]);
+  useEffect(() => {
+    if (typingUserIds.length === 0) return;
+    const t = setTimeout(() => setTyping((p) => ({ ...p })), TYPING_TTL_MS);
+    return () => clearTimeout(t);
+  }, [typingUserIds.length, typing]);
+
+  const restMsgs: UiMessage[] = useMemo(
+    () => (q.data ?? []).map((m) => ({
+      id: m.interactionId, actorId: m.actorId, senderId: null, text: m.text ?? "", at: m.occurredAt,
+      mine: !!myActorId && m.actorId === myActorId, reactions: [],
+    })),
+    [q.data, myActorId],
+  );
+
+  const messages = socketReady ? socketMsgs : restMsgs;
+
+  // My messages the other side has read (receipts carry the other actor's id).
+  const seenMine = useMemo(() => {
+    const out = new Set<string>();
+    for (const id of seenIds) if (messages.some((m) => m.id === id && m.mine)) out.add(id);
+    return out;
+  }, [seenIds, messages]);
+
+  const send = useCallback(async (content: string, opts?: { parentInteractionId?: string; attachment?: UiAttachment }) => {
+    if (socket && socketReady) {
+      await socket.send(threadId, content, opts); // echoes back over the socket as a 'message' event
+    } else {
+      // REST fallback carries the attachment ref too; a socket reconnect will replace with the live copy.
+      const m = (await sdk.command("crm.messenger.send", { threadId, content, ...(opts?.attachment ? { attachment: opts.attachment } : {}) })) as MessageDTO;
+      if (m.actorId) setMyActorId(m.actorId);
+      q.refetch();
+    }
+  }, [socket, socketReady, threadId, sdk, q]);
+
+  const react = useCallback((interactionId: string, emoji: string) => {
+    if (socket && socketReady) socket.react(threadId, interactionId, emoji);
+  }, [socket, socketReady, threadId]);
+
+  return {
+    loading: q.loading && !socketReady, error: q.error?.message ?? null,
+    messages, send, react, typingUserIds, seenIds: seenMine, refetch: q.refetch,
+  };
+}
+
+function useLiveGroupSettings(threadId: string): GroupSettingsData {
+  const { sdk } = useAppShell();
+  const { user } = useAuth();
+  const q = useQuery<UiMember[]>("crm.messenger.members", { threadId });
+  const members = useMemo(() => q.data ?? [], [q.data]);
+  const isAdmin = useMemo(() => members.some((m) => m.userId === user?.id && m.role === "ADMIN"), [members, user?.id]);
+
+  const rename = useCallback(async (subject: string) => {
+    await sdk.command("crm.messenger.group.rename", { threadId, subject });
+    q.refetch();
+  }, [sdk, threadId, q]);
+  const addMember = useCallback(async (userId: string) => {
+    await sdk.command("crm.messenger.participant.add", { threadId, userId });
+    q.refetch();
+  }, [sdk, threadId, q]);
+  const removeMember = useCallback(async (userId: string) => {
+    await sdk.command("crm.messenger.participant.remove", { threadId, userId });
+    q.refetch();
+  }, [sdk, threadId, q]);
+
+  return { loading: q.loading, error: q.error?.message ?? null, members, isAdmin, rename, addMember, removeMember, refetch: q.refetch };
+}
+
+function shape(
+  c: ConversationDTO,
+  nameOf: (id: string) => string,
+  myId: string | undefined,
+  overlay?: { lastMessage: string; lastAt: string },
+): UiConversation {
+  // A DM's title is the OTHER person — never yourself, and never the raw unknown-id fallback for both.
+  const others = myId ? c.participants.filter((p) => p !== myId) : c.participants;
+  const title = c.subject?.trim()
+    || (c.membership === "group"
+      ? `Group · ${c.participants.length}`
+      : (others.map(nameOf).join(", ") || nameOf(c.participants[0] ?? "") || "Conversation"));
+  const lastMessage = overlay?.lastMessage ?? c.lastMessage;
+  const lastAt = overlay?.lastAt ?? c.lastAt;
+  return {
+    threadId: c.threadId, title, subject: c.subject, membership: c.membership,
+    participants: c.participants, unread: c.unread,
+    ...(lastMessage ? { lastMessage } : {}), ...(lastAt ? { lastAt } : {}),
+  };
+}
+
+/* ======================================================================== */
+/* Mock implementation (no Shell configured — the demo keeps working)       */
+/* ======================================================================== */
+
+const MOCK_PEOPLE: UiPerson[] = [
+  { id: "pp_sofia", name: "Sofia Ramirez", kind: "staff" },
+  { id: "pp_dan", name: "Dan Whitaker", kind: "staff" },
+  { id: "pp_priya", name: "Priya Nair", kind: "staff" },
+  { id: "cust_acme", name: "Acme Roofing (Client)", kind: "customer" },
+  { id: "cust_globex", name: "Globex Homes (Client)", kind: "customer" },
+];
+
+interface MockThread { threadId: string; membership: Membership; subject: string | null; participants: string[]; messages: UiMessage[] }
+const now = () => new Date().toISOString();
+let MOCK_SEQ = 100;
+
+// A tiny module-level store both mock hooks share, with a subscribe-on-change so the
+// conversation list and the open thread stay in sync (no globalThis, no render writes).
+const MOCK_STORE = new Map<string, MockThread>([
+  ["th_mock_1", { threadId: "th_mock_1", membership: "dm", subject: null, participants: ["me", "pp_sofia"],
+    messages: [{ id: "m1", actorId: "pp_sofia", text: "Can you review the Henderson estimate?", at: now(), mine: false, reactions: [] }] }],
+  ["th_mock_2", { threadId: "th_mock_2", membership: "group", subject: "Storm response — East side", participants: ["me", "pp_dan", "pp_priya"],
+    messages: [{ id: "m2", actorId: "pp_dan", text: "Crew is rolling out at 7.", at: now(), mine: false, reactions: [] }] }],
+]);
+const mockListeners = new Set<() => void>();
+const notifyMock = () => mockListeners.forEach((l) => l());
+function useMockSubscription(): void {
+  const [, setV] = useState(0);
+  useEffect(() => {
+    const l = () => setV((n) => n + 1);
+    mockListeners.add(l);
+    return () => { mockListeners.delete(l); };
+  }, []);
+}
+
+function useMockMessenger(): MessengerData {
+  useMockSubscription();
+  const nameById = useMemo(() => Object.fromEntries(MOCK_PEOPLE.map((p) => [p.id, p.name])), []);
+  const nameOf = useCallback((id: string) => nameById[id] ?? `User ${shortId(id)}`, [nameById]);
+
+  const conversations: UiConversation[] = [...MOCK_STORE.values()].map((t) => {
+    const last = t.messages[t.messages.length - 1];
+    return {
+      threadId: t.threadId,
+      title: t.subject || t.participants.filter((p) => p !== "me").map(nameOf).join(", ") || "Conversation",
+      subject: t.subject, membership: t.membership, participants: t.participants, unread: 0,
+      ...(last ? { lastMessage: last.text, lastAt: last.at } : {}),
+    };
+  });
+
+  const openConversation = useCallback(async (participantIds: string[], opts?: { membership?: Membership; subject?: string }) => {
+    const membership = opts?.membership ?? (participantIds.length === 1 ? "dm" : "group");
+    const threadId = `th_mock_${MOCK_SEQ++}`;
+    MOCK_STORE.set(threadId, { threadId, membership, subject: opts?.subject ?? null, participants: ["me", ...participantIds], messages: [] });
+    notifyMock();
+    return threadId;
+  }, []);
+
+  return { live: false, loading: false, error: null, directory: MOCK_PEOPLE, conversations, nameOf, openConversation, refetch: () => {} };
+}
+
+function useMockThread(threadId: string): ThreadData {
+  useMockSubscription();
+  const thread = MOCK_STORE.get(threadId);
+  const send = useCallback(async (content: string, opts?: { parentInteractionId?: string }) => {
+    const t = MOCK_STORE.get(threadId);
+    if (t) {
+      t.messages = [...t.messages, {
+        id: `m_${MOCK_SEQ++}`, actorId: "me", text: content, at: now(), mine: true, reactions: [],
+        ...(opts?.parentInteractionId ? { parentInteractionId: opts.parentInteractionId } : {}),
+      }];
+      notifyMock();
+    }
+  }, [threadId]);
+  const react = useCallback((interactionId: string, emoji: string) => {
+    const t = MOCK_STORE.get(threadId);
+    if (!t) return;
+    t.messages = t.messages.map((m) => {
+      if (m.id !== interactionId) return m;
+      const has = (m.reactions ?? []).find((r) => r.emoji === emoji);
+      const reactions = has
+        ? (m.reactions ?? []).filter((r) => r.emoji !== emoji)
+        : [...(m.reactions ?? []), { emoji, count: 1, mine: true }];
+      return { ...m, reactions };
+    });
+    notifyMock();
+  }, [threadId]);
+  return {
+    loading: false, error: null, messages: thread?.messages ?? [], send, react,
+    typingUserIds: [], seenIds: new Set(), refetch: notifyMock,
+  };
+}
+
+function useMockGroupSettings(threadId: string): GroupSettingsData {
+  useMockSubscription();
+  const nameById = useMemo(() => Object.fromEntries(MOCK_PEOPLE.map((p) => [p.id, p.name])), []);
+  const t = MOCK_STORE.get(threadId);
+  const members: UiMember[] = (t?.participants ?? []).map((id) => ({
+    userId: id,
+    displayName: id === "me" ? "You" : (nameById[id] ?? `User ${shortId(id)}`),
+    role: id === "me" ? "ADMIN" : "MEMBER",
+  }));
+  const rename = useCallback(async (subject: string) => {
+    const th = MOCK_STORE.get(threadId);
+    if (th) { th.subject = subject; notifyMock(); }
+  }, [threadId]);
+  const addMember = useCallback(async (userId: string) => {
+    const th = MOCK_STORE.get(threadId);
+    if (th && !th.participants.includes(userId)) { th.participants = [...th.participants, userId]; notifyMock(); }
+  }, [threadId]);
+  const removeMember = useCallback(async (userId: string) => {
+    const th = MOCK_STORE.get(threadId);
+    if (th) { th.participants = th.participants.filter((p) => p !== userId); notifyMock(); }
+  }, [threadId]);
+  return { loading: false, error: null, members, isAdmin: true, rename, addMember, removeMember, refetch: notifyMock };
+}

src/lib/messenger-socket.tsx

@@ -0,0 +1,149 @@
+"use client";
+
+// v2 live stream: one IIOS MessageSocket for the whole Messenger panel, using the SDK
+// (@insignia/iios-kernel-client) — not raw socket.io. The delegated realtime token comes from
+// the be-crm data door (crm.messenger.realtime). Threads subscribe through a context; the socket
+// re-opens every joined thread on reconnect (handled inside the SDK). In mock mode this is a no-op
+// passthrough and the thread hook falls back to the REST poll.
+//
+// Beyond plain messages, the kernel exposes typing, read receipts, and reactions (generic
+// annotations). This provider fans each server event out to per-thread listeners so the UI can
+// render typing indicators, "seen" ticks, and emoji reactions live.
+
+import { createContext, useCallback, useContext, useEffect, useRef, useState, type ReactNode } from "react";
+import { MessageSocket, type Message, type AnnotationEvent } from "@insignia/iios-kernel-client";
+import { useAuth, useQuery } from "@abe-kap/appshell-sdk/react";
+import { isShellConfigured } from "./appshell";
+import { toReactions, type UiMessage } from "./messenger-api";
+
+interface RealtimeDTO { url: string; audience: string; token?: string }
+
+export interface ReceiptHit { interactionId: string; actorId: string }
+
+export interface MessengerSocket {
+  ready: boolean;
+  myUserId?: string;
+  openThread: (threadId: string) => Promise<UiMessage[]>;
+  send: (threadId: string, content: string, opts?: { parentInteractionId?: string; attachment?: { contentRef: string; mimeType: string; sizeBytes: number } }) => Promise<void>;
+  subscribe: (threadId: string, cb: (m: UiMessage) => void) => () => void;
+  /** Fires for EVERY inbound message regardless of thread — drives live sidebar previews. */
+  onAnyMessage: (cb: (threadId: string, m: UiMessage) => void) => () => void;
+  sendTyping: (threadId: string) => void;
+  onTyping: (threadId: string, cb: (userId: string) => void) => () => void;
+  markRead: (threadId: string, interactionId: string) => void;
+  /** The kernel's receipt event carries no threadId, so this is a global stream; the thread hook
+   *  filters to receipts for its own (mine) messages. */
+  onReceipt: (cb: (e: ReceiptHit) => void) => () => void;
+  react: (threadId: string, interactionId: string, emoji: string) => void;
+  onAnnotation: (threadId: string, cb: (e: AnnotationEvent) => void) => () => void;
+}
+
+const Ctx = createContext<MessengerSocket | null>(null);
+export function useMessengerSocket(): MessengerSocket | null { return useContext(Ctx); }
+
+const SHELL = isShellConfigured();
+
+const toUi = (m: Message, myUserId?: string): UiMessage => ({
+  id: m.id, actorId: m.senderActorId ?? null, senderId: m.senderId ?? null, text: m.content ?? "", at: m.createdAt,
+  mine: !!myUserId && m.senderId === myUserId,
+  ...(m.parentInteractionId ? { parentInteractionId: m.parentInteractionId } : {}),
+  ...(m.attachment ? { attachment: { contentRef: m.attachment.contentRef, mimeType: m.attachment.mimeType, sizeBytes: m.attachment.sizeBytes } } : {}),
+  reactions: toReactions(m.annotations, myUserId),
+});
+
+export function MessengerSocketProvider({ children }: { children: ReactNode }) {
+  // SHELL is a build-time constant, so the branch is stable across renders (Rules-of-Hooks safe).
+  if (!SHELL) return <>{children}</>;
+  return <LiveSocketProvider>{children}</LiveSocketProvider>;
+}
+
+// A tiny per-thread listener registry, reused for messages / typing / receipts / annotations.
+function makeRegistry<T>() {
+  const map = new Map<string, Set<(v: T) => void>>();
+  const add = (key: string, cb: (v: T) => void) => {
+    if (!map.has(key)) map.set(key, new Set());
+    map.get(key)!.add(cb);
+    return () => { map.get(key)?.delete(cb); };
+  };
+  const emit = (key: string, v: T) => map.get(key)?.forEach((cb) => cb(v));
+  return { add, emit };
+}
+
+function LiveSocketProvider({ children }: { children: ReactNode }) {
+  const { user } = useAuth();
+  const rt = useQuery<RealtimeDTO>("crm.messenger.realtime", {});
+  const [ready, setReady] = useState(false);
+  const socketRef = useRef<MessageSocket | null>(null);
+  const myRef = useRef<string | undefined>(user?.id);
+  myRef.current = user?.id;
+
+  // One registry per event kind, keyed by threadId (plus a global message fan-out).
+  const msgReg = useRef(makeRegistry<UiMessage>()).current;
+  const anyMsg = useRef(new Set<(threadId: string, m: UiMessage) => void>()).current;
+  const typingReg = useRef(makeRegistry<string>()).current;
+  const receiptSet = useRef(new Set<(e: ReceiptHit) => void>()).current;
+  const annReg = useRef(makeRegistry<AnnotationEvent>()).current;
+
+  const url = rt.data?.url;
+  const token = rt.data?.token;
+
+  useEffect(() => {
+    if (!url || !token) return;
+    const socket = new MessageSocket({ serviceUrl: url, token, autoConnect: false });
+    socketRef.current = socket;
+    const offConnected = socket.onConnected(() => setReady(true));
+    const offMessage = socket.on("message", (m) => {
+      const ui = toUi(m, myRef.current);
+      msgReg.emit(m.threadId, ui);
+      anyMsg.forEach((cb) => cb(m.threadId, ui));
+    });
+    const offTyping = socket.on("typing", (e) => { if (e.userId !== myRef.current) typingReg.emit(e.threadId, e.userId); });
+    const offReceipt = socket.on("receipt", (e) => receiptSet.forEach((cb) => cb({ interactionId: e.interactionId, actorId: e.actorId })));
+    const offAnn = socket.on("annotation", (e) => annReg.emit(e.threadId, e));
+    socket.connect();
+    return () => {
+      offConnected(); offMessage(); offTyping(); offReceipt(); offAnn();
+      socket.disconnect(); socketRef.current = null; setReady(false);
+    };
+  }, [url, token, msgReg, anyMsg, typingReg, receiptSet, annReg]);
+
+  const openThread = useCallback(async (threadId: string): Promise<UiMessage[]> => {
+    const s = socketRef.current;
+    if (!s) return [];
+    const res = await s.openThread(threadId);
+    return res.history.map((m) => toUi(m, myRef.current));
+  }, []);
+
+  const send = useCallback(async (threadId: string, content: string, opts?: { parentInteractionId?: string; attachment?: { contentRef: string; mimeType: string; sizeBytes: number } }) => {
+    const s = socketRef.current;
+    if (!s) throw new Error("Not connected");
+    const sendOpts = {
+      ...(opts?.parentInteractionId ? { parentInteractionId: opts.parentInteractionId } : {}),
+      ...(opts?.attachment ? { attachment: opts.attachment } : {}),
+    };
+    await s.sendMessage(threadId, content, Object.keys(sendOpts).length ? sendOpts : undefined);
+  }, []);
+
+  const subscribe = useCallback((threadId: string, cb: (m: UiMessage) => void) => msgReg.add(threadId, cb), [msgReg]);
+  const onAnyMessage = useCallback((cb: (threadId: string, m: UiMessage) => void) => {
+    anyMsg.add(cb); return () => { anyMsg.delete(cb); };
+  }, [anyMsg]);
+  const onTyping = useCallback((threadId: string, cb: (userId: string) => void) => typingReg.add(threadId, cb), [typingReg]);
+  const onReceipt = useCallback((cb: (e: ReceiptHit) => void) => {
+    receiptSet.add(cb); return () => { receiptSet.delete(cb); };
+  }, [receiptSet]);
+  const onAnnotation = useCallback((threadId: string, cb: (e: AnnotationEvent) => void) => annReg.add(threadId, cb), [annReg]);
+
+  const sendTyping = useCallback((threadId: string) => socketRef.current?.typing(threadId), []);
+  const markRead = useCallback((threadId: string, interactionId: string) => { void socketRef.current?.markRead(threadId, interactionId); }, []);
+  const react = useCallback((threadId: string, interactionId: string, emoji: string) => { void socketRef.current?.react(threadId, interactionId, emoji); }, []);
+
+  return (
+    <Ctx.Provider value={{
+      ready, myUserId: user?.id, openThread, send, subscribe, onAnyMessage,
+      sendTyping, onTyping, markRead, onReceipt, react, onAnnotation,
+    }}>
+      {children}
+    </Ctx.Provider>
+  );
+}

src/lib/otp.ts

@@ -0,0 +1,16 @@
+/**
+ * Demo OTP fallback, shared by the login and registration flows.
+ *
+ * While the Twilio SMS sender is down we can't deliver real one-time codes. When
+ * MOCK_OTP is on, phone verification steps skip Supabase/Twilio and accept a fixed
+ * DEMO_OTP instead. Flip NEXT_PUBLIC_MOCK_OTP to "false" (or remove it) to restore
+ * real SMS — no other change needed.
+ *
+ * IMPORTANT: this only substitutes for a *secondary* verification (e.g. confirming a
+ * phone during registration/onboarding, where the session already exists). It cannot
+ * mock a *login* whose sole credential is the OTP — there the OTP verification is what
+ * mints the session, and a faked code produces no session (the dashboard's AuthGate
+ * would bounce the user straight back). Passwordless login therefore stays real.
+ */
+export const MOCK_OTP = process.env.NEXT_PUBLIC_MOCK_OTP === "true";
+export const DEMO_OTP = "123456";

src/lib/team-api.ts

@@ -38,6 +38,8 @@ export interface UiMember {
 }
 export interface UiInvite {
   id: string; email: string; roleIds: string[]; invitedBy: string; sentAt: string;
+  /** Accept token for the invite link (pending invites only; no email delivery yet). */
+  token?: string;
 }
 
 export interface TeamData {
@@ -46,7 +48,9 @@ export interface TeamData {
   setMemberRoles: (id: string, roleIds: string[]) => Promise<void>;
   updateMember: (id: string, patch: { title?: string; roleIds?: string[] }) => Promise<void>;
   removeMember: (id: string) => Promise<void>;
+  /** Create an invite. be-crm emails the invitee automatically. */
   invite: (email: string, roleIds: string[]) => Promise<void>;
+  /** Resend an invite (regenerates the token + re-emails it). */
   resendInvite: (id: string) => Promise<void>;
   revokeInvite: (id: string) => Promise<void>;
   setPermission: (roleId: string, permId: string, granted: boolean) => Promise<void>;
@@ -68,9 +72,9 @@ const initialsOf = (name: string) =>
 /* ---- be-crm DTO types (subset used here) -------------------------------- */
 
 interface RoleRef { id: string; slug: string; name: string; color: string | null; isSystem: boolean; isOwnerRole: boolean }
-interface MemberDTO { id: string; principalId: string; jobTitle: string | null; joinedAt: string; status: "active" | "deactivated"; roles: RoleRef[]; openDeals: number }
+interface MemberDTO { id: string; principalId: string; jobTitle: string | null; joinedAt: string; status: "active" | "deactivated"; roles: RoleRef[]; openDeals: number; email?: string | null; firstName?: string | null; lastName?: string | null; displayName?: string | null }
 interface RoleDTO { id: string; slug: string; name: string; description: string | null; color: string | null; isSystem: boolean; isOwnerRole: boolean; permissions: string[]; memberCount: number }
-interface InvitationDTO { id: string; email: string; roles: RoleRef[]; invitedBy: string; createdAt: string }
+interface InvitationDTO { id: string; email: string; roles: RoleRef[]; invitedBy: string; createdAt: string; token?: string }
 
 const relTime = (iso: string): string => {
   const then = Date.parse(iso);
@@ -153,12 +157,16 @@ function useLiveTeam(): TeamData {
 
   const members: UiMember[] = useMemo(() => (membersQ.data?.items ?? []).map((m) => {
     const isYou = !!meId && m.principalId === meId;
-    const name = isYou && user?.displayName
-      ? user.displayName
-      : (m.jobTitle?.trim() || `Member ${m.principalId.replace(/^pp_/, "").slice(0, 6)}`);
+    // Prefer the member's real name/email from their CRM registration; fall back to the
+    // ACE (for the current user), then job title, then a short principal id.
+    const name = m.displayName?.trim()
+      || (isYou && user?.displayName)
+      || m.jobTitle?.trim()
+      || `Member ${m.principalId.replace(/^pp_/, "").slice(0, 6)}`;
+    const email = m.email || (isYou ? user?.email : undefined) || "";
     return {
       id: m.id, principalId: m.principalId, name, initials: initialsOf(name),
-      email: isYou && user?.email ? user.email : m.principalId,
+      email,
       title: m.jobTitle ?? "", roleIds: m.roles.map((r) => r.id), gradient: gradientFor(m.id),
       status: (m.status === "active" ? "active" : "offline") as UiStatus,
       lastActive: m.status === "active" ? "Active" : "—",
@@ -169,7 +177,7 @@ function useLiveTeam(): TeamData {
 
   const invites: UiInvite[] = useMemo(() => (invitesQ.data?.items ?? []).map((i) => ({
     id: i.id, email: i.email, roleIds: i.roles.map((r) => r.id),
-    invitedBy: i.invitedBy, sentAt: relTime(i.createdAt),
+    invitedBy: i.invitedBy, sentAt: relTime(i.createdAt), token: i.token,
   })), [invitesQ.data]);
 
   return {