# CLAUDE.md

Questo file fornisce indicazioni a Claude Code (claude.ai/code) per lavorare con il codice di questo repository.

## Panoramica del progetto

Sito web professionale per **Due Bytes**, agenzia di sviluppo web con sede ad Arma di Taggia (Italia). È una single-page application (SPA) con un pannello admin integrato per la gestione del portfolio.

**Questa cartella contiene il redesign 2026-07** del sito (design system "Due stati", vedi sotto), diventato la versione attiva l'11/08/2026. La versione precedente (Bootstrap, palette blu) è archiviata in `_archive/sito-precedente-blu-2026/` in questa stessa cartella, non deployata e non referenziata da nulla. La cartella è servita live dal NAS per anteprima: https://nas.duebytes.synology.me/_private/duebytes/ (sincronizzazione Synology Drive, i file impiegano qualche secondo a propagarsi).

**Stack tecnologico:**
- Frontend: HTML5, CSS3 custom (nessun framework), JavaScript vanilla (nessuna libreria)
- Font via Google Fonts: Bricolage Grotesque (display), Instrument Sans (testo), JetBrains Mono (etichette/dati)
- Backend: PHP 7.4+ (solo per il pannello admin, che usa ancora Bootstrap/SortableJS via CDN nel proprio HTML)
- Nessun build system, package manager o bundler

## Design system "Due stati" (redesign 2026-07)

Il concept nasce dal marchio: la sigla del logo, **2B**, in ASCII occupa esattamente **due byte** (`2` = 0x32 = `00110010`, `B` = 0x42 = `01000010`). Il motivo binario ricorre in tutto il sito:

- **Bit-strip**: 16 celle che si assestano sul pattern `00110010 01000010` (hero, animata; footer, statica)
- **Campo di bit animato** (`canvas.bit-field`): griglia di 0/1 su hero e contatti; i bit vicini al mouse si accendono in arancio, onde autonome attraversano il campo. Densità a gradiente (tenue a sinistra sul testo, piena a destra)
- **Indirizzi binari a 3 bit** negli occhielli delle sezioni (001 servizi … 111 chi siamo) e nell'**HUD fisso** in basso a sinistra (solo desktop) che mostra la sezione corrente
- **Effetto "decodifica"** sulle etichette mono (si assestano da glifi casuali; solo su testo monospace, così il layout non si muove)

**Palette** (CSS custom properties in `:root`):
```css
--carta: #f7f6f2      --carta-tint: #efede5   --bianco: #fffefb
--inchiostro: #191a17 --inchiostro-2: #5b5d56 --linea: #dcdacf
--accento: #ff4d00 (arancio internazionale)   --accento-scuro: #e04400
--notte: #171814      --notte-2: #101110      --latte: #f2f1ea
--latte-2: #a3a49a    --linea-notte: #33342e
```
Le bande scure (`.band-dark`, `.footer`) ridefiniscono le variabili di contesto `--bg/--fg/--fg-2/--line`: i componenti si adattano da soli. Non hardcodare colori nei componenti.

**Sezioni animate principali:**
- **Metodo**: timeline scroll-driven; la variabile `--steps-progress` (impostata da `initSteps()` in main.js) riempie la linea centrale, sul tratto percorso scorre un flusso animato, le fasi si attivano al passaggio
- **Portfolio**: "nuvola" di card flottanti; pattern deterministico di rotazioni/sfalsamenti via `nth-child`, galleggiamento continuo (keyframe `bob`), parallasse per-card via `--par` (da `initFloatingCards()`)
- Tutte le animazioni rispettano `prefers-reduced-motion` (CSS + guardie JS)

## Struttura del progetto

- `index.html` — Landing page principale (SPA)
- `assets/css/style.css` — Unico foglio di stile (token + componenti, commentato a sezioni)
- `assets/js/main.js` — JavaScript dell'applicazione: menu mobile, scroll-spy custom + HUD, bit-strip, campo di bit canvas, reveal on scroll, contatori, timeline metodo, nuvola portfolio, marquee domini clienti
- `assets/img/portfolio/` — Screenshot dei progetti in portfolio
- `data/portfolio.json` — Dati dei progetti portfolio (array JSON)
- `admin/` — Pannello di amministrazione (INVARIATO nel redesign: scrive solo su portfolio.json)
  - `admin/index.html` — Dashboard admin (HTML/CSS/JS inline)
  - `admin/api.php` — API REST per CRUD portfolio e upload immagini
  - `admin/auth.php` — Endpoint di autenticazione
  - `admin/config/credentials.php` — Credenziali admin (protetto da .htaccess)
- `docs/` — Note e piani di lavoro locali (non deployati)
- `_archive/` — Versioni precedenti del sito, non deployate, non referenziate (vedi `sito-precedente-blu-2026/`)

**File di lavoro locali (NON parte del sito, NON deployare):** screenshot `.png`/`.yml` nella root sono artefatti di sessioni passate. Non sono referenziati da `index.html` e non vanno mai caricati via lftp.

**Niente version control:** questo progetto NON è un repository git. Nessun undo. Un backup dei file v1 pre-redesign (index.html, style.css, main.js, portfolio.json, CLAUDE.md) è in `_archive/sito-precedente-blu-2026/`.

## Architettura

### Frontend (index.html + main.js)
La landing carica i progetti da `data/portfolio.json` via fetch e genera le card della nuvola portfolio (`#portfolio-cloud`); dagli stessi dati ricava il marquee dei domini clienti in fondo alla hero (github.com escluso). Tutti i dati del JSON vengono passati per `escapeHtml()` e i link validati con `isSafeUrl()` prima dell'inserimento nel DOM.

**Scroll:** le ancore usano lo scroll nativo (`scroll-behavior: smooth` + `scroll-padding-top` nel CSS), NON JavaScript. Lo scroll-spy (link attivo + HUD) è custom in `setActiveNavLink()`; non introdurre `data-bs-spy` o simili.

**Attenzione al `backdrop-filter` sull'header:** rende l'header containing block dei discendenti `position: fixed`. Il pannello del menu mobile usa quindi `top/left + width/height: 100dvh` espliciti, non `inset: 0` (che verrebbe risolto rispetto all'header alto 68px).

**Cache-busting:** i link a `style.css` e `main.js` hanno query-string `?v=YYYYMMDD[x]` da incrementare a ogni modifica (valore attuale `?v=20260714d`).

**Dettagli di design (Paolo è molto esigente sulla tipografia):** dopo ogni edit a `index.html`/`style.css` fare un audit mirato ai dettagli con browser su desktop XL (1440px) e mobile (390px). Regole consolidate:
- **Paragrafi lunghi allineati a sinistra**, MAI centrati. Titoli e occhielli centrati o a sinistra sì; blocchi di testo su più righe no. Spacing ~`1.5rem` tra paragrafi consecutivi.
- **NBHY sui composti nei titoli:** `‑` per "e‑commerce" ecc. NON nel meta/SEO, dove serve il trattino ASCII.
- `text-wrap: balance` sui titoli; occhio a vedove/orfane e parole spezzate.
- Il logo abbreviato di Due Bytes è **2B** (non "DB", che ricorda "database").

### Backend Admin (admin/api.php)
API REST con tre azioni via query string `?action=`:
- `load` (GET) — Carica tutti i progetti da `data/portfolio.json`
- `save` (POST) — Salva l'array aggiornato dei progetti
- `upload` (POST) — Upload immagine con ottimizzazione automatica (max 800x600px, JPEG 85%, libreria GD)

L'autenticazione è client-side con `sessionStorage` dopo verifica credenziali via `auth.php`. Il redesign non tocca l'admin: finché `data/portfolio.json` mantiene lo schema `{id, title, description, link, image}`, tutto resta compatibile.

## Tono, contenuti e autoria dei testi

Regole vincolanti per **qualsiasi testo pubblico** (copy di `index.html`, descrizioni in `data/portfolio.json`, profilo Google Business, pitch/proposte ai clienti):

- **Paolo è l'autore unico.** Mai riferirsi nei testi pubblici a "Claude", "Claude Code", "vibe coding", "AI-assisted", "generato con AI" o analoghi. Gli stack tecnici reali (PHP, Rust, Python, LangGraph, FAISS, Swift…) sono competenze legittime e vanno dichiarati.
- **Niente em dash `—` / en dash `–`** nei testi italiani. Usare virgole, parentesi o punto e virgola. Il trattino ASCII nei composti ("e-commerce") va bene. Prima di salvare copy lunga, grep dei caratteri `\x{2013}\x{2014}`.
- Formulazione in prima persona plurale: "sviluppiamo", "progettiamo", "realizziamo".

(Questo CLAUDE.md è documentazione interna, non testo pubblico: le sue regole non si applicano a sé stesso.)

**Struttura `data/portfolio.json`:** i progetti con `link`/`image` vuoti (es. IOTA Web Guardian) sono **volutamente non cliccabili**: diventano schede scure "In sviluppo". Popolare `link`/`image` solo quando avranno un URL live.

## Requisiti server

- PHP 7.4+ con estensione GD (solo per l'admin)
- Apache con mod_rewrite (per .htaccess)
- Permessi di scrittura su `assets/img/portfolio/` e `data/`
- HTTPS consigliato per il pannello admin

## Deploy su TopHost

Il sito live è su TopHost (shared hosting), dominio duebytes.it. Credenziali FTP in `/Users/paolo/Server/Siti Web/_private/TopHost - DueBytes.txt`.

**Il redesign è online su duebytes.it dall'11/08/2026** (v1 precedente archiviata in `_archive/sito-precedente-blu-2026/`, non più in produzione).

**Upload selettivo via `lftp`:**
```bash
lftp -u "duebytes.it,<password>" ftp.duebytes.it <<'EOF'
set ssl:verify-certificate no
set ftp:ssl-allow yes
lcd "/Users/paolo/Server/Siti Web/_private/duebytes"
put index.html -o index.html
put data/portfolio.json -o data/portfolio.json
put assets/css/style.css -o assets/css/style.css
put assets/js/main.js -o assets/js/main.js
quit
EOF
```

**⚠️ Cartelle INTOCCABILI sulla root del dominio:**
- `www/` — siti demo/staging per i clienti
- `app/` — webapp consegnate ai clienti

Non cancellare, non sovrascrivere, non fare `mirror` inverso dalla root. Solo `put` selettivi dei file realmente modificati.

**⚠️ Permessi su TopHost:** lftp crea directory con permessi 700 e file con 600/700, NON serviti da nginx (HTTP 403). Dopo ogni `put` che crea nuove dir/file:
```bash
chmod 755 assets assets/css assets/js assets/img assets/img/portfolio data admin admin/config
chmod 644 index.html sitemap.xml ...
glob -- chmod 644 assets/img/portfolio/*.jpg
```
Sintomo: la home risponde 200 ma CSS/JS/immagini danno 403 → controllare permessi cartelle.

**File non-landing in root del dominio:** oltre a `index.html` e all'admin, sulla root del server ci sono `index.php`, `ordine.*`, `report.*`, `stati.php`, ecc.: appartengono a un gestionale personale di Paolo, non vanno toccati.

## Pagine delle app

Pagine statiche a sé, fuori dalla SPA, con i font e la palette del sito:
- `quantobasta/` — pagina di assistenza di Quanto Basta (URL di assistenza su App Store), IT + EN; `quantobasta/privacy/` — informativa privacy (richiesta dagli store); `quantobasta/icona.png` — icona usata da queste pagine e da `beta/`.
- `beta/` — **pagina dei tester**: elenca le app in prova con i link per provarle su Android e iPhone. L'indirizzo `https://www.duebytes.it/beta/` è quello che Paolo dà ai tester e non cambia; per aggiungere un'app o aggiornare uno stato segui `beta/LEGGIMI.md` (file locale, non si carica).

## Note importanti

- Tutta l'interfaccia e i contenuti sono in **italiano**
- Non esiste un sistema di build: le modifiche a CSS/JS sono immediate (ricordarsi il cache-buster)
- Il pannello admin ha CSS e JS inline nel suo `index.html`
- CORS nell'API è configurato con `Access-Control-Allow-Origin: *`