**I tuoi agenti scrivono codice. Truthmark mantiene la documentazione pensata per le persone e revisionabile in Git.**
Truthmark installa workflow nativi di Git che permettono agli agenti di coding IA di creare nuova documentazione di prodotto e ingegneria a partire dal codice e dai test esistenti, mantenerla aggiornata dopo ogni modifica al codice e consegnarti normali diff Markdown da revisionare.
La maggior parte degli strumenti di documentazione si ferma dopo la generazione. Truthmark offre agli agenti un ciclo di vita completo della documentazione all’interno del tuo repository:
- **Crea nuova documentazione da software funzionante.** Truth Document legge codice e test, quindi crea documentazione di prodotto o ingegneria con un perimetro definito.
- **Mantieni la documentazione allineata automaticamente.** Truth Sync viene eseguito al passaggio di consegne dell’agente dopo modifiche funzionali al codice e aggiorna la verità del repository prima che il lavoro sia concluso.
- **Trasforma nuovamente la documentazione in codice.** Truth Realize implementa documenti di verità approvati mantenendo un workflow pulito che parte dalla documentazione.
- **Ripristina la proprietà man mano che la codebase cresce.** Truth Structure crea percorsi delimitati e documenti iniziali per aree nuove o sovraccariche.
- **Revisiona tutto in Git.** Codice, decisioni, contratti, architettura, operazioni e comportamento viaggiano insieme al branch.
Nessuna knowledge base ospitata. Nessuna memoria privata degli agenti. Nessuna documentazione intrappolata nella cronologia delle chat.
## Avvio rapido: crea il tuo primo documento di verità
**Requisiti:** Node.js 24 o versione successiva, un repository Git e un host di coding IA supportato per i workflow degli agenti.
Esegui quanto segue nel repository che vuoi far gestire a Truthmark:
`truthmark init` permette di selezionare Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor oppure una configurazione dell’interfaccia a riga di comando neutrale rispetto all’host.
Ora chiedi all’agente configurato di documentare un comportamento reale:
```text
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
```
Truth Document crea un nuovo documento di verità delimitato quando non ne esiste uno, aggiorna il documento proprietario esistente quando è presente e aggiorna il routing quando necessario. Non modifica il codice funzionale.
I percorsi esatti seguono la struttura di proprietà del tuo repository. I nuovi file compaiono in `git status`; le modifiche ai file tracciati compaiono in `git diff`.
La modalità di invocazione varia in base all’host. OpenCode usa `/skill truthmark-document`, Antigravity usa `@truthmark-document` e gli altri host supportati utilizzano la propria interfaccia nativa per skill o comandi slash. Consulta la [tabella delle piattaforme](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md#supported-agent-platforms) per i comandi esatti.
Per script e integrazione continua, passa esplicitamente le piattaforme selezionate:
Scegli `none` in modalità interattiva oppure esegui `truthmark init --clear-platforms` per ottenere un repository neutrale rispetto all’host. Puoi aggiungere piattaforme per agenti in seguito rieseguendo `truthmark init`.
L’interfaccia a riga di comando di Truthmark installa e convalida il contratto del repository. Il tuo agente di coding esegue la revisione delle evidenze e il lavoro di documentazione attraverso i workflow nativi dell’host installati.
| **Truth Document** | Il codice esistente ha bisogno di documentazione | Crea o aggiorna documentazione di prodotto e ingegneria basata su evidenze |
| **Truth Sync** | Il codice funzionale è cambiato | Mantiene allineati la documentazione mappata e il routing prima della consegna |
| **Truth Structure** | Una nuova area ha bisogno di proprietà o la documentazione esistente è troppo ampia | Crea percorsi delimitati e strutture iniziali per i documenti |
| **Truth Realize** | Un documento di verità approvato deve diventare software funzionante | Aggiorna il codice funzionale a partire dalla documentazione |
| **Truth Check** | La verità del repository deve essere sottoposta ad audit | Segnala problemi di routing, proprietà, evidenze e documentazione |
| **Truthmark Portal** | Il team desidera un sito di documentazione navigabile | Genera una presentazione HTML statica e versionata dai documenti di verità Markdown |
Truthmark può creare documentazione per funzionalità di prodotto, comportamento dell’implementazione, interfacce di programmazione delle applicazioni, architettura, workflow, operazioni e test. Codice e test forniscono le evidenze; documenti Markdown delimitati conservano il risultato.
I percorsi collegano le aree di codice ai documenti canonici. Quando gli agenti modificano il comportamento, Truth Sync sa dove deve risiedere la verità corrispondente e mantiene la consegna revisionabile.
La verità di prodotto raccoglie promesse rivolte agli utenti, limiti, decisioni e criteri di accettazione. La verità di ingegneria raccoglie comportamento corrente, contratti, architettura, workflow, operazioni e comportamento dei test.
Tutto ciò che conta risiede in file versionati del repository. La verità segue il branch, funziona con normali pull request e rimane visibile a ogni maintainer e agente di coding.
Truthmark non richiede servizi ospitati, daemon, database, archivi vettoriali o server Model Context Protocol. Il repository contiene il proprio workflow di documentazione.
Truthmark è progettato per maintainer e team di ingegneria che usano già agenti di coding IA e vogliono che il repository continui a dire la verità con la stessa rapidità con cui cambia il codice.
| `truthmark init` | Crea o aggiorna configurazione, routing, template e workflow degli host selezionati |
| `truthmark check [--base <ref>]` | Convalida la verità del repository e, facoltativamente, esegue la diagnostica di aggiornamento del branch |
| `truthmark index --json` | Ispeziona i metadati derivati del repository e del routing |
| `truthmark impact --base <ref> --json` | Mappa i file modificati su documenti, proprietari e test vicini |
| `truthmark workflow status --workflow <id> [--base <ref>] --json` | Ispeziona applicabilità e obiettivi del workflow |
| `truthmark validate ...` | Convalida i report dei workflow e le concessioni di scrittura |
| `truthmark uninstall --dry-run` / `truthmark uninstall --apply` | Mostra in anteprima o rimuove le superfici host generate preservando la verità creata |
- [Contratti di configurazione, routing e comandi](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
- [Manutenzione della verità del repository](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
