truthmark 1.2.1 → 1.2.3

package/README.de.md

@@ -1,31 +1,68 @@
-# Truthmark ist die Wahrheitsschicht für KI-Softwareentwicklung.
+# Truthmark
+
+**Truthmark automatisiert die Pflege von Repository-Wahrheit für KI-Softwareentwicklung.**
 
 [English](README.md) | Deutsch | [中文](README.zh.md) | [Español](README.es.md) | [Русский](README.ru.md)
 
-KI-Coding-Agenten können bereits gut Code schreiben. Womit sie weiterhin Schwierigkeiten haben: Produktabsicht, Architekturgrenzen und Zuständigkeiten im Repository zuverlässig aus veralteter Dokumentation, verstreuten Chats und flüchtigem Tool-Gedächtnis zu rekonstruieren.
-Truthmark löst das, indem es branch-lokale Repository-Wahrheit zu einer erstklassigen Laufzeitfläche für Agenten macht. Es installiert eine Git-native, branch-gebundene Wahrheitsschicht direkt im Repository, gibt Agenten explizite Routing- und Workflow-Grenzen und sorgt dafür, dass diese Wahrheit mit dem Code mitwandert, der tatsächlich ausgeliefert wird.
-Das ist kein besseres Prompt-Engineering. Es ist eine besser steuerbare Art, KI in einer echten Codebasis einzusetzen: weniger wiederholte Entscheidungen, weniger veraltete Dokumentation, sauberere Übergaben und KI-Coding-Sitzungen, die prüfbare Engineering-Aufzeichnungen hinterlassen, statt im Prompt-Verlauf oder in undurchsichtigen Tool-Zuständen zu verschwinden.
-Für Teams, die bereits wissen, dass Agenten Code erzeugen können, und jetzt wollen, dass das Repository selbst lesbar, prüfbar und steuerbar bleibt.
+<img src="docs/assets/truthmark-banner.png" alt="Truthmark-Banner" width="100%" />
 
-## Was Truthmark löst
+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:
+
+- Agent ändert funktionalen Code
+- relevante Tests laufen
+- Truth Sync 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.
+
+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.
+
+Das ist wichtig, weil der Workflow mit dem Branch lebt. Sobald ein Repository initialisiert ist, reisen Regeln, Routing und installierte Workflow-Flächen im Repository mit, sodass Zusammenarbeit und Übergaben weniger von der Rechnerkonfiguration einer einzelnen Person abhängen.
 
-KI-Coding ist heute leicht zu starten, aber teuer zu beherrschen. Sobald Agenten schnell Code schreiben können, wird Repository-Wahrheit zur Steuerfläche.
-Dieses Fehlermuster zeigt sich vorhersehbar: Anforderungen bleiben im Chat, Architekturentscheidungen werden wiederholt, Agenten bearbeiten die falschen Bereiche, und Branches erben Kontext, den Reviewer nicht zuverlässig prüfen können. Der Code kommt vielleicht schnell voran, aber dem Repository wird schwerer zu vertrauen.
-Truthmark verändert das Arbeitsmodell:
+Für Teams, die bereits wissen, dass Agenten Code erzeugen können, beantwortet Truthmark das nächste Problem: wie das Repository selbst lesbar, prüfbar und steuerbar bleibt, wenn KI-gestützte Arbeit skaliert.
 
-- Branch-lokale Wahrheit wandert mit dem Branch, statt in einem privaten Tool-Speicher zu liegen.
-- Git macht diese Wahrheit prüfbar, diffbar und im Team teilbar.
-- Dokumentation folgt dem Code, statt still in Fiktion abzudriften.
-- Routing bleibt in `docs/truthmark/areas.md` und delegierten untergeordneten Routendateien explizit, damit Agenten wissen, welche Dokumentation welchen Code verantwortet.
-- Aktive Produkt- und Architekturentscheidungen stehen in den kanonischen Dokumenten, die sie betreffen, nicht in zeitgestempelten Planungsprotokollen.
-- Local-first-Workflows vermeiden die Abhängigkeit von Daemon, Datenbank, Remote-Dienst oder MCP.
+## Visueller Überblick
+
+<table>
+	<tr>
+		<td align="center" width="50%">
+			<img src="docs/assets/truthmark-features.png" alt="Truthmark-Funktionen" width="100%" />
+			<br><strong>Funktionen</strong><br>
+			Was Truthmark installiert und wie sich die Workflow-Fläche aufteilt.
+		</td>
+		<td align="center" width="50%">
+			<img src="docs/assets/truthmark-position.png" alt="Truthmark-Positionierung" width="100%" />
+			<br><strong>Positionierung</strong><br>
+			Wo Truthmark im Verhältnis zu Prompts, Memory und Spec-Workflows steht.
+		</td>
+	</tr>
+	<tr>
+		<td align="center" colspan="2">
+			<img src="docs/assets/truthmark-syncflow.png" alt="Truthmark-Sync-Ablauf" width="100%" />
+			<br><strong>Sync-Ablauf</strong><br>
+			Wie Truth Sync normale Codeänderungen vor einer Übergabe abschließt.
+		</td>
+	</tr>
+</table>
+
+## Warum Teams es nutzen
+
+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.
+- 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.
 
-Für Tech Leads liegt der Wert in Governance ohne Theater: Tests, Code Review und Ownership leisten weiterhin die eigentliche Arbeit; Truthmark macht den Kontext des Agenten dauerhaft, prüfbar und branch-gebunden.
+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.
 
 ## Wo Truthmark hineinpasst
 
-Truthmark versucht nicht, jedes andere KI-Workflow-Tool zu ersetzen. Es sitzt in einer bestimmten Schicht des Stacks:
+Truthmark ist keine allgemeine KI-Produktivitätssuite. Es besetzt eine bestimmte Schicht im Stack: branch-gebundene, prüfbare Repository-Wahrheit, die mit der Implementierung synchron bleibt.
 
 | Wenn du brauchst                                                            | Beste Wahl                                  |
 | --------------------------------------------------------------------------- | ------------------------------------------- |
@@ -38,9 +75,9 @@ Der Punkt ist nicht, dass Prompts, Memory oder Specs nutzlos wären. Der Punkt i
 
 ## Inhalt
 
+- [Warum Teams es nutzen](#warum-teams-es-nutzen)
 - [Was Truthmark löst](#was-truthmark-löst)
 - [Wo Truthmark hineinpasst](#wo-truthmark-hineinpasst)
-- [Workflow-Fläche](#workflow-fläche)
 - [Erste Schritte](#erste-schritte)
 - [Wie es läuft](#wie-es-läuft)
 - [Was es installiert](#was-es-installiert)
@@ -51,12 +88,13 @@ Der Punkt ist nicht, dass Prompts, Memory oder Specs nutzlos wären. Der Punkt i
 - [Nicht-Ziele](#nicht-ziele)
 - [Lizenz](#lizenz)
 
-## Workflow-Fläche
+## Was Truthmark löst
 
 Truthmark macht Repository-Wahrheit zu einer expliziten Workflow-Fläche für Agenten:
 
-- `TRUTHMARK.md` definiert den branch-lokalen Workflow-Vertrag.
+- `.truthmark/config.yml` definiert den festgeschriebenen Hierarchievertrag.
 - `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 Realize gibt doc-first Änderungen einen begrenzten Pfad für Code-Updates.
 - `truthmark check` validiert die daraus entstehenden Wahrheitsartefakte.
@@ -92,33 +130,29 @@ Prüfe `.truthmark/config.yml` vor `init`; es ist der in Git festgeschriebene Hi
 
 ```text
 .truthmark/config.yml
-TRUTHMARK.md
 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
 AGENTS.md
 CLAUDE.md
-.codex/skills/truthmark-structure/SKILL.md
-.codex/skills/truthmark-sync/SKILL.md
-.codex/skills/truthmark-realize/SKILL.md
-.codex/skills/truthmark-check/SKILL.md
-.opencode/skills/truthmark-structure/SKILL.md
-.opencode/skills/truthmark-sync/SKILL.md
-.opencode/skills/truthmark-realize/SKILL.md
-.opencode/skills/truthmark-check/SKILL.md
+GEMINI.md
 ```
 
-Wenn du zusätzliche Plattformen in `.truthmark/config.yml` aktivierst, aktualisiert Truthmark die entsprechenden verwalteten Flächen beim nächsten `init`.
+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`.
 
-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-Nutzer können ihn mit `/truthmark-structure` oder `$truthmark-structure` aufrufen; Hosts im OpenCode-Stil können `/skill truthmark-structure` verwenden.
+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.
 
 ## Wie es läuft
 
-Truthmark legt nicht fest, welcher Subagent Truth Sync ausführen soll. Der handelnde Agent und die Host-Umgebung entscheiden, ob delegiert oder der Workflow inline ausgeführt wird.
-Die meisten Nutzer sollten Truth Sync nicht direkt aufrufen müssen. Der normale Ablauf ist:
+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.
+
+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:
 
 ```text
 Agent ändert funktionalen Code
@@ -129,7 +163,7 @@ 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 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.
-Codex-Nutzer können es mit `/truthmark-sync` oder `$truthmark-sync` aufrufen. Hosts im OpenCode-Stil können `/skill truthmark-sync` verwenden.
+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
@@ -142,33 +176,35 @@ 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-Nutzer können es mit `/truthmark-realize` oder `$truthmark-realize` aufrufen. Hosts im OpenCode-Stil können `/skill truthmark-realize` verwenden.
+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.
 
 ## Was es installiert
 
-Truthmark hält die dauerhafte Workflow-Fläche klein:
+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.md` für den branch-lokalen Workflow-Vertrag
+- `.truthmark/config.yml` für den festgeschriebenen Hierarchievertrag
 - `docs/truthmark/areas.md` für den Root-Routenindex
 - `docs/truthmark/areas/**/*.md` für delegierte untergeordnete Routendateien
-- verwaltete Instruktionsblöcke für konfigurierte Plattformen wie `AGENTS.md`, `CLAUDE.md`, Cursor-Regeln, Copilot-Anweisungen und `GEMINI.md`
-- Codex- und repo-lokale Skills für Truth Structure, Truth Sync, Truth Realize und Truth Check
+- `docs/templates/feature-doc.md` für den editierbaren Feature-Dokument-Standard 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
 
 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 Realize aktualisiert Code so, dass er zu den Wahrheitsdokumenten passt.
 - Truth Check auditiert die Gesundheit der Repository-Wahrheit.
 
-`README.md`-Dateien von Features sind Indizes. Truth Sync soll begrenzte Blattdokumente für aktuelles Verhalten lesen und aktualisieren.
+`README.md`-Dateien von Features sind Indizes. Truth Sync soll begrenzte Blattdokumente für aktuelles Verhalten lesen und aktualisieren. Generierte Workflow-Flächen bewahren die Autorität der Repository-Regeln, während sie Implementierungscode und kanonische Wahrheitsdokumente als Belege für aktuelles Verhalten behandeln.
 
 Generierte Flächen werden von Truthmark verwaltet, enthalten einen Versionsmarker und können mit `truthmark init` aktualisiert werden.
 
 ## Befehle
 
-Truthmark V1 hält die CLI absichtlich klein. 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 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.
 
 ```bash
 truthmark config
@@ -181,7 +217,7 @@ truthmark check --json
 `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 Sync, Truth Realize und Truth Check sind installierte Agenten-Workflows, keine täglichen Top-Level-CLI-Befehle.
+Truth Structure, Truth Document, Truth Sync, Truth Realize und Truth Check sind installierte Agenten-Workflows, keine täglichen Top-Level-CLI-Befehle.
 
 ## Warum es existiert
 
@@ -199,14 +235,14 @@ 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.
+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`
 - verwaltete `AGENTS.md`-Workflow-Anweisungen
-- generierte Skill-Flächen für Truth Structure, Truth Sync, Truth Realize und Truth Check für konfigurierte Agenten-Hosts
+- generierte Skill-Flächen für Truth Structure, Truth Document, Truth Sync, Truth Realize und Truth Check für konfigurierte Agenten-Hosts
 - Branch-Scope-Metadaten
 - Diagnostik für Konfiguration, Autorität, Routing, Entscheidungsstruktur, Frontmatter, Links und polyglotte Abdeckung
 

package/README.es.md

@@ -1,31 +1,68 @@
-# Truthmark es la capa de verdad para el desarrollo de software con IA.
+# Truthmark
+
+**Truthmark automatiza el mantenimiento de la verdad para el desarrollo de software con IA.**
 
 [English](README.md) | [Deutsch](README.de.md) | [中文](README.zh.md) | Español | [Русский](README.ru.md)
 
-Los agentes de programación con IA ya escriben código bastante bien. Lo que todavía hacen mal es reconstruir de forma fiable la intención del producto, los límites de arquitectura y la responsabilidad sobre cada parte del repositorio a partir de documentación obsoleta, conversaciones dispersas y memoria temporal de herramientas.
+<img src="docs/assets/truthmark-banner.png" alt="Banner de Truthmark" width="100%" />
 
-## Qué resuelve Truthmark
+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:
+
+- 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
+- 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.
+
+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.
+
+Eso importa porque el flujo vive con la rama. Una vez inicializado un repositorio, las reglas, el enrutamiento y las superficies instaladas viajan dentro del repo, así que la colaboración y los traspasos dependen menos de la configuración local de una sola persona.
+
+Para equipos que ya saben que los agentes pueden generar código, Truthmark responde al siguiente problema: cómo hacer que el repositorio siga siendo legible, revisable y gobernable a medida que crece el trabajo asistido por IA.
 
-Truthmark lo resuelve convirtiendo la verdad local de cada rama en una superficie de ejecución de primera clase para los agentes. Instala una capa de verdad nativa de Git, acotada a la rama, directamente dentro del repositorio; da a los agentes rutas y límites de flujo de trabajo explícitos; y hace que esa verdad viaje con el código que realmente se entrega.
-Esto no es mejor ingeniería de prompts. Es una forma más gobernable de usar IA en una base de código real: menos decisiones repetidas, menos documentación obsoleta, traspasos más limpios y sesiones de programación con IA que dejan registros de ingeniería revisables en lugar de desaparecer en el historial de prompts o en estados opacos de herramientas.
-Está pensado para equipos que ya saben que los agentes pueden generar código y ahora necesitan que el repositorio siga siendo legible, revisable y gobernable.
-Empezar a programar con IA ya es fácil; gobernarlo es lo costoso. Cuando los agentes pueden escribir código rápido, la verdad del repositorio se convierte en la superficie de control.
-Ese fallo aparece de forma predecible: los requisitos se quedan en chats, las decisiones de arquitectura se repiten, los agentes tocan las zonas equivocadas y las ramas heredan contexto que los revisores no pueden inspeccionar con confianza. El código puede avanzar rápido, pero el repositorio se vuelve más difícil de confiar.
-Truthmark cambia el modelo de trabajo:
-
-- La verdad local de la rama viaja con la rama, en lugar de vivir en un almacén privado de herramientas.
-- Git hace que esa verdad sea revisable, comparable y compartible con el equipo.
-- La documentación sigue al código en lugar de derivar silenciosamente hacia la ficción.
-- El enrutamiento permanece explícito en `docs/truthmark/areas.md` y en archivos de rutas secundarias delegadas, para que los agentes sepan qué documentación gobierna qué código.
-- Las decisiones activas de producto y arquitectura viven en los documentos canónicos que gobiernan, no en registros de planificación con marca de tiempo.
-- Los flujos de trabajo locales evitan depender de un demonio, una base de datos, un servicio remoto o MCP.
+## Resumen visual
+
+<table>
+	<tr>
+		<td align="center" width="50%">
+			<img src="docs/assets/truthmark-features.png" alt="Características de Truthmark" width="100%" />
+			<br><strong>Características</strong><br>
+			Lo que instala Truthmark y cómo se divide la superficie de trabajo.
+		</td>
+		<td align="center" width="50%">
+			<img src="docs/assets/truthmark-position.png" alt="Posicionamiento de Truthmark" width="100%" />
+			<br><strong>Posicionamiento</strong><br>
+			Dónde encaja Truthmark frente a prompts, memoria y flujos spec-first.
+		</td>
+	</tr>
+	<tr>
+		<td align="center" colspan="2">
+			<img src="docs/assets/truthmark-syncflow.png" alt="Flujo de sync de Truthmark" width="100%" />
+			<br><strong>Flujo de sync</strong><br>
+			Cómo Truth Sync cierra cambios normales de código antes del traspaso.
+		</td>
+	</tr>
+</table>
+
+## Por qué los equipos lo adoptan
+
+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.
+- 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.
 
-Para responsables técnicos, el valor es gobernanza sin teatro: 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.
+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.
 
 ## Dónde encaja Truthmark
 
-Truthmark no intenta reemplazar todas las demás herramientas de flujo de trabajo con IA. Ocupa una capa concreta de la pila:
+Truthmark no es una suite general de productividad para IA. Ocupa una capa concreta de la pila: verdad de repositorio revisable, acotada a la rama y alineada con la implementación.
 
 | Si necesitas                                                                   | Mejor opción                                 |
 | ------------------------------------------------------------------------------ | -------------------------------------------- |
@@ -38,9 +75,9 @@ La idea no es que los prompts, la memoria o las especificaciones no sirvan. La i
 
 ## Contenido
 
+- [Por qué los equipos lo adoptan](#por-qué-los-equipos-lo-adoptan)
 - [Qué resuelve Truthmark](#qué-resuelve-truthmark)
 - [Dónde encaja Truthmark](#dónde-encaja-truthmark)
-- [Superficie de flujo](#superficie-de-flujo)
 - [Primeros pasos](#primeros-pasos)
 - [Cómo se ejecuta](#cómo-se-ejecuta)
 - [Qué instala](#qué-instala)
@@ -51,12 +88,13 @@ La idea no es que los prompts, la memoria o las especificaciones no sirvan. La i
 - [No objetivos](#no-objetivos)
 - [Licencia](#licencia)
 
-## Superficie de flujo
+## Qué resuelve Truthmark
 
 Truthmark convierte la verdad del repositorio en una superficie explícita de flujo de trabajo para agentes:
 
-- `TRUTHMARK.md` define el contrato de flujo de trabajo local a la rama.
+- `.truthmark/config.yml` define el contrato de jerarquía confirmado en el repositorio.
 - `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 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.
@@ -92,33 +130,29 @@ Revisa `.truthmark/config.yml` antes de `init`; es el contrato de jerarquía con
 
 ```text
 .truthmark/config.yml
-TRUTHMARK.md
 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
 AGENTS.md
 CLAUDE.md
-.codex/skills/truthmark-structure/SKILL.md
-.codex/skills/truthmark-sync/SKILL.md
-.codex/skills/truthmark-realize/SKILL.md
-.codex/skills/truthmark-check/SKILL.md
-.opencode/skills/truthmark-structure/SKILL.md
-.opencode/skills/truthmark-sync/SKILL.md
-.opencode/skills/truthmark-realize/SKILL.md
-.opencode/skills/truthmark-check/SKILL.md
+GEMINI.md
 ```
 
-Si habilitas plataformas adicionales en `.truthmark/config.yml`, Truthmark actualizará las superficies administradas correspondientes en el siguiente `init`.
+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`.
 
-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. Los usuarios de Codex pueden invocarlo con `/truthmark-structure` o `$truthmark-structure`; los hosts de estilo OpenCode pueden usar `/skill truthmark-structure`.
+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`.
 
 ## Cómo se ejecuta
 
-Truthmark no especifica qué subagente debe ejecutar Truth Sync. El agente que actúa y el entorno anfitrión deciden si delegan o ejecutan el flujo en línea.
-La mayoría de los usuarios no debería invocar Truth Sync directamente. El flujo normal es:
+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`.
+
+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:
 
 ```text
 el agente cambia código funcional
@@ -129,7 +163,7 @@ se confirma o se entrega 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.
-Los usuarios de Codex pueden invocarlo con `/truthmark-sync` o `$truthmark-sync`. Los hosts de estilo OpenCode pueden usar `/skill truthmark-sync`.
+Codex, Claude Code y los IDEs de Copilot compatibles pueden invocarlo con `/truthmark-sync`. Los hosts de estilo OpenCode pueden usar `/skill truthmark-sync`.
 Usa este flujo cuando una decisión de producto o arquitectura empieza en la documentación:
 
 ```text
@@ -142,33 +176,35 @@ se confirma o se entrega 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.
-Los usuarios de Codex pueden invocarlo con `/truthmark-realize` o `$truthmark-realize`. Los hosts de estilo OpenCode pueden usar `/skill truthmark-realize`.
+Codex, Claude Code y los IDEs de Copilot compatibles pueden invocarlo con `/truthmark-realize`. Los hosts de estilo OpenCode pueden usar `/skill truthmark-realize`.
 
 ## Qué instala
 
-Truthmark mantiene pequeña la superficie duradera de flujo de trabajo:
+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.md` para el contrato de flujo de trabajo local a la rama
+- `.truthmark/config.yml` para el contrato de jerarquía confirmado
 - `docs/truthmark/areas.md` para el índice raíz de rutas
 - `docs/truthmark/areas/**/*.md` para archivos de rutas secundarias delegadas
-- bloques de instrucciones administrados para plataformas configuradas como `AGENTS.md`, `CLAUDE.md`, reglas de Cursor, instrucciones de Copilot y `GEMINI.md`
-- skills locales del repositorio y de Codex para Truth Structure, Truth Sync, Truth Realize y Truth Check
+- `docs/templates/feature-doc.md` para el estándar editable de documentos de función usado 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
 
 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 Realize actualiza el código para que coincida con los documentos de verdad.
 - Truth Check audita la salud de la verdad del repositorio.
 
-Los `README.md` de funciones son índices. Se espera que Truth Sync lea y actualice documentos hoja acotados para el comportamiento actual.
+Los `README.md` de funciones son índices. Se espera que Truth Sync lea y actualice documentos hoja acotados para el comportamiento actual. Las superficies de flujo generadas preservan la autoridad de las reglas del repositorio mientras tratan el código de implementación y los documentos canónicos de verdad como evidencia del comportamiento actual.
 
 Las superficies generadas son administradas por Truthmark, incluyen un marcador de versión y pueden refrescarse con `truthmark init`.
 
 ## Comandos
 
-Truthmark V1 mantiene la CLI pequeña a propósito. 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 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.
 
 ```bash
 truthmark config
@@ -181,7 +217,7 @@ truthmark check --json
 `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 Sync, Truth Realize y Truth Check son flujos de trabajo instalados para agentes, no comandos CLI principales de uso diario.
+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.
 
 ## Por qué existe
 
@@ -199,14 +235,14 @@ 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.
+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`
 - instrucciones de flujo de trabajo administradas en `AGENTS.md`
-- superficies de skill generadas para Truth Structure, 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 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