truthmark 1.2.3 → 1.4.0

package/README.de.md

@@ -1,6 +1,6 @@
 # Truthmark
 
-**Truthmark automatisiert die Pflege von Repository-Wahrheit für KI-Softwareentwicklung.**
+**Truthmark installiert Repository-Wahrheits-Workflows für KI-Softwareentwicklung.**
 
 [English](README.md) | Deutsch | [中文](README.zh.md) | [Español](README.es.md) | [Русский](README.ru.md)
 
@@ -8,14 +8,14 @@
 
 KI-Coding-Agenten schreiben bereits schnell Code. Der teure Teil ist, die Repository-Wahrheit mit den tatsächlichen Änderungen im Gleichschritt zu halten.
 
-Truthmark fügt diesem Ablauf eine automatische Abschlusskontrolle hinzu. Der normale Pfad ist einfach:
+Truthmark fügt diesem Ablauf eine Abschlusskontrolle als Workflow hinzu. Der normale Pfad ist einfach:
 
 - Agent ändert funktionalen Code
 - relevante Tests laufen
-- Truth Sync aktualisiert zugeordnete Wahrheitsdokumente, bevor der Agent fertig ist
+- der installierte Truth-Sync-Workflow aktualisiert zugeordnete Wahrheitsdokumente, bevor der Agent fertig ist
 - Truth-Doc-Diff prüfen, wenn einer erzeugt wurde
 
-Die meisten Tools bitten Teams darum, sich eine Gewohnheit anzueignen. Truthmark automatisiert die Gewohnheit.
+Die meisten Tools bitten Teams darum, sich eine Gewohnheit anzueignen. Truthmark macht daraus Repository-Workflow-Infrastruktur.
 
 Truthmark macht aus einem KI-Workflow Repository-Infrastruktur statt persönlichem Tooling. Es installiert eine Git-native, branch-gebundene Wahrheitsschicht im Repository, gibt Agenten explizites Routing und begrenzte Workflow-Flächen und hält diese Wahrheit in Git prüfbar, statt sie über Prompt-Verlauf, veraltete Dokumentation oder privaten Tool-Zustand zu verstreuen.
 
@@ -51,12 +51,12 @@ Für Teams, die bereits wissen, dass Agenten Code erzeugen können, beantwortet
 
 Truthmark versucht nicht, Agenten klüger wirken zu lassen. Es soll KI-gestützte Repository-Änderungen vertrauenswürdiger machen.
 
-- Automatisierte Truth-Sync-Läufe nach Codeänderungen machen Dokumentationspflege zu einer Workflow-Schutzschicht statt zu einer Teamgewohnheit.
+- Installierte Truth-Sync-Läufe nach Codeänderungen machen Dokumentationspflege zu einer Workflow-Schutzschicht statt zu einer Teamgewohnheit.
 - Branch-gebundene Wahrheit bewegt sich mit dem Code, sodass Reviewer aktuelle Wahrheit in normalen Git-Diffs prüfen können.
 - Repository-native Workflow-Flächen machen Rollout leichter und Übergaben robuster als reine Pro-User-Konfiguration.
 - Explizites Routing in `docs/truthmark/areas.md` und delegierten untergeordneten Routendateien gibt Agenten Zuständigkeitsgrenzen und sicherere Schreibpfade.
 - Local-first-Betrieb vermeidet einen Daemon, eine Datenbank, einen Remote-Dienst oder eine MCP-Abhängigkeit.
-- Das Modell funktioniert in Codebasen mit JavaScript, TypeScript, Go, Python, C# und Java.
+- Das Routing-Modell ist sprachunabhängig, mit Coverage-Diagnostik für gängige JavaScript-, TypeScript-, Go-, Python-, C#- und Java-Codeflächen.
 
 Für Tech Leads liegt der Wert in Governance ohne Zusatzinfrastruktur: Tests, Code Review und Ownership leisten weiterhin die eigentliche Arbeit; Truthmark macht den Kontext des Agenten dauerhaft, prüfbar und branch-gebunden.
 
@@ -96,6 +96,7 @@ Truthmark macht Repository-Wahrheit zu einer expliziten Workflow-Fläche für Ag
 - `docs/truthmark/areas.md` und delegierte untergeordnete Routendateien ordnen Codebereiche den Dokumenten zu, die sie verantworten.
 - Truth Document erstellt oder repariert kanonische Wahrheitsdokumente für bereits implementiertes Verhalten, wenn keine Codeänderung nötig ist.
 - Truth Sync hält zugeordnete Wahrheitsdokumente bei funktionalen Änderungen synchron.
+- Truth Preview zeigt wahrscheinliches Workflow-Routing vor Änderungen an, ohne Schreibzugriffe zu autorisieren.
 - Truth Realize gibt doc-first Änderungen einen begrenzten Pfad für Code-Updates.
 - `truthmark check` validiert die daraus entstehenden Wahrheitsartefakte.
 - Das gesamte Modell bleibt local-first und Git-nativ.
@@ -132,17 +133,17 @@ Prüfe `.truthmark/config.yml` vor `init`; es ist der in Git festgeschriebene Hi
 .truthmark/config.yml
 docs/truthmark/areas.md
 docs/truthmark/areas/repository.md
-docs/templates/feature-doc.md
-docs/features/README.md
-docs/features/repository/README.md
-docs/features/repository/overview.md
+docs/templates/behavior-doc.md
+docs/truth/README.md
+docs/truth/repository/README.md
+docs/truth/repository/overview.md
 AGENTS.md
 CLAUDE.md
 GEMINI.md
 ```
 
 Unterstützte Plattformen sind `codex`, `opencode`, `claude-code`, `github-copilot` und `gemini-cli`. Die Standardkonfiguration enthält alle davon; entferne Plattformen, die du nicht nutzt, aus `.truthmark/config.yml`, bevor du `truthmark init` erneut ausführst.
-Die standardmäßig erzeugte Struktur verwendet `README.md`-Dateien von Features als Indizes und beginnt die Wahrheit über aktuelles Verhalten in begrenzten Blattdokumenten wie `docs/features/repository/overview.md`.
+Die standardmäßig erzeugte Struktur verwendet Truth-`README.md`-Dateien als Indizes und beginnt die Wahrheit über aktuelles Verhalten in begrenzten Blattdokumenten wie `docs/truth/repository/overview.md`.
 
 Bestehende Repositories brauchen nach `init` meist einen Aufräumschritt: Führe den installierten Truth-Structure-Workflow aus, wenn die erzeugte `repository`-Route zu breit ist, Ownership mehrere Produkte oder Services umfasst oder Routendateien noch auf Platzhalterdokumente zeigen. Truth Structure teilt breite Routings auf, erstellt oder repariert erste kanonische Wahrheitsdokumente und gibt Truth Sync präzise Ziele, bevor funktionale Codearbeit beginnt. Codex, Claude Code und unterstützte Copilot-IDEs können ihn mit `/truthmark-structure` aufrufen; Hosts im OpenCode-Stil können `/skill truthmark-structure` verwenden.
 
@@ -150,51 +151,88 @@ Bestehende Repositories brauchen nach `init` meist einen Aufräumschritt: Führe
 
 Truthmark ist am stärksten auf dem Standardpfad, nicht als Sammlung manueller Befehle. Der handelnde Agent und die Host-Umgebung entscheiden, ob delegiert oder der installierte Workflow inline ausgeführt wird.
 
-Nutze Truth Document, wenn implementiertes Verhalten bereits existiert, aber die kanonischen Wahrheitsdokumente fehlen oder schwach sind. Der Agent liest Implementierung, Tests, Routing und vorhandene Dokumente, schreibt nur Wahrheitsdokumente und Routing und darf funktionalen Code nicht ändern. Codex, Claude Code und unterstützte Copilot-IDEs können es mit `/truthmark-document` aufrufen; Hosts im OpenCode-Stil können `/skill truthmark-document` verwenden.
+### Vorhandenes Verhalten ohne Doku
 
-Die meisten Nutzer sollten Truth Sync nicht direkt aufrufen müssen. Entscheidend ist, dass Truth Sync als automatische Abschlusskontrolle wirkt, wenn funktionaler Code geändert wurde. Der normale Ablauf ist:
+Nutze das, wenn die Implementierung bereits existiert, aber die kanonischen Wahrheitsdokumente fehlen oder schwach sind:
 
 ```text
-Agent ändert funktionalen Code
-relevante Tests laufen
-Truth Sync wird vor dem Abschluss des Agenten ausgelöst
-Truth-Doc-Diff prüfen, falls einer erzeugt wurde
-Arbeit committen oder übergeben
+benutzer identifiziert ein implementiertes verhalten oder einen api-endpunkt
+benutzer ruft truth document ausdrücklich auf
+agent liest implementierung, tests, routing und vorhandene docs
+agent schreibt nur truth docs und routing
+truth-doc-diff prüfen
 ```
 
-Truth Sync ist code-first: Code führt, Wahrheitsdokumente folgen, und Truth Sync darf funktionalen Code nicht umschreiben. Seine Hauptaufgabe ist eine automatische Abschlusskontrolle, wenn funktionaler Code geändert wurde. Direkte Aufrufe sind vor allem für Fehlersuche, frühe Synchronisierung vor einer Übergabe oder bewusstes Ausführen des Workflows gedacht.
+Truth Document ist manuell und implementation-first: Code dient als Beleg, Wahrheitsdokumente werden erstellt oder repariert, und funktionaler Code darf nicht geändert werden. Codex, Claude Code und unterstützte Copilot-IDEs können es mit `/truthmark-document` aufrufen. Hosts im OpenCode-Stil können `/skill truthmark-document` verwenden.
+
+```text
+/truthmark-document dokumentiere das implementierte session-timeout-verhalten unter docs/truth/authentication
+```
+
+### Normale Codeänderungen
+
+Die meisten Nutzer sollten Truth Sync nicht direkt aufrufen müssen. Entscheidend ist, dass der installierte Agenten-Workflow Truth Sync als Abschlusskontrolle behandelt, wenn funktionaler Code geändert wurde. Der normale Ablauf ist:
+
+```text
+agent ändert funktionalen code
+relevante tests laufen
+der installierte truth-sync-workflow läuft, bevor der agent fertig ist
+truth-doc-diff prüfen, falls einer erzeugt wurde
+arbeit committen oder übergeben
+```
+
+Truth Sync ist code-first: Code führt, Wahrheitsdokumente folgen, und Truth Sync darf funktionalen Code nicht umschreiben. Seine Hauptaufgabe ist, über den installierten Agenten-Workflow als Abschlusskontrolle zu laufen, wenn funktionaler Code geändert wurde. Direkte Aufrufe sind vor allem für Fehlersuche, frühe Synchronisierung vor einer Übergabe oder bewusstes Ausführen des Workflows gedacht.
+
 Codex, Claude Code und unterstützte Copilot-IDEs können es mit `/truthmark-sync` aufrufen. Hosts im OpenCode-Stil können `/skill truthmark-sync` verwenden.
-Nutze diesen Ablauf, wenn eine Produkt- oder Architekturentscheidung in der Dokumentation beginnt:
 
 ```text
-Benutzer bearbeitet Wahrheitsdokumente
-Benutzer ruft Truth Realize ausdrücklich auf
-Agent liest Wahrheitsdokumente und relevanten Code
-Agent aktualisiert nur Code
-relevante Tests laufen
-Arbeit committen oder übergeben
+/truthmark-sync die repository-wahrheit jetzt vor der übergabe synchronisieren
+```
+
+### Doc-first-Änderungen
+
+Nutze das, wenn eine Produkt- oder Architekturentscheidung in der Doku beginnt:
+
+```text
+benutzer bearbeitet wahrheitsdokumente
+benutzer ruft truth realize ausdrücklich auf
+agent liest wahrheitsdokumente und relevanten code
+agent aktualisiert nur code
+relevante tests laufen
+arbeit committen oder übergeben
 ```
 
 Truth Realize ist manuell und doc-first: Wahrheitsdokumente führen, Code folgt, und der Agent darf die Wahrheitsdokumente, die er realisiert, nicht bearbeiten.
+
 Codex, Claude Code und unterstützte Copilot-IDEs können es mit `/truthmark-realize` aufrufen. Hosts im OpenCode-Stil können `/skill truthmark-realize` verwenden.
 
+```text
+/truthmark-realize docs/truth/authentication/session-timeout.md in code umsetzen
+```
+
 ## Was es installiert
 
 Truthmark hält die dauerhafte Workflow-Fläche klein und repository-nativ. Nach `truthmark init` trägt das Repository selbst Routing, Regeln und installierte Workflow-Flächen, sodass Teams nicht nur auf die lokale Konfiguration einer einzelnen Person angewiesen sind.
 
-- `.truthmark/config.yml` für maschinenlesbare Konfiguration
-- `.truthmark/config.yml` für den festgeschriebenen Hierarchievertrag
+Truthmark installiert zwei getrennte Oberflächen:
+
+- menschenorientierte CLI-Befehle, die Menschen oder CI ausführen, um das Repository zu konfigurieren, installierte Dateien zu aktualisieren, Truth-Artefakte zu validieren und optional abgeleiteten Review-Kontext zu erzeugen
+- Agenten-Workflow-Flächen, die Coding-Agenten oder Agenten-Hosts während Implementierungsworkflows aufrufen; sie sind keine zusätzlichen täglichen Terminalbefehle für Menschen
+
+- `.truthmark/config.yml` für den maschinenlesbaren, festgeschriebenen Hierarchievertrag
 - `docs/truthmark/areas.md` für den Root-Routenindex
 - `docs/truthmark/areas/**/*.md` für delegierte untergeordnete Routendateien
-- `docs/templates/feature-doc.md` für den editierbaren Feature-Dokument-Standard der generierten Workflows
+- `docs/templates/behavior-doc.md` sowie die weiteren typspezifischen Vorlagen unter `docs/templates/` für die editierbaren Truth-Doc-Standards der generierten Workflows
 - verwaltete Instruktionsblöcke für konfigurierte Plattformen wie `AGENTS.md`, `CLAUDE.md`, Copilot-Anweisungen und `GEMINI.md`
-- host-native Skills, Prompts oder Commands für Truth Structure, Truth Document, Truth Sync, Truth Realize und Truth Check
+- host-native Skills, Prompts oder Commands für Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize und Truth Check
+- projektbezogene schreibgeschützte Codex-, Claude-Code-, GitHub-Copilot- und OpenCode-Prüfer plus geleaste `truth-doc-writer`-Agenten, wo Hosts Agenten unterstützen, unter `.codex/agents/`, `.claude/agents/`, `.github/agents/` und `.opencode/agents/` für workflow-eigene Audits und vom Parent geleaste Dokument-Shards
 
 Die installierten Workflow-Flächen sind die Runtime:
 
 - Truth Structure erstellt oder repariert Area-Routing und erste Wahrheitsdokumente.
 - Truth Document erstellt oder repariert Wahrheitsdokumente für bereits implementiertes Verhalten.
 - Truth Sync hält zugeordnete Wahrheitsdokumente bei funktionalen Änderungen synchron.
+- Truth Preview zeigt wahrscheinliches Workflow-Routing vor Änderungen an, ohne Dateien zu schreiben.
 - Truth Realize aktualisiert Code so, dass er zu den Wahrheitsdokumenten passt.
 - Truth Check auditiert die Gesundheit der Repository-Wahrheit.
 
@@ -204,20 +242,33 @@ Generierte Flächen werden von Truthmark verwaltet, enthalten einen Versionsmark
 
 ## Befehle
 
-Truthmark V1 hält die CLI absichtlich klein, weil der laufende Workflow in den installierten Agenten-Flächen leben soll und nicht in einer langen Liste täglicher manueller Befehle. In nachgelagerten Repositories erzeugt `truthmark config` den in Git festgeschriebenen Hierarchievertrag, `truthmark init` installiert und aktualisiert Workflow-Flächen aus dieser geprüften Konfiguration, und `truthmark check` validiert Wahrheitsartefakte für manuelle Audits, CI oder Fehlersuche.
+Truthmark V1 hält die Terminal-CLI fokussiert. Die meisten menschlichen Nutzer brauchen nur Einrichtung, Aktualisierung und Validierung:
 
-```bash
-truthmark config
-truthmark init
-truthmark check
-truthmark config --json
-truthmark check --json
-```
+| Menschenorientierter CLI-Befehl | Zweck |
+| -------------------------------- | ----- |
+| `truthmark config` | Erstellt `.truthmark/config.yml`; schreibt nur diese Datei, außer `--stdout` wird verwendet. |
+| `truthmark init` | Installiert oder aktualisiert lokale Workflow-Dateien aus der geprüften Konfiguration. |
+| `truthmark check` | Validiert Konfiguration, Autorität, Routing, entscheidungstragende Dokumente, Frontmatter, interne Links, Branch-Scope und Coverage-Diagnostik. |
+
+Die übrigen CLI-Befehle sind optionale Repository-Intelligence-Helfer. Sie erzeugen abgeleiteten Review-Kontext für den aktiven Checkout; sie sind keine Quellen der Wahrheit:
 
-`config` schreibt nur `.truthmark/config.yml`, außer `--stdout` wird verwendet.
-`init` benötigt `.truthmark/config.yml` und installiert oder aktualisiert anschließend die lokalen Workflow-Dateien.
-`check` validiert Konfiguration, Autorität, Routing, entscheidungstragende Dokumente, Frontmatter, interne Links, Branch-Scope und Coverage-Diagnostik.
-Truth Structure, Truth Document, Truth Sync, Truth Realize und Truth Check sind installierte Agenten-Workflows, keine täglichen Top-Level-CLI-Befehle.
+| Optionaler CLI-Befehl | Zweck |
+| --------------------- | ----- |
+| `truthmark index` | Baut RepoIndex- und RouteMap-JSON für den aktiven Checkout. |
+| `truthmark impact --base <ref>` | Ordnet geänderte Dateien den gerouteten Truth-Dokumenten, zuständigen Routen, nahen Tests und öffentlichen Symbolen zu. |
+| `truthmark context --workflow <workflow> [--base <ref>]` | Erzeugt ein begrenztes ContextPack für Truth Sync, Truth Document oder Truth Realize. `--format markdown` rendert eine menschenlesbare Fassung. |
+
+Alle oben genannten CLI-Befehle unterstützen `--json`, wenn strukturierte Ausgabe für Automatisierung nützlich ist.
+
+Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize und Truth Check sind installierte Agenten-Workflows, keine täglichen Top-Level-CLI-Befehle.
+
+Sie laufen über die konfigurierten Agenten-Host-Flächen, zum Beispiel Codex/Claude/Copilot `/truthmark-*`, OpenCode `/skill truthmark-*` oder Gemini `/truthmark:*`.
+
+Diese Aufrufe wirken befehlsartig, weil Agenten-Hosts Skills über Slash-Commands bereitstellen. Behandle sie als Anweisungen an einen Agenten, nicht als Terminalbefehle, die Menschen ausführen sollen.
+
+```text
+/truthmark-check routing und truth-abdeckung vor der review prüfen
+```
 
 ## Warum es existiert
 
@@ -236,15 +287,20 @@ Es geht davon aus, dass ernsthafte Teams Folgendes brauchen:
 ## Projektstatus
 
 Truthmark ist kein Memory-Server und kein MCP-Server. Es ist eine Repository-Praxis, verpackt als kleiner CLI-Installer plus agent-native Workflow-Flächen, die KI-Workflow-Regeln in Repository-Infrastruktur verwandeln.
+
 V1 bietet derzeit:
 
 - `truthmark config`
 - `truthmark init`
 - `truthmark check`
+- `truthmark index`
+- `truthmark impact`
+- `truthmark context`
 - verwaltete `AGENTS.md`-Workflow-Anweisungen
-- generierte Skill-Flächen für Truth Structure, Truth Document, Truth Sync, Truth Realize und Truth Check für konfigurierte Agenten-Hosts
+- generierte Truth Structure-, Truth Document-, Truth Sync-, Truth Preview-, Truth Realize- und Truth Check-Skill-Flächen für konfigurierte Agenten-Hosts
 - Branch-Scope-Metadaten
-- Diagnostik für Konfiguration, Autorität, Routing, Entscheidungsstruktur, Frontmatter, Links und polyglotte Abdeckung
+- Diagnostik für Konfiguration, Autorität, Routing, Entscheidungsstruktur, Frontmatter, Links, Freshness und polyglotte Abdeckung
+- abgeleitete RepoIndex-, RouteMap-, ImpactSet- und ContextPack-Artefakte für schnellere lokale Prüfung, wenn die CLI verfügbar ist
 
 ## Dokumentation
 
@@ -252,10 +308,10 @@ Die Root-README ist für Menschen gedacht, die das Paket evaluieren und ausprobi
 
 - [Dokumentationsindex](docs/README.md)
 - [Architekturüberblick](docs/architecture/overview.md)
-- [API- und CLI-Verträge](docs/features/contracts.md)
-- [Init- und Scaffold-Verhalten](docs/features/init-and-scaffold.md)
-- [Check-Diagnostik](docs/features/check-diagnostics.md)
-- [Installierte Workflows](docs/features/installed-workflows.md)
+- [API- und CLI-Verträge](docs/truth/contracts.md)
+- [Init- und Scaffold-Verhalten](docs/truth/init-and-scaffold.md)
+- [Check-Diagnostik](docs/truth/check-diagnostics.md)
+- [Installierte Workflows](docs/truth/workflows/overview.md)
 - [Leitfaden zur Pflege von Repository-Wahrheit](docs/standards/maintaining-repository-truth.md)
 
 Aktuelles Verhalten gehört in den oben genannten kanonischen Dokumentationsbaum.

package/README.es.md

@@ -1,6 +1,6 @@
 # Truthmark
 
-**Truthmark automatiza el mantenimiento de la verdad para el desarrollo de software con IA.**
+**Truthmark instala flujos de verdad del repositorio para el desarrollo de software con IA.**
 
 [English](README.md) | [Deutsch](README.de.md) | [中文](README.zh.md) | Español | [Русский](README.ru.md)
 
@@ -8,14 +8,14 @@
 
 Los agentes de programación con IA ya escriben código rápido. La parte costosa es mantener alineada la verdad del repositorio con lo que realmente cambió.
 
-Truthmark añade una salvaguarda automática al cierre de ese flujo. El camino normal es simple:
+Truthmark añade una guarda de cierre basada en flujo de trabajo. El camino normal es simple:
 
 - el agente cambia código funcional
 - se ejecutan las pruebas relevantes
-- Truth Sync actualiza los documentos de verdad asignados antes de que el agente termine
+- el flujo instalado Truth Sync actualiza los documentos de verdad asignados antes de que el agente termine
 - se revisa el diff de documentos de verdad si se produjo uno
 
-La mayoría de las herramientas pide al equipo adoptar un hábito. Truthmark automatiza ese hábito.
+La mayoría de las herramientas pide al equipo adoptar un hábito. Truthmark convierte ese hábito en infraestructura de flujo del repositorio.
 
 Truthmark convierte un flujo de trabajo con IA en infraestructura del repositorio, no en tooling personal. Instala una capa de verdad nativa de Git y acotada a la rama dentro del propio repositorio, da a los agentes rutas explícitas y superficies de trabajo acotadas, y mantiene esa verdad revisable en Git en lugar de dispersarla por el historial de prompts, documentación obsoleta o estado privado de herramientas.
 
@@ -51,12 +51,12 @@ Para equipos que ya saben que los agentes pueden generar código, Truthmark resp
 
 Truthmark no intenta hacer que los agentes suenen más inteligentes. Intenta que los cambios de repositorio asistidos por IA sean más confiables.
 
-- La sincronización automática de la verdad tras cambios de código convierte el mantenimiento de documentación en una salvaguarda del flujo, no en un hábito del equipo.
+- El flujo instalado Truth Sync tras cambios de código convierte el mantenimiento de documentación en una salvaguarda del flujo, no en un hábito del equipo.
 - La verdad acotada a la rama viaja con el código, de modo que quienes revisan pueden inspeccionar la verdad actual en diffs normales de Git.
 - Las superficies de flujo nativas del repositorio hacen el despliegue más ligero y los traspasos más resistentes que una simple configuración por usuario.
 - El enrutamiento explícito en `docs/truthmark/areas.md` y en archivos de rutas secundarias delegadas da a los agentes límites de responsabilidad y rutas de escritura más seguras.
 - La operación local-first evita depender de un demonio, una base de datos, un servicio remoto o MCP.
-- El modelo funciona en bases de código JavaScript, TypeScript, Go, Python, C# y Java.
+- El modelo de enrutamiento es independiente del lenguaje, con diagnósticos de cobertura para superficies comunes de código JavaScript, TypeScript, Go, Python, C# y Java.
 
 Para responsables técnicos, el valor es gobernanza sin infraestructura extra: las pruebas, la revisión de código y la propiedad siguen haciendo el trabajo real; Truthmark vuelve el contexto del agente duradero, inspeccionable y acotado a la rama.
 
@@ -96,6 +96,7 @@ Truthmark convierte la verdad del repositorio en una superficie explícita de fl
 - `docs/truthmark/areas.md` y los archivos de rutas secundarias delegadas asignan áreas de código a los documentos que las gobiernan.
 - Truth Document genera o repara documentos de verdad canónica para comportamiento ya implementado cuando no hace falta cambiar código.
 - Truth Sync mantiene alineados los documentos de verdad asignados cuando hay cambios funcionales.
+- Truth Preview previsualiza el enrutamiento de flujo probable antes de editar, sin autorizar escrituras.
 - Truth Realize ofrece a los cambios que empiezan en documentación una ruta acotada para actualizar código.
 - `truthmark check` valida los artefactos de verdad resultantes.
 - Todo el modelo se mantiene local-first y nativo de Git.
@@ -132,17 +133,17 @@ Revisa `.truthmark/config.yml` antes de `init`; es el contrato de jerarquía con
 .truthmark/config.yml
 docs/truthmark/areas.md
 docs/truthmark/areas/repository.md
-docs/templates/feature-doc.md
-docs/features/README.md
-docs/features/repository/README.md
-docs/features/repository/overview.md
+docs/templates/behavior-doc.md
+docs/truth/README.md
+docs/truth/repository/README.md
+docs/truth/repository/overview.md
 AGENTS.md
 CLAUDE.md
 GEMINI.md
 ```
 
 Las plataformas compatibles son `codex`, `opencode`, `claude-code`, `github-copilot` y `gemini-cli`. La configuración predeterminada las incluye todas; elimina de `.truthmark/config.yml` las plataformas que no uses antes de volver a ejecutar `truthmark init`.
-La estructura generada por defecto usa los `README.md` de funciones como índices y empieza la verdad sobre el comportamiento actual en documentos hoja acotados, como `docs/features/repository/overview.md`.
+La estructura generada por defecto usa los `README.md` de verdad como índices y empieza la verdad sobre el comportamiento actual en documentos hoja acotados, como `docs/truth/repository/overview.md`.
 
 Los repositorios existentes suelen necesitar una pasada de limpieza después de `init`: ejecuta el flujo instalado Truth Structure cuando la ruta `repository` generada sea demasiado amplia, la propiedad abarque varios productos o servicios, o los archivos de rutas sigan apuntando a documentos de marcador de posición. Truth Structure divide rutas amplias, crea o repara documentos de verdad canónica iniciales y da a Truth Sync destinos precisos antes de que empiece el trabajo de código funcional. Codex, Claude Code y los IDEs de Copilot compatibles pueden invocarlo con `/truthmark-structure`; los hosts de estilo OpenCode pueden usar `/skill truthmark-structure`.
 
@@ -150,51 +151,88 @@ Los repositorios existentes suelen necesitar una pasada de limpieza después de
 
 Truthmark es más fuerte en el camino por defecto, no como un conjunto de comandos manuales. El agente que actúa y el entorno anfitrión deciden si delegan o ejecutan el flujo instalado en línea.
 
-Usa Truth Document cuando el comportamiento ya está implementado pero los documentos de verdad canónica faltan o son débiles. El agente lee implementación, pruebas, rutas y documentos existentes, escribe solo documentos de verdad y rutas, y no debe cambiar código funcional. Codex, Claude Code y los IDEs de Copilot compatibles pueden invocarlo con `/truthmark-document`; los hosts de estilo OpenCode pueden usar `/skill truthmark-document`.
+### Comportamiento existente sin docs
 
-La mayoría de los usuarios no debería invocar Truth Sync directamente. Lo importante es que Truth Sync actúe como salvaguarda automática al cierre cuando cambió código funcional. El flujo normal es:
+Usa esto cuando la implementación ya existe pero faltan o son débiles los documentos de verdad canónica:
+
+```text
+el usuario identifica un comportamiento implementado o un endpoint de api
+el usuario invoca explícitamente truth document
+el agente lee implementación, pruebas, rutas y docs existentes
+el agente solo escribe truth docs y rutas
+revisar el diff de truth docs
+```
+
+Truth Document es manual y con prioridad de implementación: el código sirve como evidencia, los documentos de verdad se crean o reparan, y no se debe cambiar código funcional. Codex, Claude Code y los IDEs de Copilot compatibles pueden invocarlo con `/truthmark-document`; los hosts de estilo OpenCode pueden usar `/skill truthmark-document`.
+
+```text
+/truthmark-document documenta el comportamiento implementado del timeout de sesión en docs/truth/authentication
+```
+
+### Cambios de código normales
+
+La mayoría de los usuarios no debería invocar Truth Sync directamente. Lo importante es que el flujo instalado del agente trate Truth Sync como una guarda de cierre cuando cambió código funcional. El flujo normal es:
 
 ```text
 el agente cambia código funcional
 se ejecutan las pruebas relevantes
-Truth Sync se dispara antes de que el agente termine
-se revisa el diff de documentos de verdad si se produjo uno
-se confirma o se entrega el trabajo
+el flujo instalado truth sync se ejecuta antes de que el agente termine
+revisar el diff de truth docs si se produjo uno
+confirmar o entregar el trabajo
 ```
 
-Truth Sync es code-first: el código lidera, los documentos de verdad siguen, y Truth Sync no debe reescribir código funcional. Su tarea principal es actuar como salvaguarda automática al cierre cuando cambió código funcional. La invocación directa se usa sobre todo para depurar, forzar una sincronización temprana antes de entregar el trabajo o ejecutar el flujo de forma intencional.
+Truth Sync es code-first: el código lidera, los documentos de verdad siguen, y Truth Sync no debe reescribir código funcional. Su tarea principal es ejecutarse mediante el flujo instalado del agente como guarda de cierre cuando cambió código funcional. La invocación directa se usa sobre todo para depurar, forzar una sincronización temprana antes de entregar el trabajo o ejecutar el flujo de forma intencional.
+
 Codex, Claude Code y los IDEs de Copilot compatibles pueden invocarlo con `/truthmark-sync`. Los hosts de estilo OpenCode pueden usar `/skill truthmark-sync`.
+
+```text
+/truthmark-sync sincroniza ahora la verdad del repositorio antes de la entrega
+```
+
+### Cambios doc-first
+
 Usa este flujo cuando una decisión de producto o arquitectura empieza en la documentación:
 
 ```text
-el usuario edita los documentos de verdad
-el usuario invoca explícitamente Truth Realize
-el agente lee los documentos de verdad y el código relevante
+el usuario edita truth docs
+el usuario invoca explícitamente truth realize
+el agente lee truth docs y el código relevante
 el agente actualiza solo el código
 se ejecutan las pruebas relevantes
-se confirma o se entrega el trabajo
+confirmar o entregar el trabajo
 ```
 
 Truth Realize es manual y doc-first: los documentos de verdad lideran, el código sigue, y el agente no debe editar los documentos de verdad que está realizando.
+
 Codex, Claude Code y los IDEs de Copilot compatibles pueden invocarlo con `/truthmark-realize`. Los hosts de estilo OpenCode pueden usar `/skill truthmark-realize`.
 
+```text
+/truthmark-realize realiza docs/truth/authentication/session-timeout.md como código
+```
+
 ## Qué instala
 
 Truthmark mantiene pequeña y nativa del repositorio la superficie duradera de flujo de trabajo. Después de `truthmark init`, el propio repositorio lleva el enrutamiento, las reglas y las superficies instaladas, así que el equipo no depende solo de la configuración local de una persona.
 
-- `.truthmark/config.yml` para configuración legible por máquina
-- `.truthmark/config.yml` para el contrato de jerarquía confirmado
+Truthmark instala dos superficies distintas:
+
+- comandos CLI orientados a personas, ejecutados por personas o CI para configurar el repositorio, refrescar archivos instalados, validar artefactos de verdad y generar opcionalmente contexto derivado para revisión
+- superficies de flujo de trabajo para agentes, invocadas por agentes de código u hosts de agentes durante flujos de implementación; no son comandos de terminal diarios adicionales para personas
+
+- `.truthmark/config.yml` para el contrato de jerarquía confirmado y legible por máquina
 - `docs/truthmark/areas.md` para el índice raíz de rutas
 - `docs/truthmark/areas/**/*.md` para archivos de rutas secundarias delegadas
-- `docs/templates/feature-doc.md` para el estándar editable de documentos de función usado por los flujos generados
+- `docs/templates/behavior-doc.md` y las demás plantillas específicas por tipo bajo `docs/templates/` para los estándares editables de truth docs usados por los flujos generados
 - bloques de instrucciones administrados para plataformas configuradas como `AGENTS.md`, `CLAUDE.md`, instrucciones de Copilot y `GEMINI.md`
-- skills, prompts o comandos nativos del host para Truth Structure, Truth Document, Truth Sync, Truth Realize y Truth Check
+- skills, prompts o comandos nativos del host para Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize y Truth Check
+- verificadores de solo lectura de Codex, Claude Code, GitHub Copilot y OpenCode con alcance de proyecto, más agentes `truth-doc-writer` con lease donde el host admite agentes, bajo `.codex/agents/`, `.claude/agents/`, `.github/agents/` y `.opencode/agents/` para auditorías propias del flujo y shards de documentación concedidos por el padre
 
 Las superficies de flujo de trabajo instaladas son el entorno de ejecución:
 
 - Truth Structure crea o repara el enrutamiento de áreas y documentos de verdad iniciales.
 - Truth Document crea o repara documentos de verdad para comportamiento ya implementado.
 - Truth Sync mantiene alineados los documentos de verdad asignados con los cambios funcionales.
+- Truth Preview previsualiza el enrutamiento de flujo probable antes de editar sin escribir archivos.
 - Truth Realize actualiza el código para que coincida con los documentos de verdad.
 - Truth Check audita la salud de la verdad del repositorio.
 
@@ -204,20 +242,33 @@ Las superficies generadas son administradas por Truthmark, incluyen un marcador
 
 ## Comandos
 
-Truthmark V1 mantiene la CLI pequeña a propósito porque el flujo continuo debe vivir en las superficies instaladas del agente, no en una lista larga de comandos manuales de uso diario. En repositorios derivados, `truthmark config` crea el contrato de jerarquía confirmado en Git, `truthmark init` instala y refresca superficies de flujo de trabajo a partir de esa configuración revisada, y `truthmark check` valida los artefactos de verdad para auditorías manuales, CI o depuración.
+Truthmark V1 mantiene enfocada la CLI de terminal. La mayoría de los usuarios humanos solo necesita configuración, actualización y validación:
 
-```bash
-truthmark config
-truthmark init
-truthmark check
-truthmark config --json
-truthmark check --json
-```
+| CLI orientada a personas | Uso |
+| ------------------------ | --- |
+| `truthmark config` | Crea `.truthmark/config.yml`; solo escribe ese archivo, salvo que se use `--stdout`. |
+| `truthmark init` | Instala o refresca los archivos locales de flujo de trabajo desde la configuración revisada. |
+| `truthmark check` | Valida configuración, autoridad, enrutamiento, documentos que contienen decisiones, frontmatter, enlaces internos, alcance de rama y diagnósticos de cobertura. |
+
+Los demás comandos CLI son ayudantes opcionales de inteligencia del repositorio. Generan contexto derivado para revisión sobre el checkout activo; no son fuentes de verdad:
 
-`config` solo escribe `.truthmark/config.yml`, salvo que se use `--stdout`.
-`init` requiere `.truthmark/config.yml` y luego instala o refresca los archivos locales de flujo de trabajo.
-`check` valida configuración, autoridad, enrutamiento, documentos que contienen decisiones, frontmatter, enlaces internos, alcance de rama y diagnósticos de cobertura.
-Truth Structure, Truth Document, Truth Sync, Truth Realize y Truth Check son flujos de trabajo instalados para agentes, no comandos CLI principales de uso diario.
+| CLI opcional | Uso |
+| ------------ | --- |
+| `truthmark index` | Construye JSON de RepoIndex y RouteMap para el checkout activo. |
+| `truthmark impact --base <ref>` | Mapea los archivos cambiados a truth docs enrutados, rutas propietarias, pruebas cercanas y símbolos públicos. |
+| `truthmark context --workflow <workflow> [--base <ref>]` | Genera un ContextPack acotado para Truth Sync, Truth Document o Truth Realize. `--format markdown` lo renderiza en un formato legible para personas. |
+
+Todos los comandos CLI anteriores admiten `--json` cuando la salida estructurada es útil para automatización.
+
+Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize y Truth Check son flujos de trabajo instalados para agentes, no comandos CLI principales de uso diario.
+
+Se ejecutan a través de las superficies configuradas del host agente, por ejemplo Codex/Claude/Copilot `/truthmark-*`, OpenCode `/skill truthmark-*` o Gemini `/truthmark:*`.
+
+Estas invocaciones parecen comandos porque los hosts de agentes exponen skills mediante slash commands. Trátalas como instrucciones para un agente, no como comandos de terminal que una persona deba ejecutar.
+
+```text
+/truthmark-check audita el enrutamiento y la cobertura de verdad antes de la revisión
+```
 
 ## Por qué existe
 
@@ -236,15 +287,20 @@ Asume que los equipos serios necesitan:
 ## Estado del proyecto
 
 Truthmark no es un servidor de memoria ni un servidor MCP. Es una práctica de repositorio empaquetada como un pequeño instalador CLI más superficies de flujo de trabajo nativas para agentes que convierten las reglas del flujo de IA en infraestructura del repositorio.
+
 V1 actualmente ofrece:
 
 - `truthmark config`
 - `truthmark init`
 - `truthmark check`
+- `truthmark index`
+- `truthmark impact`
+- `truthmark context`
 - instrucciones de flujo de trabajo administradas en `AGENTS.md`
-- superficies de skill generadas para Truth Structure, Truth Document, Truth Sync, Truth Realize y Truth Check en los anfitriones de agentes configurados
+- superficies de skill generadas para Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize y Truth Check en los anfitriones de agentes configurados
 - metadatos de alcance de rama
 - diagnósticos de configuración, autoridad, enrutamiento, estructura de decisiones, frontmatter, enlaces y cobertura políglota
+- artefactos derivados de RepoIndex, RouteMap, ImpactSet y ContextPack para una revisión local más rápida cuando la CLI está disponible
 
 ## Documentación
 
@@ -252,10 +308,10 @@ El README raíz es para personas que evalúan y prueban el paquete. Las especifi
 
 - [Índice de documentación](docs/README.md)
 - [Resumen de arquitectura](docs/architecture/overview.md)
-- [Contratos de API y CLI](docs/features/contracts.md)
-- [Comportamiento de init y scaffold](docs/features/init-and-scaffold.md)
-- [Diagnósticos de check](docs/features/check-diagnostics.md)
-- [Flujos de trabajo instalados](docs/features/installed-workflows.md)
+- [Contratos de API y CLI](docs/truth/contracts.md)
+- [Comportamiento de init y scaffold](docs/truth/init-and-scaffold.md)
+- [Diagnósticos de check](docs/truth/check-diagnostics.md)
+- [Flujos de trabajo instalados](docs/truth/workflows/overview.md)
 - [Guía para mantener la verdad del repositorio](docs/standards/maintaining-repository-truth.md)
 
 El comportamiento actual pertenece al árbol canónico de documentación anterior.