truthmark 1.2.2 → 1.3.0

package/README.es.md

@@ -1,31 +1,68 @@
-# Truthmark es la capa de verdad para el desarrollo de software con IA.
+# Truthmark
+
+**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)
 
-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 guarda de cierre basada en flujo de trabajo. El camino normal es simple:
+
+- el agente cambia código funcional
+- se ejecutan las pruebas relevantes
+- 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 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.
+
+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.
+
+## 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 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:
+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 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.
+- 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 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 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,88 +130,145 @@ 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/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`.
 
 ## 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.
+
+### Comportamiento existente sin docs
+
+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 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 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/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 Sync, Truth Realize y Truth Check
+- 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, `truthmark check` valida los artefactos de verdad para auditorías manuales, CI o depuración, y los comandos de inteligencia del repositorio generan artefactos derivados de revisión cuando hay herramientas locales disponibles.
 
 ```bash
 truthmark config
 truthmark init
 truthmark check
+truthmark index
+truthmark impact --base main
+truthmark context --workflow truth-sync --base main
 truthmark config --json
 truthmark check --json
+truthmark index --json
+truthmark impact --base main --json
+truthmark context --workflow truth-sync --base main --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.
+
+`index` construye JSON de RepoIndex y RouteMap para el checkout activo.
+
+`impact --base <ref>` mapea los archivos cambiados a los truth docs enrutados, rutas propietarias, pruebas cercanas y símbolos públicos.
+
+`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.
+
+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.
+
+Se ejecutan a través de las superficies configuradas del host agente, por ejemplo Codex/Claude/Copilot `/truthmark-*`, OpenCode `/skill truthmark-*` o Gemini `/truthmark:*`.
+
+```text
+/truthmark-check audita el enrutamiento y la cobertura de verdad antes de la revisión
+```
 
 ## Por qué existe
 
@@ -191,16 +286,21 @@ 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`
+- `truthmark index`
+- `truthmark impact`
+- `truthmark context`
 - 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
+- artefactos derivados de RepoIndex, RouteMap, ImpactSet y ContextPack para una revisión local más rápida cuando la CLI está disponible
 
 ## Documentación
 
@@ -208,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.

package/README.md

@@ -1,40 +1,68 @@
 # Truthmark
 
-**Truthmark is the truth layer for AI software development.**
+**Truthmark installs repository truth workflows for AI software development.**
 
 English | [Deutsch](README.de.md) | [中文](README.zh.md) | [Español](README.es.md) | [Русский](README.ru.md)
 
-![Truthmark overview](docs/assets/truthmark-overview.png)
+<img src="docs/assets/truthmark-banner.png" alt="Truthmark banner" width="100%" />
 
-AI coding agents are already good at writing code. They are still bad at reliably reconstructing product intent, architecture boundaries, and repository ownership from stale docs, scattered chats, and ephemeral tool memory.
+AI coding agents already write code fast. The expensive part is keeping repository truth aligned with what changed.
 
-Truthmark fixes that by turning branch-local repository truth into a first-class runtime surface for agents. It installs a Git-native, branch-scoped truth layer directly inside the repo, gives agents explicit routing and workflow boundaries, and makes that truth move with the code that actually ships.
+Truthmark adds a finish-time workflow guard to that workflow. The normal path is simple:
 
-This is not better prompt engineering. It is a more governable way to use AI in a real codebase: fewer repeated decisions, fewer stale docs, cleaner handoffs, and AI coding sessions that leave behind reviewable engineering records instead of disappearing into prompt history or opaque tool state.
+- agent changes functional code
+- run relevant tests
+- the installed Truth Sync workflow updates mapped truth docs before the agent finishes
+- review the truth-doc diff if one was produced
 
-For teams who already know agents can generate code, and now need the repository itself to stay legible, reviewable, and governable.
+Most tools ask teams to adopt a habit. Truthmark turns the habit into repository workflow infrastructure.
 
-## Why teams try it
+Truthmark turns an AI workflow into repo infrastructure, not personal tooling. It installs a Git-native, branch-scoped truth layer inside the repository, gives agents explicit routing and bounded workflow surfaces, and keeps that truth reviewable in Git instead of scattering it across prompt history, stale docs, or private tool memory.
 
-AI coding is now easy to start and expensive to govern. Once agents can write code quickly, repository truth becomes the control surface.
+That matters because the workflow lives with the branch. Once a repository is initialized, the rules, routing, and installed workflow surfaces travel in-repo, so collaboration and handoffs are less dependent on one person's machine setup.
 
-That failure mode shows up in predictable ways: requirements live in chat, architecture decisions get repeated, agents touch the wrong surfaces, and branches inherit context that reviewers cannot reliably inspect. The code may move fast, but the repository gets harder to trust.
+For teams who already know agents can generate code, Truthmark answers the next problem: how to keep the repository itself legible, reviewable, and governable as AI-assisted work scales.
 
-Truthmark changes the working model:
+## Visual overview
 
-- Branch-local truth travels with the branch instead of living in a private tool store.
-- Git makes that truth reviewable, diffable, and shareable across the team.
-- Docs follow code instead of drifting quietly into fiction.
-- Routing stays explicit in `docs/truthmark/areas.md` and delegated child route files so agents know which docs own which code.
-- Active product and architecture decisions live in the canonical docs they govern instead of in timestamped planning logs.
-- Local-first workflows avoid a daemon, database, remote service, or MCP dependency.
-- The model works across JavaScript, TypeScript, Go, Python, C#, and Java codebases.
+<table>
+  <tr>
+    <td align="center" width="50%">
+      <img src="docs/assets/truthmark-features.png" alt="Truthmark features" width="100%" />
+      <br><strong>Features</strong><br>
+      What Truthmark installs and how the workflow surface is split.
+    </td>
+    <td align="center" width="50%">
+      <img src="docs/assets/truthmark-position.png" alt="Truthmark position" width="100%" />
+      <br><strong>Position</strong><br>
+      Where Truthmark fits relative to prompts, memory, and spec workflows.
+    </td>
+  </tr>
+  <tr>
+    <td align="center" colspan="2">
+      <img src="docs/assets/truthmark-syncflow.png" alt="Truthmark sync flow" width="100%" />
+      <br><strong>Sync flow</strong><br>
+      How Truth Sync closes out normal code changes before handoff.
+    </td>
+  </tr>
+</table>
 
-For tech leads, the value is governance without theater: tests, code review, and ownership still do the real work; Truthmark makes the agent's context durable, inspectable, and branch-scoped.
+## Why teams adopt it
+
+Truthmark is not trying to make agents sound smarter. It is trying to make AI-assisted repository change easier to trust.
+
+- Installed Truth Sync after code changes turns documentation maintenance into a workflow safeguard instead of a team habit.
+- Branch-scoped truth moves with the code, so reviewers can inspect current truth in ordinary Git diffs.
+- Repository-native workflow surfaces make rollout lighter and handoffs more resilient than per-user setup alone.
+- Explicit routing in `docs/truthmark/areas.md` and delegated child route files gives agents ownership boundaries and safer write paths.
+- Local-first operation avoids a daemon, database, remote service, or MCP dependency.
+- The routing model is language-agnostic, with coverage diagnostics for common JavaScript, TypeScript, Go, Python, C#, and Java code surfaces.
+
+For tech leads, the value is governance without extra infrastructure: tests, code review, and ownership still do the real work; Truthmark makes the agent's context durable, inspectable, and branch-scoped.
 
 ## Where Truthmark fits
 
-Truthmark is not trying to replace every other AI workflow tool. It sits in a specific layer of the stack:
+Truthmark is not a general AI productivity suite. It occupies a specific layer of the stack: branch-scoped, reviewable repository truth that stays aligned with implementation.
 
 | If you need                                                           | Best fit                                |
 | --------------------------------------------------------------------- | --------------------------------------- |
@@ -47,6 +75,7 @@ The point is not that prompts, memory, or specs are useless. The point is that n
 
 ## Table of Contents
 
+- [Why teams adopt it](#why-teams-adopt-it)
 - [What Truthmark solves](#what-truthmark-solves)
 - [Where Truthmark fits](#where-truthmark-fits)
 - [Get started](#get-started)
@@ -63,8 +92,9 @@ The point is not that prompts, memory, or specs are useless. The point is that n
 
 Truthmark turns repository truth into an explicit workflow surface for agents:
 
-- `TRUTHMARK.md` defines the branch-local workflow contract.
+- `.truthmark/config.yml` defines the committed hierarchy contract.
 - `docs/truthmark/areas.md` and delegated child route files map code areas to the docs that own them.
+- Truth Document generates or repairs canonical truth docs for existing implemented behavior when no code change is needed.
 - Truth Sync keeps mapped truth docs aligned with functional changes.
 - Truth Realize gives doc-first changes a bounded code-update path.
 - `truthmark check` validates the resulting truth artifacts.
@@ -101,42 +131,69 @@ Review `.truthmark/config.yml` before `init`; it is the committed hierarchy cont
 
 ```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
+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
 ```
 
 Supported platforms are `codex`, `opencode`, `claude-code`, `github-copilot`, and `gemini-cli`. The default config includes all of them; remove platforms you do not use from `.truthmark/config.yml` before rerunning `truthmark init`.
 
-The default scaffold keeps feature `README.md` files as indexes and starts current behavior truth in bounded leaf docs such as `docs/features/repository/overview.md`.
+The default scaffold keeps truth `README.md` files as indexes and starts current behavior truth in bounded leaf docs such as `docs/truth/repository/overview.md`.
 
 Existing repositories usually need one cleanup pass after `init`: run the installed Truth Structure workflow when the generated `repository` route is too broad, ownership spans multiple products or services, or route files still point at placeholder docs. Truth Structure splits broad routing, creates or repairs starter canonical truth docs, and gives Truth Sync precise destinations before functional-code work begins. Codex, Claude Code, and supported Copilot IDEs can invoke it with `/truthmark-structure`; OpenCode-style hosts can invoke `/skill truthmark-structure`.
 
+```text
+/truthmark-structure split the broad repository area into auth, billing, and notifications
+```
+
 ## How it runs
 
-Truthmark does not specify which subagent should run Truth Sync. The acting agent and host environment decide whether to delegate or run the workflow inline.
+Truthmark is strongest on the default path, not as a pile of manual commands. The acting agent and host environment decide whether to delegate or run the installed workflow inline.
+
+### Existing behavior without docs
+
+Use this when implementation already exists but the canonical truth docs are missing or weak:
+
+```text
+user identifies an implemented behavior or API endpoint
+user explicitly invokes Truth Document
+agent reads implementation, tests, routing, and existing docs
+agent writes truth docs and routing only
+review the truth-doc diff
+```
+
+Truth Document is manual and implementation-first: code is inspected as evidence, truth docs are created or repaired, and functional code must not be changed. Codex, Claude Code, and supported Copilot IDEs can invoke it with `/truthmark-document`. OpenCode-style hosts can invoke `/skill truthmark-document`.
+
+```text
+/truthmark-document document the implemented session timeout behavior under docs/truth/authentication
+```
 
 ### Normal code changes
 
-Most users should not need to invoke Truth Sync directly. The normal path is:
+Most users should not need to invoke Truth Sync directly. The important behavior is that the installed agent workflow treats Truth Sync as a finish-time guard when functional code changed. The normal path is:
 
 ```text
 agent changes functional code
 run relevant tests
-Truth Sync triggers before the agent finishes
+the installed Truth Sync workflow runs before the agent finishes
 review the truth-doc diff if one was produced
 commit or hand off the work
 ```
 
-Truth Sync is code-first: code leads, truth docs follow, and Truth Sync must not rewrite functional code. Its main job is to act as an automatic finish-time safeguard when functional code changed. Direct invocation is mainly for troubleshooting, forcing an early sync before handoff, or running the workflow intentionally.
+Truth Sync is code-first: code leads, truth docs follow, and Truth Sync must not rewrite functional code. Its main job is to run through the installed agent workflow as a finish-time guard when functional code changed. Direct invocation is mainly for troubleshooting, forcing an early sync before handoff, or running the workflow intentionally.
 
 Codex, Claude Code, and supported Copilot IDEs can invoke it with `/truthmark-sync`. OpenCode-style hosts can invoke `/skill truthmark-sync`.
 
+```text
+/truthmark-sync sync the repository truth now before handoff
+```
+
 ### Doc-first changes
 
 Use this when a product or architecture decision starts in docs:
@@ -154,38 +211,49 @@ Truth Realize is manual and doc-first: truth docs lead, code follows, and the ag
 
 Codex, Claude Code, and supported Copilot IDEs can invoke it with `/truthmark-realize`. OpenCode-style hosts can invoke `/skill truthmark-realize`.
 
+```text
+/truthmark-realize realize docs/truth/authentication/session-timeout.md into code
+```
+
 ## What it installs
 
-Truthmark keeps the durable workflow surface small:
+Truthmark keeps the durable workflow surface small and repository-native. After `truthmark init`, the repo itself carries the routing, rules, and installed workflow surfaces, so teams are not relying only on one operator's local setup.
 
-- `.truthmark/config.yml` for machine-readable configuration
-- `TRUTHMARK.md` for the branch-local workflow contract
+- `.truthmark/config.yml` for the machine-readable committed hierarchy contract
 - `docs/truthmark/areas.md` for the root route index
 - `docs/truthmark/areas/**/*.md` for delegated child route files
+- `docs/templates/behavior-doc.md` plus the other kind-specific templates under `docs/templates/` for the editable truth-doc standards used by generated workflows
 - managed instruction blocks for configured platforms such as `AGENTS.md`, `CLAUDE.md`, Copilot instructions, and `GEMINI.md`
-- host-native skills, prompts, or commands for Truth Structure, Truth Sync, Truth Realize, and Truth Check
+- host-native skills, prompts, or commands for Truth Structure, Truth Document, Truth Sync, Truth Realize, and Truth Check
 
 The installed workflow surfaces are the runtime:
 
 - Truth Structure creates or repairs area routing and starter truth docs.
+- Truth Document creates or repairs truth docs for existing implemented behavior.
 - Truth Sync keeps mapped truth docs aligned with functional changes.
 - Truth Realize updates code to match truth docs.
 - Truth Check audits repository truth health.
 
-Feature `README.md` files are indexes. Truth Sync is expected to read and update bounded leaf docs for current behavior.
+Truth `README.md` files are indexes. Truth Sync is expected to read and update bounded leaf docs for current behavior. Generated workflow surfaces preserve repository-rule authority while treating implementation code and canonical truth docs as evidence for current behavior.
 
 Generated surfaces are managed by Truthmark, include a version marker, and may be refreshed by `truthmark init`.
 
 ## Commands
 
-Truthmark V1 intentionally keeps the CLI small. In downstream repositories, `truthmark config` creates the committed hierarchy contract, `truthmark init` installs and refreshes workflow surfaces from that reviewed config, and `truthmark check` validates truth artifacts for manual audits, CI, or troubleshooting.
+Truthmark V1 keeps the CLI focused because the ongoing workflow is meant to live in the installed agent surfaces, not in a long list of daily manual commands. In downstream repositories, `truthmark config` creates the committed hierarchy contract, `truthmark init` installs and refreshes workflow surfaces from that reviewed config, `truthmark check` validates truth artifacts for manual audits, CI, or troubleshooting, and the repository-intelligence commands generate derived review artifacts when local tooling is available.
 
 ```bash
 truthmark config
 truthmark init
 truthmark check
+truthmark index
+truthmark impact --base main
+truthmark context --workflow truth-sync --base main
 truthmark config --json
 truthmark check --json
+truthmark index --json
+truthmark impact --base main --json
+truthmark context --workflow truth-sync --base main --json
 ```
 
 `config` writes only `.truthmark/config.yml` unless `--stdout` is used.
@@ -194,10 +262,20 @@ truthmark check --json
 
 `check` validates configuration, authority, routing, decision-bearing docs, frontmatter, internal links, branch scope, and coverage diagnostics.
 
-Truth Structure, Truth Sync, Truth Realize, and Truth Check are installed agent workflows, not top-level daily CLI commands.
+`index` builds RepoIndex and RouteMap JSON for the active checkout.
+
+`impact --base <ref>` maps changed files to routed truth docs, owning routes, nearby tests, and public symbols.
+
+`context --workflow <workflow> [--base <ref>]` generates a bounded ContextPack for Truth Sync, Truth Document, or Truth Realize. `--format markdown` renders a human-readable pack.
+
+Truth Structure, Truth Document, Truth Sync, Truth Realize, and Truth Check are installed agent workflows, not top-level daily CLI commands.
 
 They run through the configured agent host surfaces, for example Codex/Claude/Copilot `/truthmark-*`, OpenCode `/skill truthmark-*`, or Gemini `/truthmark:*`.
 
+```text
+/truthmark-check audit routing and truth coverage before review
+```
+
 ## Why it exists
 
 Most AI coding workflows optimize for the next answer. Truthmark optimizes for the next handoff.
@@ -213,7 +291,7 @@ It assumes serious teams need:
 - truth that travels with the branch instead of living in hidden session state
 - workflows that still work when the package is not installed globally
 
-Truthmark is not a memory server and it is not an MCP server. It is a repository practice packaged as a small CLI installer plus agent-native workflow surfaces.
+Truthmark is not a memory server and it is not an MCP server. It is a repository practice packaged as a small CLI installer plus agent-native workflow surfaces that turn AI workflow rules into repo infrastructure.
 
 ## Project status
 
@@ -222,10 +300,14 @@ V1 currently provides:
 - `truthmark config`
 - `truthmark init`
 - `truthmark check`
+- `truthmark index`
+- `truthmark impact`
+- `truthmark context`
 - managed `AGENTS.md` workflow instructions
-- generated Truth Structure, Truth Sync, Truth Realize, and Truth Check skill surfaces for configured agent hosts
+- generated Truth Structure, Truth Document, Truth Sync, Truth Realize, and Truth Check skill surfaces for configured agent hosts
 - branch-scope metadata
-- config, authority, routing, decision-structure, frontmatter, link, and polyglot coverage diagnostics
+- config, authority, routing, decision-structure, frontmatter, link, freshness, and polyglot coverage diagnostics
+- derived RepoIndex, RouteMap, ImpactSet, and ContextPack artifacts for faster local review when the CLI is available
 
 ## Documentation
 
@@ -233,10 +315,10 @@ The root README is for people evaluating and trying the package. Detailed functi
 
 - [Docs index](docs/README.md)
 - [Architecture overview](docs/architecture/overview.md)
-- [API and CLI contracts](docs/features/contracts.md)
-- [Init and scaffold behavior](docs/features/init-and-scaffold.md)
-- [Check diagnostics](docs/features/check-diagnostics.md)
-- [Installed workflows](docs/features/installed-workflows.md)
+- [API and CLI contracts](docs/truth/contracts.md)
+- [Init and scaffold behavior](docs/truth/init-and-scaffold.md)
+- [Check diagnostics](docs/truth/check-diagnostics.md)
+- [Installed workflows](docs/truth/workflows/overview.md)
 - [Repository truth maintenance guide](docs/standards/maintaining-repository-truth.md)
 
 Current behavior belongs in the canonical docs tree above.