docs: update USER_FLOWS.md for marketplace + lead response flows

- Flow 11: note CTA token in forward email + matching notification tasks
- Flow 12 (new): supplier lead_respond endpoint + one-click CTA token flow
- Flow 13 (was 12): add Marketplace admin dashboard row, update Leads row
  with search/filter/HTMX inline actions, note HTMX partials

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/USER_FLOWS.md

@@ -169,23 +169,40 @@ Same as Flow 2 but arrives at `/<lang>/leads/quote` directly (no planner state).
 |------|-----|-------|
 | 1 | View teased lead | `GET /<lang>/suppliers/dashboard/leads` — lead shown with blurred contact info |
 | 2 | Unlock | `POST /<lang>/suppliers/leads/<id>/unlock` — deducts 1 credit, reveals full lead |
-| 3 | Receive email | `send_lead_forward_email` task enqueued — full project brief sent to supplier |
+| 3 | Receive email | `send_lead_forward_email` task enqueued — full project brief sent to supplier with one-click CTA link |
 | 4 | Entrepreneur notified | `send_lead_matched_notification` task — notifies entrepreneur a supplier was matched |
 
 **Auth required:** Yes — `@_lead_tier_required`
 **Credit check:** Server-side check; if 0 credits → redirect to boosts tab
+**Matching notification:** On quote verification, `notify_matching_suppliers` task auto-notifies growth/pro suppliers whose `service_area` matches the lead's country (max 20 per lead); `send_weekly_lead_digest` sends a Monday 08:00 UTC summary of new matching leads to all paid suppliers
 
 ---
 
-## 12. Admin Flows
+## 12. Supplier → Update Lead Response Status
+
+**Entry:** Supplier dashboard leads tab, or one-click CTA link in forward email
+
+| Step | URL | Notes |
+|------|-----|-------|
+| 1a | Click "Mark as contacted" in email | `GET /suppliers/leads/cta/<cta_token>` — one-click; advances status `sent` → `contacted`; redirects to `/suppliers/dashboard?tab=leads` |
+| 1b | Update via dashboard | `POST /<lang>/suppliers/leads/<token>/respond` — HTMX; sets `status` and optional `supplier_note`; returns 204 |
+
+**Auth required:** CTA link is unauthenticated (token is the credential); dashboard endpoint requires `@_lead_tier_required`
+**Valid statuses:** `sent / viewed / contacted / quoted / won / lost / no_response`
+**Idempotency:** CTA only advances `sent → contacted`; subsequent clicks are no-ops
+
+---
+
+## 13. Admin Flows
 
 **Entry:** `/admin/` (requires `@role_required("admin")`)
 
 | Area | URL | What you can do |
 |------|-----|-----------------|
 | Dashboard | `GET /admin/` | Stats overview |
+| Marketplace | `GET /admin/marketplace` | Lead funnel, credit economy, supplier engagement, live activity stream, inline feature flag toggles |
 | Users | `GET /admin/users`, `/admin/users/<id>` | List, view, impersonate |
-| Leads | `GET /admin/leads`, `/admin/leads/<id>` | List, filter, view detail, change status, forward to supplier, create |
+| Leads | `GET /admin/leads`, `/admin/leads/<id>` | List (search + period filter + summary cards), view detail, HTMX inline status change + forward to supplier |
 | Suppliers | `GET /admin/suppliers`, `/admin/suppliers/<id>` | List, view, adjust credits, change tier, create |
 | Feedback | `GET /admin/feedback` | View all submitted feedback |
 | Email Sent Log | `GET /admin/emails`, `/admin/emails/<id>` | List all outgoing emails (filter by type/event/search), detail with API-enriched HTML preview |
@@ -197,6 +214,7 @@ Same as Flow 2 but arrives at `/<lang>/leads/quote` directly (no planner state).
 | Articles | `GET /admin/articles` | CRUD, publish/unpublish, rebuild HTML |
 | Task Queue | `GET /admin/tasks` | View worker tasks, retry/delete failed |
 
+**HTMX partials:** `lead_status_badge.html` (status change), `lead_forward_history.html` (forward history), `marketplace_activity.html` (activity stream)
 **Dev shortcut:** `/auth/dev-login?email=<admin-email>` where email is in `config.ADMIN_EMAILS`
 
 ---