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.