From 7192f5e82a481950b2ab714ede92d256f2af8e79 Mon Sep 17 00:00:00 2001
From: Simone Cavalli <simonecavalli@MacBook-Air-di-Simone.local>
Date: Wed, 13 May 2026 10:44:13 +0200
Subject: [PATCH] docs: create roadmap (4 phases)

---
 CLAUDE.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..32a0a72
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,50 @@
+# ClientHub — Project Instructions
+
+## Project
+
+**ClientHub** — Portale clienti per consulente di personal branding.
+- Dashboard cliente via link segreto (no login)
+- Admin area per gestione clienti, fasi, task, deliverable, pagamenti
+- Deploy: Vercel su `welcomeclient.iamcavalli.net`
+
+## GSD Workflow
+
+This project uses the **Get Shit Done** workflow. Planning lives in `.planning/`.
+
+### Current State
+
+See `.planning/STATE.md` for current phase and active work.
+See `.planning/ROADMAP.md` for full phase structure.
+See `.planning/REQUIREMENTS.md` for all requirements with REQ-IDs.
+
+### Phase Execution
+
+- Run `/gsd-plan-phase N` to plan a phase before executing
+- Run `/gsd-execute-phase N` to execute a planned phase
+- Run `/gsd-progress` to check current status
+
+## Architecture Constraints
+
+The following decisions are LOCKED from the data model and must be respected in all phases:
+
+1. **`clients.token` is a separate rotatable field — NEVER the primary key.** Clients have a stable UUID `id` and a separate `token` field used for secret link access. Rotation = single UPDATE on `token`.
+
+2. **Client API never exposes `quote_items`.** The `accepted_total` field on the `clients` row is the only price the client API returns. Quote line items are admin-only. Enforced at the query layer, not the UI.
+
+3. **`deliverables.approved_at` is immutable.** Once set, it cannot be unset by the client. Admin-only override only if strictly necessary.
+
+4. **Two independent auth paths:**
+   - `/c/[token]/*` → Next.js Middleware validates token against DB, 404 on miss
+   - `/admin/*` → Auth.js Credentials session check
+
+5. **No file hosting in v1.** Documents are external URLs (Google Drive, PDF links) stored as text.
+
+## Stack
+
+Next.js 15 (App Router) · Neon (serverless Postgres) · Drizzle ORM · Auth.js v4 · nanoid · Tailwind v4 · shadcn/ui · Zod · React Hook Form
+
+## Security
+
+- Client tokens: cryptographically random via `nanoid` (21 chars, ~126 bit entropy). Never derived from client name or sequential ID.
+- Admin area: protected by Auth.js session before Phase 2 ships to production.
+- Payment privacy: `quote_items` never returned by client-facing API routes.
\ No newline at end of file