truthmark 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MerlinH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.de.md

@@ -0,0 +1,229 @@
+# Truthmark ist die Wahrheitsschicht 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.
+
+## Was Truthmark löst
+
+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:
+
+- 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.
+- 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.
+
+## Wo Truthmark hineinpasst
+
+Truthmark versucht nicht, jedes andere KI-Workflow-Tool zu ersetzen. Es sitzt in einer bestimmten Schicht des Stacks:
+
+| Wenn du brauchst                                                            | Beste Wahl                                  |
+| --------------------------------------------------------------------------- | ------------------------------------------- |
+| Bessere Ergebnisse aus einer einzelnen Coding-Sitzung                       | Bessere Prompts und enger gefasste Aufgaben |
+| Bequemlichkeit über Sitzungen hinweg für einen Agenten oder eine Person     | Speicherwerkzeuge                           |
+| Spec-first-Planung für neue Features                                        | Spezifikations-Tools wie Spec Kit           |
+| Branch-gebundene, prüfbare Repository-Wahrheit, die mit dem Code mitwandert | Truthmark                                   |
+
+Der Punkt ist nicht, dass Prompts, Memory oder Specs nutzlos wären. Der Punkt ist, dass keines davon allein Repository-Wahrheit in ein in Git festgeschriebenes, prüfbares Asset verwandelt, das Übergaben, Reviews und auseinanderlaufende Branches übersteht.
+
+## Inhalt
+
+- [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)
+- [Befehle](#befehle)
+- [Warum es existiert](#warum-es-existiert)
+- [Projektstatus](#projektstatus)
+- [Dokumentation](#dokumentation)
+- [Nicht-Ziele](#nicht-ziele)
+- [Lizenz](#lizenz)
+
+## Workflow-Fläche
+
+Truthmark macht Repository-Wahrheit zu einer expliziten Workflow-Fläche für Agenten:
+
+- `TRUTHMARK.md` definiert den branch-lokalen Workflow-Vertrag.
+- `docs/truthmark/areas.md` und delegierte untergeordnete Routendateien ordnen Codebereiche den Dokumenten zu, die sie verantworten.
+- 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.
+- Das gesamte Modell bleibt local-first und Git-nativ.
+
+Das ist das Kernversprechen: Agentenkontext wird zu festgeschriebenem Repository-Zustand statt zu einem privaten Sitzungsartefakt.
+
+## Erste Schritte
+
+Wenn du Truthmark zunächst gegen ein anderes lokales Repository ausprobieren willst, bevor das Paket anderswo veröffentlicht ist:
+
+```bash
+cd /path/to/truthmark
+npm install
+npm run build
+cd /path/to/your-repo
+node /path/to/truthmark/dist/main.js config
+node /path/to/truthmark/dist/main.js init
+node /path/to/truthmark/dist/main.js check
+```
+
+Prüfe `.truthmark/config.yml` vor `init`; es ist der in Git festgeschriebene Hierarchievertrag. Nach `init` solltest du die generierte Workflow-Fläche und die Routendateien prüfen, damit die gerouteten Dokumente zu den Dokumenten passen, die deinen Code tatsächlich verantworten:
+
+```text
+.truthmark/config.yml
+TRUTHMARK.md
+docs/truthmark/areas.md
+docs/truthmark/areas/repository.md
+docs/features/README.md
+docs/features/repository/README.md
+docs/features/repository/overview.md
+AGENTS.md
+CLAUDE.md
+skills/truthmark-structure/SKILL.md
+skills/truthmark-sync/SKILL.md
+skills/truthmark-realize/SKILL.md
+skills/truthmark-check/SKILL.md
+```
+
+Wenn du zusätzliche Plattformen in `.truthmark/config.yml` aktivierst, aktualisiert Truthmark die entsprechenden verwalteten Flächen beim nächsten `init`.
+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`.
+
+## 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:
+
+```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
+```
+
+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.
+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
+```
+
+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.
+
+## Was es installiert
+
+Truthmark hält die dauerhafte Workflow-Fläche klein:
+
+- `.truthmark/config.yml` für maschinenlesbare Konfiguration
+- `TRUTHMARK.md` für den branch-lokalen Workflow-Vertrag
+- `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
+
+Die installierten Workflow-Flächen sind die Runtime:
+
+- Truth Structure erstellt oder repariert Area-Routing und erste Wahrheitsdokumente.
+- 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.
+
+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.
+
+```bash
+truthmark config
+truthmark init
+truthmark check
+truthmark config --json
+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.
+
+## Warum es existiert
+
+Die meisten KI-Coding-Workflows optimieren für die nächste Antwort. Truthmark optimiert für die nächste Übergabe.
+Es geht davon aus, dass ernsthafte Teams Folgendes brauchen:
+
+- branch-spezifische Produktwahrheit
+- dauerhafte Architektur- und API-Entscheidungen
+- explizite Zuständigkeit zwischen Dokumentation und Code
+- sichere Schreibgrenzen für Agenten
+- normale Git-Diffs, die Menschen prüfen können
+- lesbares Markdown, das Teammitglieder ohne Spezialwerkzeuge inspizieren können
+- Wahrheit, die mit dem Branch mitwandert, statt in verborgenem Sitzungszustand zu leben
+- Workflows, die auch funktionieren, wenn das Paket nicht global installiert ist
+
+## 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.
+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
+- Branch-Scope-Metadaten
+- Diagnostik für Konfiguration, Autorität, Routing, Entscheidungsstruktur, Frontmatter, Links und polyglotte Abdeckung
+
+Es wird nicht angenommen, dass das ungescopte Paket `truthmark` bereits veröffentlicht ist.
+
+## Dokumentation
+
+Die Root-README ist für Menschen gedacht, die das Paket evaluieren und ausprobieren. Detaillierte funktionale und geschäftliche Spezifikationen liegen unter `docs/`:
+
+- [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)
+- [Leitfaden zur Pflege von Repository-Wahrheit](docs/standards/maintaining-repository-truth.md)
+
+Aktuelles Verhalten gehört in den oben genannten kanonischen Dokumentationsbaum.
+
+## Nicht-Ziele
+
+Truthmark V1 ist nicht:
+
+- ein gehosteter Dienst
+- ein MCP-Server
+- eine Vektordatenbank
+- ein Generator für Dokumentations-Websites
+- ein CI- oder PR-Enforcement-Produkt
+- ein Ersatz für Tests, Code Review oder technische Führung
+- eine autonome Code-Rewrite-Engine
+
+Es ist ein leichtgewichtiger Weg, lokale KI-Coding-Agenten dazu zu bringen, die Wahrheit zu respektieren, die dein Team in Git pflegt.
+
+## Lizenz
+
+MIT. Siehe [LICENSE](LICENSE).

package/README.es.md

@@ -0,0 +1,229 @@
+# Truthmark es la capa de 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.
+
+## Qué resuelve Truthmark
+
+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.
+- 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.
+
+## 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:
+
+| Si necesitas                                                                   | Mejor opción                                 |
+| ------------------------------------------------------------------------------ | -------------------------------------------- |
+| Mejores resultados en una sola sesión de programación                          | Mejores prompts y una tarea mejor delimitada |
+| Continuidad cómoda entre sesiones para un agente o una persona                 | Herramientas de memoria                      |
+| Planificación spec-first para nuevas funciones                                 | Herramientas de especificación como Spec Kit |
+| Verdad del repositorio, revisable y acotada a la rama, que viaja con el código | Truthmark                                    |
+
+La idea no es que los prompts, la memoria o las especificaciones no sirvan. La idea es que ninguno de ellos, por sí solo, convierte la verdad del repositorio en un activo confirmado en Git, inspeccionable y capaz de sobrevivir a traspasos, revisiones y divergencias entre ramas.
+
+## Contenido
+
+- [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)
+- [Comandos](#comandos)
+- [Por qué existe](#por-qué-existe)
+- [Estado del proyecto](#estado-del-proyecto)
+- [Documentación](#documentación)
+- [No objetivos](#no-objetivos)
+- [Licencia](#licencia)
+
+## Superficie de flujo
+
+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.
+- `docs/truthmark/areas.md` y los archivos de rutas secundarias delegadas asignan áreas de código a los documentos que las gobiernan.
+- 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.
+- Todo el modelo se mantiene local-first y nativo de Git.
+
+Esta es la promesa central: el contexto del agente pasa a ser estado confirmado del repositorio, no un artefacto privado de una sesión.
+
+## Primeros pasos
+
+Para probar Truthmark contra otro repositorio local antes de que el paquete se publique en otro lugar:
+
+```bash
+cd /path/to/truthmark
+npm install
+npm run build
+cd /path/to/your-repo
+node /path/to/truthmark/dist/main.js config
+node /path/to/truthmark/dist/main.js init
+node /path/to/truthmark/dist/main.js check
+```
+
+Revisa `.truthmark/config.yml` antes de `init`; es el contrato de jerarquía confirmado en el repositorio. Después de `init`, revisa la superficie de flujo de trabajo generada y los archivos de rutas para que los documentos enrutados coincidan con los documentos que realmente gobiernan tu código:
+
+```text
+.truthmark/config.yml
+TRUTHMARK.md
+docs/truthmark/areas.md
+docs/truthmark/areas/repository.md
+docs/features/README.md
+docs/features/repository/README.md
+docs/features/repository/overview.md
+AGENTS.md
+CLAUDE.md
+skills/truthmark-structure/SKILL.md
+skills/truthmark-sync/SKILL.md
+skills/truthmark-realize/SKILL.md
+skills/truthmark-check/SKILL.md
+```
+
+Si habilitas plataformas adicionales en `.truthmark/config.yml`, Truthmark actualizará las superficies administradas correspondientes en el siguiente `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`.
+
+## 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:
+
+```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
+```
+
+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`.
+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 agente actualiza solo el código
+se ejecutan las pruebas relevantes
+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`.
+
+## Qué instala
+
+Truthmark mantiene pequeña la superficie duradera de flujo de trabajo:
+
+- `.truthmark/config.yml` para configuración legible por máquina
+- `TRUTHMARK.md` para el contrato de flujo de trabajo local a la rama
+- `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
+
+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 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.
+
+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.
+
+```bash
+truthmark config
+truthmark init
+truthmark check
+truthmark config --json
+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.
+
+## Por qué existe
+
+La mayoría de los flujos de programación con IA optimizan la siguiente respuesta. Truthmark optimiza el siguiente traspaso.
+Asume que los equipos serios necesitan:
+
+- verdad de producto específica de cada rama
+- decisiones duraderas de arquitectura y API
+- propiedad explícita entre documentación y código
+- límites seguros de escritura para agentes
+- diffs normales de Git que humanos puedan revisar
+- Markdown legible que el equipo pueda inspeccionar sin herramientas especiales
+- verdad que viaje con la rama en lugar de vivir en estado oculto de sesión
+- flujos que sigan funcionando aunque el paquete no esté instalado globalmente
+
+## 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.
+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
+- metadatos de alcance de rama
+- diagnósticos de configuración, autoridad, enrutamiento, estructura de decisiones, frontmatter, enlaces y cobertura políglota
+
+No se debe asumir que el paquete sin scope `truthmark` ya está publicado.
+
+## Documentación
+
+El README raíz es para personas que evalúan y prueban el paquete. Las especificaciones funcionales y de negocio detalladas viven en `docs/`:
+
+- [Í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)
+- [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.
+
+## No objetivos
+
+Truthmark V1 no es:
+
+- un servicio alojado
+- un servidor MCP
+- una base de datos vectorial
+- un generador de sitios de documentación
+- un producto de enforcement para CI o PR
+- un sustituto de pruebas, revisión de código o liderazgo técnico
+- un motor autónomo de reescritura de código
+
+Es una forma ligera de hacer que los agentes locales de programación con IA respeten la verdad que tu equipo guarda en Git.
+
+## Licencia
+
+MIT. Consulta [LICENSE](LICENSE).