truthmark 1.2.3 → 1.4.0

package/README.md

@@ -1,6 +1,6 @@
 # Truthmark
 
-**Truthmark automates truth maintenance 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)
 
@@ -8,14 +8,14 @@ English | [Deutsch](README.de.md) | [中文](README.zh.md) | [Español](README.e
 
 AI coding agents already write code fast. The expensive part is keeping repository truth aligned with what changed.
 
-Truthmark adds an automatic finish-time safeguard to that workflow. The normal path is simple:
+Truthmark adds a finish-time workflow guard to that workflow. The normal path is simple:
 
 - agent changes functional code
 - run relevant tests
-- Truth Sync updates mapped truth docs before the agent finishes
+- the installed Truth Sync workflow updates mapped truth docs before the agent finishes
 - review the truth-doc diff if one was produced
 
-Most tools ask teams to adopt a habit. Truthmark automates the habit.
+Most tools ask teams to adopt a habit. Truthmark turns the habit into repository workflow infrastructure.
 
 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.
 
@@ -51,12 +51,12 @@ For teams who already know agents can generate code, Truthmark answers the next
 
 Truthmark is not trying to make agents sound smarter. It is trying to make AI-assisted repository change easier to trust.
 
-- Automated truth sync after code changes turns documentation maintenance into a workflow safeguard instead of a team habit.
+- 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 model works across JavaScript, TypeScript, Go, Python, C#, and Java codebases.
+- 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.
 
@@ -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.
@@ -133,10 +134,10 @@ Review `.truthmark/config.yml` before `init`; it is the committed hierarchy cont
 .truthmark/config.yml
 docs/truthmark/areas.md
 docs/truthmark/areas/repository.md
-docs/templates/feature-doc.md
-docs/features/README.md
-docs/features/repository/README.md
-docs/features/repository/overview.md
+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
@@ -144,7 +145,7 @@ 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`.
 
@@ -171,22 +172,22 @@ 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/features/authentication
+/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 important behavior is that Truth Sync acts as an automatic finish-time safeguard when functional code changed. 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`.
 
@@ -212,55 +213,65 @@ 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/features/authentication/session-timeout.md into code
+/truthmark-realize realize docs/truth/authentication/session-timeout.md into code
 ```
 
 ## What it installs
 
 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/config.yml` for the committed hierarchy contract
+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/feature-doc.md` for the editable feature-doc standard used by generated workflows
+- `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.
 
-Feature `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.
+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 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, and `truthmark check` validates truth artifacts for manual audits, CI, or troubleshooting.
+Truthmark V1 keeps the terminal CLI focused. Most human users only need setup, refresh, and validation:
 
-```bash
-truthmark config
-truthmark init
-truthmark check
-truthmark config --json
-truthmark check --json
-```
+| 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. |
 
-`config` writes only `.truthmark/config.yml` unless `--stdout` is used.
+The remaining CLI commands are optional repository-intelligence helpers. They generate derived review context for the active checkout; they are not sources of truth:
 
-`init` requires `.truthmark/config.yml`, then installs or refreshes the local workflow files.
+| 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. |
 
-`check` validates configuration, authority, routing, decision-bearing docs, frontmatter, internal links, branch scope, and coverage diagnostics.
+All CLI commands above support `--json` where structured output is useful for automation.
 
-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
 ```
@@ -289,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 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, 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
 
@@ -300,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.

package/README.ru.md

@@ -1,6 +1,6 @@
 # Truthmark
 
-**Truthmark автоматизирует поддержку истины для разработки ПО с ИИ.**
+**Truthmark устанавливает рабочие процессы истины репозитория для разработки ПО с ИИ.**
 
 [English](README.md) | [Deutsch](README.de.md) | [中文](README.zh.md) | [Español](README.es.md) | Русский
 
@@ -8,14 +8,14 @@
 
 ИИ-агенты уже быстро пишут код. Дорогая часть — удерживать истину репозитория в соответствии с тем, что реально изменилось.
 
-Truthmark добавляет в этот процесс автоматическую финальную защиту. Обычный путь прост:
+Truthmark добавляет в этот процесс финальную защиту на уровне рабочего процесса. Обычный путь прост:
 
 - агент меняет функциональный код
 - запускаются релевантные тесты
-- Truth Sync обновляет связанные документы истины до завершения работы агента
+- установленный рабочий процесс Truth Sync обновляет связанные документы истины до завершения работы агента
 - если был создан diff документов истины, его проверяют
 
-Большинство инструментов просит команды выработать привычку. Truthmark автоматизирует эту привычку.
+Большинство инструментов просит команды выработать привычку. Truthmark превращает эту привычку в инфраструктуру рабочего процесса репозитория.
 
 Truthmark превращает ИИ-процесс в инфраструктуру репозитория, а не в персональный инструмент. Он устанавливает Git-native слой истины внутри репозитория, задает агентам явную маршрутизацию и ограниченные рабочие поверхности и сохраняет эту истину проверяемой в Git вместо того, чтобы разносить ее по истории промптов, устаревшей документации или приватному состоянию инструментов.
 
@@ -51,12 +51,12 @@ Truthmark превращает ИИ-процесс в инфраструктур
 
 Truthmark не пытается сделать так, чтобы агенты звучали умнее. Он пытается сделать изменения в репозитории, выполненные с помощью ИИ, более надежными.
 
-- Автоматический Truth Sync после изменений кода превращает поддержку документации в защиту рабочего процесса, а не в командную привычку.
+- Установленный Truth Sync после изменений кода превращает поддержку документации в защиту рабочего процесса, а не в командную привычку.
 - Истина, ограниченная веткой, движется вместе с кодом, поэтому ревьюеры могут проверять актуальную истину в обычных Git diff.
 - Рабочие поверхности, встроенные в репозиторий, упрощают внедрение и делают передачу работы устойчивее, чем одна лишь персональная настройка.
 - Явная маршрутизация в `docs/truthmark/areas.md` и делегированных дочерних файлах маршрутов дает агентам границы ответственности и более безопасные пути записи.
 - Local-first работа избавляет от зависимости на демон, базу данных, удаленный сервис или MCP.
-- Модель работает в кодовых базах на JavaScript, TypeScript, Go, Python, C# и Java.
+- Модель маршрутизации не зависит от языка и дает диагностику покрытия для распространенных поверхностей кода JavaScript, TypeScript, Go, Python, C# и Java.
 
 Для технических лидеров ценность в управлении без дополнительной инфраструктуры: тесты, ревью кода и владение зонами ответственности по-прежнему делают основную работу; Truthmark делает контекст агента долговечным, проверяемым и ограниченным веткой.
 
@@ -96,6 +96,7 @@ Truthmark превращает истину репозитория в явную
 - `docs/truthmark/areas.md` и делегированные дочерние файлы маршрутов сопоставляют области кода с документами, которые за них отвечают.
 - Truth Document создает или исправляет канонические документы истины для уже реализованного поведения, когда изменение кода не нужно.
 - Truth Sync поддерживает синхронизацию сопоставленных документов истины при функциональных изменениях.
+- Truth Preview предварительно показывает вероятную маршрутизацию рабочего процесса до правок, не авторизуя записи.
 - Truth Realize дает изменениям, начинающимся с документации, ограниченный путь для обновления кода.
 - `truthmark check` валидирует получившиеся артефакты истины.
 - Вся модель остается local-first и Git-native.
@@ -132,17 +133,17 @@ node /path/to/truthmark/dist/main.js check
 .truthmark/config.yml
 docs/truthmark/areas.md
 docs/truthmark/areas/repository.md
-docs/templates/feature-doc.md
-docs/features/README.md
-docs/features/repository/README.md
-docs/features/repository/overview.md
+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
 ```
 
 Поддерживаемые платформы: `codex`, `opencode`, `claude-code`, `github-copilot` и `gemini-cli`. Конфигурация по умолчанию включает их все; удалите из `.truthmark/config.yml` платформы, которыми не пользуетесь, перед повторным запуском `truthmark init`.
-Стандартная шаблонная структура использует `README.md` функциональных разделов как индексы и начинает описывать истину текущего поведения в ограниченных листовых документах, например `docs/features/repository/overview.md`.
+Стандартная шаблонная структура использует truth-`README.md` как индексы и начинает описывать истину текущего поведения в ограниченных листовых документах, например `docs/truth/repository/overview.md`.
 
 Существующим репозиториям обычно нужен один этап очистки после `init`: запустите установленный рабочий процесс Truth Structure, если созданный маршрут `repository` слишком широкий, владение охватывает несколько продуктов или сервисов, либо файлы маршрутов все еще указывают на документы-заглушки. Truth Structure разделяет широкие маршруты, создает или исправляет начальные канонические документы истины и дает Truth Sync точные цели до начала работы с функциональным кодом. Codex, Claude Code и поддерживаемые IDE Copilot могут вызвать его через `/truthmark-structure`; хосты в стиле OpenCode могут использовать `/skill truthmark-structure`.
 
@@ -150,51 +151,88 @@ GEMINI.md
 
 Сильная сторона Truthmark — путь по умолчанию, а не набор ручных команд. Действующий агент и среда хоста сами решают, делегировать работу или выполнить установленный процесс на месте.
 
-Используйте Truth Document, когда поведение уже реализовано, но канонические документы истины отсутствуют или слабы. Агент читает реализацию, тесты, маршруты и существующие документы, пишет только документы истины и маршруты и не должен менять функциональный код. Codex, Claude Code и поддерживаемые IDE Copilot могут вызывать его через `/truthmark-document`; хосты в стиле OpenCode могут использовать `/skill truthmark-document`.
+### Существующее поведение без документации
 
-Большинству пользователей не нужно вызывать Truth Sync напрямую. Главное, что Truth Sync работает как автоматическая финальная защита, когда менялся функциональный код. Нормальный путь выглядит так:
+Используйте это, когда реализация уже есть, но канонические документы истины отсутствуют или слабы:
+
+```text
+пользователь определяет реализованное поведение или api-эндпоинт
+пользователь явно вызывает truth document
+агент читает реализацию, тесты, маршрутизацию и существующие docs
+агент пишет только truth docs и маршрутизацию
+проверить diff truth docs
+```
+
+Truth Document — это ручной процесс с приоритетом реализации: код служит доказательством, документы истины создаются или исправляются, и функциональный код менять нельзя. Codex, Claude Code и поддерживаемые IDE Copilot могут вызывать его через `/truthmark-document`; хосты в стиле OpenCode могут использовать `/skill truthmark-document`.
+
+```text
+/truthmark-document документирует реализованное поведение session timeout в docs/truth/authentication
+```
+
+### Обычные изменения кода
+
+Большинству пользователей не нужно напрямую вызывать Truth Sync. Главное, что установленный агентский процесс рассматривает Truth Sync как финальную защиту, когда менялся функциональный код. Нормальный путь выглядит так:
 
 ```text
 агент изменяет функциональный код
 запускаются релевантные тесты
-Truth Sync срабатывает до завершения работы агента
-если был создан diff документов истины, он проверяется
+установленный truth sync workflow запускается до завершения агента
+если был создан diff truth docs, он проверяется
 работа коммитится или передается дальше
 ```
 
-Truth Sync работает по принципу code-first: сначала идет код, затем документы истины, и Truth Sync не должен переписывать функциональный код. Его основная задача быть автоматической финальной проверкой, когда менялся функциональный код. Прямой вызов нужен в основном для отладки, ранней синхронизации перед передачей работы или намеренного запуска рабочего процесса.
+Truth Sync работает по принципу code-first: сначала идет код, затем документы истины, и Truth Sync не должен переписывать функциональный код. Его основная задача - выполняться через установленный агентский процесс как финальная защита, когда менялся функциональный код. Прямой вызов нужен в основном для отладки, ранней синхронизации перед передачей работы или намеренного запуска рабочего процесса.
+
 Codex, Claude Code и поддерживаемые IDE Copilot могут вызывать его через `/truthmark-sync`. Хосты в стиле OpenCode могут использовать `/skill truthmark-sync`.
+
+```text
+/truthmark-sync синхронизируй истину репозитория прямо сейчас перед передачей
+```
+
+### Doc-first изменения
+
 Используйте этот путь, когда продуктовое или архитектурное решение начинается в документации:
 
 ```text
-пользователь редактирует документы истины
-пользователь явно вызывает Truth Realize
-агент читает документы истины и связанный код
+пользователь редактирует truth docs
+пользователь явно вызывает truth realize
+агент читает truth docs и связанный код
 агент обновляет только код
 запускаются релевантные тесты
 работа коммитится или передается дальше
 ```
 
-Truth Realize это ручной процесс по принципу doc-first: документы истины идут первыми, код следует за ними, и агент не должен редактировать документы истины, которые он реализует.
+Truth Realize — это ручной doc-first процесс: документы истины идут первыми, код следует за ними, и агент не должен редактировать документы истины, которые он реализует.
+
 Codex, Claude Code и поддерживаемые IDE Copilot могут вызывать его через `/truthmark-realize`. Хосты в стиле OpenCode могут использовать `/skill truthmark-realize`.
 
+```text
+/truthmark-realize реализуй docs/truth/authentication/session-timeout.md в код
+```
+
 ## Что он устанавливает
 
 Truthmark держит постоянную рабочую поверхность маленькой и встроенной в репозиторий. После `truthmark init` сам репозиторий несет маршрутизацию, правила и установленные рабочие поверхности, поэтому команда не зависит только от локальной настройки одного человека.
 
-- `.truthmark/config.yml` для машиночитаемой конфигурации
-- `.truthmark/config.yml` для зафиксированного контракта иерархии
+Truthmark устанавливает два разных интерфейса:
+
+- CLI-команды для людей, которые запускают люди или CI, чтобы настроить репозиторий, обновить установленные файлы, проверить артефакты истины и при необходимости создать производный контекст для ревью
+- агентские рабочие поверхности, которые вызывают coding agents или агентские хосты во время реализации; это не дополнительные ежедневные терминальные команды для людей
+
+- `.truthmark/config.yml` для машиночитаемого зафиксированного контракта иерархии
 - `docs/truthmark/areas.md` для корневого индекса маршрутов
 - `docs/truthmark/areas/**/*.md` для делегированных дочерних файлов маршрутов
-- `docs/templates/feature-doc.md` для редактируемого стандарта feature-документов, используемого сгенерированными рабочими процессами
+- `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 аудитирует здоровье истины репозитория.
 
@@ -204,20 +242,33 @@ Truthmark держит постоянную рабочую поверхност
 
 ## Команды
 
-Truthmark V1 намеренно держит CLI небольшим, потому что постоянный рабочий процесс должен жить в установленных агентских поверхностях, а не в длинном списке ежедневных ручных команд. В нижестоящих репозиториях `truthmark config` создает зафиксированный контракт иерархии, `truthmark init` устанавливает и обновляет рабочие поверхности на основе этой проверенной конфигурации, а `truthmark check` валидирует артефакты истины для ручных аудитов, CI или отладки.
+Truthmark V1 держит терминальный CLI сфокусированным. Большинству людей нужны только настройка, обновление и проверка:
 
-```bash
-truthmark config
-truthmark init
-truthmark check
-truthmark config --json
-truthmark check --json
-```
+| CLI-команда для людей | Назначение |
+| --------------------- | ---------- |
+| `truthmark config` | Создает `.truthmark/config.yml`; пишет только этот файл, если не используется `--stdout`. |
+| `truthmark init` | Устанавливает или обновляет локальные файлы рабочих процессов из проверенной конфигурации. |
+| `truthmark check` | Валидирует конфигурацию, полномочия, маршрутизацию, документы с решениями, frontmatter, внутренние ссылки, область действия ветки и диагностику покрытия. |
+
+Остальные CLI-команды - необязательные помощники репозиторной аналитики. Они создают производный контекст для ревью активного checkout; они не являются источниками истины:
 
-`config` пишет только `.truthmark/config.yml`, если не используется `--stdout`.
-`init` требует `.truthmark/config.yml`, а затем устанавливает или обновляет локальные файлы рабочих процессов.
-`check` валидирует конфигурацию, полномочия, маршрутизацию, документы с решениями, frontmatter, внутренние ссылки, область действия ветки и диагностику покрытия.
-Truth Structure, Truth Document, Truth Sync, Truth Realize и Truth Check это установленные агентские рабочие процессы, а не повседневные CLI-команды верхнего уровня.
+| Необязательная 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` рендерит его в читаемый человеком вид. |
+
+Все CLI-команды выше поддерживают `--json`, когда структурированный вывод полезен для автоматизации.
+
+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
+```
 
 ## Зачем он существует
 
@@ -236,15 +287,20 @@ Truth Structure, Truth Document, Truth Sync, Truth Realize и Truth Check это
 ## Статус проекта
 
 Truthmark не является сервером памяти и не является MCP-сервером. Это репозиторная практика, упакованная как небольшой CLI-установщик и родные для агентов рабочие поверхности, которые превращают правила ИИ-процесса в инфраструктуру репозитория.
+
 V1 сейчас предоставляет:
 
 - `truthmark config`
 - `truthmark init`
 - `truthmark check`
+- `truthmark index`
+- `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 доступен
 
 ## Документация
 
@@ -252,10 +308,10 @@ V1 сейчас предоставляет:
 
 - [Индекс документации](docs/README.md)
 - [Обзор архитектуры](docs/architecture/overview.md)
-- [Контракты API и CLI](docs/features/contracts.md)
-- [Поведение init и scaffold](docs/features/init-and-scaffold.md)
-- [Диагностика check](docs/features/check-diagnostics.md)
-- [Установленные workflow](docs/features/installed-workflows.md)
+- [Контракты API и CLI](docs/truth/contracts.md)
+- [Поведение init и scaffold](docs/truth/init-and-scaffold.md)
+- [Диагностика check](docs/truth/check-diagnostics.md)
+- [Установленные workflow](docs/truth/workflows/overview.md)
 - [Руководство по поддержанию истины репозитория](docs/standards/maintaining-repository-truth.md)
 
 Текущее поведение должно жить в каноническом дереве документации выше.