# `.claude/` — la cartella di configurazione di ClientHub

Questo file si carica quando si lavora **dentro `.claude/`**. Spiega cosa va dove, e basta.

**Per il progetto comanda [`../CLAUDE.md`](../CLAUDE.md)**: stack, vincoli LOCKED, procedura
di deploy, accesso al DB, design system. Qui non si duplica niente di quello — una seconda
copia è il modo più veloce per averne due che si contraddicono.

## Cosa va in ogni cartella

| Cartella | Cosa ci va | Cosa **non** ci va |
|---|---|---|
| `rules/` | Regole caricate per contesto. Oggi: `memory-discipline.md`, importata da `../CLAUDE.md` | Documentazione di feature — quella sta in `STATUS.md` |
| `skills/` | **Solo** skill specifiche di ClientHub: `preventivo/`, `audit/` | Le skill globali (`/seo-audit`, `/copywriting`, `/docx`…) — stanno in `~/.claude/skills/` |
| `agents/` | **Solo** agenti specifici di ClientHub. Oggi vuota: quello dell'audit nasce col motore | I 18 agenti globali di `~/.claude/agents/` |
| `hooks/` | Script eseguibili richiamati da `settings.json` | Logica di prodotto |
| `plans/` | I piani delle milestone, versionati | Piani usa-e-getta di una singola sessione |
| `commands/`, `workflows/`, `projects/` | Vuote per ora, sono lo scheletro | — |
| `memory/` | Appunti di lavoro versionati nel repo | **La memoria persistente. Non è qui** → vedi sotto |
| `worktrees/` | Generata dagli strumenti | — |

### Agenti e skill globali non si copiano qui

Regola già fissata in [`../../CLAUDE.md`](../../CLAUDE.md): agenti e skill che valgono per
tutti i progetti vivono in `~/.claude/` e si invocano da qualunque cartella. Copiarne uno qui
crea due file destinati a divergere, e il primo a cambiare vince a caso.

In locale ci va solo ciò che **senza questo repo non ha senso**: le due skill qui sotto.

### `.claude/memory/` ≠ memoria persistente

Due posti diversi con lo stesso nome, e confonderli fa perdere il lavoro:

- **`.claude/memory/`** (questa cartella) — appunti versionati nel repo, li vede chiunque
  faccia clone.
- **`~/.claude/projects/-Users-simonecavalli-Vault-IAMCAVALLI-hub/memory/`** — la memoria
  persistente vera, un file per fatto più `MEMORY.md` come indice. Sta fuori dal repo, non
  si committa, e viene iniettata in automatico a inizio sessione.

Ci va quello che **non si deduce dal repo**: perché una decisione è stata presa, un vincolo
operativo, una cosa provata che non funziona. Regole complete in
[`rules/memory-discipline.md`](rules/memory-discipline.md).

## Le skill del progetto

- **`/preventivo`** — l'attrezzo per lavorare sulla pipeline che genera i preventivi
  (`src/lib/proposal/`) senza romperla. Non contiene un prompt di generazione: quello vive
  in `agent.ts` ed è l'unico.
- **`/audit`** — fa girare le cinque fonti di `src/lib/audit/sources/` su un URL e dice cosa
  è stato **misurato** e cosa no. Le fonti sono in produzione ma inerti: nessuna route le
  chiama ancora.

## Gli hook attivi

Tutti e tre in [`settings.json`](settings.json). Si provano a mano prima di fidarsi.

| Hook | Quando | Cosa fa |
|---|---|---|
| Promemoria memoria | `Stop` | Se `src/` o `.planning/` hanno modifiche non committate, ricorda di aggiornare `STATE.md`. Non blocca |
| [`guardia-migration.sh`](hooks/guardia-migration.sh) | `PreToolUse` su Write/Edit in `src/db/migrations/` | **Blocca** l'SQL che cancella dati dalle entità protette (`clients`, `projects`, `payments`, `phases`). È il vincolo Data Safety LOCKED fatto rispettare dalla macchina |
| [`guardia-token.sh`](hooks/guardia-token.sh) | `PostToolUse` su `.tsx`/`.css` | **Avvisa** se compaiono classi Tailwind grezze o hex letterali. Non blocca: le eccezioni sanzionate esistono e stanno nella whitelist dello script |

Per provarli senza passare da Claude:

```bash
echo '{"tool_input":{"file_path":"src/db/migrations/9999_x.sql","content":"DROP TABLE payments;"}}' \
  | .claude/hooks/guardia-migration.sh; echo "exit=$?"   # atteso: 2

echo '{"tool_input":{"file_path":"src/x.tsx","content":"<div className=\"bg-slate-100\"/>"}}' \
  | .claude/hooks/guardia-token.sh; echo "exit=$?"       # atteso: 0 + avviso
```

## I piani

`plans/` contiene i piani della milestone v2.5, portati dentro il repo il 2026-08-26 perché
stavano solo in `~/.claude/plans/` e `STATE.md` avvertiva che senza quelli la milestone non
era ricostruibile. Dettaglio in [`plans/README.md`](plans/README.md).