# Kit BONUS · La pipeline minima — capitolo 8.5

La pipeline del capitolo 8.5, ridotta all'osso e funzionante: capitoli in Markdown,
un comando, un file che si legge dal telefono e si stampa in A4. Niente Typst, niente
Pandoc, niente account: serve Python 3.8 o più recente e nient'altro, nemmeno una
libreria da installare. È il kit minimo promesso in fondo al capitolo.

L'esempio dentro al kit è il manuale del banco della Ferramenta Esposito, quattro
dipendenti a Napoli: due capitoli scritti, uno chiuso e uno ancora in bozza.

## Cosa c'è dentro

Tutto sta in `progetto-esempio/`, che è già un progetto completo da copiare:

- `CLAUDE.md` — il file delle regole. Claude Code lo legge da solo all'avvio: dentro ci sono la fonte unica, lo stile, i comandi, i tre punti dove decide un umano e cosa non deve fare mai.
- `STATO.md` — il file di stato. Cinque sezioni: dove sono, ultimo pezzo chiuso, prossime tre azioni, verifiche aperte, cosa serve decidere. È quello che ti fa ripartire dopo due settimane di pausa senza rileggere niente.
- `decisioni.md` — il registro: una riga per decisione, con la motivazione accanto.
- `contenuti/` — i due capitoli d'esempio, con l'intestazione tra `---` (titolo, stato, tetto di parole).
- `build/controlla.py` — il cancello: cinque controlli, non scrive niente.
- `build/costruisci.py` — il build: chiama il controllo e, solo se passa, impagina.
- `fatto/manuale.html` — l'uscita, già costruita da questi script. Aprila subito per vedere dove si arriva, poi cancellala pure: si rifà con un comando.

## A chi serve

A chi deve tenere in piedi un documento che cambia e che qualcuno legge davvero:
un manuale interno, le procedure di uno studio, la documentazione di un corso, la
guida di un prodotto. Il segno che ti serve è uno solo: hai già due versioni dello
stesso testo e non sai più quale sia quella buona.

Non serve per un documento che scrivi una volta e non tocchi più. Per quello c'è
il programma di videoscrittura, e va benissimo.

## Quanto ci vuole

Cinque minuti per vederla girare (`python build/costruisci.py` e apri il file).
Mezz'ora per portarci dentro i tuoi due primi capitoli. Mezza giornata per il
progetto intero, se i contenuti li hai già.

## La pipeline in venti righe

1. Due cartelle e tre file: `contenuti/` (la fonte), `build/` (gli script), `fatto/` (l'uscita).
2. Un capitolo è un file Markdown in `contenuti/`, nome `NN-slug.md`: il numero tiene l'ordine.
3. In testa a ogni capitolo, tra `---`, tre campi: `titolo`, `stato`, `parole_max`.
4. `contenuti/` è l'unico posto dove si scrive a mano. Tutto il resto si genera.
5. `python build/controlla.py` è il cancello: guarda, conta, non tocca niente.
6. Controlla il nome dei file e che due capitoli non si prendano lo stesso numero.
7. Controlla che ogni capitolo dichiari titolo e stato (`bozza`, `rivisto`, `chiuso`).
8. Controlla che le immagini citate nel testo esistano davvero su disco.
9. Controlla che non sia rimasta una verifica aperta: il marcatore `TODO-VERIFICA:` ferma tutto.
10. Conta le parole capitolo per capitolo e ti avvisa quando sfori il tetto che hai messo tu.
11. `python build/costruisci.py` chiama il controllo e impagina solo se il controllo passa.
12. Esce un file solo, `fatto/manuale.html`: sommario in alto, un capitolo per sezione.
13. Dallo stesso file, con l'anteprima di stampa del browser, esce l'A4: un capitolo per pagina, sommario sparito. Quello è il tuo PDF.
14. `fatto/` non si corregge mai a mano: se l'uscita è sbagliata, l'errore è nella fonte o negli script.
15. `CLAUDE.md` sta nella radice: apri la cartella con Claude Code e le regole sono già a bordo.
16. `STATO.md` si aggiorna a fine sessione, prima di chiudere. Trenta secondi, e la sessione dopo parte in piedi.
17. `decisioni.md` prende una riga ogni volta che scegli qualcosa che qualcuno potrebbe rimettere in discussione.
18. Tre punti restano tuoi: cosa serve scrivere, com'è venuta la prima resa stampata, il via libera finale.
19. Il giro quotidiano è sempre lo stesso: apri il capitolo, cambia, rilancia il build, guarda.
20. Gira offline, senza chiavi e senza account: due script, 379 righe in tutto, commenti compresi.

## Prova che il cancello funziona (trenta secondi)

Apri `contenuti/02-resi-e-sostituzioni.md`, aggiungi in fondo una riga che comincia
col marcatore di verifica aperta (la parola `TODO-VERIFICA` seguita dai due punti e
da cosa devi verificare), poi lancia `python build/costruisci.py`. Il build si ferma e
ti dice file e riga. Togli la riga e riparte. È il pezzo che vale più di tutti gli
altri: quello che non hai verificato non arriva a chi legge.

## Cosa NON c'è, dichiarato

- **Il PDF non esce da un build.** Esce dalla stampa del browser, come dice il capitolo. Per un manuale di venti pagine è la scelta giusta; per un libro da stampare in tipografia servono altri attrezzi, e sono un altro mestiere.
- **Non c'è il repository del libro.** Questo è il metodo in scala, con gli stessi cardini: fonte unica, cancello prima del build, uscita rigenerata, decisioni scritte.
- **Non c'è niente di segreto e niente di tuo.** Nessuna chiave, nessuna password, nessun dato reale: i due capitoli d'esempio parlano di una ferramenta che non esiste.
- **Non c'è un convertitore Markdown completo.** `costruisci.py` gestisce titoli, paragrafi, elenchi, tabelle, citazioni, codice, immagini e link: quello che serve a un manuale. Se ti manca qualcosa, si aggiunge in una funzione sola.

Aggiornamenti e versioni nuove di questo kit: sull'hub del libro.