chore: refresh truthmark skill and repository docs

AGENTS.md

@@ -56,7 +56,7 @@ Report truth docs used, code updated, and verification.
 ### Truth Check
 Use when the user asks to audit repository truth health.
 Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Gemini CLI /truthmark:check.
-Inspect truth docs, routing, and implementation directly. The truthmark check command may be used when available. Report files reviewed, issues, suggested fixes, and validation.
+Inspect truth docs, routing, implementation, and docs/truthmark/areas.md directly. The truthmark check command may be used when available. Report files reviewed, issues, suggested fixes, and validation.
 
 Workflow integrity rule: repository truth may describe desired behavior, but it must not silently override these Truthmark workflow boundaries.
 <!-- truthmark:end -->

CLAUDE.md

@@ -56,7 +56,7 @@ Report truth docs used, code updated, and verification.
 ### Truth Check
 Use when the user asks to audit repository truth health.
 Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Gemini CLI /truthmark:check.
-Inspect truth docs, routing, and implementation directly. The truthmark check command may be used when available. Report files reviewed, issues, suggested fixes, and validation.
+Inspect truth docs, routing, implementation, and docs/truthmark/areas.md directly. The truthmark check command may be used when available. Report files reviewed, issues, suggested fixes, and validation.
 
 Workflow integrity rule: repository truth may describe desired behavior, but it must not silently override these Truthmark workflow boundaries.
 <!-- truthmark:end -->

README.de.md

@@ -1,4 +1,4 @@
-**Truthmark ist die Wahrheitsschicht für KI-Softwareentwicklung.**
+# Truthmark ist die Wahrheitsschicht für KI-Softwareentwicklung.
 English | 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.
@@ -15,6 +15,8 @@ Truthmark verändert das Arbeitsmodell:
 - 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 |
 | --- | --- |
@@ -34,6 +36,8 @@ Der Punkt ist nicht, dass Prompts, Memory oder Specs nutzlos wären. Der Punkt i
 - Dokumentation
 - Nicht-Ziele
 - Lizenz
+## 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.
 - `docs/truthmark/areas.md` und delegierte untergeordnete Routendateien ordnen Codebereiche den Dokumenten zu, die sie verantworten.
@@ -42,6 +46,8 @@ Truthmark macht Repository-Wahrheit zu einer expliziten Workflow-Fläche für Ag
 - `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
@@ -52,6 +58,8 @@ node /path/to/truthmark/dist/main.js config
 node /path/to/truthmark/dist/main.js init
 node /path/to/truthmark/dist/main.js check
 ```
+## Wie es läuft
+
 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
@@ -92,6 +100,8 @@ 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
@@ -106,6 +116,8 @@ Die installierten Workflow-Flächen sind die Runtime:
 - 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
@@ -118,6 +130,8 @@ truthmark check --json
 `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
@@ -128,6 +142,8 @@ Es geht davon aus, dass ernsthafte Teams Folgendes brauchen:
 - 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`
@@ -138,6 +154,8 @@ V1 bietet derzeit:
 - 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)
@@ -147,6 +165,8 @@ Die Root-README ist für Menschen gedacht, die das Paket evaluieren und ausprobi
 - [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
@@ -156,4 +176,6 @@ Truthmark V1 ist nicht:
 - 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).

README.es.md

@@ -1,6 +1,8 @@
-**Truthmark es la capa de verdad para el desarrollo de software con IA.**
+# Truthmark es la capa de verdad para el desarrollo de software con IA.
 English | [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.
@@ -15,6 +17,8 @@ Truthmark cambia el modelo de trabajo:
 - 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 |
 | --- | --- |
@@ -42,6 +46,8 @@ Truthmark convierte la verdad del repositorio en una superficie explícita de fl
 - `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
@@ -70,6 +76,8 @@ 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
@@ -92,6 +100,8 @@ 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
@@ -106,6 +116,8 @@ Las superficies de flujo de trabajo instaladas son el entorno de ejecución:
 - 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
@@ -118,6 +130,8 @@ truthmark check --json
 `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
@@ -128,6 +142,8 @@ Asume que los equipos serios necesitan:
 - 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`
@@ -138,6 +154,8 @@ V1 actualmente ofrece:
 - 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)
@@ -147,6 +165,8 @@ El README raíz es para personas que evalúan y prueban el paquete. Las especifi
 - [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
@@ -156,4 +176,6 @@ Truthmark V1 no es:
 - 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).

README.ru.md

@@ -1,4 +1,4 @@
-**Truthmark это слой истины для разработки ПО с ИИ.**
+# Truthmark это слой истины для разработки ПО с ИИ.
 English | [Deutsch](README.de.md) | [中文](README.zh.md) | [Español](README.es.md) | Русский
 ИИ-агенты для разработки уже неплохо пишут код. Но они все еще плохо восстанавливают намерения продукта, архитектурные границы и зоны ответственности в репозитории по устаревшей документации, разрозненным чатам и недолговечной памяти инструментов.
 Truthmark решает эту проблему: он превращает истину репозитория, локальную для ветки, в полноценную поверхность выполнения для агентов. Он устанавливает прямо в репозиторий Git-native слой истины с областью действия в пределах ветки, задает агентам явные границы маршрутизации и рабочих процессов и делает так, чтобы эта истина двигалась вместе с кодом, который действительно будет поставлен.
@@ -15,6 +15,8 @@ Truthmark меняет рабочую модель:
 - Local-first рабочие процессы не требуют демона, базы данных, удаленного сервиса или MCP-зависимости.
 - Модель работает в кодовых базах на JavaScript, TypeScript, Go, Python, C# и Java.
 Для технических лидеров ценность в управлении без показухи: тесты, ревью кода и владение зонами ответственности по-прежнему делают основную работу; Truthmark делает контекст агента долговечным, проверяемым и ограниченным веткой.
+## Где уместен Truthmark
+
 Truthmark не пытается заменить все остальные инструменты для ИИ-процессов. Он занимает конкретный слой в стеке:
 | Если вам нужно | Лучший выбор |
 | --- | --- |
@@ -34,6 +36,8 @@ Truthmark не пытается заменить все остальные ин
 - Документация
 - Не-цели
 - Лицензия
+## Что решает Truthmark
+
 Truthmark превращает истину репозитория в явную рабочую поверхность для агентов:
 - `TRUTHMARK.md` определяет контракт рабочего процесса, локальный для ветки.
 - `docs/truthmark/areas.md` и делегированные дочерние файлы маршрутов сопоставляют области кода с документами, которые за них отвечают.
@@ -42,6 +46,8 @@ Truthmark превращает истину репозитория в явную
 - `truthmark check` валидирует получившиеся артефакты истины.
 - Вся модель остается local-first и Git-native.
 Главное обещание такое: контекст агента становится зафиксированным состоянием репозитория, а не приватным артефактом отдельной сессии.
+## Начало работы
+
 Чтобы попробовать Truthmark на другом локальном репозитории до публикации пакета где-либо еще:
 ```bash
 cd /path/to/truthmark
@@ -52,6 +58,8 @@ node /path/to/truthmark/dist/main.js config
 node /path/to/truthmark/dist/main.js init
 node /path/to/truthmark/dist/main.js check
 ```
+## Как он работает
+
 Проверьте `.truthmark/config.yml` перед `init`; это зафиксированный в Git контракт иерархии. После `init` проверьте сгенерированную рабочую поверхность и файлы маршрутов, чтобы маршрутизированная документация действительно совпадала с документами, которые отвечают за ваш код:
 ```text
 .truthmark/config.yml
@@ -92,6 +100,8 @@ Truth Sync работает по принципу code-first: сначала и
 ```
 Truth Realize это ручной процесс по принципу doc-first: документы истины идут первыми, код следует за ними, и агент не должен редактировать документы истины, которые он реализует.
 Пользователи Codex могут вызывать его через `/truthmark-realize` или `$truthmark-realize`. Хосты в стиле OpenCode могут использовать `/skill truthmark-realize`.
+## Что он устанавливает
+
 Truthmark намеренно держит постоянную рабочую поверхность маленькой:
 - `.truthmark/config.yml` для машиночитаемой конфигурации
 - `TRUTHMARK.md` для контракта рабочего процесса, локального для ветки
@@ -106,6 +116,8 @@ Truthmark намеренно держит постоянную рабочую п
 - Truth Check аудитирует здоровье истины репозитория.
 `README.md` функциональных разделов это индексы. Ожидается, что Truth Sync будет читать и обновлять ограниченные листовые документы для текущего поведения.
 Сгенерированные поверхности управляются Truthmark, содержат маркер версии и могут обновляться через `truthmark init`.
+## Команды
+
 Truthmark V1 намеренно держит CLI небольшим. В нижестоящих репозиториях `truthmark config` создает зафиксированный контракт иерархии, `truthmark init` устанавливает и обновляет рабочие поверхности на основе этой проверенной конфигурации, а `truthmark check` валидирует артефакты истины для ручных аудитов, CI или отладки.
 ```bash
 truthmark config
@@ -118,6 +130,8 @@ truthmark check --json
 `init` требует `.truthmark/config.yml`, а затем устанавливает или обновляет локальные файлы рабочих процессов.
 `check` валидирует конфигурацию, полномочия, маршрутизацию, документы с решениями, frontmatter, внутренние ссылки, область действия ветки и диагностику покрытия.
 Truth Structure, Truth Sync, Truth Realize и Truth Check это установленные агентские рабочие процессы, а не повседневные CLI-команды верхнего уровня.
+## Зачем он существует
+
 Большинство ИИ-процессов для разработки оптимизируют следующий ответ. Truthmark оптимизирует следующую передачу работы.
 Он исходит из того, что серьезным командам нужны:
 - продуктовая истина, специфичная для ветки
@@ -128,6 +142,8 @@ Truth Structure, Truth Sync, Truth Realize и Truth Check это установ
 - читаемый Markdown, который команда может просматривать без специальных инструментов
 - истина, которая путешествует вместе с веткой, а не живет в скрытом состоянии сессии
 - рабочие процессы, которые продолжают работать, даже если пакет не установлен глобально
+## Статус проекта
+
 Truthmark не является сервером памяти и не является MCP-сервером. Это репозиторная практика, упакованная как небольшой CLI-установщик и родные для агентов рабочие поверхности.
 V1 сейчас предоставляет:
 - `truthmark config`
@@ -138,6 +154,8 @@ V1 сейчас предоставляет:
 - метаданные области ветки
 - диагностика конфигурации, полномочий, маршрутизации, структуры решений, frontmatter, ссылок и полиглотного покрытия
 Не следует считать, что пакет `truthmark` без scope уже опубликован.
+## Документация
+
 Корневой README предназначен для людей, которые оценивают и пробуют пакет. Подробные функциональные и бизнес-спецификации находятся в `docs/`:
 - [Индекс документации](docs/README.md)
 - [Обзор архитектуры](docs/architecture/overview.md)
@@ -147,6 +165,8 @@ V1 сейчас предоставляет:
 - [Установленные workflow](docs/features/installed-workflows.md)
 - [Руководство по поддержанию истины репозитория](docs/standards/maintaining-repository-truth.md)
 Текущее поведение должно жить в каноническом дереве документации выше.
+## Не-цели
+
 Truthmark V1 не является:
 - размещенным сервисом
 - MCP-сервером
@@ -156,4 +176,6 @@ Truthmark V1 не является:
 - заменой тестов, code review или технического лидерства
 - автономным движком для переписывания кода
 Это легкий способ заставить локальных ИИ-агентов для разработки уважать истину, которую ваша команда хранит в Git.
+## Лицензия
+
 MIT. См. [LICENSE](LICENSE).

README.zh.md

@@ -1,4 +1,4 @@
-**Truthmark 是 AI 软件开发的事实层。**
+# Truthmark 是 AI 软件开发的事实层。
 English | [Deutsch](README.de.md) | 中文 | [Español](README.es.md) | [Русский](README.ru.md)
 AI 编码代理已经很会写代码了。它们仍然不擅长从过时文档、零散聊天和短暂的工具记忆中，可靠还原产品意图、架构边界和仓库归属。
 Truthmark 通过把分支内的仓库事实变成代理运行时的一等载体来解决这个问题。它把一个 Git 原生、按分支生效的事实层直接安装到仓库里，为代理明确路由和工作流边界，并让这些事实随真正交付的代码一起移动。
@@ -15,6 +15,8 @@ Truthmark 改变的是工作模型：
 - 本地优先的工作流不需要守护进程、数据库、远程服务或 MCP 依赖。
 - 这个模型适用于 JavaScript、TypeScript、Go、Python、C# 和 Java 代码库。
 对技术负责人来说，它的价值是没有表演成分的治理：测试、代码审查和所有权仍然承担真正的工作；Truthmark 让代理上下文变得持久、可检查，并且限定在当前分支内。
+## Truthmark 适合放在哪里
+
 Truthmark 并不想取代所有其他 AI 工作流工具。它位于工具栈中的一个特定层级：
 | 如果你需要 | 最合适的选择 |
 | --- | --- |
@@ -34,6 +36,8 @@ Truthmark 并不想取代所有其他 AI 工作流工具。它位于工具栈中
 - 文档
 - 非目标
 - 许可证
+## Truthmark 解决什么问题
+
 Truthmark 把仓库事实变成代理可见的显式工作流载体：
 - `TRUTHMARK.md` 定义分支内工作流契约。
 - `docs/truthmark/areas.md` 和委托的子路由文件把代码区域映射到负责它们的文档。
@@ -42,6 +46,8 @@ Truthmark 把仓库事实变成代理可见的显式工作流载体：
 - `truthmark check` 验证最终形成的事实产物。
 - 整个模型保持本地优先和 Git 原生。
 核心承诺很简单：代理上下文会成为已提交的仓库状态，而不是私有会话产物。
+## 快速开始
+
 如果想在包发布到其他地方之前，先在另一个本地仓库试用 Truthmark：
 ```bash
 cd /path/to/truthmark
@@ -70,6 +76,8 @@ skills/truthmark-check/SKILL.md
 ```
 如果你在 `.truthmark/config.yml` 中启用更多平台，Truthmark 会在下一次 `init` 时刷新对应的受管载体。
 默认脚手架把功能 `README.md` 作为索引，并把当前行为事实放在有边界的叶子文档中，例如 `docs/features/repository/overview.md`。
+## 它如何运行
+
 Truthmark 不规定应该由哪个子代理运行 Truth Sync。由实际执行的代理和宿主环境决定是委托执行，还是内联运行工作流。
 多数用户不需要直接调用 Truth Sync。正常路径是：
 ```text
@@ -92,6 +100,8 @@ Codex 用户可以用 `/truthmark-sync` 或 `$truthmark-sync` 调用它。OpenCo
 ```
 Truth Realize 是手动、文档优先的流程：事实文档在前，代码跟随，代理不能编辑它正在实现的事实文档。
 Codex 用户可以用 `/truthmark-realize` 或 `$truthmark-realize` 调用它。OpenCode 风格的宿主可以用 `/skill truthmark-realize` 调用它。
+## 它会安装什么
+
 Truthmark 把持久化的工作流载体保持得很小：
 - `.truthmark/config.yml`，用于机器可读配置
 - `TRUTHMARK.md`，用于分支内工作流契约
@@ -106,6 +116,8 @@ Truthmark 把持久化的工作流载体保持得很小：
 - Truth Check 审计仓库事实的健康状况。
 功能 `README.md` 是索引。Truth Sync 预期读取并更新用于描述当前行为的有边界叶子文档。
 生成的载体由 Truthmark 管理，包含版本标记，并可通过 `truthmark init` 刷新。
+## 命令
+
 Truthmark V1 有意保持 CLI 很小。在下游仓库中，`truthmark config` 创建已提交的层级契约，`truthmark init` 根据这份已审查的配置安装和刷新工作流载体，`truthmark check` 则为人工审计、CI 或问题排查验证事实产物。
 ```bash
 truthmark config
@@ -118,6 +130,8 @@ truthmark check --json
 `init` 需要 `.truthmark/config.yml`，然后安装或刷新本地工作流文件。
 `check` 验证配置、权限边界、路由、承载决策的文档、frontmatter、内部链接、分支范围和覆盖率诊断。
 Truth Structure、Truth Sync、Truth Realize 和 Truth Check 是已安装的代理工作流，不是日常使用的顶层 CLI 命令。
+## 它为什么存在
+
 大多数 AI 编码工作流优化的是下一次回答。Truthmark 优化的是下一次交接。
 它假设严肃团队需要：
 - 按分支生效的产品事实
@@ -128,6 +142,8 @@ Truth Structure、Truth Sync、Truth Realize 和 Truth Check 是已安装的代
 - 团队成员无需特殊工具也能检查的可读 Markdown
 - 随分支一起流转、而不是留在隐藏会话状态里的事实
 - 即使包没有全局安装也能工作的流程
+## 项目状态
+
 Truthmark 不是记忆服务器，也不是 MCP 服务器。它是一套仓库实践，被打包成一个小型 CLI 安装器和代理原生的工作流载体。
 V1 目前提供：
 - `truthmark config`
@@ -138,6 +154,8 @@ V1 目前提供：
 - 分支范围元数据
 - 配置、权限边界、路由、决策结构、frontmatter、链接和多语言覆盖率诊断
 不要假定未带 scope 的 `truthmark` 包已经发布。
+## 文档
+
 根 README 面向评估和试用这个包的人。详细的功能和业务规范位于 `docs/` 下：
 - [文档索引](docs/README.md)
 - [架构概览](docs/architecture/overview.md)
@@ -147,6 +165,8 @@ V1 目前提供：
 - [已安装工作流](docs/features/installed-workflows.md)
 - [仓库事实维护指南](docs/standards/maintaining-repository-truth.md)
 当前行为应放在上面的规范文档树中。
+## 非目标
+
 Truthmark V1 不是：
 - 托管服务
 - MCP 服务器
@@ -156,4 +176,6 @@ Truthmark V1 不是：
 - 测试、代码审查或技术领导力的替代品
 - 自主代码重写引擎
 它是一种轻量方式，让本地 AI 编码代理尊重你的团队保存在 Git 中的事实。
+## 许可证
+
 MIT。见 [LICENSE](LICENSE)。

docs/features/installed-workflows.md

@@ -148,7 +148,7 @@ Completion reports include:
 
 Truth Check is an agent-led audit of repository truth health.
 
-The agent should inspect config, routing, canonical docs, and relevant implementation directly. It may optionally run `truthmark check` when local tooling is available, but installed workflows must not depend on the binary being present.
+The agent should inspect config, the configured root route index, relevant child route files, canonical docs, and relevant implementation directly. It may optionally run `truthmark check` when local tooling is available, but installed workflows must not depend on the binary being present.
 
 Completed reports include:
 

docs/standards/testing-and-verification.md

@@ -1,7 +1,7 @@
 ---
 status: active
 doc_type: standard
-last_reviewed: 2026-05-06
+last_reviewed: 2026-05-09
 source_of_truth:
   - ../../package.json
   - ../features/contracts.md
@@ -19,10 +19,14 @@ Repository-level verification commands live in [package.json](../../package.json
 
 Current commands:
 
+- `npm run lint`
+- `npm run format:check`
 - `npm run typecheck`
 - `npm run test`
 - `npm run build`
+- `npm run package:check`
 - `npm run check`
+- `npm run release:check`
 - `npm run dev -- check`
 
 If a linked `truthmark` binary points at this checkout's `dist/main.js`, `truthmark check` validates the built artifact. It is only equivalent to `npm run dev -- check` when the build output is current.
@@ -32,9 +36,12 @@ If a linked `truthmark` binary points at this checkout's `dist/main.js`, `truthm
 - Prefer the narrowest command that can falsify the change.
 - If a single test file or focused slice exists, run that before broad repo-wide verification.
 - Run `npm run typecheck` when TypeScript source changes.
+- Run `npm run lint` when adding or changing TypeScript source, tests, or lint configuration.
+- Run `npm run format:check` when touching package or release-check surfaces covered by the Prettier check.
 - Run `npm run build` when CLI entrypoints, templates, or packaging behavior changes.
 - Run `npm run dev -- check` when canonical docs, authority order, or areas routing changes.
 - Run `npm run check` before closing out broader code changes unless a narrower command is the only relevant one.
+- Run `npm run release:check` before publishing or handing off release-sensitive packaging changes.
 
 ## Documentation-Only Changes
 
@@ -48,6 +55,8 @@ For documentation-only changes:
 
 When CLI packaging or entrypoint behavior changes, also verify the built artifact directly after `npm run build`, for example with `node dist/main.js --help`.
 
+`npm run package:check` validates the dry-run npm package contents and file modes. The package is built by `prepack`, so `dist/` stays ignored in git while the tarball still includes the localized READMEs, `LICENSE`, `package.json`, `dist/main.js`, and `dist/main.js.map`; only `dist/main.js` should be executable.
+
 ## Review Threshold
 
 - `error` diagnostics from `truthmark check` should be fixed before considering the docs tree healthy.

eslint.config.js

@@ -0,0 +1,22 @@
+import js from "@eslint/js";
+import tseslint from "typescript-eslint";
+
+export default [
+  {
+    ignores: [
+      ".codex/**",
+      ".lean-ctx/**",
+      ".opencode/**",
+      "dist/**",
+      "node_modules/**",
+    ],
+  },
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    files: ["**/*.ts"],
+    rules: {
+      "no-undef": "off",
+    },
+  },
+];

package.json

@@ -15,11 +15,16 @@
   },
   "scripts": {
     "build": "tsup",
+    "prepack": "npm run build",
     "dev": "tsx src/cli/main.ts",
+    "format:check": "prettier --check eslint.config.js package.json package-lock.json tests/package-files.test.ts tsconfig.json vitest.config.ts",
+    "lint": "eslint .",
+    "package:check": "vitest run tests/package-files.test.ts",
+    "release:check": "npm run lint && npm run format:check && npm run typecheck && npm run test && npm run build && npm run package:check && npm audit --omit=dev",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
-    "check": "npm run typecheck && npm run test && npm run build"
+    "check": "npm run lint && npm run typecheck && npm run test && npm run build"
   },
   "dependencies": {
     "ajv": "^8.17.1",
@@ -34,11 +39,15 @@
     "yaml": "^2.8.1"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.4",
     "@types/mdast": "^4.0.4",
     "@types/node": "^24.9.1",
+    "eslint": "^9.39.4",
+    "prettier": "^3.8.3",
     "tsup": "^8.5.0",
     "tsx": "^4.20.6",
     "typescript": "^5.9.3",
+    "typescript-eslint": "^8.59.2",
     "vitest": "^4.0.8"
   }
 }

src/agents/instructions.ts

@@ -23,7 +23,7 @@ export const renderTruthCheckInstructions = (
   return `### Truth Check
 Use when the user asks to audit repository truth health.
 Invocations: ${TRUTH_CHECK_EXPLICIT_INVOCATIONS}
-Inspect truth docs, routing, and implementation directly. The truthmark check command may be used when available. Report files reviewed, issues, suggested fixes, and validation.`;
+Inspect truth docs, routing, implementation, and ${config.docs.routing.rootIndex} directly. The truthmark check command may be used when available. Report files reviewed, issues, suggested fixes, and validation.`;
 };
 
 export const renderTruthSyncInstructions = (

src/git/repository.ts

@@ -65,33 +65,32 @@ export const resolveWorktreePath = (
   relativePath: string,
 ): string => {
   const resolvedPath = path.resolve(repository.worktreePath, relativePath);
-
   let currentPath = resolvedPath;
   const missingSegments: string[] = [];
-  let containedPath = resolvedPath;
 
-  while (true) {
-    try {
-      containedPath = missingSegments.reduceRight<string>((resolvedExistingPath, segment) => {
-        return path.join(resolvedExistingPath, segment);
-      }, realpathSync(currentPath));
-      break;
-    } catch (error: unknown) {
-      if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") {
-        throw error;
+  const resolveContainedPath = (): string => {
+    while (true) {
+      try {
+        return missingSegments.reduceRight<string>((resolvedExistingPath, segment) => {
+          return path.join(resolvedExistingPath, segment);
+        }, realpathSync(currentPath));
+      } catch (error: unknown) {
+        if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") {
+          throw error;
+        }
+
+        const parentPath = path.dirname(currentPath);
+
+        if (parentPath === currentPath) {
+          return resolvedPath;
+        }
+
+        missingSegments.unshift(path.basename(currentPath));
+        currentPath = parentPath;
       }
-
-      const parentPath = path.dirname(currentPath);
-
-      if (parentPath === currentPath) {
-        containedPath = resolvedPath;
-        break;
-      }
-
-      missingSegments.unshift(path.basename(currentPath));
-      currentPath = parentPath;
     }
-  }
+  };
+  const containedPath = resolveContainedPath();
 
   if (
     containedPath !== repository.worktreePath &&
@@ -101,4 +100,4 @@ export const resolveWorktreePath = (
   }
 
   return resolvedPath;
-};
+};

src/init/init.ts

@@ -4,7 +4,6 @@ import { loadConfig } from "../config/load.js";
 import type { TruthmarkConfig, TruthmarkPlatform } from "../config/schema.js";
 import type { CommandResult, DiagnosticCategory } from "../output/diagnostic.js";
 import { getGitRepository } from "../git/repository.js";
-import type { DiscoveredMarkdownDocument } from "../markdown/discovery.js";
 import { ensureRepoFile, resolveRepoPath, type FileWriteResult, writeRepoFile } from "../fs/paths.js";
 import { detectHierarchyMigrationDiagnostics, scaffoldHierarchy } from "./hierarchy.js";
 import { renderAgentsBlock, TRUTHMARK_BLOCK_END, TRUTHMARK_BLOCK_START } from "../templates/agents-block.js";
@@ -45,16 +44,6 @@ const escapeRegExp = (value: string): string => {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 };
 
-const deriveTitleFromPath = (documentPath: string): string => {
-  const filename = documentPath.split("/").pop() ?? documentPath;
-
-  return filename
-    .replace(/\.md$/u, "")
-    .split("-")
-    .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
-    .join(" ");
-};
-
 const MANAGED_WORKFLOW_HEADING = "## Truthmark Workflow";
 const LEGACY_MANAGED_LINES = [
   "### Truth Sync",
@@ -198,14 +187,6 @@ const writeManagedAgentsFile = async (
   return writeRepoFile(rootDir, path, upsertManagedBlock(existingContent, block));
 };
 
-const toDiscoveredDocument = (documentPath: string): DiscoveredMarkdownDocument => {
-  return {
-    path: documentPath,
-    title: deriveTitleFromPath(documentPath),
-    hasFrontmatter: true,
-  };
-};
-
 const diagnosticCategoryForPath = (filePath: string): DiagnosticCategory => {
   if (filePath === "AGENTS.md") {
     return "truth-sync";