diff --git a/.planning/DESIGN-SYSTEM.md b/.planning/DESIGN-SYSTEM.md
deleted file mode 100644
index f7f49c3..0000000
--- a/.planning/DESIGN-SYSTEM.md
+++ /dev/null
@@ -1,58 +0,0 @@
-# Design System — Offer Studio UI direction (v2.1)
-
-**Definito:** 2026-06-13 (via skill `ui-ux-pro-max`)
-**Scope:** Applies to Phase 11 (Catalog DB-view), 12 (Offer composition/DnD), 13 (Servizi Attivi), 14 (CRM Attio-style) — any "database view" table in `/admin/*`.
-
-## Direzione
-
-ClickUp / Pipedrive: dense ma leggibile, flat, zero decorazione. **Pattern:** Minimalism & Swiss Style + Flat Design — grid-based, alto contrasto, hover/transition rapidi (150-250ms), nessuna ombra/gradiente pesante.
-
-## Brand tokens — INVARIATI (da `src/app/globals.css`)
-
-Non introdurre una nuova palette: ClickUp/Pipedrive è una direzione di LAYOUT/interazione, non di colore. Il brand iamcavalli resta:
-
-| Token | Valore | Uso |
-|---|---|---|
-| `--color-primary` | `#1A463C` (verde scuro) | azioni primarie, focus ring, link attivi |
-| `--color-accent` | `#DEF168` (lime) | highlight/badge di stato attivo, CTA secondarie |
-| `--color-background` | `#ffffff` | sfondo pagina/tabella |
-| `--color-muted` / `--color-bg-subtle` | `#f9f9f9` | righe alternate, header tabella, quick-add row |
-| `--color-border` | `#e5e7eb` | bordi cella sottili (1px), MAI ombre pesanti |
-| `--color-foreground` | `#1a1a1a` | testo primario |
-| `--color-muted-foreground` | `#71717a` | placeholder, metadati, celle vuote |
-| Font | Geist Sans (già configurato) | nessun cambio — coerente con "Minimal Swiss" |
-
-## Pattern tabella database-view (Phase 11-13)
-
-- **Riga**: altezza compatta (~40px), padding orizzontale `px-3`, bordo inferiore `border-border` 1px — NO bordi verticali tra celle (look ClickUp, non Excel)
-- **Inline edit**: click su cella → diventa `<input>`/`<select>` borderless con `ring-1 ring-primary` on focus → Enter salva, Esc annulla, blur salva. Nessun modal, nessun reload.
-- **Tag multi-select**: `Badge` (già in `components/ui/badge.tsx`) con colori derivati da una palette fissa a rotazione (6-8 colori pastello su sfondo, testo scuro per contrasto AA) + pulsante "+" inline per creare un nuovo tag senza uscire dalla riga
-- **Quick-add row**: ultima riga della tabella, sempre visibile, placeholder "+ Aggiungi servizio" — stile identico alle righe dati ma `text-muted-foreground`, diventa riga normale dopo il primo salvataggio
-- **Filtri/ricerca**: barra sopra la tabella, input singolo con icona search (Lucide), filtro client-side istantaneo su nome/tag — NO bottone "Cerca", NO reload
-- **Header tabella**: sticky, `bg-muted`, font-weight 600, NO maiuscolo decorativo eccessivo (small-caps ok, ALL-CAPS pesante no)
-- **Hover riga**: `bg-muted/50`, transizione `transition-colors duration-150`, cursore pointer solo su celle editabili
-
-## Componenti shadcn da riusare/estendere
-
-Già presenti: `table`, `badge`, `dialog`, `select`, `input`, `button`, `form`. Per Phase 11 servirà probabilmente:
-- Un componente `EditableCell` (input/select inline, non in shadcn — da costruire ad-hoc su `input.tsx`)
-- Un `TagMultiSelect` (combobox + badge, da costruire su `select.tsx`/`badge.tsx` — shadcn `command`/`popover` non ancora installati, valutare in planning)
-
-## Anti-pattern da evitare
-
-- Ombre pesanti, glassmorphism, gradienti decorativi
-- Icone emoji (usare SVG Lucide, coerente col resto dell'app)
-- Tabelle senza filtro/ricerca
-- Azioni riga-per-riga quando serve bulk (Phase 12+: valutare checkbox + action bar per operazioni multiple)
-- Hover che causa layout shift (no scale transform su righe tabella)
-
-## Checklist pre-delivery (per ogni componente nuovo)
-
-- [ ] Contrasto testo ≥ 4.5:1 (light mode — testo muted minimo `#475569`/`text-muted-foreground` attuale è `#71717a`, verificare su `bg-muted`)
-- [ ] `cursor-pointer` su celle/righe editabili e cliccabili
-- [ ] Focus ring visibile (`ring-1 ring-primary` o `--color-ring`) su input inline e bottoni
-- [ ] Transizioni 150-250ms, `transform`/`opacity` non `width`/`height`
-- [ ] Responsive: tabella in `overflow-x-auto` wrapper sotto 1024px, niente layout rotto
-
----
-*Riferimento per CONTEXT.md (Phase 11) e per eventuale `/gsd-ui-phase` su fasi 11-14.*
diff --git a/.planning/HANDOFF.md b/.planning/HANDOFF.md
deleted file mode 100644
index 84d9d1d..0000000
--- a/.planning/HANDOFF.md
+++ /dev/null
@@ -1,57 +0,0 @@
-# Handoff
-
-Living document — update at the end of each session so the next one can resume without re-deriving context. Overwrite stale sections; keep it short and actionable.
-
----
-
-## 2026-06-13 — Milestone v2.1 "Offer Studio + Proposal AI" pianificata — pronta per esecuzione
-
-### Cosa è stato fatto
-
-Eseguito ciclo completo `/gsd-new-milestone "Offer Studio + Proposal AI"` (research saltata su scelta utente):
-
-- **PROJECT.md**: nuovo milestone v2.1 con goal, 4 target feature, sezione "Validated" aggiornata con v2.0 (Phase 7-10), "Active" riscritta in 4 categorie prioritizzate, nuove Key Decisions (compartimenti stagni confermato, ordine Offer Studio→Proposal AI, tab Preventivo→Servizi Attivi zero-perdita verificata)
-- **v2.0 archiviata** (copie, non spostamenti): `REQUIREMENTS.md`/`ROADMAP.md`/phases 07-10 → `.planning/milestones/v2.0-*`
-- **REQUIREMENTS.md** riscritto: 23 requisiti v1 in 5 categorie (Offer Studio, Workspace Servizi Attivi, CRM Attio, Dashboard [bloccata], Proposal AI) + deferred v2 (OFFER-14, AUTH-OTP-01, ARCH-01) + out of scope
-- **ROADMAP.md** creato: 7 nuove fasi (11-17), copertura 100% (23/23 requisiti mappati), tutte approvate dall'utente
-- **STATE.md**: switch a v2.1, focus = Phase 11
-
-### Roadmap v2.1 (Phase 11-17)
-
-| Fase | Titolo | Requisiti | Note |
-| --- | --- | --- | --- |
-| 11 | Catalog Database-View UX & Legacy Consolidation | OFFER-07,08,09,10,13 | unifica `service_catalog`/`offer_services` → `services` PRIMA della nuova UX |
-| 12 | Offer Composition Drag&Drop & CSV Import | OFFER-11,12 | `@dnd-kit`, totale live durante drag, import CSV one-shot |
-| 13 | Workspace — Servizi Attivi | PROJ-06..10 | rimuove tab Preventivo (zero perdita, `accepted_total` resta via Payments) e Forecast; nuova tab Servizi Attivi (one-shot/ricorrenti + tracking incassi mensili) |
-| 14 | CRM Attio-style & Fix | CRM-08..12 | inline edit lead + tag, fix FollowUpWidget IT / LeadForm types / SendQuoteModal |
-| 15 | Dashboard Revenue Stats | DASH-11 | **BLOCCATA** — attesa mockup utente, isolata/skippabile, non blocca 16/17 |
-| 16 | Proposal AI — Data Foundations & Auto-Provisioning | PROP-03,04 | campo Stripe Payment Link + auto-provisioning su accettazione (ex-Phase 11) |
-| 17 | Proposal AI — Builder, Pagina Pubblica & Email | PROP-01,02,05 | AI builder + redesign `/quote/[token]` + invio email Resend (ex-Phase 12) |
-
-### Nota trasparenza — deviazione dal workflow
-
-Il workflow `/gsd-new-milestone` prevede uno step "phases clear" che farebbe `rm -rf` di `.planning/phases/01-10/` senza backup. **Non l'ho eseguito**: è distruttivo, senza archiviazione automatica, e CLAUDE.md richiede conferma prima di operazioni distruttive/di investigare prima di rimuovere lavoro storico. Le fasi 07-10 sono state invece COPIATE (non spostate) in `.planning/milestones/v2.0-phases/`; le directory originali `01-10` restano in `.planning/phases/`. Nessuna perdita — solo directory duplicate, pulizia facoltativa in futuro.
-
-### Prossima sessione
-
-1. **Pianificare Phase 11** (Catalog Database-View UX & Legacy Consolidation): `/gsd-plan-phase 11` (oppure `/gsd-discuss-phase 11` prima per decisioni aperte: schema tag, formato CSV import, strategia consolidamento `service_catalog`/`offer_services`)
-2. Se arriva il **mockup dashboard** dall'utente: Phase 15 (DASH-11) può essere sbloccata, usare `/gsd-ui-phase` come contratto UI
-3. Migration Phase 11 (consolidamento catalogo) e Phase 13/16 (nuovi campi recurring/payment link) vanno applicate a prod via SSH+docker exec PRIMA del push del codice dipendente (regola storica, vedi sotto)
-
----
-
-## 2026-06-12 — Direzione "Offer Studio" + "Proposal AI" → ora pianificata (vedi sopra)
-
-- **BUG fixato e deployato**: `/admin/leads/[id]` 500 per `params` non awaited (Next.js 16) → fix commit `ea20685`, confermato live in prod (container `857af5c1...`).
-- Decisioni strutturali (Preventivo→Servizi Attivi, Forecast→Dashboard, CRM Attio-style, compartimenti stagni) sono ora formalizzate in PROJECT.md/REQUIREMENTS.md/ROADMAP.md — vedi sezione 2026-06-13 sopra.
-
----
-
-## 2026-06-11 (sera) — Phase 10 redo COMPLETATO, root cause risolta (storico)
-
-- **Root cause del crash post-deploy Phase 10**: il DB prod non aveva NESSUNA migration dopo la 0000 (mancavano `services`, `leads`, `offer_phases`, `quotes`…). Catalogo e quote già rotti prima di Phase 10; il deploy Phase 10 ha aggiunto il crash dashboard (FollowUpWidget→leads). NON era un problema di piattaforma (l'app è Gitea→Coolify, non Vercel).
-- **Fix**: migrations 0001+0003+0004+0005 applicate atomicamente al DB prod via `ssh root@178.104.27.55` → `docker exec -i xwkk0040w0kk0gsgcgog8owk psql` (porta 54321 firewallata dall'esterno, si passa da SSH). Dati protetti verificati intatti (4 clients / 5 projects / 13 payments / 6 phases).
-- **Redo Phase 10 deployato**: commit `5aa6614` (deps+UI primitives) e `008a434` (modulo CRM completo). Utente conferma pagine visibili in prod.
-- **REGOLA**: le migration qui sono manuali — applicare al DB prod PRIMA di pushare codice che usa il nuovo schema. Pattern: `cat migration.sql | ssh root@178.104.27.55 "docker exec -i xwkk0040w0kk0gsgcgog8owk sh -c 'psql -U \$POSTGRES_USER -d clienthub -v ON_ERROR_STOP=1 --single-transaction'"` (verificare prima che sia additive-only).
-- Branch `phase10-wip` (= `8e2752a`) cancellabile quando il redo è considerato definitivo. Dangling ancora recuperabile: `5d75752` (sidebar App shortcuts).
-- Script riusabile: `scripts/push-phase10-migration.ts` (solo dal server o con tunnel).
diff --git a/.planning/MILESTONES.md b/.planning/MILESTONES.md
index 849d63c..bb7c61e 100644
--- a/.planning/MILESTONES.md
+++ b/.planning/MILESTONES.md
@@ -1,5 +1,40 @@
 # Milestones
 
+## v2.4 Post-vendita (Phases 13 + 26, in corso)
+
+**Consegnato:** 2 fasi, entrambe in produzione e verificate.
+
+**Key accomplishments:**
+
+- Ciclo di vita dei servizi ricorrenti (Phase 13, prod 2026-08-01): `project_offers.status` (attivo/sospeso/cessato) + `end_date` via migr. 0016; il forecast a 12 mesi smette di sommare un retainer fermo; comandi Sospendi/Riattiva/Cessa nella tab Offerte; il cliente vede stato, "attivo dal / fino al" e canone mensile (RET-01..05)
+- Anteprima admin del portale + toggle password sul login (Phase 26, prod 2026-08-08): `?preview=1` con sessione Auth.js valida apre il portale di un cliente in sola lettura, senza passare dal gate OTP (PREV-01/02, AUTH-09)
+
+**Deviazione registrata:** vincolo LOCKED #4 — una route `/client/*` ora legge anche la sessione Auth.js (Phase 26).
+
+**Aperto:** RET-06 (canoni mensili tracciabili), più il backlog ereditato. Vedi `REQUIREMENTS.md`.
+
+Fasi: [13-ciclo-vita-servizi-ricorrenti](phases/13-ciclo-vita-servizi-ricorrenti/13-SUMMARY.md) · [26-anteprima-admin-e-login](phases/26-anteprima-admin-e-login/26-SUMMARY.md)
+
+---
+
+## v2.3 Email & Accesso (Phases 23–25, shipped 2026-07-29)
+
+**Phases completed:** 3 fasi (23–25) · eseguite fuori dal ciclo GSD (nessun PLAN/SUMMARY per fase)
+
+**Key accomplishments:**
+
+- Resend Setup (Phase 23): `resend@6.18.1`, `src/lib/mailer.ts` con Result tipizzato, template OTP in italiano, env configurate su Coolify
+- Schema + Whitelist Admin (Phase 24): migr. 0015 additiva pura applicata a prod — `client_emails`, `otp_codes`, `clients.sessions_valid_from`; sezione "Accessi al portale" in `/admin/clients/[id]` (OTP-01, OTP-08)
+- OTP Gate + Sessione (Phase 25): codice 6 cifre CSPRNG hashato, TTL 15 min, monouso, max 5 tentativi; cookie HMAC per-cliente, 90 giorni; rate limiting e no-enumeration (OTP-02..07)
+
+**Verificata end-to-end in produzione** su `hub.iamcavalli.net` il 2026-07-29: senza cookie il gate non lascia trapelare **nessun dato di progetto** nell'HTML.
+
+**Known deferred items at close:** SEND-01/SEND-02 (invio preventivo via email) — rinviati, il mailer resta comunque in prod.
+
+Archive: [`milestones/v2.3-ROADMAP.md`](milestones/v2.3-ROADMAP.md) · [`milestones/v2.3-REQUIREMENTS.md`](milestones/v2.3-REQUIREMENTS.md)
+
+---
+
 ## v2.2 Sales Loop (Phases 18–22, shipped 2026-06-20)
 
 **Phases completed:** 5 phases (18–22) · 9 plans · 27 commits · 87 files · +7.349/-842 righe
@@ -28,6 +63,10 @@ Archive: `.planning/milestones/v2.2-ROADMAP.md` · `.planning/milestones/v2.2-RE
 - Offer Editor Tier A/B/C (Phase 12): editor offerte con matrice checkbox servizi×tier, totale live, prezzo pubblico manuale, tag 4-dimensioni, promessa di trasformazione; 55 servizi reali caricati (OFFER-11, OFFER-15..18)
 - CRM Attio-style (Phase 14): `/admin/leads` ridisegnata con inline edit + tag multi-select; FollowUpWidget in italiano; LeadForm tipizzato; SendQuoteModal senza rami irraggiungibili (CRM-08..12)
 
+Phase 13 è poi tornata in vita come milestone v2.4, consegnata il 2026-08-01.
+
+Archive: [`milestones/v2.1-ROADMAP.md`](milestones/v2.1-ROADMAP.md) (ricostruito il 2026-08-08) · fasi in [`milestones/v2.1-phases/`](milestones/v2.1-phases/)
+
 ---
 
 ## v2.0 Business Operations Suite (Phases 7–10, completato 2026-06-13)
diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md
index b436aa8..ca53de6 100644
--- a/.planning/PROJECT.md
+++ b/.planning/PROJECT.md
@@ -8,15 +8,16 @@ Suite operativa per un consulente di personal branding, live su hub.iamcavalli.n
 
 Il cliente apre il link e vede esattamente a che punto è il suo progetto, cosa deve ancora succedere e cosa ha già approvato — senza dover scrivere email per chiedere aggiornamenti.
 
-## Current Milestone: v2.3 Email & Accesso
+## Current Milestone: v2.4 Post-vendita
 
-**Goal:** Aggiungere uno strato email all'app — OTP gate per il portale cliente e invio link preventivo dall'admin — con un'unica integrazione Resend condivisa.
+**Goal:** Chiudere il ciclo di vita di ciò che è già venduto — un retainer deve poter finire, e l'admin deve poter vedere il portale con gli occhi del cliente.
 
-**Target features:**
-- AUTH-OTP-01 — OTP gate portale cliente (whitelist email + sessione 30gg + admin UI)
-- PUB-03 — Invio link `/preventivo/[slug]` via email Resend dall'admin
+**Consegnato (in produzione):**
 
-**Backlog v2.4+:** PROP-03 (Stripe Payment Link), PROP-04 (auto-provisioning al "Vinto"), Phase 13 (servizi ricorrenti)
+- Phase 13 — Ciclo di vita dei servizi ricorrenti (RET-01..05), prod 2026-08-01
+- Phase 26 — Anteprima admin del portale + toggle password sul login (PREV-01/02, AUTH-09), prod 2026-08-08
+
+**Backlog:** RET-06 (canoni mensili tracciabili), SEND-01/02 (invio preventivo via email), PROP-03 (Stripe Payment Link), PROP-04 (auto-provisioning al "Vinto"), DEBT-01 (debito design). Elenco completo in `REQUIREMENTS.md`.
 
 ## Requirements
 
@@ -57,10 +58,19 @@ Validated in v2.2 Sales Loop (shipped 2026-06-20):
 - ✓ Agente AI: Claude Opus 4.8, Zod schema 20+ sezioni, snapshot JSONB proposals, form admin — Phase 21 (AI-01, AI-02)
 - ✓ Deck pubblico `/preventivo/[slug]`: 20+ slide 100vh, keyboard nav; accept/reject `accepted_at` immutabile — Phase 22 (PUB-01, PUB-02)
 
-### Active — v2.3
+Validated in v2.3 Email & Accesso (shipped 2026-07-29):
 
-- [ ] AUTH-OTP-01 — Accesso cliente via OTP email: whitelist `client_emails`, gate `/client/[token]/*`, sessione 30gg, admin whitelist UI
-- [ ] PUB-03 — Invia link `/preventivo/[slug]` via email Resend dall'admin
+- ✓ Gate OTP sul portale cliente: whitelist `client_emails`, codice 6 cifre via Resend, sessione firmata **90 giorni** (non 30: modificata il 2026-07-28), revoca in blocco dall'admin — Phase 23/24/25 (OTP-01..08). Migr. 0015.
+- ✗ PUB-03 / SEND-01/02 (invio preventivo via email) **non consegnato**: rinviato al backlog il 2026-07-28. Il preventivo si manda a mano; l'infrastruttura Resend è comunque in prod.
+
+Validated in v2.4 Post-vendita (in produzione):
+
+- ✓ Ciclo di vita dei servizi ricorrenti: `project_offers.status` + `end_date`, forecast che si ferma, comandi Sospendi/Riattiva/Cessa, stato visibile al cliente — Phase 13 (RET-01..05). Migr. 0016.
+- ✓ Anteprima admin in sola lettura del portale cliente + toggle password sul login — Phase 26 (PREV-01/02, AUTH-09).
+
+### Active
+
+Nessun requisito in lavorazione. Il prossimo va scelto dal backlog in `REQUIREMENTS.md`.
 
 ### Out of Scope
 
@@ -79,8 +89,8 @@ Validated in v2.2 Sales Loop (shipped 2026-06-20):
 - Tutto sotto la stessa app: `/admin/*` (sessione Auth.js) + `/client/[token]/*` (token) + `/preventivo/[slug]` (pubblico)
 - La sidebar admin include: Dashboard, Leads (con toggle Lista/Kanban), Offerte, Catalogo, Preventivi (con CTA globale "Genera preventivo")
 - Stack v2.2: `@anthropic-ai/sdk@0.105.0` (Claude Opus 4.8), `@dnd-kit` (Kanban), `nanoid` (slug proposals)
-- DB live: 10 migrazioni applicate a prod (0000–0010); `proposals` table con `content jsonb` snapshot; `client_transcripts` per lead
-- Migrations sono manuali: SSH tunnel → `node` script PRIMA di pushare codice schema-dipendente; `drizzle-kit generate` rotto da Phase 8
+- DB live: migrazioni applicate a prod fino alla **0016**; `proposals` con `content jsonb` snapshot; `client_transcripts` per lead; `client_emails`/`otp_codes` per il gate OTP
+- Migrations sono manuali: SQL a mano applicato via **SSH + docker exec** PRIMA di pushare il codice schema-dipendente (procedura in `CLAUDE.md`); `drizzle-kit generate` rotto da Phase 8
 - `ANTHROPIC_API_KEY` in Coolify — aggiunta 2026-06-20 via PHP artisan; costo ~$0.44/preventivo (Opus 4.8)
 - Il flusso commerciale reale: call con lead → transcript incollato → genera preventivo AI → deck pubblica → cliente sceglie tier → vinto/perso
 
@@ -90,7 +100,7 @@ Validated in v2.2 Sales Loop (shipped 2026-06-20):
 - **Architettura (LOCKED)**: `clients.token` separato e rotatable; `quote_items` mai esposti via client API; `deliverables.approved_at` immutabile; no file hosting
 - **Compartimenti stagni**: un'unica app Next.js, moduli isolati (route group + service layer propri) su Postgres condiviso; migrations solo additive; niente deploy separati per ora (modello OMC adattato)
 - **NO database esterno / Excel come fonte dati**: Postgres resta l'unica fonte di verità — il problema è la UX, non il dato
-- **Numerazione fasi**: v2.0 ha chiuso a Phase 10; v2.1 parte da Phase 11
+- **Numerazione fasi**: progressiva e mai riusata — v1.0 1–6, v2.0 7–10, v2.1 11–17 (13/15/16/17 mai eseguite), v2.2 18–22, v2.3 23–25, v2.4 13 (ripresa dal congelamento) + 26
 
 ## Key Decisions
 
@@ -103,14 +113,18 @@ Validated in v2.2 Sales Loop (shipped 2026-06-20):
 | Catalogo servizi unificato (una tabella `services`) | Due cataloghi paralleli (service_catalog + offer_services) duplicano manutenzione prezzi | ✓ Good — tabella `services` live da Phase 7, consolidamento legacy in v2.1 |
 | Tier offerte indipendenti (A/B/C separati, stesso tag) | Più semplice di un meccanismo di ereditarietà; ogni tier configurato a sé | ✓ Good — usato in deck slide Pricing/StagesRecap/Comparison |
 | Prezzi pacchetti per-preventivo, non da catalogo | Permette di alzare i prezzi nel tempo senza toccare il catalogo | ✓ Good — `public_price` per tier, snapshot in `proposals.content` |
-| Al "Vinto" le fasi dell'offerta sono COPIATE nel progetto | Il progetto resta modificabile senza toccare il template offerta | — Pending (PROP-04, backlog v2.3) |
+| Al "Vinto" le fasi dell'offerta sono COPIATE nel progetto | Il progetto resta modificabile senza toccare il template offerta | — Pending (PROP-04, backlog) |
 | NO DB esterno/Excel, Postgres unica fonte | Lezione 2026-06-11: due fonti disallineate hanno causato il crash Phase 10 | ✓ Good |
 | Catalogo/Offerte UX = database view custom (non Notion-clone) | Notion troppo complesso per v1; serve velocità, non sezioni analitiche | ✓ Good — confermato in v2.1 |
 | Tab "Preventivo" rimossa, "Offerte" → "Servizi attivi" | Preventivo Builder è l'unico flusso; `accepted_total` già coperto da Payments | ✓ Confermato — zero perdita funzionale verificata (2026-06-13) |
 | Ordine: Offer Studio (UX dato) prima, Proposal AI (AI) dopo | L'AI è l'ultimo miglio, serve un dato pulito e veloce da gestire prima | ✓ Good — strategia validata: catalogo+offerte puliti → AI in v2.2 |
 | Output AI = JSON strutturato Zod → template fisso | Coerenza visiva garantita; zero rischio HTML rotto dall'AI | ✓ Good — 20+ sezioni Zod validate, deck sempre coerente |
 | `proposals.content` = JSONB snapshot immutabile | Prezzi e profilo consulente "bloccati" al momento della generazione | ✓ Good — invariante di audit, coerente con `accepted_at` |
-| Email Resend (PUB-03) deferred | Scope minimo funziona; link condiviso manualmente per ora | — Pending (v2.3 candidato #1) |
+| Email Resend (PUB-03) deferred | Scope minimo funziona; link condiviso manualmente per ora | — Pending — rinviata di nuovo il 2026-07-28, il mailer però è in prod |
+| Il gate OTP sta in cima alla `page`, mai nel layout | Nell'App Router il `page` è renderizzato in parallelo al layout: gattare nel layout lascia i dati nel payload RSC | ✓ Good — verificato: 46.907 → 17.594 byte di HTML |
+| Sessione OTP a 90 giorni invece di 30 | Rientro più fluido per il cliente, compensato dalla revoca in blocco lato admin (OTP-08) | ✓ Good — in prod dal 2026-07-29 |
+| Storico di vendita ≠ forecast | `getOffersSoldBreakdown` non filtra per stato: escludere le offerte cessate riscriverebbe il fatturato passato | ✓ Good — Phase 13 |
+| Anteprima admin del portale in sola lettura | Le API client autenticano sul token nel body, non sulla sessione: un click distratto approverebbe un deliverable, e `approved_at` è immutabile (LOCKED #3) | ✓ Good — protezione a livello UI, deviazione da LOCKED #4 accettata (Phase 26) |
 
 ## Evolution
 
@@ -130,4 +144,4 @@ This document evolves at phase transitions and milestone boundaries.
 4. Update Context with current state
 
 ---
-*Last updated: 2026-06-21 — v2.3 milestone started: Email & Accesso (AUTH-OTP-01 + PUB-03)*
+*Last updated: 2026-08-08 — v2.3 archiviata, v2.4 Post-vendita corrente (Phase 13 + 26 in produzione)*
diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md
index 0119316..af8a013 100644
--- a/.planning/REQUIREMENTS.md
+++ b/.planning/REQUIREMENTS.md
@@ -1,69 +1,47 @@
-# Requirements: ClientHub v2.3 Email & Accesso
+# Requirements: ClientHub v2.4 Post-vendita
 
-**Defined:** 2026-06-21
+**Definiti:** 2026-08-08 (ricostruiti a posteriori — v2.4 è partita senza requisiti scritti)
 **Core Value:** Il cliente apre il link e vede esattamente a che punto è il suo progetto, cosa deve ancora succedere e cosa ha già approvato — senza dover scrivere email per chiedere aggiornamenti.
 
-## v2.3 Requirements
+Milestone precedente: [v2.3 Email & Accesso](milestones/v2.3-ROADMAP.md), shipped 2026-07-29.
 
-### Email OTP Gate (AUTH-OTP-01)
+## Consegnati
 
-Portale cliente blindato da email OTP. Nuovo `client_emails` table (whitelist) + `otp_codes` table (codice, email, expires_at, consumed). Resend come provider email. Sessione **90 giorni** con cookie dopo verifica, revocabile dall'admin.
+### Ciclo di vita dei servizi ricorrenti (Phase 13) — ✅ in produzione 2026-08-01
 
-- [x] **OTP-01**: Admin può aggiungere e rimuovere email dalla whitelist di ogni cliente nell'admin UI
-- [x] **OTP-02**: Cliente senza sessione OTP vede una schermata "inserisci email" invece della dashboard
-- [x] **OTP-03**: Sistema invia OTP via Resend solo se l'email inserita è nella whitelist di quel cliente
-- [x] **OTP-04**: Cliente inserisce il codice OTP ricevuto e ottiene sessione autenticata (cookie **90 giorni**)
-- [x] **OTP-05**: Codici OTP scadono dopo 15 minuti dall'invio
-- [x] **OTP-06**: Endpoint OTP è rate-limited per prevenire brute force
-- [x] **OTP-07**: Messaggi di errore OTP non rivelano se l'email è in whitelist o no (no enumeration)
-- [x] **OTP-08**: Admin può revocare in blocco tutte le sessioni attive di un cliente
+- [x] **RET-01**: Un'offerta ricorrente assegnata a un progetto ha uno stato (attivo / sospeso / cessato) e una data di fine opzionale
+- [x] **RET-02**: L'admin può sospendere, riattivare e cessare un retainer dalla tab Offerte del progetto
+- [x] **RET-03**: Il forecast a 12 mesi smette di sommare un retainer sospeso, cessato o oltre la sua `end_date`
+- [x] **RET-04**: Lo storico del venduto (`getOffersSoldBreakdown`) **non** filtra per stato — escludere le cessate riscriverebbe il passato
+- [x] **RET-05**: Il cliente vede stato, "attivo dal / fino al" e "canone mensile"; le offerte cessate non gli arrivano
 
-> **[2026-07-28] Modifiche alla spec del 2026-06-21**, decise in sessione:
-> - Sessione **90 giorni** invece di 30 (rientro più fluido), compensata da OTP-08.
-> - **SEND-01/SEND-02 spostati al backlog v2.4**: il preventivo si invia a mano, l'automazione non serve ora. Phase 23 si è ridotta alla sola infrastruttura Resend, che l'OTP usa comunque.
-> - **Il gate NON sta nel layout** ma in cima a ogni page sotto `/client/[token]/`. Nell'App Router il segmento `page` viene renderizzato in parallelo al layout: gattare nel layout nascondeva la dashboard a schermo ma lasciava fasi, task e pagamenti nel payload RSC dell'HTML (verificato: 46.907 byte con i dati → 17.594 dopo il fix). Helper: `src/lib/client-gate.ts`.
+### Anteprima admin e login (Phase 26) — ✅ in produzione 2026-08-08
 
-## v2.4+ Backlog
+- [x] **PREV-01**: L'admin può aprire il portale di un cliente in sola lettura senza passare dal gate OTP (`?preview=1` + sessione Auth.js valida)
+- [x] **PREV-02**: In anteprima approvazione e composer messaggi sono disattivati a livello di UI
+- [x] **AUTH-09**: Il campo password del login admin ha un toggle mostra/nascondi
 
-### Conversione Commerciale
+## Backlog v2.4+ (non pianificati)
 
-- **PROP-03**: Stripe Payment Link su deck pubblico `/preventivo/[slug]`
-- **PROP-04**: Auto-provisioning cliente/progetto/fasi al "Vinto" nel CRM
-- **SEND-01/SEND-02**: invio del link `/preventivo/[slug]` via email dall'admin UI — *rinviato da v2.3 il 2026-07-28, l'invio si fa a mano. L'infrastruttura Resend (`src/lib/mailer.ts`) è già pronta, manca solo l'azione e il pulsante.*
+Ereditati dalle chiusure di milestone precedenti, nessuno in corso:
 
-### Post-Vendita
+- [ ] **SEND-01 / SEND-02** — Invio del link `/preventivo/[slug]` via email dall'admin. Il mailer (`src/lib/mailer.ts`) è già pronto e in produzione dalla v2.3: manca solo il pulsante e l'action. *Rinviati il 2026-07-28.*
+- [ ] **PROP-03** — Stripe Payment Link sul deck pubblico del preventivo. *Rinviato al kickoff v2.3.*
+- [ ] **PROP-04** — Auto-provisioning di cliente / progetto / fasi al passaggio del lead a "Vinto". *Rinviato al kickoff v2.3.*
+- [ ] **RET-06** — Canoni mensili tracciabili (agosto pagato / settembre no). **Serve una tabella nuova**: `payments` è protetta dai vincoli di Data Safety e la sua riscalatura è pensata per i piani una tantum. *Fuori scope di Phase 13.*
+- [ ] **OFFER-14** — Sezioni analitiche stile Notion sull'offerta. *Rinviato al kickoff v2.1.*
+- [ ] **ARCH-01** — Split del modulo "compartimento stagno" in un deploy separato. *Solo se il modulo cresce.*
+- [ ] **DEBT-01** — Debito design: **~40 file, ~450 occorrenze** di palette Tailwind raw e hex literal al posto dei token semantici. I cluster: `/admin/projects/[id]` e i suoi tab (~182), `/admin/offers/[id]/edit` (~79), `/admin/clients/[id]` (~59), tutto `/quote/[token]` (~48, ed è rivolto al cliente), `ChatPanel` del portale (37), più `ui/dialog.tsx` che propaga il look vecchio a ogni modale. Esclusi perché legittimi: `AdminSidebar` (eccezione brand documentata), `src/lib/mailer.ts` (HTML email, niente CSS var), i colori di stato di `StatusBadge` (sanzionati dal design system, hanno già le varianti `dark:`). *Misurato il 2026-08-08 — la stima precedente di "11 pagine" era sottostimata.*
+- [ ] **DEBT-02** — Tabelle legacy `service_catalog` / `offer_services` / `offer_micro_services` come deadweight; `createService` / `serviceSchema` dead code in `src/app/admin/catalog/actions.ts`.
 
-- **Phase 13**: Gestione servizi attivi/ricorrenti post-vendita nel portale cliente (congelata da v2.1)
+## Aperto, non un requisito
 
-## Out of Scope
+**Whitelist del portale vuota per 3 clienti su 4.** La migration 0015 ha seedato solo
+`mario@test.it` (cliente di test). Protocollo Estetico, Caruso Speaker e Teckell hanno
+whitelist vuota e finché lo è **il loro portale non è accessibile**. Si popola da
+`/admin/clients/<id>` → "Accessi al portale", poi va reinviato il link.
 
-| Feature | Reason |
-|---------|--------|
-| Self-registration cliente | Solo whitelist admin-gestita — nessun accesso senza approvazione esplicita |
-| Magic link senza OTP | OTP è più sicuro e già deciso come design; magic link = scope creep |
-| Email marketing / newsletter | Non pertinente al portale |
-| Multi-admin | Ancora single admin per ora |
+## Fuori scope
 
-## Traceability
-
-| Requirement | Phase | Status |
-|-------------|-------|--------|
-| OTP-01 | Phase 24 | ✅ Done (2026-07-28) |
-| OTP-02 | Phase 25 | ✅ Done (2026-07-28) |
-| OTP-03 | Phase 25 | ✅ Done (2026-07-28) |
-| OTP-04 | Phase 25 | ✅ Done (2026-07-28) |
-| OTP-05 | Phase 25 | ✅ Done (2026-07-28) |
-| OTP-06 | Phase 25 | ✅ Done (2026-07-28) |
-| OTP-07 | Phase 25 | ✅ Done (2026-07-28) |
-| OTP-08 | Phase 24 | ✅ Done (2026-07-28) |
-| SEND-01 | — | ⏭️ Rinviato a v2.4 |
-| SEND-02 | — | ⏭️ Rinviato a v2.4 |
-
-**Coverage:**
-- v2.3 requirements: 8 in scope (OTP-01…08) + 2 rinviati
-- Implementati: 8/8 ✓ — verificati con 9 test E2E in locale contro il DB di produzione
-- **Non ancora in produzione**: il codice è scritto e testato ma NON pushato. Vedi i blocchi in `STATE.md`.
-
----
-*Requirements defined: 2026-06-21*
-*Last updated: 2026-07-28 — sessione 90gg, OTP-08 aggiunto, SEND-01/02 rinviati, OTP-01…08 implementati*
+- File hosting (vincolo LOCKED #5: i documenti restano URL esterni).
+- Tabella utenti / multi-admin: l'auth resta una singola credenziale da env.
diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md
index 6985071..bd8ca8b 100644
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@@ -4,10 +4,10 @@
 
 - ✅ **v1.0 Client Portal & Offer System** — Phases 1–6 (shipped 2026-06-10) — [archive](milestones/v1.0-ROADMAP.md)
 - ✅ **v2.0 Business Operations Suite** — Phases 7–10 (shipped 2026-06-13) — [archive](milestones/v2.0-ROADMAP.md)
-- ✅ **v2.1 Offer Studio + CRM** — Phases 11–14 parziale (chiuso 2026-06-19, reset → v2.2)
+- ✅ **v2.1 Offer Studio + CRM** — Phases 11, 12, 14 (chiusa per reset 2026-06-19) — [archive](milestones/v2.1-ROADMAP.md)
 - ✅ **v2.2 Sales Loop** — Phases 18–22 (shipped 2026-06-20) — [archive](milestones/v2.2-ROADMAP.md)
-- ✅ **v2.3 Email & Accesso** — Phases 23–25 (shipped 2026-07-29)
-- 🔨 **v2.4 Post-vendita** — Phase 13 (in corso)
+- ✅ **v2.3 Email & Accesso** — Phases 23–25 (shipped 2026-07-29) — [archive](milestones/v2.3-ROADMAP.md)
+- 🔨 **v2.4 Post-vendita** — Phases 13 + 26 (entrambe in produzione)
 
 ## Phases
 
@@ -15,10 +15,10 @@
 <summary>✅ v1.0 + v2.0 + v2.1 (Phases 1–17) — SHIPPED / CHIUSE</summary>
 
 Vedi archivi:
+
 - `milestones/v1.0-ROADMAP.md` — Phases 1–6
 - `milestones/v2.0-ROADMAP.md` — Phases 7–10
-- Phases 11, 12, 14 — Offer Studio + CRM Attio (shipped in prod)
-- Phases 13, 15, 16, 17 — congelate/abbandonate/ri-scopate in v2.2
+- `milestones/v2.1-ROADMAP.md` — Phases 11, 12, 14 shipped; 15/16/17 abbandonate o ri-scopate; **Phase 13 ripresa in v2.4**
 
 </details>
 
@@ -35,57 +35,27 @@ Archivio completo: [milestones/v2.2-ROADMAP.md](milestones/v2.2-ROADMAP.md)
 
 </details>
 
-### 🔨 v2.3 — Email & Accesso (Phases 23–25)
+<details>
+<summary>✅ v2.3 Email & Accesso (Phases 23–25) — SHIPPED 2026-07-29</summary>
 
-- [x] **Phase 23: Resend Setup** — SDK Resend + `src/lib/mailer.ts` + template OTP *(l'invio preventivo è stato rinviato a v2.4 il 2026-07-28)*
-- [x] **Phase 24: Schema + Whitelist Admin** — Tabelle `client_emails` e `otp_codes`, admin UI gestione whitelist + revoca sessioni
-- [x] **Phase 25: OTP Gate + Sessione** — Gate OTP completo, sessione **90gg**, rate limiting, no enumeration
+- [x] Phase 23: Resend Setup — SDK + `src/lib/mailer.ts` + template OTP *(SEND-01/02 rinviati al backlog il 2026-07-28)*
+- [x] Phase 24: Schema + Whitelist Admin — `client_emails`, `otp_codes`, UI whitelist + revoca sessioni (migr. 0015)
+- [x] Phase 25: OTP Gate + Sessione — gate completo, sessione **90gg**, rate limiting, no enumeration
 
-✅ **Shipped 2026-07-29** (commit `27da969`), verificata end-to-end su `hub.iamcavalli.net`. SEND-01/02 rinviati a backlog.
+Shipped col commit `27da969`, verificata end-to-end su `hub.iamcavalli.net`.
+Archivio completo: [milestones/v2.3-ROADMAP.md](milestones/v2.3-ROADMAP.md)
 
-### 🔨 v2.4 — Post-vendita (Phase 13)
+</details>
 
-- [ ] **Phase 13: Ciclo di vita dei servizi ricorrenti** — `project_offers.status` + `end_date` (migr. 0016), forecast che si ferma davvero, comandi Sospendi/Riattiva/Cessa nella tab Offerte, stato dell'abbonamento visibile al cliente.
+### 🔨 v2.4 — Post-vendita (Phases 13 + 26)
 
-Fuori scope di questo giro, rimandato: tracciamento dei canoni mese per mese (serve una tabella nuova — `payments` è protetta e la sua riscalatura è pensata per i piani una tantum).
+- [x] **Phase 13: Ciclo di vita dei servizi ricorrenti** — `project_offers.status` + `end_date` (migr. 0016), forecast che si ferma davvero, comandi Sospendi/Riattiva/Cessa nella tab Offerte, stato dell'abbonamento visibile al cliente. ✅ **prod 2026-08-01** (`5177a37`) — [13-SUMMARY.md](phases/13-ciclo-vita-servizi-ricorrenti/13-SUMMARY.md)
+- [x] **Phase 26: Anteprima admin del portale + toggle password** — `?preview=1` con sessione Auth.js valida apre il portale di un cliente in sola lettura, senza gate OTP. ✅ **prod 2026-08-08** (`09a5b1f`, `187550f`) — [26-SUMMARY.md](phases/26-anteprima-admin-e-login/26-SUMMARY.md)
 
-## Phase Details
-
-### Phase 23: Resend Setup + Invio Preventivo
-**Goal**: Admin può inviare il link `/preventivo/[slug]` via email con un click dall'admin UI
-**Depends on**: Nothing — primo uso di Resend, nessuna dipendenza DB
-**Requirements**: SEND-01, SEND-02
-**Success Criteria** (what must be TRUE):
-  1. Admin fa click su "Invia preventivo" nel dettaglio lead/preventivo e l'email parte senza uscire dall'app
-  2. Il destinatario riceve un'email in italiano con nome cliente e link cliccabile al deck pubblico
-  3. L'invio usa Resend con le variabili d'ambiente configurate su Coolify (`RESEND_API_KEY`, `RESEND_FROM`)
-  4. In caso di errore Resend, l'admin vede un messaggio di errore chiaro nell'UI (non un crash silenzioso)
-**Plans**: TBD
-**UI hint**: yes
-
-### Phase 24: Schema + Whitelist Admin
-**Goal**: Admin può gestire la whitelist email di ogni cliente, con le tabelle DB pronte per l'OTP gate
-**Depends on**: Phase 23 (Resend SDK già installato e variabili d'ambiente configurate)
-**Requirements**: OTP-01
-**Success Criteria** (what must be TRUE):
-  1. Admin può aggiungere una o più email alla whitelist di un cliente dalla pagina dettaglio cliente
-  2. Admin può rimuovere un'email dalla whitelist di un cliente
-  3. Le tabelle `client_emails` e `otp_codes` esistono in produzione (migration additive applicata via SSH prima del codice)
-  4. La migration non tocca nessuna delle tabelle protette (`clients`, `projects`, `payments`, `phases`)
-**Plans**: TBD
-**UI hint**: yes
-
-### Phase 25: OTP Gate + Sessione
-**Goal**: Il portale `/client/[token]/*` richiede verifica OTP email prima di mostrare la dashboard
-**Depends on**: Phase 24 (tabelle `client_emails` e `otp_codes` in prod)
-**Requirements**: OTP-02, OTP-03, OTP-04, OTP-05, OTP-06, OTP-07
-**Success Criteria** (what must be TRUE):
-  1. Cliente senza sessione OTP valida vede una schermata "inserisci la tua email" al posto della dashboard
-  2. Inserita un'email in whitelist, il cliente riceve il codice OTP via Resend; inserendo il codice corretto ottiene accesso con cookie valido 30 giorni
-  3. Un'email non in whitelist non riceve OTP — il messaggio d'errore mostrato è identico a quello per email valide (no enumeration)
-  4. Un codice OTP non utilizzato entro 15 minuti viene rifiutato; il cliente deve richiederne uno nuovo
-  5. Tentativi ripetuti sugli endpoint OTP vengono bloccati dal rate limiter (no brute force)
-**Plans**: TBD
+**Nessuna fase aperta.** Il prossimo lavoro va scelto dal backlog in
+[REQUIREMENTS.md](REQUIREMENTS.md) — i candidati principali sono RET-06 (canoni
+mensili tracciabili, richiede una tabella nuova perché `payments` è protetta) e
+DEBT-01 (debito design, ~40 file).
 
 ## Progress
 
@@ -95,10 +65,9 @@ Fuori scope di questo giro, rimandato: tracciamento dei canoni mese per mese (se
 | 7–10. Unified Catalog → CRM Pipeline | v2.0 | 12/12 | ✅ Done | 2026-06-13 |
 | 11. Catalog Database-View UX | v2.1 | 4/4 | ✅ Done | 2026-06-13 |
 | 12. Offer Editor Tier A/B/C | v2.1 | 5/5 | ✅ Done | 2026-06-18 |
-| 13. Workspace Servizi Attivi | v2.1 | — | ❌ Congelata | — |
 | 14. CRM Attio-style & Fix | v2.1 | 3/3 | ✅ Done | 2026-06-14 |
 | 15. Dashboard Revenue Stats | v2.1 | — | ❌ Abbandonata | — |
-| 16–17. Proposal AI originale | v2.1 | — | ❌ Ri-scopata in v2.2 | — |
+| 16–17. Proposal AI originale | v2.1 | — | ♻️ Ri-scopata in v2.2 | — |
 | 18. Cleanup & Consolidamento | v2.2 | 3/3 | ✅ Done | 2026-06-19 |
 | 19. Pipeline CRM Kanban | v2.2 | 1/1 | ✅ Done | 2026-06-19 |
 | 20. Knowledge Base Cliente | v2.2 | 3/3 | ✅ Done | 2026-06-20 |
@@ -107,50 +76,9 @@ Fuori scope di questo giro, rimandato: tracciamento dei canoni mese per mese (se
 | 23. Resend Setup | v2.3 | 1/1 | ✅ Done | 2026-07-28 |
 | 24. Schema + Whitelist Admin | v2.3 | 1/1 | ✅ Done | 2026-07-28 |
 | 25. OTP Gate + Sessione | v2.3 | 1/1 | ✅ Done | 2026-07-29 |
-| 13. Ciclo di vita servizi ricorrenti | v2.4 | 1/1 | 🔨 In corso | — |
+| 13. Ciclo di vita servizi ricorrenti | v2.4 | 1/1 | ✅ Done | 2026-08-01 |
+| 26. Anteprima admin + login | v2.4 | 1/1 | ✅ Done | 2026-08-08 |
 
 ---
+*Roadmap aggiornata: 2026-08-08 — v2.3 archiviata, v2.4 documentata a posteriori*
 
-## Requirement Coverage (v2.3)
-
-| Requirement | Phase |
-|-------------|-------|
-| SEND-01 | Phase 23 |
-| SEND-02 | Phase 23 |
-| OTP-01 | Phase 24 |
-| OTP-02 | Phase 25 |
-| OTP-03 | Phase 25 |
-| OTP-04 | Phase 25 |
-| OTP-05 | Phase 25 |
-| OTP-06 | Phase 25 |
-| OTP-07 | Phase 25 |
-
-**Mapped: 9/9. No orphans.**
-
----
-
-## Dependency Chain (v2.3)
-
-```
-Phase 23 (Resend config + SDK)
-    └── Phase 24 (schema DB additive: client_emails + otp_codes)
-            └── Phase 25 (OTP gate + sessione cookie 30gg)
-```
-
-Phase 23 first: Resend SDK e variabili d'ambiente sono infrastruttura condivisa con Phase 25 (email OTP).
-Phase 24 before Phase 25: le tabelle `client_emails` e `otp_codes` devono essere in prod (via SSH migration) prima del gate.
-
----
-
-## Implementation Notes (v2.3)
-
-**Migration constraint:** `client_emails` e `otp_codes` sono nuove tabelle — migration additiva pura. SQL a mano (drizzle-kit generate rotto da Phase 8). Applicare via SSH tunnel PRIMA di pushare il codice dipendente.
-
-**OTP middleware layer:** Il token middleware esistente (proxy.ts → `/api/internal/validate-token`) rimane invariato. Il gate OTP è uno strato aggiuntivo dopo la validazione del token, non un suo rimpiazzo.
-
-**Resend shared infra:** La stessa istanza Resend client e le stesse variabili d'ambiente (`RESEND_API_KEY`, `RESEND_FROM`) servono sia Phase 23 (email preventivo) sia Phase 25 (email OTP). Configurare una volta in Phase 23, riusare in Phase 25.
-
-**Security invariants (Phase 25, come consegnata):** rate limiting su entrambi gli endpoint OTP; risposta identica per email in whitelist e non; OTP 6 cifre, scade 15 minuti, monouso (`consumed_at` al primo uso), max 5 tentativi; cookie HttpOnly + Secure + SameSite=Lax, **MaxAge 90 giorni** (non 30: modificato il 2026-07-28, compensato dalla revoca admin), per-cliente. Il gate sta in cima alla `page`, non nel layout — vedi la lezione in `STATE.md`.
-
----
-*Roadmap created: 2026-06-21 — v2.3 Email & Accesso*
diff --git a/.planning/UI-RULES.md b/.planning/UI-RULES.md
deleted file mode 100644
index 46f1354..0000000
--- a/.planning/UI-RULES.md
+++ /dev/null
@@ -1,68 +0,0 @@
-# UI Rules — ClientHub admin
-
-Derived from the live codebase (`src/app/globals.css`, design system usage across admin pages).
-These are the rules to follow for any new or modified admin page.
-
----
-
-## Brand palette
-
-All colours must be written as **hex literals** — no Tailwind semantic tokens (`text-foreground`, `bg-muted`, etc.) in admin UI. Semantic tokens are defined in `globals.css` but mixing hex and tokens creates inconsistency.
-
-| Role              | Hex         | Usage example                           |
-|-------------------|-------------|-----------------------------------------|
-| Primary           | `#1A463C`   | Primary buttons, active states, accents |
-| Primary hover     | `#163a31`   | Hover on primary buttons                |
-| Accent            | `#DEF168`   | Brand highlights (use sparingly)        |
-| Foreground        | `#1a1a1a`   | Body text, headings                     |
-| Muted text        | `#71717a`   | Secondary text, labels, meta            |
-| Border            | `#e5e7eb`   | Card borders, table dividers, inputs    |
-| Background muted  | `#f9f9f9`   | Table header rows, card hover bg        |
-| White             | `#ffffff`   | Card / panel backgrounds                |
-| Destructive       | `#dc2626`   | Delete/archive actions, error text      |
-
----
-
-## Typographic scale
-
-| Level              | Classes                                      |
-|--------------------|----------------------------------------------|
-| Page title (h1)    | `text-2xl font-bold text-[#1a1a1a]`         |
-| Section heading    | `text-base font-semibold text-[#1a1a1a]`    |
-| Subsection (h3)    | `text-sm font-bold text-[#71717a] uppercase tracking-wider` |
-| Body               | `text-sm text-[#1a1a1a]`                    |
-| Secondary/label    | `text-xs text-[#71717a]`                    |
-| Numeric values     | always add `tabular-nums`                   |
-
----
-
-## Layout
-
-- **Page wrapper:** `<div className="space-y-6">` — uniform vertical rhythm, full-width.
-- **Page header:** always use `<PageHeader>` from `src/components/admin/PageHeader.tsx` — never hand-roll the title + action row.
-- **No width constraints on list pages:** do not add `max-w-*` or `mx-auto` to the page root. Width is controlled by the sidebar layout (`src/app/admin/layout.tsx`).
-- **Detail/form pages** (e.g. OfferEditorClient) may keep their own `max-w-4xl mx-auto` — this rule applies to list/overview pages only.
-- **Cards:** `rounded-lg border border-[#e5e7eb] bg-white p-4`; hover: `hover:shadow-[0_4px_12px_rgba(0,0,0,0.08)]`.
-- **Tables:** `bg-white rounded-xl border border-[#e5e7eb] overflow-hidden`; thead `bg-[#f9f9f9] border-b border-[#e5e7eb]`; row divider `border-b border-[#e5e7eb]`.
-
----
-
-## Interaction
-
-- Clickable elements: `cursor-pointer`
-- Colour transitions: `transition-colors duration-150`
-- Focus ring: `focus:outline-none focus-visible:ring-2 focus-visible:ring-[#1A463C]/30`
-- Minimum touch target on buttons: 44 × 44 px (use `py-2 px-4` minimum or `h-10`)
-- Primary CTA: `bg-[#1A463C] text-white hover:bg-[#163a31] transition-colors`
-- Secondary/ghost CTA: `border border-[#e5e7eb] text-[#1a1a1a] hover:bg-[#f9f9f9] transition-colors`
-- Destructive action: `text-[#dc2626] hover:bg-red-50 transition-colors`
-
----
-
-## Anti-patterns (do not do these)
-
-- **No emoji as UI icons** — use Lucide React icons instead.
-- **No mixed semantic tokens and hex** — pick hex throughout any given page/component.
-- **No per-page `max-w-*` on list pages** — layout width is the sidebar shell's responsibility.
-- **No hand-rolled page header divs** — always use `<PageHeader>` to keep title size/weight/colour uniform.
-- **No inline `style={{}}` for colours that have a Tailwind class** — reserve `style` for dynamic values only (e.g. progress bar width percentages).
diff --git a/.planning/milestones/v2.1-ROADMAP.md b/.planning/milestones/v2.1-ROADMAP.md
new file mode 100644
index 0000000..ea29bb5
--- /dev/null
+++ b/.planning/milestones/v2.1-ROADMAP.md
@@ -0,0 +1,64 @@
+# Archivio milestone v2.1 — Offer Studio + CRM
+
+**Fasi previste:** 11–17 · **Consegnate:** 11, 12, 14 · **Aperta:** 2026-06-13 · **Chiusa per reset:** 2026-06-19
+
+> **Ricostruito a posteriori il 2026-08-08.** v2.1 è l'unica milestone rimasta senza
+> archivio: è stata interrotta da un reset di scope e nessuno l'ha chiusa
+> formalmente, così le sue fasi sono rimaste in `.planning/phases/` per due mesi.
+> Questo file è ricostruito da `MILESTONES.md`, dalla tabella Progress di
+> `ROADMAP.md` e dalle cartelle di fase archiviate in [v2.1-phases/](v2.1-phases/).
+> Non esiste un `v2.1-REQUIREMENTS.md`: i 23 requisiti originali sono stati
+> sovrascritti quando `REQUIREMENTS.md` è stato riscritto per v2.3.
+
+## Obiettivo originale
+
+Offer Studio (fasi 11–15) prima di Proposal AI (fasi 16–17): prima una UX dati
+pulita e veloce, poi il builder AI costruito sopra.
+
+## Esito per fase
+
+| Fase | Titolo | Plans | Esito |
+|---|---|---|---|
+| 11 | Catalog Database-View UX + consolidamento legacy | 4/4 | ✅ 2026-06-13 |
+| 12 | Offer Editor Tier A/B/C | 5/5 | ✅ 2026-06-18 |
+| 13 | Workspace — Servizi Attivi | — | ❄️ Congelata → ripresa in **v2.4** |
+| 14 | CRM Attio-style & Fix | 3/3 | ✅ 2026-06-14 |
+| 15 | Dashboard Revenue Stats | — | ❌ Abbandonata (bloccata su un mockup mai fornito) |
+| 16–17 | Proposal AI (impianto originale) | — | ♻️ Ri-scopate in v2.2 (fasi 21–22) |
+
+Documentazione di dettaglio (PLAN, SUMMARY, RESEARCH, VERIFICATION) in
+[v2.1-phases/](v2.1-phases/).
+
+## Cosa è stato consegnato
+
+- **Phase 11 — Catalog Database-View UX** (OFFER-07..10, OFFER-13): il catalogo
+  `services` come tabella a edit inline, tag multi-select, quick-add, ricerca
+  istantanea; consolidamento delle tabelle legacy.
+- **Phase 12 — Offer Editor Tier A/B/C** (OFFER-11, OFFER-15..18): editor offerte
+  con matrice checkbox servizi × tier, totale live, prezzo pubblico manuale, tag su
+  4 dimensioni, promessa di trasformazione. 55 servizi reali caricati.
+- **Phase 14 — CRM Attio-style** (CRM-08..12): `/admin/leads` ridisegnata con edit
+  inline e tag multi-select; FollowUpWidget in italiano; LeadForm tipizzato;
+  SendQuoteModal ripulita dai rami irraggiungibili.
+
+## Il reset del 2026-06-19
+
+A metà milestone il piano è stato riscritto: la milestone **v2.2 "Sales Loop"**
+sostituisce le fasi residue. Decisioni bloccate in quel momento:
+
+1. L'URL del preventivo è `/preventivo/[slug]`, pubblico.
+2. Si tagliano Forecast, quote builder manuale e Phase 15; `/admin/analytics` viene
+   fusa nella Dashboard.
+3. Il portale post-vendita resta core e non si tocca (Phase 13 congelata).
+4. L'agente AI è "io scelgo l'offerta, l'AI personalizza" leggendo i transcript;
+   provider Claude.
+
+Phase 13 è poi tornata in vita come **milestone v2.4**, consegnata il 2026-08-01.
+
+## Debito lasciato aperto
+
+- Tabelle legacy `service_catalog` / `offer_services` / `offer_micro_services`
+  rimaste come deadweight.
+- `createService` / `serviceSchema` dead code in `src/app/admin/catalog/actions.ts`
+  (Phase 11 Plan 04, annotato in `deferred-items.md`).
+- `offer_micros` senza `created_at` — nessun "tier più vecchio" affidabile.
diff --git a/.planning/phases/11-catalog-database-view-ux-legacy-consolidation/11-01-PLAN.md b/.planning/milestones/v2.1-phases/11-catalog-database-view-ux-legacy-consolidation/11-01-PLAN.md
similarity index 100%
rename from .planning/phases/11-catalog-database-view-ux-legacy-consolidation/11-01-PLAN.md
rename to .planning/milestones/v2.1-phases/11-catalog-database-view-ux-legacy-consolidation/11-01-PLAN.md
diff --git a/.planning/phases/11-catalog-database-view-ux-legacy-consolidation/11-01-SUMMARY.md b/.planning/milestones/v2.1-phases/11-catalog-database-view-ux-legacy-consolidation/11-01-SUMMARY.md
similarity index 100%
rename from .planning/phases/11-catalog-database-view-ux-legacy-consolidation/11-01-SUMMARY.md
rename to .planning/milestones/v2.1-phases/11-catalog-database-view-ux-legacy-consolidation/11-01-SUMMARY.md
diff --git a/.planning/phases/11-catalog-database-view-ux-legacy-consolidation/11-02-PLAN.md b/.planning/milestones/v2.1-phases/11-catalog-database-view-ux-legacy-consolidation/11-02-PLAN.md
similarity index 100%
rename from .planning/phases/11-catalog-database-view-ux-legacy-consolidation/11-02-PLAN.md
rename to .planning/milestones/v2.1-phases/11-catalog-database-view-ux-legacy-consolidation/11-02-PLAN.md
diff --git a/.planning/phases/11-catalog-database-view-ux-legacy-consolidation/11-02-SUMMARY.md b/.planning/milestones/v2.1-phases/11-catalog-database-view-ux-legacy-consolidation/11-02-SUMMARY.md
similarity index 100%
rename from .planning/phases/11-catalog-database-view-ux-legacy-consolidation/11-02-SUMMARY.md
rename to .planning/milestones/v2.1-phases/11-catalog-database-view-ux-legacy-consolidation/11-02-SUMMARY.md
diff --git a/.planning/phases/11-catalog-database-view-ux-legacy-consolidation/11-03-PLAN.md b/.planning/milestones/v2.1-phases/11-catalog-database-view-ux-legacy-consolidation/11-03-PLAN.md
similarity index 100%
rename from .planning/phases/11-catalog-database-view-ux-legacy-consolidation/11-03-PLAN.md
rename to .planning/milestones/v2.1-phases/11-catalog-database-view-ux-legacy-consolidation/11-03-PLAN.md
diff --git a/.planning/phases/11-catalog-database-view-ux-legacy-consolidation/11-03-SUMMARY.md b/.planning/milestones/v2.1-phases/11-catalog-database-view-ux-legacy-consolidation/11-03-SUMMARY.md
similarity index 100%
rename from .planning/phases/11-catalog-database-view-ux-legacy-consolidation/11-03-SUMMARY.md
rename to .planning/milestones/v2.1-phases/11-catalog-database-view-ux-legacy-consolidation/11-03-SUMMARY.md
diff --git a/.planning/phases/11-catalog-database-view-ux-legacy-consolidation/11-04-PLAN.md b/.planning/milestones/v2.1-phases/11-catalog-database-view-ux-legacy-consolidation/11-04-PLAN.md
similarity index 100%
rename from .planning/phases/11-catalog-database-view-ux-legacy-consolidation/11-04-PLAN.md
rename to .planning/milestones/v2.1-phases/11-catalog-database-view-ux-legacy-consolidation/11-04-PLAN.md
diff --git a/.planning/phases/11-catalog-database-view-ux-legacy-consolidation/11-04-SUMMARY.md b/.planning/milestones/v2.1-phases/11-catalog-database-view-ux-legacy-consolidation/11-04-SUMMARY.md
similarity index 100%
rename from .planning/phases/11-catalog-database-view-ux-legacy-consolidation/11-04-SUMMARY.md
rename to .planning/milestones/v2.1-phases/11-catalog-database-view-ux-legacy-consolidation/11-04-SUMMARY.md
diff --git a/.planning/phases/11-catalog-database-view-ux-legacy-consolidation/11-CONTEXT.md b/.planning/milestones/v2.1-phases/11-catalog-database-view-ux-legacy-consolidation/11-CONTEXT.md
similarity index 100%
rename from .planning/phases/11-catalog-database-view-ux-legacy-consolidation/11-CONTEXT.md
rename to .planning/milestones/v2.1-phases/11-catalog-database-view-ux-legacy-consolidation/11-CONTEXT.md
diff --git a/.planning/phases/11-catalog-database-view-ux-legacy-consolidation/11-DISCUSSION-LOG.md b/.planning/milestones/v2.1-phases/11-catalog-database-view-ux-legacy-consolidation/11-DISCUSSION-LOG.md
similarity index 100%
rename from .planning/phases/11-catalog-database-view-ux-legacy-consolidation/11-DISCUSSION-LOG.md
rename to .planning/milestones/v2.1-phases/11-catalog-database-view-ux-legacy-consolidation/11-DISCUSSION-LOG.md
diff --git a/.planning/phases/11-catalog-database-view-ux-legacy-consolidation/11-PATTERNS.md b/.planning/milestones/v2.1-phases/11-catalog-database-view-ux-legacy-consolidation/11-PATTERNS.md
similarity index 100%
rename from .planning/phases/11-catalog-database-view-ux-legacy-consolidation/11-PATTERNS.md
rename to .planning/milestones/v2.1-phases/11-catalog-database-view-ux-legacy-consolidation/11-PATTERNS.md
diff --git a/.planning/phases/11-catalog-database-view-ux-legacy-consolidation/11-REVIEW.md b/.planning/milestones/v2.1-phases/11-catalog-database-view-ux-legacy-consolidation/11-REVIEW.md
similarity index 100%
rename from .planning/phases/11-catalog-database-view-ux-legacy-consolidation/11-REVIEW.md
rename to .planning/milestones/v2.1-phases/11-catalog-database-view-ux-legacy-consolidation/11-REVIEW.md
diff --git a/.planning/phases/11-catalog-database-view-ux-legacy-consolidation/11-VERIFICATION.md b/.planning/milestones/v2.1-phases/11-catalog-database-view-ux-legacy-consolidation/11-VERIFICATION.md
similarity index 100%
rename from .planning/phases/11-catalog-database-view-ux-legacy-consolidation/11-VERIFICATION.md
rename to .planning/milestones/v2.1-phases/11-catalog-database-view-ux-legacy-consolidation/11-VERIFICATION.md
diff --git a/.planning/phases/11-catalog-database-view-ux-legacy-consolidation/deferred-items.md b/.planning/milestones/v2.1-phases/11-catalog-database-view-ux-legacy-consolidation/deferred-items.md
similarity index 100%
rename from .planning/phases/11-catalog-database-view-ux-legacy-consolidation/deferred-items.md
rename to .planning/milestones/v2.1-phases/11-catalog-database-view-ux-legacy-consolidation/deferred-items.md
diff --git a/.planning/phases/12-offer-composition-drag-drop-csv-import/12-01-PLAN.md b/.planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-01-PLAN.md
similarity index 100%
rename from .planning/phases/12-offer-composition-drag-drop-csv-import/12-01-PLAN.md
rename to .planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-01-PLAN.md
diff --git a/.planning/phases/12-offer-composition-drag-drop-csv-import/12-01-SUMMARY.md b/.planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-01-SUMMARY.md
similarity index 100%
rename from .planning/phases/12-offer-composition-drag-drop-csv-import/12-01-SUMMARY.md
rename to .planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-01-SUMMARY.md
diff --git a/.planning/phases/12-offer-composition-drag-drop-csv-import/12-02-PLAN.md b/.planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-02-PLAN.md
similarity index 100%
rename from .planning/phases/12-offer-composition-drag-drop-csv-import/12-02-PLAN.md
rename to .planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-02-PLAN.md
diff --git a/.planning/phases/12-offer-composition-drag-drop-csv-import/12-02-SUMMARY.md b/.planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-02-SUMMARY.md
similarity index 100%
rename from .planning/phases/12-offer-composition-drag-drop-csv-import/12-02-SUMMARY.md
rename to .planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-02-SUMMARY.md
diff --git a/.planning/phases/12-offer-composition-drag-drop-csv-import/12-03-PLAN.md b/.planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-03-PLAN.md
similarity index 100%
rename from .planning/phases/12-offer-composition-drag-drop-csv-import/12-03-PLAN.md
rename to .planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-03-PLAN.md
diff --git a/.planning/phases/12-offer-composition-drag-drop-csv-import/12-03-SUMMARY.md b/.planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-03-SUMMARY.md
similarity index 100%
rename from .planning/phases/12-offer-composition-drag-drop-csv-import/12-03-SUMMARY.md
rename to .planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-03-SUMMARY.md
diff --git a/.planning/phases/12-offer-composition-drag-drop-csv-import/12-04-PLAN.md b/.planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-04-PLAN.md
similarity index 100%
rename from .planning/phases/12-offer-composition-drag-drop-csv-import/12-04-PLAN.md
rename to .planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-04-PLAN.md
diff --git a/.planning/phases/12-offer-composition-drag-drop-csv-import/12-04-SUMMARY.md b/.planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-04-SUMMARY.md
similarity index 100%
rename from .planning/phases/12-offer-composition-drag-drop-csv-import/12-04-SUMMARY.md
rename to .planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-04-SUMMARY.md
diff --git a/.planning/phases/12-offer-composition-drag-drop-csv-import/12-05-PLAN.md b/.planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-05-PLAN.md
similarity index 100%
rename from .planning/phases/12-offer-composition-drag-drop-csv-import/12-05-PLAN.md
rename to .planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-05-PLAN.md
diff --git a/.planning/phases/12-offer-composition-drag-drop-csv-import/12-05-SUMMARY.md b/.planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-05-SUMMARY.md
similarity index 100%
rename from .planning/phases/12-offer-composition-drag-drop-csv-import/12-05-SUMMARY.md
rename to .planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-05-SUMMARY.md
diff --git a/.planning/phases/12-offer-composition-drag-drop-csv-import/12-CONTEXT.md b/.planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-CONTEXT.md
similarity index 100%
rename from .planning/phases/12-offer-composition-drag-drop-csv-import/12-CONTEXT.md
rename to .planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-CONTEXT.md
diff --git a/.planning/phases/12-offer-composition-drag-drop-csv-import/12-RESEARCH.md b/.planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-RESEARCH.md
similarity index 100%
rename from .planning/phases/12-offer-composition-drag-drop-csv-import/12-RESEARCH.md
rename to .planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-RESEARCH.md
diff --git a/.planning/phases/12-offer-composition-drag-drop-csv-import/12-REVIEW.md b/.planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-REVIEW.md
similarity index 100%
rename from .planning/phases/12-offer-composition-drag-drop-csv-import/12-REVIEW.md
rename to .planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-REVIEW.md
diff --git a/.planning/phases/12-offer-composition-drag-drop-csv-import/12-UI-SPEC.md b/.planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-UI-SPEC.md
similarity index 100%
rename from .planning/phases/12-offer-composition-drag-drop-csv-import/12-UI-SPEC.md
rename to .planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-UI-SPEC.md
diff --git a/.planning/phases/12-offer-composition-drag-drop-csv-import/12-VERIFICATION.md b/.planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-VERIFICATION.md
similarity index 100%
rename from .planning/phases/12-offer-composition-drag-drop-csv-import/12-VERIFICATION.md
rename to .planning/milestones/v2.1-phases/12-offer-composition-drag-drop-csv-import/12-VERIFICATION.md
diff --git a/.planning/phases/14-crm-attio-style-fix/14-01-PLAN.md b/.planning/milestones/v2.1-phases/14-crm-attio-style-fix/14-01-PLAN.md
similarity index 100%
rename from .planning/phases/14-crm-attio-style-fix/14-01-PLAN.md
rename to .planning/milestones/v2.1-phases/14-crm-attio-style-fix/14-01-PLAN.md
diff --git a/.planning/phases/14-crm-attio-style-fix/14-01-SUMMARY.md b/.planning/milestones/v2.1-phases/14-crm-attio-style-fix/14-01-SUMMARY.md
similarity index 100%
rename from .planning/phases/14-crm-attio-style-fix/14-01-SUMMARY.md
rename to .planning/milestones/v2.1-phases/14-crm-attio-style-fix/14-01-SUMMARY.md
diff --git a/.planning/phases/14-crm-attio-style-fix/14-02-PLAN.md b/.planning/milestones/v2.1-phases/14-crm-attio-style-fix/14-02-PLAN.md
similarity index 100%
rename from .planning/phases/14-crm-attio-style-fix/14-02-PLAN.md
rename to .planning/milestones/v2.1-phases/14-crm-attio-style-fix/14-02-PLAN.md
diff --git a/.planning/phases/14-crm-attio-style-fix/14-02-SUMMARY.md b/.planning/milestones/v2.1-phases/14-crm-attio-style-fix/14-02-SUMMARY.md
similarity index 100%
rename from .planning/phases/14-crm-attio-style-fix/14-02-SUMMARY.md
rename to .planning/milestones/v2.1-phases/14-crm-attio-style-fix/14-02-SUMMARY.md
diff --git a/.planning/phases/14-crm-attio-style-fix/14-03-PLAN.md b/.planning/milestones/v2.1-phases/14-crm-attio-style-fix/14-03-PLAN.md
similarity index 100%
rename from .planning/phases/14-crm-attio-style-fix/14-03-PLAN.md
rename to .planning/milestones/v2.1-phases/14-crm-attio-style-fix/14-03-PLAN.md
diff --git a/.planning/phases/14-crm-attio-style-fix/14-03-SUMMARY.md b/.planning/milestones/v2.1-phases/14-crm-attio-style-fix/14-03-SUMMARY.md
similarity index 100%
rename from .planning/phases/14-crm-attio-style-fix/14-03-SUMMARY.md
rename to .planning/milestones/v2.1-phases/14-crm-attio-style-fix/14-03-SUMMARY.md
diff --git a/.planning/phases/14-crm-attio-style-fix/14-PATTERNS.md b/.planning/milestones/v2.1-phases/14-crm-attio-style-fix/14-PATTERNS.md
similarity index 100%
rename from .planning/phases/14-crm-attio-style-fix/14-PATTERNS.md
rename to .planning/milestones/v2.1-phases/14-crm-attio-style-fix/14-PATTERNS.md
diff --git a/.planning/phases/14-crm-attio-style-fix/14-RESEARCH.md b/.planning/milestones/v2.1-phases/14-crm-attio-style-fix/14-RESEARCH.md
similarity index 100%
rename from .planning/phases/14-crm-attio-style-fix/14-RESEARCH.md
rename to .planning/milestones/v2.1-phases/14-crm-attio-style-fix/14-RESEARCH.md
diff --git a/.planning/phases/14-crm-attio-style-fix/14-REVIEW.md b/.planning/milestones/v2.1-phases/14-crm-attio-style-fix/14-REVIEW.md
similarity index 100%
rename from .planning/phases/14-crm-attio-style-fix/14-REVIEW.md
rename to .planning/milestones/v2.1-phases/14-crm-attio-style-fix/14-REVIEW.md
diff --git a/.planning/phases/14-crm-attio-style-fix/14-UI-SPEC.md b/.planning/milestones/v2.1-phases/14-crm-attio-style-fix/14-UI-SPEC.md
similarity index 100%
rename from .planning/phases/14-crm-attio-style-fix/14-UI-SPEC.md
rename to .planning/milestones/v2.1-phases/14-crm-attio-style-fix/14-UI-SPEC.md
diff --git a/.planning/phases/14-crm-attio-style-fix/14-VERIFICATION.md b/.planning/milestones/v2.1-phases/14-crm-attio-style-fix/14-VERIFICATION.md
similarity index 100%
rename from .planning/phases/14-crm-attio-style-fix/14-VERIFICATION.md
rename to .planning/milestones/v2.1-phases/14-crm-attio-style-fix/14-VERIFICATION.md
diff --git a/.planning/phases/14-crm-attio-style-fix/deferred-items.md b/.planning/milestones/v2.1-phases/14-crm-attio-style-fix/deferred-items.md
similarity index 100%
rename from .planning/phases/14-crm-attio-style-fix/deferred-items.md
rename to .planning/milestones/v2.1-phases/14-crm-attio-style-fix/deferred-items.md
diff --git a/.planning/phases/18-cleanup-consolidamento/18-01-PLAN.md b/.planning/milestones/v2.2-phases/18-cleanup-consolidamento/18-01-PLAN.md
similarity index 100%
rename from .planning/phases/18-cleanup-consolidamento/18-01-PLAN.md
rename to .planning/milestones/v2.2-phases/18-cleanup-consolidamento/18-01-PLAN.md
diff --git a/.planning/phases/18-cleanup-consolidamento/18-01-SUMMARY.md b/.planning/milestones/v2.2-phases/18-cleanup-consolidamento/18-01-SUMMARY.md
similarity index 100%
rename from .planning/phases/18-cleanup-consolidamento/18-01-SUMMARY.md
rename to .planning/milestones/v2.2-phases/18-cleanup-consolidamento/18-01-SUMMARY.md
diff --git a/.planning/phases/18-cleanup-consolidamento/18-02-PLAN.md b/.planning/milestones/v2.2-phases/18-cleanup-consolidamento/18-02-PLAN.md
similarity index 100%
rename from .planning/phases/18-cleanup-consolidamento/18-02-PLAN.md
rename to .planning/milestones/v2.2-phases/18-cleanup-consolidamento/18-02-PLAN.md
diff --git a/.planning/phases/18-cleanup-consolidamento/18-02-SUMMARY.md b/.planning/milestones/v2.2-phases/18-cleanup-consolidamento/18-02-SUMMARY.md
similarity index 100%
rename from .planning/phases/18-cleanup-consolidamento/18-02-SUMMARY.md
rename to .planning/milestones/v2.2-phases/18-cleanup-consolidamento/18-02-SUMMARY.md
diff --git a/.planning/phases/18-cleanup-consolidamento/18-03-PLAN.md b/.planning/milestones/v2.2-phases/18-cleanup-consolidamento/18-03-PLAN.md
similarity index 100%
rename from .planning/phases/18-cleanup-consolidamento/18-03-PLAN.md
rename to .planning/milestones/v2.2-phases/18-cleanup-consolidamento/18-03-PLAN.md
diff --git a/.planning/phases/18-cleanup-consolidamento/18-03-SUMMARY.md b/.planning/milestones/v2.2-phases/18-cleanup-consolidamento/18-03-SUMMARY.md
similarity index 100%
rename from .planning/phases/18-cleanup-consolidamento/18-03-SUMMARY.md
rename to .planning/milestones/v2.2-phases/18-cleanup-consolidamento/18-03-SUMMARY.md
diff --git a/.planning/phases/19-pipeline-crm-kanban/19-01-PLAN.md b/.planning/milestones/v2.2-phases/19-pipeline-crm-kanban/19-01-PLAN.md
similarity index 100%
rename from .planning/phases/19-pipeline-crm-kanban/19-01-PLAN.md
rename to .planning/milestones/v2.2-phases/19-pipeline-crm-kanban/19-01-PLAN.md
diff --git a/.planning/phases/19-pipeline-crm-kanban/19-01-SUMMARY.md b/.planning/milestones/v2.2-phases/19-pipeline-crm-kanban/19-01-SUMMARY.md
similarity index 100%
rename from .planning/phases/19-pipeline-crm-kanban/19-01-SUMMARY.md
rename to .planning/milestones/v2.2-phases/19-pipeline-crm-kanban/19-01-SUMMARY.md
diff --git a/.planning/phases/19-pipeline-crm-kanban/19-RESEARCH.md b/.planning/milestones/v2.2-phases/19-pipeline-crm-kanban/19-RESEARCH.md
similarity index 100%
rename from .planning/phases/19-pipeline-crm-kanban/19-RESEARCH.md
rename to .planning/milestones/v2.2-phases/19-pipeline-crm-kanban/19-RESEARCH.md
diff --git a/.planning/phases/19-pipeline-crm-kanban/19-VERIFICATION.md b/.planning/milestones/v2.2-phases/19-pipeline-crm-kanban/19-VERIFICATION.md
similarity index 100%
rename from .planning/phases/19-pipeline-crm-kanban/19-VERIFICATION.md
rename to .planning/milestones/v2.2-phases/19-pipeline-crm-kanban/19-VERIFICATION.md
diff --git a/.planning/phases/20-knowledge-base-cliente/20-01-PLAN.md b/.planning/milestones/v2.2-phases/20-knowledge-base-cliente/20-01-PLAN.md
similarity index 100%
rename from .planning/phases/20-knowledge-base-cliente/20-01-PLAN.md
rename to .planning/milestones/v2.2-phases/20-knowledge-base-cliente/20-01-PLAN.md
diff --git a/.planning/phases/20-knowledge-base-cliente/20-01-SUMMARY.md b/.planning/milestones/v2.2-phases/20-knowledge-base-cliente/20-01-SUMMARY.md
similarity index 100%
rename from .planning/phases/20-knowledge-base-cliente/20-01-SUMMARY.md
rename to .planning/milestones/v2.2-phases/20-knowledge-base-cliente/20-01-SUMMARY.md
diff --git a/.planning/phases/20-knowledge-base-cliente/20-02-PLAN.md b/.planning/milestones/v2.2-phases/20-knowledge-base-cliente/20-02-PLAN.md
similarity index 100%
rename from .planning/phases/20-knowledge-base-cliente/20-02-PLAN.md
rename to .planning/milestones/v2.2-phases/20-knowledge-base-cliente/20-02-PLAN.md
diff --git a/.planning/phases/20-knowledge-base-cliente/20-02-SUMMARY.md b/.planning/milestones/v2.2-phases/20-knowledge-base-cliente/20-02-SUMMARY.md
similarity index 100%
rename from .planning/phases/20-knowledge-base-cliente/20-02-SUMMARY.md
rename to .planning/milestones/v2.2-phases/20-knowledge-base-cliente/20-02-SUMMARY.md
diff --git a/.planning/phases/20-knowledge-base-cliente/20-03-PLAN.md b/.planning/milestones/v2.2-phases/20-knowledge-base-cliente/20-03-PLAN.md
similarity index 100%
rename from .planning/phases/20-knowledge-base-cliente/20-03-PLAN.md
rename to .planning/milestones/v2.2-phases/20-knowledge-base-cliente/20-03-PLAN.md
diff --git a/.planning/phases/20-knowledge-base-cliente/20-03-SUMMARY.md b/.planning/milestones/v2.2-phases/20-knowledge-base-cliente/20-03-SUMMARY.md
similarity index 100%
rename from .planning/phases/20-knowledge-base-cliente/20-03-SUMMARY.md
rename to .planning/milestones/v2.2-phases/20-knowledge-base-cliente/20-03-SUMMARY.md
diff --git a/.planning/phases/20-knowledge-base-cliente/20-CONTEXT.md b/.planning/milestones/v2.2-phases/20-knowledge-base-cliente/20-CONTEXT.md
similarity index 100%
rename from .planning/phases/20-knowledge-base-cliente/20-CONTEXT.md
rename to .planning/milestones/v2.2-phases/20-knowledge-base-cliente/20-CONTEXT.md
diff --git a/.planning/phases/20-knowledge-base-cliente/20-DISCUSSION-LOG.md b/.planning/milestones/v2.2-phases/20-knowledge-base-cliente/20-DISCUSSION-LOG.md
similarity index 100%
rename from .planning/phases/20-knowledge-base-cliente/20-DISCUSSION-LOG.md
rename to .planning/milestones/v2.2-phases/20-knowledge-base-cliente/20-DISCUSSION-LOG.md
diff --git a/.planning/phases/21-agente-ai-generazione-preventivo/21-01-SUMMARY.md b/.planning/milestones/v2.2-phases/21-agente-ai-generazione-preventivo/21-01-SUMMARY.md
similarity index 100%
rename from .planning/phases/21-agente-ai-generazione-preventivo/21-01-SUMMARY.md
rename to .planning/milestones/v2.2-phases/21-agente-ai-generazione-preventivo/21-01-SUMMARY.md
diff --git a/.planning/phases/21-agente-ai-generazione-preventivo/21-CONTEXT.md b/.planning/milestones/v2.2-phases/21-agente-ai-generazione-preventivo/21-CONTEXT.md
similarity index 100%
rename from .planning/phases/21-agente-ai-generazione-preventivo/21-CONTEXT.md
rename to .planning/milestones/v2.2-phases/21-agente-ai-generazione-preventivo/21-CONTEXT.md
diff --git a/.planning/phases/21-agente-ai-generazione-preventivo/21-DISCUSSION-LOG.md b/.planning/milestones/v2.2-phases/21-agente-ai-generazione-preventivo/21-DISCUSSION-LOG.md
similarity index 100%
rename from .planning/phases/21-agente-ai-generazione-preventivo/21-DISCUSSION-LOG.md
rename to .planning/milestones/v2.2-phases/21-agente-ai-generazione-preventivo/21-DISCUSSION-LOG.md
diff --git a/.planning/phases/21-agente-ai-generazione-preventivo/21-PLAN.md b/.planning/milestones/v2.2-phases/21-agente-ai-generazione-preventivo/21-PLAN.md
similarity index 100%
rename from .planning/phases/21-agente-ai-generazione-preventivo/21-PLAN.md
rename to .planning/milestones/v2.2-phases/21-agente-ai-generazione-preventivo/21-PLAN.md
diff --git a/.planning/phases/22-pagina-pubblica-preventivo/22-01-SUMMARY.md b/.planning/milestones/v2.2-phases/22-pagina-pubblica-preventivo/22-01-SUMMARY.md
similarity index 100%
rename from .planning/phases/22-pagina-pubblica-preventivo/22-01-SUMMARY.md
rename to .planning/milestones/v2.2-phases/22-pagina-pubblica-preventivo/22-01-SUMMARY.md
diff --git a/.planning/milestones/v2.3-REQUIREMENTS.md b/.planning/milestones/v2.3-REQUIREMENTS.md
new file mode 100644
index 0000000..0119316
--- /dev/null
+++ b/.planning/milestones/v2.3-REQUIREMENTS.md
@@ -0,0 +1,69 @@
+# Requirements: ClientHub v2.3 Email & Accesso
+
+**Defined:** 2026-06-21
+**Core Value:** Il cliente apre il link e vede esattamente a che punto è il suo progetto, cosa deve ancora succedere e cosa ha già approvato — senza dover scrivere email per chiedere aggiornamenti.
+
+## v2.3 Requirements
+
+### Email OTP Gate (AUTH-OTP-01)
+
+Portale cliente blindato da email OTP. Nuovo `client_emails` table (whitelist) + `otp_codes` table (codice, email, expires_at, consumed). Resend come provider email. Sessione **90 giorni** con cookie dopo verifica, revocabile dall'admin.
+
+- [x] **OTP-01**: Admin può aggiungere e rimuovere email dalla whitelist di ogni cliente nell'admin UI
+- [x] **OTP-02**: Cliente senza sessione OTP vede una schermata "inserisci email" invece della dashboard
+- [x] **OTP-03**: Sistema invia OTP via Resend solo se l'email inserita è nella whitelist di quel cliente
+- [x] **OTP-04**: Cliente inserisce il codice OTP ricevuto e ottiene sessione autenticata (cookie **90 giorni**)
+- [x] **OTP-05**: Codici OTP scadono dopo 15 minuti dall'invio
+- [x] **OTP-06**: Endpoint OTP è rate-limited per prevenire brute force
+- [x] **OTP-07**: Messaggi di errore OTP non rivelano se l'email è in whitelist o no (no enumeration)
+- [x] **OTP-08**: Admin può revocare in blocco tutte le sessioni attive di un cliente
+
+> **[2026-07-28] Modifiche alla spec del 2026-06-21**, decise in sessione:
+> - Sessione **90 giorni** invece di 30 (rientro più fluido), compensata da OTP-08.
+> - **SEND-01/SEND-02 spostati al backlog v2.4**: il preventivo si invia a mano, l'automazione non serve ora. Phase 23 si è ridotta alla sola infrastruttura Resend, che l'OTP usa comunque.
+> - **Il gate NON sta nel layout** ma in cima a ogni page sotto `/client/[token]/`. Nell'App Router il segmento `page` viene renderizzato in parallelo al layout: gattare nel layout nascondeva la dashboard a schermo ma lasciava fasi, task e pagamenti nel payload RSC dell'HTML (verificato: 46.907 byte con i dati → 17.594 dopo il fix). Helper: `src/lib/client-gate.ts`.
+
+## v2.4+ Backlog
+
+### Conversione Commerciale
+
+- **PROP-03**: Stripe Payment Link su deck pubblico `/preventivo/[slug]`
+- **PROP-04**: Auto-provisioning cliente/progetto/fasi al "Vinto" nel CRM
+- **SEND-01/SEND-02**: invio del link `/preventivo/[slug]` via email dall'admin UI — *rinviato da v2.3 il 2026-07-28, l'invio si fa a mano. L'infrastruttura Resend (`src/lib/mailer.ts`) è già pronta, manca solo l'azione e il pulsante.*
+
+### Post-Vendita
+
+- **Phase 13**: Gestione servizi attivi/ricorrenti post-vendita nel portale cliente (congelata da v2.1)
+
+## Out of Scope
+
+| Feature | Reason |
+|---------|--------|
+| Self-registration cliente | Solo whitelist admin-gestita — nessun accesso senza approvazione esplicita |
+| Magic link senza OTP | OTP è più sicuro e già deciso come design; magic link = scope creep |
+| Email marketing / newsletter | Non pertinente al portale |
+| Multi-admin | Ancora single admin per ora |
+
+## Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| OTP-01 | Phase 24 | ✅ Done (2026-07-28) |
+| OTP-02 | Phase 25 | ✅ Done (2026-07-28) |
+| OTP-03 | Phase 25 | ✅ Done (2026-07-28) |
+| OTP-04 | Phase 25 | ✅ Done (2026-07-28) |
+| OTP-05 | Phase 25 | ✅ Done (2026-07-28) |
+| OTP-06 | Phase 25 | ✅ Done (2026-07-28) |
+| OTP-07 | Phase 25 | ✅ Done (2026-07-28) |
+| OTP-08 | Phase 24 | ✅ Done (2026-07-28) |
+| SEND-01 | — | ⏭️ Rinviato a v2.4 |
+| SEND-02 | — | ⏭️ Rinviato a v2.4 |
+
+**Coverage:**
+- v2.3 requirements: 8 in scope (OTP-01…08) + 2 rinviati
+- Implementati: 8/8 ✓ — verificati con 9 test E2E in locale contro il DB di produzione
+- **Non ancora in produzione**: il codice è scritto e testato ma NON pushato. Vedi i blocchi in `STATE.md`.
+
+---
+*Requirements defined: 2026-06-21*
+*Last updated: 2026-07-28 — sessione 90gg, OTP-08 aggiunto, SEND-01/02 rinviati, OTP-01…08 implementati*
diff --git a/.planning/milestones/v2.3-ROADMAP.md b/.planning/milestones/v2.3-ROADMAP.md
new file mode 100644
index 0000000..aaa8ed0
--- /dev/null
+++ b/.planning/milestones/v2.3-ROADMAP.md
@@ -0,0 +1,99 @@
+# Archivio milestone v2.3 — Email & Accesso
+
+**Fasi:** 23–25 · **Aperta:** 2026-06-21 · **Shipped:** 2026-07-29 (commit `27da969`)
+**Requisiti:** [v2.3-REQUIREMENTS.md](v2.3-REQUIREMENTS.md)
+
+> **Nota di archivio.** v2.3 è stata eseguita **fuori dal ciclo GSD**: non sono mai
+> esistite cartelle `phases/23`, `24`, `25` con PLAN/SUMMARY. Questo file *è*
+> la documentazione della milestone — non cercare altrove.
+
+## Obiettivo
+
+Aggiungere uno strato email all'app: gate OTP per il portale cliente e invio del
+link preventivo dall'admin, con un'unica integrazione Resend condivisa.
+
+Il portale non doveva più essere apribile col solo link: chiunque avesse l'URL
+vedeva il progetto del cliente.
+
+## Fasi
+
+### Phase 23 — Resend Setup ✅ 2026-07-28
+
+**Goal:** infrastruttura email condivisa.
+**Requisiti:** SEND-01, SEND-02 (poi ridotti — vedi sotto).
+
+Consegnato: `resend@6.18.1`, `src/lib/mailer.ts` (Result tipizzato, mai un catch
+silenzioso), template OTP in italiano. `RESEND_API_KEY` e `RESEND_FROM` configurate
+su Coolify (production **e** preview).
+
+**Riduzione di scope del 2026-07-28:** SEND-01/SEND-02 (invio del preventivo via
+email dall'admin) spostati al backlog. Il preventivo si manda a mano; l'automazione
+non serviva subito. Phase 23 si è ridotta alla sola infrastruttura Resend, che il
+gate OTP usa comunque.
+
+### Phase 24 — Schema + Whitelist Admin ✅ 2026-07-28
+
+**Goal:** l'admin gestisce la whitelist email di ogni cliente; tabelle pronte per il gate.
+**Requisiti:** OTP-01. **Dipende da:** Phase 23.
+
+Migration `0015_otp_access.sql`, **additiva pura**, applicata a prod via SSH prima
+del codice dipendente: `client_emails` (whitelist, unique case-insensitive),
+`otp_codes` (hash del codice, mai il codice in chiaro), `clients.sessions_valid_from`
+(revoca in blocco). Conteggi pre/post identici sulle tabelle protette —
+clients 4 / projects 5 / payments 11 / phases 10.
+
+UI: sezione "Accessi al portale" in `/admin/clients/[id]` — aggiungi/rimuovi email,
+"Revoca sessioni attive". Server actions in `clients/[id]/actions.ts`.
+
+### Phase 25 — OTP Gate + Sessione ✅ 2026-07-29
+
+**Goal:** `/client/[token]/*` richiede verifica OTP prima di mostrare la dashboard.
+**Requisiti:** OTP-02..OTP-07. **Dipende da:** Phase 24.
+
+Consegnato: `src/lib/otp.ts` (codice 6 cifre CSPRNG, hash SHA-256 con
+`NEXTAUTH_SECRET`+clientId, TTL 15 minuti, monouso, max 5 tentativi),
+`src/lib/client-session.ts` (cookie HMAC per-cliente `ch_sess_<id>`, httpOnly +
+secure + SameSite=lax, `path=/client`), `src/lib/client-gate.ts`, le route
+`/api/client/otp/request|verify`, il componente `OtpGate`.
+
+**Scostamento dalla spec del 21/06:** sessione **90 giorni** invece di 30 — rientro
+più fluido, compensato da OTP-08 (revoca in blocco lato admin).
+
+## Catena di dipendenze
+
+```
+Phase 23 (Resend SDK + env)
+    └── Phase 24 (schema additivo: client_emails + otp_codes)
+            └── Phase 25 (gate OTP + sessione cookie 90gg)
+```
+
+## Copertura requisiti
+
+| Requisito | Fase | Esito |
+|---|---|---|
+| SEND-01, SEND-02 | 23 | ⏭ Rinviati al backlog il 2026-07-28 |
+| OTP-01 | 24 | ✅ |
+| OTP-02 … OTP-07 | 25 | ✅ |
+| OTP-08 (revoca) | 24 | ✅ |
+
+## Verifica in produzione (2026-07-29, `hub.iamcavalli.net`)
+
+Gate mostrato senza cookie e **zero dati di progetto nell'HTML** (12.487 byte);
+email fuori e dentro whitelist danno risposta identica e solo la seconda genera un
+OTP; codice sbagliato rifiutato, corretto accettato; cookie `ch_sess_<id>` con
+`Secure` + `HttpOnly` + `SameSite=lax` + `Max-Age=7776000`; rientro col cookie
+mostra la dashboard; la sessione di un cliente sull'URL di un altro mostra il gate.
+Nessun errore d'invio nei log del container. Dati di test rimossi, tabelle protette
+invariate.
+
+## Lezioni
+
+Le due lezioni operative di questa milestone (il gate non va nel layout App Router;
+ricreare il dominio su Resend rigenera la chiave DKIM) sono in `STATUS.md`,
+sezione "Lezioni operative" — è lì che si vanno a cercare.
+
+## Strascico alla chiusura
+
+La whitelist è stata seedata solo con `mario@test.it` (cliente di test). Tre clienti
+reali su quattro hanno whitelist vuota e finché lo è **il loro portale non è
+accessibile**. Voce aperta in `STATUS.md`.
diff --git a/.planning/phases/13-ciclo-vita-servizi-ricorrenti/13-SUMMARY.md b/.planning/phases/13-ciclo-vita-servizi-ricorrenti/13-SUMMARY.md
new file mode 100644
index 0000000..249c436
--- /dev/null
+++ b/.planning/phases/13-ciclo-vita-servizi-ricorrenti/13-SUMMARY.md
@@ -0,0 +1,55 @@
+# Phase 13 — Ciclo di vita dei servizi ricorrenti
+
+**Milestone:** v2.4 Post-vendita · **Stato:** ✅ in produzione, verificata end-to-end
+**Consegnata:** 2026-08-01 · **Commit:** `5177a37` · **Migration:** `0016_project_offer_lifecycle.sql`
+
+> **Ricostruito a posteriori il 2026-08-08** dal commit, dalla migration e da
+> `STATUS.md`. La fase è stata eseguita fuori dal ciclo GSD: non esiste un PLAN.
+> Phase 13 nasce congelata in v2.1 (giugno) e riaperta come milestone v2.4.
+
+## Il problema
+
+Un retainer, una volta assegnato, non si poteva fermare. `project_offers` aveva solo
+`start_date`, e il ramo retainer di `src/lib/forecast-queries.ts` sommava il canone a
+**ogni mese** dell'orizzonte da lì in poi, per sempre. Un cliente che disdiceva
+continuava a gonfiare il forecast a 12 mesi e a vedersi l'abbonamento attivo nel
+proprio portale.
+
+## Cosa è stato fatto
+
+**Schema** — migration `0016`, additiva pura, applicata a prod **prima** del push:
+`project_offers.status` (`attivo|sospeso|cessato`, CHECK `NOT VALID` per evitare un
+lock lungo) e `project_offers.end_date` (nullable, NULL = continuativo). Default
+`'attivo'` così ogni riga esistente conserva esattamente il comportamento precedente.
+Nessun DROP, nessun TRUNCATE. Idempotente.
+
+**Forecast** — i retainer si fermano a `end_date`; sospesi e cessati escono dal
+calcolo. `getOffersSoldBreakdown` **non** filtra per stato di proposito: è uno
+storico di vendita, ed escludere le cessate riscriverebbe il passato.
+`offersAcceptedTotal` esclude le cessate (default del piano pagamenti).
+
+**Admin** — comandi Sospendi / Riattiva / Cessa più data di fine nella tab Offerte,
+mostrati solo per i ricorrenti. `setProjectOfferLifecycle` valida con Zod e filtra
+**anche per `project_id`**, così un id arbitrario non può toccare un altro progetto.
+
+**Portale cliente** — "Attivo dal", "fino al", badge *In pausa*, "Canone mensile" al
+posto di "Prezzo finale". Le offerte cessate non arrivano mai al client.
+
+**Fix collaterale** — un retainer sospeso continuava a intestare i pagamenti "Totale
+Pagamento Mensile" e a sovrascriverne l'importo.
+
+## Decisioni
+
+- **Storico di vendita ≠ forecast.** Due letture diverse degli stessi dati: il
+  breakdown del venduto ignora lo stato, il forecast lo rispetta. Unificarle
+  avrebbe fatto sparire fatturato già incassato dai report.
+- **Default `'attivo'` invece di NULL.** Rende la migration a comportamento
+  invariato senza una backfill separata.
+- **Filtro per `project_id` nell'action**, non solo per id dell'offerta: difesa in
+  profondità contro un id manipolato.
+
+## Fuori scope, rimandato
+
+Tracciamento dei canoni mese per mese (agosto pagato / settembre no). Serve una
+tabella nuova: `payments` è protetta dai vincoli di Data Safety e la sua riscalatura
+è pensata per i piani una tantum. Voce di backlog in `REQUIREMENTS.md`.
diff --git a/.planning/phases/26-anteprima-admin-e-login/26-SUMMARY.md b/.planning/phases/26-anteprima-admin-e-login/26-SUMMARY.md
new file mode 100644
index 0000000..33dfc88
--- /dev/null
+++ b/.planning/phases/26-anteprima-admin-e-login/26-SUMMARY.md
@@ -0,0 +1,71 @@
+# Phase 26 — Anteprima admin del portale + toggle password sul login
+
+**Milestone:** v2.4 Post-vendita · **Stato:** ✅ in produzione (deploy Coolify 2026-08-08)
+**Commit:** `09a5b1f` (toggle password) · `187550f` (anteprima admin)
+
+> **Ricostruito a posteriori il 2026-08-08.** Lavoro non pianificato in roadmap,
+> nato da due attriti d'uso reali. 26 è il primo numero di fase libero.
+
+## 1. Toggle mostra/nascondi password — `09a5b1f`
+
+Il campo password del login admin non offriva modo di rileggere quanto digitato: un
+accesso fallito era indistinguibile da un errore di battitura.
+
+Toggle **inline**, non un nuovo primitivo in `ui/`: `type="password"` compare una
+sola volta in tutto il codebase, un'astrazione avrebbe avuto un solo consumatore.
+`type="button"` perché dentro un `<form>` il default è submit; `tabIndex={-1}` per
+tenere il Tab sulla sequenza campo → Accedi. Classi a token semantici; gli hex
+literal preesistenti della pagina restano da migrare col resto del debito design.
+
+**Causa a monte (non era un bug):** `ADMIN_PASSWORD` è stata ruotata il 2026-07-28
+**solo su Coolify**, e `.env.local` è rimasto alla precedente. Vale anche per
+`NEXTAUTH_SECRET`. `.env.local` non è allineato a produzione e non va trattato come
+fonte di verità per le credenziali.
+
+## 2. Anteprima admin in sola lettura del portale — `187550f`
+
+Quando un cliente segnalava "non trovo una cosa" non c'era modo di guardare il
+portale con i suoi occhi: il gate OTP lascia entrare solo lui. Dall'elenco clienti
+(`ClientRow`) un'icona apre ora `/client/<slug>?preview=1` in una scheda nuova.
+
+**Come funziona.** `getClientGate()` accetta `{ previewRequested }` e salta il gate
+solo se il query param c'è **e** `getServerSession(authOptions)` è valida. Senza il
+param anche un admin vede il gate OTP — così il gate resta testabile dal vivo.
+Ritorna `preview: true` **senza sintetizzare una `ClientSession`**: un admin in
+anteprima non è un cliente autenticato, e confondere i due stati li renderebbe
+indistinguibili proprio dove serve distinguerli. Il flag viaggia via
+`PreviewProvider` / `usePreview()` e non per prop drilling: `ApproveButton` sta
+quattro livelli sotto la dashboard.
+
+**Perché sola lettura.** Il portale scrive davvero: `/api/client/approve` e
+`/api/client/comment` autenticano sul token nel body, non sulla sessione, e
+`deliverables.approved_at` è immutabile una volta impostato (**LOCKED #3**). Un
+click distratto approverebbe un deliverable in modo irreversibile. La protezione è
+a livello **UI, non API**: un admin può ancora chiamare le route a mano. È voluto —
+l'obiettivo è impedire l'incidente, non difendersi da sé stessi.
+
+## ⚠️ Deviazione consapevole dal vincolo LOCKED #4
+
+`CLAUDE.md` fissa: `/client/[token]/*` → token middleware, `/admin/*` → sessione
+Auth.js. Ora una route client legge **anche** la sessione Auth.js. Non indebolisce
+nulla — per i clienti il gate OTP è identico — ma la sezione LOCKED richiede
+approvazione esplicita prima di essere modificata. **Annotato in `CLAUDE.md` il
+2026-08-08 con l'ok dell'utente.**
+
+## Verifica
+
+**Verificato** col build di produzione su `:3100` contro il DB reale (sole letture):
+`?preview=1` senza sessione admin → gate OTP; con cookie di sessione contraffatto →
+gate OTP; `?preview=0`, `?preview=abc`, `?preview=` → gate OTP; nessun query param
+**con** sessione admin → gate OTP (nessuna regressione); sessione admin valida +
+`?preview=1` → portale con banner e composer disattivato, sia sul cliente a progetto
+singolo sia su quello a due progetti.
+
+**Non verificato dal vivo:** il ramo `ApproveButton` — in produzione la tabella
+`deliverables` è **vuota** (0 righe), quindi quel pulsante oggi non si renderizza
+mai. Wiring controllato solo a livello di codice. Il click dell'occhiolino sul login
+è verificato solo nel markup renderizzato (`type="button"`, `tabindex="-1"`,
+`aria-label`).
+
+**Nota di metodo:** Playwright non funziona contro `npm run dev` — la CSP blocca
+`eval` e i client component non si idratano. Va usato il build di produzione.
diff --git a/.planning/research/FEATURES.md b/.planning/research/FEATURES.md
deleted file mode 100644
index 5f871c9..0000000
--- a/.planning/research/FEATURES.md
+++ /dev/null
@@ -1,107 +0,0 @@
-# FEATURES.md — ClientHub Freelancer Client Portal
-
-**Domain:** Freelancer client portal — solo personal branding consultant
-**Project:** ClientHub (welcomeclient.iamcavalli.net)
-**Researched:** 2026-05-09
-**Confidence:** HIGH
-
----
-
-## Context
-
-Two asymmetric roles. Admin (the freelancer) has full CRUD. Client (read + lightweight interaction) accesses via secret URL — no login, no account — and can view, comment, and approve. The product competes indirectly with Notion client portals, HoneyBook, Dubsado, and bespoke agency portals. The differentiator is zero-friction secret link access and personal brand positioning.
-
----
-
-## Table Stakes
-
-Features clients expect when opening any project portal. Missing these causes confusion, distrust, or support overhead.
-
-| Feature | Why Expected | Complexity | Notes |
-|---------|--------------|------------|-------|
-| Project overview at a glance | Client needs to know "where we are" without reading walls of text | Low | Name, brand, brief, current phase |
-| Phase + task status visibility | Primary client question is "what's done, what's next" | Low | Phases with nested tasks; status per task (todo / in progress / done) |
-| Deliverable approval | Client must formally sign off on outputs | Medium | Per-deliverable approve action; state persists; admin sees approval timestamp |
-| Inline commenting on tasks/deliverables | Feedback and questions without email | Medium | Flat comments sufficient for v1; threading is nice-to-have |
-| Document / file links | Deliverables, briefs, contracts surface in the portal | Low | Links to Google Drive, PDF, external URL; no file hosting needed |
-| Payment status visibility | Client needs to know what they owe | Low | Deposit 50% + balance 50%; three states each: pending / invoiced / paid |
-| Total quoted amount (not itemized) | Client expects to see the agreed number | Low | Single total; line items are admin-only |
-| Mobile-readable layout | Clients open links on phones | Low | Responsive web; no native app |
-| Persistent secret link | Link must not expire or rotate without notice | Low | UUIDs in DB, never regenerated unless admin resets explicitly |
-| Trustworthy, branded appearance | First impression determines confidence in the consultant | Low | Logo, brand colors, professional typography — not a generic SaaS look |
-
----
-
-## Differentiators
-
-Not expected, but meaningfully improve experience or workflow.
-
-| Feature | Value Proposition | Complexity | Notes |
-|---------|-------------------|------------|-------|
-| Decision log / history | Running record of agreed decisions — eliminates "we never agreed on that" disputes | Low | Append-only note stream visible to client; admin writes entries |
-| Phase progress indicator | Visual progress bar gives a sense of momentum | Low | Derived from task completion %; no extra data model needed |
-| "Last updated" timestamp on dashboard | Shows the portal is live and maintained | Low | Trivially derived from DB updated_at |
-| Admin overview: all clients at a glance | Freelancer scans all active projects and overdue payments in one view | Medium | List with status badges; payment alert if overdue |
-| Payment status badge with clear labels | Color-coded states (red = unpaid, yellow = invoiced, green = paid) | Low | Client sees their own; admin sees all |
-| Shareable link reset | Admin can invalidate and regenerate a client's link if it leaks | Low | DB field update + redirect; rarely used but reassuring |
-| Service catalog | Admin builds quotes from a curated menu of services; reusable across clients | Medium | Lookup table; admin-only; used by Claude in v2 |
-| Claude-assisted onboarding (v2) | Generates phases + quote draft from a brief — massively speeds up admin work | High | Explicitly v2 in PROJECT.md |
-
----
-
-## Anti-Features
-
-Deliberately NOT building these.
-
-| Anti-Feature | Why Avoid | What to Do Instead |
-|--------------|-----------|-------------------|
-| Client login / account creation | Adds friction with no benefit for a small client list | Secret UUID link |
-| In-app invoicing / PDF generation | Accounting is out of scope | Show payment status only |
-| File upload / storage | Massive complexity | Link to Google Drive or Dropbox |
-| Email / SMS notifications | Transactional email infrastructure is heavy | Manual communication fine for small client list |
-| Multi-admin / team roles | Freelancer works alone | Single admin |
-| Client-editable project structure | Clients editing phases corrupts admin's source of truth | Comment and approve only |
-| Itemized pricing visible to client | Erodes commercial confidentiality | Single total; detail is admin-only |
-| Kanban / drag-and-drop board | Phases are sequential, not a fluid backlog | Ordered phase list |
-| Time tracking | Out of scope for project-based billing | Not relevant |
-| Multi-language / i18n | Single consultant, single-market | Hardcode interface language |
-
----
-
-## Feature Dependencies
-
-```
-Secret link (UUID) → Client dashboard
-Client dashboard → Phase/task display
-Phase/task display → Deliverable approval
-Phase/task display → Inline commenting
-Admin client management → Secret link generation
-Admin client management → Payment tracking
-Service catalog → Quote building (admin picks from catalog)
-Quote building → Payment tracking (total = basis for deposit/balance)
-Service catalog → Claude onboarding v2
-```
-
-**Key insight:** Admin must create data before the client dashboard shows anything meaningful. Admin-first, then client.
-
----
-
-## MVP Build Order
-
-1. Admin: create/edit client record with secret link generation
-2. Admin: create/edit phases and tasks per client
-3. Admin: set payment amounts and statuses
-4. Client dashboard: read-only view (overview, phases, tasks, payment status, documents)
-5. Client: deliverable approval
-6. Client: inline comments
-7. Admin: all-clients overview
-8. Admin: service catalog
-9. v2: Claude-assisted onboarding
-
----
-
-## Open Questions
-
-- What happens when a client accidentally shares their secret link? Is link reset sufficient, or should there be an access log?
-- Does the decision log need to be visible to clients from day one, or deferred?
-- Should approval actions be reversible (un-approve)?
diff --git a/.planning/research/FEATURES_v2.0.md b/.planning/research/FEATURES_v2.0.md
deleted file mode 100644
index 8d4f3f0..0000000
--- a/.planning/research/FEATURES_v2.0.md
+++ /dev/null
@@ -1,412 +0,0 @@
-# Feature Landscape: Business Operations Suite v2.0 (New Features)
-
-**Domain:** Proposal generation + lightweight CRM for solo personal-branding consultant  
-**Researched:** 2026-06-10  
-**Research Mode:** Ecosystem (proposal software + lightweight CRM patterns)  
-**Confidence:** MEDIUM-HIGH  
-**Scope:** ONLY new v2.0 features (does NOT review v1.0 table stakes already shipped)
-
----
-
-## Executive Summary
-
-The Business Operations Suite adds three interconnected workflows to ClientHub:
-
-1. **Proposal Generation & Delivery** — Sales call → multistep proposal page (2-hour delivery) → lead selects tier A/B/C → acceptance triggers automation
-2. **Lead Pipeline Management** — Minimal CRM for tracking prospects through 5 stages (Contacted → Qualified → Proposal Sent → Negotiating → Won/Lost)
-3. **Onboarding Automation** — When lead is marked Won, auto-create client + project with phases copied from chosen offer + configurable payment schedule
-
-**For a solo consultant, this is radically different from team CRMs** (Pipedrive, HubSpot, GoHighLevel). Avoid: territory management, team routing, email automation, role-based access, forecasting rollups, lead scoring algorithms. Instead: **minimal data entry, follow-up reminders based on last-contact date, and seamless handoff from proposal acceptance to project setup.**
-
-**Core insight:** Solo consultants manage long-term relationships across years, not one-time deals closed in 30 days. Pipeline stages should reflect relationship milestones (Contacted, Qualified, Proposal Sent), not sales rep activity (Attempted, Left Message). Follow-ups are "who did I talk to recently?" not "assign task to rep."
-
----
-
-## Table Stakes Features (New v2.0)
-
-Features users expect when adopting a proposal + CRM system. Missing these = product feels incomplete.
-
-### Proposal Generation & Delivery
-
-| Feature | Why Expected | Complexity | Notes |
-|---------|--------------|-----------|-------|
-| Pick client + 1–3 offers, set per-quote prices | Core value: sales call → proposal in 2 hours. Prices set per quote, not from catalog (allows price increases over time without updating service catalog) | Medium | Depends on existing `offers` & `clients` (Phase 5). Quote prices override offer base prices. |
-| Generate public multistep HTML/CSS page | Leads need clickable link, not PDF email. Interactive engagement beats static documents (Qwilr/Proposify standard). Reduces abandonment. | Medium | Responsive, mobile-first, branded with consultant name/logo. No login required. |
-| Multistep flow (intro → pricing tiers → CTA) | Reduces cognitive overload vs. single long page. Step 1: offer overview. Step 2: A/B/C tiers with pricing. Step 3: accept/decline button. | Low | Conditional logic hides irrelevant sections; simple progressive disclosure. |
-| Public acceptance button (no e-signature) | Lead confirms tier choice WITHOUT entering hub. Triggers: timestamp capture + email record + lead status update. | Low | Simple "Accept this offer" button → records accepted_at + accepted_by_email. E-signature deferred (design ready, v1 constraint). |
-| Proposal URL shareable & public | Lead receives link in email, opens in browser, no friction. | Low | Generate unique slug (`/proposal/[uuid]`). No auth. Optionally expires after N days or on acceptance. |
-| Acceptance proof (signer + timestamp) | Documentation for dispute resolution. Downloadable PDF or stored audit record. | Low | Store: accepted_by_name, accepted_by_email, accepted_at, accepted_offer_id. |
-
-### Lead Pipeline
-
-| Feature | Why Expected | Complexity | Notes |
-|---------|--------------|-----------|-------|
-| Pipeline stages: Contacted → Qualified → Proposal Sent → Negotiating → Won/Lost | Core tracking. Each stage requires buyer action, not just rep activity. Termination: Won or Lost. | Low | **Minimal for solo:** 5 stages max. More = data entry overhead. Stages are immutable enums. |
-| Move lead between stages (UI) | Basic pipeline UX. See all leads grouped by stage at a glance. | Low | Dropdown per row (simple) or kanban board (polish). Dropdown sufficient for MVP. |
-| Lead details: name, email, company, phone, last_contact_date, next_action, notes | Minimum context for follow-ups. | Low | Notes = freeform text (call outcomes, concerns, personality notes, next steps). |
-| Lead created manually OR auto-created from proposal send | Manual: import prospects. Auto-create: when proposal sent to unknown email, create lead record automatically. | Low | Auto-create is convenience; manual is fallback. Both supported. |
-| Log activities: calls, emails, meetings, notes | Track interactions without leaving dashboard. Auto-updates last_contact_date. | Low | Activity types: [call, email, meeting, note]. Log date, duration, description. Displayed as feed. |
-
-### Follow-Up Reminders
-
-| Feature | Why Expected | Complexity | Notes |
-|---------|--------------|-----------|-------|
-| Dashboard widget: "Follow up today" sorted by last_contact_date | Solves core pain: "who did I talk to recently that I should check in with?" | Low | Query: WHERE last_contact_date <= TODAY - 7 days AND stage NOT IN (Won, Lost). Red badge. |
-| Proposal stall detector: if Proposal Sent >3 days, no response | Flags silence = red flag for follow-up. | Low | Simple dashboard alert; no email automation (consultant checks dashboard in morning). |
-| Auto-update last_contact_date on activity | Keeps reminders accurate. Prevents "I called them but forgot to log it" drift. | Low | Trigger: on call/email/meeting/note creation OR stage change → update lead.last_contact_date = NOW. |
-
-### Project Auto-Creation (Won → Onboarding)
-
-| Feature | Why Expected | Complexity | Notes |
-|---------|--------------|-----------|-------|
-| On lead.stage = Won: auto-create `client` + `project` with copied phases | Closing automation. Proposal acceptance → instant hub readiness for delivery. | Medium | Requires: chosen offer known, project_offers finalized (Phase 5), 1-4 configurable installments. |
-| Copy offer phases → project phases (modifiable) | Project inherits offer structure but can be customized per client without mutating offer template. | Medium | Phases are modifiable in hub (Phase 1). Creation source logged: "Copied from Offer X on [date]" for audit. |
-| Set payment installments per project (not per offer) | Payment plan configured case-by-case: some 50/50, others 4-part. Allows flexibility. | Medium | Templates: 50/50 (acconto/saldo), 3-part, 4-part, custom. UI: choose template during Won → project creation. |
-| Lead → Client transition: copy email, create token, link to existing client if repeat | Avoid duplicate clients. Allow linking Won lead to existing client (repeat engagement). | Medium | Check email collision. If exists: "Add project to existing client X?" vs. "Create new client". Generate secret token. |
-
----
-
-## Differentiators (New v2.0)
-
-Features that set ClientHub apart from generic proposal software + CRM. Not expected, but valued for solo consultant use case.
-
-| Feature | Value Proposition | Complexity | Notes |
-|---------|-------------------|-----------|-------|
-| Tier-independent offer structure (Signature A/B/C as separate offers) | Each tier has own URL, phases, pricing. A = professional, B = budget—same catalog, different scope. No cloning, no inheritance logic. | Medium | Requires flexible offer builder (drag services between phases), offer status (draft/active/archived). Built in Phase 5. |
-| Proposal phases visible in public page (lead sees what they're buying) | Lead sees not just price, but scope: "4-week branding sprint, 3 revision rounds, monthly retainer". Transparency builds confidence. | Low | Proposal page shows phase names, deliverables summary (text), timeline (start + duration). |
-| Dashboard follow-up list filterable by offer type + stage | "Show all Signature A leads in Negotiating" to spot bottlenecks by tier. | Low | Filter buttons: by offer type, stage, last_contact_date range. Dropdown or toggle buttons. |
-| Activity feed per lead (call notes, email log, meetings, searchable) | Context without leaving dashboard. "Last contact: 2026-05-28, 11am call—timeline concerns". | Medium | Depends on activity logging system. Store type, date, duration, description. Searchable. |
-| Proposal pages branded with consultant info (not generic SaaS) | Proposal is part of sales process; branding reinforces personal brand. | Low | Logo, consultant name, brand colors, professional typography inherited from admin settings. |
-| Email integration hint (design ready, defer to later batch) | Send proposal via dashboard; auto-log email send as activity. | Medium | Deferred per PROJECT.md (v1 constraint). Placeholder: manual copy-paste OK for MVP. |
-
----
-
-## Anti-Features: What NOT to Build (v2.0)
-
-| Anti-Feature | Why Avoid | What to Do Instead |
-|--------------|-----------|-------------------|
-| Multi-user team collaboration, role-based access | Solo consultant is single admin. Team features add auth complexity, sync issues, notification storms. Overhead >> value. | Stay single-admin. Architecture with permission flags but don't build UI/logic. If team joins later, migrate incrementally. |
-| CRM email automation, drip campaigns, email sequences | Solo consultant sends proposals + checks in manually. Automation-heavy workflows are for outbound prospecting funnels (not this use case). Lead generation not in scope. | Keep simple: dashboard reminder = "check in with X". Consultant sends email manually, logs it as activity. |
-| Forecasting with rollups, quota tracking, team capacity planning, territory assignment | These are team sales metrics. Solo consultant cares: "How many leads in pipeline?" and "What's revenue if all Negotiating deals close?" | Simple dashboard: shows total value by stage (e.g., "Negotiating: $45k"), breakdown by offer type. No forecast math. |
-| Lead scoring, MQL → SQL qualification algorithms, scoring rules | Solo consultant qualifies leads manually (call + gut feel). Scoring requires training data and tuning. | Keep manual: stage = Contacted, Qualified, Proposal Sent. "Qualified" is consultant's call. No automation. |
-| Calendar sync, email sync, call recording, Slack/Teams integration | Adds external dependency surface area. Consultant logs calls + emails manually. | Fallback: freeform "Call notes" text field per activity. No attempt to auto-log from email/Slack. |
-| Multi-currency support, tax calculation, invoice generation, accounting system integration | Accounting is out of scope (PROJECT.md locked). Payment tracking only. | Keep simple: amount_accepted in EUR, payment schedule in local currency. No conversion logic or invoicing. |
-| Proposal version control, edit history, detailed audit trail | Overkill for solo consultant. One proposal per client, accept or decline. | Simple: created_at, updated_at timestamps. Accepted version is locked (immutable once accepted_at set). No versioning. |
-| Client can reverse/un-approve acceptance | Creates ambiguity in closing. | Once accepted_at is set, proposal is final. Consultant can move lead back to Proposal Sent if needed. |
-
----
-
-## Feature Dependencies (v2.0)
-
-```
-Proposal Generation:
-  ├─ clients (exists, Phase 1)
-  ├─ projects (exists, Phase 1)
-  ├─ offers (Phase 5: id, name, offer_type [Entry/Signature/Retainer/custom], created_at)
-  ├─ services catalog (Phase 3: id, name, price, duration_days)
-  └─ offer_services (Phase 5: junction table, offers ↔ services)
-
-Lead Pipeline & CRM:
-  ├─ leads table (NEW: id, name, email, company, phone, created_at, last_contact_date, stage, offer_id FK, next_action text)
-  ├─ activities table (NEW: id, lead_id FK, type enum [call/email/meeting/note], log_date, description, duration_minutes)
-  ├─ lead_stage enum (NEW: Contacted, Qualified, Proposal Sent, Negotiating, Won, Lost)
-
-Project Auto-Creation (Won → Onboarding):
-  ├─ leads.stage = Won (from pipeline, not auto-set)
-  ├─ projects (exists, must be creatable via API/trigger)
-  ├─ phases (exists, must be copyable from offer phases)
-  ├─ payments (Phase 5: must support project_id FK, amount, due_date, status)
-  └─ clients.token (exists, Phase 1/4: rotatable secret)
-
-Proposal Public Pages:
-  └─ proposals table (NEW: id, client_id, lead_email, offers [JSON array], created_at, public_url, accepted_at, accepted_by_name, accepted_by_email, accepted_offer_id)
-```
-
-**Critical dependency:** Phase 5's `project_offers` relationship must be finalized. If not, proposal generation cannot proceed. Phase 7 proposal work is blocked by Phase 5 completion.
-
----
-
-## Feature Categorization by Component
-
-### Component 1: Proposal Builder & Public Pages
-
-**Responsibility:**
-- Admin UI: select client, pick 1–3 offers, confirm per-quote pricing, set lead email, generate shareable link
-- Public page: multistep form (intro → tiers → CTA), responsive, no login, branded
-- Acceptance: simple "Accept" button, no e-signature
-- Database: `proposals` table
-
-**Features in scope:**
-- Proposal generation from client + offers + prices
-- Public multistep page with interactive tier selection
-- Conditional phase visibility (show/hide sections based on tier)
-- Acceptance button + timestamp + email capture
-- Auto-create lead on proposal send (if lead email not in DB)
-- Proposal expiry (optional, default: never)
-
-**Database schema:**
-```
-proposals:
-  id UUID PK
-  client_id FK → clients
-  lead_email VARCHAR (recipient)
-  offer_ids JSON array (which offers are included)
-  quote_prices JSON {offer_id: price} (per-quote override)
-  created_at timestamp
-  updated_at timestamp
-  public_url slug
-  accepted_at timestamp nullable
-  accepted_by_name VARCHAR nullable
-  accepted_by_email VARCHAR nullable
-  accepted_offer_id FK nullable (which tier was chosen)
-```
-
-### Component 2: Lead Pipeline & Dashboard
-
-**Responsibility:**
-- Lead table with name, email, company, stage, last_contact_date, notes
-- Dashboard: table or kanban view of all leads grouped by stage
-- Activities: log calls, emails, meetings, notes
-- Follow-up reminder widget: leads not contacted in 7+ days
-
-**Features in scope:**
-- Create/edit/delete leads manually or auto-create from proposal
-- Move lead between stages (dropdown or drag/drop)
-- Log activities: type [call/email/meeting/note], duration, description
-- Auto-update last_contact_date on activity
-- Follow-up reminders: "Follow up today" widget, proposal stall detector
-- Lead notes: freeform text, searchable
-- Filter by offer type, stage, date range
-- Activity feed per lead (searchable)
-
-**Database schema:**
-```
-leads:
-  id UUID PK
-  name VARCHAR
-  email VARCHAR (unique or indexed)
-  company VARCHAR nullable
-  phone VARCHAR nullable
-  stage enum [Contacted, Qualified, Proposal Sent, Negotiating, Won, Lost]
-  offer_id FK → offers nullable (which offer was sent)
-  created_at timestamp
-  last_contact_date date
-  next_action text nullable (next step consultant plans)
-  notes text (accumulated call notes, concerns, personality)
-
-activities:
-  id UUID PK
-  lead_id FK → leads
-  type enum [call, email, meeting, note]
-  log_date timestamp
-  duration_minutes INT nullable
-  description text
-  created_at timestamp
-```
-
-### Component 3: Project Auto-Creation & Onboarding Flow
-
-**Responsibility:**
-- On lead.stage = Won, trigger creation: new client (if not exists), new project, copy phases, set payment schedule
-- UI: lead moves to Won → modal: "Which offer was chosen?" → "Confirm project creation?" → choose payment template → create
-- Result: lead archived, project appears in /admin/projects, client gets dashboard URL
-
-**Features in scope:**
-- Auto-create client from lead details
-- Auto-create project with copied phases
-- Copy phases from offer (modifiable in hub)
-- Payment installments: choose template → creates N payment records
-- Generate client secret token + dashboard URL
-- Optional: link to existing client instead of creating new
-- Notification: "Lead X → Project Y created on [date]"
-
-**Database schema:**
-```
-No new tables needed. Uses existing: clients, projects, phases, payments.
-When lead → Won:
-  1. Check if lead.email in clients table
-  2. If not: create new client, generate secret token
-  3. If yes: ask to link to existing client or create new
-  4. Copy phases from offer_id to new project
-  5. Create N payment records based on chosen template
-  6. Update lead.stage = Won (already set by UI)
-  7. Record: project creation_source = "Lead X, offer Y"
-```
-
----
-
-## MVP Recommendation
-
-### Phase 7 (MVP): Core Proposal Generation + Basic Pipeline
-
-**Priority 1: Must-Have (Launch features)**
-
-1. **Proposal builder UI:** client + offer(s) + per-quote prices → generate public multistep page
-2. **Public proposal page:** Step 1 = offer overview, Step 2 = A/B/C tiers + pricing, Step 3 = "Accept this Offer" CTA
-3. **Acceptance flow:** "Accept" button → timestamp + email capture, marks proposal as accepted
-4. **Lead auto-creation:** when proposal sent to unknown email, auto-create lead record
-5. **Basic lead pipeline:** Contacted, Qualified, Proposal Sent, Negotiating, Won, Lost stages
-6. **Lead dashboard:** table view, move stage via dropdown, lead details sidebar
-7. **Follow-up reminder widget:** leads not contacted in 7+ days, sorted by last_contact_date, dashboard badge
-8. **Activity logging (basic):** create call/email/meeting records, auto-update last_contact_date
-
-**Estimated effort:** 5–7 days (proposal builder UI + public page + lead CRUD + follow-up reminders)
-
-**Launch readiness:** Solo consultant can generate proposal in 2 hours, track lead through pipeline, see follow-up reminders.
-
----
-
-### Phase 8 (Enrichment): Lead Context & Polish
-
-**Priority 2: Features**
-
-1. **Lead notes:** freeform text per lead, searchable
-2. **Activity feed:** display recent activities per lead (call, email, meeting, note), searchable
-3. **Dashboard filters:** by offer type, stage, date range (last_contact_date)
-4. **Proposal stall detector:** flag if Proposal Sent >3 days with no activity
-5. **Lead detail card:** expand to show full context (notes, activities, next_action) without leaving dashboard
-
-**Estimated effort:** 3–4 days
-
-**Value:** Consultant has full context for each lead without switching views.
-
----
-
-### Phase 9+ (Automation & Onboarding): Project Auto-Creation
-
-**Priority 3: Features**
-
-1. **Project auto-creation:** on lead → Won, auto-create client + project with copied phases
-2. **Copy phases from offer:** phases inherit name, duration, deliverables from offer template; modifiable in hub
-3. **Payment installments:** choose template (50/50, 3-part, 4-part, custom) → create N payment records
-4. **Client token generation:** auto-generate secret token, send dashboard URL to client
-5. **Duplicate client check:** if lead.email exists in clients, ask to link or create new
-6. **Won lead notification:** dashboard shows "Lead X → Project Y created", activity logged
-
-**Estimated effort:** 3–4 days
-
-**Value:** Closing automation. Lead acceptance → instant project setup in hub, ready for delivery.
-
----
-
-## Complexity Assessment (Effort & Maintenance)
-
-| Feature | Dev Effort | Maintenance Burden | Deferability | Phase |
-|---------|-----------|-------------------|----------------|-------|
-| Proposal generation (builder UI + logic) | 2–3 days | Low (static) | No—core | 7 |
-| Public multistep page (HTML/CSS template) | 1–2 days | Low (static) | No—core | 7 |
-| Acceptance flow (button + timestamp) | 1 day | Minimal | No—core | 7 |
-| Lead pipeline (CRUD + stage transitions) | 1 day | Low | No—core | 7 |
-| Follow-up reminders (dashboard query) | 4 hours | Minimal | No—core | 7 |
-| Activity logging (calls, emails, meetings) | 1 day | Low | Yes—Phase 8 | 8 |
-| Activity feed (search + timeline) | 1 day | Low | Yes—Phase 8 | 8 |
-| Lead notes + search | 1 day | Low | Yes—Phase 8 | 8 |
-| Dashboard filters (offer type, stage, date) | 1 day | Low | Yes—Phase 8 | 8 |
-| Project auto-creation (trigger + cascade) | 2 days | Medium (error handling) | Yes—Phase 9 | 9 |
-| Payment installments (templates) | 1 day | Low | Yes—Phase 9 | 9 |
-| Client token generation + link | 4 hours | Low | Yes—Phase 9 | 9 |
-| Duplicate client check | 4 hours | Low | Yes—Phase 9 | 9 |
-| Email integration (send proposal, auto-log) | 2–3 days | Medium (provider) | Yes—defer | Later |
-| Multi-user + team features | 3–5 days | Medium-High (roles) | N/A—anti-feature | Never |
-
-**Total Phase 7 MVP:** ~5–6 days  
-**Total Phases 7–9:** ~11–14 days (complete suite)
-
----
-
-## Solo Consultant Design Constraints
-
-### What's Different from Team CRMs
-
-| Constraint | Implication | Design Pattern |
-|-----------|-----------|-----------------|
-| Single admin, no team routing | No "assign to rep" or "owner" field. All leads = Simone. | All leads belong to admin; no ownership concept. No role-based UI. |
-| Relationship-heavy, not transaction-heavy | Leads stay in pipeline for months, not 30 days. | Stage = relationship milestone (Contacted, Qualified, Proposal Sent), not rep activity (Attempted, Left Message, Following Up). |
-| Qualitative follow-up, not automation | "Check in with X, heard timeline concerns" not email sequences. | Notes + activity log, no email automation. Manual send, logged as activity. |
-| Low deal volume (5–15 in flight) | Pipeline visualization doesn't need advanced analytics. | Simple table or 5-column kanban board. No forecasting rollups. |
-| Minimal data entry tolerance | Won't log every call if it takes >3 clicks. | Modal: "Log call → name/date/notes → save" in <10 seconds. |
-| No role-based access | No "manager sees forecast, rep sees pipeline". | Single "admin dashboard" with all data. No permission layers. |
-| No forecasting pressure | Consultant forecasts deal value by feel, not rollup math. | Dashboard shows "Total Negotiating: $45k". That's it. No probability weighting. |
-| Calendar/email often offline (field work) | Email sync is nice-to-have, not must-have. | Fallback: manual entry. No real-time sync requirement. |
-| Accountability is personal, not hierarchical | No "why is this deal stalled?" escalations. | Follow-up reminder = consultant decides action. No automatic escalations. |
-
-### UX Patterns for Solo Consultant
-
-1. **Minimize data entry by default:** Yes/No confirmations, checkboxes, dropdowns. Avoid text fields unless essential.
-2. **Context visible by default:** Open a lead → see last 3 activities, next_action, stage, offer type in one view. No tabs.
-3. **Dashboard as command center:** Lead reminders + upcoming payments + next meetings all visible. No app switching.
-4. **Proposal as shared artifact:** Lead sees what they're buying (phases, deliverables, price). Consultant sees acceptance status + lead email.
-5. **Automation where it reduces clicks:** Accept proposal → auto-create lead. Move to Won → ask once for payment plan, auto-create project. Don't auto-email.
-
----
-
-## Pipeline Benchmark (Reference)
-
-From industry research:
-
-| Metric | Benchmark | Implication for ClientHub |
-|--------|-----------|---------------------------|
-| Typical pipeline stages | 5–7 stages | ClientHub uses 5: Contacted, Qualified, Proposal Sent, Negotiating, Won/Lost. Minimal overhead. |
-| Proposal Sent → Negotiation conversion | 40%+ | Flag stale proposals (>3 days, no activity) in dashboard. |
-| Negotiation → Won conversion | 50%+ | If low, consultant reviews proposal scope or pricing. |
-| Lead follow-up frequency | 8+ touches to close | Activity logging tracks touches (calls, emails, meetings). No automation; manual follow-up. |
-| Typical pipeline review cadence | Weekly or bi-weekly | Consultant checks dashboard daily; reviews pipeline health weekly. |
-| Average deal cycle for consultants | 30–90 days | ClientHub supports long cycles (no pressure to close fast). |
-
----
-
-## Confidence & Sources
-
-| Area | Confidence | Basis | Sources |
-|------|------------|-------|---------|
-| Proposal software features (multistep, acceptance, tiering) | HIGH | Verified with Qwilr, PandaDoc, Proposify; 2026 comparison articles | [Qwilr vs PandaDoc](https://www.proposify.com/blog/qwilr-vs-pandadoc), [PandaDoc vs Proposify vs Qwilr](https://saas-tools.medium.com/pandadoc-vs-proposify-vs-qwilr-which-proposal-tool-is-worth-your-budget-in-2026-8e8339d6ab87), [8 best proposal software](https://www.getaccept.com/blog/proposal-software) |
-| Pipeline stage structure (5–7 stages, Won/Lost termination) | HIGH | Verified with Pipedrive, Capsule CRM, Salesforce; "Proposal Sent → Negotiation → Won" is standard | [Salesforce Pipeline Management](https://www.salesforce.com/sales/pipeline/management/), [CRM Pipeline Stages](https://prospeo.io/s/crm-pipeline-stages), [GoHighLevel Pipeline](https://ecosire.com/blog/ghl-crm-pipeline-management) |
-| Lead follow-up reminders (last_contact_date, 7+ days flagged) | MEDIUM-HIGH | Sourced from Outreach, HubSpot, Nimble best practices; solo consultant context is reasonable inference | [Sales Pipeline Best Practices](https://www.nimble.com/blog/best-practices-of-sales-pipeline-management/), [Outreach Pipeline Management](https://www.outreach.ai/resources/blog/sales-pipeline-management-best-practices) |
-| Solo consultant CRM avoidance of team features | MEDIUM | Sourced from "Best CRM for Solopreneurs" guides; solo preference for simplicity consistent across 3+ sources | [Breakcold: CRM for Consultants](https://www.breakcold.com/blog/crm-for-consultants), [Authencio: CRM for Freelancers](https://www.authencio.com/blog/best-crm-for-consultants-freelancers-guide), [Addtocrm: Best CRM Solopreneurs](https://addtocrm.com/tools/best-crm-for-solopreneurs), [Mimiran: Anti-CRM](https://www.mimiran.com/fun-crm-for-solo-consultants-who-hate-selling/) |
-| Tiered proposal (A/B/C independent offers) | MEDIUM-HIGH | Verified via multiple consulting pricing guides; "3 tiers ideal" is consensus. Independent offers is ClientHub-specific. | [Mercury: Pricing Strategy](https://mercury.com/blog/pricing-strategy-consulting), [Ignition: Tiered Pricing](https://www.ignitionapp.com/blog/tiered-pricing-strategy-for-professional-services-proposal-templates), [Consulting Success: Consulting Rates](https://www.consultingsuccess.com/consulting-rates) |
-| Multi-step form engagement patterns | HIGH | Verified with Heyflow, Optimonk, HubSpot research; form completion rates improve with progressive disclosure | [Instapage: Multi-Step Forms](https://instapage.com/blog/multi-step-forms), [HubSpot: Multi-Step Forms](https://blog.hubspot.com/marketing/multi-step-forms), [Webstacks: Multi-Step Form Examples](https://www.webstacks.com/blog/multi-step-form) |
-| Proposal acceptance automation (→ project creation) | MEDIUM | Sourced from Anchor, Estimate Rocket, Monograph workflows. ClientHub implementation is custom but pattern is established. | [Sayanchor: Proposal Acceptance](https://www.sayanchor.com/post/proposal-acceptance-guide), [Monograph: Build, Send, Sign](https://monograph.com/blog/build-send-and-sign-proposals-with-pipeline), [DocuSign: Workflow Automation](https://www.docusign.com/blog/workflow-automation-electronic-signatures) |
-
----
-
-## Open Questions for Later Phases
-
-1. **Email integration:** Should proposals be sent via dashboard integration, or manual copy-paste? (Deferred to Phase 10+)
-2. **Proposal expiry:** Should proposals auto-expire after N days, or stay open indefinitely? (MVP: no expiry)
-3. **Lead de-duplication:** If lead email is already in clients table, how should system handle it? (MVP: manual check; Phase 9+ auto-detect)
-4. **Activity type richness:** Should activities include location, participant names, sentiment tags? (MVP: basic type + notes; Phase 8 can enhance)
-5. **Proposal versioning:** Can consultant send multiple proposals to same lead? (MVP: yes, same lead.email + new proposal record)
-6. **Payment plan customization:** Can consultant define custom installment schedules, or only use templates? (MVP: templates; Phase 9 can add custom)
-7. **Lead archive vs. delete:** When lead is Won → converted to client/project, should lead record stay in DB for history? (Recommendation: keep for audit trail; mark archived or moved_to_project_id)
-
----
-
-## Appendix: Frequently Asked Questions
-
-**Q: Why no e-signature in MVP?**  
-A: Design is ready (CLAUDE.md notes it as deferred). A simple "Accept" button + timestamp is sufficient proof of acceptance for solo consultant use case. E-signature (DocuSign, Stripe Sign) adds external dependency and cost; defer unless client explicitly requests.
-
-**Q: Should proposals auto-expire?**  
-A: No, not in MVP. Solo consultant may send proposal Monday, follow up Thursday, acceptance Friday. Expiry is team-sales friction (forces re-quote). Keep simple: accepted_at = null means still open.
-
-**Q: Can a lead be in two stages at once?**  
-A: No. Stage is singular immutable state at any moment. If second proposal sent to same lead: either (a) create new lead record (same email, add suffix "2"), or (b) update same lead.stage to "Proposal Sent" again. Option (b) is simpler; stage can repeat; last_contact_date updates on each proposal send.
-
-**Q: Should activities auto-log from email/Slack?**  
-A: No, not in MVP. Adds external dependency surface. Fallback: consultant manually logs calls/emails as activities in <10 seconds. Acceptable for solo consultant volume (5–15 leads).
-
-**Q: What if lead email already exists in clients table?**  
-A: Phase 9 auto-detection: when moving lead to Won, check if lead.email in clients. If yes, ask: "Link to existing client X (repeat engagement)?" or "Create new client". Prevents duplicate records.
-
-**Q: Can phases be reordered after project creation?**  
-A: Yes. Phases are copied from offer at project creation time, but project phases are modifiable in hub (Phase 1, already built). Offer template is never mutated. Studio-grade immutability.
-
-**Q: What's the payment flow after Won → project creation?**  
-A: Consultant chooses payment template (50/50, 3-part, 4-part, custom) during Won → project creation modal. System creates N records in `payments` table with due_dates calculated from project start_date. Client sees payment schedule in hub dashboard (Phase 1, already built). No invoicing or collection automation (out of scope, PROJECT.md locked).
-
-**Q: Can consultant change their mind after accepting a proposal?**  
-A: If consultant moves lead back to Proposal Sent or Negotiating (after accepting and creating project), the original accepted_proposal record remains immutable. Project can be deleted/archived if needed, but proposal acceptance is final. This matches real-world: once accepted, consultant can't un-close a deal.
-
----
-
-**End of FEATURES_v2.0.md**
diff --git a/.planning/research/PITFALLS.md b/.planning/research/PITFALLS.md
index aadfe57..edb05fd 100644
--- a/.planning/research/PITFALLS.md
+++ b/.planning/research/PITFALLS.md
@@ -1,177 +1,1269 @@
-# Pitfalls — ClientHub Freelancer Client Portal
+# Domain Pitfalls: Business Operations Suite (v2.0) — Adding to Production ClientHub
 
-**Domain:** Freelancer client portal with secret-link access, solo developer, Vercel deploy
-**Researched:** 2026-05-09
-**Confidence:** HIGH
+**Project:** ClientHub v2.0 (Business Operations Suite)  
+**Context:** Adding catalog migration, offer builder, public quotes, and CRM to live hub.iamcavalli.net  
+**Researched:** 2026-06-10  
+**Overall confidence:** HIGH (domain-specific integration pitfalls verified against production data constraints)
 
 ---
 
-## Critical Pitfalls
+## Executive Summary
 
-### 1. Secret Links That Are Guessable or Enumerable
+Adding a Business Operations Suite to a production client portal with real data is riskier than building from scratch. The pitfalls cluster in four areas:
 
-**What goes wrong:** If client tokens are generated from names, sequential IDs, or short strings, they can be enumerated. `/client/mario-rossi` or `/client/3` are not secrets.
+1. **Schema consolidation (Catalog):** Merging two parallel service tables without breaking existing quote_items referential integrity
+2. **Template-to-instance copy semantics (Offers):** Offer phases copied to project phases at "Won" can mutate templates or copy partially
+3. **Optimistic UI state management (Drag-drop):** Frontend and server get out of sync on sort_order conflicts in concurrent edits
+4. **Security + workflow atomicity (Public Quotes, CRM):** Token enumeration leaks pricing; double-click creates duplicate clients; partial failures leave inconsistent state
+
+Each pitfall has concrete prevention strategies designed for solo-consultant use (not team-based CRM) and production migration constraints (Data Safety rule: never delete/truncate clients, projects, payments, phases).
+
+---
+
+## CRITICAL PITFALLS (Rewrites / Data Loss Risk)
+
+### Pitfall 1: Service Catalog Consolidation Breaks Existing Quotes
+
+**What goes wrong:**
+
+You have two service tables with different purposes:
+- `service_catalog` (21 rows): operational costs, used by quote_items
+- `offer_services` (35 rows): marketing pricing, used by offer_micro_services
+
+You want a unified `services` table. Two bad approaches:
+
+**Approach A (Naive consolidation):**
+1. Create new `services` table
+2. INSERT all rows from both catalogs
+3. Update quote_items to point to new services by name matching
+4. DROP old tables
+
+**Problem:** Name matching is fragile (typos, duplicates). Foreign key constraint fails if a quote_item references a service that doesn't exist yet. Orphaned rows. Production is down.
+
+**Approach B (Copy-paste merge):**
+1. Manually consolidate the tables in SQL
+2. Delete old tables after data looks "right"
+3. Discover months later that quote_items have NULL service_id or point to wrong service
+4. prices are wrong (offer_services had different prices than service_catalog)
+5. Historical quotes can't be regenerated
+
+**Why it happens:**
+
+Two tables evolved independently. Offer services have transformation_description + price (marketing messaging). Catalog services have unit_price (cost). You conflate them, lose the distinction. Also, you can't tell which service_catalog row corresponds to which offer_service row — there's no mapping.
+
+**Consequences:**
+
+- Quote items become orphaned: `quote_items.service_id` points to deleted service
+- `projects.accepted_total` calculations fail or show wrong values
+- Client dashboard payment status breaks (can't compute from broken quote_items)
+- Audit trail destroyed: can't reconstruct what was offered in old quotes
+- Data Safety violation: quote_items become unreliable, can't be trusted for billing
+- Rollback impossible: old tables are gone
 
 **Prevention:**
-- Generate tokens as cryptographically random UUIDs (v4) or nanoid (21 chars / ~126 bits of entropy)
-- Never derive from name, company, or sequential ID
-- Never log or display full tokens in admin analytics
 
-**Warning signs:** Client slug contains the client's name. Token under 20 characters. Link can be reconstructed from info the client already knows.
+1. **Keep both tables; add a new unified `services` table alongside them:**
+   ```
+   Phases:
+   - Phase A (Expand): Add services table, backfill both catalogs into it
+   - Transition period: Old code reads service_catalog, new code reads services
+   - Phase B (Contract): After 2-3 weeks, drop old tables only if safe
+   ```
 
-**Phase mapping:** Phase 1 — data model + routing. Cannot be retrofitted after links are distributed.
+2. **Create explicit migration mapping:**
+   ```typescript
+   // services table structure:
+   // id, name, unit_price, source_type (catalog | offer), source_id, created_at
+   
+   // Backfill from catalog:
+   INSERT INTO services (id, name, unit_price, source_type, source_id)
+   SELECT nanoid(), name, unit_price, 'catalog', id FROM service_catalog;
+   
+   // Backfill from offer_services (rename if duplicates):
+   INSERT INTO services (id, name, unit_price, source_type, source_id)
+   SELECT nanoid(), 
+          CASE WHEN EXISTS(SELECT 1 FROM services WHERE name = offer_services.name)
+               THEN offer_services.name || ' (Offer)'
+               ELSE offer_services.name
+          END,
+          price, 'offer', id 
+   FROM offer_services;
+   ```
+
+3. **Never update quote_items.service_id immediately:**
+   - Leave quote_items pointing to old service_catalog
+   - New quote code writes to services table
+   - Existing quotes remain readable (backward compatible)
+   - Backfill quote_items in small batches after validation:
+     ```sql
+     UPDATE quote_items 
+     SET service_id = (SELECT id FROM services WHERE source_id = quote_items.service_id AND source_type = 'catalog')
+     WHERE service_id IS NOT NULL AND id IN (
+       SELECT id FROM quote_items ORDER BY id LIMIT 100
+     );
+     ```
+
+4. **Validation before contract phase:**
+   - Query: `SELECT COUNT(*) FROM quote_items WHERE service_id NOT IN (SELECT id FROM service_catalog)` — should be 0
+   - Checksum: SUM(subtotal) in quote_items == SUM(accepted_total) per project — must match
+   - Test quote regeneration: pick 5 old projects, regenerate quote, prices must match original
+
+5. **Immutable snapshot for historical quotes:**
+   - Store `quote_snapshot: JSONB` in project_offers row
+   - This is a frozen copy of what was offered (prices, services, terms)
+   - New code reads from services; historical quote reads from snapshot
+   - Guarantees: old quotes never change, even if catalog prices change
+
+**Detection:**
+- Query for orphaned quote_items: `SELECT COUNT(*) FROM quote_items WHERE service_id IS NOT NULL AND service_id NOT IN (SELECT id FROM service_catalog)`
+- Detect price mismatches: `SELECT project_id, SUM(subtotal), projects.accepted_total FROM quote_items JOIN projects USING(project_id) GROUP BY project_id HAVING SUM(subtotal) != projects.accepted_total`
+- Test suite: regenerate quote on historical project, compare prices to original
+
+**Phase to address:** Phase 7 (Catalog & Offers, specifically "Consolidate catalogs") — design migration BEFORE code changes
 
 ---
 
-### 2. Client API Exposes Admin Data (Hidden in UI Only)
+### Pitfall 2: Template-to-Instance Copy Mutates Template (Offer Phases Bug)
 
-**What goes wrong:** Developers fetch all client data and conditionally render fields. A technical client opens DevTools and sees the full quote breakdown — the exact thing the product prevents.
+**What goes wrong:**
+
+When a lead is won, you copy offer phases into project phases. If you copy by reference instead of by value:
+
+**Scenario A (Shallow copy):**
+```typescript
+// Offer phases structure:
+const offer = {
+  micros: [
+    { id: 'micro1', title: 'Phase 1', tasks: [{ title: 'Audit' }] }
+  ]
+};
+
+// Bad: shallow copy
+const copy = { ...offer };
+copy.micros[0].tasks[0].title = 'Updated Audit';
+
+// Result: offer.micros[0].tasks[0].title is NOW 'Updated Audit' too!
+```
+
+Admin wins a deal, copies phases, edits a project task (e.g., changes from "5 deliverables" to "3 deliverables"). Next time you use the same offer for another lead, the wrong phase structure is copied — the template has been mutated.
+
+**Scenario B (Partial copy on retry):**
+User clicks "Mark as Won," which triggers:
+```
+1. Copy offer.micros → project.phases
+2. Copy offer.services → project.tasks/deliverables
+3. Mark lead.status = 'won'
+```
+
+Network times out or browser tab closes before success page. Admin clicks "Mark as Won" again (thinking it didn't work). Now:
+- `copy.micros → project.phases` inserts new phases (duplicates)
+- Orphaned old tasks from first copy remain
+- Project has 6 phases instead of 3
+
+**Scenario C (Copy at wrong level):**
+You have `offer_micros` (marketing tiers) and `offer_services` (actual deliverables). When you copy, do you copy micros as phases? As phase groups? You're confused about the mapping, so you copy wrong level and tasks don't appear in project.
+
+**Why it happens:**
+
+JavaScript shallow copy is the default. `{...obj}`, `.slice()`, `Object.assign()` all copy references to nested objects. Offer structure is complex (macro → micro → services), and you don't have a clear mapping to project (phases → tasks → deliverables). So you guess the copy strategy.
+
+Also: "Win" action is multi-step (create project, copy phases, copy tasks, create payments). If step 2 fails, step 1 succeeded (orphaned project). No atomic transaction, no idempotency key.
+
+**Consequences:**
+
+- Same offer structure changes unpredictably across different projects
+- Admin sees phase structures diverge: "Why does project A have 5 tasks but project B (same offer) has 6 tasks?"
+- Audit trail breaks: can't reconstruct what was actually sold
+- Client dashboard shows incomplete phases (missing tasks/deliverables)
+- project.accepted_total becomes unreliable if phase structure is different
 
 **Prevention:**
-- Define two distinct data shapes: `ClientView` and `AdminView`
-- Client API routes (`/api/c/[token]/`) return `ClientView` only — enforced server-side, not in the UI
-- `accepted_total` goes on the `clients` row. Client API never queries `quote_items`
 
-**Warning signs:** Client API response includes `lineItems` filtered in the frontend. "Client sees only total" enforced with `display: none`.
+1. **Define hierarchies explicitly (CRITICAL):**
+   
+   **Offer side (marketing):**
+   - offer_macros: "Signature", "Entry", "Retainer" (tier names)
+   - offer_micros: "Signature A", "Signature B", "Signature C" (tier variations)
+   - offer_services: individual deliverables (what client receives)
+   - offer_micro_services: junction (which services in which tier)
+   
+   **Project side (execution):**
+   - projects: top-level
+   - phases: workstreams/timeline ("Discovery", "Design", "Delivery")
+   - tasks: work items within phase ("Competitor audit", "Wireframes")
+   - deliverables: client-approvable outputs ("Audit report", "Wireframe set")
+   
+   **Mapping (at "Won"):**
+   - Offer tier (micro) doesn't equal project phase
+   - Offer services map to project tasks OR deliverables (decide: task or deliverable is the copy target?)
+   - Simplest: each offer_service → 1 task in phase 1, all tasks created at once
 
-**Phase mapping:** Data model and API shape — Phase 1.
+2. **Use structuredClone for deep copy:**
+   ```typescript
+   // Instead of shallow spread
+   const deepCopy = structuredClone(offer);
+   deepCopy.micros[0].tasks[0].title = 'X'; // offer is unaffected
+   ```
+
+3. **Never copy from application layer; let database do it atomically:**
+   ```typescript
+   async function copyOfferToProject(offerId, projectId) {
+     return await db.transaction(async (tx) => {
+       // Fetch offer with all nested data
+       const offer = await tx.query.offer_micros.findMany({
+         where: eq(offer_micros.macro_id, offerId),
+         with: {
+           services: true,
+           projectOffers: true
+         }
+       });
+       
+       // Create new phases (1 per offer_micro)
+       const newPhases = [];
+       for (const micro of offer) {
+         const phase = await tx.insert(phases).values({
+           project_id: projectId,
+           title: micro.public_name,
+           sort_order: micro.sort_order
+         }).returning();
+         newPhases.push(phase);
+         
+         // Create tasks (1 per service in this micro)
+         for (const service of micro.services) {
+           const task = await tx.insert(tasks).values({
+             phase_id: phase.id,
+             title: service.name,
+             sort_order: 0
+           }).returning();
+           
+           // Create deliverable from service
+           await tx.insert(deliverables).values({
+             task_id: task.id,
+             title: service.name,
+             description: service.transformation_description
+           });
+         }
+       }
+       
+       return newPhases;
+     });
+   }
+   ```
+   
+   Single transaction = all-or-nothing. No partial copy.
+
+4. **Immutable flag on templates:**
+   ```sql
+   ALTER TABLE offer_micros ADD COLUMN is_template BOOLEAN NOT NULL DEFAULT TRUE;
+   -- Constraint: if is_template, no UPDATE allowed on title/description
+   -- Only inserts/deletes, no mutations
+   ```
+
+5. **Idempotency key prevents double-copy:**
+   ```typescript
+   // CRM leads table:
+   // id, email, status, offer_id, idempotency_key (unique), project_id
+   
+   async function markLedAsWon(leadId, idempotencyKey) {
+     return await db.transaction(async (tx) => {
+       // Check: is this key already processed?
+       const existing = await tx.select().from(leads)
+         .where(eq(leads.idempotency_key, idempotencyKey));
+       
+       if (existing.project_id) {
+         return existing; // Already won, return same project
+       }
+       
+       // First time: create project + copy phases
+       const project = await tx.insert(projects).values({
+         client_id: lead.client_id,
+         name: lead.email
+       }).returning();
+       
+       await copyOfferToProject(lead.offer_id, project.id);
+       
+       // Mark lead won
+       await tx.update(leads)
+         .set({ status: 'won', project_id: project.id })
+         .where(eq(leads.id, leadId));
+       
+       return project;
+     });
+   }
+   ```
+
+6. **Validation: count check after copy:**
+   ```typescript
+   const offer = await getOfferCounts(offerId);
+   const project = await getProjectCounts(projectId);
+   
+   // Assert counts match
+   assert(offer.microCount === project.phaseCount);
+   assert(offer.serviceCount === project.taskCount);
+   assert(offer.serviceCount === project.deliverableCount);
+   ```
+
+**Detection:**
+- Query: `SELECT COUNT(DISTINCT phase_count) FROM projects WHERE source_offer_id = 'offer_123'` — should be 1 (all instances have same structure)
+- Check: `SELECT project_id, COUNT(tasks) as task_count FROM projects JOIN phases USING(project_id) JOIN tasks USING(phase_id) GROUP BY project_id` — all projects from same offer should have identical task_count
+- Test: regenerate offer phases in a test project, compare structure to production instance
+
+**Phase to address:** Phase 7 (Catalog & Offers) for offer structure design; Phase 9 (CRM Won automation) for copy mechanism — finalize mapping BEFORE code
 
 ---
 
-### 3. Data Loss from Vercel Filesystem / In-Memory Storage
+### Pitfall 3: Public Quote Page Leaks Pricing via Token Enumeration
 
-**What goes wrong:** Vercel serverless functions are stateless. File writes to local filesystem and in-memory state are lost between invocations. SQLite on disk silently vanishes after cold start. Bug only manifests in production.
+**What goes wrong:**
+
+You create `/quote/[quoteToken]` (public URL, can be shared with prospects). Quote token is nanoid (21 chars, ~122 bits entropy). An attacker:
+
+1. Brute-forces quote tokens: 10 guesses/sec × 86400 sec/day ≈ 864K guesses/day
+2. After a few days, has enumerated all active quotes
+3. Builds pricing database: "This consultant charges €2500 for personal branding tier 1, €5000 for tier 2"
+4. Shares with competitors or uses against you in negotiations
+
+Also: if quote token leaks to wrong recipient (forwarded email, Slack channel, browser history), unauthorized access to pricing meant for one prospect only.
+
+**Why it happens:**
+
+- nanoid 21 chars is only ~122 bits entropy — decent for single-use tokens but weak against coordinated brute-force
+- You're not validating WHO requested the quote, just that token is valid (no email check, no IP restriction)
+- No rate limiting, so attacker can guess 1M tokens per day
+- No expiration, so old tokens are forever valid
+- No audit trail, so you don't know if a quote was accessed by wrong person until much later
+
+**Consequences:**
+
+- Pricing intelligence leaks to competitors
+- Confidential pricing becomes public (prospect #1 knows what prospect #2 was charged)
+- Client feels exposed/unprofessional (pricing is discoverable)
+- Legal risk: if quote was confidential, unauthorized access is a breach
+- Competitive disadvantage: prices visible to all competitors
 
 **Prevention:**
-- External persistent DB from day one: Neon (Postgres free tier)
-- Never write to `fs` for persistent data on Vercel
-- Validate persistence in the first production deploy
 
-**Warning signs:** Project stores data in a `data/` JSON directory. SQLite without a remote adapter. Data changes in one request not visible in the next.
+1. **Token security hardening:**
+   - Use `nanoid(32)` or `nanoid(64)` instead of 21 (increases entropy from ~122 bits to ~190 bits)
+   - Add expiration: `quote_token_expires_at` (default 7 days, can be extended manually)
+   - Add activation state: token only becomes valid after admin explicitly sends it to contact
+   - Don't auto-generate tokens on quote creation; generate on-demand when admin clicks "Send quote"
 
-**Phase mapping:** Day-one infrastructure decision — Phase 1, before any real data is entered.
+   ```typescript
+   // Quotes table:
+   // id, client_id, status (draft | sent | accepted | rejected)
+   // token (nullable until sent), token_expires_at, sent_to_email, created_at, sent_at
+   
+   const generateQuoteToken = () => nanoid(32);  // ~190 bits
+   
+   async function sendQuote(quoteId, contactEmail) {
+     return await db.update(quotes).set({
+       token: generateQuoteToken(),
+       token_expires_at: addDays(new Date(), 7),
+       status: 'sent',
+       sent_to_email: contactEmail,
+       sent_at: new Date()
+     }).where(eq(quotes.id, quoteId));
+   }
+   ```
+
+2. **Access control: email + token required:**
+   - Public page requires BOTH token AND email in URL or form
+   - Email validates that the person accessing is the intended recipient
+   - Endpoint signature: `/api/quote?token=[token]&email=[email]` (both required)
+   - Server validates: token belongs to quote AND quote.sent_to_email matches email
+   
+   ```typescript
+   GET /api/quote?token=...&email=contact@prospect.com
+   
+   const quote = await db.select().from(quotes)
+     .where(and(
+       eq(quotes.token, token),
+       eq(quotes.sent_to_email, email),
+       gt(quotes.token_expires_at, new Date()),
+       eq(quotes.status, 'sent')
+     ));
+   
+   if (!quote) return 401; // Unauthorized
+   ```
+
+3. **Rate limiting (prevents brute-force):**
+   - Max 3 views per token per minute (blocks scanning)
+   - Max 10 failed attempts per IP per hour (blocks enumeration)
+   - After rate limit hit, log alert: "Possible quote enumeration detected from IP X"
+
+   ```typescript
+   const rateLimitKey = `quote:${token}:views`;
+   const views = await redis.incr(rateLimitKey);
+   if (views > 3) {
+     return 429; // Too Many Requests
+   }
+   ```
+
+4. **Pricing visibility rules (CRITICAL CONSTRAINT):**
+   - Public quote page shows: client name, phase names, deliverables, TOTAL PRICE ONLY
+   - Per-service prices: NEVER visible (existing LOCKED constraint)
+   - `quote_items` table: NEVER serialized to public API response
+   - Server-side validation: assert response.quote_items === undefined before sending
+
+   ```typescript
+   // WRONG:
+   const quote = await db.select().from(quotes)
+     .where(eq(quotes.token, token));
+   return NextResponse.json(quote);  // Includes quote_items!
+   
+   // RIGHT:
+   const quote = await db.select({
+     id: quotes.id,
+     clientName: quotes.client_name,
+     totalPrice: quotes.total_price,  // sum only
+     phases: phases.title
+     // Do NOT select quote_items
+   }).from(quotes)
+     .where(and(...))
+     .leftJoin(phases, eq(phases.quote_id, quotes.id));
+   return NextResponse.json(quote);
+   ```
+
+5. **Audit trail for access:**
+   - Log every quote page view: `quote_views(quote_id, accessed_at, email, ip_hash, user_agent)`
+   - Alert admin if quote accessed from suspicious location (wrong country, multiple IPs, after hours)
+   - At minimum: count views per token, alert if >20 views (suggests enumeration)
+
+   ```typescript
+   await db.insert(quote_views).values({
+     quote_id: quote.id,
+     accessed_at: new Date(),
+     email: params.email,
+     ip_hash: hashIp(req.ip),
+     user_agent: req.headers['user-agent']
+   });
+   ```
+
+6. **Expiration enforcement:**
+   - Public page rejects expired tokens (7 days default)
+   - Admin can extend expiration if needed (e.g., "Give prospect 2 more weeks")
+   - Shows user: "This quote expired on [date]. Contact sales to request an updated quote."
+
+**Detection:**
+- Test with wrong email: `GET /api/quote?token=X&email=wrong@email.com` should return 401
+- Test after expiration: manually set token_expires_at to past date, should return 401
+- Test brute force: make 10 requests/second, should hit rate limit
+- Audit logs: search for tokens with >20 views, >5 unique emails, multiple IPs
+- Schema audit: verify quote_items not in public API response (code review)
+
+**Phase to address:** Phase 8 (Public Quote Pages) — implement all security controls IN PARALLEL with feature, not after
 
 ---
 
-### 4. Over-Engineering Before the First Client Uses It
+## MODERATE PITFALLS (Major Refactor / Data Inconsistency)
 
-**What goes wrong:** Building the Claude onboarding flow and quote generator before a single client has opened their dashboard. Real clients still managed via email while the portal is "almost ready."
+### Pitfall 4: Drag-and-Drop Sort Order Race Condition
+
+**What goes wrong:**
+
+Admin drags service B above service A in an offer phase, frontend sends `{ serviceId: B, sort_order: 1 }`. Meanwhile, another tab deletes service A, which auto-shifts all sort_orders down. The update succeeds, but now B and A have conflicting sort_orders: `[1, 1, 3, 4]`.
+
+Or: two browser tabs open the same offer. Admin in tab 1 drags service B up. Admin in tab 2 drags service C down. Both send updates concurrently. Server processes last write: tab 2's update. Tab 1's reorder is lost. Admin refreshes, sees different order.
+
+**Why it happens:**
+
+- Optimistic UI updates frontend immediately, sends async update to server
+- If server read-replica isn't synced, or if concurrent write happened between read and write, update applies to wrong baseline
+- `sort_order` is a simple integer with no version/conflict detection
+- No idempotency: if user clicks drag twice (accidental double-click), two updates sent
+
+**Consequences:**
+
+- Phase services display in wrong order intermittently (depends on which replica you hit)
+- Admin refreshes page, order changes again
+- After 3-4 drags by different admins, sort_orders become nonsensical: `[1, 3, 2, 5, 4]`
+- Clients see different phase structure depending on page cache; trust breaks
+- Audit: "Why did phase structure change?" — no record of who dragged what when
 
 **Prevention:**
-- Hard success criterion for Phase 1: one client link is shareable and works
-- Phase 1 ships read-only client dashboard only
-- Collect direct feedback from one real client before adding features
 
-**Warning signs:** >2 weeks pass without a shareable client link. Claude integration started before admin edit UI exists.
+1. **Explicit versioning (optimistic locking):**
+   ```sql
+   ALTER TABLE offer_phases ADD COLUMN version INTEGER NOT NULL DEFAULT 0;
+   -- Every UPDATE increments version
+   ```
+   
+   ```typescript
+   // Update only if version matches:
+   const result = await db.update(offer_phases)
+     .set({
+       sort_order: newSortOrder,
+       version: sql`version + 1`
+     })
+     .where(and(
+       eq(offer_phases.id, phaseId),
+       eq(offer_phases.version, expectedVersion)  // Must match
+     ))
+     .returning();
+   
+   if (!result.length) {
+     // Version mismatch: conflict
+     return { status: 409, message: 'Offer changed, please refresh' };
+   }
+   ```
+   
+   Frontend stores `version` alongside phase data:
+   ```typescript
+   const [phases, setPhases] = useState(initialPhases); // includes version
+   
+   const onDrag = async (newOrder) => {
+     const oldVersion = phases[0].version;
+     setPhases([...newOrder]); // Optimistic
+     
+     const response = await updatePhase({
+       sort_order: newOrder[0].sort_order,
+       version: oldVersion
+     });
+     
+     if (response.status === 409) {
+       // Conflict, refresh
+       const refreshed = await getPhase();
+       setPhases(refreshed);
+       showNotification('Offer changed, reloaded latest');
+     }
+   };
+   ```
 
-**Phase mapping:** Enforced by roadmap phase ordering.
+2. **Server-side sort_order recomputation (no trusting client):**
+   - Don't trust client's sort_order value — recompute from actual order
+   - User says: "Move service B before service C"
+   - Server fetches all services in phase, recomputes all sort_orders atomically
+   
+   ```typescript
+   async function reorderService(phaseId, serviceId, newPosition) {
+     return await db.transaction(async (tx) => {
+       // Fetch all services in phase, ordered by sort_order
+       const services = await tx.select()
+         .from(phase_services)
+         .where(eq(phase_services.phase_id, phaseId))
+         .orderBy(phase_services.sort_order);
+       
+       // Find service and move to newPosition
+       const serviceIndex = services.findIndex(s => s.id === serviceId);
+       if (serviceIndex === -1) return null;
+       
+       const [movedService] = services.splice(serviceIndex, 1);
+       services.splice(newPosition, 0, movedService);
+       
+       // Recompute all sort_orders atomically
+       for (let i = 0; i < services.length; i++) {
+         await tx.update(phase_services)
+           .set({ sort_order: i })
+           .where(eq(phase_services.id, services[i].id));
+       }
+       
+       return services;
+     });
+   }
+   ```
+
+3. **Optimistic updates with reconciliation:**
+   ```typescript
+   const [optimisticPhases, setOptimisticPhases] = useState(phases);
+   const [serverVersion, setServerVersion] = useState(phases.version);
+   
+   const onDrag = async (reordered) => {
+     setOptimisticPhases(reordered); // Instant feedback
+     
+     const response = await updatePhase({
+       order: reordered.map(s => s.id),
+       version: serverVersion
+     });
+     
+     if (response.status === 409) {
+       // Refresh from server
+       const current = await getPhase();
+       setOptimisticPhases(current.services);
+       setServerVersion(current.version);
+     } else {
+       setServerVersion(response.version);
+     }
+   };
+   ```
+
+4. **Serialization: queue drag actions (nuclear option):**
+   - Queue drag-and-drop actions, process one at a time
+   - User feels slight slowdown if dragging fast
+   - Guarantees no concurrent updates
+
+   ```typescript
+   const dragQueue = [];
+   let dragging = false;
+   
+   const enqueueReorder = async (action) => {
+     dragQueue.push(action);
+     if (dragging) return;
+     
+     dragging = true;
+     while (dragQueue.length > 0) {
+       const action = dragQueue.shift();
+       await reorderService(action);
+     }
+     dragging = false;
+   };
+   ```
+
+**Detection:**
+- Test concurrent updates: open offer in 2 tabs, drag in tab 1, drag in tab 2 simultaneously, save both
+- Inspect database: `SELECT sort_order FROM offer_phase_services WHERE offer_phase_id = ? ORDER BY sort_order` — should be 0..n-1 with no gaps
+- Check logs: query for 409 Conflict responses (indicates version mismatch handled correctly)
+- Audit query: "Who dragged what when?" — log reorder actions with user/timestamp
+
+**Phase to address:** Phase 7 (Offer Builder — Drag & Drop) — implement versioning BEFORE UI ships, not after bugs appear
 
 ---
 
-### 5. Token Is the Primary Key (Unrotatable)
+### Pitfall 5: CRM "Win" Automation — Double-Click Creates Two Clients
 
-**What goes wrong:** A client forwards their link. The link appears in a screenshot. There is no mechanism to rotate without losing data or breaking bookmarks. Worse if token = primary key: rotation requires a migration.
+**What goes wrong:**
+
+Admin clicks "Mark as Won" on a lead, which triggers multi-step automation:
+```
+1. Create client (email, name)
+2. Create project (client_id)
+3. Copy offer phases → project phases
+4. Create 1-4 payments
+5. Mark lead.status = 'won'
+```
+
+User's connection times out, browser tab closes, or page doesn't load success feedback. Admin thinks it didn't work, clicks "Mark as Won" again. Now:
+- Two clients created (same email)
+- Two projects created
+- Two payment schedules
+- Lead shows as "won" (confusing)
+
+Billing chaos: which client to invoice? Which payment schedule is real? Can't issue refund without knowing which one.
+
+**Why it happens:**
+
+No idempotency key. The "Win" action is a non-idempotent POST that should be safe to retry but isn't. Network is unreliable — timeouts are normal. You can't tell if the first request succeeded or failed just by timeout. Multi-step workflows can partially fail (client creation succeeds, project creation fails), leaving inconsistent state.
+
+**Consequences:**
+
+- Duplicate clients in system, different tokens (prospect receives two dashboard links)
+- Duplicate projects and payments, confusing admin dashboard KPIs
+- CRM status shows client as "won" but two projects exist (audit trail broken)
+- Refund process impossible: which payment to reverse?
+- Data Safety violation: can't trace which project is authoritative
 
 **Prevention:**
-- Data model: stable internal UUID as PK; secret token is a separate, independently updatable field
-- Build "Regenerate link" in admin area during Phase 2 — it's a single field UPDATE
-- Overwriting the token field is sufficient to invalidate the old link
 
-**Warning signs:** Token is used as PK of the client record. No admin affordance to regenerate a link.
+1. **Idempotency key pattern (CRITICAL for all multi-step workflows):**
+   ```sql
+   -- CRM leads table:
+   -- id, email, status, offer_id, idempotency_key (nanoid, unique), 
+   -- client_id (nullable), project_id (nullable), created_at
+   
+   ALTER TABLE crm_leads ADD COLUMN idempotency_key TEXT UNIQUE NOT NULL;
+   ```
+   
+   ```typescript
+   async function markLedAsWon(leadId) {
+     const lead = await db.select().from(crm_leads)
+       .where(eq(crm_leads.id, leadId));
+     
+     const idempotencyKey = lead.idempotency_key;
+     
+     return await db.transaction(async (tx) => {
+       // Check: is this key already processed?
+       const existing = await tx.select().from(crm_leads)
+         .where(and(
+           eq(crm_leads.idempotency_key, idempotencyKey),
+           isNotNull(crm_leads.client_id)
+         ));
+       
+       if (existing.length > 0) {
+         // Already won, return existing IDs
+         return {
+           status: 'already_processed',
+           clientId: existing[0].client_id,
+           projectId: existing[0].project_id
+         };
+       }
+       
+       // First time: create client + project + phases + payments
+       const client = await tx.insert(clients).values({
+         name: lead.email,
+         brand_name: lead.company_name,
+         brief: lead.notes,
+         // ... rest of fields
+       }).returning();
+       
+       const project = await tx.insert(projects).values({
+         client_id: client.id,
+         name: lead.email,
+         accepted_total: lead.quote_total
+       }).returning();
+       
+       // Copy phases from offer
+       await copyOfferToProject(lead.offer_id, project.id, tx);
+       
+       // Create payments (e.g., 50% deposit, 50% balance)
+       const paymentPlan = calculatePaymentPlan(lead.quote_total);
+       for (const payment of paymentPlan) {
+         await tx.insert(payments).values({
+           project_id: project.id,
+           label: payment.label,
+           amount: payment.amount,
+           status: 'da_saldare'
+         });
+       }
+       
+       // Mark lead won LAST (proof that all steps succeeded)
+       await tx.update(crm_leads).set({
+         status: 'won',
+         client_id: client.id,
+         project_id: project.id
+       }).where(eq(crm_leads.id, leadId));
+       
+       return {
+         status: 'success',
+         clientId: client.id,
+         projectId: project.id
+       };
+     });
+   }
+   ```
+   
+   Transaction guarantees: either ALL steps succeed, or ALL rollback. No partial state.
 
-**Phase mapping:** Data model separation — Phase 1. Admin rotation UI — Phase 2.
+2. **Idempotency on browser side (preserve key across retries):**
+   ```typescript
+   const [idempotencyKey] = useState(() => localStorage.getItem('winLead_key') || nanoid());
+   
+   const handleWinLead = async () => {
+     localStorage.setItem('winLead_key', idempotencyKey); // Persist key
+     
+     try {
+       const response = await markAsWon(leadId, idempotencyKey);
+       if (response.status === 'success' || response.status === 'already_processed') {
+         localStorage.removeItem('winLead_key'); // Clear key
+         navigate(`/admin/projects/${response.projectId}`);
+       }
+     } catch (e) {
+       showNotification('Failed to mark won. Retrying...');
+       // Retry will use same key — safe due to idempotency
+     }
+   };
+   ```
+
+3. **UI pattern: disable button until success**
+   ```typescript
+   const [loading, setLoading] = useState(false);
+   
+   return (
+     <button 
+       onClick={handleWinLead}
+       disabled={loading}
+     >
+       {loading ? 'Processing...' : 'Mark as Won'}
+     </button>
+   );
+   ```
+   
+   Button disabled immediately after click, prevents double-click. Only re-enabled on success (not on error).
+
+4. **Partial failure handling (if some step fails):**
+   - Transaction handles atomic all-or-nothing
+   - BUT: if transaction itself fails (network before commit), idempotency key ensures retry works
+   - If you need to investigate failure: client created but project creation failed, don't delete partial data
+   - Instead: mark client as `status: 'partial_onboarding'`, show admin a recovery UI: "Complete onboarding?" button
+
+   ```typescript
+   // Check for partial onboarding
+   const lead = await getLeadWithClient(leadId);
+   if (lead.client_id && !lead.project_id) {
+     return (
+       <div>
+         <p>Onboarding incomplete. Client created, but project missing.</p>
+         <button onClick={() => completeOnboarding(lead)}>
+           Complete Onboarding
+         </button>
+       </div>
+     );
+   }
+   ```
+
+**Detection:**
+- Query for duplicate clients by email: `SELECT email, COUNT(*) FROM clients GROUP BY email HAVING COUNT(*) > 1`
+- Check leads.idempotency_key: every record should have one, none should be NULL
+- CRM audit log: "Win" action should appear exactly ONCE per lead, even if endpoint was called 10 times (due to retries)
+- Payment audit: project should have exactly 2–4 payments (not 8), based on payment plan
+
+**Phase to address:** Phase 9 (CRM Won Automation) — implement idempotency in API design BEFORE feature ships, not after data corruption
 
 ---
 
-### 6. Client Approval Has No Immutable Record
+### Pitfall 6: Offer Phase Copy Doesn't Copy Task Deliverables
 
-**What goes wrong:** Client clicks "Approve." Later: "I never approved that." If approval is a boolean with no timestamp, there is no evidence. Weakens your position in commercial disputes.
+**What goes wrong:**
+
+Offer structure: offer_micros (marketing tiers) have no tasks/deliverables (they're just labels for groups of services).
+
+When you "Win" and copy to project, you need to:
+```
+offer_micros (Signature A) 
+  → project_phases (Phase 1)
+      → project_tasks (Competitor audit, Design deliverables)
+          → deliverables (Audit report.pdf, Wireframes.pdf)
+```
+
+But you copy only phases, forget to copy tasks. Or you copy tasks but forget deliverables. Or you copy deliverables but forget to set `task_id` correctly (NULL or wrong phase's task ID).
+
+Result: client dashboard shows phase with no tasks (blank), or tasks with no deliverables (can't approve anything).
+
+**Why it happens:**
+
+Offer structure is marketing (macro → micro → services). Project structure is execution (phases → tasks → deliverables). They don't map 1:1. You're confused about the mapping:
+- Is offer_micro a project_phase? (Probably)
+- Are offer_services the deliverables? Or are they task descriptions? (Unclear)
+- Do you create one task per service, or group services into tasks? (Undefined)
+
+You guess, implement halfway, realize it's broken when client can't approve.
+
+**Consequences:**
+
+- Client dashboard shows phases with no tasks/deliverables (looks broken)
+- Client can't see what they're supposed to approve
+- Admin must manually recreate deliverables (tedious, error-prone)
+- Audit trail broken: "what was promised in the offer?" vs "what's in the project?" diverge
+- Multiple projects from same offer have different deliverable structures (inconsistent)
 
 **Prevention:**
-- Store `approved_at` timestamp alongside the approval boolean — from day one
-- Display approval timestamp in admin view
-- Approvals are immutable for clients — no "undo" button
 
-**Warning signs:** Approval is a boolean column with no timestamp. Client-visible "undo approval" button exists.
+1. **Define hierarchies explicitly IN WRITING (document as code):**
+   ```typescript
+   // Type definitions make mapping explicit
+   interface OfferStructure {
+     micros: {  // e.g., "Signature A", "Signature B"
+       id: string;
+       public_name: string;
+       services: {  // e.g., "Competitor audit", "Brand strategy"
+         id: string;
+         name: string;
+         transformation_description: string;
+       }[];
+     }[];
+   }
+   
+   interface ProjectStructure {
+     phases: {  // e.g., "Discovery", "Design", "Launch"
+       id: string;
+       title: string;
+       tasks: {  // e.g., "Conduct competitor audit"
+         id: string;
+         title: string;
+         deliverables: {  // e.g., "Audit report"
+           id: string;
+           title: string;
+           description: string;
+         }[];
+       }[];
+     }[];
+   }
+   
+   // Mapping rule (explicit):
+   // 1 offer_micro → 1 project_phase (keep titles)
+   // 1 offer_service → 1 project_task → 1 project_deliverable
+   ```
 
-**Phase mapping:** Schema — Phase 1. Display in admin — Phase 2.
+2. **Explicit copy function with validation:**
+   ```typescript
+   async function copyOfferToProject(offerId: string, projectId: string) {
+     const offer = await getOfferWithAllNested(offerId);
+     
+     return await db.transaction(async (tx) => {
+       const result = {
+         phasesCreated: 0,
+         tasksCreated: 0,
+         deliverablesCreated: 0
+       };
+       
+       // For each offer micro:
+       for (const micro of offer.micros) {
+         const phase = await tx.insert(phases).values({
+           project_id: projectId,
+           title: micro.public_name,
+           sort_order: micro.sort_order
+         }).returning();
+         result.phasesCreated++;
+         
+         // For each service in this micro, create a task + deliverable:
+         for (const service of micro.services) {
+           const task = await tx.insert(tasks).values({
+             phase_id: phase.id,
+             title: service.name,
+             description: service.transformation_description,
+             sort_order: 0
+           }).returning();
+           result.tasksCreated++;
+           
+           // Service description → 1 deliverable
+           const deliverable = await tx.insert(deliverables).values({
+             task_id: task.id,
+             title: `${service.name} Deliverable`,
+             description: service.transformation_description,
+             status: 'pending'
+           }).returning();
+           result.deliverablesCreated++;
+         }
+       }
+       
+       return result;
+     });
+   }
+   ```
+
+3. **Validation: count check (integration test):**
+   ```typescript
+   const offer = await getOfferWithCounts(offerId);
+   const result = await copyOfferToProject(offerId, projectId);
+   
+   assert(result.phasesCreated === offer.micros.length);
+   assert(result.tasksCreated === offer.totalServices);
+   assert(result.deliverablesCreated === offer.totalServices);
+   
+   // Verify foreign keys:
+   const deliverables = await db.select()
+     .from(deliverables_table)
+     .where(in(deliverables_table.task_id, 
+               await db.select().from(tasks).where(eq(tasks.phase_id, ...))));
+   
+   assert(deliverables.every(d => d.task_id !== null));
+   ```
+
+4. **Test scenario in integration tests:**
+   ```typescript
+   it('copies offer with 3 micros, 2 services each into project', async () => {
+     const offer = await createTestOffer({
+       micros: [
+         { services: ['Audit', 'Strategy'] },
+         { services: ['Design', 'Copy'] },
+         { services: ['Launch', 'Training'] }
+       ]
+     });
+     
+     const project = await createTestProject();
+     const result = await copyOfferToProject(offer.id, project.id);
+     
+     expect(result.phasesCreated).toBe(3);
+     expect(result.tasksCreated).toBe(6);
+     expect(result.deliverablesCreated).toBe(6);
+     
+     // Verify structure
+     const phases = await getProjectPhases(project.id);
+     expect(phases[0].tasks.length).toBe(2);
+     expect(phases[0].tasks[0].deliverables.length).toBe(1);
+   });
+   ```
+
+**Detection:**
+- Query projects from same offer for structure consistency:
+  ```sql
+  SELECT project_id, COUNT(DISTINCT phases) as phase_count, COUNT(tasks) as task_count
+  FROM projects JOIN phases USING(project_id) JOIN tasks USING(phase_id)
+  WHERE source_offer_id = 'offer_123'
+  GROUP BY project_id;
+  -- All rows should have identical phase_count and task_count
+  ```
+
+- Find projects with missing deliverables:
+  ```sql
+  SELECT p.id FROM projects p
+  JOIN phases ph ON p.id = ph.project_id
+  JOIN tasks t ON ph.id = t.phase_id
+  LEFT JOIN deliverables d ON t.id = d.task_id
+  WHERE d.id IS NULL AND p.source_offer_id IS NOT NULL;
+  ```
+
+**Phase to address:** Phase 7 (Catalog & Offers) for offer structure design; Phase 9 (CRM/Quotes) for copy mechanism — define mapping BEFORE implementation
 
 ---
 
-## Moderate Pitfalls
+## MINOR PITFALLS (Operational Friction)
 
-### 7. Payment Status Without a Valid State Machine
+### Pitfall 7: Offer Builder State Not Synchronized Between Tabs
 
-Payment has three states (da_saldare / inviata / saldato) for two payments. If transitions are not enforced, the dashboard shows contradictory states.
+**What goes wrong:**
 
-**Prevention:** Enforce valid transitions: `da_saldare → inviata → saldato`. Admin UI offers only valid next states.
+Admin edits offer "Signature A" in tab 1, adds a new service to a phase. Tab 2 still shows old offer structure (no service). Admin in tab 2 tries to drag a service, the dragged service doesn't exist in tab 1's state. Or: tabs are editing the same offer simultaneously, last save wins, first admin's work is lost silently.
 
-**Phase mapping:** Admin UI — Phase 2.
+**Why it happens:**
+
+No real-time sync or conflict detection. SPA loads offer once, edits in memory, saves. If same user opens offer in another tab, it doesn't know about changes in tab 1.
+
+**Consequences:**
+
+- Admin's edits silently overwritten
+- Offer structure becomes inconsistent
+- Frustration: "I added a service, but it's not there"
+- For solo consultant (only user), not critical but annoying
+
+**Prevention:**
+
+1. **Conflict detection on save:**
+   - Load offer with `version` field (integer, incremented on every update)
+   - On save, check: `WHERE id = ? AND version = ?`
+   - If version mismatch, return 409 Conflict with server's current version
+   - UI shows: "Offer changed elsewhere. Reload?"
+
+2. **Session-level locking (optional, for future multi-user):**
+   - Add `locked_by: uuid | null` to offer_micros
+   - When editing, lock: `UPDATE offers SET locked_by = ?, locked_at = NOW()`
+   - When saving, unlock
+   - If another session tries to edit locked offer, show: "Being edited elsewhere"
+
+3. **Message broadcast (optional, for future real-time):**
+   - WebSocket or polling to broadcast changes between tabs
+   - Only worth it if multi-user editing becomes common
+
+**Detection:**
+- Open offer in 2 tabs, edit in both, save in sequence
+- Check: which version is final? (should be tab 2's, not tab 1's)
+- Verify version field increments
+
+**Phase to address:** Phase 7 (Offer Builder) — add versioning when form shipped, not after conflicts discovered
 
 ---
 
-### 8. Google Drive Links That Rot
+### Pitfall 8: Backward Incompatibility When Adding CRM Lead Fields
 
-Document links break when sharing settings change or the Drive account changes. Client sees a broken link to their own deliverable.
+**What goes wrong:**
 
-**Prevention:** Store a display name alongside the URL so broken links are visible in admin. Build a simple "update link" affordance in Phase 2.
+You add new schema fields to CRM leads: `source, budget, next_follow_up_date`. Existing lead records have NULL for these. New code assumes fields have values, crashes:
+```
+const budget = lead.budget * 1000;  // TypeError: Cannot read property '*' of null
+```
+
+Or you rename `lead_status` to `status`, old API calls still use `lead_status`, code path breaks.
+
+**Why it happens:**
+
+Schema changes are additive but code changes aren't. You add a column, then deploy code that assumes the field is populated. Existing records don't have the field populated, so assumptions break.
+
+**Consequences:**
+
+- Admin dashboard crashes when loading old leads
+- API returns unexpected shape
+- Code that expects fields gets NULL, calculations fail
+- Rollback is hard because you can't easily undo schema changes
+
+**Prevention:**
+
+1. **Expand-Contract migration pattern:**
+   ```
+   Phase A (Expand):
+   - Add new column as NULLABLE: ALTER TABLE crm_leads ADD COLUMN budget NUMERIC NULL;
+   - Deploy code that handles both: lead.budget ?? lead.legacy_budget ?? 0
+   - Backfill old records: UPDATE crm_leads SET budget = 0 WHERE budget IS NULL;
+   
+   Phase B (Contract):
+   - Once all records have budget, add NOT NULL: ALTER TABLE crm_leads ALTER COLUMN budget SET NOT NULL;
+   - Remove old code that handles NULL
+   - Only then can you safely drop legacy_budget column
+   ```
+
+2. **Defensive code (handles NULL gracefully):**
+   ```typescript
+   // WRONG: assumes budget always populated and is a number
+   const budgetLabel = (lead.budget / 1000).toFixed(2);
+   
+   // RIGHT: handles NULL and migration
+   const leadBudget = lead.budget ?? lead.legacy_budget ?? 0;
+   const budgetLabel = (leadBudget / 1000).toFixed(2);
+   ```
+
+3. **Schema versioning:**
+   - Track in `settings` table: `{ key: 'schema_version', value: '9' }`
+   - Code checks version and handles old shapes
+   - Prevents schema-and-code mismatches
+
+4. **Migration test:**
+   - After adding column, backfill, run query: `SELECT COUNT(*) FROM crm_leads WHERE budget IS NULL` — should be 0
+   - Add NOT NULL constraint only after validation
+   - Test with production-like data (old NULLs) in test database
+
+**Detection:**
+- Test with production data: copy production leads to test db, run new code against them
+- Query for NULL fields: `SELECT COUNT(*) FROM crm_leads WHERE budget IS NULL OR source IS NULL`
+- Code review: search for assumptions (e.g., `lead.budget.toFixed()` without null check)
+
+**Phase to address:** Phase 9 (CRM) — plan all schema changes first, execute Expand-Contract carefully
 
 ---
 
-### 9. Admin Area With No Real Access Control
+### Pitfall 9: Scope Creep — Building GoHighLevel Instead of Solo-Consultant Tool
 
-`/admin` is a secret route with no authentication. A client who guesses the URL accesses all client data.
+**What goes wrong:**
 
-**Prevention:** Add Next.js middleware check against `ADMIN_PASSWORD` env variable before Phase 2 ships. Never rely on security through obscurity for a route that contains all client data.
+You start building CRM with: leads, statuses, follow-up reminders. Then:
+- "Should add email templates" (30 hours)
+- "Should track calls" (40 hours)
+- "Should integrate with calendar" (20 hours)
+- "Should score leads by engagement" (50 hours)
+- "Should have team assignments" (60 hours)
+- "Should send bulk emails" (40 hours)
 
-**Phase mapping:** Phase 2, before admin area contains real data.
+18 months later CRM is 40% done, other features blocked, and you're building Salesforce for one person.
+
+**Why it happens:**
+
+CRM is unbounded feature space. Every CRM ever adds more features. You imagine the "complete" product and feel like MVP is missing pieces. Also, features are tempting: "just add X" sounds quick (it's not).
+
+**Consequences:**
+
+- CRM Phases 9–12 never ship (stuck in feature bloat)
+- Other priorities (catalog, quotes, public pages) delayed indefinitely
+- Code complexity explodes, maintenance burden increases
+- Solo consultant doesn't actually use 90% of features (nice-to-haves)
+- Real problem (lead pipeline visibility) gets 1/10 of attention it deserves
+
+**Prevention:**
+
+1. **Explicit scope document with Must/Should/Could/Won't (MoSCoW):**
+   
+   **MUST HAVE (v2.0 — shipped in Phase 9):**
+   - Lead status pipeline: New → Contacted → Quoted → Won/Lost
+   - Quote prerequisite: can't win without attaching quote
+   - Auto-create client + project on Won
+   - Follow-up reminders in dashboard: "You haven't contacted [prospect] in 5 days"
+   - Mark as lost (deal rejected)
+   
+   **SHOULD HAVE (v2.1 — later milestone, if time):**
+   - Email template system (for follow-up messages)
+   - Call logging: date, outcome, next step
+   - Lead source tracking: website, referral, cold outreach
+   
+   **COULD HAVE (nice-to-haves, only if free time):**
+   - Email campaign automation (use Mailchimp for this)
+   - Lead scoring/AI ranking (premature optimization)
+   - Custom fields (overkill for solo practice)
+   
+   **WON'T HAVE (explicitly out of scope for solo consultant v2.0):**
+   - Multi-user team assignments (only you)
+   - Lead distribution/queuing (not relevant)
+   - Call recording integration (use Calendly/Zoom for this)
+   - Bulk import/export (you add leads one at a time)
+   - Webhook integrations to other tools (complexity tax)
+   - CRM API for integrations (premature)
+   - Reporting/dashboards beyond KPI dashboard (already exists)
+
+2. **Success criteria by feature, not by feature count:**
+   - MVP v2.0 success: "Can I go from cold lead to won project in <30 minutes without manual work?"
+   - Success metric: "Did I use this CRM feature >2x per week?"
+   - If not used, remove it (don't carry dead weight)
+
+3. **Ruthless scope boundary questions:**
+   - "Is this essential for lead → quote → won → project workflow?"
+   - "Will I actually use this weekly?"
+   - "Does this directly serve the solo consultant (not a 50-person sales team)?"
+   - If no, defer to v2.1 or later (or never)
+
+4. **Feature prioritization by impact:**
+   - Tier 1 (must ship): lead pipeline, quote attachment, auto-onboarding
+   - Tier 2 (ship if time): follow-up reminders, source tracking
+   - Tier 3 (defer): templates, scoring, integrations
+
+**Detection:**
+- Review Phase 9 spec: count "must" vs "should" vs "could" vs "won't"
+- If "could" list is longer than "must" list, scope creep is happening
+- After v2.0 ships, audit actual usage weekly: which CRM features did you use?
+- If >15% of features unused, that's scope creep aftermath
+
+**Phase to address:** Phase 9 (CRM) planning — before design, agree on exact boundaries and document in Must/Should/Won't categories
 
 ---
 
-### 10. Comments Scope Creeping Into Threading
+## Phase-Specific Warnings
 
-"Clients can leave comments" becomes complex when replies, read/unread state, and notifications are added. Can double Phase 1 scope.
-
-**Prevention:** Phase 1 ships comments as a flat append-only list per task. No threading, no replies, no email notifications.
+| Phase | Feature | Likely Pitfall | Mitigation |
+|-------|---------|---------------|-----------|
+| 7 | Catalog consolidation | Orphaned quote_items, broken price snapshots | Expand-Contract migration; dual writes; verify referential integrity before contract |
+| 7 | Offer builder (drag-drop) | Sort order race conditions, conflicting versions | Add version field; use optimistic locking; recompute server-side |
+| 7 | Copy offer to offer tier | Template mutation, partial copies, missing tasks | Atomic transaction for entire tree; deep copy; integration tests |
+| 8 | Public quote pages | Token enumeration, pricing leakage, unauthorized access | Longer tokens (32+ chars); expiration; email validation; rate limiting; never include quote_items |
+| 8 | Quote acceptance | Double-processing (accepted twice) | Add unique constraint on (quote_id, lead_id); prevent concurrent accepts |
+| 9 | CRM "Win" automation | Double-click creates duplicate clients | Idempotency key pattern; atomic transaction; disable button until success |
+| 9 | CRM schema changes | Backward incompatibility (NULL field handling) | Expand-Contract pattern; defensive code; backfill validation before NOT NULL |
+| 9 | CRM scope definition | Feature bloat, never ships | Explicit Must/Should/Could/Won't scope document; measure actual usage; ruthless pruning |
 
 ---
 
-## Minor Pitfalls
+## Integration Pitfalls (Cross-Feature)
 
-### 11. DNS Configuration as a Last-Minute Task
+### Data Consistency: Offer Promise vs. Project Execution
 
-`welcomeclient.iamcavalli.net` requires a CNAME to Vercel's DNS. Propagation takes minutes to hours. Doing this the day of a client demo misses the deadline.
+**Risk:** CRM wins, creates project with copied phases. Admin later edits project deliverables (changes requirements). Client dashboard shows updated requirements, but the original "promise" (in offer) is now different. Client approval audit trail is broken.
 
-**Prevention:** Configure DNS in Phase 1 before the UI is complete. Verify propagation independently.
+**Mitigation:**
+- Store immutable offer snapshot in project_offers row: `offer_snapshot: JSONB`
+- Client dashboard shows BOTH offer promise and project execution in parallel
+- Admin must explicitly accept client's approval of any changes
+- Audit log every project change with reason (scope change, typo fix, etc.)
 
 ---
 
-### 12. Mobile Responsiveness as an Afterthought
+### Token Security Across Client/Public Surfaces
 
-Clients open the link on their phone from a shared message. A broken mobile layout is the first impression.
+**Risk:** Two token-based surfaces:
+- `/client/[token]` (confidential project dashboard, 21 chars)
+- `/quote/[quoteToken]` (public semi-confidential, 32 chars)
 
-**Prevention:** Use Tailwind mobile-first defaults from the start. Test on a real phone before any link is sent.
+If validation is inconsistent, one surface may leak data the other guards.
+
+**Mitigation:**
+- Centralized token validation middleware
+- Different token lengths (client 21, quote 32) to distinguish in logs
+- Rate-limit both surfaces separately; detect enumeration attempts
+- Test both with wrong/expired/tampered tokens
 
 ---
 
-### 13. No Empty States
+### Payment State Consistency After Partial Failure
 
-A new client record with no tasks shows a blank page. The client assumes something is broken.
+**Risk:** CRM "Win" creates client, project, and 1–4 payments in transaction. If payment creation partially succeeds (1 of 3 created, then error), payment schedule is broken.
 
-**Prevention:** Design minimal empty states for no-tasks, no-documents, no-comments.
+**Mitigation:**
+- ALL-OR-NOTHING transaction (shown in Pitfall 5)
+- Payment initialization is deterministic: same total + plan = same payments
+- Retry is idempotent: re-running creates same payments (no duplicates)
+- Admin dashboard shows: "Payment setup incomplete, retry?" with clear status
 
 ---
 
-## Phase-Specific Warnings Summary
+## Recommended Research/Validation for Each Phase
 
-| Phase Topic | Likely Pitfall | Mitigation |
-|---|---|---|
-| Client token generation | Guessable slug from name | Crypto-random UUID/nanoid, never name-derived |
-| Client-facing API | Admin data in JSON response | `ClientView` type enforced server-side |
-| Storage choice | Vercel filesystem not persistent | External DB (Neon) before first data write |
-| Admin area access | No real auth | Middleware check before Phase 2 ships |
-| Approval recording | Boolean-only, no audit trail | Store `approved_at` from day one |
-| Token in data model | Token = PK, unrotatable | Separate stable ID from rotatable token field |
-| Phase ordering | Claude flow before dashboard | Enforce: client view → admin edit → Claude |
-| Comments | Threading scope creep | Flat list in Phase 1 |
-| DNS | Last-minute failure | Configure and verify in Phase 1 |
+| Phase | Topic | Validation | Owner |
+|-------|-------|-----------|-------|
+| 7 | Migration safety | Dry-run consolidation on prod DB backup; verify referential integrity | Dev |
+| 7 | Offer hierarchies | Document offer vs project structure mapping explicitly | Product + Dev |
+| 7 | Drag-drop conflicts | Load test concurrent edits; verify sort_order integrity | QA |
+| 8 | Token security | Brute-force test, enumeration test, leakage test on public page | Security review |
+| 8 | Public page access | Test token expiration, email validation, rate limiting | QA |
+| 9 | CRM idempotency | Test double-click, network failures, partial recovery | QA + Dev |
+| 9 | Scope validation | Review Must/Should/Won't with user; mark priorities | Product |
+| 9 | Payment consistency | Test partial failures, rollback scenarios, retry idempotency | Dev + QA |
+
+---
+
+## Sources
+
+- [Data Migration Testing: A Complete Guide](http://migravion.com/blog/data-migration-testing-guide)
+- [Maintaining Data Integrity During Migration — Plane Blog](https://plane.so/blog/maintaining-data-integrity-during-migration)
+- [Optimistic Updates: State-Based and Render-Based Approaches](https://www.nirtamir.com/articles/optimistic-updates-state-vs-render/)
+- [Optimistic UI Without Lying: React 19 Blueprint](https://www.7tech.co.in/react-optimistic-ui-blueprint-conflict-safe-mutations/)
+- [The Double-Click Problem: How Idempotency Saved Our Checkout System](https://codefarm0.medium.com/the-double-click-problem-how-idempotency-saved-our-checkout-system-a704be65d207)
+- [Idempotency in software: Designing Systems to Safely Retry](https://emmanuelvalverderamos.substack.com/p/idempotency-in-software-designing)
+- [Zero-Downtime Postgres Migrations with Drizzle ORM](https://dev.to/whoffagents/zero-downtime-postgres-migrations-with-drizzle-orm-22ga)
+- [Backward Compatibility in Schema Evolution: Guide](https://www.dataexpert.io/blog/backward-compatibility-schema-evolution-guide)
+- [How to Avoid Scope Creep and Misalignment When Launching MVP](https://medium.com/swlh/the-one-map-you-need-to-avoid-scope-creep-and-align-stakeholders-c4763789eeda)
+- [Best CRM for Consultants & Freelancers (2026 Guide)](https://www.authencio.com/blog/best-crm-for-consultants-freelancers-guide)
+- [Defending OAuth: Common Attacks and Prevention](https://workos.com/blog/oauth-common-attacks-and-how-to-prevent-them/)
+- [Token Leakage Via Referer — Pentest Vulnerability Wiki](https://www.cobalt.io/vulnerability-wiki/v4-access-control/token-leakage-referer)
+- [Transactional Locking to Prevent Race Conditions](https://sqlfordevs.com/transaction-locking-prevent-race-condition)
diff --git a/.planning/research/PITFALLS_CHECKLIST.md b/.planning/research/PITFALLS_CHECKLIST.md
deleted file mode 100644
index eb6bd7c..0000000
--- a/.planning/research/PITFALLS_CHECKLIST.md
+++ /dev/null
@@ -1,210 +0,0 @@
-# Pitfalls Checklist: Business Operations Suite v2.0
-
-Quick reference for preventing the 9 major pitfalls during Phase 7–9 implementation.
-
----
-
-## Critical Pitfalls (Before Code)
-
-### 1. Catalog Consolidation Breaks Quotes
-- [ ] Migration strategy documented (Expand-Contract, not drop)
-- [ ] Mapping layer between old/new tables designed
-- [ ] Backfill script tested on production backup
-- [ ] Referential integrity test query written
-- [ ] Dual-write period defined (2-3 weeks)
-- [ ] Rollback plan documented (drop new table, revert code)
-
-### 2. Offer Template Mutation
-- [ ] Offer/project hierarchy mapping documented (1 page)
-- [ ] Copy function uses `db.transaction()` (all-or-nothing)
-- [ ] Uses `structuredClone()` for deep copy, not `{...spread}`
-- [ ] Idempotency key added to CRM leads table
-- [ ] Integration test: copy offer, verify structure consistent across instances
-- [ ] Test: edit project phase, verify offer template unchanged
-
-### 3. Public Quote Token Leakage
-- [ ] Token length ≥ 32 chars (nanoid(32) or nanoid(64))
-- [ ] Expiration field added (default 7 days)
-- [ ] Email validation on public page (token + email required)
-- [ ] Rate limiting implemented (max 3 views/token/minute)
-- [ ] Code audit: quote_items NOT in public API response
-- [ ] Test: brute-force 1000 guesses, verify rate limit activates
-- [ ] Test: enumerate tokens with different emails, verify 401
-
----
-
-## Moderate Pitfalls (During Implementation)
-
-### 4. Drag-and-Drop Race Condition
-- [ ] `version` field added to offer_phases
-- [ ] Update mutation checks version (returns 409 if mismatch)
-- [ ] Server recomputes all sort_orders atomically
-- [ ] Frontend handles 409 Conflict (refresh UI)
-- [ ] Test: concurrent drag in 2 tabs, verify final state correct
-
-### 5. CRM "Win" Double-Click
-- [ ] Idempotency key added to crm_leads (unique)
-- [ ] "Win" mutation checks if key already processed
-- [ ] All sub-steps in single `db.transaction()`
-- [ ] Button disabled until success
-- [ ] Idempotency key stored in localStorage
-- [ ] Test: double-click "Win", verify only 1 client created
-
-### 6. Offer Copy Missing Tasks/Deliverables
-- [ ] Mapping documented: offer_micro → project_phase → project_task → deliverable
-- [ ] Copy function recursive (phases → tasks → deliverables)
-- [ ] Validation test: assert counts match expected
-- [ ] Integration test exists (copy, verify structure)
-- [ ] Query test: no orphaned deliverables (task_id IS NULL)
-
----
-
-## Minor Pitfalls (Polish)
-
-### 7. Offer State Not Synced Between Tabs
-- [ ] `version` field on offer_micros
-- [ ] Update returns 409 on version mismatch
-- [ ] UI shows "Offer changed, reload?" dialog
-
-### 8. CRM Schema Backward Incompatibility
-- [ ] New columns added as NULLABLE
-- [ ] Code handles NULL defensively (e.g., `lead.budget ?? 0`)
-- [ ] Backfill script written (sets defaults for existing rows)
-- [ ] NOT NULL constraint added only after backfill + validation
-- [ ] Test: production data copied to test db, code runs without errors
-
-### 9. CRM Scope Creep
-- [ ] Must-have features defined for v2.0 (lead pipeline, quote, auto-onboard)
-- [ ] Should-have features listed for v2.1+ (email, calls, source)
-- [ ] Won't-have features documented (team, multi-user, integrations)
-- [ ] Scope document signed off by product
-- [ ] Success metric defined: "Can go from lead to won project in <30 min"
-
----
-
-## Phase 7 Checklist (Catalog & Offers)
-
-**Before code:**
-- [ ] Catalog consolidation migration plan reviewed
-- [ ] Offer/project hierarchy documented
-- [ ] Drag-drop version/locking strategy designed
-
-**During implementation:**
-- [ ] Migration backfill tested on production backup
-- [ ] Drag-drop version field added
-- [ ] Offer phase copy function atomic (transaction)
-- [ ] Idempotency key on CRM leads
-- [ ] Integration tests for copy consistency
-
-**Before go-live:**
-- [ ] Dry-run migration on production DB
-- [ ] Verify referential integrity (no orphaned quote_items)
-- [ ] Concurrent drag-drop test passes
-- [ ] Offer copy count validation passes
-
----
-
-## Phase 8 Checklist (Public Quote Pages)
-
-**Before code:**
-- [ ] Token security requirements finalized
-- [ ] API response schema designed (no quote_items)
-- [ ] Rate limiting strategy defined
-
-**During implementation:**
-- [ ] Token generation (nanoid(32))
-- [ ] Expiration + email validation
-- [ ] Rate limiting middleware
-- [ ] Code audit for quote_items exposure
-- [ ] Brute-force test (>1000 guesses/sec)
-
-**Before go-live:**
-- [ ] Brute-force test activates rate limit
-- [ ] Enumeration test returns 401 for wrong email
-- [ ] Expiration test returns 401 after expiration
-- [ ] Code review: quote_items not in response
-
----
-
-## Phase 9 Checklist (CRM Won Automation)
-
-**Before code:**
-- [ ] Scope document (Must/Should/Could/Won't) reviewed
-- [ ] Idempotency strategy designed
-- [ ] Payment plan algorithm defined
-- [ ] Offer snapshot structure (JSONB) designed
-
-**During implementation:**
-- [ ] Idempotency key on crm_leads
-- [ ] "Win" mutation atomic (client + project + phases + payments)
-- [ ] Offer snapshot stored on win
-- [ ] Button disabled until success
-- [ ] Payment consistency tests
-
-**Before go-live:**
-- [ ] Double-click test: only 1 client created
-- [ ] Network timeout test: retry returns same project
-- [ ] Partial failure test: rollback on error
-- [ ] Payment consistency test: correct number created
-- [ ] Idempotency test: 10x "Win" with same key = 1 client
-
----
-
-## Key Questions Before Each Phase
-
-**Phase 7:**
-- ✓ Is catalog consolidation migration safe (Expand-Contract, dual-write)?
-- ✓ Does offer/project hierarchy mapping make sense (1 micro = 1 phase)?
-- ✓ Is copy function atomic (all-or-nothing)?
-- ✓ Do we have integration tests for offer phase structure consistency?
-
-**Phase 8:**
-- ✓ Is token length ≥ 32 chars and properly random?
-- ✓ Do we validate both token AND email on public page?
-- ✓ Is rate limiting active (max 3 views/token/min)?
-- ✓ Can we prove quote_items never appears in public response?
-
-**Phase 9:**
-- ✓ Is "Win" action atomic (transaction)?
-- ✓ Does idempotency key prevent duplicates on retry?
-- ✓ Is button disabled until success?
-- ✓ Have we defined Must/Should/Won't scope with user?
-
----
-
-## Testing Validation Matrix
-
-| Pitfall | Test Case | Expected Outcome | Status |
-|---------|-----------|------------------|--------|
-| 1. Catalog consolidation | Backfill migration on prod backup | Zero orphaned quote_items | [ ] |
-| 2. Offer template mutation | Edit project phase, check offer unchanged | Offer template immutable | [ ] |
-| 3. Token leakage | Brute-force 1000 guesses/sec | Rate limit activates (429) | [ ] |
-| 3. Token leakage | Enumerate with wrong email | Returns 401 Unauthorized | [ ] |
-| 4. Drag-drop race | Concurrent drag in 2 tabs | Final sort_order is coherent | [ ] |
-| 5. Double-click clients | Click "Win" twice | Only 1 client created | [ ] |
-| 5. Double-click clients | Network timeout + retry | Same project returned | [ ] |
-| 6. Missing deliverables | Copy offer to project | All tasks and deliverables copied | [ ] |
-| 8. Schema backward compat | Copy production data to test DB | No crashes, NULL handled | [ ] |
-| 9. Payment consistency | "Win" with partial failure | Rollback, no orphaned payments | [ ] |
-
----
-
-## Red Flags During Development
-
-🚨 **Stop and review if:**
-- Offer/project hierarchy mapping is unclear (should be 1 page, explicit)
-- Drag-drop sort_order updates without version check
-- "Win" mutation has any non-transactional steps (client created outside txn)
-- Copy function uses shallow spread (`{...obj}`) instead of `structuredClone()`
-- Token length < 32 chars
-- Public API response includes quote_items or per_service_price
-- CRM leads table has no idempotency_key column
-- Schema changes add NOT NULL without backfill test
-- "Win" button not disabled until response received
-- No rate limiting on public quote page
-
----
-
-**Owner:** Development team  
-**Review:** Before each phase kickoff  
-**Update:** As testing results come in
diff --git a/.planning/research/PITFALLS_SUMMARY.md b/.planning/research/PITFALLS_SUMMARY.md
deleted file mode 100644
index cf80822..0000000
--- a/.planning/research/PITFALLS_SUMMARY.md
+++ /dev/null
@@ -1,302 +0,0 @@
-# Pitfalls Research Summary: Business Operations Suite (v2.0)
-
-**Project:** ClientHub v2.0 — Adding Business Operations Suite to Production  
-**Research Date:** 2026-06-10  
-**Confidence:** HIGH (domain-specific research backed by schema review + security analysis)
-
----
-
-## Overview
-
-Adding a complex Business Operations Suite (catalog consolidation + offer builder + public quotes + CRM automation) to a production app with real client data creates integration risks not present when building from scratch. This research documents the most dangerous pitfalls (rewrites/data loss) and operational friction points, with concrete prevention strategies for each.
-
-**Key insight:** Most pitfalls cluster in four areas of high integration complexity:
-1. **Schema consolidation** — breaking existing quote_items referential integrity
-2. **Template-to-instance copy semantics** — offer phases mutating templates
-3. **Optimistic UI + concurrent edits** — sort order conflicts
-4. **Multi-step workflow atomicity** — CRM automation creating duplicates or partial state
-
----
-
-## Critical Pitfalls (Require Design Changes Before Code)
-
-### Pitfall 1: Catalog Consolidation Breaks Quotes (Data Loss Risk)
-
-**Severity:** CRITICAL — Can orphan quote_items, break billing calculations
-
-**Problem:**
-Two parallel service tables (`service_catalog` for costs, `offer_services` for marketing pricing) need consolidation. Naive merge breaks `quote_items` referential integrity or loses price history.
-
-**Prevention Strategy:**
-- **Expand-Contract migration:** Add new unified `services` table alongside old ones, backfill in phases, only drop old tables after validation
-- **Immutable snapshot:** Store `quote_snapshot: JSONB` in project_offers (freeze prices at time of win)
-- **Referential integrity test:** Query for orphaned quote_items before/after migration
-- **Backward compatibility:** Old quotes read from old tables, new quotes use new table, transition over 2-3 weeks
-
-**Phase:** 7 (Catalog & Offers) — Plan migration design BEFORE any code changes
-
-**Validation checklist:**
-- [ ] Migration mapping layer documented (catalog ↔ services ↔ offer_services)
-- [ ] Backfill strategy written (small batches, checksum validation)
-- [ ] Dual-write period defined (how long to run old+new in parallel)
-- [ ] Referential integrity test query exists
-
----
-
-### Pitfall 2: Offer Template Mutation on Copy (Data Corruption Risk)
-
-**Severity:** CRITICAL — Templates silently mutate when project phases edited
-
-**Problem:**
-Copying offer phases to project via shallow copy = shared references. Admin edits project phase, template phase mutates too. Next deal uses corrupted template. Also: partial copies on retry create duplicate phases.
-
-**Prevention Strategy:**
-- **Deep copy with atomic transaction:** Use `db.transaction()` for entire copy operation (all-or-nothing); copy at database level, not in JS
-- **Immutable template flag:** `offer_micros.is_template = true`, prevent UPDATE on templates
-- **Idempotency key:** "Win" request includes idempotency key; retry returns same project (no duplicates)
-- **Explicit hierarchy mapping:** Document what offer_micro → project_phase, what offer_service → project_task/deliverable
-
-**Phase:** 7 (Offers) for design, 9 (CRM) for "Win" automation
-
-**Validation checklist:**
-- [ ] Hierarchy mapping documented (offer ↔ project structures)
-- [ ] Atomic copy function implemented (single transaction, all-or-nothing)
-- [ ] Idempotency key added to CRM leads
-- [ ] Integration tests verify copy structure consistency across multiple instances
-
----
-
-### Pitfall 3: Public Quote Token Leakage (Security Risk)
-
-**Severity:** CRITICAL — Token enumeration exposes all pricing
-
-**Problem:**
-Public quote page with nanoid 21-char token can be brute-forced or enumerated. Attacker builds pricing database, breaches commercial confidentiality.
-
-**Prevention Strategy:**
-- **Longer token:** nanoid(32) instead of 21 (~190 bits vs ~122 bits entropy)
-- **Access control:** Require both token + email (validate recipient match)
-- **Expiration:** token_expires_at (default 7 days)
-- **Rate limiting:** Max 3 views/token/minute (blocks enumeration)
-- **Never expose quote_items:** Public API response excludes line items, shows TOTAL PRICE ONLY
-- **Activation state:** Token valid only AFTER admin sends it (not auto-generated on create)
-
-**Phase:** 8 (Public Quote Pages) — Implement security controls IN PARALLEL with feature
-
-**Validation checklist:**
-- [ ] Token length ≥ 32 chars, rate limiting ≥ 3/min
-- [ ] Email validation on public page (token + email both required)
-- [ ] Expiration enforced (test expired token returns 401)
-- [ ] Code audit: quote_items never in public API response
-- [ ] Brute-force test: verify rate limit activates
-
----
-
-## Moderate Pitfalls (Major Refactoring / Data Inconsistency)
-
-### Pitfall 4: Drag-and-Drop Sort Order Race Condition
-
-**Severity:** MODERATE — Phases display in wrong order, user frustration
-
-**Problem:**
-Concurrent drag-and-drop edits in multiple tabs cause sort_order conflicts. Last write wins, earlier update is lost. No version conflict detection.
-
-**Prevention Strategy:**
-- **Optimistic locking:** Add `version` field to offer_phases, update only if version matches (return 409 Conflict if mismatch)
-- **Server-side recomputation:** Don't trust client's sort_order, recompute all orders atomically based on actual position
-- **Optimistic UI with reconciliation:** Update frontend instantly, reconcile with server result (409 = refresh)
-
-**Phase:** 7 (Offer Builder — Drag & Drop)
-
-**Validation checklist:**
-- [ ] `version` field added to offer_phases
-- [ ] Update mutation includes version check
-- [ ] Server recomputes all sort_orders atomically
-- [ ] Concurrent edit test exists (open 2 tabs, drag in both)
-
----
-
-### Pitfall 5: CRM "Win" Double-Click Creates Duplicate Clients
-
-**Severity:** MODERATE — Duplicate clients, broken billing, audit confusion
-
-**Problem:**
-Multi-step "Win" automation (create client → project → phases → payments) has no idempotency. Double-click creates two clients, two projects. Network timeouts are invisible to user.
-
-**Prevention Strategy:**
-- **Idempotency key:** Every lead has unique idempotency_key; "Win" request checks if key already processed (if yes, return existing client_id)
-- **Atomic transaction:** All steps (client, project, phases, payments) in single transaction — all succeed or all rollback
-- **UI feedback:** Button disabled until success (prevents accidental double-click)
-- **Browser persistence:** Store idempotency_key in localStorage, preserve across refresh
-
-**Phase:** 9 (CRM Won Automation)
-
-**Validation checklist:**
-- [ ] CRM leads table has idempotency_key column (unique)
-- [ ] "Win" mutation checks for existing key before creating
-- [ ] All substeps in single db.transaction()
-- [ ] Button disabled until response received
-- [ ] Idempotency key stored in localStorage
-- [ ] Test: double-click "Win", verify only 1 client created
-
----
-
-### Pitfall 6: Offer Phase Copy Misses Tasks/Deliverables
-
-**Severity:** MODERATE — Client dashboard shows incomplete phases (no tasks to approve)
-
-**Problem:**
-Copy offer → project phases but forget to copy tasks or deliverables. Client sees phase with no work items.
-
-**Prevention Strategy:**
-- **Explicit mapping:** Document offer_micro → project_phase, offer_service → project_task/deliverable mapping
-- **Full-tree copy function:** Copy phases, then tasks for each phase, then deliverables for each task (all in one transaction)
-- **Validation test:** Assert phase_count, task_count, deliverable_count match expected values after copy
-
-**Phase:** 7 (Offers structure design), 9 (Copy implementation)
-
-**Validation checklist:**
-- [ ] Mapping documented (offer vs project hierarchies)
-- [ ] Copy function handles entire tree (phases → tasks → deliverables)
-- [ ] Integration test: copy offer, verify counts match expected
-- [ ] Query test: check no deliverables are orphaned (task_id IS NULL)
-
----
-
-## Minor Pitfalls (Operational Friction)
-
-### Pitfall 7: Offer State Not Synced Between Tabs
-
-**Problem:** Admin edits offer in tab 1, tab 2 doesn't know, last save wins (first admin's work lost)
-
-**Prevention:** Add `version` field, return 409 on version mismatch, show "Offer changed, reload?"
-
----
-
-### Pitfall 8: CRM Schema Backward Incompatibility
-
-**Problem:** Add new fields (budget, source) as NULL, code assumes populated, crashes
-
-**Prevention:** Expand-Contract pattern — add as NULL, handle NULL defensively in code, backfill, then add NOT NULL constraint
-
----
-
-### Pitfall 9: CRM Scope Creep (Feature Bloat)
-
-**Problem:** "Just add email templates" → 30 hours. "Add calls" → 40 hours. CRM never ships.
-
-**Prevention:** Explicit Must/Should/Could/Won't scope document. Must-haves only for v2.0: lead pipeline, quote attachment, auto-onboarding. Defer rest.
-
----
-
-## Key Design Decisions for Phase 7–9
-
-| Decision | Why | Validation |
-|----------|-----|-----------|
-| Expand-Contract migration for catalog | Zero-downtime, safe rollback, no data loss | Dry-run on prod backup before go-live |
-| Deep copy + atomic transaction for offer phases | Prevents template mutation, partial copies | Integration test, structure consistency query |
-| Idempotency key on "Win" action | Safe retry, prevents duplicate clients | Double-click test, query for duplicates |
-| Public quote token security layers (length, expiration, email, rate limit) | Blocks enumeration, limits leakage | Brute-force test, code audit for quote_items |
-| Offer snapshot (immutable JSONB) | Preserves what was promised vs. what's executing | Store at win time, display in client dashboard |
-| Version field on offer_phases + optimistic locking | Detects concurrent edit conflicts | Concurrent drag test, 409 Conflict handling |
-
----
-
-## Roadmap Implications
-
-**Phase 7 (Catalog & Offers):**
-- Design catalog consolidation migration before any code
-- Implement drag-drop with version fields from start
-- Document offer/project hierarchy mapping explicitly
-- Write copy function atomically (no partial copies)
-
-**Phase 8 (Public Quote Pages):**
-- Implement token security controls in parallel (not after)
-- Rate limiting + email validation + expiration
-- Code audit: quote_items never in response
-- Test brute-force + enumeration
-
-**Phase 9 (CRM — Won Automation):**
-- Add idempotency_key to leads table
-- Implement atomic "Win" transaction
-- Store offer snapshot at win time
-- Define Must/Should/Won't scope before design
-- Integration tests for payment consistency
-
-**Phase 10+ (Future):**
-- Defer: email templates, call logging, team features, integrations
-- Solo consultant doesn't need multi-user or GoHighLevel-scale features
-
----
-
-## Testing Strategy for Confidence
-
-### Phase 7 (Catalog & Offers)
-1. Dry-run consolidation migration on production database backup
-2. Verify all quote_items still resolve to services (no orphans)
-3. Regenerate quotes from old projects, compare prices to originals
-4. Concurrent drag-drop test: open offer in 2 tabs, drag in both, verify final state
-5. Copy offer phases to test project, verify phase/task/deliverable counts
-
-### Phase 8 (Public Quote Pages)
-1. Brute-force token space: 1000 guesses/sec, verify rate limit activates
-2. Enumerate tokens: generate 100 quotes, try to access one meant for different email, verify 401
-3. Expiration test: set token_expires_at to past, verify access fails
-4. Code audit: search response JSON for price, quote_items, per_service_price (should be zero matches)
-5. Authorized access test: correct email + token, verify success
-
-### Phase 9 (CRM — Won Automation)
-1. Double-click "Win" button, verify only 1 client created
-2. Network failure during "Win": simulate timeout after client creation, retry, verify same project returned
-3. Partial failure: mock project creation failure, verify client not created (rollback)
-4. Payment consistency: verify 2–4 payments created based on payment plan
-5. Idempotency: call "Win" 10x with same idempotency_key, verify only 1 project, 1 set of payments
-
----
-
-## Confidence Assessment
-
-| Area | Level | Reason |
-|------|-------|--------|
-| Catalog consolidation risks | HIGH | Schema review shows existing quote_items dependencies; migration pattern verified via Drizzle docs |
-| Offer copy semantics | HIGH | JavaScript shallow copy / deep copy distinction well-understood; transaction guarantees verified |
-| Token security | HIGH | Brute-force math straightforward; nanoid 32 vs 21 entropy difference verified |
-| CRM idempotency | HIGH | Idempotency pattern researched across multiple sources; double-click problem well-documented |
-| Scope creep prevention | MEDIUM | CRM feature bloat is common, but solo consultant constraint makes Must/Should/Won't achievable |
-| Concurrent edit handling | MEDIUM | Optimistic locking pattern standard, but requires careful implementation in Next.js + Drizzle |
-
----
-
-## Next Steps for Phase Planning
-
-1. **Before Phase 7 design starts:**
-   - Finalize catalog consolidation migration plan (Expand-Contract timeline)
-   - Document offer/project hierarchy mapping (1 page, code-level documentation)
-   - Design offer copy function signature and transaction strategy
-
-2. **Before Phase 7 code starts:**
-   - Implement drag-drop versioning (version field + optimistic locking)
-   - Write integration tests for offer phase copy
-
-3. **Before Phase 8 design starts:**
-   - Token security requirements: length (32), expiration (7d), email validation, rate limit (3/min)
-   - API response schema: exclude quote_items, include total_price only
-
-4. **Before Phase 9 design starts:**
-   - Finalize Must/Should/Won't scope (document with user/consultant)
-   - Design "Win" workflow: idempotency key + atomic transaction
-   - Define payment plan algorithm (2–4 payments based on offer tier)
-
----
-
-## References for Implementation
-
-- **Drizzle migrations:** https://dev.to/whoffagents/zero-downtime-postgres-migrations-with-drizzle-orm-22ga
-- **Idempotency pattern:** https://codefarm0.medium.com/the-double-click-problem-how-idempotency-saved-our-checkout-system-a704be65d207
-- **Optimistic updates:** https://www.nirtamir.com/articles/optimistic-updates-state-vs-render/
-- **Schema evolution:** https://www.dataexpert.io/blog/backward-compatibility-schema-evolution-guide
-- **Token security:** https://workos.com/blog/oauth-common-attacks-and-how-to-prevent-them/
-
----
-
-**Document location:** `/Users/simonecavalli/Vault/IAMCAVALLI/.planning/research/PITFALLS_V2.md` (detailed pitfall reference)
diff --git a/.planning/research/PITFALLS_V2.md b/.planning/research/PITFALLS_V2.md
deleted file mode 100644
index edb05fd..0000000
--- a/.planning/research/PITFALLS_V2.md
+++ /dev/null
@@ -1,1269 +0,0 @@
-# Domain Pitfalls: Business Operations Suite (v2.0) — Adding to Production ClientHub
-
-**Project:** ClientHub v2.0 (Business Operations Suite)  
-**Context:** Adding catalog migration, offer builder, public quotes, and CRM to live hub.iamcavalli.net  
-**Researched:** 2026-06-10  
-**Overall confidence:** HIGH (domain-specific integration pitfalls verified against production data constraints)
-
----
-
-## Executive Summary
-
-Adding a Business Operations Suite to a production client portal with real data is riskier than building from scratch. The pitfalls cluster in four areas:
-
-1. **Schema consolidation (Catalog):** Merging two parallel service tables without breaking existing quote_items referential integrity
-2. **Template-to-instance copy semantics (Offers):** Offer phases copied to project phases at "Won" can mutate templates or copy partially
-3. **Optimistic UI state management (Drag-drop):** Frontend and server get out of sync on sort_order conflicts in concurrent edits
-4. **Security + workflow atomicity (Public Quotes, CRM):** Token enumeration leaks pricing; double-click creates duplicate clients; partial failures leave inconsistent state
-
-Each pitfall has concrete prevention strategies designed for solo-consultant use (not team-based CRM) and production migration constraints (Data Safety rule: never delete/truncate clients, projects, payments, phases).
-
----
-
-## CRITICAL PITFALLS (Rewrites / Data Loss Risk)
-
-### Pitfall 1: Service Catalog Consolidation Breaks Existing Quotes
-
-**What goes wrong:**
-
-You have two service tables with different purposes:
-- `service_catalog` (21 rows): operational costs, used by quote_items
-- `offer_services` (35 rows): marketing pricing, used by offer_micro_services
-
-You want a unified `services` table. Two bad approaches:
-
-**Approach A (Naive consolidation):**
-1. Create new `services` table
-2. INSERT all rows from both catalogs
-3. Update quote_items to point to new services by name matching
-4. DROP old tables
-
-**Problem:** Name matching is fragile (typos, duplicates). Foreign key constraint fails if a quote_item references a service that doesn't exist yet. Orphaned rows. Production is down.
-
-**Approach B (Copy-paste merge):**
-1. Manually consolidate the tables in SQL
-2. Delete old tables after data looks "right"
-3. Discover months later that quote_items have NULL service_id or point to wrong service
-4. prices are wrong (offer_services had different prices than service_catalog)
-5. Historical quotes can't be regenerated
-
-**Why it happens:**
-
-Two tables evolved independently. Offer services have transformation_description + price (marketing messaging). Catalog services have unit_price (cost). You conflate them, lose the distinction. Also, you can't tell which service_catalog row corresponds to which offer_service row — there's no mapping.
-
-**Consequences:**
-
-- Quote items become orphaned: `quote_items.service_id` points to deleted service
-- `projects.accepted_total` calculations fail or show wrong values
-- Client dashboard payment status breaks (can't compute from broken quote_items)
-- Audit trail destroyed: can't reconstruct what was offered in old quotes
-- Data Safety violation: quote_items become unreliable, can't be trusted for billing
-- Rollback impossible: old tables are gone
-
-**Prevention:**
-
-1. **Keep both tables; add a new unified `services` table alongside them:**
-   ```
-   Phases:
-   - Phase A (Expand): Add services table, backfill both catalogs into it
-   - Transition period: Old code reads service_catalog, new code reads services
-   - Phase B (Contract): After 2-3 weeks, drop old tables only if safe
-   ```
-
-2. **Create explicit migration mapping:**
-   ```typescript
-   // services table structure:
-   // id, name, unit_price, source_type (catalog | offer), source_id, created_at
-   
-   // Backfill from catalog:
-   INSERT INTO services (id, name, unit_price, source_type, source_id)
-   SELECT nanoid(), name, unit_price, 'catalog', id FROM service_catalog;
-   
-   // Backfill from offer_services (rename if duplicates):
-   INSERT INTO services (id, name, unit_price, source_type, source_id)
-   SELECT nanoid(), 
-          CASE WHEN EXISTS(SELECT 1 FROM services WHERE name = offer_services.name)
-               THEN offer_services.name || ' (Offer)'
-               ELSE offer_services.name
-          END,
-          price, 'offer', id 
-   FROM offer_services;
-   ```
-
-3. **Never update quote_items.service_id immediately:**
-   - Leave quote_items pointing to old service_catalog
-   - New quote code writes to services table
-   - Existing quotes remain readable (backward compatible)
-   - Backfill quote_items in small batches after validation:
-     ```sql
-     UPDATE quote_items 
-     SET service_id = (SELECT id FROM services WHERE source_id = quote_items.service_id AND source_type = 'catalog')
-     WHERE service_id IS NOT NULL AND id IN (
-       SELECT id FROM quote_items ORDER BY id LIMIT 100
-     );
-     ```
-
-4. **Validation before contract phase:**
-   - Query: `SELECT COUNT(*) FROM quote_items WHERE service_id NOT IN (SELECT id FROM service_catalog)` — should be 0
-   - Checksum: SUM(subtotal) in quote_items == SUM(accepted_total) per project — must match
-   - Test quote regeneration: pick 5 old projects, regenerate quote, prices must match original
-
-5. **Immutable snapshot for historical quotes:**
-   - Store `quote_snapshot: JSONB` in project_offers row
-   - This is a frozen copy of what was offered (prices, services, terms)
-   - New code reads from services; historical quote reads from snapshot
-   - Guarantees: old quotes never change, even if catalog prices change
-
-**Detection:**
-- Query for orphaned quote_items: `SELECT COUNT(*) FROM quote_items WHERE service_id IS NOT NULL AND service_id NOT IN (SELECT id FROM service_catalog)`
-- Detect price mismatches: `SELECT project_id, SUM(subtotal), projects.accepted_total FROM quote_items JOIN projects USING(project_id) GROUP BY project_id HAVING SUM(subtotal) != projects.accepted_total`
-- Test suite: regenerate quote on historical project, compare prices to original
-
-**Phase to address:** Phase 7 (Catalog & Offers, specifically "Consolidate catalogs") — design migration BEFORE code changes
-
----
-
-### Pitfall 2: Template-to-Instance Copy Mutates Template (Offer Phases Bug)
-
-**What goes wrong:**
-
-When a lead is won, you copy offer phases into project phases. If you copy by reference instead of by value:
-
-**Scenario A (Shallow copy):**
-```typescript
-// Offer phases structure:
-const offer = {
-  micros: [
-    { id: 'micro1', title: 'Phase 1', tasks: [{ title: 'Audit' }] }
-  ]
-};
-
-// Bad: shallow copy
-const copy = { ...offer };
-copy.micros[0].tasks[0].title = 'Updated Audit';
-
-// Result: offer.micros[0].tasks[0].title is NOW 'Updated Audit' too!
-```
-
-Admin wins a deal, copies phases, edits a project task (e.g., changes from "5 deliverables" to "3 deliverables"). Next time you use the same offer for another lead, the wrong phase structure is copied — the template has been mutated.
-
-**Scenario B (Partial copy on retry):**
-User clicks "Mark as Won," which triggers:
-```
-1. Copy offer.micros → project.phases
-2. Copy offer.services → project.tasks/deliverables
-3. Mark lead.status = 'won'
-```
-
-Network times out or browser tab closes before success page. Admin clicks "Mark as Won" again (thinking it didn't work). Now:
-- `copy.micros → project.phases` inserts new phases (duplicates)
-- Orphaned old tasks from first copy remain
-- Project has 6 phases instead of 3
-
-**Scenario C (Copy at wrong level):**
-You have `offer_micros` (marketing tiers) and `offer_services` (actual deliverables). When you copy, do you copy micros as phases? As phase groups? You're confused about the mapping, so you copy wrong level and tasks don't appear in project.
-
-**Why it happens:**
-
-JavaScript shallow copy is the default. `{...obj}`, `.slice()`, `Object.assign()` all copy references to nested objects. Offer structure is complex (macro → micro → services), and you don't have a clear mapping to project (phases → tasks → deliverables). So you guess the copy strategy.
-
-Also: "Win" action is multi-step (create project, copy phases, copy tasks, create payments). If step 2 fails, step 1 succeeded (orphaned project). No atomic transaction, no idempotency key.
-
-**Consequences:**
-
-- Same offer structure changes unpredictably across different projects
-- Admin sees phase structures diverge: "Why does project A have 5 tasks but project B (same offer) has 6 tasks?"
-- Audit trail breaks: can't reconstruct what was actually sold
-- Client dashboard shows incomplete phases (missing tasks/deliverables)
-- project.accepted_total becomes unreliable if phase structure is different
-
-**Prevention:**
-
-1. **Define hierarchies explicitly (CRITICAL):**
-   
-   **Offer side (marketing):**
-   - offer_macros: "Signature", "Entry", "Retainer" (tier names)
-   - offer_micros: "Signature A", "Signature B", "Signature C" (tier variations)
-   - offer_services: individual deliverables (what client receives)
-   - offer_micro_services: junction (which services in which tier)
-   
-   **Project side (execution):**
-   - projects: top-level
-   - phases: workstreams/timeline ("Discovery", "Design", "Delivery")
-   - tasks: work items within phase ("Competitor audit", "Wireframes")
-   - deliverables: client-approvable outputs ("Audit report", "Wireframe set")
-   
-   **Mapping (at "Won"):**
-   - Offer tier (micro) doesn't equal project phase
-   - Offer services map to project tasks OR deliverables (decide: task or deliverable is the copy target?)
-   - Simplest: each offer_service → 1 task in phase 1, all tasks created at once
-
-2. **Use structuredClone for deep copy:**
-   ```typescript
-   // Instead of shallow spread
-   const deepCopy = structuredClone(offer);
-   deepCopy.micros[0].tasks[0].title = 'X'; // offer is unaffected
-   ```
-
-3. **Never copy from application layer; let database do it atomically:**
-   ```typescript
-   async function copyOfferToProject(offerId, projectId) {
-     return await db.transaction(async (tx) => {
-       // Fetch offer with all nested data
-       const offer = await tx.query.offer_micros.findMany({
-         where: eq(offer_micros.macro_id, offerId),
-         with: {
-           services: true,
-           projectOffers: true
-         }
-       });
-       
-       // Create new phases (1 per offer_micro)
-       const newPhases = [];
-       for (const micro of offer) {
-         const phase = await tx.insert(phases).values({
-           project_id: projectId,
-           title: micro.public_name,
-           sort_order: micro.sort_order
-         }).returning();
-         newPhases.push(phase);
-         
-         // Create tasks (1 per service in this micro)
-         for (const service of micro.services) {
-           const task = await tx.insert(tasks).values({
-             phase_id: phase.id,
-             title: service.name,
-             sort_order: 0
-           }).returning();
-           
-           // Create deliverable from service
-           await tx.insert(deliverables).values({
-             task_id: task.id,
-             title: service.name,
-             description: service.transformation_description
-           });
-         }
-       }
-       
-       return newPhases;
-     });
-   }
-   ```
-   
-   Single transaction = all-or-nothing. No partial copy.
-
-4. **Immutable flag on templates:**
-   ```sql
-   ALTER TABLE offer_micros ADD COLUMN is_template BOOLEAN NOT NULL DEFAULT TRUE;
-   -- Constraint: if is_template, no UPDATE allowed on title/description
-   -- Only inserts/deletes, no mutations
-   ```
-
-5. **Idempotency key prevents double-copy:**
-   ```typescript
-   // CRM leads table:
-   // id, email, status, offer_id, idempotency_key (unique), project_id
-   
-   async function markLedAsWon(leadId, idempotencyKey) {
-     return await db.transaction(async (tx) => {
-       // Check: is this key already processed?
-       const existing = await tx.select().from(leads)
-         .where(eq(leads.idempotency_key, idempotencyKey));
-       
-       if (existing.project_id) {
-         return existing; // Already won, return same project
-       }
-       
-       // First time: create project + copy phases
-       const project = await tx.insert(projects).values({
-         client_id: lead.client_id,
-         name: lead.email
-       }).returning();
-       
-       await copyOfferToProject(lead.offer_id, project.id);
-       
-       // Mark lead won
-       await tx.update(leads)
-         .set({ status: 'won', project_id: project.id })
-         .where(eq(leads.id, leadId));
-       
-       return project;
-     });
-   }
-   ```
-
-6. **Validation: count check after copy:**
-   ```typescript
-   const offer = await getOfferCounts(offerId);
-   const project = await getProjectCounts(projectId);
-   
-   // Assert counts match
-   assert(offer.microCount === project.phaseCount);
-   assert(offer.serviceCount === project.taskCount);
-   assert(offer.serviceCount === project.deliverableCount);
-   ```
-
-**Detection:**
-- Query: `SELECT COUNT(DISTINCT phase_count) FROM projects WHERE source_offer_id = 'offer_123'` — should be 1 (all instances have same structure)
-- Check: `SELECT project_id, COUNT(tasks) as task_count FROM projects JOIN phases USING(project_id) JOIN tasks USING(phase_id) GROUP BY project_id` — all projects from same offer should have identical task_count
-- Test: regenerate offer phases in a test project, compare structure to production instance
-
-**Phase to address:** Phase 7 (Catalog & Offers) for offer structure design; Phase 9 (CRM Won automation) for copy mechanism — finalize mapping BEFORE code
-
----
-
-### Pitfall 3: Public Quote Page Leaks Pricing via Token Enumeration
-
-**What goes wrong:**
-
-You create `/quote/[quoteToken]` (public URL, can be shared with prospects). Quote token is nanoid (21 chars, ~122 bits entropy). An attacker:
-
-1. Brute-forces quote tokens: 10 guesses/sec × 86400 sec/day ≈ 864K guesses/day
-2. After a few days, has enumerated all active quotes
-3. Builds pricing database: "This consultant charges €2500 for personal branding tier 1, €5000 for tier 2"
-4. Shares with competitors or uses against you in negotiations
-
-Also: if quote token leaks to wrong recipient (forwarded email, Slack channel, browser history), unauthorized access to pricing meant for one prospect only.
-
-**Why it happens:**
-
-- nanoid 21 chars is only ~122 bits entropy — decent for single-use tokens but weak against coordinated brute-force
-- You're not validating WHO requested the quote, just that token is valid (no email check, no IP restriction)
-- No rate limiting, so attacker can guess 1M tokens per day
-- No expiration, so old tokens are forever valid
-- No audit trail, so you don't know if a quote was accessed by wrong person until much later
-
-**Consequences:**
-
-- Pricing intelligence leaks to competitors
-- Confidential pricing becomes public (prospect #1 knows what prospect #2 was charged)
-- Client feels exposed/unprofessional (pricing is discoverable)
-- Legal risk: if quote was confidential, unauthorized access is a breach
-- Competitive disadvantage: prices visible to all competitors
-
-**Prevention:**
-
-1. **Token security hardening:**
-   - Use `nanoid(32)` or `nanoid(64)` instead of 21 (increases entropy from ~122 bits to ~190 bits)
-   - Add expiration: `quote_token_expires_at` (default 7 days, can be extended manually)
-   - Add activation state: token only becomes valid after admin explicitly sends it to contact
-   - Don't auto-generate tokens on quote creation; generate on-demand when admin clicks "Send quote"
-
-   ```typescript
-   // Quotes table:
-   // id, client_id, status (draft | sent | accepted | rejected)
-   // token (nullable until sent), token_expires_at, sent_to_email, created_at, sent_at
-   
-   const generateQuoteToken = () => nanoid(32);  // ~190 bits
-   
-   async function sendQuote(quoteId, contactEmail) {
-     return await db.update(quotes).set({
-       token: generateQuoteToken(),
-       token_expires_at: addDays(new Date(), 7),
-       status: 'sent',
-       sent_to_email: contactEmail,
-       sent_at: new Date()
-     }).where(eq(quotes.id, quoteId));
-   }
-   ```
-
-2. **Access control: email + token required:**
-   - Public page requires BOTH token AND email in URL or form
-   - Email validates that the person accessing is the intended recipient
-   - Endpoint signature: `/api/quote?token=[token]&email=[email]` (both required)
-   - Server validates: token belongs to quote AND quote.sent_to_email matches email
-   
-   ```typescript
-   GET /api/quote?token=...&email=contact@prospect.com
-   
-   const quote = await db.select().from(quotes)
-     .where(and(
-       eq(quotes.token, token),
-       eq(quotes.sent_to_email, email),
-       gt(quotes.token_expires_at, new Date()),
-       eq(quotes.status, 'sent')
-     ));
-   
-   if (!quote) return 401; // Unauthorized
-   ```
-
-3. **Rate limiting (prevents brute-force):**
-   - Max 3 views per token per minute (blocks scanning)
-   - Max 10 failed attempts per IP per hour (blocks enumeration)
-   - After rate limit hit, log alert: "Possible quote enumeration detected from IP X"
-
-   ```typescript
-   const rateLimitKey = `quote:${token}:views`;
-   const views = await redis.incr(rateLimitKey);
-   if (views > 3) {
-     return 429; // Too Many Requests
-   }
-   ```
-
-4. **Pricing visibility rules (CRITICAL CONSTRAINT):**
-   - Public quote page shows: client name, phase names, deliverables, TOTAL PRICE ONLY
-   - Per-service prices: NEVER visible (existing LOCKED constraint)
-   - `quote_items` table: NEVER serialized to public API response
-   - Server-side validation: assert response.quote_items === undefined before sending
-
-   ```typescript
-   // WRONG:
-   const quote = await db.select().from(quotes)
-     .where(eq(quotes.token, token));
-   return NextResponse.json(quote);  // Includes quote_items!
-   
-   // RIGHT:
-   const quote = await db.select({
-     id: quotes.id,
-     clientName: quotes.client_name,
-     totalPrice: quotes.total_price,  // sum only
-     phases: phases.title
-     // Do NOT select quote_items
-   }).from(quotes)
-     .where(and(...))
-     .leftJoin(phases, eq(phases.quote_id, quotes.id));
-   return NextResponse.json(quote);
-   ```
-
-5. **Audit trail for access:**
-   - Log every quote page view: `quote_views(quote_id, accessed_at, email, ip_hash, user_agent)`
-   - Alert admin if quote accessed from suspicious location (wrong country, multiple IPs, after hours)
-   - At minimum: count views per token, alert if >20 views (suggests enumeration)
-
-   ```typescript
-   await db.insert(quote_views).values({
-     quote_id: quote.id,
-     accessed_at: new Date(),
-     email: params.email,
-     ip_hash: hashIp(req.ip),
-     user_agent: req.headers['user-agent']
-   });
-   ```
-
-6. **Expiration enforcement:**
-   - Public page rejects expired tokens (7 days default)
-   - Admin can extend expiration if needed (e.g., "Give prospect 2 more weeks")
-   - Shows user: "This quote expired on [date]. Contact sales to request an updated quote."
-
-**Detection:**
-- Test with wrong email: `GET /api/quote?token=X&email=wrong@email.com` should return 401
-- Test after expiration: manually set token_expires_at to past date, should return 401
-- Test brute force: make 10 requests/second, should hit rate limit
-- Audit logs: search for tokens with >20 views, >5 unique emails, multiple IPs
-- Schema audit: verify quote_items not in public API response (code review)
-
-**Phase to address:** Phase 8 (Public Quote Pages) — implement all security controls IN PARALLEL with feature, not after
-
----
-
-## MODERATE PITFALLS (Major Refactor / Data Inconsistency)
-
-### Pitfall 4: Drag-and-Drop Sort Order Race Condition
-
-**What goes wrong:**
-
-Admin drags service B above service A in an offer phase, frontend sends `{ serviceId: B, sort_order: 1 }`. Meanwhile, another tab deletes service A, which auto-shifts all sort_orders down. The update succeeds, but now B and A have conflicting sort_orders: `[1, 1, 3, 4]`.
-
-Or: two browser tabs open the same offer. Admin in tab 1 drags service B up. Admin in tab 2 drags service C down. Both send updates concurrently. Server processes last write: tab 2's update. Tab 1's reorder is lost. Admin refreshes, sees different order.
-
-**Why it happens:**
-
-- Optimistic UI updates frontend immediately, sends async update to server
-- If server read-replica isn't synced, or if concurrent write happened between read and write, update applies to wrong baseline
-- `sort_order` is a simple integer with no version/conflict detection
-- No idempotency: if user clicks drag twice (accidental double-click), two updates sent
-
-**Consequences:**
-
-- Phase services display in wrong order intermittently (depends on which replica you hit)
-- Admin refreshes page, order changes again
-- After 3-4 drags by different admins, sort_orders become nonsensical: `[1, 3, 2, 5, 4]`
-- Clients see different phase structure depending on page cache; trust breaks
-- Audit: "Why did phase structure change?" — no record of who dragged what when
-
-**Prevention:**
-
-1. **Explicit versioning (optimistic locking):**
-   ```sql
-   ALTER TABLE offer_phases ADD COLUMN version INTEGER NOT NULL DEFAULT 0;
-   -- Every UPDATE increments version
-   ```
-   
-   ```typescript
-   // Update only if version matches:
-   const result = await db.update(offer_phases)
-     .set({
-       sort_order: newSortOrder,
-       version: sql`version + 1`
-     })
-     .where(and(
-       eq(offer_phases.id, phaseId),
-       eq(offer_phases.version, expectedVersion)  // Must match
-     ))
-     .returning();
-   
-   if (!result.length) {
-     // Version mismatch: conflict
-     return { status: 409, message: 'Offer changed, please refresh' };
-   }
-   ```
-   
-   Frontend stores `version` alongside phase data:
-   ```typescript
-   const [phases, setPhases] = useState(initialPhases); // includes version
-   
-   const onDrag = async (newOrder) => {
-     const oldVersion = phases[0].version;
-     setPhases([...newOrder]); // Optimistic
-     
-     const response = await updatePhase({
-       sort_order: newOrder[0].sort_order,
-       version: oldVersion
-     });
-     
-     if (response.status === 409) {
-       // Conflict, refresh
-       const refreshed = await getPhase();
-       setPhases(refreshed);
-       showNotification('Offer changed, reloaded latest');
-     }
-   };
-   ```
-
-2. **Server-side sort_order recomputation (no trusting client):**
-   - Don't trust client's sort_order value — recompute from actual order
-   - User says: "Move service B before service C"
-   - Server fetches all services in phase, recomputes all sort_orders atomically
-   
-   ```typescript
-   async function reorderService(phaseId, serviceId, newPosition) {
-     return await db.transaction(async (tx) => {
-       // Fetch all services in phase, ordered by sort_order
-       const services = await tx.select()
-         .from(phase_services)
-         .where(eq(phase_services.phase_id, phaseId))
-         .orderBy(phase_services.sort_order);
-       
-       // Find service and move to newPosition
-       const serviceIndex = services.findIndex(s => s.id === serviceId);
-       if (serviceIndex === -1) return null;
-       
-       const [movedService] = services.splice(serviceIndex, 1);
-       services.splice(newPosition, 0, movedService);
-       
-       // Recompute all sort_orders atomically
-       for (let i = 0; i < services.length; i++) {
-         await tx.update(phase_services)
-           .set({ sort_order: i })
-           .where(eq(phase_services.id, services[i].id));
-       }
-       
-       return services;
-     });
-   }
-   ```
-
-3. **Optimistic updates with reconciliation:**
-   ```typescript
-   const [optimisticPhases, setOptimisticPhases] = useState(phases);
-   const [serverVersion, setServerVersion] = useState(phases.version);
-   
-   const onDrag = async (reordered) => {
-     setOptimisticPhases(reordered); // Instant feedback
-     
-     const response = await updatePhase({
-       order: reordered.map(s => s.id),
-       version: serverVersion
-     });
-     
-     if (response.status === 409) {
-       // Refresh from server
-       const current = await getPhase();
-       setOptimisticPhases(current.services);
-       setServerVersion(current.version);
-     } else {
-       setServerVersion(response.version);
-     }
-   };
-   ```
-
-4. **Serialization: queue drag actions (nuclear option):**
-   - Queue drag-and-drop actions, process one at a time
-   - User feels slight slowdown if dragging fast
-   - Guarantees no concurrent updates
-
-   ```typescript
-   const dragQueue = [];
-   let dragging = false;
-   
-   const enqueueReorder = async (action) => {
-     dragQueue.push(action);
-     if (dragging) return;
-     
-     dragging = true;
-     while (dragQueue.length > 0) {
-       const action = dragQueue.shift();
-       await reorderService(action);
-     }
-     dragging = false;
-   };
-   ```
-
-**Detection:**
-- Test concurrent updates: open offer in 2 tabs, drag in tab 1, drag in tab 2 simultaneously, save both
-- Inspect database: `SELECT sort_order FROM offer_phase_services WHERE offer_phase_id = ? ORDER BY sort_order` — should be 0..n-1 with no gaps
-- Check logs: query for 409 Conflict responses (indicates version mismatch handled correctly)
-- Audit query: "Who dragged what when?" — log reorder actions with user/timestamp
-
-**Phase to address:** Phase 7 (Offer Builder — Drag & Drop) — implement versioning BEFORE UI ships, not after bugs appear
-
----
-
-### Pitfall 5: CRM "Win" Automation — Double-Click Creates Two Clients
-
-**What goes wrong:**
-
-Admin clicks "Mark as Won" on a lead, which triggers multi-step automation:
-```
-1. Create client (email, name)
-2. Create project (client_id)
-3. Copy offer phases → project phases
-4. Create 1-4 payments
-5. Mark lead.status = 'won'
-```
-
-User's connection times out, browser tab closes, or page doesn't load success feedback. Admin thinks it didn't work, clicks "Mark as Won" again. Now:
-- Two clients created (same email)
-- Two projects created
-- Two payment schedules
-- Lead shows as "won" (confusing)
-
-Billing chaos: which client to invoice? Which payment schedule is real? Can't issue refund without knowing which one.
-
-**Why it happens:**
-
-No idempotency key. The "Win" action is a non-idempotent POST that should be safe to retry but isn't. Network is unreliable — timeouts are normal. You can't tell if the first request succeeded or failed just by timeout. Multi-step workflows can partially fail (client creation succeeds, project creation fails), leaving inconsistent state.
-
-**Consequences:**
-
-- Duplicate clients in system, different tokens (prospect receives two dashboard links)
-- Duplicate projects and payments, confusing admin dashboard KPIs
-- CRM status shows client as "won" but two projects exist (audit trail broken)
-- Refund process impossible: which payment to reverse?
-- Data Safety violation: can't trace which project is authoritative
-
-**Prevention:**
-
-1. **Idempotency key pattern (CRITICAL for all multi-step workflows):**
-   ```sql
-   -- CRM leads table:
-   -- id, email, status, offer_id, idempotency_key (nanoid, unique), 
-   -- client_id (nullable), project_id (nullable), created_at
-   
-   ALTER TABLE crm_leads ADD COLUMN idempotency_key TEXT UNIQUE NOT NULL;
-   ```
-   
-   ```typescript
-   async function markLedAsWon(leadId) {
-     const lead = await db.select().from(crm_leads)
-       .where(eq(crm_leads.id, leadId));
-     
-     const idempotencyKey = lead.idempotency_key;
-     
-     return await db.transaction(async (tx) => {
-       // Check: is this key already processed?
-       const existing = await tx.select().from(crm_leads)
-         .where(and(
-           eq(crm_leads.idempotency_key, idempotencyKey),
-           isNotNull(crm_leads.client_id)
-         ));
-       
-       if (existing.length > 0) {
-         // Already won, return existing IDs
-         return {
-           status: 'already_processed',
-           clientId: existing[0].client_id,
-           projectId: existing[0].project_id
-         };
-       }
-       
-       // First time: create client + project + phases + payments
-       const client = await tx.insert(clients).values({
-         name: lead.email,
-         brand_name: lead.company_name,
-         brief: lead.notes,
-         // ... rest of fields
-       }).returning();
-       
-       const project = await tx.insert(projects).values({
-         client_id: client.id,
-         name: lead.email,
-         accepted_total: lead.quote_total
-       }).returning();
-       
-       // Copy phases from offer
-       await copyOfferToProject(lead.offer_id, project.id, tx);
-       
-       // Create payments (e.g., 50% deposit, 50% balance)
-       const paymentPlan = calculatePaymentPlan(lead.quote_total);
-       for (const payment of paymentPlan) {
-         await tx.insert(payments).values({
-           project_id: project.id,
-           label: payment.label,
-           amount: payment.amount,
-           status: 'da_saldare'
-         });
-       }
-       
-       // Mark lead won LAST (proof that all steps succeeded)
-       await tx.update(crm_leads).set({
-         status: 'won',
-         client_id: client.id,
-         project_id: project.id
-       }).where(eq(crm_leads.id, leadId));
-       
-       return {
-         status: 'success',
-         clientId: client.id,
-         projectId: project.id
-       };
-     });
-   }
-   ```
-   
-   Transaction guarantees: either ALL steps succeed, or ALL rollback. No partial state.
-
-2. **Idempotency on browser side (preserve key across retries):**
-   ```typescript
-   const [idempotencyKey] = useState(() => localStorage.getItem('winLead_key') || nanoid());
-   
-   const handleWinLead = async () => {
-     localStorage.setItem('winLead_key', idempotencyKey); // Persist key
-     
-     try {
-       const response = await markAsWon(leadId, idempotencyKey);
-       if (response.status === 'success' || response.status === 'already_processed') {
-         localStorage.removeItem('winLead_key'); // Clear key
-         navigate(`/admin/projects/${response.projectId}`);
-       }
-     } catch (e) {
-       showNotification('Failed to mark won. Retrying...');
-       // Retry will use same key — safe due to idempotency
-     }
-   };
-   ```
-
-3. **UI pattern: disable button until success**
-   ```typescript
-   const [loading, setLoading] = useState(false);
-   
-   return (
-     <button 
-       onClick={handleWinLead}
-       disabled={loading}
-     >
-       {loading ? 'Processing...' : 'Mark as Won'}
-     </button>
-   );
-   ```
-   
-   Button disabled immediately after click, prevents double-click. Only re-enabled on success (not on error).
-
-4. **Partial failure handling (if some step fails):**
-   - Transaction handles atomic all-or-nothing
-   - BUT: if transaction itself fails (network before commit), idempotency key ensures retry works
-   - If you need to investigate failure: client created but project creation failed, don't delete partial data
-   - Instead: mark client as `status: 'partial_onboarding'`, show admin a recovery UI: "Complete onboarding?" button
-
-   ```typescript
-   // Check for partial onboarding
-   const lead = await getLeadWithClient(leadId);
-   if (lead.client_id && !lead.project_id) {
-     return (
-       <div>
-         <p>Onboarding incomplete. Client created, but project missing.</p>
-         <button onClick={() => completeOnboarding(lead)}>
-           Complete Onboarding
-         </button>
-       </div>
-     );
-   }
-   ```
-
-**Detection:**
-- Query for duplicate clients by email: `SELECT email, COUNT(*) FROM clients GROUP BY email HAVING COUNT(*) > 1`
-- Check leads.idempotency_key: every record should have one, none should be NULL
-- CRM audit log: "Win" action should appear exactly ONCE per lead, even if endpoint was called 10 times (due to retries)
-- Payment audit: project should have exactly 2–4 payments (not 8), based on payment plan
-
-**Phase to address:** Phase 9 (CRM Won Automation) — implement idempotency in API design BEFORE feature ships, not after data corruption
-
----
-
-### Pitfall 6: Offer Phase Copy Doesn't Copy Task Deliverables
-
-**What goes wrong:**
-
-Offer structure: offer_micros (marketing tiers) have no tasks/deliverables (they're just labels for groups of services).
-
-When you "Win" and copy to project, you need to:
-```
-offer_micros (Signature A) 
-  → project_phases (Phase 1)
-      → project_tasks (Competitor audit, Design deliverables)
-          → deliverables (Audit report.pdf, Wireframes.pdf)
-```
-
-But you copy only phases, forget to copy tasks. Or you copy tasks but forget deliverables. Or you copy deliverables but forget to set `task_id` correctly (NULL or wrong phase's task ID).
-
-Result: client dashboard shows phase with no tasks (blank), or tasks with no deliverables (can't approve anything).
-
-**Why it happens:**
-
-Offer structure is marketing (macro → micro → services). Project structure is execution (phases → tasks → deliverables). They don't map 1:1. You're confused about the mapping:
-- Is offer_micro a project_phase? (Probably)
-- Are offer_services the deliverables? Or are they task descriptions? (Unclear)
-- Do you create one task per service, or group services into tasks? (Undefined)
-
-You guess, implement halfway, realize it's broken when client can't approve.
-
-**Consequences:**
-
-- Client dashboard shows phases with no tasks/deliverables (looks broken)
-- Client can't see what they're supposed to approve
-- Admin must manually recreate deliverables (tedious, error-prone)
-- Audit trail broken: "what was promised in the offer?" vs "what's in the project?" diverge
-- Multiple projects from same offer have different deliverable structures (inconsistent)
-
-**Prevention:**
-
-1. **Define hierarchies explicitly IN WRITING (document as code):**
-   ```typescript
-   // Type definitions make mapping explicit
-   interface OfferStructure {
-     micros: {  // e.g., "Signature A", "Signature B"
-       id: string;
-       public_name: string;
-       services: {  // e.g., "Competitor audit", "Brand strategy"
-         id: string;
-         name: string;
-         transformation_description: string;
-       }[];
-     }[];
-   }
-   
-   interface ProjectStructure {
-     phases: {  // e.g., "Discovery", "Design", "Launch"
-       id: string;
-       title: string;
-       tasks: {  // e.g., "Conduct competitor audit"
-         id: string;
-         title: string;
-         deliverables: {  // e.g., "Audit report"
-           id: string;
-           title: string;
-           description: string;
-         }[];
-       }[];
-     }[];
-   }
-   
-   // Mapping rule (explicit):
-   // 1 offer_micro → 1 project_phase (keep titles)
-   // 1 offer_service → 1 project_task → 1 project_deliverable
-   ```
-
-2. **Explicit copy function with validation:**
-   ```typescript
-   async function copyOfferToProject(offerId: string, projectId: string) {
-     const offer = await getOfferWithAllNested(offerId);
-     
-     return await db.transaction(async (tx) => {
-       const result = {
-         phasesCreated: 0,
-         tasksCreated: 0,
-         deliverablesCreated: 0
-       };
-       
-       // For each offer micro:
-       for (const micro of offer.micros) {
-         const phase = await tx.insert(phases).values({
-           project_id: projectId,
-           title: micro.public_name,
-           sort_order: micro.sort_order
-         }).returning();
-         result.phasesCreated++;
-         
-         // For each service in this micro, create a task + deliverable:
-         for (const service of micro.services) {
-           const task = await tx.insert(tasks).values({
-             phase_id: phase.id,
-             title: service.name,
-             description: service.transformation_description,
-             sort_order: 0
-           }).returning();
-           result.tasksCreated++;
-           
-           // Service description → 1 deliverable
-           const deliverable = await tx.insert(deliverables).values({
-             task_id: task.id,
-             title: `${service.name} Deliverable`,
-             description: service.transformation_description,
-             status: 'pending'
-           }).returning();
-           result.deliverablesCreated++;
-         }
-       }
-       
-       return result;
-     });
-   }
-   ```
-
-3. **Validation: count check (integration test):**
-   ```typescript
-   const offer = await getOfferWithCounts(offerId);
-   const result = await copyOfferToProject(offerId, projectId);
-   
-   assert(result.phasesCreated === offer.micros.length);
-   assert(result.tasksCreated === offer.totalServices);
-   assert(result.deliverablesCreated === offer.totalServices);
-   
-   // Verify foreign keys:
-   const deliverables = await db.select()
-     .from(deliverables_table)
-     .where(in(deliverables_table.task_id, 
-               await db.select().from(tasks).where(eq(tasks.phase_id, ...))));
-   
-   assert(deliverables.every(d => d.task_id !== null));
-   ```
-
-4. **Test scenario in integration tests:**
-   ```typescript
-   it('copies offer with 3 micros, 2 services each into project', async () => {
-     const offer = await createTestOffer({
-       micros: [
-         { services: ['Audit', 'Strategy'] },
-         { services: ['Design', 'Copy'] },
-         { services: ['Launch', 'Training'] }
-       ]
-     });
-     
-     const project = await createTestProject();
-     const result = await copyOfferToProject(offer.id, project.id);
-     
-     expect(result.phasesCreated).toBe(3);
-     expect(result.tasksCreated).toBe(6);
-     expect(result.deliverablesCreated).toBe(6);
-     
-     // Verify structure
-     const phases = await getProjectPhases(project.id);
-     expect(phases[0].tasks.length).toBe(2);
-     expect(phases[0].tasks[0].deliverables.length).toBe(1);
-   });
-   ```
-
-**Detection:**
-- Query projects from same offer for structure consistency:
-  ```sql
-  SELECT project_id, COUNT(DISTINCT phases) as phase_count, COUNT(tasks) as task_count
-  FROM projects JOIN phases USING(project_id) JOIN tasks USING(phase_id)
-  WHERE source_offer_id = 'offer_123'
-  GROUP BY project_id;
-  -- All rows should have identical phase_count and task_count
-  ```
-
-- Find projects with missing deliverables:
-  ```sql
-  SELECT p.id FROM projects p
-  JOIN phases ph ON p.id = ph.project_id
-  JOIN tasks t ON ph.id = t.phase_id
-  LEFT JOIN deliverables d ON t.id = d.task_id
-  WHERE d.id IS NULL AND p.source_offer_id IS NOT NULL;
-  ```
-
-**Phase to address:** Phase 7 (Catalog & Offers) for offer structure design; Phase 9 (CRM/Quotes) for copy mechanism — define mapping BEFORE implementation
-
----
-
-## MINOR PITFALLS (Operational Friction)
-
-### Pitfall 7: Offer Builder State Not Synchronized Between Tabs
-
-**What goes wrong:**
-
-Admin edits offer "Signature A" in tab 1, adds a new service to a phase. Tab 2 still shows old offer structure (no service). Admin in tab 2 tries to drag a service, the dragged service doesn't exist in tab 1's state. Or: tabs are editing the same offer simultaneously, last save wins, first admin's work is lost silently.
-
-**Why it happens:**
-
-No real-time sync or conflict detection. SPA loads offer once, edits in memory, saves. If same user opens offer in another tab, it doesn't know about changes in tab 1.
-
-**Consequences:**
-
-- Admin's edits silently overwritten
-- Offer structure becomes inconsistent
-- Frustration: "I added a service, but it's not there"
-- For solo consultant (only user), not critical but annoying
-
-**Prevention:**
-
-1. **Conflict detection on save:**
-   - Load offer with `version` field (integer, incremented on every update)
-   - On save, check: `WHERE id = ? AND version = ?`
-   - If version mismatch, return 409 Conflict with server's current version
-   - UI shows: "Offer changed elsewhere. Reload?"
-
-2. **Session-level locking (optional, for future multi-user):**
-   - Add `locked_by: uuid | null` to offer_micros
-   - When editing, lock: `UPDATE offers SET locked_by = ?, locked_at = NOW()`
-   - When saving, unlock
-   - If another session tries to edit locked offer, show: "Being edited elsewhere"
-
-3. **Message broadcast (optional, for future real-time):**
-   - WebSocket or polling to broadcast changes between tabs
-   - Only worth it if multi-user editing becomes common
-
-**Detection:**
-- Open offer in 2 tabs, edit in both, save in sequence
-- Check: which version is final? (should be tab 2's, not tab 1's)
-- Verify version field increments
-
-**Phase to address:** Phase 7 (Offer Builder) — add versioning when form shipped, not after conflicts discovered
-
----
-
-### Pitfall 8: Backward Incompatibility When Adding CRM Lead Fields
-
-**What goes wrong:**
-
-You add new schema fields to CRM leads: `source, budget, next_follow_up_date`. Existing lead records have NULL for these. New code assumes fields have values, crashes:
-```
-const budget = lead.budget * 1000;  // TypeError: Cannot read property '*' of null
-```
-
-Or you rename `lead_status` to `status`, old API calls still use `lead_status`, code path breaks.
-
-**Why it happens:**
-
-Schema changes are additive but code changes aren't. You add a column, then deploy code that assumes the field is populated. Existing records don't have the field populated, so assumptions break.
-
-**Consequences:**
-
-- Admin dashboard crashes when loading old leads
-- API returns unexpected shape
-- Code that expects fields gets NULL, calculations fail
-- Rollback is hard because you can't easily undo schema changes
-
-**Prevention:**
-
-1. **Expand-Contract migration pattern:**
-   ```
-   Phase A (Expand):
-   - Add new column as NULLABLE: ALTER TABLE crm_leads ADD COLUMN budget NUMERIC NULL;
-   - Deploy code that handles both: lead.budget ?? lead.legacy_budget ?? 0
-   - Backfill old records: UPDATE crm_leads SET budget = 0 WHERE budget IS NULL;
-   
-   Phase B (Contract):
-   - Once all records have budget, add NOT NULL: ALTER TABLE crm_leads ALTER COLUMN budget SET NOT NULL;
-   - Remove old code that handles NULL
-   - Only then can you safely drop legacy_budget column
-   ```
-
-2. **Defensive code (handles NULL gracefully):**
-   ```typescript
-   // WRONG: assumes budget always populated and is a number
-   const budgetLabel = (lead.budget / 1000).toFixed(2);
-   
-   // RIGHT: handles NULL and migration
-   const leadBudget = lead.budget ?? lead.legacy_budget ?? 0;
-   const budgetLabel = (leadBudget / 1000).toFixed(2);
-   ```
-
-3. **Schema versioning:**
-   - Track in `settings` table: `{ key: 'schema_version', value: '9' }`
-   - Code checks version and handles old shapes
-   - Prevents schema-and-code mismatches
-
-4. **Migration test:**
-   - After adding column, backfill, run query: `SELECT COUNT(*) FROM crm_leads WHERE budget IS NULL` — should be 0
-   - Add NOT NULL constraint only after validation
-   - Test with production-like data (old NULLs) in test database
-
-**Detection:**
-- Test with production data: copy production leads to test db, run new code against them
-- Query for NULL fields: `SELECT COUNT(*) FROM crm_leads WHERE budget IS NULL OR source IS NULL`
-- Code review: search for assumptions (e.g., `lead.budget.toFixed()` without null check)
-
-**Phase to address:** Phase 9 (CRM) — plan all schema changes first, execute Expand-Contract carefully
-
----
-
-### Pitfall 9: Scope Creep — Building GoHighLevel Instead of Solo-Consultant Tool
-
-**What goes wrong:**
-
-You start building CRM with: leads, statuses, follow-up reminders. Then:
-- "Should add email templates" (30 hours)
-- "Should track calls" (40 hours)
-- "Should integrate with calendar" (20 hours)
-- "Should score leads by engagement" (50 hours)
-- "Should have team assignments" (60 hours)
-- "Should send bulk emails" (40 hours)
-
-18 months later CRM is 40% done, other features blocked, and you're building Salesforce for one person.
-
-**Why it happens:**
-
-CRM is unbounded feature space. Every CRM ever adds more features. You imagine the "complete" product and feel like MVP is missing pieces. Also, features are tempting: "just add X" sounds quick (it's not).
-
-**Consequences:**
-
-- CRM Phases 9–12 never ship (stuck in feature bloat)
-- Other priorities (catalog, quotes, public pages) delayed indefinitely
-- Code complexity explodes, maintenance burden increases
-- Solo consultant doesn't actually use 90% of features (nice-to-haves)
-- Real problem (lead pipeline visibility) gets 1/10 of attention it deserves
-
-**Prevention:**
-
-1. **Explicit scope document with Must/Should/Could/Won't (MoSCoW):**
-   
-   **MUST HAVE (v2.0 — shipped in Phase 9):**
-   - Lead status pipeline: New → Contacted → Quoted → Won/Lost
-   - Quote prerequisite: can't win without attaching quote
-   - Auto-create client + project on Won
-   - Follow-up reminders in dashboard: "You haven't contacted [prospect] in 5 days"
-   - Mark as lost (deal rejected)
-   
-   **SHOULD HAVE (v2.1 — later milestone, if time):**
-   - Email template system (for follow-up messages)
-   - Call logging: date, outcome, next step
-   - Lead source tracking: website, referral, cold outreach
-   
-   **COULD HAVE (nice-to-haves, only if free time):**
-   - Email campaign automation (use Mailchimp for this)
-   - Lead scoring/AI ranking (premature optimization)
-   - Custom fields (overkill for solo practice)
-   
-   **WON'T HAVE (explicitly out of scope for solo consultant v2.0):**
-   - Multi-user team assignments (only you)
-   - Lead distribution/queuing (not relevant)
-   - Call recording integration (use Calendly/Zoom for this)
-   - Bulk import/export (you add leads one at a time)
-   - Webhook integrations to other tools (complexity tax)
-   - CRM API for integrations (premature)
-   - Reporting/dashboards beyond KPI dashboard (already exists)
-
-2. **Success criteria by feature, not by feature count:**
-   - MVP v2.0 success: "Can I go from cold lead to won project in <30 minutes without manual work?"
-   - Success metric: "Did I use this CRM feature >2x per week?"
-   - If not used, remove it (don't carry dead weight)
-
-3. **Ruthless scope boundary questions:**
-   - "Is this essential for lead → quote → won → project workflow?"
-   - "Will I actually use this weekly?"
-   - "Does this directly serve the solo consultant (not a 50-person sales team)?"
-   - If no, defer to v2.1 or later (or never)
-
-4. **Feature prioritization by impact:**
-   - Tier 1 (must ship): lead pipeline, quote attachment, auto-onboarding
-   - Tier 2 (ship if time): follow-up reminders, source tracking
-   - Tier 3 (defer): templates, scoring, integrations
-
-**Detection:**
-- Review Phase 9 spec: count "must" vs "should" vs "could" vs "won't"
-- If "could" list is longer than "must" list, scope creep is happening
-- After v2.0 ships, audit actual usage weekly: which CRM features did you use?
-- If >15% of features unused, that's scope creep aftermath
-
-**Phase to address:** Phase 9 (CRM) planning — before design, agree on exact boundaries and document in Must/Should/Won't categories
-
----
-
-## Phase-Specific Warnings
-
-| Phase | Feature | Likely Pitfall | Mitigation |
-|-------|---------|---------------|-----------|
-| 7 | Catalog consolidation | Orphaned quote_items, broken price snapshots | Expand-Contract migration; dual writes; verify referential integrity before contract |
-| 7 | Offer builder (drag-drop) | Sort order race conditions, conflicting versions | Add version field; use optimistic locking; recompute server-side |
-| 7 | Copy offer to offer tier | Template mutation, partial copies, missing tasks | Atomic transaction for entire tree; deep copy; integration tests |
-| 8 | Public quote pages | Token enumeration, pricing leakage, unauthorized access | Longer tokens (32+ chars); expiration; email validation; rate limiting; never include quote_items |
-| 8 | Quote acceptance | Double-processing (accepted twice) | Add unique constraint on (quote_id, lead_id); prevent concurrent accepts |
-| 9 | CRM "Win" automation | Double-click creates duplicate clients | Idempotency key pattern; atomic transaction; disable button until success |
-| 9 | CRM schema changes | Backward incompatibility (NULL field handling) | Expand-Contract pattern; defensive code; backfill validation before NOT NULL |
-| 9 | CRM scope definition | Feature bloat, never ships | Explicit Must/Should/Could/Won't scope document; measure actual usage; ruthless pruning |
-
----
-
-## Integration Pitfalls (Cross-Feature)
-
-### Data Consistency: Offer Promise vs. Project Execution
-
-**Risk:** CRM wins, creates project with copied phases. Admin later edits project deliverables (changes requirements). Client dashboard shows updated requirements, but the original "promise" (in offer) is now different. Client approval audit trail is broken.
-
-**Mitigation:**
-- Store immutable offer snapshot in project_offers row: `offer_snapshot: JSONB`
-- Client dashboard shows BOTH offer promise and project execution in parallel
-- Admin must explicitly accept client's approval of any changes
-- Audit log every project change with reason (scope change, typo fix, etc.)
-
----
-
-### Token Security Across Client/Public Surfaces
-
-**Risk:** Two token-based surfaces:
-- `/client/[token]` (confidential project dashboard, 21 chars)
-- `/quote/[quoteToken]` (public semi-confidential, 32 chars)
-
-If validation is inconsistent, one surface may leak data the other guards.
-
-**Mitigation:**
-- Centralized token validation middleware
-- Different token lengths (client 21, quote 32) to distinguish in logs
-- Rate-limit both surfaces separately; detect enumeration attempts
-- Test both with wrong/expired/tampered tokens
-
----
-
-### Payment State Consistency After Partial Failure
-
-**Risk:** CRM "Win" creates client, project, and 1–4 payments in transaction. If payment creation partially succeeds (1 of 3 created, then error), payment schedule is broken.
-
-**Mitigation:**
-- ALL-OR-NOTHING transaction (shown in Pitfall 5)
-- Payment initialization is deterministic: same total + plan = same payments
-- Retry is idempotent: re-running creates same payments (no duplicates)
-- Admin dashboard shows: "Payment setup incomplete, retry?" with clear status
-
----
-
-## Recommended Research/Validation for Each Phase
-
-| Phase | Topic | Validation | Owner |
-|-------|-------|-----------|-------|
-| 7 | Migration safety | Dry-run consolidation on prod DB backup; verify referential integrity | Dev |
-| 7 | Offer hierarchies | Document offer vs project structure mapping explicitly | Product + Dev |
-| 7 | Drag-drop conflicts | Load test concurrent edits; verify sort_order integrity | QA |
-| 8 | Token security | Brute-force test, enumeration test, leakage test on public page | Security review |
-| 8 | Public page access | Test token expiration, email validation, rate limiting | QA |
-| 9 | CRM idempotency | Test double-click, network failures, partial recovery | QA + Dev |
-| 9 | Scope validation | Review Must/Should/Won't with user; mark priorities | Product |
-| 9 | Payment consistency | Test partial failures, rollback scenarios, retry idempotency | Dev + QA |
-
----
-
-## Sources
-
-- [Data Migration Testing: A Complete Guide](http://migravion.com/blog/data-migration-testing-guide)
-- [Maintaining Data Integrity During Migration — Plane Blog](https://plane.so/blog/maintaining-data-integrity-during-migration)
-- [Optimistic Updates: State-Based and Render-Based Approaches](https://www.nirtamir.com/articles/optimistic-updates-state-vs-render/)
-- [Optimistic UI Without Lying: React 19 Blueprint](https://www.7tech.co.in/react-optimistic-ui-blueprint-conflict-safe-mutations/)
-- [The Double-Click Problem: How Idempotency Saved Our Checkout System](https://codefarm0.medium.com/the-double-click-problem-how-idempotency-saved-our-checkout-system-a704be65d207)
-- [Idempotency in software: Designing Systems to Safely Retry](https://emmanuelvalverderamos.substack.com/p/idempotency-in-software-designing)
-- [Zero-Downtime Postgres Migrations with Drizzle ORM](https://dev.to/whoffagents/zero-downtime-postgres-migrations-with-drizzle-orm-22ga)
-- [Backward Compatibility in Schema Evolution: Guide](https://www.dataexpert.io/blog/backward-compatibility-schema-evolution-guide)
-- [How to Avoid Scope Creep and Misalignment When Launching MVP](https://medium.com/swlh/the-one-map-you-need-to-avoid-scope-creep-and-align-stakeholders-c4763789eeda)
-- [Best CRM for Consultants & Freelancers (2026 Guide)](https://www.authencio.com/blog/best-crm-for-consultants-freelancers-guide)
-- [Defending OAuth: Common Attacks and Prevention](https://workos.com/blog/oauth-common-attacks-and-how-to-prevent-them/)
-- [Token Leakage Via Referer — Pentest Vulnerability Wiki](https://www.cobalt.io/vulnerability-wiki/v4-access-control/token-leakage-referer)
-- [Transactional Locking to Prevent Race Conditions](https://sqlfordevs.com/transaction-locking-prevent-race-condition)
diff --git a/.planning/research/SUMMARY.md b/.planning/research/SUMMARY.md
deleted file mode 100644
index 50bb900..0000000
--- a/.planning/research/SUMMARY.md
+++ /dev/null
@@ -1,126 +0,0 @@
-# Project Research Summary
-
-**Project:** ClientHub — welcomeclient.iamcavalli.net
-**Domain:** Freelancer client portal (secret-link access, solo consultant)
-**Researched:** 2026-05-09
-**Confidence:** HIGH
-
----
-
-## Executive Summary
-
-ClientHub è un portale web a due ruoli per un consulente di personal branding. I clienti accedono via UUID segreto casuale — nessun account, nessun login, zero attrito. L'admin gestisce tutto: crea clienti, fasi, task, deliverable, pagamenti e preventivi. Il consensus della ricerca è chiaro: costruisci prima la dashboard cliente, poi l'admin CRUD, poi catalogo servizi e preventivi, poi il flusso Claude AI (v2).
-
-Stack confermato: **Next.js 15 + Neon (Postgres) + Drizzle ORM + Auth.js + nanoid + Tailwind v4 + shadcn/ui**. Ogni scelta è ottimizzata per un developer solo su Vercel: nessun backend da mantenere, nessun costo di connection pooling, nessuna infrastruttura di upload file, nessuna libreria di auth per i clienti. Il meccanismo "secret link" è un Next.js Middleware edge check — veloce, zero client JS, 404 se il token non esiste.
-
-I rischi dominanti sono architetturali, non tecnici. Se il token è la primary key diventa non-rotazionabile. Se la client API restituisce `quote_items` (anche nascosti nell'UI), un cliente con DevTools vede i prezzi dei singoli servizi. Se il progetto parte dal flusso Claude prima che un cliente possa aprire la sua dashboard, il portale non esce. Tutti e tre prevenibili con le decisioni corrette sul data model dal giorno uno.
-
----
-
-## Key Findings
-
-### Stack Raccomandato
-
-| Tecnologia | Ruolo | Perché |
-|------------|-------|--------|
-| Next.js 15 (App Router) | Framework full-stack | Server Actions sostituiscono un'API REST separata; nativo Vercel |
-| Neon (serverless Postgres) | Database principale | Free tier (0.5 GB, 100 CU-h/mese) sufficiente per 5–20 clienti; scala a zero |
-| Drizzle ORM + neon-http | Accesso DB + migrazioni | Nessun costo di connection pooling; schema-as-code; inferenza TypeScript end-to-end |
-| Auth.js v4 (Credentials) | Sessione admin | Account singolo, cookie JWT firmato, nessuna tabella utenti in DB |
-| nanoid | Generazione token | 21 char, ~126 bit di entropia, URL-safe, crittograficamente sicuro |
-| Tailwind v4 + shadcn/ui | UI | Componenti copiati nel codebase, accessibilità Radix UI, zero runtime dep |
-| Zod + React Hook Form | Validazione e form | Schema unico; RHF solo per form admin complessi |
-
-File upload deliberatamente esclusi dalla v1. I link ai documenti sono campi testo che puntano a Google Drive.
-
-### Features v1
-
-**Table stakes (obbligatori):**
-- Panoramica progetto (nome, brand, brief, fase corrente)
-- Visibilità fasi e task con stato (todo / in corso / fatto)
-- Approvazione deliverable con timestamp immutabile
-- Commenti inline su task e deliverable (lista piatta, no threading)
-- Link a documenti esterni (solo URL, no file hosting)
-- Stato pagamenti: acconto 50% + saldo 50% (da saldare / inviata / saldato)
-- Totale preventivo accettato visibile al cliente (cifra unica, mai dettaglio)
-- Layout mobile-ready
-- Link segreto persistente e non-scadente
-
-**Differenziatori (low-effort, includibili in v1):**
-- Log decisioni / storico (nota append-only)
-- Indicatore di avanzamento fase (derivato da % task completati)
-- Timestamp "ultimo aggiornamento" sulla dashboard
-- Vista admin: tutti i clienti con badge stato pagamenti
-- Reset link segreto (single UPDATE, solo admin)
-
-**Anti-features (mai costruire):** login cliente, PDF fatture in-app, multi-admin, struttura progetto modificabile dal cliente, prezzi singoli visibili al cliente, kanban board.
-
-### Architettura
-
-Singola applicazione Next.js su Vercel, un database Neon Postgres. Nessun backend separato.
-
-**Due path di accesso isolati:**
-- `/c/[token]/*` → Middleware valida il token contro Neon, 404 se mancante
-- `/admin/*` → Auth.js session check, singolo account admin
-
-**Decisioni chiave del data model:**
-- `clients.token` è un campo separato e rotazionabile — **non** la primary key
-- `clients.accepted_total` denormalizzato: la client API non tocca mai `quote_items`
-- `deliverables.approved_at` come audit trail immutabile dal giorno uno
-- `payments` sempre due righe per cliente (acconto + saldo), create alla finalizzazione del preventivo
-- `ClientView` e `AdminView` sono tipi distinti lato server — privacy enforce a livello di query, non di UI
-
-### Pitfall Critici
-
-1. **Token = primary key (non rotazionabile)** — Usa UUID stabile come PK e campo `token` separato e aggiornabile. Deve essere nella schema della Fase 1; non si può correggere dopo che i link sono stati distribuiti.
-2. **Client API espone `quote_items` (nascosti solo nell'UI)** — Definisci `ClientView` come tipo server-side che non interroga mai `quote_items`. Un cliente tecnico con DevTools non deve mai vedere i prezzi singoli.
-3. **Over-engineering prima che un cliente usi il portale** — Criterio di successo duro per la Fase 1: un link cliente reale è condivisibile e funziona. Non iniziare il flusso Claude prima che l'admin possa creare un cliente e il cliente possa aprire la sua dashboard.
-4. **Nessun record di approvazione immutabile** — Salva `approved_at` (timestamp, non solo boolean) dallo schema iniziale.
-5. **Area admin senza vera autenticazione** — Il check Middleware su `ADMIN_PASSWORD` env var deve essere in place prima che la Fase 2 vada in produzione.
-
----
-
-## Implicazioni per la Roadmap
-
-### Struttura suggerita: 4 fasi
-
-**Fase 1 — Foundation: DB schema, token API, dashboard cliente**
-Consegna: un link cliente reale condivisibile che mostra il progetto su mobile e desktop.
-Copre: panoramica, fasi/task, pagamenti, documenti, link segreto, DNS.
-
-**Fase 2 — Admin CRUD + auth + commenti + approvazioni**
-Consegna: admin crea/modifica clienti, fasi, task, deliverable, pagamenti. Cliente commenta e approva. Admin può rigenerare il link.
-Copre: auth Middleware, CRUD completo, flow approvazione con timestamp, commenti lista piatta.
-
-**Fase 3 — Catalogo servizi + preventivi**
-Consegna: admin costruisce catalogo riutilizzabile e compone preventivi da esso. `accepted_total` scritto sulla riga cliente.
-Nessuna dipendenza client-facing oltre `accepted_total` (già in schema dalla Fase 1).
-
-**Fase 4 (v2) — Flusso Claude AI per onboarding**
-Dipende da CRUD stabile + catalogo completo. Claude legge il brief e suggerisce fasi + preventivo.
-*Richiede ricerca dedicata durante la pianificazione.*
-
-### Flag di ricerca
-- Fasi 1–3: pattern standard, nessuna ricerca aggiuntiva necessaria
-- Fase 4: richiede ricerca su Claude API structured output, streaming vs batch, prompt engineering per generazione fasi
-
----
-
-## Confidence Assessment
-
-| Area | Confidence | Note |
-|------|------------|------|
-| Stack | HIGH | Tutte le tecnologie stabili e in produzione |
-| Features | HIGH | Feature set opinionated e ben delimitato |
-| Architettura | HIGH | Data model completo, pattern two-path auth provato |
-| Pitfall | HIGH | Tutti mappabili a decisioni concrete della Fase 1 |
-
-**Domande aperte (da risolvere durante la pianificazione delle fasi):**
-- Access log per i link (utile per rilevare accessi non autorizzati)?
-- Approvazioni reversibili (admin-only revoke)?
-- Log decisioni visibile al cliente dalla v1 o solo admin?
-- DNS: configurare e verificare la propagazione nella Fase 1
-
----
-
-*Ricerca completata: 2026-05-09 | Pronto per la roadmap: sì*
\ No newline at end of file
diff --git a/.planning/SECURITY-AUDIT-INFRA.md b/.planning/security/SECURITY-AUDIT-INFRA.md
similarity index 100%
rename from .planning/SECURITY-AUDIT-INFRA.md
rename to .planning/security/SECURITY-AUDIT-INFRA.md
diff --git a/.planning/SECURITY-REMEDIATION-PLAN.md b/.planning/security/SECURITY-REMEDIATION-PLAN.md
similarity index 100%
rename from .planning/SECURITY-REMEDIATION-PLAN.md
rename to .planning/security/SECURITY-REMEDIATION-PLAN.md
diff --git a/.planning/SECURITY-SCAN.md b/.planning/security/SECURITY-SCAN.md
similarity index 100%
rename from .planning/SECURITY-SCAN.md
rename to .planning/security/SECURITY-SCAN.md