01 · Handbook

Sistema, stack,
flow di un cambio.

Dove vivono le cose, perché abbiamo scelto questo stack, e come si fa una modifica end-to-end senza rompere niente.

Stack tecnologico

Otto livelli, una sola scelta per livello. La regola: se devi spiegare perché c'è una tech in più, probabilmente non serve.

Livello	Scelta	Perché
Frontend	`Nuxt 4 (Vue 3 + TypeScript)`	SSR, file-based routing, ergonomia DX.
Backend	`Nitro (server routes)`	Edge-ready, stessa codebase del frontend.
Database	`Supabase (Postgres + RLS)`	Auth + DB + storage in un colpo.
Hosting	`Vercel`	Deploy preview per branch, edge functions, zero-config.
AI	`OpenAI (GPT-4o) + Anthropic (Claude Opus/Sonnet)`	Routing per task: structured per OpenAI, ragionamento per Claude.
Email transazionale	`Resend`	API pulita, deliverability buona, dominio verificato.
Auth	`Supabase Auth (magic link + OAuth)`	Niente password da gestire.
Cookie & consenso	`Klaro!`	GDPR-compliant, granulare per servizio.

Repo

Tutto il codice di xp.pianeta.studio vive in PianetaDev/pianeta-xp. Branch principale: main. Niente PR di default — push diretti, vedi convenzioni.

struttura cartelle

pianeta-xp/
├── app/
│   ├── pages/          # file-based routing
│   ├── components/     # Vue components
│   ├── composables/    # logic riusabile
│   └── layouts/        # default + custom
├── server/
│   ├── api/            # endpoint server
│   ├── routes/         # rotte raw (sitemap, og, ecc.)
│   └── utils/          # helper backend
├── public/             # static assets
├── scripts/            # OG generators, ingest, smoke
├── nuxt.config.ts
└── .env.local          # NUXT_* env vars

Flow di una modifica end-to-end

I 6 step che facciamo ogni volta che tocchiamo qualcosa, dal "voglio cambiare X" al "è online verificato".

Apri il repo in Claude Code.Da terminale: cd pianeta-xp && claude. Se la modifica è grossa, fai prima un brainstorming (vedi skill).
Branch sandbox.Per modifiche non banali: git checkout -b sandbox/<nome>. Per fix immediati su main va bene direttamente.
Modifica + verifica locale.npm run dev per vedere subito; npm run build per essere sicuri che builda davvero.
Commit con autore studio.Email del commit: info@pianeta.studio. Se è la prima volta, configurala.
Push e deploy con cache pulita.Cancella .nuxt .output .vercel/output, rebuild, vercel deploy --prod.
Smoke test + verifica reale.Lancia npm run smoke. Apri il sito in incognito + hard reload per bypassare la cache.

end-to-end · shell

# Lavora su una branch sandbox per evitare di rompere prod
git checkout -b sandbox/handbook-tweak

# ...modifica i file con Claude...

# Verifica locale
npm run dev      # http://localhost:3000
npm run build    # build production

# Commit con email studio (vedi sotto)
git add -A
git commit -m "handbook: chiarisco flow di deploy"

# Push diretto a main (no PR — vedi feedback_no_pr)
git checkout main && git merge sandbox/handbook-tweak
git push

# Deploy con cache pulita
rm -rf .nuxt .output .vercel/output
npm run build
vercel deploy --prod --prebuilt --yes

# Smoke test
BASE=https://xp.pianeta.studio npm run smoke

Componenti custom riusabili

Pianeta.Green ha il suo Design System nel repo. Non importare Hederae qui — usa o estendi i componenti già presenti.

Componente	Path	Uso
BcNav	`app/components/BcNav.vue`	Nav header riusabile per le landing Bussola.
BcPromptBox	`app/components/BcPromptBox.vue`	Box "chiedi qualcosa" stile chat.
CountUp	`app/components/CountUp.vue`	Animazione numerica per metriche.
HandbookHb*	`app/components/handbook/`	Header, sidebar, footer, code-block per /handbook.
Section header pattern	`inline ovunque`	eyebrow + title + lede + meta — paper style condiviso con Bulletin.

Convenzioni che non si negoziano

Git author sempre info@pianeta.studio — niente email personali nei commit pubblici.
Branch sandbox per ogni iterazione lunga; merge a main quando è pronto e verificato.
Smoke = 32 check. Se aggiungi una pagina pubblica, aggiungi un check in scripts/smoke.sh.
Env vars su Vercel vanno duplicate: KEY (per script) + NUXT_KEY (per il runtime Nuxt).
Migrations Supabase versionate in supabase/migrations/ — niente modifiche a mano in console.
No PR di default su xp — push diretti a main. PR solo se Max le chiede esplicitamente.

git · una tantum

# Una sola volta, per il repo
git config user.email "info@pianeta.studio"
git config user.name "Pianeta.Studio"

.env / Vercel