# I prompt delle dieci tappe dell'app
# Dal libro «AI di casa» (AI Sul Serio, aisulserio.com), capitolo 24. Verificato il 02/10/2026.

# Uno alla volta, nell'agente di programmazione (Claude Code o Codex), nella cartella del progetto.
# Dopo ogni tappa: prova l'app, poi salva con Git.

===== Tappa 0 · Il progetto =====

Leggi AGENTS.md, SPEC.md e SCHEDA-ARGOMENTO.md. Crea il progetto Electron con il modello ufficiale: npx @quick-start/create-electron, template react-ts. La cartella non è vuota: crealo in una sottocartella temporanea, poi sposta tutti i file qui (rinomina il README del modello in README-modello.md) e cancella la sottocartella. Poi npm install. Se npm avvisa che gli script di installazione non sono approvati, approva solo electron, electron-winstaller ed esbuild con npm install-scripts approve, e reinstalla. Alla fine npm run dev deve aprire la finestra di prova. Spiegami come la vedo.

===== Tappa 1 · Le tre colonne =====

Tappa 1 della SPEC (§3). Aggiungi Tailwind CSS 4 (plugin @tailwindcss/vite nel renderer) e Motion. Sostituisci la pagina di prova con il layout dell'app:
- sidebar a sinistra (260 px) con il nome dell'app dalla SCHEDA, un progetto di esempio «Cucina di casa» con due conversazioni finte, il pulsante «Nuova conversazione» e in basso le voci Il mio PC, Modelli, Che cosa ricordo, Impostazioni (per ora aprono una pagina vuota con il titolo);
- chat al centro con un messaggio di benvenuto e la casella per scrivere (non collegata a niente);
- canvas a destra, nascosto, che si apre con un'animazione morbida dal pulsante «Mostra canvas» (solo per prova) e si chiude con «Chiudi».
Tema chiaro e scuro: segue Windows, con un pulsante per cambiarlo a mano, ricordato tra un avvio e l'altro. Finestra iniziale 1280×800, minima 960×600, titolo «Assistente di cucina». Testi in italiano. Stile pulito, colori sobri, un solo colore d'accento caldo. Alla fine npm run build senza errori.

===== Tappa 2 · La chat con l’AI di casa =====

Tappa 2 della SPEC (§2 e §3). Collega la chat a Ollama (http://127.0.0.1:11434), facendo le chiamate solo nel processo principale e passando dal preload con IPC tipizzato:
- all'avvio controlla che Ollama risponda; se no, mostra in alto un avviso in italiano «Ollama non risponde: è aperto?» con il pulsante Riprova;
- usa /api/chat in streaming: le parole compaiono mentre arrivano; num_ctx 8192, keep_alive "30m", think false;
- come modello usa, tra quelli installati in Ollama (/api/tags), quello con ruolo "chat" e fascia più alta nel catalogo-modelli.json; mostra il nome sopra la chat;
- pulsante Ferma durante la risposta (interrompe davvero la richiesta);
- risposte in Markdown (react-markdown con remark-gfm), con tabelle ed elenchi;
- sotto ogni risposta: modello, secondi e token al secondo (dai campi eval_count ed eval_duration dell'ultimo pezzo);
- Invio manda, Maiusc+Invio va a capo; la chat scorre in basso da sola;
- il prompt di sistema è sempre identico, all'inizio della conversazione, e prende da SCHEDA-ARGOMENTO.md solo il nome, l'argomento, il tono e le cose da non fare mai. Gli esempi della scheda (allergie, gusti) NON vanno nel prompt: il modello li crederebbe fatti veri;
I messaggi per ora restano in memoria (il salvataggio è la tappa 4). Alla fine npm run build senza errori.

===== Tappa 3 · Il mio PC e il modello giusto =====

Tappa 3 della SPEC (§4 e §5). Crea la pagina «Il mio PC»:
- legge processore, RAM totale e libera, scheda video e memoria video dedicata, esattamente come dice la SPEC (nvidia-smi per NVIDIA, registro di Windows HardwareInformation.qwMemorySize per le altre; mai Win32_VideoController.AdapterRAM, che si ferma a 4 GB). Usa execFile, niente moduli nativi;
- calcola la fascia con le soglie del catalogo-modelli.json e la mostra con una frase semplice («Il tuo PC è in fascia 2 · Comodo»);
- propone il modello di chat migliore che entra (peso del file + 1 GB di margine ≤ memoria video; senza scheda video, ≤ metà della RAM; a parità di fascia vince il primo nell'ordine del catalogo) e il modello di embedding; per ciascuno dice se è già installato;
- pulsante «Scarica» con barra di avanzamento (/api/pull in streaming) e pulsante Annulla;
- pulsante «Prova di velocità»: prima una richiesta di riscaldamento da 1 token (il primo giro dopo il caricamento è lento e falsa la misura), poi una domanda fissa con num_predict 120; mostra i token al secondo e, con /api/ps, la percentuale del modello nella scheda video. Se è sotto 10 token al secondo, spiega in una frase perché e propone il modello più piccolo;
- «Usa questo modello» salva la scelta e il contesto della fascia (in un file impostazioni.json nella cartella dei dati dell'app, per ora) e la chat li usa al posto della scelta automatica.
Alla fine npm run build senza errori.

===== Tappa 4 · Progetti e conversazioni salvati =====

Tappa 4 della SPEC (§6). Salva tutto in SQLite con il modulo node:sqlite integrato (DatabaseSync), nel processo principale, file dati.sqlite nella cartella dei dati dell'app. Niente moduli nativi.
- Tabelle progetti, conversazioni, messaggi come nella SPEC. Al primo avvio crea il progetto «Cucina di casa».
- La sidebar mostra progetti e conversazioni veri, dalla più recente; «Nuova conversazione» ne crea una nel progetto aperto; clic destro su una conversazione: Rinomina, Elimina (con conferma).
- Ogni messaggio inviato e ogni risposta si salvano, con modello, secondi e token al secondo. Riaprendo l'app ritrovo tutto.
- Dopo la prima risposta di una conversazione, in background, chiedi al modello un titolo di massimo 5 parole e aggiornalo nella sidebar. Usa lo stesso num_ctx della chat: con un contesto diverso Ollama ricarica il modello da capo e tutto rallenta (vale per ogni chiamata allo stesso modello).
- Pulsante «+ Progetto» per creare un progetto con nome e istruzioni proprie; le istruzioni del progetto si aggiungono al prompt di sistema, sempre nella stessa posizione.
Alla fine npm run build senza errori, e spiegami dove sta il file dei dati.

===== Tappa 5 · Il pensiero visibile =====

Tappa 5 della SPEC (§5 e §7). Aggiungi il ragionamento:
- sopra la casella un selettore «Ragionamento: Spento / Acceso / Automatico», salvato nelle impostazioni. Automatico = acceso solo se la domanda è lunga (più di 200 caratteri) o chiede conti, confronti o passaggi («calcola», «quanto», «confronta», «perché», «passo per passo»);
- passa think true o false a /api/chat; se il modello non supporta il ragionamento (capacità «thinking» assente in /api/show o nel catalogo) mandalo sempre a false e mostra «non disponibile per questo modello»;
- il pensiero arriva nel campo message.thinking: mostralo mentre arriva in un riquadro grigio con un'animazione leggera («Sto pensando…»); quando finisce si chiude da solo e diventa «Ha pensato per N s», che si riapre con un clic;
- salva il pensiero nel database con il messaggio;
- animazioni brevi (200–300 ms) e niente effetti pesanti: devono andare bene anche su un PC lento.
Alla fine npm run build senza errori.

===== Tappa 6 · La memoria che impara =====

Tappa 6 della SPEC (§8). Aggiungi la memoria:
- tabella ricordi (testo, progetto, embedding, data, attivo). Gli embedding si fanno con /api/embed e il modello di embedding del catalogo (nomic-embed-text); se non è installato, la pagina Il mio PC lo propone già;
- dopo ogni risposta, in background, chiedi al modello di estrarre al massimo 3 fatti stabili sull'utente SOLO dalle frasi dell'utente (allergie, gusti, quante persone, elettrodomestici…). Usa il parametro format di Ollama con uno schema JSON {"fatti": [string]}, temperatura 0 e lo stesso num_ctx della chat. Se non c'è niente di stabile, l'elenco è vuoto;
- niente doppioni: se un fatto nuovo ha similarità del coseno maggiore di 0,9 con un ricordo esistente, non lo salvi;
- prima di rispondere, calcola l'embedding della domanda e aggiungi al prompt di sistema, dopo le istruzioni fisse, i 5 ricordi più vicini con la frase «Cose che sai dell'utente (dette da lui):»;
- pagina «Che cosa ricordo»: elenco dei ricordi con data, Modifica, Elimina, e l'interruttore «Memoria in pausa» (salvato nelle impostazioni: in pausa non si salvano ricordi nuovi e non si usano quelli vecchi);
- un piccolo avviso animato nella chat quando l'app impara qualcosa: «Ho imparato: …», con l'icona di un quaderno.
Alla fine npm run build senza errori.

===== Tappa 7 · I documenti del progetto =====

Tappa 7 della SPEC (§9). Aggiungi i documenti del progetto:
- nell'intestazione della chat un pulsante «Documenti», con l'icona di una cartella, che fa scegliere una cartella per il progetto (finestra di Windows dal processo principale) e la indicizza, con un avviso di avanzamento;
- legge .txt, .md e .pdf (per i PDF usa pdfjs-dist, build «legacy», tutto JavaScript: niente moduli nativi). Testo diviso in pezzi da circa 800 caratteri con 100 di sovrapposizione; embedding con il modello di embedding; tabella pezzi (progetto, file, data di modifica del file, testo, embedding);
- cache: un file si reindicizza solo se la sua data di modifica è cambiata; i file cancellati escono dall'indice;
- prima di rispondere, se il progetto ha documenti, prendi i 4 pezzi più vicini alla domanda (similarità almeno 0,5) e mettili nel prompt di sistema, dopo i ricordi, con il nome del file, chiedendo di citare il file da cui prende la risposta;
- sotto la risposta mostra «Fonti:» solo con i file che la risposta cita davvero: con documenti corti tutti i pezzi superano la soglia, e mostrarli tutti confonde;
- un PDF senza testo (fatto con lo scanner) va segnalato: «Questo PDF sembra una foto: non riesco a leggerne il testo».
Alla fine npm run build senza errori.

===== Tappa 8 · Gli agenti e gli strumenti =====

Tappa 8 della SPEC (§10). Aggiungi gli agenti:
- tabella agenti (nome, emoji, istruzioni, strumenti permessi). Al primo avvio crea i tre agenti della SCHEDA-ARGOMENTO.md. Sopra la casella un selettore: «Assistente» (senza strumenti) oppure un agente;
- strumenti con il tool calling di Ollama (campo tools di /api/chat): cerca_memoria(domanda), cerca_documenti(domanda), calcola(espressione), leggi_file(nome) solo nella cartella del progetto, cerca_web(domanda) solo se «Solo offline» è spento. calcola usa un piccolo calcolatore sicuro (numeri, + − × ÷, parentesi, percentuali): mai eval;
- il ciclo: il modello chiede uno strumento, l'app lo esegue e gli restituisce il risultato (messaggio role "tool"), al massimo 5 passi, poi la risposta finale in streaming;
- nel prompt di sistema dell'agente aggiungi un «Come lavori» numerato, costruito dagli strumenti permessi: prima cerca_memoria invece di fare domande, calcola con tutti i numeri, scrivi_canvas per i documenti, poi rispondi in breve. Senza questo metodo i modelli piccoli fanno domande e si fermano a metà;
- ogni passo compare nella chat in una timeline animata: «Cerco nei documenti: …», «Calcolo: …», ognuno con la sua icona, con l'esito in breve;
- cerca_web e ogni strumento che va fuori dal PC chiedono conferma all'utente con una finestra «Posso cercare sul web: …? Sì / No»;
- se il modello non supporta gli strumenti (capacità «tools»), il selettore degli agenti avvisa «questo modello non sa usare gli strumenti»;
- pagina Impostazioni › Agenti (anche semplice): modifica nome, istruzioni e strumenti permessi.
Alla fine npm run build senza errori.

===== Tappa 9 · Il canvas =====

Tappa 9 della SPEC (§3 e §10). Completa il canvas nella terza colonna:
- aggiungi lo strumento scrivi_canvas(titolo, contenuto) agli agenti che lo hanno tra gli strumenti nella SCHEDA: quando lo usano, il canvas si apre da solo con un'animazione e mostra il documento. Nella descrizione dello strumento chiedi un documento completo, un elemento per riga, mai segnaposto come [inserisci…];
- sotto ogni risposta dell'assistente un pulsante piccolo «Apri nel canvas» che ci copia la risposta;
- nel canvas: titolo modificabile, schede «Anteprima» (Markdown) e «Modifica» (testo), pulsanti Copia, Salva .md e Salva PDF (finestra di Windows per scegliere dove; il PDF lo fa Electron con printToPDF da una finestra nascosta, niente librerie in più), Chiudi;
- togli il pulsante di prova «Mostra canvas» della tappa 1;
- le modifiche fatte nel canvas restano finché non lo chiudi o non arriva un documento nuovo.
Alla fine npm run build senza errori.

===== Tappa 10 · Rifiniture e installer =====

Tappa 10 della SPEC (§11). Rifiniture finali:
- pagina «Modelli»: i modelli installati in Ollama con peso e, se c'è nel catalogo, nome, fascia e nota; per ognuno «Usa per la chat» ed «Elimina» (con conferma, /api/delete); in fondo il link alla pagina Il mio PC per scaricarne altri;
- il tema (Windows / Chiaro / Scuro) passa nelle Impostazioni: togli il pulsante fisso in basso a destra;
- se Ollama non è installato (niente risposta e niente programma), l'avviso spiega come installarlo da ollama.com, con il pulsante che apre il sito nel browser;
- electron-builder: nome del prodotto «Assistente di cucina», appId it.aidicasa.assistentecucina, installer NSIS per l'utente corrente con la scelta della cartella, collegamento sul desktop e nel menu Start, icona da resources/icon.png;
- npm run build:win deve produrre l'installer .exe nella cartella dist. Spiegami l'avviso di SmartScreen che vedrò, perché l'app non è firmata.
Alla fine prova tutto con npm run build e npm run build:win.