docs: focus public documentation on product usage

This commit is contained in:
2026-08-26 10:15:07 +02:00
parent 23bc2f6555
commit a54d4769dd
67 changed files with 290 additions and 9963 deletions
+8 -15
View File
@@ -27,7 +27,6 @@ Per il filesystem Evidence v2, il primo sorgente autorevole deve stare nella dir
├── curated/ # Evidence Units revisionate
│ └── <dominio>/<unit>.md
├── manifest.yaml # legami, hash e metadati della preparazione
├── evaluation/ # fixture di valutazione del recupero
└── example/ # esempi e materiale di supporto
```
@@ -53,19 +52,19 @@ Le unità Markdown lette dal loader storico della CLI hanno frontmatter YAML. I
```markdown
---
id: evidence:fascia-pediatrica
title: Fascia pediatrica
id: evidence:autonomia-batteria
title: Autonomia nominale della batteria
tier: structural
status: reviewed
sources:
- source/domain/patient.md
- source/domain/bicycle.md
tables:
- patient
- bicycle_model
concepts:
- concept:patient-age
- concept:battery-range
---
Definizione verificata della fascia pediatrica.
Definizione verificata dell'autonomia nominale per modello di bicicletta elettrica.
La regola deve essere abbastanza atomica da poter essere citata senza ricostruire
un intero capitolo. Il testo deve distinguere definizione, condizioni e limiti.
@@ -90,13 +89,11 @@ flowchart TD
ING --> VEC["Embedding e vector store"]
BM25 --> GEN["Generazione candidata"]
VEC --> GEN
GEN --> EVAL["tht evidence evaluate\nfixture di retrieval"]
EVAL -->|pass| ACT["Generazione attiva"]
EVAL -->|fail| FIX
GEN --> ACT["Generazione attiva"]
ACT --> RUNTIME["Ricerca Evidence nel workflow"]
```
La preparazione può ristrutturare sorgenti cambiate, ma non pubblica da sola. `prepare` produce una proposta e può indicare il file sorgente coinvolto in caso di errore. `validate` non scrive né pubblica. Il commit è un'azione del curatore nel clone di authoring. Il runtime legge una revisione completa e validata, poi la pipeline crea una generazione versionata. L'attivazione è atomica: una generazione precedente resta disponibile secondo la policy di retention.
La preparazione può ristrutturare sorgenti cambiate, ma non pubblica da sola. `prepare` produce una proposta e può indicare il documento coinvolto in caso di errore. `validate` non scrive né pubblica. La pubblicazione della revisione è un'azione del curatore. Il runtime legge una revisione completa e validata, poi la pipeline crea una generazione versionata. L'attivazione è atomica: una generazione precedente resta disponibile secondo la policy di retention.
La ricerca runtime usa il recupero ibrido. Il ramo denso usa gli embedding, il ramo BM25 usa la ricerca lessicale e la fusione deterministica ordina i risultati. L'unità pubblicata conserva la provenienza, che il modello deve citare quando usa l'evidence.
@@ -183,7 +180,3 @@ Le formule hanno un formato distinto dalle Evidence documentali. Una formula pro
- [Contratto Workspace Evidence v3](contracts/workspace-evidence-v3.md)
- [Contratto della CLI di preprocessing](contracts/workspace-preprocessing-cli.md)
- [ADR: confine di pubblicazione](adr/0001-evidence-publication-boundary.md)
- [ADR: preparazione atomica e ancorata al sorgente](adr/0006-grounded-atomic-evidence-preparation.md)
- [ADR: valutazione prima dell'attivazione](adr/0003-evaluate-evidence-before-activation.md)
- [ADR: recupero ibrido deterministico](adr/0008-make-hybrid-evidence-retrieval-deterministic.md)