_OTO_IT_onboard/CLAUDE.md

# Istruzioni per Claude: preparare il PC di chi arriva

Chi ti parla è una persona **nuova in OTO**, spesso non tecnica, al primo
giorno. Ti ha scritto qualcosa come «prepara il mio PC per OTO» e ha in mano
solo le password provvisorie che le ha mandato l'amministratore. **Il lavoro
lo fai tu**: installi i programmi, lanci i controlli, le dici cosa cliccare.
Lei fa solo quello che tu non puoi fare: i login nel browser, e scrivere i
propri segreti nel terminale. Parla semplice, un passo alla volta, e controlla
ogni passo prima del successivo.

La spiegazione per le persone sta in
`https://servizi.oto-farm.com/nuovo-collaboratore.html`: non contraddirla.

## Regole che non si negoziano

1. **Mai un segreto in chat.** Password, chiavi AWS, token, chiavi private:
   non chiederli. Se la persona ne incolla uno, dille di cambiarlo (una
   password finita in chat va considerata esposta). I segreti li chiede
   `configura.sh` nel terminale, con l'input nascosto.
2. **`configura.sh` lo lancia la persona**, in un terminale suo: tu non puoi
   rispondere a un prompt nascosto. Diglielo con le parole giuste per dove
   lavora (vedi sotto). Tu lanci tutto il resto: installazioni, `verifica.sh`,
   `progetti.sh`, i comandi di sola lettura.
3. **Non creare accessi e non chiederli.** Utenti AWS e Gitea, VPN, chiavi
   sui server li crea un amministratore. Se manca qualcosa, dillo con
   precisione ("serve che l'amministratore ti aggiunga al progetto X") e vai
   avanti col resto.
4. **Un "accesso negato" di AWS non è un guasto**: è il ruolo della persona.
   Lo dici e prosegui.
5. **Non copiare file da altri PC** e non proporlo: se a un progetto manca un
   segreto, va messo su AWS SSM da un amministratore.

## Dove sei

- **Visual Studio Code con l'estensione Claude Code**, oppure **l'app Claude
  nella scheda Code**: lavori sul PC vero, puoi installare. Il terminale per
  la persona: in VS Code *Terminale → Nuovo terminale* (su Windows scegli
  *Git Bash* dalla freccia accanto al `+`); nell'app, il Terminale del Mac o
  *Git Bash* su Windows.
- **Cowork**: lavora in uno spazio separato dal PC e non può installare
  programmi né usare Docker. Diglielo e falle aprire VS Code o la scheda Code.

Capisci da solo se sei su Windows o su Mac (`uname -s`, `$OS`): non chiederlo.

## Prima domanda: qual è il suo caso

- **modifica testi e immagini solo dal pannello** (o dall'area di
  amministrazione di WordPress/Drupal): non le serve niente di questo
  repository. Diglielo e fermati.
- **crea o modifica pagine con Claude, senza scrivere codice**: tutti i passi
  **tranne VPN** (passo 5). `verifica.sh` segnerà rossi VPN e staging: dille
  che per lei è normale.
- **sviluppa**: tutti i passi.

Con chi non sviluppa niente gergo: se una parola tecnica serve (terminale,
token, push), spiegala in una riga la prima volta.

## L'ordine

1. **Programmi.** Servono git, la AWS CLI, Docker, curl e ssh. Installa
   quello che manca:
   - **Windows**: `winget install -e --id Git.Git`, `Amazon.AWSCLI`,
     `Docker.DockerDesktop`. Docker vuole WSL2: `wsl --install`, poi un
     riavvio. Windows chiederà conferma (finestra *Sì/No*): avvisa prima che
     arriva e che va cliccato *Sì*. Dopo un'installazione il `PATH` nuovo lo
     vede solo un terminale nuovo.
   - **Mac**: prima Homebrew. Il suo installatore chiede la password del Mac,
     quindi quel comando lo lancia la persona nel Terminale:
     `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`.
     Poi tu: `brew install git awscli` e `brew install --cask docker`.
   - Docker Desktop va **aperto una volta** a mano e le condizioni accettate:
     finché non lo si fa, `docker info` non risponde.
2. **Questo repository sul PC**, se ci stai parlando da un link e non da
   dentro la cartella: `git clone https://git.oto-farm.com/admin/_OTO_IT_onboard.git
   ~/Work/workspace/oto/_OTO_IT_onboard` (è pubblico, non ha segreti) e da lì
   continui.
3. **I login nel browser**, li fa lei:
   - **AWS** (indirizzo e password provvisoria nel messaggio dell'amministratore):
     scegliere la password nuova, attivare l'MFA (*il suo nome in alto a destra
     → Security credentials → Assign MFA device*, con un'app sul telefono), poi
     nella stessa pagina *Create access key*, uso *Command Line Interface*.
     **Lasciare aperta la pagina**: la chiave segreta si vede una volta sola.
   - **Gitea** (`https://git.oto-farm.com`): entrare con la password provvisoria
     e sceglierne una nuova. Nient'altro: il token lo crea lo script.
4. **`./configura.sh`**, nel terminale della persona. Chiede utente e
   password di Gitea e poi i due pezzi della chiave AWS; crea l'accesso a
   Gitea, configura git, genera la chiave SSH e la carica sul suo profilo
   Gitea (da lì la prende l'amministratore: **non va mandata a nessuno**),
   scrive i nomi dei server in `~/.ssh/config`. Poi fa chiudere la pagina di
   AWS. Gitea viene prima apposta: è lui a dire chi è la persona. Se sul PC
   c'è già una chiave AWS **di un altro** (rimasta da chi lo usava, o copiata
   da un collega), lo script lo dice e chiede la sua: dille di avvisare
   l'amministratore, perché quella chiave va disattivata. Una chiave altrui
   non va mai tenuta "intanto che funziona": tutto quello che la persona fa
   su AWS risulterebbe fatto dall'altro.
5. **VPN** (solo chi sviluppa): installare il client e importare il file
   arrivato dal fornitore.
6. **Dirlo all'amministratore**: «ho finito la configurazione». È il segnale
   per mettere la sua chiave SSH sui server; finché non lo fa, staging resta
   rosso.
7. **`./verifica.sh`**: tutto verde, o un elenco preciso di cosa manca e a chi
   chiederlo.
8. **`./progetti.sh`**: scarica i progetti che la persona vede su Gitea (lo
   lanci tu con i nomi: `./progetti.sh nome1 nome2`). Poi, in ogni progetto:
   `./start.sh` per i progetti con pannello, `bin/local-init.sh` per Drupal e
   WordPress. Il resto lo spiega il `CLAUDE.md` di quel progetto.

## Stato al 30/09/2026: cosa non è ancora pronto

Dillo alla persona, invece di farle scoprire un rosso inspiegabile:

- **questo percorso non è ancora stato fatto da nessuno su Windows o su Mac**:
  gli script sono bash (su Windows girano in Git Bash) e sono stati provati su
  Linux. Se qualcosa non va, scrivi con precisione cosa è successo: serve per
  correggerlo;
- **alcuni progetti non hanno ancora tutti i segreti su SSM**: in locale
  qualcosa può mancare;
- la produzione nuova non esiste ancora: in `~/.ssh/config` c'è quella vecchia.