docs: track security evidence and research notes

docs/plans/2026-09-08-security-hardening-prd.md

@@ -0,0 +1,283 @@
+# PRD — Security hardening per Docker personale e server multiutente
+
+**Stato:** bozza da validare con `grill-with-docs`; implementazione rinviata.
+**Data:** 8 settembre 2026.
+**Owner delle decisioni:** il maintainer di ThothII.
+**Ripresa:** [prompt per la prossima sessione](2026-09-08-security-hardening-resume-prompt.md).
+
+Questo documento conserva la survey di sicurezza discussa con il maintainer e propone requisiti,
+priorità e criteri di accettazione. Non è una spec approvata, un penetration test, una certificazione
+o un'autorizzazione a intervenire sui deploy. Nessun ticket, worktree o intervento applicativo è
+stato avviato per questo PRD. Non è prevista un'esecuzione automatica alla scadenza di una data.
+
+La survey aveva come riferimento HEAD `50c546e42d03281082af3679b8b8d7ce0d01aefa`; alla
+registrazione di questo documento HEAD è `818563c4085c9ebce69dca2cbc15ed71fe13f381`.
+Sono riferimenti per confrontare le revisioni, non attestazioni di un worktree originariamente
+pulito. I rilievi derivano da lettura del codice, controlli locali mirati e audit delle dipendenze:
+non è stata verificata la configurazione effettiva del server remoto. Alla ripresa ogni rilievo
+deve essere riconfermato, chiuso con evidenza oppure riformulato rispetto al codice corrente.
+
+## Problema
+
+ThothII deve avere un perimetro di sicurezza comprensibile e verificabile sia come applicazione
+Docker su un Mac o PC personale, sia come installazione server condivisa con autenticazione
+built-in oppure OIDC. Le protezioni esistenti non bastano, da sole, a dimostrare isolamento fra
+utenti, contenimento dell'agente e controllo delle informazioni inviate ai modelli.
+
+In particolare, autenticare un utente non equivale ad autorizzarlo su una sessione o sui dati di
+un workspace; un gate del workflow non equivale a una sandbox; cifrare un vault non protegge
+dal furto congiunto del vault e della sua chiave.
+
+## Risultato desiderato
+
+L'operatore sceglie un profilo supportato, riceve una diagnosi chiara delle configurazioni
+incompatibili e può verificare i controlli con prove ripetibili. L'utente accede soltanto alle
+risorse consentite. Credenziali e dati sorgente attraversano esclusivamente i confini approvati.
+I rischi residui sono espliciti e accettati dal maintainer, non dedotti dal passaggio dei test.
+
+### Profili da confermare
+
+| Profilo | Confine e aspettativa proposta | Decisione ancora necessaria |
+| --- | --- | --- |
+| Docker personale, singolo utente | Host fidato; interfaccia pubblicata su loopback; servizi interni non pubblici | Eventuale modalità senza login, accesso LAN e deroghe TLS ammesse |
+| Server multiutente, built-in | HTTPS, account distinti, autorizzazione server-side e sessioni separabili | Risorse condivise, ruoli, recupero account e requisiti MFA |
+| Server multiutente, OIDC | Stesse garanzie applicative; IdP come fonte di identità e attributi concordati | Mapping dei gruppi, scadenze, revoca e comportamento con IdP indisponibile |
+
+Il luogo del deploy, la modalità di autenticazione e il backend di persistenza sono assi distinti.
+In particolare, “Docker in locale” non significa necessariamente modalità di autenticazione
+`local`, né richiede necessariamente persistenza filesystem. “Multiutente” non implica una
+piattaforma SaaS multi-tenant: va deciso se gli utenti condividono gli stessi diritti sui dati.
+
+### Confini di fiducia
+
+- Browser e richieste HTTP rispetto a reverse proxy, backend e identità autenticata.
+- Utente A rispetto a sessioni, stream, artefatti e risorse dell'utente B.
+- Processo Pi e contenuti non fidati rispetto a filesystem, credenziali e altri processi.
+- ThothII rispetto a DWH, IdP, provider LLM ed endpoint embedding.
+- Dati operativi rispetto a log, tracce Pi, indici, esportazioni e backup.
+- Immagini e dipendenze distribuite rispetto al runtime installato.
+
+Considerare almeno: richieste non autenticate, utente autenticato che tenta accessi non consentiti,
+contenuti DWH/documentali che inducono l'agente ad azioni improprie, segreti esposti accidentalmente
+e richieste che consumano risorse eccessive. La compromissione dell'amministratore dell'host non
+viene considerata risolvibile dal solo hardening applicativo; va esplicitato cosa resta esposto.
+
+## User stories
+
+1. Come operatore personale, voglio avviare Docker senza pubblicare involontariamente il servizio sulla rete.
+2. Come operatore server, voglio che combinazioni di autenticazione, esposizione e storage non sicure siano rifiutate con un rimedio leggibile.
+3. Come utente, voglio che conoscere l'ID di una sessione altrui non mi permetta di leggerla o modificarla.
+4. Come amministratore, voglio definire quali workspace e dati sono condivisi e quali richiedono autorizzazioni distinte.
+5. Come utente, voglio che login built-in e OIDC producano le stesse garanzie di autorizzazione applicativa.
+6. Come amministratore, voglio che logout, revoca e rimozione dei diritti abbiano tempi di efficacia dichiarati, inclusi gli stream aperti.
+7. Come responsabile dei dati, voglio che i valori sensibili non raggiungano un destinatario non autorizzato attraverso il grounding o la generazione.
+8. Come operatore, voglio verificare identità e cifratura del DWH, ricevendo un errore se la verifica richiesta fallisce.
+9. Come operatore, voglio che Pi disponga soltanto delle risorse necessarie al lavoro approvato.
+10. Come utente, voglio continuare a usare i gate umani e il resume senza perdere le protezioni di isolamento.
+11. Come responsabile dei dati, voglio sapere quali contenuti sono persistiti e per quanto tempo, anche fuori dagli artefatti di workflow.
+12. Come operatore, voglio diagnosticare errori senza leggere API key, password, token o campioni sensibili nei log.
+13. Come utente di un server condiviso, voglio che una richiesta costosa di un altro utente non esaurisca tutte le risorse disponibili.
+14. Come operatore dietro proxy, voglio limiti e controlli HTTP che usino correttamente l'origine delle richieste.
+15. Come maintainer, voglio aggiornamenti delle dipendenze verificabili e distribuzioni riproducibili.
+16. Come operatore, voglio backup ripristinabili con protezioni e limiti della cifratura espliciti.
+17. Come maintainer, voglio test negativi che dimostrino il rifiuto degli abusi, oltre ai percorsi leciti.
+18. Come operatore, voglio istruzioni di adozione e rollback per ogni cambiamento che coinvolge dati o configurazioni esistenti.
+
+## Registro dei rilievi della survey
+
+Le priorità sono proposte, condizionate al profilo e all'esposizione. **P0** indica un candidato
+bloccante per il rilascio del profilo interessato, **P1** il successivo hardening e **P2** il
+consolidamento. Non sono punteggi CVSS né affermazioni di sfruttabilità già dimostrata.
+
+| ID | Evidenza o limite osservato nella survey | Rischio da verificare | Priorità proposta |
+| --- | --- | --- | --- |
+| SEC-01 | Senza session storage PostgreSQL il resolver usa il principal locale e il repository filesystem usa una radice condivisa | Attribuzione e separazione delle sessioni in combinazioni multiutente non supportate | P0 server; verificare prima i vincoli di configurazione già presenti |
+| SEC-02 | Pi è un processo figlio del core; il gate dichiara di non essere una sandbox | Accesso a risorse o credenziali oltre il compito, anche per effetto di contenuti non fidati | P0 se si promette isolamento fra utenti non fidati; P1 personale |
+| SEC-03 | Nel percorso DWH diretto era emersa una discontinuità fra configurazione TLS resa dal deployment e configurazione consumata dal connettore | TLS richiesto ma non applicato o verificato come atteso | P0 per connessioni che richiedono TLS; riconfermare per ogni driver |
+| SEC-04 | Il grounding LSH restituisce valori reali; l'applicazione del Sensitive Data Flag a questo percorso è un follow-up esplicitamente rinviato | Valori sensibili nel contesto di un modello non autorizzato | P0 se quel percorso usa dati sensibili e un destinatario non autorizzato |
+| SEC-05 | Pi ha una propria directory di sessione; la survey non ha trovato l'opzione che disabilita la persistenza nel lancio esaminato | Tracce aggiuntive rispetto agli artefatti dichiarati, con retention non verificata | P1; presenza e contenuto effettivo delle tracce da verificare |
+| SEC-06 | Gruppi OIDC fotografati al login; autenticazione SSE all'apertura, senza evidenza di chiusura alla revoca | Permessi o stream utilizzabili oltre il tempo di revoca atteso | P1 server; elevare se il requisito richiede revoca immediata |
+| SEC-07 | La permission di uso delle sessioni consente l'accesso all'elenco dei workspace senza una ACL per workspace osservata | Accesso ai dati più ampio del previsto se i diritti differiscono fra utenti | P0 con diritti differenziati; scelta esplicita altrimenti |
+| SEC-08 | Un LIMIT già presente può superare il limite applicativo; fetch completo prima del taglio del risultato | Consumo eccessivo di memoria, DWH, processi e budget modello | P1, con particolare rilievo multiutente |
+| SEC-09 | Rate limit basato sull'IP della richiesta; configurazione proxy fidati e hardening degli header da completare/verificare | Contatori condivisi impropriamente, fiducia errata negli header o difese browser incomplete | P1 server |
+| SEC-10 | Audit storico con advisory nel runtime Pi; dipendenze Python runtime non interamente vincolate da un lock nella build esaminata | Vulnerabilità dipendenti dalla versione e build non riproducibili | P1; nuova scansione e verifica di raggiungibilità obbligatorie |
+| SEC-11 | Core non-root, ma senza tutte le restrizioni osservate nel servizio di manutenzione | Impatto maggiore di un processo compromesso | P1 server, P2 personale salvo rischio specifico |
+| SEC-12 | Vault cifrato con chiave locale adiacente; backup esaminato non cifrato come archivio | Copia congiunta di chiave e dati; esportazioni o backup troppo accessibili | P1 se esportati fuori dall'host, altrimenti priorità da concordare |
+
+La survey aveva anche rilevato controlli da preservare: hashing Argon2id, cookie di sessione
+opachi con HttpOnly/SameSite, controlli CSRF/origin, OIDC con PKCE e nonce, revoca applicativa,
+RLS PostgreSQL, query read-only con timeout, container non-root e assenza di mount del socket
+Docker. La RLS dipendente dall'identità impostata dall'applicazione non sostituisce una sandbox
+contro codice che possiede le credenziali del database.
+
+## Requisiti e accettazione proposti
+
+Questi sono esiti da validare, non scelte implementative già approvate. Soglie, eccezioni e
+semantica dei permessi vanno fissate nel grilling prima di rendere i ticket eseguibili.
+
+### R1 — Profili supportati e proprietà delle sessioni (SEC-01)
+
+- Descrivere la matrice consentita di esposizione, autenticazione e persistenza; rifiutare le combinazioni incompatibili prima di accettare traffico.
+- Con due utenti distinti, verificare elenco, lettura, modifica, resume, artefatti e SSE: un accesso fuori dai diritti deve essere rifiutato senza rivelare contenuti.
+- Il percorso personale supportato deve continuare a funzionare; non introdurre un fallback silenzioso al principal locale sul server.
+
+### R2 — Contenimento del runtime agente (SEC-02)
+
+- Concordare tool, directory, segreti ed egress necessari a Pi, nonché il livello di fiducia fra gli utenti.
+- Dimostrare con fixture controllate che un'azione non autorizzata non accede a risorse di un'altra sessione o a credenziali non necessarie.
+- Verificare che il contenimento scelto mantenga funzionanti workflow, gate e resume. Se il confine scelto non garantisce isolamento ostile, documentare e approvare quel limite.
+
+### R3 — TLS DWH end-to-end (SEC-03)
+
+- Per ogni driver supportato, verificare che i parametri TLS arrivino al connettore realmente usato.
+- CA valida e nome corretto devono consentire la connessione; CA non fidata, nome errato o downgrade vietato devono fallire quando il profilo richiede verifica TLS.
+- Eventuali eccezioni personali devono essere deliberate, visibili e prive di fallback automatico.
+
+### R4 — Controllo della divulgazione dei valori (SEC-04)
+
+- Applicare la policy approvata prima che risultati LSH e altri campioni raggiungano il prompt, non soltanto nella UI.
+- Testare Sensitive Data Flag e Model Data Boundary alle interfacce effettive di uscita; verificare che il valore protetto sia assente, non solo che un helper sia stato chiamato.
+- Decidere il comportamento con classificazione mancante, nuovi campi, indici già pubblicati e flag cambiati dopo l'indicizzazione.
+- Rispettare il gate di owner acceptance già registrato per il follow-up schema-linking; confermarne lo stato prima di implementare.
+
+### R5 — Persistenza, retention e log (SEC-05)
+
+- Inventariare artefatti, tracce Pi, temporanei, log, indici ed esportazioni realmente prodotti.
+- Definire abilitazione, contenuto ammesso, accessi, retention e cancellazione per ciascuna classe.
+- Una sessione di prova con segreti-canary e dati sintetici deve dimostrare l'assenza dei contenuti vietati; la pulizia deve preservare gli artefatti necessari al resume.
+
+### R6 — Revoca e ciclo di vita dell'identità (SEC-06)
+
+- Concordare tempi massimi distinti per revoca applicativa e variazione dei diritti nell'IdP, senza promettere sincronizzazione istantanea non supportata.
+- Verificare logout, revoca amministrativa, scadenza, cambio dei gruppi, stream già aperti e riconnessione.
+- Stabilire se e come gestire processi in corso quando cambiano i diritti; definire il comportamento durante indisponibilità delle fonti di validità.
+
+### R7 — Autorizzazione alle risorse condivise (SEC-07)
+
+- Decidere il perimetro condiviso di workspace, DWH, catalogo e amministrazione.
+- Se i diritti sono differenziati, applicarli alle API e alle operazioni di creazione/resume, non soltanto al selettore frontend.
+- Se tutti gli utenti autorizzati condividono i dati, renderlo un contratto esplicito senza presentarlo come isolamento multi-tenant.
+
+### R8 — Limiti effettivi e disponibilità (SEC-08)
+
+- Fissare limiti per righe, byte, durata, concorrenza e chiamate al modello; valutare quote per utente sul server.
+- Verificare SQL con LIMIT assente o eccessivo e risultati voluminosi: il consumo deve essere limitato prima del fetch completo, non soltanto nella risposta.
+- Timeout e cancellazione devono rilasciare risorse; una richiesta abusiva non deve impedire il lavoro lecito dell'altro utente entro i limiti concordati.
+
+### R9 — Reverse proxy e difese HTTP (SEC-09)
+
+- Dichiarare i proxy fidati e verificare sia il corretto riconoscimento del client sia il rifiuto di header inoltrati da sorgenti non fidate.
+- Verificare rate limit, origini ammesse, cookie e protezioni CSRF nei percorsi diretto e HTTPS dietro proxy.
+- Definire una policy per gli header di sicurezza e CSP compatibile con frontend e SSE; testare il comportamento effettivo del browser.
+
+### R10 — Dipendenze e build (SEC-10)
+
+- Rigenerare l'inventario delle dipendenze effettivamente distribuite, includendo Pi, Python e immagini base; separare runtime e sviluppo.
+- Per ogni advisory rilevante, registrare versione, percorso, raggiungibilità, rimedio o accettazione motivata. I conteggi dell'audit storico non sono una baseline aggiornata.
+- Rendere riproducibile la risoluzione delle dipendenze concordate e verificare un rebuild; evitare aggiornamenti indiscriminati scollegati dai rilievi.
+
+### R11 — Hardening Docker (SEC-11)
+
+- Applicare il minimo privilegio a capability, privilegi, mount scrivibili, rete e risorse, secondo il runtime concordato.
+- Verificare che porte e mount esposti corrispondano al profilo; Qdrant, catalogo ed embedding non devono diventare pubblici per effetto di un default inatteso.
+- Eseguire uno smoke test di avvio, workflow, manutenzione e arresto con le restrizioni abilitate; documentare le directory che richiedono scrittura.
+
+### R12 — Segreti, backup e ripristino (SEC-12)
+
+- Definire chi può leggere e copiare segreti, chiavi e backup; verificare permessi e redazione degli output.
+- Concordare la protezione degli archivi esportati e la gestione della chiave: un archivio contenente anche la chiave di decifratura non è protetto da quella sola cifratura.
+- Provare ripristino e rotazione su dati sintetici. Il modello di minaccia e l'eventuale rischio accettato devono accompagnare le istruzioni operative.
+
+## Decisioni aperte per `grill-with-docs`
+
+Il seguente elenco è una mappa delle decisioni, non un questionario da somministrare tutto insieme.
+La skill deve chiedere, a ogni round, soltanto le decisioni i cui prerequisiti sono già risolti.
+
+1. Quali profili devono essere supportati e quali minacce devono contenere? Gli utenti server sono reciprocamente fidati?
+2. Tutti gli utenti vedono gli stessi workspace e dati? Quali operazioni sono amministrative?
+3. Quale esecuzione di tool è indispensabile a Pi e quale confine di isolamento è sostenibile sul desktop e sul server?
+4. Quali dati possono raggiungere modelli esterni? Quale policy vale per classificazione assente o incompleta?
+5. Quale semantica e latenza di revoca servono per built-in, OIDC, SSE e lavori già in corso?
+6. Quali tracce sono utili al prodotto e alla diagnosi? Con quali durata, accessi e cancellazione?
+7. Quali limiti di risorse, eccezioni TLS e garanzie sui backup sono necessari nei due contesti?
+8. Quali rischi bloccano un rilascio, quali sono accettabili temporaneamente e chi ne approva l'accettazione?
+9. Quali confini pubblici verranno testati, con quali fixture e gate manuali? Quali migrazioni richiedono una prova di rollback?
+
+Le risposte devono distinguere **decisione confermata**, **proposta** e **fatto da verificare**.
+Non cambiare implicitamente ADR esistenti. Un nuovo ADR è opportuno soltanto per una decisione
+costosa da invertire, sorprendente senza contesto e frutto di alternative reali; può bastare un
+titolo e un breve paragrafo. `CONTEXT.md` resta un glossario, non il contenitore del PRD.
+
+## Strategia di test da approvare
+
+Preferire le interfacce pubbliche già esistenti: API HTTP/SSE con due identità, CLI e repository
+di sessione nel loro percorso reale, connettori DWH, uscita verso i provider e lifecycle Docker.
+Il numero di confini va mantenuto piccolo senza ridurre tutto a test unitari che non attraversano
+la protezione da dimostrare.
+
+Ogni requisito approvato deve avere un caso lecito e un caso negativo, con dati sintetici,
+precondizioni esplicite e risultato osservabile. Usare fixture locali per IdP, DWH e provider;
+testare l'integrazione reale soltanto in un ambiente di prova autorizzato. I valori numerici dei
+limiti e delle latenze devono diventare assert misurabili prima dell'implementazione.
+
+Confermare i confini con il maintainer prima di scrivere test. Usare `tdd` una fetta alla volta:
+test rosso sul comportamento, implementazione minima, test verde. Eseguire typecheck e test
+mirati durante il lavoro, le suite pertinenti al termine e `code-review` separando Standards e
+Spec contro una base Git fissata. Il passaggio dei test automatici non chiude i gate manuali.
+
+## Sequenza proposta, non ancora trasformata in ticket
+
+1. Riconfermare i rilievi e chiudere le decisioni che determinano il modello di minaccia.
+2. Approvare profili, confini di test e criteri di rilascio; aggiornare questo PRD.
+3. Usare `to-spec` per la spec concordata e, con autorizzazione, pubblicarla nel tracker Gitea canonico.
+4. Usare `to-tickets` per fette verticali autonomamente verificabili, ciascuna con dipendenze reali e criteri di accettazione; far approvare la scomposizione prima della pubblicazione.
+5. Dare precedenza ai rischi P0 effettivi del profilo scelto, senza attendere il completamento dell'intero hardening per consegnare un controllo verificabile.
+6. Dopo autorizzazione, implementare un ticket per contesto fresco nel worktree dedicato; chiudere con test, review e istruzioni operative.
+
+Non creare automaticamente una issue per ogni riga della survey: alcune richiedono prima una
+decisione, altre possono essere già risolte. Il tracker è Gitea, non il mirror GitHub. Le issue
+prodotte da `to-tickets` dopo approvazione sono già pronte per `ready-for-agent`, senza ulteriore
+triage; questa bozza non lo è. Dopo la pubblicazione, collegare qui la spec canonica e segnalare
+che questo documento è la baseline storica, evitando due specifiche concorrenti.
+
+## Vincoli, adozione e fuori perimetro
+
+- Oggi sono autorizzati soltanto questi documenti e la loro navigazione. Nessuna modifica a codice, credenziali, container, server, IdP o database.
+- La ripresa parte da analisi e grilling. Creazione del worktree, pubblicazione delle issue e implementazione richiedono conferma del maintainer nella sessione futura.
+- Per il worktree, verificare base, nome e percorso e preservare tutte le modifiche preesistenti. Non copiare automaticamente `.env`, chiavi, dati reali o volumi operativi.
+- Ogni modifica incompatibile deve descrivere diagnosi preventiva, adozione, migrazione, backup e rollback. Non migrare o cancellare sessioni reali durante i test.
+- Preservare workflow a otto fasi, gate umani, resume, persistenza degli artefatti, DWH read-only e Installation Model Catalog come autorità dei modelli.
+- Sono fuori perimetro: redesign generico, nuove funzionalità di prodotto non necessarie, sostituzione generalizzata dell'autenticazione, SaaS multi-tenant, pentest remoto e certificazioni di conformità.
+- Il problema separato della visibilità dei modelli sul server non fa parte di questo PRD.
+
+## Criteri di completamento del futuro intervento
+
+Il lavoro è completo quando tutti i requisiti della spec approvata hanno evidenze e tracciamento,
+i profili supportati superano i controlli automatici e i gate manuali concordati, le procedure di
+adozione/ripristino sono verificate e i rischi residui hanno una decisione esplicita dell'owner.
+Un rilievo storico smentito va chiuso con evidenza, non implementato per inerzia. La chiusura di
+un sottoinsieme approvato non deve essere presentata come risoluzione di tutti i rilievi.
+
+## Appendice — Punti di partenza per riconfermare le evidenze
+
+Questi riferimenti sono indizi della survey, non prescrizioni sui file da modificare. Cercare i
+simboli e i percorsi correnti alla ripresa; le righe e la distribuzione dei moduli possono cambiare.
+
+| Rilievo | Punti di partenza nel repository |
+| --- | --- |
+| SEC-01 | `harness/tht/session/repository.py` (`resolve_principal`), `filesystem_repository.py`, `backend/src/config.ts`; [architettura auth](../architecture/authentication.md) |
+| SEC-02 | `backend/src/pi/pi-process-manager.ts`, `provider-credentials.ts`, `harness/.pi/extensions/tht-gate.js`, repository PostgreSQL e identità di connessione |
+| SEC-03 | Renderer dell'installazione, `harness/tht/config.py`, `harness/tht/db/connection.py`; [contratto DWH](../contracts/tht-dwh.md) |
+| SEC-04 | `harness/tht/cli/search_cmd.py`, runtime LSH, worker descrizioni; [ADR-0011](../adr/0011-gate-source-samples-with-a-sensitive-data-flag.md) e gate in `PROJECT_STATE.md` |
+| SEC-05 | `backend/src/pi/managed-config.ts`, argomenti del processo Pi, versione Pi nel lockfile e comportamento della libreria effettivamente distribuita |
+| SEC-06 | `backend/src/auth/session-store.ts`, `backend/src/routes/sessions.ts`, SSE hub; [OIDC](../install/authentication-oidc.md) |
+| SEC-07 | `backend/src/routes/workspaces.ts`, ammissione delle sessioni e policy dei permessi |
+| SEC-08 | `harness/tht/execute/__init__.py` (`_inject_limit`, fetch dei risultati), timeout e limiti del process manager |
+| SEC-09 | `backend/src/app.ts`, rate limiter del login, configurazione proxy e risposte HTTP del deploy di prova |
+| SEC-10 | Lockfile backend/frontend/Pi, installazione Python nell'immagine core e inventario immagini; advisory storici su `undici`, `brace-expansion`, `protobufjs` e relativa dipendenza Pi da rivalutare |
+| SEC-11 | Dockerfile e Compose in `deploy/`, confronto fra core e manutenzione, `docker inspect` con output sanitizzato solo su ambiente autorizzato |
+| SEC-12 | `backend/src/workspaces/secret-store.ts`, backup/restore in `tools/tht`; [ADR-0002](../adr/0002-workspace-database-secret-references.md) |
+
+Per le decisioni collegate consultare anche [ADR-0010](../adr/0010-allow-bounded-real-source-samples-for-description-generation.md),
+[ADR-0013](../adr/0013-use-one-installation-model-catalog-with-runtime-projections.md),
+gli ADR correnti sulla sensitivity e le istruzioni in `docs/agents/`.

docs/plans/2026-09-08-security-hardening-resume-prompt.md

@@ -0,0 +1,100 @@
+# Riprendere il PRD di sicurezza con le skill di Pocock
+
+**Stato:** prompt conservato per uso futuro; nessuna esecuzione programmata.
+**PRD:** [Security hardening per Docker personale e server multiutente](2026-09-08-security-hardening-prd.md).
+
+Apri una sessione nella codebase ThothII e incolla il blocco seguente. Il nome corretto della
+skill è `grill-with-docs`, che combina `grilling` e `domain-modeling`. Il prompt apre la fase di
+chiarimento; il passaggio a issue, worktree e implementazione resta soggetto alle conferme indicate.
+
+```text
+Riprendiamo il lavoro di sicurezza rinviato l'8 settembre 2026.
+
+Leggi docs/plans/2026-09-08-security-hardening-prd.md. È una bozza di PRD ricavata da una
+survey storica, non una spec approvata né una prova della configurazione del server remoto.
+Voglio preparare interventi proporzionati per Docker su Mac/PC personale e per un server
+multiutente con autenticazione built-in oppure OIDC. Il problema separato dei modelli
+visibili sul server è fuori perimetro.
+
+Usa realmente le skill di Matt Pocock: leggi le istruzioni installate, dichiarando quali
+applichi. Parti da ask-matt per verificare il percorso e da grill-with-docs per il lavoro
+di design; quest'ultima richiede grilling e domain-modeling. Se una skill non è disponibile,
+segnalalo e concorda il fallback, senza installarla o fingere di averla eseguita.
+
+FASE 1 — Riconferma delle evidenze, senza modificare il runtime
+
+1. Leggi AGENTS.md, PROJECT_STATE.md, CONTEXT.md, le istruzioni docs/agents/ su dominio,
+   issue tracker e label, gli ADR pertinenti e il PRD. Controlla HEAD, stato del worktree
+   e differenze dalla baseline della survey. Preserva tutte le modifiche preesistenti.
+2. Riconferma i rilievi SEC-01…SEC-12 nel codice corrente. Separa fatti verificati,
+   ipotesi, rischi condizionati al profilo e problemi già risolti. Non trattare i vecchi
+   conteggi delle dipendenze come una scansione aggiornata.
+3. Usa controlli locali read-only e dati sintetici. Per un difetto da riprodurre, usa
+   diagnosing-bugs con un segnale ripetibile sul comportamento effettivo; una diagnosi
+   non autorizza ancora il fix. Confronta fatti di librerie e advisory con fonti primarie
+   correnti quando necessario, senza inviare codice privato o segreti ai servizi di ricerca.
+4. Non accedere o intervenire su server, IdP, DWH o provider reali senza aver concordato
+   target e operazioni. Non mostrare API key, cookie, password o campioni di dati reali.
+
+Esito della fase: una matrice aggiornata che conserva gli ID dei rilievi, con evidenza,
+profilo interessato e stato. Un fatto ancora non verificabile resta esplicitamente aperto.
+
+FASE 2 — grill-with-docs, con me presente
+
+5. Costruisci l'albero delle decisioni. Parti da profili di deploy, fiducia fra utenti e
+   condivisione dei dati; poi affronta isolamento di Pi, policy dei valori sensibili,
+   revoca, retention e limiti seguendo le dipendenze effettive.
+6. A ogni round presenta soltanto le domande attualmente sbloccate, numerate, con la tua
+   raccomandazione e i trade-off. Attendi le mie risposte prima di assumere le decisioni
+   successive. Cerca autonomamente i fatti ricavabili dal repository; usa agenti di
+   ricerca mirati quando previsto dalla skill, senza delegare a loro le mie decisioni.
+7. Aggiorna il PRD distinguendo proposte e decisioni confermate. Aggiorna CONTEXT.md solo
+   per termini realmente risolti. Proponi ADR soltanto per scelte difficili da invertire,
+   sorprendenti senza contesto e fondate su alternative reali: basta il formato minimo.
+8. Concorda requisiti, priorità, rischi accettati e criteri misurabili, inclusi i tempi
+   di revoca e i limiti di risorse. Conferma con me i confini pubblici dei test prima
+   di scriverli. Mantieni espliciti i gate manuali già presenti in PROJECT_STATE.md.
+
+Esito della fase: nessuna decisione bloccante lasciata implicitamente all'agente;
+riepilogo e mia conferma della comprensione condivisa. Fino a quella conferma rimani
+su analisi e documentazione: nessun cambiamento applicativo o di deployment.
+
+FASE 3 — Spec e ticket, soltanto dopo mia conferma
+
+9. Usa to-spec per sintetizzare le decisioni già prese, senza riaprire arbitrariamente
+   l'intervista. Chiedimi conferma della pubblicazione prima di creare la spec nel
+   tracker canonico Gitea indicato in docs/agents/issue-tracker.md, non nel mirror GitHub.
+   Collega la spec canonica dal PRD e rendi chiaro quale documento è la fonte aggiornata.
+10. Usa to-tickets per proporre fette verticali verificabili autonomamente, dimensionate
+    per un contesto fresco. Collega ogni ticket ai requisiti e ai rilievi pertinenti,
+    indica i veri blocker e includi criteri positivi e negativi. Fai approvare granularità
+    e dipendenze prima di pubblicare. Solo i ticket approvati e completi ricevono
+    ready-for-agent; non rimetterli in triage e non chiudere automaticamente la spec padre.
+11. Se una decisione richiede una prova eseguibile, proponi un prototype limitato a quella
+    domanda prima di fissare la spec. Usa wayfinder solo se il lavoro risulta realmente
+    troppo ampio e incerto per essere chiarito con grill-with-docs.
+
+Esito della fase: spec approvata e ticket autosufficienti con dipendenze risolte o esplicite.
+Chiedimi se autorizzo il primo ticket: l'approvazione del design non avvia da sola il codice.
+
+FASE 4 — Implementazione futura autorizzata
+
+12. Prima di modificare codice, concorda e crea un worktree dedicato, verificando percorso,
+    branch e commit base. Non riusare una directory occupata, non alterare il worktree
+    originario e non copiare automaticamente segreti o dati operativi. Assicurati che
+    PRD e prompt siano disponibili nel worktree attraverso un passaggio esplicito.
+13. Esegui implement su un ticket sbloccato per volta, in un contesto fresco. Segui tdd
+    ai confini concordati: un test rosso sul comportamento, implementazione minima,
+    test verde. Esegui typecheck e test mirati durante il lavoro e le suite pertinenti
+    al termine; usa fixture locali per IdP, DWH e provider.
+14. Esegui code-review sui due assi Standards e Spec, usando i due agenti previsti dalla
+    skill e una base Git fissata. Assicurati che il diff esaminato includa tutto il lavoro
+    del ticket, anche se ancora non committato; un diff vuoto non è una review superata.
+    Risolvi i rilievi e verifica di nuovo. Commit soltanto del lavoro pertinente nel
+    worktree autorizzato; push, merge e deploy richiedono un'autorizzazione distinta.
+15. Consegna evidenze dei test, istruzioni di adozione e rollback, gate manuali pendenti
+    e rischi residui. Non dichiarare chiuso il PRD intero se è concluso soltanto un ticket
+    o se resta un'accettazione dell'owner.
+
+Inizia dalla Fase 1, poi proponimi il primo round di grill-with-docs.
+```

docs/research/2026-09-07-antigravity-gemini-flash-value.md

@@ -0,0 +1,122 @@
+# Google Antigravity e Gemini 3.8 Flash: convenienza costo/qualità
+
+Verifica effettuata il **7 settembre 2026**, privilegiando documentazione e annunci
+ufficiali Google. Le prove indipendenti su Gemini 3.8 Flash sono ancora limitate perché il
+modello è stato pubblicato il 2 settembre 2026.
+
+## Giudizio sintetico
+
+- **Registrazione gratuita: decisamente conveniente.** Il piano Individual da $0 include
+  Gemini 3.8 Flash, l'ultima versione Flash, oltre alla CLI e alle funzioni principali di
+  Antigravity. È difficile ottenere un rapporto costo/qualità migliore di un accesso gratuito
+  a un modello di questa fascia.
+- **Google AI Pro da circa $20/mese: probabilmente conveniente per uso regolare**, ma solo dopo
+  aver misurato il consumo sul piano gratuito. Google non pubblica un numero fisso di prompt o
+  token inclusi, quindi non è possibile calcolare un break-even affidabile contro l'API.
+- **Ultra da $100 o $200: non lo comprerei per il solo Gemini Flash** senza aver già dimostrato
+  di saturare Pro. Il piano da $100 offre 5 volte la quota Pro; quello da $200 ne offre 20 volte.
+- Per il server dietro CyberArk, Antigravity ha un vantaggio concreto: la CLI ufficiale `agy`
+  funziona direttamente in Linux e prevede esplicitamente un flusso OAuth remoto tramite URL e
+  codice, senza tunnel né port forwarding.
+
+## Accesso e prezzi
+
+La [pagina ufficiale dei piani Antigravity](https://www.antigravity.google/docs/plans/) e la
+[tabella dei modelli](https://www.antigravity.google/docs/models/) indicano che Gemini 3.8 Flash
+è disponibile su Individual gratuito, AI Plus, AI Pro, AI Ultra ed Enterprise. Il piano gratuito
+include anche completamenti Tab illimitati e tutte le funzioni del prodotto, inclusa la CLI, ma
+ha un limite settimanale di base.
+
+Google AI Pro costa normalmente **$19,99/mese** nella pagina internazionale di
+[Google One](https://one.google.com/about/plans) e offre quote Antigravity superiori, con rinnovo
+ogni cinque ore finché non viene raggiunto il limite settimanale. Google AI Ultra è offerto a
+[$100/mese con quota 5× Pro oppure $200/mese con quota 20× Pro](https://blog.google/products-and-platforms/products/google-one/google-ai-subscriptions/).
+
+Il problema è la misurabilità: Google dichiara che i limiti dipendono dalla capacità disponibile
+e dalla quantità di lavoro compiuta dall'agente, possono cambiare e non corrispondono a un numero
+pubblico fisso di richieste o token. Pro e Ultra possono acquistare crediti per continuare oltre
+la quota base, con consumo ai prezzi della piattaforma Gemini.
+
+Usando direttamente la Gemini API, Gemini 3.8 Flash costa fino al 31 dicembre 2026:
+
+- **$0,75 per milione di token di input**;
+- **$3,75 per milione di token di output**, inclusi i token di ragionamento;
+- la metà in modalità Batch o Flex.
+
+Dal 1º gennaio 2027 questi prezzi raddoppieranno a $1,50/$7,50. Esiste anche un free tier API,
+con limiti, nel quale input e output sono gratuiti ma i contenuti possono essere usati per
+migliorare i prodotti Google. Fonte: [pricing ufficiale Gemini API](https://ai.google.dev/gemini-api/docs/pricing).
+
+## Qualità del modello
+
+[Gemini 3.8 Flash](https://ai.google.dev/gemini-api/docs/models/gemini-3.8-flash) è GA, offre un
+contesto da 1.048.576 token, output fino a 65.536 token, livelli di ragionamento low/medium/high e
+strumenti per code execution, computer use, file search, function calling e search grounding.
+
+I risultati pubblicati da Google lo collocano molto vicino ai modelli flagship su alcuni test di
+coding, ma non su tutti:
+
+| Benchmark | Gemini 3.8 Flash | Claude Opus 5 | GPT-5.6 Sol | Lettura onesta |
+|---|---:|---:|---:|---|
+| DeepSWE v1.1 | 73,7% | 74,0% | 72,7% | Prestazione quasi flagship sul software engineering end-to-end |
+| Terminal-Bench 2.1 | 89,4% | 89,1% | 88,8% | Eccellente nel terminale sul benchmark più maturo |
+| Terminal-Bench 4.0 | 19,1% | 51,8% | 37,3% | Forte calo sul test nuovo e più difficile: non è universalmente al livello dei flagship |
+
+La [metodologia ufficiale Google](https://deepmind.google/models/evals-methodology/gemini-3-8-flash/)
+precisa che diversi punteggi Gemini sono calcolati internamente e che i concorrenti provengono
+anche da risultati auto-dichiarati; inoltre DeepSWE usa mini-swe, mentre Terminal-Bench usa un
+harness diverso. I numeri vanno quindi letti come indicazione, non come garanzia. Una
+[ricostruzione della tabella e dei confronti](https://www.vellum.ai/blog/gemini-3-8-flash-benchmarks-explained)
+mostra lo stesso andamento: molto competitivo sui compiti di coding già ben rappresentati, più
+debole su alcune prove nuove e aperte.
+
+La conclusione qualitativa è: **ottimo implementatore quotidiano e subagente veloce**, con qualità
+da modello molto più costoso in diversi task; per architettura difficile, debugging ambiguo o
+lavori ad alto rischio è ancora sensato affiancargli un modello più forte come pianificatore o
+revisore.
+
+## Perché Antigravity è particolarmente adatto al server
+
+La [CLI ufficiale Antigravity](https://antigravity.google/docs/cli/overview/) è una TUI interattiva
+con editing multi-file, cronologia, tool calling, sandbox e subagenti. La
+[guida d'installazione e autenticazione](https://antigravity.google/docs/cli/install/) conferma:
+
+- esecuzione nativa su Linux, macOS e Windows;
+- binario `agy` installato in `~/.local/bin` su Linux/macOS;
+- quando rileva SSH, stampa un URL da aprire sul Mac e richiede di incollare nel terminale il
+  codice ottenuto;
+- nessuna porta in ascolto e nessun port forwarding sono necessari per questo login.
+
+Questo risolve meglio di ZCode il vincolo CyberArk, purché il server possa effettuare connessioni
+HTTPS in uscita e sia consentita l'installazione del binario.
+
+Per consumare la quota della registrazione Antigravity bisogna usare il client ufficiale. I
+[termini Antigravity](https://antigravity.google/terms) vietano di riutilizzare il login/OAuth con
+Pi, OMP, Claude Code, OpenCode o altri client. Con questi harness si può invece usare una normale
+chiave Gemini API, pagando o consumando la quota API separata.
+
+## Privacy e codice aziendale
+
+Con un account personale Google registra le interazioni e può usarle per valutare e migliorare
+prodotti e modelli; l'utente può disattivare l'uso dalle impostazioni. I termini Enterprise sono
+diversi e la documentazione dichiara che codice, prompt e trascrizioni delle organizzazioni non
+sono usati per addestrare i modelli Google. Fonti:
+[termini Antigravity](https://antigravity.google/terms) e
+[integrazioni Enterprise](https://antigravity.google/docs/ide/extensions/).
+
+Su un server aziendale protetto da CyberArk userei quindi una registrazione personale solo dopo
+aver verificato la policy interna; in caso contrario sceglierei l'accesso Antigravity Enterprise
+tramite il progetto Google Cloud dell'organizzazione.
+
+## Raccomandazione finale
+
+1. Creare l'account gratuito e usare `agy` sul server per una settimana con task reali.
+2. Tenere disabilitato l'uso automatico dei crediti extra e osservare i due indicatori di quota.
+3. Passare a Pro soltanto se il limite gratuito interferisce con il lavoro.
+4. Non acquistare Ultra finché Pro non viene saturato con regolarità.
+5. Usare Gemini 3.8 Flash come modello principale per esplorazione, implementazione e test; per le
+   decisioni più difficili, mantenere Codex/Sol/Opus o un altro modello forte come revisore.
+
+In breve: **sì, oggi Antigravity gratuito o Pro offre uno dei migliori rapporti costo/qualità per
+Gemini 3.8 Flash**, e nel caso specifico la CLI ufficiale senza tunnel aumenta ulteriormente il
+valore. Il limite commerciale da accettare è la quota non numerica e modificabile da Google.

docs/research/2026-09-07-deepseek-harness-terminal.md

@@ -0,0 +1,154 @@
+# DeepSeek Harness su un server raggiunto tramite CyberArk
+
+Data della verifica: 7 settembre 2026.
+
+## Risposta breve
+
+Sì. Il progetto che ha attirato molta attenzione è **DeepSeek Harness**, comando
+`dsh`, pubblicato da DeepSeek nel repository ufficiale
+[`deepseek-ai/deepseek-harness`](https://github.com/deepseek-ai/deepseek-harness).
+Può lavorare direttamente sul server senza SSH port forwarding usando il profilo
+ufficiale **headless**:
+
+```sh
+export DEEPSEEK_API_KEY='...'
+npx @deepseek-ai/dsh --profile headless \
+  "Esamina questo repository e correggi i test che falliscono"
+```
+
+Questo profilo esegue un incarico, stampa la risposta e termina. Non avvia GUI,
+browser o server HTTP e, soprattutto, **non apre alcuna porta**. Lo documentano sia
+il [README del profilo headless](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/bundle/headless/README.md)
+sia il [riferimento della CLI](https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/cli/reference/README.md).
+Pertanto il port forwarding non serve: basta la shell che CyberArk già consente e
+connettività HTTPS in uscita.
+
+La limitazione importante è che non si tratta, per ora, di un'interfaccia terminale
+interattiva come Pi, OMP, Claude Code o Codex: il profilo ufficiale headless accetta
+**un solo task per invocazione e non permette follow-up interattivi**.
+
+## Che cos'è, e cosa non è
+
+DeepSeek lo presenta come un harness open source in *developer preview*, basato su
+un'architettura in cui modelli, strumenti, skill, sessioni, sandbox, storage,
+subagenti e UI sono plugin componibili. La pagina ufficiale descrive inoltre
+modalità Standard, Code, Minimal e Creator e la registrazione append-only delle
+esecuzioni. Non è semplicemente il modello DeepSeek e non è uno dei numerosi wrapper
+creati dalla comunità. Fonti: [pagina ufficiale DeepSeek Harness](https://www.deepseek.com/harness/en/)
+e [README ufficiale](https://github.com/deepseek-ai/deepseek-harness#readme).
+
+L'identità del pacchetto è verificabile anche nel
+[`package.json` della CLI](https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/cli/package.json):
+il pacchetto pubblico è `@deepseek-ai/dsh` e installa l'eseguibile `dsh`.
+Il [record ufficiale del repository](https://api.github.com/repos/deepseek-ai/deepseek-harness)
+ne data la creazione al 13 agosto 2026; alla data di questa verifica la release
+più recente è la prerelease
+[`dsh-v0.1.3-alpha.2`](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.3-alpha.2),
+pubblicata il 7 settembre 2026. Questo conferma quanto il progetto sia giovane e
+rafforza l'avvertenza sulla stabilità delle interfacce.
+
+## Le tre modalità rilevanti nel tuo scenario
+
+| Modalità | Porta/tunnel | Interazione | Utilità con CyberArk |
+|---|---:|---|---|
+| `dsh --profile headless "task"` | Nessuna | One-shot, non interattiva | **Sì, è la soluzione semplice** |
+| `dsh web` | HTTP locale su `127.0.0.1:3080` | Web interattiva | No dal Mac senza forwarding, reverse proxy autorizzato o browser sul server |
+| `dsh --profile acp` | Nessuna porta; JSON-RPC su stdin/stdout | Persistente, pilotata da un client ACP | Possibile, ma l'integrazione attraverso CyberArk va provata |
+
+La Web UI ufficiale ascolta per default su `127.0.0.1:3080`; il README afferma
+esplicitamente che, durante un lancio SSH, il forwarding è responsabilità del client
+SSH o dell'editor. È quindi inadatta al vincolo descritto, a meno di cambiare
+l'architettura di accesso con l'approvazione dell'amministrazione
+([README ufficiale](https://github.com/deepseek-ai/deepseek-harness#run)).
+
+Il profilo ACP ufficiale è invece un server di automazione persistente su
+**JSON-RPC stdio**, senza UI. Un client ACP avvia `dsh --profile acp`, crea una
+sessione indicando una directory di lavoro assoluta e scambia richieste e risposte
+su standard input/output
+([README ACP ufficiale](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/bundle/acp-app/README.md)).
+
+Da ciò segue una possibilità tecnica: un client locale potrebbe usare come comando
+qualcosa di equivalente a `ssh <server> dsh --profile acp`, trasportando lo stdio
+senza alcun port forwarding. Questa è però un'**inferenza architetturale**, non una
+configurazione dichiarata compatibile con CyberArk da DeepSeek. Banner di login,
+MFA interattivo, testo aggiunto su stdout, divieto di `ssh host command`, timeout o
+riscrittura dei flussi da parte del proxy CyberArk possono corrompere JSON-RPC o
+impedire del tutto l'avvio. Se CyberArk offre soltanto una console web/interattiva,
+ACP non collega automaticamente Zed sul Mac al processo remoto.
+
+## Requisiti di rete e di sistema
+
+- Il repository richiede Node.js `^22.19.0` oppure `>=24.0.0`, come specificato
+  nel [`package.json` ufficiale](https://github.com/deepseek-ai/deepseek-harness/blob/master/package.json).
+- Il primo `npx` deve poter scaricare `@deepseek-ai/dsh` dal registry npm. In un
+  ambiente bloccato occorre un mirror aziendale o un'installazione preventiva
+  autorizzata.
+- Per usare il provider predefinito occorrono `DEEPSEEK_API_KEY` e traffico HTTPS
+  in uscita verso `https://api.deepseek.com`. `DEEPSEEK_BASE_URL` può sostituire
+  l'endpoint, per esempio con un proxy OpenAI-compatible
+  ([adapter DeepSeek ufficiale](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/llm/llm-deepseek/README.md)).
+- Se la rete aziendale impone un proxy HTTP, il riferimento della CLI indica
+  `NODE_USE_ENV_PROXY=1` affinché una versione Node compatibile rispetti
+  `HTTP_PROXY` e `HTTPS_PROXY`
+  ([riferimento della CLI, sezione Source execution](https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/cli/reference/README.md#source-execution)).
+- Le operazioni richieste dall'agente possono necessitare altri host in uscita
+  (`git`, registry dei pacchetti, documentazione). Non sono necessari per il
+  trasporto DSH in sé, ma possono esserlo per il task affidato.
+
+In altre parole, serve **HTTPS outbound**, non una connessione in ingresso verso il
+server e non un tunnel dal Mac.
+
+## Limiti pratici specifici di CyberArk
+
+1. **Accesso alla shell:** se CyberArk consente di aprire una normale sessione shell
+   e di eseguire Node, `headless` funziona concettualmente come qualunque altro
+   comando. Se applica allowlist ai binari, servirà l'autorizzazione per `node`,
+   `npx`/`dsh` e per gli strumenti che l'agente vuole eseguire.
+2. **Egress:** firewall e proxy devono consentire almeno l'endpoint del modello;
+   CyberArk non sostituisce questa autorizzazione di rete.
+3. **Durata della sessione:** un timeout o la chiusura della sessione privilegiata
+   può terminare il task. `headless` non lascia un demone dietro di sé, ma incarichi
+   lunghi vanno confrontati con i limiti della sessione CyberArk.
+4. **Credenziali e registrazione:** evitare di digitare o stampare la chiave API in
+   una sessione registrata. Conviene usare il meccanismo aziendale approvato per
+   iniettare il secret e verificare cosa CyberArk registra.
+5. **Approvals:** l'headless ufficiale non ha un interlocutore umano integrato. Le
+   richieste di escalation senza un *answerer* vengono negate in modo fail-closed;
+   le normali scritture consentite nella workspace restano possibili
+   ([contratto delle approvazioni](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/interaction/user-approval/README.md)).
+6. **Sicurezza:** DeepSeek dichiara il progetto non sottoposto a security audit e
+   non pronto per produzione. Può eseguire codice generato dal modello e accedere
+   a file, processi, rete e credenziali disponibili al processo. Il progetto stesso
+   raccomanda privilegi minimi e un ambiente dedicato o usa-e-getta
+   ([Safety notice ufficiale](https://github.com/deepseek-ai/deepseek-harness/blob/master/SAFETY.md)).
+
+Un dettaglio importante in un server aziendale: la sandbox corrente descritta da
+DeepSeek governa gli effetti sul filesystem, mentre rete e visibilità dei processi
+sono fuori dal suo vocabolario di enforcement. Non considerarla quindi un sostituto
+di firewall, container, account dedicato e policy CyberArk
+([documentazione sandbox ufficiale](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/sandbox.md)).
+
+## TUI interattiva: stato reale
+
+Il prodotto ufficiale offre oggi Web UI, headless one-shot e interfacce di
+automazione SDK/ACP. Una TUI a schermo intero chiamata `dsh-tui` è stata presentata
+nell'area community del repository, ma il pacchetto e il repository appartengono a
+terzi, non a DeepSeek
+([discussione nella community DSH](https://github.com/deepseek-ai/deepseek-harness/discussions/3715)).
+Non va confusa con la CLI ufficiale e, dato che DSH avverte di possibili cambiamenti
+incompatibili durante la developer preview, non la considererei la prima scelta su
+un server aziendale protetto.
+
+## Giudizio
+
+Per il tuo vincolo concreto la risposta è **sì, ma in modalità one-shot**:
+`dsh --profile headless` è utilizzabile dalla normale shell CyberArk, non apre porte
+e non richiede tunnel. È una soluzione tecnicamente più adatta della Web UI, ma
+meno comoda di Pi/OMP o Codex CLI per un dialogo iterativo.
+
+La proverei inizialmente su una copia non sensibile del repository, con
+`workspace-write`, egress ristretto e secret iniettato secondo le regole aziendali.
+Se vuoi un'esperienza persistente dal Mac, ACP su stdio merita un piccolo test di
+compatibilità con il gateway CyberArk; non lo darei per funzionante finché non si
+verifica che il gateway permetta un comando remoto non interattivo e mantenga
+stdin/stdout completamente puliti.

docs/research/2026-09-07-omp-codex-zcode.md

@@ -0,0 +1,127 @@
+# OMP con GPT-5.6 Sol, Codex ufficiale e ZCode CLI
+
+_Verifica effettuata il 7 settembre 2026 su documentazione e codice/fonti primarie correnti._
+
+## Risposta breve
+
+Se l'obiettivo è usare **GPT-5.6 Sol attraverso la quota inclusa nel piano ChatGPT/Codex**, la
+scelta consigliata è **Codex ufficiale**: CLI per il lavoro da terminale, app desktop per più task,
+worktree e revisione visuale. OMP è un harness molto capace e può essere preferibile per ACP/Zed,
+multi-provider, LSP/DAP e orchestrazione dei subagenti, ma il suo accesso “OpenAI Codex OAuth” non
+è una superficie che OpenAI documenta ufficialmente come client supportato.
+
+Se invece OMP usa una **chiave API OpenAI**, l'integrazione è tecnicamente normale e GPT-5.6 Sol è
+disponibile tramite Responses API con function calling, structured outputs e diversi tool. In quel
+caso, però, il consumo è fatturato come API e non attinge alla quota inclusa nel piano ChatGPT.
+
+Per **ZCode di Z.ai**, la documentazione ufficiale corrente presenta un'app desktop/ADE, non una
+CLI pubblica autonoma. Esiste `zcode-app-cli`, ma è un progetto comunitario che si dichiara non
+ufficiale ed estrae il runtime distribuito con l'app. Non esiste una garanzia ufficiale che riceva
+un presunto bonus di quota del 50%; la documentazione corrente non promette neppure un diritto
+fisso “150%” per tutti gli utenti ZCode.
+
+## 1. OMP + GPT-5.6 Sol oppure Codex?
+
+### Il modello è solo una parte del risultato
+
+Usare lo stesso modello non rende equivalenti due agenti. L'harness decide prompt di sistema,
+selezione e schema dei tool, raccolta del contesto, compaction, gestione degli errori, permessi,
+parallelismo e verifica. Non risultano benchmark first-party che confrontino direttamente
+GPT-5.6 Sol dentro OMP contro lo stesso modello dentro Codex: un vincitore assoluto non è quindi
+dimostrabile.
+
+GPT-5.6 Sol è il modello flagship general-purpose della famiglia 5.6 e supporta Responses API,
+function calling, structured outputs, hosted shell, apply patch, skills, MCP e tool search.
+[Scheda ufficiale GPT-5.6 Sol](https://developers.openai.com/api/docs/models/gpt-5.6-sol).
+
+### Accesso tramite abbonamento
+
+OMP dichiara un provider **OpenAI Codex OAuth** e consente il login dal proprio harness.
+[README OMP](https://github.com/can1357/oh-my-pi/blob/daf07999c2fee9b22edc7bf8fea1fb6272e0df5e/README.md).
+
+La documentazione OpenAI, però, indica il login ChatGPT per l'accesso in abbonamento soltanto per
+l'app desktop ChatGPT/Codex, Codex CLI e l'estensione IDE. Non include OMP tra i client supportati.
+Questo non prova che OMP non funzioni, ma significa che compatibilità, continuità dell'accesso e
+interpretazione della quota non sono garantite da OpenAI per quel percorso.
+[Autenticazione ufficiale Codex](https://learn.chatgpt.com/docs/auth).
+
+Con una chiave API la situazione è diversa: l'accesso al modello è ufficiale, ma è fatturato ai
+prezzi API. OpenAI specifica inoltre che l'autenticazione API usa il pricing API invece dei crediti
+inclusi nel piano ChatGPT.
+[Pricing Codex](https://learn.chatgpt.com/docs/pricing),
+[pricing del modello](https://developers.openai.com/api/docs/models/gpt-5.6-sol).
+
+### Confronto operativo
+
+| Priorità | Scelta migliore | Motivo |
+|---|---|---|
+| GPT-5.6 Sol con quota ChatGPT e supporto prevedibile | Codex ufficiale | Login, quota e aggiornamenti sono first-party |
+| Esperienza terminale, scripting e CI | Codex CLI | Loop locale, `codex exec`, review e handoff cloud |
+| Task paralleli, worktree e review visuale | App desktop Codex | Gestione visuale dei task e isolamento mediante Git worktree |
+| ACP/Zed, molti provider, LSP/DAP e Agent Hub | OMP | Harness più estensibile e ricco di strumenti |
+| OMP con stabilità contrattuale dell'accesso | OMP + API key | API ufficiale, ma costo separato dal piano ChatGPT |
+
+La CLI ufficiale è consigliata per terminale, automazione e CI.
+[Codex CLI](https://learn.chatgpt.com/docs/codex/cli). L'app desktop è più comoda per task
+concorrenti isolati, diff visuali e passaggio fra checkout locale e worktree.
+[Worktree Codex](https://learn.chatgpt.com/docs/environments/git-worktrees).
+
+CLI e app non danno due quote separate: quando si accede con ChatGPT, fanno parte dello stesso
+ecosistema Codex/ChatGPT e consumano la stessa quota del piano. Il consumo concreto dipende da
+modello, lunghezza del contesto e complessità del task.
+[Pricing e limiti](https://learn.chatgpt.com/docs/pricing).
+
+### Giudizio
+
+Per un flusso principale basato su GPT-5.6 Sol sceglierei **Codex CLI**; affiancherei l'app quando
+servono task paralleli, worktree e review visuale. Sceglierei OMP come harness principale soltanto
+se le sue capacità specifiche — soprattutto Zed/ACP, routing multi-provider o Agent Hub — valgono
+più del supporto first-party. Se OMP deve essere affidabile nel tempo, userei una API key anziché
+fondare il workflow sul login OAuth non documentato da OpenAI per client terzi.
+
+## 2. Il “150%” di Codex non è quota aggiuntiva
+
+Nella documentazione OpenAI, **1,5× indica la velocità del Fast mode**, non un aumento della quota.
+Con GPT-5.6, Fast mode consuma crediti a **2,5×** il tasso Standard. È disponibile nei client
+Codex ufficiali quando si accede con ChatGPT.
+[Fast mode](https://learn.chatgpt.com/docs/agent-configuration/speed).
+
+## 3. Esiste una CLI ufficiale ZCode?
+
+La guida ufficiale ZCode offre download desktop per macOS, Windows e Linux e descrive ZCode come
+ADE con terminale integrato. Non documenta un comando autonomo ufficiale equivalente a `codex`.
+La presenza di directory chiamate `~/.zcode/cli/` riguarda il runtime/config interno e non equivale
+alla pubblicazione di una CLI supportata.
+[Installazione ZCode](https://zcode.z.ai/en/docs/install),
+[FAQ ufficiale](https://zcode.z.ai/en/docs/qa).
+
+Esiste il progetto comunitario
+[`zcode-app-cli`](https://github.com/kingsword09/zcode-cli), installabile con npm. Il progetto si
+definisce esplicitamente non affiliato né approvato da Z.ai e dichiara di estrarre il runtime
+dall'app desktop. Va quindi considerato non ufficiale e soggetto a possibili rotture e problemi di
+compatibilità o licenza.
+
+### Ha il 150% della quota?
+
+Non c'è una conferma ufficiale corrente. Le pagine ZCode attuali descrivono quote Coding Plan su
+finestre di cinque ore e settimanali, quota MCP mensile, crediti e reset card promozionali/dinamiche;
+non dichiarano un moltiplicatore fisso 150% applicabile alla CLI.
+[Statistiche e quota ZCode](https://zcode.z.ai/en/docs/usage-stats),
+[connessione al Coding Plan](https://zcode.z.ai/en/docs/configuration).
+
+Alcuni benefici sono esplicitamente legati all'app e al login ZCode: per esempio le reset card
+richiedono di essere connessi a ZCode, mentre gli idle-time task gratuiti sono una funzione
+dell'app in rollout. Questo non autorizza a concludere che un client comunitario riceva gli stessi
+benefici.
+[ZCode Usage Stats](https://zcode.z.ai/en/docs/usage-stats),
+[ZCode overview](https://zcode.z.ai/en/docs/welcome).
+
+Inoltre, i termini del GLM Coding Plan avvertono che l'uso tramite strumenti non autorizzati o non
+supportati può comportare restrizioni di alcuni benefici. Di conseguenza non userei una CLI
+comunitaria con l'obiettivo specifico di ottenere quota extra.
+[Termini del GLM Coding Plan](https://docs.z.ai/legal-agreement/subscription-terms).
+
+La scelta prudente è usare l'app ZCode ufficiale — incluso il suo terminale integrato o Remote
+Development — e considerare valido soltanto il saldo mostrato in tempo reale nell'app. Se Z.ai
+pubblicherà una CLI ufficiale o una regola “+50%”, servirà una dichiarazione esplicita applicabile
+alla versione e al piano usati.

docs/research/2026-09-07-pi-config-vs-oh-my-pi.md

@@ -0,0 +1,148 @@
+# Pi + `pi-config` di Amos vs Oh My Pi
+
+_Ricerca aggiornata al 7 settembre 2026. Fonti: esclusivamente repository, documentazione, sorgenti, issue tracker e release ufficiali dei progetti._
+
+## Risposta breve
+
+**Per la maggior parte degli sviluppatori che vuole un agente completo e pronto all'uso, sceglierei Oh My Pi (OMP), ma non con le impostazioni di sicurezza predefinite.** OMP integra provider, routing per ruolo, LSP/DAP, subagent, web, browser, sessioni, memoria, marketplace e una UX terminale molto più ampia. È un prodotto coerente, installabile e aggiornabile come tale.
+
+**Sceglierei invece Pi con pezzi selezionati di `pi-config` se volessi un nucleo piccolo, leggibile e fortemente personalizzabile**, accettando di assemblare, verificare e mantenere personalmente ogni componente. Il vantaggio non è avere più funzioni: è sapere con precisione quali funzioni si stanno aggiungendo.
+
+La prima distinzione è fondamentale:
+
+- [`amosblomqvist/pi-config`](https://github.com/amosblomqvist/pi-config) **non è una distribuzione alternativa di Pi**. È la configurazione personale di Amos Blomqvist: una raccolta di estensioni e skill da copiare selettivamente sopra il [Pi ufficiale](https://github.com/earendil-works/pi). Il README invita esplicitamente a non installarla come un unico pacchetto e a non clonarla sopra la propria configurazione.
+- Per “Oh My Pi” qui si intende [`can1357/oh-my-pi`](https://github.com/can1357/oh-my-pi), il fork integrato di Pi che si presenta come agente “batteries included”. Non è un semplice tema o dotfile pack.
+
+Di conseguenza il confronto corretto è **Pi ufficiale + componenti scelti da `pi-config` e dai repository companion** contro **OMP come fork/prodotto integrato**.
+
+## Confronto spalla a spalla
+
+| Area | Pi + `pi-config` | Oh My Pi | Valutazione |
+|---|---|---|---|
+| Installazione | Prima si installa [Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/README.md), poi si copiano singole estensioni/skill in `~/.pi/agent/`; alcuni componenti richiedono `npm install`, Chromium, Python o tool di sistema. Il [README di `pi-config`](https://github.com/amosblomqvist/pi-config#installation) raccomanda la selezione manuale. | Installer shell/PowerShell, Homebrew, Bun, Nix e `mise`, più binari multipiattaforma nelle [release](https://github.com/can1357/oh-my-pi/releases). | **OMP**: onboarding e aggiornamento più coerenti. |
+| Filosofia | Pi è un harness terminale minimale, esteso tramite TypeScript, skill, prompt template, temi e pacchetti; evita intenzionalmente alcune funzionalità integrate, inclusi subagent e plan mode, per lasciarle alle estensioni ([README Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/README.md)). `pi-config` porta questa filosofia all'estremo: si prendono solo i pezzi voluti. | Fork “batteries included”: molte capacità sono native o integrate e configurabili da una superficie comune ([README OMP](https://github.com/can1357/oh-my-pi)). | **Dipende**: controllo e semplicità a Pi; completezza a OMP. |
+| Provider e modelli | `pi-config` non aggiunge provider. Eredita da Pi login per Anthropic/OpenAI/Copilot, numerosi provider API, servizi cloud, OpenRouter e modelli locali/custom ([provider Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/README.md#providers-and-models)). | Dichiara oltre 60 provider e modelli locali/remoti; assegna modelli distinti ai ruoli `default`, `smol`, `slow`, `plan`, `commit`, `vision`, `task`, `advisor` e `tiny`, con fallback e credenziali multiple ([model routing OMP](https://github.com/can1357/oh-my-pi#sixty-plus-providers-a-thousand-models-one-model-away)). | **OMP** per ampiezza e routing; Pi resta già provider-agnostic. |
+| Prompt e istruzioni | Pi supporta `AGENTS.md`, `SYSTEM.md`, `APPEND_SYSTEM.md` e prompt template. `prompt-snippets` aggiunge piccoli frammenti attivabili per singolo messaggio, poi azzerati ([sorgente/README](https://github.com/amosblomqvist/pi-config/tree/main/extensions/prompt-snippets)). | Stessi concetti di personalizzazione del prompt, con override globali/progetto/modello ([documentazione](https://github.com/can1357/oh-my-pi/blob/main/docs/system-prompt-customization.md)); aggiunge ruoli modello, advisor e agent personalizzati. | **OMP** per orchestrazione; **pi-config** ha la migliore micro-UX per regole effimere per messaggio. |
+| Subagent | Non nativi nel core. Il companion [`pi-interactive-subagents`](https://github.com/amosblomqvist/pi-interactive-subagents) avvia agent asincroni in pannelli tmux, persistenti e pilotabili; include `scout`, `researcher` e `worker`, loadout a allowlist e nesting esplicito. | Subagent di prima classe con batch, modalità sincrona/asincrona, output strutturato, Agent Hub, steering/revive/kill e ricorsione controllata. L'isolamento del workspace esiste, ma è **opt-in**, non una proprietà automatica di ogni spawn ([task](https://github.com/can1357/oh-my-pi/blob/main/docs/tools/task.md)). | **OMP** per orchestrazione complessiva; **Amos** per pannelli tmux e minimo privilegio più semplice da verificare. |
+| Tool di coding | Il core Pi espone un set volutamente piccolo; `pi-config` aggiunge soprattutto browser, fetch/search, guard e UI di domande. | Lettura/scrittura/editing e AST, grep/glob, shell ed evaluator persistenti, LSP, DAP, code review, security scan, checkpoint/rewind e altri tool elencati nel [README](https://github.com/can1357/oh-my-pi#thirty-one-first-class-tools). Alcuni sono disattivati inizialmente. | **OMP**, nettamente, per intelligence sul codice e debug. |
+| Web e browser | [`browser`](https://github.com/amosblomqvist/pi-config/tree/main/extensions/browser) usa Playwright/Chromium headless ed è spento di default; è una singola pagina senza download/upload. `web-search` usa Google Custom Search e richiede API key/CSE ([sorgente](https://github.com/amosblomqvist/pi-config/blob/main/extensions/web-search/index.ts)); c'è anche `web-fetch`. | Browser/computer integrati e ricerca con numerosi backend, inclusi servizi a pagamento, locali/pubblici e motori specializzati ([README](https://github.com/can1357/oh-my-pi#web-search)). | **OMP** per copertura; `pi-config` è più piccolo e comprensibile. |
+| Skill e plugin | Skill file-based native di Pi più quattro skill incluse: analisi sessioni, PDF, web debug e trascrizione YouTube ([inventario](https://github.com/amosblomqvist/pi-config#skills)). `learn`, dictation, memoria e subagent sono repository separati. | Skill caricate progressivamente tramite metadata e URI `skill://` ([skill docs](https://github.com/can1357/oh-my-pi/blob/main/docs/skills.md)); marketplace per plugin Git/local/catalogo, con skill, comandi, agent, hook, tool, MCP e LSP ([marketplace](https://github.com/can1357/oh-my-pi/blob/main/docs/marketplace.md)). | **OMP** per distribuzione e composizione. |
+| MCP e interoperabilità | Dipende dalle capacità/estensioni del Pi base; `pi-config` non offre un livello MCP proprio. | Configurazione MCP utente/progetto e discovery di configurazioni provenienti anche da altri editor/agenti ([MCP docs](https://github.com/can1357/oh-my-pi/blob/main/docs/mcp-config.md)). | **OMP**. |
+| UX/TUI | TUI Pi pulita con editor, fuzzy file search, immagini, shell, steering/follow-up e alberi di sessione. `ask-user-question` aggiunge un dialogo strutturato; snippets e pannelli tmux sono distintivi. [`pi-dictate`](https://github.com/amosblomqvist/pi-dictate) aggiunge dettatura Deepgram. | TUI più ricca con card dei tool, preview/accettazione edit, picker, Agent Hub e time-travel; include sia sintesi vocale sia STT tramite scorciatoia `Alt+H` ([README OMP](https://github.com/can1357/oh-my-pi)). | **OMP** in generale; la semplicità di Pi può essere un pregio. La voce non è esclusiva della configurazione Amos. |
+| Sessioni | Pi salva JSONL ad albero, consente resume/fork/clone/tree e compaction conservando lo storico ([sessioni Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/README.md#sessions)). | JSONL append-only, struttura ad albero, blob esterni e ricostruzione versionata ([formato](https://github.com/can1357/oh-my-pi/blob/main/docs/session.md)); dump/export/share/fork/resume sono documentati come operazioni native ([operazioni](https://github.com/can1357/oh-my-pi/blob/main/docs/session-operations-export-share-fork-resume.md)). | **OMP**, di poco, per operazioni integrate; i due condividono una base concettuale simile. |
+| Memoria | [`pi-observational-memory`](https://github.com/amosblomqvist/pi-observational-memory) è opzionale e spento di default: observer LLM paralleli distillano i turni, una compaction deterministica crea un ledger e un consolidatore produce file Markdown per sessione. È auditabile, ma aggiunge costo e complessità. | Memoria spenta di default con backend `local`, Hindsight, Mnemopi e Sharpshooter; sommari/lezioni possono attraversare sessioni e alimentare skill, con esplicita avvertenza che la memoria può essere obsoleta ([memory docs](https://github.com/can1357/oh-my-pi/blob/main/docs/memory.md)). | **OMP** per scelta e integrazione; **Amos** per un modello per-sessione semplice da ispezionare. |
+| Sicurezza applicativa | Pi dichiara di non avere un permission system integrato per filesystem, processi, rete o credenziali e consiglia container/microVM ([security Pi](https://github.com/earendil-works/pi#permissions--containerization)). [`bash-guard`](https://github.com/amosblomqvist/pi-config/tree/main/extensions/bash-guard) intercetta euristicamente solo chiamate al tool `bash`: non protegge `write`, `edit` né i comandi `!`. | Ha policy per tool e tre approval mode, ma il default è **`yolo`**; in tale modalità gli override di comandi bash critici non forzano il prompt. Anche quando si approva un comando non c'è contenimento di filesystem, rete o subprocessi ([approval docs](https://github.com/can1357/oh-my-pi/blob/main/docs/approval-mode.md)). L'offuscamento dei segreti esiste ma è spento di default ([secrets docs](https://github.com/can1357/oh-my-pi/blob/main/docs/secrets.md)). | **Nessun vincitore sicuro di default**. OMP offre controlli migliori, ma sceglie un default molto permissivo. |
+| Isolamento | Nessun sandbox OS o worktree per-agent documentato; l'allowlist del loadout limita i tool, non il filesystem raggiungibile dai tool concessi. | Gli spawn normali condividono la `cwd` del parent. Workspace separato e merge patch/branch richiedono `task.isolation.enabled` **e** `isolated: true` sul task; l'opzione non è disponibile in plan mode ([task](https://github.com/can1357/oh-my-pi/blob/main/docs/tools/task.md#inputs)). Neppure questo è un sandbox OS. | **OMP** per isolamento anti-collisione opt-in; **parità negativa** come confine di sicurezza. |
+| Portabilità | I componenti sono piccoli file TypeScript/Markdown copiabili, quindi il lock-in concettuale è basso. Però molte estensioni Amos importano ancora il vecchio scope `@mariozechner/*`; il Pi attuale usa `@earendil-works/*`. L'[advisory ufficiale](https://github.com/earendil-works/pi/security/advisories/GHSA-r95r-rj6r-c39x) depreca il vecchio pacchetto, quindi oggi serve una verifica/possibile migrazione degli import. | Binari e setup multipiattaforma; importa varie convenzioni esterne. Tuttavia si è allontanato dal Pi upstream: scope `@oh-my-pi`, runtime/test Bun, moduli nativi, auth e API proprie sono differenze dichiarate nella [guida di porting](https://github.com/can1357/oh-my-pi/blob/main/docs/porting-from-pi-mono.md). | **Pi + selezione manuale** per lock-in ridotto; **OMP** per portabilità operativa immediata. |
+| Migrazione delle estensioni | È l'ambiente nativo della raccolta Amos, salvo la transizione di package scope appena citata. | Non tratta `.pi/extensions` come root nativa. Può leggere dichiarazioni `pi.extensions` nei manifest, ma il caricamento e le API non rendono la migrazione automaticamente compatibile ([extension loading](https://github.com/can1357/oh-my-pi/blob/main/docs/extension-loading.md)). | **Non è drop-in in nessuna direzione**; verificare ogni estensione. |
+| Aggiornamenti e manutenzione | `pi-config` è un piccolo snapshot personale, senza release versionate; il [registro commit](https://github.com/amosblomqvist/pi-config/commits/main/) mostra pochissimi cambiamenti e l'integrazione è responsabilità dell'utente. I companion hanno cicli propri. | Distribuzione versionata con release frequenti e asset per piattaforma; al 7 settembre 2026 la release più recente è [`v18.1.13`](https://github.com/can1357/oh-my-pi/releases/tag/v18.1.13). | **OMP** per manutenzione di prodotto; le release molto rapide aumentano anche il rischio di churn. |
+| Maturità pratica | Il Pi sottostante è un progetto attivo e maturo, ma `pi-config` non è testato o pubblicato come distribuzione unitaria. L'autore di `pi-dictate`, per esempio, lo presenta esplicitamente come tool personale mantenuto per il proprio uso ([README](https://github.com/amosblomqvist/pi-dictate)). | Repository ampio, migliaia di commit e cadenza di release elevata ([storia](https://github.com/can1357/oh-my-pi/commits/main/), [release](https://github.com/can1357/oh-my-pi/releases)). Più integrazione e utenti implicano più validazione reale, ma anche superficie di bug e regressioni maggiore. | **OMP** come prodotto; nessuna garanzia che “più grande” significhi “più stabile”. |
+
+## Approfondimento: gestione dei subagenti
+
+**Sì: OMP ha una gestione dei subagenti paragonabile e, come orchestratore automatico, più completa.** La proposta Amos non è però semplicemente inferiore: privilegia un diverso modello operativo, nel quale ogni agente vive in un vero pannello tmux che l'utente può osservare e usare direttamente, con un loadout strettamente autorizzato.
+
+| Capacità | Pi + Amos `pi-interactive-subagents` | Oh My Pi |
+|---|---|---|
+| Esecuzione e fan-out | Sempre asincrono e non bloccante; più chiamate partono in parallelo e notificano il parent indipendentemente ([README, “How it works”](https://github.com/amosblomqvist/pi-interactive-subagents/blob/c3e8b53c0754ae5ccc19fdab5a7481ec039bc2f7/README.md#how-it-works)). Non è documentato un limite di concorrenza configurabile. | `task.batch` è attivo di default e accetta `tasks[]`; con `async.enabled=true` gli agenti sono job in background, altrimenti il parent attende. Un semaforo `task.maxConcurrency` limita sia sync sia async ([task: input, modi e limiti](https://github.com/can1357/oh-my-pi/blob/4c6feacddb6ff26e5219df7283bc371ad7e1de55/docs/tools/task.md#modes--variants)). |
+| Messaggi fra agenti | `subagent_message` corregge uno spawn in corsa al prossimo confine di turno o riapre quello concluso; `ask_question` permette al child di parcheggiarsi e interrogare il parent ([messaging](https://github.com/amosblomqvist/pi-interactive-subagents/blob/c3e8b53c0754ae5ccc19fdab5a7481ec039bc2f7/README.md#messaging)). | `hub send` consegna steering/follow-up, anche agli agenti parcheggiati, che vengono riattivati; la messaggistica peer è disponibile anche ai child ([task, “Notes”](https://github.com/can1357/oh-my-pi/blob/4c6feacddb6ff26e5219df7283bc371ad7e1de55/docs/tools/task.md#notes)). Limite documentato: lo steering è testo libero, non uno stato condiviso strutturato di goal/todo. |
+| Supervisione e intervento umano | Widget con stati `starting/active/waiting/stalled/running`, tool corrente e completamenti espandibili; il pannello tmux è la sessione reale, quindi l'utente può entrarvi e scrivere direttamente ([status widget](https://github.com/amosblomqvist/pi-interactive-subagents/blob/c3e8b53c0754ae5ccc19fdab5a7481ec039bc2f7/README.md#status-widget--configuration)). | `Alt+A` apre Agent Hub: roster/albero, attività, modello, costo/token, transcript live, steering, revive e kill; l'utente può mettere a fuoco la sessione del child e scrivergli ([Agent Hub](https://github.com/can1357/oh-my-pi/blob/4c6feacddb6ff26e5219df7283bc371ad7e1de55/docs/agent-hub.md)). **OMP non manca quindi della supervisione interattiva**; Amos la rende più concreta e terminal-native tramite pannelli separati. |
+| Resume e persistenza | Registro nome→sessione persistente attraverso i riavvii; il resume ripristina lo snapshot del loadout originale. Supporta sessioni `standalone`, `lineage-only` o `fork` con contesto del parent ([resume](https://github.com/amosblomqvist/pi-interactive-subagents/blob/c3e8b53c0754ae5ccc19fdab5a7481ec039bc2f7/README.md#messaging), [session mode](https://github.com/amosblomqvist/pi-interactive-subagents/blob/c3e8b53c0754ae5ccc19fdab5a7481ec039bc2f7/README.md#session-mode)). | Salva output e transcript (`agent://`, `history://`); agenti idle/parcheggiati sono riattivabili anche dopo il resume del parent ([Agent Hub, “Persisted agents”](https://github.com/can1357/oh-my-pi/blob/4c6feacddb6ff26e5219df7283bc371ad7e1de55/docs/agent-hub.md#persisted-agents-and-advisors)). Eccezione importante: un task eseguito in workspace isolato viene smontato dopo merge/cattura patch e **non è riattivabile** ([task flow](https://github.com/can1357/oh-my-pi/blob/4c6feacddb6ff26e5219df7283bc371ad7e1de55/docs/tools/task.md#flow)). |
+| Definizioni e routing modelli | File Markdown in `.pi/agents` o `~/.pi/agent/agents`, con modello, thinking, skill, tool, `cwd` e modalità sessione; il singolo spawn può sovrascrivere il modello. Include tre profili (`scout`, `researcher`, `worker`) ([custom agents](https://github.com/amosblomqvist/pi-interactive-subagents/blob/c3e8b53c0754ae5ccc19fdab5a7481ec039bc2f7/README.md#custom-agents)). | File Markdown `.omp/agents`, agent inclusi e provenienti da estensioni/plugin; routing con override per nome, lista fallback e alias `modelRoles`, più effort per task, prewalk e advisor opzionali ([agent definition](https://github.com/can1357/oh-my-pi/blob/4c6feacddb6ff26e5219df7283bc371ad7e1de55/docs/task-agent-discovery.md#agent-definition-shape), [routing](https://github.com/can1357/oh-my-pi/blob/4c6feacddb6ff26e5219df7283bc371ad7e1de55/docs/task-agent-discovery.md#model-and-structured-output-precedence)). |
+| Tool e sicurezza applicativa | Allowlist stretta: il child parte con `--no-extensions` e riceve soltanto i tool e le estensioni esplicitamente elencati; lo snapshot preserva il vincolo al resume ([tool access](https://github.com/amosblomqvist/pi-interactive-subagents/blob/c3e8b53c0754ae5ccc19fdab5a7481ec039bc2f7/README.md#tool-access-control)). È minimo privilegio applicativo, non sandbox OS. | Ogni definizione può limitare `tools` e `spawns`, e il limite di profondità rimuove `task`; però i child headless forzano `tools.approvalMode: yolo`, perché non hanno una UI locale per le conferme ([task flow](https://github.com/can1357/oh-my-pi/blob/4c6feacddb6ff26e5219df7283bc371ad7e1de55/docs/tools/task.md#flow)). Di conseguenza la qualità dell'allowlist/deny policy del parent è un confine essenziale. |
+| Agenti annidati | Solo se `subagent_agents` è presente; la lista autorizza nomi precisi a ogni livello e non esiste uno spawn senza profilo nominato ([tool access](https://github.com/amosblomqvist/pi-interactive-subagents/blob/c3e8b53c0754ae5ccc19fdab5a7481ec039bc2f7/README.md#tool-access-control)). Il parent attende anche i nipoti prima dell'auto-exit. | Supportati con policy `spawns` e limite `task.maxRecursionDepth` (default `2`); al limite il tool `task` viene rimosso ([recursion gating](https://github.com/can1357/oh-my-pi/blob/4c6feacddb6ff26e5219df7283bc371ad7e1de55/docs/task-agent-discovery.md#recursion-depth-gating)). Agent Hub conserva la gerarchia parent/child. |
+| Filesystem, worktree e conflitti | `cwd` può assegnare una directory diversa, ma il README non documenta workspace/worktree isolati né merge automatici ([role folders](https://github.com/amosblomqvist/pi-interactive-subagents/blob/c3e8b53c0754ae5ccc19fdab5a7481ec039bc2f7/README.md#role-folders)). **Inferenza:** più worker scriventi nella stessa checkout possono quindi collidere; separare le `cwd` resta responsabilità dell'orchestratore/utente. | Lo spawn ordinario usa la `cwd` del parent. L'isolamento è disponibile soltanto con configurazione globale attiva, `isolated: true`, repository Git e fuori dal plan mode; può applicare patch o cherry-pickare un branch ([task modes](https://github.com/can1357/oh-my-pi/blob/4c6feacddb6ff26e5219df7283bc371ad7e1de55/docs/tools/task.md#modes--variants)). Verifica l'applicabilità della patch; in caso di conflitto lascia l'artefatto per intervento manuale e preserva lo stash in branch mode ([gestione conflitti](https://github.com/can1357/oh-my-pi/blob/4c6feacddb6ff26e5219df7283bc371ad7e1de55/docs/tools/task.md#notes)). |
+| Output | Il risultato è l'ultimo messaggio assistant, inoltrato al parent; non è documentato un contratto JSON Schema né un merge di file ([auto-exit](https://github.com/amosblomqvist/pi-interactive-subagents/blob/c3e8b53c0754ae5ccc19fdab5a7481ec039bc2f7/README.md#auto-exit)). | `outputSchema` per item, modalità `permissive`/`strict`, risultato parsato e artefatti completi tramite `agent://`; il child deve concludere con `yield`, con fino a tre reminder ([task outputs](https://github.com/can1357/oh-my-pi/blob/4c6feacddb6ff26e5219df7283bc371ad7e1de55/docs/tools/task.md#outputs), [flow](https://github.com/can1357/oh-my-pi/blob/4c6feacddb6ff26e5219df7283bc371ad7e1de55/docs/tools/task.md#flow)). |
+| Portabilità e prerequisiti | Questa variante è esplicitamente **tmux-only** e richiede Pi + tmux ([requirements](https://github.com/amosblomqvist/pi-interactive-subagents/blob/c3e8b53c0754ae5ccc19fdab5a7481ec039bc2f7/README.md#requirements)); l'upstream HazAT supporta più multiplexer, ma non è il componente qui confrontato. | Il runtime OMP è multipiattaforma; l'isolamento seleziona backend diversi per Linux, macOS e Windows e ricade su copia ricorsiva quando necessario ([backend di isolamento](https://github.com/can1357/oh-my-pi/blob/4c6feacddb6ff26e5219df7283bc371ad7e1de55/docs/tools/task.md#side-effects)). |
+
+### Giudizio mirato
+
+**Per orchestrazione di subagenti sceglierei OMP**, perché combina fan-out controllato, sync/async, Agent Hub, messaggistica peer, output tipizzato, nesting con limiti e isolamento anti-collisione opzionale. Quindi la risposta alla domanda “ce l'ha anche OMP?” è **sì, e sul piano funzionale offre di più**.
+
+**Pi + Amos resta preferibile in due casi:** quando si vuole entrare fisicamente nei pannelli dei worker mentre lavorano, oppure quando si considera prioritaria una politica child “deny by default” molto leggibile. La sua gestione può essere ottimale per un power user tmux; non è però altrettanto completa come orchestratore automatico, soprattutto per output strutturato, concorrenza limitata e gestione/merge degli artefatti.
+
+Due caveat impediscono un verdetto semplicistico:
+
+1. in OMP “subagent isolato” non significa “ogni subagent”: senza entrambi i toggle necessari, gli agenti scriventi condividono la checkout;
+2. isolamento e continuità sono in tensione: il child OMP isolato evita collisioni, ma dopo il merge/cleanup non può essere riattivato; uno non isolato può invece essere parcheggiato e ripreso.
+
+## Cosa include davvero `pi-config`
+
+Nel repository principale ci sono:
+
+- `ask-user-question`: richiesta strutturata con popup TUI e serializzazione dell'interazione;
+- `bash-guard`: conferma/blocco euristico di comandi shell pericolosi;
+- `browser`: automazione Playwright su Chromium headless, disattivata inizialmente;
+- `custom-header`: header TUI personalizzato;
+- `prompt-snippets`: regole brevi attivabili sul singolo messaggio;
+- `web-fetch` e `web-search`;
+- skill per analisi sessioni, PDF, debug web e trascrizione YouTube.
+
+L'elenco e i prerequisiti sono nel [README ufficiale](https://github.com/amosblomqvist/pi-config). Le capacità più ambiziose sono in repository distinti:
+
+- [`pi-interactive-subagents`](https://github.com/amosblomqvist/pi-interactive-subagents), subagent interattivi in tmux;
+- [`pi-observational-memory`](https://github.com/amosblomqvist/pi-observational-memory), memoria osservazionale per sessione;
+- [`pi-dictate`](https://github.com/amosblomqvist/pi-dictate), STT con Deepgram;
+- [`learn`](https://github.com/amosblomqvist/learn), ambiente didattico con quiz, log e agent di ricerca/visualizzazione.
+
+Questi componenti **non formano automaticamente una singola installazione testata, aggiornata e versionata insieme**. Considerarli una “suite” è un'inferenza utile per il confronto, non una promessa del maintainer.
+
+## Dove OMP è realmente superiore
+
+1. **È coerente come prodotto.** Installazione, configurazione YAML, schema, tool, sessioni e aggiornamenti fanno parte dello stesso rilascio ([settings](https://github.com/can1357/oh-my-pi/blob/main/docs/settings.md)).
+2. **Il routing dei modelli è molto più sofisticato.** Non si sceglie soltanto un modello: si possono assegnare costi/capacità differenti a pianificazione, task, vision, commit, advisor e attività leggere.
+3. **L'intelligence sul codice è integrata.** LSP, DAP, editing AST, evaluator persistenti e review non richiedono di costruire un proprio stack di estensioni.
+4. **Subagent e memoria sono parti del sistema**, non componenti companion da sincronizzare a mano.
+5. **Ha più opzioni di interoperabilità**: MCP, marketplace e discovery di configurazioni da altri strumenti.
+
+Questa superiorità è soprattutto di **copertura e integrazione**, non una prova automatica di qualità superiore per ogni singola funzione. Le quantità dichiarate nel README di OMP sono affermazioni del progetto, non benchmark indipendenti.
+
+## Dove Pi + la configurazione Amos è migliore
+
+1. **È più facile capire il perimetro.** Ogni estensione è piccola, selezionabile e sostituibile. Si può usare `prompt-snippets` senza accettare browser, memoria o subagent.
+2. **Ha meno lock-in architetturale.** Le skill Markdown e molte estensioni TypeScript restano vicine all'ecosistema Pi, anche se oggi gli import verso il vecchio package scope richiedono attenzione.
+3. **Alcune idee sono più eleganti che “integrate”.** Gli snippet effimeri per messaggio, gli agent visibili nei pannelli tmux e la memoria in file Markdown per sessione sono facili da osservare e modificare.
+4. **Favorisce l'apprendimento del sistema.** È una buona base per chi vuole costruirsi il proprio harness anziché adottare una piattaforma già opinionata.
+
+Il prezzo è tempo operativo: installazione, dipendenze, compatibilità, aggiornamenti e test ricadono sull'utente.
+
+## Sicurezza: la conclusione scomoda
+
+**Né Pi + `pi-config` né OMP forniscono, da soli, un sandbox di sicurezza.**
+
+- In Pi, `bash-guard` è un buon guardrail UX, ma non vede tutte le scritture e non contiene il processo. Le estensioni Pi hanno accesso al sistema con i privilegi dell'utente; la documentazione raccomanda esplicitamente container o microVM ([Pi security](https://github.com/earendil-works/pi#permissions--containerization)).
+- In OMP esistono più policy, deny list e modalità di approvazione. Tuttavia `tools.approvalMode` parte da **`yolo`**, i safety override bash non diventano prompt in quella modalità, un comando approvato conserva accesso ambientale e le estensioni girano nello stesso processo ([approval mode](https://github.com/can1357/oh-my-pi/blob/main/docs/approval-mode.md), [extension loading](https://github.com/can1357/oh-my-pi/blob/main/docs/extension-loading.md)). Anche la protezione dei segreti è opt-in.
+
+Se scegliessi OMP imposterei subito almeno:
+
+1. `tools.approvalMode: always-ask` per un ambiente sensibile, oppure `write` come compromesso;
+2. deny/prompt espliciti per evaluator, browser/computer e tool non necessari;
+3. offuscamento segreti abilitato e configurato;
+4. esecuzione in container, VM o microVM quando repository, credenziali o rete sono sensibili.
+
+Con Pi farei la stessa cosa a livello OS e tratterei `bash-guard` come seconda cintura, non come sandbox.
+
+## Raccomandazione per profilo
+
+| Profilo | Scelta consigliata | Perché |
+|---|---|---|
+| Sviluppatore che vuole essere produttivo subito | **Oh My Pi** | Meno assemblaggio; LSP/DAP, modelli, agent e sessioni sono già integrati. |
+| Power user multi-model / molti provider | **Oh My Pi** | Routing per ruolo, fallback e credenziali multiple sono capacità native. |
+| Team che vuole una configurazione ripetibile | **Oh My Pi**, release fissata | Installer, Nix/mise, config e release versionate sono più riproducibili; fissare la versione riduce il churn. |
+| Hacker di Pi che vuole costruire il proprio ambiente | **Pi + componenti `pi-config`** | Superficie ridotta, sorgenti leggibili, composizione libera. |
+| Utente che vuole solo snippet, guard o browser | **Pi + singole estensioni** | Non serve adottare un fork molto più grande per tre capacità. |
+| Chi apprezza subagent visibili e interattivi in tmux | **Pi + `pi-interactive-subagents`** | È una scelta UX specifica e ben distinta dall'Agent Hub. |
+| Ambiente ad alta sicurezza | **Nessuno dei due senza isolamento OS** | I controlli applicativi non sostituiscono container/microVM; OMP va inoltre tolto da `yolo`. |
+| Runtime Pi già integrato via RPC, come ThothII | **Restare su Pi salvo progetto di migrazione dedicato** | OMP offre RPC/ACP, ma package scope, caricamento estensioni, eventi e semantiche del fork richiedono test contrattuali: non è una sostituzione drop-in. |
+
+### Nota specifica per ThothII
+
+Per usare un agente nel terminale del repository, OMP può essere valutato senza cambiare l'architettura. **Sostituire invece il processo Pi che ThothII avvia in modalità RPC è un'altra decisione.** ThothII dipende dal contratto degli eventi RPC, dall'estensione gate, dal resume e dal comportamento di sessione. La [guida di porting di OMP](https://github.com/can1357/oh-my-pi/blob/main/docs/porting-from-pi-mono.md) e la sua [documentazione di caricamento estensioni](https://github.com/can1357/oh-my-pi/blob/main/docs/extension-loading.md) mostrano divergenze sufficienti da richiedere almeno una suite di compatibilità end-to-end prima di considerarlo un sostituto.
+
+## Verdetto
+
+**Il migliore in assoluto, per me, è Oh My Pi — con una release fissata e una configurazione iniziale più restrittiva del default.** Vince quasi tutte le categorie funzionali e riduce drasticamente il lavoro di integrazione.
+
+Non lo sceglierei però “alla cieca”: `yolo` come default è un caveat serio, la superficie enorme rende probabile qualche regressione e il fork crea più dipendenza dalle proprie API. Per una workstation con codice e credenziali reali lo metterei dietro approvazioni esplicite e isolamento OS.
+
+**Pi + `pi-config` è la scelta migliore quando l'obiettivo è un ambiente personale minimale e intenzionale**, non quando si cerca il maggior numero di funzioni. Installerei solo i componenti necessari, controllerei gli import dopo la migrazione da `@mariozechner/*` a `@earendil-works/*` e aggiungerei test prima di usarli in un flusso critico.

docs/research/2026-09-07-zai-coding-plan-cli-quota.md

@@ -0,0 +1,44 @@
+# Z.ai Coding Plan: bonus di quota e client CLI
+
+Verifica effettuata il **7 settembre 2026**, esclusivamente su fonti ufficiali Z.ai/ZCode.
+
+## Risposta breve
+
+**No: Z.ai non documenta un bonus permanente del 150% (+50%) per un altro harness CLI.** La sola pagina ufficiale che usa oggi l'espressione “150% quota boost” è quella di **AutoClaw**: lo presenta come vantaggio a tempo limitato per piani Individual e Team, ma non precisa se significhi quota finale al 150% o incremento del 150%. AutoClaw è inoltre descritto come applicazione desktop per macOS e Windows, non come CLI da installare su un server. ([AutoClaw](https://autoclaw.z.ai/))
+
+C'è però una promozione temporanea più interessante e formulata senza ambiguità: dal **3 al 20 settembre 2026**, ogni giorno fra le **23:00 e le 09:00 UTC+8**, GLM-5.3-Flash consuma zero quota in ZCode, mentre negli **altri agenti ufficialmente supportati la quota disponibile è raddoppiata**. In Italia, nel periodo della campagna, la finestra corrisponde alle **17:00–03:00 CEST**. La promozione vale per tutti i piani a pagamento e soltanto per GLM-5.3-Flash; GLM-5.3 continua a consumare la quota normale. ([GLM-5.3-Flash Usage Campaign](https://docs.z.ai/devpack/notice/event-glm-5.3-flash))
+
+## Quali alternative CLI sono ufficialmente ammesse
+
+La pagina corrente dei tool supportati nomina espressamente questi client utilizzabili da terminale:
+
+| Harness | CLI/server | Stato nella documentazione Z.ai | Quota |
+|---|---:|---|---|
+| **Pi** | Sì | Esplicitamente incluso fra i Coding Agent Tool | Quota ordinaria; **2× su GLM-5.3-Flash nella finestra della campagna** |
+| **Codex** | Sì | Esplicitamente incluso fra i Coding Agent Tool | Come sopra |
+| **Claude Code** | Sì | Supportato e corredato da guida CLI ufficiale Z.ai | Come sopra |
+| **OpenCode** | Sì | Supportato; guida ufficiale intitolata esplicitamente “OpenCode CLI” | Come sopra |
+| **Droid** | Sì | Descritto da Z.ai come agente che gira nel terminale | Come sopra |
+| **Crush** | Sì | Descritto esplicitamente come CLI/TUI | Come sopra |
+| **Goose** | Sì | Incluso fra i Coding Agent Tool, con esecuzione locale | Come sopra |
+| **Oh My Pi (OMP)** | Sì, tecnicamente | **Non è nominato** nell'elenco ufficiale; Z.ai nomina Pi, non OMP | Bonus e conformità **non confermati ufficialmente** |
+
+Fonti: [elenco ufficiale dei tool e endpoint Coding Plan](https://docs.z.ai/devpack/tool/others), [guida Claude Code](https://docs.z.ai/devpack/tool/claude), [guida OpenCode CLI](https://docs.z.ai/devpack/tool/opencode).
+
+Z.ai espone endpoint Coding Plan per Anthropic Messages, OpenAI Chat Completions e OpenAI Responses, ma questo **non rende automaticamente autorizzato qualunque client compatibile**: le condizioni limitano la quota ai tool ufficialmente supportati e avvertono che l'uso con integrazioni non autorizzate può comportare restrizioni. ([Subscription Terms](https://docs.z.ai/legal-agreement/subscription-terms), [Usage Policy](https://docs.z.ai/devpack/usage-policy))
+
+## Implicazione pratica per il server
+
+Per il caso in esame sceglierei **Pi + configurazione Amos direttamente sul server**: Pi è ora nominato ufficialmente da Z.ai, funziona da terminale e, durante la campagna attuale, rientra ragionevolmente negli “other supported Agents” con quota raddoppiata per GLM-5.3-Flash. La configurazione Amos estende Pi senza sostituire il client; resta comunque prudente verificare nel pannello consumi che le chiamate vengano classificate come Pi.
+
+La seconda scelta è **OpenCode**, perché Z.ai fornisce una procedura CLI esplicita (`opencode auth login` → `Z.AI Coding Plan`). Claude Code è altrettanto documentato, ma la scelta dipende dalla preferenza per il suo harness.
+
+Non sceglierei OMP confidando nel bonus: benché possa usare endpoint compatibili, **Oh My Pi non compare per nome** nell'elenco autorizzato. La risposta ufficialmente difendibile è quindi: **Pi sì; OMP non confermato**.
+
+Infine, ZCode dispone oggi di pacchetti Linux, ma la documentazione li definisce sempre **desktop app** (`.AppImage`, `.deb`, `.rpm`) da lanciare con interfaccia grafica; non documenta una modalità CLI/headless equivalente a Pi o OpenCode. ([Installazione ZCode](https://zcode.z.ai/en/docs/install))
+
+## Verdetto
+
+- Se si cerca **esattamente un +50% permanente**, non risulta alcun harness CLI ufficialmente documentato.
+- Se si vuole sfruttare la **promozione corrente**, Pi, Codex, Claude Code, OpenCode, Droid, Crush e Goose sono alternative CLI ufficialmente supportate; nel periodo e nella fascia indicati ottengono **2×**, non 150%, usando GLM-5.3-Flash.
+- Per questa infrastruttura sceglierei **Pi+Amos sul server**, oppure **OpenCode** se si desidera il percorso d'installazione più esplicitamente documentato da Z.ai.

docs/research/2026-09-07-zed-acp-omp-pi.md

@@ -0,0 +1,67 @@
+# ACP di Zed, Oh My Pi e Pi
+
+_Verifica effettuata il 7 settembre 2026 su documentazione e codice sorgente primari._
+
+## In breve
+
+ACP (Agent Client Protocol) è un protocollo aperto che standardizza il collegamento tra un
+editor/IDE e un coding agent. Il paragone utile è con LSP: LSP standardizza editor ↔ language
+server, ACP standardizza editor ↔ agente. Il client (per esempio Zed) ospita l'interfaccia;
+l'agent process conserva normalmente runtime, modelli, autenticazione, strumenti e configurazione.
+
+ACP usa JSON-RPC 2.0. Copre inizializzazione e autenticazione, creazione/ripristino delle sessioni,
+prompt e cancellazione, streaming di testo e pensieri, piani e tool call, comandi, richieste di
+permesso e — se entrambe le parti lo supportano — operazioni su filesystem e terminale.
+
+Fonti: [introduzione ACP](https://agentclientprotocol.com/overview/introduction),
+[flusso e metodi del protocollo](https://agentclientprotocol.com/protocol/overview),
+[External Agents in Zed](https://zed.dev/docs/ai/external-agents).
+
+## Confronto in Zed
+
+| Aspetto | Oh My Pi | Pi |
+|---|---|---|
+| Tipo di integrazione | Server ACP incorporato: `omp acp` | Adapter comunitario `pi-acp`, installabile dal registry di Zed |
+| Collegamento al motore | ACP è una modalità dello stesso motore OMP | L'adapter avvia `pi --mode rpc` e traduce RPC ↔ ACP |
+| Output e tool call | Streaming e tool call ACP nativi | Streaming, tool card, posizioni nei file e diff strutturati tradotti dall'adapter |
+| File | Può inoltrare `read`/`write` al filesystem del client | Nessuna delega ACP `fs/*`; Pi legge e scrive localmente |
+| Terminale | Può creare e seguire terminali del client | Nessuna delega ACP `terminal/*`; i comandi girano localmente |
+| Permessi | `edit` e `bash` possono usare `session/request_permission` nell'editor | La UI riceve i tool call, ma non ha la stessa integrazione nativa di file/terminale |
+| Sessioni | Implementazione diretta di sessioni, comandi e configurazione ACP | Mappa le sessioni ACP ai file di sessione Pi e supporta `session/load` |
+| Skills/comandi | Carica skills, estensioni e slash command OMP | Carica skills e comandi Pi; l'adapter aggiunge comandi per l'uso headless |
+| MCP configurati in Zed | OMP contiene il plumbing ACP/MCP nel proprio server | Accettati nei parametri ACP ma non inoltrati a Pi dall'adapter corrente |
+| Maturità dichiarata | Funzionalità first-class del progetto | L'adapter si definisce “MVP-style” e centrato soprattutto su Zed |
+
+L'integrazione OMP non è solo una dichiarazione nel README: il comando ACP è parte del sorgente e
+il `ClientBridge` instrada `read`, `write`, `bash`, `edit` e richieste di permesso verso il client
+quando Zed annuncia le capacità corrispondenti. Fonti:
+[README OMP](https://github.com/can1357/oh-my-pi/blob/daf07999c2fee9b22edc7bf8fea1fb6272e0df5e/README.md),
+[comando ACP](https://github.com/can1357/oh-my-pi/blob/daf07999c2fee9b22edc7bf8fea1fb6272e0df5e/packages/coding-agent/src/commands/acp.ts),
+[ACP ClientBridge](https://github.com/can1357/oh-my-pi/blob/daf07999c2fee9b22edc7bf8fea1fb6272e0df5e/packages/coding-agent/src/modes/acp/acp-client-bridge.ts).
+
+Pi è comunque supportato esplicitamente da Zed: si installa `pi ACP` dal registry. L'integrazione
+è però un progetto separato e non una modalità presente nel core Pi. L'adapter corrente conserva
+molto dell'esperienza utile — streaming, tool call, diff, resume, comandi e skills — ma dichiara
+esplicitamente di non delegare filesystem o terminale a Zed e di non collegare a Pi gli MCP server
+ricevuti dal client. Fonti:
+[scheda Pi nel registry Zed](https://zed.dev/acp/agent/pi),
+[manifest del registry](https://github.com/agentclientprotocol/registry/blob/9ec416a76f69c9ff8a8316931e38f4c74ad41fa8/pi-acp/agent.json),
+[README e limiti di `pi-acp`](https://github.com/svkozak/pi-acp/blob/d1cffc047ab37a096ee70ca39cfc1de463db8d12/README.md),
+[RPC di Pi](https://github.com/earendil-works/pi/blob/9211da172325117dc59e6f9f25f248dc628b3f81/packages/coding-agent/docs/rpc.md).
+
+## Giudizio
+
+**OMP si trova meglio con ACP perché ACP è una sua interfaccia nativa e il suo livello strumenti è
+stato progettato per delegare operazioni all'editor.** Zed non è soltanto una finestra per la chat:
+partecipa a file, terminale e autorizzazioni.
+
+**Pi si trova comunque bene con Zed per l'uso quotidiano**, specialmente per conversazione,
+streaming, modifiche, diff e ripresa delle sessioni. Oggi, però, l'integrazione è meno profonda:
+Zed controlla un adapter che controlla Pi via RPC, mentre file e shell rimangono dal lato Pi.
+
+Per Pi+Amos, i subagenti tmux non diventano automaticamente thread/subagenti nativi di Zed: ACP
+espone la sessione Pi principale, mentre l'orchestrazione Amos continua nel proprio runtime e nei
+pane tmux. È quindi una combinazione possibile, ma per osservare e pilotare direttamente quei pane
+l'esperienza terminale/tmux resta più fedele. Questa conclusione è un'inferenza dall'architettura
+dell'adapter (`pi-acp` avvia una singola sessione Pi RPC per sessione ACP) e dai limiti dichiarati,
+non una garanzia esplicita del progetto Amos.

docs/research/text-to-sql-products.md

@@ -0,0 +1,33 @@
+# Prodotti text-to-SQL e natural-language-to-SQL
+
+Ricognizione di prodotti e siti ufficiali che consentono di interrogare dati strutturati
+in linguaggio naturale e/o di generare SQL. Sono escluse pubblicazioni accademiche,
+benchmark e articoli di terze parti. Le descrizioni riportano solo capacità dichiarate
+nelle fonti ufficiali collegate.
+
+Data della ricerca: 2026-09-09.
+
+Nota di verifica: al 2026-09-09 SQLPilot non è stato verificato come raggiungibile. Il fetch
+del sito ufficiale `https://sqlpilot.ai/` restituisce `502 Bad Gateway`; anche
+`https://www.sqlpilot.ai/`, `http://sqlpilot.ai/`, `/download` e `/signup` non risultano
+raggiungibili dal controllo diretto (risoluzione DNS fallita), senza redirect osservabili.
+La pagina ufficiale indicizzata in precedenza resta una fonte storica, non una conferma di
+disponibilità odierna. Non è stato individuato un URL ufficiale alternativo funzionante.
+
+| Prodotto | URL ufficiale | Descrizione verificabile | Modello |
+|---|---|---|---|
+| [Vanna AI](https://vanna.ai/) | [Sito](https://vanna.ai/) · [Documentazione](https://vanna.ai/docs/index.html) | Framework/agente SQL che permette agli utenti di porre domande in linguaggio naturale su un database. La documentazione descrive un flusso RAG: si addestra il modello con SQL, DDL e documentazione, poi `ask` genera SQL che può essere eseguito sul database. | Open source; disponibile anche come servizio/soluzione hosted ed enterprise. |
+| [Wren AI](https://github.com/Canner/WrenAI) | [Repository ufficiale](https://github.com/Canner/WrenAI) · [Documentazione CLI](https://github.com/Canner/WrenAI/blob/main/docs/core/reference/cli.md) | Layer semantico open source per agenti e applicazioni GenBI. Il progetto dichiara supporto a text-to-SQL su oltre 20 sorgenti dati; la CLI conserva coppie natural-language-to-SQL e usa il contesto semantico/MDL per scrivere ed eseguire query. | Open source (licenza Apache-2.0 per il core dichiarato nel repository). |
+| [Dataherald](https://github.com/Dataherald/dataherald) | [Repository ufficiale](https://github.com/Dataherald/dataherald) | Engine natural-language-to-SQL per domande su dati relazionali. Il repository descrive un’API che espone un database in modo interrogabile in linguaggio naturale e include componenti per engine, API enterprise, console amministrativa e Slackbot. | Open source (Apache-2.0); include componenti enterprise self-hosted. |
+| [DB-GPT](https://github.com/eosphoros-ai/DB-GPT) | [Repository ufficiale](https://github.com/eosphoros-ai/DB-GPT) · [DB-GPT-Hub](https://github.com/eosphoros-ai/DB-GPT-Hub) | Framework open source per applicazioni data-driven e agenti, con un workflow Text-to-SQL documentato e un progetto Hub per dataset, modelli e fine-tuning dedicati alla conversione testo-SQL. | Open source. |
+| [Snowflake Cortex Analyst](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-analyst) | [Documentazione ufficiale](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-analyst) | Servizio gestito di Snowflake con cui utenti business pongono domande in linguaggio naturale e ricevono risposte senza scrivere SQL. La documentazione lo descrive esplicitamente come sistema agentico che genera risposte text-to-SQL, usando semantic model/views per il contesto. | SaaS/enterprise gestito nella piattaforma Snowflake. |
+| [Databricks Genie / Genie Agents](https://docs.databricks.com/gcp/en/genie-agents/concepts) | [Documentazione ufficiale](https://docs.databricks.com/gcp/en/genie-agents/concepts) · [API](https://docs.databricks.com/gcp/en/genie-agents/conversation-api) | Funzionalità Databricks per interagire con dati tramite linguaggio naturale. La documentazione dichiara che Genie converte i prompt in SQL, restituisce quando possibile la query generata e i risultati, e può porre domande di chiarimento. | SaaS/enterprise, integrato in Databricks. |
+| [ThoughtSpot Spotter](https://www.thoughtspot.com/product/spotter-semantics) | [Pagina prodotto ufficiale](https://www.thoughtspot.com/product/spotter-semantics) · [SpotGuide](https://tsa-guide.thoughtspot.com/) | Interfaccia di analytics conversazionale: l’utente descrive ciò che vuole in linguaggio naturale e il motore genera query SQL deterministiche tramite il layer semantico. La guida ufficiale presenta Spotter come esperienza “no SQL” per cercare e interrogare i dati. | SaaS/enterprise analytics. |
+| [Seek AI](https://www.seek.ai/ai-data-analyst) | [AI Data Analyst](https://www.seek.ai/ai-data-analyst) · [Product Overview](https://www.seek.ai/product-overview) | Piattaforma/agent per dati strutturati con un Dialogue Agent che interpreta domande in linguaggio naturale e un Semantic Parsing Agent che genera query; l’offerta include anche un’interfaccia embedded per prodotti SaaS e un’app nativa Snowflake. | SaaS/enterprise; disponibile anche come componente embedded e Snowflake Native App. |
+| ~~SQLPilot~~ | [Sito ufficiale](https://sqlpilot.ai/) | **Non verificato al 2026-09-09**: il dominio ufficiale non è risultato raggiungibile (502/DNS) e non è stato trovato un redirect o un URL ufficiale alternativo funzionante. Una precedente indicizzazione ufficiale descriveva un editor SQL assistito da AI, ma non costituisce conferma di disponibilità odierna. | Non verificato. |
+
+## Note di perimetro
+
+- “Open source” indica un progetto il cui repository ufficiale dichiara una licenza o un core open source; non implica che eventuali servizi hosted siano gratuiti.
+- “SaaS/enterprise” indica un prodotto gestito o venduto come piattaforma aziendale; le fonti ufficiali non sempre pubblicano prezzi o dettagli contrattuali.
+- Le capacità possono dipendere dal database collegato, dal modello semantico configurato e dai permessi dell’installazione.