docs: run-book for Mac setup, spike and commissioning

README.md

@@ -83,7 +83,8 @@ configurazione.
 | Caratteri | 22 famiglie OFL/Apache incluse nel pacchetto ([THIRD-PARTY-FONTS.md](THIRD-PARTY-FONTS.md)) |
 
 Dettagli verificati sperimentalmente in [`docs/typst-verified.md`](docs/typst-verified.md);
-requisiti di sistema e assunzioni non verificate in [`docs/platform-notes.md`](docs/platform-notes.md).
+requisiti di sistema e assunzioni non verificate in [`docs/platform-notes.md`](docs/platform-notes.md);
+procedura di installazione e collaudo in [`docs/RUNBOOK.md`](docs/RUNBOOK.md).
 
 ## Licenza
 

docs/RUNBOOK.md

@@ -0,0 +1,161 @@
+# Run-book — installazione e collaudo sul Mac
+
+Ordine deliberato: **prima si misura, poi si installa**. La fase 1 può dire che un
+modello non è adatto a questa macchina, e allora la configurazione cambia — meglio
+scoprirlo prima di scrivere `pi-imgen.json`.
+
+Tutto è verificato su Linux tranne ciò che richiede hardware Apple. Quello che segue è
+esattamente ciò che non ho potuto misurare io.
+
+---
+
+## 0 · Prerequisiti (10 min)
+
+```bash
+uname -m                      # deve dire arm64
+sw_vers -productVersion       # 13+ obbligatorio, 14+ per lo scontorno in un passaggio
+node -v                       # >= 22.3  <-- pi-ai usa process.getBuiltinModule
+```
+
+⚠️ **Node < 22.3 è la trappola più probabile.** Su Node 20 ogni modulo che arriva a
+`pi-ai` fallisce con `process.getBuiltinModule is not a function`. Esiste un dist-tag
+`legacy-node20` ma è fermo alla 0.74.2 contro la 0.84.x attuale: meglio aggiornare Node.
+
+```bash
+brew install node draw-things-cli typst
+brew install ghostscript poppler qpdf     # opzionali: pre-flight di stampa
+```
+
+`draw-things-cli` è in **Homebrew Core**: niente tap personalizzati, niente `--HEAD`.
+
+---
+
+## 1 · Lo spike — il vero cancello (un pomeriggio)
+
+Nessuno di questi numeri esiste pubblicamente per un M4 base. Da fare **prima**
+dell'installazione vera e propria.
+
+### 1a. Il server caldo funziona davvero?
+
+**La cosa più importante di tutta la lista.** Ho verificato che `draw-things-cli --remote`
+parli con `gRPCServerCLI` leggendo il sorgente di entrambi i lati, **mai eseguendoli**.
+
+```bash
+# scaricare il server (non è su Homebrew: è un asset di release)
+curl -fL -o gRPCServerCLI-macOS \
+  https://github.com/drawthingsai/draw-things-community/releases/download/v1.20260716.0/gRPCServerCLI-macOS
+chmod +x gRPCServerCLI-macOS
+
+./gRPCServerCLI-macOS /Volumes/<disco>/ai-models --no-tls --port 7859 --cpu-offload &
+
+# la STESSA generazione due volte, cronometrata
+time draw-things-cli generate --model z_image_turbo_1.0_i8x.ckpt \
+  --prompt "autumn chestnut harvest, warm evening light, painterly" \
+  --negative-prompt "text, letters, words, typography, watermark, signature" \
+  --width 768 --height 1088 --steps 8 --seed 42 \
+  --models-dir /Volumes/<disco>/ai-models --disable-preview \
+  --remote --remote-url 127.0.0.1 --remote-port 7859 --no-remote-tls \
+  --output /tmp/a.png
+```
+
+**Se la seconda esecuzione è molto più rapida, il modello è rimasto caldo e tutto il
+disegno del ciclo bozza→finale regge.** Se invece i tempi sono uguali, il server non
+sta servendo: si ripiega su `draw-things-cli` da solo (ogni generazione ricarica il
+modello) e le bozze diventano lente ma il resto funziona.
+
+⚠️ `--output` è **obbligatorio**: senza, la CLI disegna un'anteprima nel terminale e
+**non scrive alcun file**. `--disable-preview` idem.
+
+### 1b. Gli altri quattro numeri
+
+| Cosa | Come | Perché conta |
+|---|---|---|
+| `_i8x` vs `_q5p` | stessa generazione, due modelli | `_i8x` usa la Neural Engine dell'M4: atteso ~2x |
+| Tiling VAE on/off a 1024² | `--config-json '{"tiledDecoding":true,...}'` vs `false`, guardando la memoria in Activity Monitor | 14.03 GB → 7.18 GB di picco: è la differenza fra funzionare e andare in swap |
+| Ingrandimento a A3/300dpi | il modello `upscale` su un 1024px | Obbligatorio per la stampa: 1024px su A3 sono ~62 dpi |
+| img2img va in crash? | una generazione con `--image` | Bug noto #121 sui Mac da 16 GB. Se si presenta, si perde **solo** la modifica generativa |
+
+Annotare i tempi: servono a scegliere i passi di default.
+
+---
+
+## 2 · Installazione
+
+```bash
+pi install git:git.sal.giize.com/mozempk/pi-imgen
+cd ~/.pi/agent/git/git.sal.giize.com/mozempk/pi-imgen
+./install.sh
+```
+
+⚠️ **Da verificare al primo colpo:** che `pi install git:` accetti un host diverso da
+GitHub — tutti gli esempi documentati sono GitHub. Se non risolve, il ripiego è clonare
+a mano e aggiungere il percorso a `extensions` in `~/.pi/agent/settings.json`: stesso
+risultato, un passaggio in più.
+
+`install.sh` è **ri-eseguibile**: chiede dove tenere i modelli (disco esterno) e dove
+salvare i file, scarica i caratteri, e **unisce** in `~/.pi/agent/pi-imgen.json` senza
+sovrascrivere i preset.
+
+### Il direttore artistico ha bisogno di un modello
+
+Registrare **opencode Go** come provider in pi — è OpenAI-compatibile:
+
+```
+base URL : https://opencode.ai/zen/go/v1
+API key  : $OPENCODE_API_KEY
+```
+
+Poi in `pi-imgen.json`: `"directorProvider"` e `"directorModel"`.
+
+Senza questo il direttore non ha su cosa girare. (Verificato: quell'abbonamento **non**
+contiene modelli di immagini — può essere solo il cervello, mai il pennello.)
+
+---
+
+## 3 · Collaudo
+
+```bash
+pi
+> /doctor
+```
+
+`/doctor` parla italiano e dice cosa manca con il rimedio: disco non montato, binario
+assente, modello mancante, caratteri non scaricati.
+
+Poi la prova vera:
+
+```
+> /poster
+```
+
+Un evento reale in arrivo. **Il collaudo è lui che produce una locandina da solo**, non
+una suite di test che passa.
+
+Sul terminale: le anteprime inline richiedono iTerm2, Ghostty, WezTerm o Warp.
+**Terminal.app di Apple non mostra immagini** — i file però si aprono nel Finder comunque.
+
+### Prima di portarla in tipografia
+
+```bash
+pdfinfo -box poster.pdf     # TrimBox presente, 303x426 mm per A3+3mm
+pdffonts poster.pdf         # ogni riga: emb=yes   (sub=yes è normale)
+```
+
+Consegnare **un PDF singolo, 3 mm di abbondanza, RGB, senza crocini**: va bene per la
+grande maggioranza delle copisterie. I crocini si attivano da configurazione solo se la
+tipografia li chiede (i servizi online li rifiutano).
+
+---
+
+## Se qualcosa va storto
+
+| Sintomo | Causa |
+|---|---|
+| `process.getBuiltinModule is not a function` | Node < 22.3 → §0 |
+| Nessun file prodotto, nessun errore | Manca `--output` |
+| "disco dei modelli non montato" | Volume esterno assente — messaggio previsto, non un bug |
+| Crash su img2img | Bug #121 → `/poster` e `/logo` funzionano lo stesso |
+| Scontorno non disponibile | Serve macOS 14; su 13 ripiega su rembg (**non** il modello di default: è CC BY-NC) |
+| Bozze lente quanto il finale | Il server caldo non sta servendo → §1a |
+
+Dettagli e assunzioni non verificate: [`platform-notes.md`](platform-notes.md).