truthmark 1.3.0 → 1.4.0

package/README.de.md

@@ -96,6 +96,7 @@ Truthmark macht Repository-Wahrheit zu einer expliziten Workflow-Fläche für Ag
 - `docs/truthmark/areas.md` und delegierte untergeordnete Routendateien ordnen Codebereiche den Dokumenten zu, die sie verantworten.
 - Truth Document erstellt oder repariert kanonische Wahrheitsdokumente für bereits implementiertes Verhalten, wenn keine Codeänderung nötig ist.
 - Truth Sync hält zugeordnete Wahrheitsdokumente bei funktionalen Änderungen synchron.
+- Truth Preview zeigt wahrscheinliches Workflow-Routing vor Änderungen an, ohne Schreibzugriffe zu autorisieren.
 - Truth Realize gibt doc-first Änderungen einen begrenzten Pfad für Code-Updates.
 - `truthmark check` validiert die daraus entstehenden Wahrheitsartefakte.
 - Das gesamte Modell bleibt local-first und Git-nativ.
@@ -213,18 +214,25 @@ Codex, Claude Code und unterstützte Copilot-IDEs können es mit `/truthmark-rea
 
 Truthmark hält die dauerhafte Workflow-Fläche klein und repository-nativ. Nach `truthmark init` trägt das Repository selbst Routing, Regeln und installierte Workflow-Flächen, sodass Teams nicht nur auf die lokale Konfiguration einer einzelnen Person angewiesen sind.
 
+Truthmark installiert zwei getrennte Oberflächen:
+
+- menschenorientierte CLI-Befehle, die Menschen oder CI ausführen, um das Repository zu konfigurieren, installierte Dateien zu aktualisieren, Truth-Artefakte zu validieren und optional abgeleiteten Review-Kontext zu erzeugen
+- Agenten-Workflow-Flächen, die Coding-Agenten oder Agenten-Hosts während Implementierungsworkflows aufrufen; sie sind keine zusätzlichen täglichen Terminalbefehle für Menschen
+
 - `.truthmark/config.yml` für den maschinenlesbaren, festgeschriebenen Hierarchievertrag
 - `docs/truthmark/areas.md` für den Root-Routenindex
 - `docs/truthmark/areas/**/*.md` für delegierte untergeordnete Routendateien
 - `docs/templates/behavior-doc.md` sowie die weiteren typspezifischen Vorlagen unter `docs/templates/` für die editierbaren Truth-Doc-Standards der generierten Workflows
 - verwaltete Instruktionsblöcke für konfigurierte Plattformen wie `AGENTS.md`, `CLAUDE.md`, Copilot-Anweisungen und `GEMINI.md`
-- host-native Skills, Prompts oder Commands für Truth Structure, Truth Document, Truth Sync, Truth Realize und Truth Check
+- host-native Skills, Prompts oder Commands für Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize und Truth Check
+- projektbezogene schreibgeschützte Codex-, Claude-Code-, GitHub-Copilot- und OpenCode-Prüfer plus geleaste `truth-doc-writer`-Agenten, wo Hosts Agenten unterstützen, unter `.codex/agents/`, `.claude/agents/`, `.github/agents/` und `.opencode/agents/` für workflow-eigene Audits und vom Parent geleaste Dokument-Shards
 
 Die installierten Workflow-Flächen sind die Runtime:
 
 - Truth Structure erstellt oder repariert Area-Routing und erste Wahrheitsdokumente.
 - Truth Document erstellt oder repariert Wahrheitsdokumente für bereits implementiertes Verhalten.
 - Truth Sync hält zugeordnete Wahrheitsdokumente bei funktionalen Änderungen synchron.
+- Truth Preview zeigt wahrscheinliches Workflow-Routing vor Änderungen an, ohne Dateien zu schreiben.
 - Truth Realize aktualisiert Code so, dass er zu den Wahrheitsdokumenten passt.
 - Truth Check auditiert die Gesundheit der Repository-Wahrheit.
 
@@ -234,38 +242,30 @@ Generierte Flächen werden von Truthmark verwaltet, enthalten einen Versionsmark
 
 ## Befehle
 
-Truthmark V1 hält die CLI fokussiert, weil der laufende Workflow in den installierten Agenten-Flächen leben soll und nicht in einer langen Liste täglicher manueller Befehle. In nachgelagerten Repositories erzeugt `truthmark config` den in Git festgeschriebenen Hierarchievertrag, `truthmark init` installiert und aktualisiert Workflow-Flächen aus dieser geprüften Konfiguration, `truthmark check` validiert Wahrheitsartefakte für manuelle Audits, CI oder Fehlersuche, und die Repository-Intelligence-Befehle erzeugen abgeleitete Prüfarbeitsstände, wenn lokale Werkzeuge verfügbar sind.
+Truthmark V1 hält die Terminal-CLI fokussiert. Die meisten menschlichen Nutzer brauchen nur Einrichtung, Aktualisierung und Validierung:
 
-```bash
-truthmark config
-truthmark init
-truthmark check
-truthmark 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` 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.
+| Menschenorientierter CLI-Befehl | Zweck |
+| -------------------------------- | ----- |
+| `truthmark config` | Erstellt `.truthmark/config.yml`; schreibt nur diese Datei, außer `--stdout` wird verwendet. |
+| `truthmark init` | Installiert oder aktualisiert lokale Workflow-Dateien aus der geprüften Konfiguration. |
+| `truthmark check` | Validiert Konfiguration, Autorität, Routing, entscheidungstragende Dokumente, Frontmatter, interne Links, Branch-Scope und Coverage-Diagnostik. |
 
-`check` validiert Konfiguration, Autorität, Routing, entscheidungstragende Dokumente, Frontmatter, interne Links, Branch-Scope und Coverage-Diagnostik.
+Die übrigen CLI-Befehle sind optionale Repository-Intelligence-Helfer. Sie erzeugen abgeleiteten Review-Kontext für den aktiven Checkout; sie sind keine Quellen der Wahrheit:
 
-`index` baut RepoIndex- und RouteMap-JSON für den aktiven Checkout.
+| Optionaler CLI-Befehl | Zweck |
+| --------------------- | ----- |
+| `truthmark index` | Baut RepoIndex- und RouteMap-JSON für den aktiven Checkout. |
+| `truthmark impact --base <ref>` | Ordnet geänderte Dateien den gerouteten Truth-Dokumenten, zuständigen Routen, nahen Tests und öffentlichen Symbolen zu. |
+| `truthmark context --workflow <workflow> [--base <ref>]` | Erzeugt ein begrenztes ContextPack für Truth Sync, Truth Document oder Truth Realize. `--format markdown` rendert eine menschenlesbare Fassung. |
 
-`impact --base <ref>` ordnet geänderte Dateien den gerouteten Truth-Dokumenten, Routen, nahen Tests und öffentlichen Symbolen zu.
+Alle oben genannten CLI-Befehle unterstützen `--json`, wenn strukturierte Ausgabe für Automatisierung nützlich ist.
 
-`context --workflow <workflow> [--base <ref>]` erzeugt ein begrenztes ContextPack für Truth Sync, Truth Document oder Truth Realize. `--format markdown` rendert eine menschenlesbare Fassung.
-
-Truth Structure, Truth Document, Truth Sync, Truth Realize und Truth Check sind installierte Agenten-Workflows, keine täglichen Top-Level-CLI-Befehle.
+Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize und Truth Check sind installierte Agenten-Workflows, keine täglichen Top-Level-CLI-Befehle.
 
 Sie laufen über die konfigurierten Agenten-Host-Flächen, zum Beispiel Codex/Claude/Copilot `/truthmark-*`, OpenCode `/skill truthmark-*` oder Gemini `/truthmark:*`.
 
+Diese Aufrufe wirken befehlsartig, weil Agenten-Hosts Skills über Slash-Commands bereitstellen. Behandle sie als Anweisungen an einen Agenten, nicht als Terminalbefehle, die Menschen ausführen sollen.
+
 ```text
 /truthmark-check routing und truth-abdeckung vor der review prüfen
 ```
@@ -297,7 +297,7 @@ V1 bietet derzeit:
 - `truthmark impact`
 - `truthmark context`
 - verwaltete `AGENTS.md`-Workflow-Anweisungen
-- generierte Truth Structure-, Truth Document-, Truth Sync-, Truth Realize- und Truth Check-Skill-Flächen für konfigurierte Agenten-Hosts
+- generierte Truth Structure-, Truth Document-, Truth Sync-, Truth Preview-, Truth Realize- und Truth Check-Skill-Flächen für konfigurierte Agenten-Hosts
 - Branch-Scope-Metadaten
 - Diagnostik für Konfiguration, Autorität, Routing, Entscheidungsstruktur, Frontmatter, Links, Freshness und polyglotte Abdeckung
 - abgeleitete RepoIndex-, RouteMap-, ImpactSet- und ContextPack-Artefakte für schnellere lokale Prüfung, wenn die CLI verfügbar ist

package/README.es.md

@@ -96,6 +96,7 @@ Truthmark convierte la verdad del repositorio en una superficie explícita de fl
 - `docs/truthmark/areas.md` y los archivos de rutas secundarias delegadas asignan áreas de código a los documentos que las gobiernan.
 - Truth Document genera o repara documentos de verdad canónica para comportamiento ya implementado cuando no hace falta cambiar código.
 - Truth Sync mantiene alineados los documentos de verdad asignados cuando hay cambios funcionales.
+- Truth Preview previsualiza el enrutamiento de flujo probable antes de editar, sin autorizar escrituras.
 - Truth Realize ofrece a los cambios que empiezan en documentación una ruta acotada para actualizar código.
 - `truthmark check` valida los artefactos de verdad resultantes.
 - Todo el modelo se mantiene local-first y nativo de Git.
@@ -213,18 +214,25 @@ Codex, Claude Code y los IDEs de Copilot compatibles pueden invocarlo con `/trut
 
 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 instala dos superficies distintas:
+
+- comandos CLI orientados a personas, ejecutados por personas o CI para configurar el repositorio, refrescar archivos instalados, validar artefactos de verdad y generar opcionalmente contexto derivado para revisión
+- superficies de flujo de trabajo para agentes, invocadas por agentes de código u hosts de agentes durante flujos de implementación; no son comandos de terminal diarios adicionales para personas
+
 - `.truthmark/config.yml` para el contrato de jerarquía confirmado y legible por máquina
 - `docs/truthmark/areas.md` para el índice raíz de rutas
 - `docs/truthmark/areas/**/*.md` para archivos de rutas secundarias delegadas
 - `docs/templates/behavior-doc.md` y las demás plantillas específicas por tipo bajo `docs/templates/` para los estándares editables de truth docs usados por los flujos generados
 - bloques de instrucciones administrados para plataformas configuradas como `AGENTS.md`, `CLAUDE.md`, instrucciones de Copilot y `GEMINI.md`
-- skills, prompts o comandos nativos del host para Truth Structure, Truth Document, Truth Sync, Truth Realize y Truth Check
+- skills, prompts o comandos nativos del host para Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize y Truth Check
+- verificadores de solo lectura de Codex, Claude Code, GitHub Copilot y OpenCode con alcance de proyecto, más agentes `truth-doc-writer` con lease donde el host admite agentes, bajo `.codex/agents/`, `.claude/agents/`, `.github/agents/` y `.opencode/agents/` para auditorías propias del flujo y shards de documentación concedidos por el padre
 
 Las superficies de flujo de trabajo instaladas son el entorno de ejecución:
 
 - Truth Structure crea o repara el enrutamiento de áreas y documentos de verdad iniciales.
 - Truth Document crea o repara documentos de verdad para comportamiento ya implementado.
 - Truth Sync mantiene alineados los documentos de verdad asignados con los cambios funcionales.
+- Truth Preview previsualiza el enrutamiento de flujo probable antes de editar sin escribir archivos.
 - Truth Realize actualiza el código para que coincida con los documentos de verdad.
 - Truth Check audita la salud de la verdad del repositorio.
 
@@ -234,38 +242,30 @@ Las superficies generadas son administradas por Truthmark, incluyen un marcador
 
 ## Comandos
 
-Truthmark V1 mantiene la CLI pequeña a propósito porque el flujo continuo debe vivir en las superficies instaladas del agente, no en una lista larga de comandos manuales de uso diario. En repositorios derivados, `truthmark config` crea el contrato de jerarquía confirmado en Git, `truthmark init` instala y refresca superficies de flujo de trabajo a partir de esa configuración revisada, `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.
+Truthmark V1 mantiene enfocada la CLI de terminal. La mayoría de los usuarios humanos solo necesita configuración, actualización y validación:
 
-```bash
-truthmark config
-truthmark init
-truthmark check
-truthmark 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.
+| CLI orientada a personas | Uso |
+| ------------------------ | --- |
+| `truthmark config` | Crea `.truthmark/config.yml`; solo escribe ese archivo, salvo que se use `--stdout`. |
+| `truthmark init` | Instala o refresca los archivos locales de flujo de trabajo desde la configuración revisada. |
+| `truthmark check` | Valida configuración, autoridad, enrutamiento, documentos que contienen decisiones, frontmatter, enlaces internos, alcance de rama y diagnósticos de cobertura. |
 
-`check` valida configuración, autoridad, enrutamiento, documentos que contienen decisiones, frontmatter, enlaces internos, alcance de rama y diagnósticos de cobertura.
+Los demás comandos CLI son ayudantes opcionales de inteligencia del repositorio. Generan contexto derivado para revisión sobre el checkout activo; no son fuentes de verdad:
 
-`index` construye JSON de RepoIndex y RouteMap para el checkout activo.
+| CLI opcional | Uso |
+| ------------ | --- |
+| `truthmark index` | Construye JSON de RepoIndex y RouteMap para el checkout activo. |
+| `truthmark impact --base <ref>` | Mapea los archivos cambiados a truth docs enrutados, rutas propietarias, pruebas cercanas y símbolos públicos. |
+| `truthmark context --workflow <workflow> [--base <ref>]` | Genera un ContextPack acotado para Truth Sync, Truth Document o Truth Realize. `--format markdown` lo renderiza en un formato legible para personas. |
 
-`impact --base <ref>` mapea los archivos cambiados a los truth docs enrutados, rutas propietarias, pruebas cercanas y símbolos públicos.
+Todos los comandos CLI anteriores admiten `--json` cuando la salida estructurada es útil para automatización.
 
-`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.
+Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize y Truth Check son flujos de trabajo instalados para agentes, no comandos CLI principales de uso diario.
 
 Se ejecutan a través de las superficies configuradas del host agente, por ejemplo Codex/Claude/Copilot `/truthmark-*`, OpenCode `/skill truthmark-*` o Gemini `/truthmark:*`.
 
+Estas invocaciones parecen comandos porque los hosts de agentes exponen skills mediante slash commands. Trátalas como instrucciones para un agente, no como comandos de terminal que una persona deba ejecutar.
+
 ```text
 /truthmark-check audita el enrutamiento y la cobertura de verdad antes de la revisión
 ```
@@ -297,7 +297,7 @@ V1 actualmente ofrece:
 - `truthmark impact`
 - `truthmark context`
 - instrucciones de flujo de trabajo administradas en `AGENTS.md`
-- superficies de skill generadas para Truth Structure, Truth Document, Truth Sync, Truth Realize y Truth Check en los anfitriones de agentes configurados
+- superficies de skill generadas para Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize y Truth Check en los anfitriones de agentes configurados
 - metadatos de alcance de rama
 - diagnósticos de configuración, autoridad, enrutamiento, estructura de decisiones, frontmatter, enlaces y cobertura políglota
 - artefactos derivados de RepoIndex, RouteMap, ImpactSet y ContextPack para una revisión local más rápida cuando la CLI está disponible

package/README.md

@@ -96,6 +96,7 @@ Truthmark turns repository truth into an explicit workflow surface for agents:
 - `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 Preview previews likely workflow routing before edits without authorizing writes.
 - Truth Realize gives doc-first changes a bounded code-update path.
 - `truthmark check` validates the resulting truth artifacts.
 - The whole model stays local-first and Git-native.
@@ -219,18 +220,25 @@ Codex, Claude Code, and supported Copilot IDEs can invoke it with `/truthmark-re
 
 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 installs two distinct surfaces:
+
+- human-facing CLI commands, run by people or CI to configure the repo, refresh installed files, validate truth artifacts, and optionally generate derived review context
+- agent workflow surfaces, invoked by coding agents or agent hosts during implementation workflows; they are not extra daily terminal commands for humans
+
 - `.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 Document, Truth Sync, Truth Realize, and Truth Check
+- host-native skills, prompts, or commands for Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize, and Truth Check
+- Codex, Claude Code, GitHub Copilot, and OpenCode project-scoped read-only verifiers plus leased `truth-doc-writer` agents where hosts support agents, under `.codex/agents/`, `.claude/agents/`, `.github/agents/`, and `.opencode/agents/` for workflow-owned audits and parent-leased doc shards
 
 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 Preview previews likely workflow routing before edits without writing files.
 - Truth Realize updates code to match truth docs.
 - Truth Check audits repository truth health.
 
@@ -240,38 +248,30 @@ Generated surfaces are managed by Truthmark, include a version marker, and may b
 
 ## Commands
 
-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.
+Truthmark V1 keeps the terminal CLI focused. Most human users only need setup, refresh, and validation:
 
-```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.
-
-`init` requires `.truthmark/config.yml`, then installs or refreshes the local workflow files.
+| Human-facing CLI | Use |
+| ---------------- | --- |
+| `truthmark config` | Create `.truthmark/config.yml`; writes only that file unless `--stdout` is used. |
+| `truthmark init` | Install or refresh local workflow files from the reviewed config. |
+| `truthmark check` | Validate configuration, authority, routing, decision-bearing docs, frontmatter, internal links, branch scope, and coverage diagnostics. |
 
-`check` validates configuration, authority, routing, decision-bearing docs, frontmatter, internal links, branch scope, and coverage diagnostics.
+The remaining CLI commands are optional repository-intelligence helpers. They generate derived review context for the active checkout; they are not sources of truth:
 
-`index` builds RepoIndex and RouteMap JSON for the active checkout.
+| Optional CLI | Use |
+| ------------ | --- |
+| `truthmark index` | Build RepoIndex and RouteMap JSON for the active checkout. |
+| `truthmark impact --base <ref>` | Map changed files to routed truth docs, owning routes, nearby tests, and public symbols. |
+| `truthmark context --workflow <workflow> [--base <ref>]` | Generate a bounded ContextPack for Truth Sync, Truth Document, or Truth Realize. `--format markdown` renders a human-readable pack. |
 
-`impact --base <ref>` maps changed files to routed truth docs, owning routes, nearby tests, and public symbols.
+All CLI commands above support `--json` where structured output is useful for automation.
 
-`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.
+Truth Structure, Truth Document, Truth Sync, Truth Preview, 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:*`.
 
+These invocations look command-like because agent hosts expose skills through slash commands. Treat them as instructions to an agent, not as terminal commands a human is expected to run.
+
 ```text
 /truthmark-check audit routing and truth coverage before review
 ```
@@ -304,7 +304,7 @@ V1 currently provides:
 - `truthmark impact`
 - `truthmark context`
 - managed `AGENTS.md` workflow instructions
-- generated Truth Structure, Truth Document, Truth Sync, Truth Realize, and Truth Check skill surfaces for configured agent hosts
+- generated Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize, and Truth Check skill surfaces for configured agent hosts
 - branch-scope metadata
 - 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

package/README.ru.md

@@ -96,6 +96,7 @@ Truthmark превращает истину репозитория в явную
 - `docs/truthmark/areas.md` и делегированные дочерние файлы маршрутов сопоставляют области кода с документами, которые за них отвечают.
 - Truth Document создает или исправляет канонические документы истины для уже реализованного поведения, когда изменение кода не нужно.
 - Truth Sync поддерживает синхронизацию сопоставленных документов истины при функциональных изменениях.
+- Truth Preview предварительно показывает вероятную маршрутизацию рабочего процесса до правок, не авторизуя записи.
 - Truth Realize дает изменениям, начинающимся с документации, ограниченный путь для обновления кода.
 - `truthmark check` валидирует получившиеся артефакты истины.
 - Вся модель остается local-first и Git-native.
@@ -213,18 +214,25 @@ Codex, Claude Code и поддерживаемые IDE Copilot могут выз
 
 Truthmark держит постоянную рабочую поверхность маленькой и встроенной в репозиторий. После `truthmark init` сам репозиторий несет маршрутизацию, правила и установленные рабочие поверхности, поэтому команда не зависит только от локальной настройки одного человека.
 
+Truthmark устанавливает два разных интерфейса:
+
+- CLI-команды для людей, которые запускают люди или CI, чтобы настроить репозиторий, обновить установленные файлы, проверить артефакты истины и при необходимости создать производный контекст для ревью
+- агентские рабочие поверхности, которые вызывают coding agents или агентские хосты во время реализации; это не дополнительные ежедневные терминальные команды для людей
+
 - `.truthmark/config.yml` для машиночитаемого зафиксированного контракта иерархии
 - `docs/truthmark/areas.md` для корневого индекса маршрутов
 - `docs/truthmark/areas/**/*.md` для делегированных дочерних файлов маршрутов
 - `docs/templates/behavior-doc.md` и другие шаблоны по видам под `docs/templates/` для редактируемых стандартов truth docs, используемых сгенерированными рабочими процессами
 - управляемые блоки инструкций для настроенных платформ, таких как `AGENTS.md`, `CLAUDE.md`, инструкции Copilot и `GEMINI.md`
-- нативные для хоста skills, prompts или commands для Truth Structure, Truth Document, Truth Sync, Truth Realize и Truth Check
+- нативные для хоста skills, prompts или commands для Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize и Truth Check
+- проектные проверяющие агенты Codex, Claude Code, GitHub Copilot и OpenCode в режиме только чтения, а также leased-агенты `truth-doc-writer` там, где хост поддерживает агентов, под `.codex/agents/`, `.claude/agents/`, `.github/agents/` и `.opencode/agents/` для аудитов, которыми владеет рабочий процесс, и для документных шардов, выданных родительским агентом
 
 Установленные рабочие поверхности и есть среда выполнения:
 
 - Truth Structure создает или исправляет маршрутизацию областей и стартовые документы истины.
 - Truth Document создает или исправляет документы истины для уже реализованного поведения.
 - Truth Sync поддерживает синхронизацию сопоставленных документов истины с функциональными изменениями.
+- Truth Preview предварительно показывает вероятную маршрутизацию рабочего процесса до правок без записи файлов.
 - Truth Realize обновляет код так, чтобы он соответствовал документам истины.
 - Truth Check аудитирует здоровье истины репозитория.
 
@@ -234,38 +242,30 @@ Truthmark держит постоянную рабочую поверхност
 
 ## Команды
 
-Truthmark V1 намеренно держит CLI небольшим, потому что постоянный рабочий процесс должен жить в установленных агентских поверхностях, а не в длинном списке ежедневных ручных команд. В нижестоящих репозиториях `truthmark config` создает зафиксированный контракт иерархии, `truthmark init` устанавливает и обновляет рабочие поверхности на основе этой проверенной конфигурации, `truthmark check` валидирует артефакты истины для ручных аудитов, CI или отладки, а команды репозиторной аналитики создают производные артефакты для проверки, когда доступны локальные инструменты.
+Truthmark V1 держит терминальный CLI сфокусированным. Большинству людей нужны только настройка, обновление и проверка:
 
-```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` пишет только `.truthmark/config.yml`, если не используется `--stdout`.
-
-`init` требует `.truthmark/config.yml`, а затем устанавливает или обновляет локальные файлы рабочих процессов.
+| CLI-команда для людей | Назначение |
+| --------------------- | ---------- |
+| `truthmark config` | Создает `.truthmark/config.yml`; пишет только этот файл, если не используется `--stdout`. |
+| `truthmark init` | Устанавливает или обновляет локальные файлы рабочих процессов из проверенной конфигурации. |
+| `truthmark check` | Валидирует конфигурацию, полномочия, маршрутизацию, документы с решениями, frontmatter, внутренние ссылки, область действия ветки и диагностику покрытия. |
 
-`check` валидирует конфигурацию, полномочия, маршрутизацию, документы с решениями, frontmatter, внутренние ссылки, область действия ветки и диагностику покрытия.
+Остальные CLI-команды - необязательные помощники репозиторной аналитики. Они создают производный контекст для ревью активного checkout; они не являются источниками истины:
 
-`index` строит JSON RepoIndex и RouteMap для активного checkout.
+| Необязательная CLI-команда | Назначение |
+| -------------------------- | ---------- |
+| `truthmark index` | Строит JSON RepoIndex и RouteMap для активного checkout. |
+| `truthmark impact --base <ref>` | Сопоставляет измененные файлы с routed truth docs, owning routes, nearby tests и public symbols. |
+| `truthmark context --workflow <workflow> [--base <ref>]` | Генерирует ограниченный ContextPack для Truth Sync, Truth Document или Truth Realize. `--format markdown` рендерит его в читаемый человеком вид. |
 
-`impact --base <ref>` сопоставляет измененные файлы с routed truth docs, owning routes, nearby tests и public symbols.
+Все CLI-команды выше поддерживают `--json`, когда структурированный вывод полезен для автоматизации.
 
-`context --workflow <workflow> [--base <ref>]` генерирует ограниченный ContextPack для Truth Sync, Truth Document или Truth Realize. `--format markdown` рендерит его в читаемый человеком вид.
-
-Truth Structure, Truth Document, Truth Sync, Truth Realize и Truth Check это установленные агентские рабочие процессы, а не повседневные CLI-команды верхнего уровня.
+Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize и Truth Check это установленные агентские рабочие процессы, а не повседневные CLI-команды верхнего уровня.
 
 Они запускаются через настроенные поверхности хоста агента, например Codex/Claude/Copilot `/truthmark-*`, OpenCode `/skill truthmark-*` или Gemini `/truthmark:*`.
 
+Эти вызовы выглядят как команды, потому что агентские хосты предоставляют skills через slash-команды. Относитесь к ним как к инструкциям для агента, а не как к терминальным командам, которые должен запускать человек.
+
 ```text
 /truthmark-check проверь маршрутизацию и покрытие truth перед review
 ```
@@ -297,7 +297,7 @@ V1 сейчас предоставляет:
 - `truthmark impact`
 - `truthmark context`
 - управляемые инструкции рабочих процессов в `AGENTS.md`
-- сгенерированные skill-поверхности Truth Structure, Truth Document, Truth Sync, Truth Realize и Truth Check для настроенных агентских хостов
+- сгенерированные skill-поверхности Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize и Truth Check для настроенных агентских хостов
 - метаданные области ветки
 - диагностика конфигурации, полномочий, маршрутизации, структуры решений, frontmatter, ссылок и полиглотного покрытия
 - производные артефакты RepoIndex, RouteMap, ImpactSet и ContextPack для более быстрой локальной проверки, когда CLI доступен

package/README.zh.md

@@ -96,6 +96,7 @@ Truthmark 把仓库事实变成代理可见的显式工作流载体：
 - `docs/truthmark/areas.md` 和委托的子路由文件把代码区域映射到负责它们的文档。
 - Truth Document 在无需修改代码时，为已实现行为生成或修复规范事实文档。
 - Truth Sync 在功能性变更发生时，让已映射的事实文档保持同步。
+- Truth Preview 在编辑前预览可能的工作流路由，但不授权写入。
 - Truth Realize 为文档优先的变更提供有边界的代码更新路径。
 - `truthmark check` 验证最终形成的事实产物。
 - 整个模型保持本地优先和 Git 原生。
@@ -213,18 +214,25 @@ Codex、Claude Code 和支持的 Copilot IDE 可以用 `/truthmark-realize` 调
 
 Truthmark 把持久化的工作流载体保持得很小，而且是仓库原生的。运行 `truthmark init` 之后，仓库本身就携带路由、规则和已安装的工作流载体，因此团队不再只依赖某个人的本地配置。
 
+Truthmark 会安装两类不同入口：
+
+- 面向人的 CLI 命令，由人或 CI 运行，用来配置仓库、刷新已安装文件、验证 truth artifacts，并可选生成派生的审查上下文
+- 面向代理的工作流载体，由编码代理或代理宿主在实现工作流中调用；它们不是给人每天在终端里额外运行的命令
+
 - `.truthmark/config.yml`，用于机器可读的已提交层级契约
 - `docs/truthmark/areas.md`，用于根路由索引
 - `docs/truthmark/areas/**/*.md`，用于委托的子路由文件
 - `docs/templates/behavior-doc.md` 以及 `docs/templates/` 下其他按类型划分的模板，用作生成工作流采用的可编辑 truth doc 标准
 - 面向已配置平台的受管说明块，例如 `AGENTS.md`、`CLAUDE.md`、Copilot 指令和 `GEMINI.md`
-- 面向 Truth Structure、Truth Document、Truth Sync、Truth Realize 和 Truth Check 的宿主原生技能、提示或命令
+- 面向 Truth Structure、Truth Document、Truth Sync、Truth Preview、Truth Realize 和 Truth Check 的宿主原生技能、提示或命令
+- `.codex/agents/`、`.claude/agents/`、`.github/agents/` 和 `.opencode/agents/` 下项目级 Codex、Claude Code、GitHub Copilot 与 OpenCode 只读验证器，以及在宿主支持代理时使用的租约式 `truth-doc-writer` 代理，用于工作流自有审计和父代理租约授权的文档分片
 
 安装后的工作流载体就是运行时：
 
 - Truth Structure 创建或修复区域路由和起始事实文档。
 - Truth Document 为已实现行为创建或修复事实文档。
 - Truth Sync 在功能性变更发生时，让已映射的事实文档保持同步。
+- Truth Preview 在编辑前预览可能的工作流路由，但不写入文件。
 - Truth Realize 更新代码，使其符合事实文档。
 - Truth Check 审计仓库事实的健康状况。
 
@@ -234,38 +242,30 @@ Truthmark 把持久化的工作流载体保持得很小，而且是仓库原生
 
 ## 命令
 
-Truthmark V1 有意保持 CLI 很小，因为持续运行的工作流应该活在已安装的代理载体里，而不是一长串日常手动命令里。在下游仓库中，`truthmark config` 创建已提交的层级契约，`truthmark init` 根据这份已审查的配置安装和刷新工作流载体，`truthmark check` 则为人工审计、CI 或问题排查验证事实产物，而仓库情报命令会在有本地工具时生成派生审查产物。
+Truthmark V1 会保持终端 CLI 聚焦。大多数人类用户只需要设置、刷新和验证：
 
-```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` 只写入 `.truthmark/config.yml`，除非使用 `--stdout`。
-
-`init` 需要 `.truthmark/config.yml`，然后安装或刷新本地工作流文件。
+| 面向人的 CLI | 用途 |
+| ------------ | ---- |
+| `truthmark config` | 创建 `.truthmark/config.yml`；除非使用 `--stdout`，否则只写入这个文件。 |
+| `truthmark init` | 根据已审查配置安装或刷新本地工作流文件。 |
+| `truthmark check` | 验证配置、权限边界、路由、承载决策的文档、frontmatter、内部链接、分支范围和覆盖率诊断。 |
 
-`check` 验证配置、权限边界、路由、承载决策的文档、frontmatter、内部链接、分支范围和覆盖率诊断。
+其余 CLI 命令是可选的仓库情报辅助工具。它们为当前 checkout 生成派生审查上下文；它们不是事实来源：
 
-`index` 为当前 checkout 构建 RepoIndex 和 RouteMap JSON。
+| 可选 CLI | 用途 |
+| -------- | ---- |
+| `truthmark index` | 为当前 checkout 构建 RepoIndex 和 RouteMap JSON。 |
+| `truthmark impact --base <ref>` | 把变更文件映射到已路由的 truth docs、所属路由、附近测试和 public symbols。 |
+| `truthmark context --workflow <workflow> [--base <ref>]` | 为 Truth Sync、Truth Document 或 Truth Realize 生成受限的 ContextPack。`--format markdown` 会把它渲染成可读文本。 |
 
-`impact --base <ref>` 会把变更文件映射到已路由的 truth docs、所属路由、附近测试和 public symbols。
+上面所有 CLI 命令在需要结构化输出用于自动化时都支持 `--json`。
 
-`context --workflow <workflow> [--base <ref>]` 会为 Truth Sync、Truth Document 或 Truth Realize 生成一个受限的 ContextPack。`--format markdown` 会把它渲染成可读文本。
-
-Truth Structure、Truth Document、Truth Sync、Truth Realize 和 Truth Check 是已安装的代理工作流，不是日常使用的顶层 CLI 命令。
+Truth Structure、Truth Document、Truth Sync、Truth Preview、Truth Realize 和 Truth Check 是已安装的代理工作流，不是日常使用的顶层 CLI 命令。
 
 它们通过已配置的代理宿主表面运行，例如 Codex/Claude/Copilot 的 `/truthmark-*`、OpenCode 的 `/skill truthmark-*`，或者 Gemini 的 `/truthmark:*`。
 
+这些调用看起来像命令，是因为代理宿主会通过 slash commands 暴露技能。应把它们当作给代理的指令，而不是人类需要在终端中运行的 Truthmark CLI 命令。
+
 ```text
 /truthmark-check 在 review 前审计路由和 truth 覆盖
 ```
@@ -297,7 +297,7 @@ V1 目前提供：
 - `truthmark impact`
 - `truthmark context`
 - 受管的 `AGENTS.md` 工作流说明
-- 为已配置代理宿主生成的 Truth Structure、Truth Document、Truth Sync、Truth Realize 和 Truth Check 技能载体
+- 为已配置代理宿主生成的 Truth Structure、Truth Document、Truth Sync、Truth Preview、Truth Realize 和 Truth Check 技能载体
 - 分支范围元数据
 - 配置、权限边界、路由、决策结构、frontmatter、链接和多语言覆盖率诊断
 - RepoIndex、RouteMap、ImpactSet 和 ContextPack 派生产物，可在 CLI 可用时加快本地检查