La mappa di CATPIT — dove si legge, e come si controlla che sia vera

Quando usarla: prima di toccare o di descrivere qualunque cosa di CATPIT — stanze,
rotte a comandi, dati del vault, agenti, regole di scrittura — e prima di scrivere un
brief su CATPIT per un altro agente.

1. La mappa non sta qui dentro

Sta in:

C:\Users\Ettore\Claude\Agente Residente openclaw\catpit\CONTEXT_FOR_AGENTS.md

È un file generato. Questa skill non ne tiene copia, e non deve tenerne: una copia
invecchia, ed è esattamente il difetto che il generatore ha chiuso — la versione scritta a
mano dichiarava dentro «aggiornato al 4 luglio», raccontava 3 agenti quando erano 6 e
citava stanze nascoste da settimane. Chi la leggeva lavorava su una piantina sbagliata
senza avere modo di accorgersene.

Regola: la mappa si legge sul momento. Non si cita a memoria, non si ricopia dentro
brief, richieste, task o altre skill. Si scrive il percorso e si rimanda lì.

2. Cosa ci trovi, in che ordine leggerlo

1. Riga «Generato:» — data e ora vere della generazione. È la prima cosa da guardare.
2. Tabella «Le fonti lette» — per ogni fonte: percorso, impronta sha256, ultima modifica. Serve al controllo del punto 3.
3. Poi la parte che ti serve:

• Le stanze — codice → rotta, comprese quelle fuori dal menu ma ancora vive;
• Le rotte a comandi — metodi HTTP e action ammesse, lette dal codice;
• Gli agenti — id, stato, modello sul gateway, ruolo;
• I dati — file del vault → colonne/chiavi → chi lo nomina in lib/;
• Le regole di scrittura — copia di sicurezza, lucchetto, archiviazione, id.

3. È fresca? Si controlla, non si dà per buona

Se una fonte risulta modificata dopo la riga «Generato», la pagina è vecchia.

Confronto senza toccare niente (scrive in una copia di lavoro):

cd "C:\Users\Ettore\Claude\Agente Residente openclaw\catpit"
node scripts/genera-contesto.mjs --dove ../tmp/mappa-check.md
diff ../tmp/mappa-check.md CONTEXT_FOR_AGENTS.md

Come si legge l'esito:

• solo la riga «Generato:» diversa → la mappa in uso è fresca: quella riga è l'orologio, cambia a ogni giro. Non è un allarme.
• qualunque altra differenza → la mappa in uso è vecchia: rigenerala.

Poi cancella la copia di lavoro (../tmp/mappa-check.md): è un doppione, e un doppione
di una mappa è il problema da cui siamo partiti.

Per aggiornarla davvero, nella stessa cartella:

npm run contesto

Gira in pochi secondi e stampa il conto di quello che ha letto (stanze, rotte, agenti,
voci del vault): se il conto è vuoto o assurdo, non fidarti del file.

Fail-closed: se una fonte non esiste più o ha cambiato forma, il comando si ferma
dicendo quale fonte e cosa si aspettava, e il file resta com'era. Meglio vecchio e
coerente che fresco e monco. Un errore del generatore non si aggira scrivendo a mano: si
corregge la fonte e si rigenera.

4. Cosa nella mappa NON c'è

• Come si sta al mondo lavorando qui (regole di condotta, soglia delle 600 righe, come parte un agente, documentazione della versione esatta di Next/React/Tailwind): catpit\AGENTS.md, scritto a mano.
• Il metodo di lavoro sul codice (verifiche vere, prova negativa, protocollo di consegna): è il task a112, la skill catpit-dev, ancora da installare.

5. I punti fissi — quelli che nessuna rigenerazione cambia

• App Next.js sulla porta 3010, avviata con next start (non dev): ferma → compila → rilancia. Dopo la build il processo va riavviato, altrimenti gli asset rispondono 500 e la pagina esce senza stile.
• Il master dei dati è `CATPIT_vault\` (CSV + JSON): .bak a ogni scrittura, un solo lucchetto sulle scritture, cancellazione morbida (colonna archiviato, la riga resta), id generati da nextId() e mai scritti a mano.
• Le rotte di scrittura sono POST con un campo `action`. Le action ammesse le elenca la mappa: non si vanno a memoria, e una POST con il campo sbagliato può rispondere ok senza cambiare niente.
• Un avvio vero di un agente costa token: nessun lancio automatico senza un gesto esplicito di Ettore.
• Verifica a schermo su http://127.0.0.1:3010/... con un browser vero: il render offline non conta.
• Trunk del repo: `master`, non main.

6. Se la mappa e il codice non concordano

Vince il codice: la mappa è una lettura del codice, non una fonte a sé. Si corregge la
fonte, si rigenera, e si dichiara cosa si è corretto. Il file generato non si
«aggiusta»: una correzione scritta lì dentro sparisce al rilascio successivo, e nel
frattempo sembra vera.