docs: aggregate P2-P6 acceptance, full-suite results, and user guide

PROJECT_STATE.md

@@ -7,7 +7,7 @@
 > ThothII per il repository (app + CLI `thothctl`), (3) come usare l'applicazione ThothII di base
 > (sessioni, domande, gate). Il documento userà parole semplici ed esempi; i dettagli tecnici
 > resteranno nei contratti esistenti. Esempio pratico completo: Policlinico San Donato.
- Last updated: 2026-08-13 (P2–P6 all accepted).
+ Last updated: 2026-08-13 (P2–P6 accepted; aggregate PASS; user guide written).
 > Point a fresh session here ("read PROJECT_STATE.md") before substantial work.
 
 ### P3 effective configuration and `.tht-dwh` — implementation complete, automated PASS, manual PASS (2026-08-13)
@@ -134,6 +134,34 @@
 - **Manual acceptance:** PASS (owner approval 2026-08-13) — walkthrough section P6 in
   `docs/testing/p2-p6-manual-verification.md`.
 
+### Final aggregate P2–P6 verification — automated PASS, manual PENDING (2026-08-13)
+
+- **Aggregate process goal:** one clean-state run exercises the complete DWH → FK → schema →
+  filesystem Evidence chain through `thothctl`/the operator surface, proves idempotency and
+  revision isolation, proves a second installation consumes the same Git workspace with its own
+  state, exercises unsafe-tree and bound negatives, and cleans only owned resources.
+- **Automated acceptance:** PASS 12/12 (run `p2p6-ee542112c526ef0d4c25ddf6c8bc164b`, report
+  `.artifacts/p2p6-integration/p2p6-ee542112c526ef0d4c25ddf6c8bc164b/` retained via `--keep`, bound
+  to clean source commit `1dcf4051b0d9db8ae163e4d7c53871564ca3c564`): preflight, clean_state,
+  ownership, activation_materialization, dwh_chain, fk_schema_evidence_chain, revision_isolation,
+  second_installation, unsafe_tree_refused, bound_refused, secret_scan, cleanup_confinement. Runner:
+  `scripts/p2p6-acceptance.sh` / `backend/scripts/p2p6-acceptance.mjs` (+unit test).
+- **Full suites + builds (design §10):** harness **873 passed / 4 deselected** (with color disabled;
+  the forced-color environment splits `--help` flags and trips the gate-CLI consistency test only);
+  backend **698/698** + tsc + build; frontend **364/364** + `tsc -b` + build; `thothctl` Go
+  build+test **9/9**; `git diff --check` clean.
+- **Manual acceptance:** PENDING — "Final aggregate P2–P6 verification" in
+  `docs/testing/p2-p6-manual-verification.md`.
+
+### User-guide deliverable (owner requirement) — written, review PENDING (2026-08-13)
+
+- **`docs/guida-utente.md`** (Italian, simple words + examples) covers: (1) preparing the workspace
+  Git repository (catalog + schema-v3 descriptor + Evidence + curated annotations), (2) using the
+  ThothII tools for the repository (`thothctl` commands + read-only workspace management), and (3)
+  using the base ThothII application (sessions, questions, gates). It ends with a complete
+  Policlinico San Donato walkthrough and links to the technical contracts.
+- Registered in the MkDocs nav (`mkdocs.yml`). Owner review PENDING.
+
 ### P2 host preprocessing CLI — implementation complete, automated PASS, manual PENDING (2026-08-11)
 
 - **Scope:** P2 (PRD D2, based on the P1.1 registry contract): the installed native `thothctl`

docs/guida-utente.md

@@ -0,0 +1,255 @@
+# ThothII — Guida utente
+
+Questa guida accompagna passo-passo chi deve **preparare** il repository dei workspace, **usare
+gli strumenti** ThothII per quel repository e **usare l'applicazione** per fare domande in
+linguaggio naturale e ottenere SQL validato. Usa parole semplici ed esempi; i dettagli tecnici
+restano nei contratti citati in fondo.
+
+> **Che cos'è ThothII.** È un *datamart builder* con revisione umana: tu scrivi una domanda in
+> linguaggio naturale, un modello propone via via i passaggi (chiarimenti, schema, CTE, SQL) e un
+> **revisore umano decide** a ogni passaggio chiave. Il risultato finale è SQL validato pronto da
+> eseguire sul data warehouse.
+
+---
+
+## Parte 1 — Preparare il repository dei workspace su Git
+
+### 1.1 La struttura
+
+Il repository dei workspace è un **repository Git** che descrive *quali dati* sono disponibili e
+*come raggiungerli*. Non contiene i dati e **non contiene segreti** (password, token, certificati).
+
+Un repository valido contiene:
+
+```text
+thoth-workspaces.yaml              ← catalogo: elenco dei workspace
+<id-workspace>/workspace.yaml      ← descrittore del workspace (schema v3)
+<id-workspace>/evidence/           ← (facoltativo) documenti di contesto, es. *.md
+<id-workspace>/schema/annotations.yaml   ← (facoltativo) join logici curati a mano (P5)
+workspace-docs/<id-workspace>/     ← generato dall'applicazione, non va editato
+```
+
+- Il **catalogo** `thoth-workspaces.yaml` è un semplice elenco:
+
+```yaml
+schema_version: 1
+workspaces:
+  - id: psd-clinical
+    name: Policlinico San Donato
+    description: DWH clinico del Policlinico San Donato
+```
+
+- L'**id** deve essere minuscolo, senza spazi, es. `psd-clinical` (`[a-z][a-z0-9-]{2,62}`).
+- Il **descrittore** `<id>/workspace.yaml` è lo schema v3. È l'unica descrizione valida.
+
+### 1.2 Esempio di descrittore (Policlinico San Donato)
+
+```yaml
+workspace:
+  schema_version: 3
+  id: psd-clinical
+  name: Policlinico San Donato
+  description: DWH clinico — aritmologia
+  language: it                      # le descrizioni/evidence sono in italiano
+
+dwh:
+  engine: postgres
+  database: postgres
+  schema: datawarehouse
+  supported_transports: [rest_api]  # accesso tramite API REST (PostgREST)
+
+semantic_index:
+  vector_store:
+    engine: qdrant
+    collection: psd-clinical
+    dimensions: 1024
+    distance: cosine
+  embedding:
+    provider: ollama_internal
+    model: qwen3-embedding:0.6b
+    dimensions: 1024
+
+llm_policy:
+  allowed: [zai/glm-5.2]
+
+diagnostics:
+  dwh_rest:
+    method: POST
+    path: /rpc/ping
+    auth: x-api-key
+    response: { database: database, schema: schema }
+
+evidence:
+  source:
+    type: filesystem
+    uri: psd-clinical/evidence      # percorso dentro il repository
+  policy:
+    max_chunk_chars: 4000
+    retain_published_generations: 3
+```
+
+Cosa cambia rispetto ai vecchi workspace (se ne avevi uno):
+
+- il database si raggiunge solo con **REST** o **Postgres diretto** (`rest_api` /
+  `postgres_direct`); il tunnel SSH resta disabilitato;
+- l'indice semantico è **interno** (Qdrant + `qwen3-embedding:0.6b`, 1024 dimensioni, cosine);
+- l'Evidence **filesystem** sta dentro il repository (`<id>/evidence`) e viene materializzata dal
+  commit Git fissato (P6); è supportata anche l'Evidence HTTP.
+
+### 1.3 Regole da rispettare
+
+1. **Git è la fonte di verità.** Descriptor, catalogo ed Evidence si modificano solo con un
+   *commit* + *push* e poi un *pull* dell'installazione.
+2. **Niente segreti nel repository.** Endpoint, token, certificati e password vivono solo nei file
+   di installazione protetti (fuori da Git).
+3. **I file `workspace-docs/` sono generati** dall'applicazione: non modificarli a mano.
+4. **Solo schema v3.** I descrittori v1/v2 vengono rifiutati prima dell'attivazione.
+5. **L'applicazione non fa push di contenuti curati.** L'operatore che cura il repository lavora in
+   un clone autore separato.
+
+---
+
+## Parte 2 — Usare gli strumenti ThothII per il repository
+
+Ci sono **due** strumenti: l'**applicazione web** (gestione workspace) e la **CLI `thothctl`**
+(preprocessing/operator). L'installazione completa è descritta nei manuali
+`docs/install/local-workspace-registry.md` (macOS/Windows/Linux) e
+`docs/install/server-workspace-registry.md`.
+
+### 2.1 `thothctl` — comandi principali
+
+`thothctl` si invoca sempre con `--installation <percorso>/thothii-installation.yaml`. I comandi
+utili, nell'ordine tipico:
+
+```bash
+# 1) vedere lo stato di un workspace (revisione e identità)
+thothctl --installation <install> workspace inspect --workspace <id> --json
+
+# 2) introspezione del DWH (genera physical.yaml + LSH)
+thothctl --installation <install> workspace preprocess dwh --workspace <id> --json
+
+# 3) suggerire le join (FK) da SQL già approvato
+thothctl --installation <install> workspace schema suggest-fks --workspace <id>   --from-sql <query>.sql --output <candidati>.yaml --json
+
+# 4) dopo la revisione: pubblicare gli FK curati in Git e accettarli
+thothctl --installation <install> workspace schema accept --workspace <id>   --run <run-id> --yes --json
+
+# 5) indicizzare lo schema (Qdrant)
+thothctl --installation <install> workspace index-schema --workspace <id> --json
+
+# 6) preprocessing dell'Evidence
+thothctl --installation <install> workspace preprocess evidence --workspace <id> --json
+
+# 7) catena completa (DWH → FK → schema → Evidence)
+thothctl --installation <install> workspace preprocess run --workspace <id> --json
+
+# 8) ispezione/ricostruzione della collection Qdrant (solo manutenzione)
+thothctl --installation <install> workspace vector inspect --workspace <id> --json
+thothctl --installation <install> workspace vector rebuild --workspace <id>   --collection <nome> --confirm <nome> --destroy
+```
+
+Note importanti:
+
+- **`--json` produce solo JSON su stdout** (contratto macchina): usalo negli script.
+- **`preprocess run` si ferma per la revisione umana** quando ci sono nuove join proposte: esce con
+  `manual_review_required`. Dopo la revisione si riparte con `schema accept ... --yes` e
+  `preprocess run --resume <run-id>`.
+- **Un file Evidence filesystem viene materializzato dal commit Git fissato** (niente checkout
+  mobile); symlink, percorsi pericolosi e alberi troppo grandi vengono rifiutati.
+- **Il CLI non scrive mai nel repository** (nessun push di contenuti curati).
+
+### 2.2 Applicazione web — gestione workspace
+
+Per i workspace **già pronti** (`ready`) la pagina workspace è **in sola lettura**:
+*Pull/Sync*, *Validate*, *Test* dell'installazione, *Export*, riepilogo Evidence e la guida Git per
+il curatore. Il modulo di bootstrap modificabile compare solo per gli slot del catalogo in stato
+`configuration_required`.
+
+---
+
+## Parte 3 — Usare l'applicazione ThothII di base
+
+### 3.1 Nuova sessione
+
+Apri l'applicazione e usa il modulo **New session**: inserisci solo la **domanda** in linguaggio
+naturale (workspace, modello e provider sono impostazioni globali già configurate).
+
+Esempio di domanda:
+
+> «Estrai i pazienti che hanno eseguito un'ablazione nell'ultimo anno, con nome, cognome e data
+> dell'intervento.»
+
+### 3.2 Il workflow a 8 fasi e i gate
+
+La domanda attraversa **8 fasi**. Tu vedi i documenti intermedi e decidi nei punti chiave:
+
+1. **F1 chiarimento** — se serve, il modello chiede di togliere ambiguità;
+2. **F2 memoria** — recupera le memory riutilizzabili;
+3. **F3 riscrittura** — riscrive e approva la domanda;
+4. **F4 schema-linking** — propone tabelle e colonne collegate;
+5. **F5 sintesi** — riassume lo schema scelto;
+6. **F6 CTE** — costruisce i CTE;
+7. **F7 SQL finale** — produce `sql_final.sql`;
+8. **F8 datamart** — esecuzione/export (dbt, CSV, Excel).
+
+I **gate di revisione** appaiono come widget: scegli un'opzione singola, seleziona più voci, o
+conferma un artefatto/fase. Il modello *propone*, il revisore *decide*. Il lato destro mostra gli
+artefatti (schema-linking, CTE, SQL); il pannello Model activity mostra domanda/ragionamento.
+
+### 3.3 Sessioni
+
+Le sessioni sono elencate nella barra laterale con id, domanda, data e autore. Una sessione
+**riprende** dall'ultima fase incompleta ricostruendo lo stato dai documenti salvati su disco
+(`session_manifest.yaml` + artefatti di fase + `review_decisions.jsonl`). Lo stato salvato **è** la
+verità: ciò che non è registrato non è avvenuto.
+
+---
+
+## Esempio pratico completo — Policlinico San Donato
+
+### Passo 0 — repository
+
+Crea il repository Git del workspace (es. `tht-workspace-psd`):
+
+```text
+thoth-workspaces.yaml          # catalogo con psd-clinical
+psd-clinical/workspace.yaml    # descrittore v3 (vedi §1.2)
+psd-clinical/evidence/         # i documenti .md di contesto curati
+psd-clinical/schema/annotations.yaml   # (quando ci sono join curate)
+```
+
+Fai `commit` e `push`. Nell'installazione, l'applicazione fa `Pull` e **attiva** il workspace:
+valida lo schema v3, materializza l'Evidence dal commit fissato e prepara la collection Qdrant
+(1024/cosine + indici).
+
+### Passo 1 — preprocessing
+
+```bash
+thothctl --installation ~/thothii-installation.yaml workspace preprocess dwh   --workspace psd-clinical --json
+thothctl --installation ~/thothii-installation.yaml workspace preprocess run   --workspace psd-clinical --json
+```
+
+Se il run si ferma per le join (`manual_review_required`):
+
+```bash
+# il curatore rivede i candidati e pubblica psd-clinical/schema/annotations.yaml, poi:
+thothctl --installation ~/thothii-installation.yaml workspace schema accept   --workspace psd-clinical --run <run-id> --yes --json
+thothctl --installation ~/thothii-installation.yaml workspace preprocess run   --workspace psd-clinical --resume <run-id> --json
+```
+
+### Passo 2 — la domanda
+
+Nell'applicazione seleziona il workspace `psd-clinical` e crea una sessione con la domanda. Segui
+le fasi e conferma ai gate: il modello proporrà lo schema-linking (tabelle/colonne del DWH
+`datawarehouse`), i CTE e infine l'SQL finale, che potrai copiare/visualizzare ed eseguire.
+
+---
+
+## Dove trovare i dettagli tecnici
+
+- Contratto CLI: `docs/contracts/workspace-preprocessing-cli.md`
+- Contratto `.tht-dwh`: `docs/contracts/tht-dwh.md`
+- Evidence v3: `docs/contracts/workspace-evidence-v3.md`
+- Installazione locale: `docs/install/local-workspace-registry.md`
+- Installazione server: `docs/install/server-workspace-registry.md`
+- Verifica manuale P2–P6: `docs/testing/p2-p6-manual-verification.md`

docs/testing/p2-p6-manual-verification.md

@@ -203,7 +203,12 @@ Checks:
 Decision: **PASS** (owner approval 2026-08-13).
 ## Final aggregate P2–P6 verification
 
-**Status:** runnable only after P6.
+**Status:** runnable; automated integration PASS; manual acceptance PENDING.
+
+The automated aggregate (run `p2p6-ee542112c526ef0d4c25ddf6c8bc164b`, report
+`.artifacts/p2p6-integration/...`) already executed the complete DWH → FK → schema → filesystem
+Evidence chain, idempotency, revision isolation, a second installation, unsafe-tree/bound negatives,
+secret scan, and exact cleanup.
 
 The final manual pass will start with a new registry and two independent installations. It will
 run the complete DWH → FK → schema → filesystem Evidence chain, prove idempotency and revision

mkdocs.yml

@@ -47,6 +47,7 @@ markdown_extensions:
     alternate_style: true
 nav:
 - Home: index.md
+- Guida utente: guida-utente.md
 - ThothII (Documentazione Tecnica):
   - Panoramica Architettura: architecture/overview.md
   - Installazione Docker (4 contesti): installazione-docker-4-contesti.md