truthmark 1.4.0 → 1.5.0

package/README.ru.md

@@ -1,294 +1,640 @@
 # Truthmark
 
-**Truthmark устанавливает рабочие процессы истины репозитория для разработки ПО с ИИ.**
+**Ваши агенты пишут код. Truthmark делает их контекст проверяемым в Git.**
 
 [English](README.md) | [Deutsch](README.de.md) | [中文](README.zh.md) | [Español](README.es.md) | Русский
 
-<img src="docs/assets/truthmark-banner.png" alt="Баннер Truthmark" width="100%" />
+![Баннер Truthmark](docs/assets/truthmark-banner.png)
 
-ИИ-агенты уже быстро пишут код. Дорогая часть — удерживать истину репозитория в соответствии с тем, что реально изменилось.
+ИИ-агенты для разработки могут менять репозиторий быстрее, чем люди успевают выравнивать его контекст.
 
-Truthmark добавляет в этот процесс финальную защиту на уровне рабочего процесса. Обычный путь прост:
+Truthmark чинит ту часть, которая обычно ломается после написания кода: истину репозитория.
 
-- агент меняет функциональный код
-- запускаются релевантные тесты
-- установленный рабочий процесс Truth Sync обновляет связанные документы истины до завершения работы агента
-- если был создан diff документов истины, его проверяют
+Он устанавливает Git-native, ограниченный веткой слой рабочего процесса, который помогает ИИ-агентам обновлять правильные документы, соблюдать границы владения и оставлять людям обычные diff для ревью.
 
-Большинство инструментов просит команды выработать привычку. Truthmark превращает эту привычку в инфраструктуру рабочего процесса репозитория.
+Без размещенного сервиса.
 
-Truthmark превращает ИИ-процесс в инфраструктуру репозитория, а не в персональный инструмент. Он устанавливает Git-native слой истины внутри репозитория, задает агентам явную маршрутизацию и ограниченные рабочие поверхности и сохраняет эту истину проверяемой в Git вместо того, чтобы разносить ее по истории промптов, устаревшей документации или приватному состоянию инструментов.
+Без базы данных.
 
-Это важно, потому что процесс живет вместе с веткой. После инициализации репозитория правила, маршрутизация и установленные рабочие поверхности путешествуют внутри репозитория, поэтому совместная работа и передача задач меньше зависят от локальной настройки одного человека.
+Без скрытого слоя памяти.
 
-Для команд, которые уже знают, что агенты умеют генерировать код, Truthmark решает следующую проблему: как сделать так, чтобы сам репозиторий оставался понятным, проверяемым и управляемым по мере роста ИИ-ассистированной разработки.
+Без дополнительного сервера в эксплуатации.
 
-## Визуальный обзор
+Только истина репозитория, которая движется вместе с веткой.
 
-<table>
-	<tr>
-		<td align="center" width="50%">
-			<img src="docs/assets/truthmark-features.png" alt="Возможности Truthmark" width="100%" />
-			<br><strong>Возможности</strong><br>
-			Что устанавливает Truthmark и как устроена рабочая поверхность.
-		</td>
-		<td align="center" width="50%">
-			<img src="docs/assets/truthmark-position.png" alt="Позиционирование Truthmark" width="100%" />
-			<br><strong>Позиционирование</strong><br>
-			Где Truthmark находится относительно промптов, памяти и spec-first процессов.
-		</td>
-	</tr>
-	<tr>
-		<td align="center" colspan="2">
-			<img src="docs/assets/truthmark-syncflow.png" alt="Поток sync в Truthmark" width="100%" />
-			<br><strong>Поток sync</strong><br>
-			Как Truth Sync закрывает обычные изменения кода перед передачей работы.
-		</td>
-	</tr>
-</table>
-
-## Почему команды выбирают Truthmark
-
-Truthmark не пытается сделать так, чтобы агенты звучали умнее. Он пытается сделать изменения в репозитории, выполненные с помощью ИИ, более надежными.
-
-- Установленный Truth Sync после изменений кода превращает поддержку документации в защиту рабочего процесса, а не в командную привычку.
-- Истина, ограниченная веткой, движется вместе с кодом, поэтому ревьюеры могут проверять актуальную истину в обычных Git diff.
-- Рабочие поверхности, встроенные в репозиторий, упрощают внедрение и делают передачу работы устойчивее, чем одна лишь персональная настройка.
-- Явная маршрутизация в `docs/truthmark/areas.md` и делегированных дочерних файлах маршрутов дает агентам границы ответственности и более безопасные пути записи.
-- Local-first работа избавляет от зависимости на демон, базу данных, удаленный сервис или MCP.
-- Модель маршрутизации не зависит от языка и дает диагностику покрытия для распространенных поверхностей кода JavaScript, TypeScript, Go, Python, C# и Java.
-
-Для технических лидеров ценность в управлении без дополнительной инфраструктуры: тесты, ревью кода и владение зонами ответственности по-прежнему делают основную работу; Truthmark делает контекст агента долговечным, проверяемым и ограниченным веткой.
+## Проблема
 
-## Где уместен Truthmark
+ИИ-агенты для разработки хорошо создают код. Это порождает новый режим отказа.
+
+Реализация меняется, но история репозитория начинает расходиться:
+
+- поведение живет в истории чата
+- архитектурные документы отстают
+- продуктовые решения исчезают после передачи работы
+- ревьюеры видят diff кода без связанных diff истины
+- ветки незаметно развивают разные версии того, «что является правдой»
+- каждой сессии агента приходится заново открывать контекст
+
+Truthmark превращает этот хрупкий контекст в зафиксированную инфраструктуру репозитория.
 
-Truthmark не является универсальным набором ИИ-инструментов для продуктивности. Он занимает конкретный слой в стеке: проверяемая истина репозитория, ограниченная веткой и выровненная с реализацией.
+Вместо надежды на то, что каждый человек и каждый агент вспомнят правильную привычку документирования, Truthmark устанавливает эту привычку в репозиторий.
 
-| Если вам нужно                                                                                   | Лучший выбор                                   |
-| ------------------------------------------------------------------------------------------------ | ---------------------------------------------- |
-| Лучшие результаты в одной сессии разработки                                                      | Более точные промпты и лучше очерченная задача |
-| Удобная преемственность между сессиями для одного агента или оператора                           | Инструменты памяти                             |
-| Spec-first планирование новых функций                                                            | Инструменты спецификаций, например Spec Kit    |
-| Проверяемая истина репозитория с областью действия в пределах ветки, которая идет вместе с кодом | Truthmark                                      |
+## Обещание
 
-Смысл не в том, что промпты, память или спецификации бесполезны. Смысл в том, что ни один из этих подходов сам по себе не превращает истину репозитория в зафиксированный в Git, проверяемый актив, который переживает передачу работы, ревью и расхождение веток.
+Когда агент меняет функциональный код, работа не должна заканчиваться только diff кода.
 
-## Содержание
+Обычный путь Truthmark:
+
+```text
+агент меняет функциональный код
+запускаются релевантные тесты
+Truth Sync проверяет сопоставленные документы истины
+документы истины обновляются при необходимости
+человек проверяет diff кода + diff истины
+коммит или передача работы
+```
 
-- [Почему команды выбирают Truthmark](#почему-команды-выбирают-truthmark)
-- [Что решает Truthmark](#что-решает-truthmark)
-- [Где уместен Truthmark](#где-уместен-truthmark)
-- [Начало работы](#начало-работы)
-- [Как он работает](#как-он-работает)
-- [Что он устанавливает](#что-он-устанавливает)
-- [Команды](#команды)
-- [Зачем он существует](#зачем-он-существует)
-- [Статус проекта](#статус-проекта)
-- [Документация](#документация)
-- [Не-цели](#не-цели)
-- [Лицензия](#лицензия)
+Главная ценность такова: **ИИ-работе легче доверять, потому что репозиторий остается понятным.**
 
-## Что решает Truthmark
+## Две поверхности, одна система истины
 
-Truthmark превращает истину репозитория в явную рабочую поверхность для агентов:
+Truthmark — это не только CLI.
 
-- `.truthmark/config.yml` определяет зафиксированный контракт иерархии.
-- `docs/truthmark/areas.md` и делегированные дочерние файлы маршрутов сопоставляют области кода с документами, которые за них отвечают.
-- Truth Document создает или исправляет канонические документы истины для уже реализованного поведения, когда изменение кода не нужно.
-- Truth Sync поддерживает синхронизацию сопоставленных документов истины при функциональных изменениях.
-- Truth Preview предварительно показывает вероятную маршрутизацию рабочего процесса до правок, не авторизуя записи.
-- Truth Realize дает изменениям, начинающимся с документации, ограниченный путь для обновления кода.
-- `truthmark check` валидирует получившиеся артефакты истины.
-- Вся модель остается local-first и Git-native.
+У него две разные поверхности, и это различие важно.
 
-Главное обещание такое: контекст агента становится зафиксированным состоянием репозитория, а не приватным артефактом отдельной сессии.
+### 1. CLI для людей
 
-## Начало работы
+CLI предназначен для мейнтейнеров, ревьюеров и автоматизации.
 
-Установите Truthmark в репозитории, который хотите инициализировать:
+Используйте его, чтобы настроить репозиторий, установить или обновить файлы рабочих процессов, проверить артефакты истины и создать дополнительный контекст для ревью.
 
 ```bash
-cd /path/to/your-repo
-npm install -g truthmark
 truthmark config
 truthmark init
 truthmark check
 ```
 
-Если вы хотите попробовать еще не выпущенные изменения из исходного checkout:
+CLI подготавливает и валидирует среду репозитория.
+
+Он не является runtime для ИИ-рабочего процесса.
+
+### 2. Поверхности рабочих процессов для ИИ
+
+Поверхности для ИИ предназначены для coding agents.
+
+Truthmark устанавливает host-native skills, prompts, commands, управляемые блоки инструкций и поддерживаемые поверхности subagents, чтобы ИИ-агенты могли следовать специфичным для репозитория truth-workflows внутри своих обычных инструментов разработки.
+
+Примеры:
+
+```text
+/truthmark-sync
+/truthmark-document
+/truthmark-structure
+/truthmark-realize
+/truthmark-preview
+/truthmark-check
+```
+
+Они выглядят как команды, потому что agent hosts раскрывают workflows через slash commands, prompts, skills или project commands.
+
+Это не shell-команды.
+
+Это точки входа workflow для ИИ.
+
+Разделение и есть продукт:
+
+```text
+люди владеют контрактом репозитория
+Truthmark устанавливает контракт в repo
+агенты работают внутри этого контракта
+обновления истины появляются как Git diff
+люди проверяют результат
+```
+
+## Быстрый старт
+
+### Требования
+
+- Node.js `>=20`
+- npm
+- Git-репозиторий
+
+### Установить Truthmark
+
+Выполните это внутри репозитория, который хотите инициализировать:
 
 ```bash
-cd /path/to/truthmark
-npm install
-npm run build
 cd /path/to/your-repo
-node /path/to/truthmark/dist/main.js config
-node /path/to/truthmark/dist/main.js init
-node /path/to/truthmark/dist/main.js check
+npm install -g truthmark
 ```
 
-Проверьте `.truthmark/config.yml` перед `init`; это зафиксированный в Git контракт иерархии. После `init` проверьте сгенерированную рабочую поверхность и файлы маршрутов, чтобы маршрутизированная документация действительно совпадала с документами, которые отвечают за ваш код:
+### Создать контракт истины репозитория
+
+```bash
+truthmark config
+```
+
+Это создает:
 
 ```text
 .truthmark/config.yml
-docs/truthmark/areas.md
-docs/truthmark/areas/repository.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`.
-Стандартная шаблонная структура использует 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`.
+### Установить поверхности рабочих процессов
 
-## Как он работает
+```bash
+truthmark init
+```
 
-Сильная сторона Truthmark — путь по умолчанию, а не набор ручных команд. Действующий агент и среда хоста сами решают, делегировать работу или выполнить установленный процесс на месте.
+Это устанавливает или обновляет:
 
-### Существующее поведение без документации
+- файлы маршрутов
+- scaffolding документов истины
+- управляемые блоки инструкций
+- поверхности рабочих процессов для ИИ для настроенных платформ
 
-Используйте это, когда реализация уже есть, но канонические документы истины отсутствуют или слабы:
+### Проверить настройку
 
-```text
-пользователь определяет реализованное поведение или api-эндпоинт
-пользователь явно вызывает truth document
-агент читает реализацию, тесты, маршрутизацию и существующие docs
-агент пишет только truth docs и маршрутизацию
-проверить diff truth docs
+```bash
+truthmark check
 ```
 
-Truth Document — это ручной процесс с приоритетом реализации: код служит доказательством, документы истины создаются или исправляются, и функциональный код менять нельзя. Codex, Claude Code и поддерживаемые IDE Copilot могут вызывать его через `/truthmark-document`; хосты в стиле OpenCode могут использовать `/skill truthmark-document`.
+Затем проверьте сгенерированные файлы перед коммитом.
+
+Точный набор файлов зависит от `.truthmark/config.yml`, но форма установки всегда одна: routing, truth scaffolding, компактные managed instructions и host-native workflow surfaces для включённых платформ.
+
+## Первое реальное использование
+
+Большинству репозиториев после инициализации нужен один этап очистки.
+
+Стандартный scaffold начинается с широкого area `repository`. Реальным репозиториям обычно нужна более точная маршрутизация.
+
+Попросите агента разделить широкий маршрут на реальные области продукта, сервиса, домена или владения:
 
 ```text
-/truthmark-document документирует реализованное поведение session timeout в docs/truth/authentication
+/truthmark-structure раздели широкий repository area на auth, billing и notifications
 ```
 
-### Обычные изменения кода
+После этого используйте своего ИИ-агента для разработки как обычно.
+
+Когда агент меняет функциональный код, Truth Sync действует как финальная защита, которая перед передачей работы проверяет, должны ли измениться сопоставленные документы истины.
+
+## Что вы получаете
+
+| Возможность | Что она делает |
+| --- | --- |
+| Git-native истина | Хранит истину репозитория в зафиксированных Markdown и config. |
+| Контекст в пределах ветки | Истина движется с веткой вместо жизни в приватной сессии. |
+| CLI для людей | Дает мейнтейнерам команды настройки, обновления, валидации и инспекции. |
+| Workflows для ИИ | Дает агентам host-native workflows для sync, documentation, structure, preview, realization и audit. |
+| Явная маршрутизация | Сопоставляет области кода с каноническими документами истины. |
+| Проверяемые передачи работы | Создает обычные Git diff для кода и документов истины. |
+| Local-first работа | Не требует размещенного сервиса, daemon, базы данных или MCP-сервера. |
+| Более безопасные границы записи | Разделяет code-first, doc-first, read-only и doc-only workflows. |
+| Валидация | Сообщает о проблемах маршрутизации, authority, frontmatter, ссылок, generated surfaces, branch scope, freshness и coverage. |
+
+## Визуальный обзор
+
+![Возможности Truthmark](docs/assets/truthmark-features.png)
+
+**Возможности:** что устанавливает Truthmark и как разделена поверхность workflow.
+
+![Позиционирование Truthmark](docs/assets/truthmark-position.png)
+
+**Позиция:** где Truthmark находится относительно prompts, memory и spec workflows.
+
+![Поток sync Truthmark](docs/assets/truthmark-syncflow.png)
+
+**Поток sync:** как Truth Sync закрывает обычные изменения кода перед передачей.
+
+## Почему команды выбирают его
+
+Truthmark предназначен для команд, которые уже знают, что ИИ-агенты могут генерировать код.
+
+Следующая проблема — governance.
+
+Не governance как церемония. Governance как простой вопрос:
+
+> После этого ИИ-ассистированного изменения репозиторий все еще говорит правду?
 
-Большинству пользователей не нужно напрямую вызывать Truth Sync. Главное, что установленный агентский процесс рассматривает Truth Sync как финальную защиту, когда менялся функциональный код. Нормальный путь выглядит так:
+Truthmark помогает командам отвечать на это с помощью зафиксированных файлов, явной маршрутизации и проверяемых diff.
+
+Он полезен, когда нужны:
+
+- меньший дрейф документации
+- лучшие передачи работы
+- продуктовая истина, специфичная для ветки
+- долговечный архитектурный и API-контекст
+- явное владение между документацией и кодом
+- более безопасные границы записи для агентов
+- проверяемый контекст вместо скрытой памяти
+- ИИ-workflows, которые продолжают работать из зафиксированных файлов repo
+
+## Где уместен Truthmark
+
+Truthmark не заменяет prompts, memory, specs, tests или code review.
+
+Он дает этим workflows долговечное место в Git.
+
+| Потребность | Лучше подходит |
+| --- | --- |
+| Лучший результат из одной сессии агента | Лучший prompt |
+| Персональная или сессионная преемственность | Memory tool |
+| Работа над функцией plan-first | Spec workflow |
+| Истина в пределах ветки, которая путешествует с кодом | Truthmark |
+| Проверка корректности поведения | Tests and review |
+| Ревью контекстных изменений, выполненных с ИИ | Truthmark plus Git review |
+
+Область Truthmark намеренно узкая:
 
 ```text
-агент изменяет функциональный код
-запускаются релевантные тесты
-установленный truth sync workflow запускается до завершения агента
-если был создан diff truth docs, он проверяется
-работа коммитится или передается дальше
+сделать истину репозитория явной
+связать ее с кодом
+установить вокруг нее workflows агентов
+сохранить результат проверяемым в Git
+```
+
+## Как работает Truthmark
+
+Truthmark работает локально с активным Git worktree.
+
+CLI для людей читает и записывает файлы репозитория, а затем завершается.
+
+Поверхности рабочих процессов для ИИ — это зафиксированные файлы, которые agent hosts могут загрузить позже. Поэтому агенты могут следовать установленному workflow из состояния репозитория, не завися от фонового процесса Truthmark.
+
+Эти слои связаны так:
+
+```mermaid
+flowchart LR
+  Human["Human / CI"] --> CLI["Truthmark CLI"]
+  CLI --> Config["Config и routing"]
+  CLI --> Truth["Канонические truth docs"]
+  CLI --> Surfaces["Сгенерированные host-native workflows"]
+  Surfaces --> Hosts["Codex / Claude Code / Copilot / OpenCode / Gemini"]
+  Hosts --> Worktree["Активный Git worktree"]
+  Hosts -->|"helper checks / validate / index"| CLI
+  Worktree --> Truth
 ```
 
-Truth Sync работает по принципу code-first: сначала идет код, затем документы истины, и Truth Sync не должен переписывать функциональный код. Его основная задача - выполняться через установленный агентский процесс как финальная защита, когда менялся функциональный код. Прямой вызов нужен в основном для отладки, ранней синхронизации перед передачей работы или намеренного запуска рабочего процесса.
+Agents не подключаются к daemon Truthmark, но могут запускать установленный Truthmark CLI, когда workflow требует validation, indexing или helper checks.
+
+Truthmark владеет сгенерированными workflow surfaces, но главный контракт архитектурный: repo-local config и routing направляют agents к каноническим truth docs, а host-native workflows дают каждому поддерживаемому agent способ выполнять одни и те же процедуры Truthmark.
+
+Сгенерированные поверхности workflow включают маркеры версии Truthmark. После обновления Truthmark снова выполните:
+
+```bash
+truthmark init
+```
+
+Затем проверьте сгенерированные diff.
+
+## Поддерживаемые платформы агентов
+
+Конфигурация по умолчанию включает все поддерживаемые платформы.
+
+Удалите платформы, которыми не пользуетесь, из `.truthmark/config.yml`, затем снова выполните:
+
+```bash
+truthmark init
+```
+
+| Имя платформы в config | Сгенерированная поверхность | Форма вызова |
+| --- | --- | --- |
+| `codex` | `.codex/skills/truthmark-*/`, `.codex/agents/` | `/truthmark-*` или `$truthmark-*` |
+| `claude-code` | `.claude/skills/truthmark-*/`, `.claude/agents/`, `CLAUDE.md` | `/truthmark-*` |
+| `github-copilot` | `.github/skills/truthmark-*/`, `.github/prompts/`, `.github/agents/`, `.github/copilot-instructions.md` | `/truthmark-*` в поддерживаемых Copilot IDE; custom agents `@truth-*` в Copilot CLI |
+| `opencode` | `.opencode/skills/truthmark-*/`, `.opencode/agents/` | `/skill truthmark-*` |
+| `gemini-cli` | `.gemini/skills/truthmark-*/`, `.gemini/commands/truthmark/`, `.gemini/agents/`, `GEMINI.md` | `/truthmark:*` |
+
+Неизвестные имена платформ являются ошибками config.
 
-Codex, Claude Code и поддерживаемые IDE Copilot могут вызывать его через `/truthmark-sync`. Хосты в стиле OpenCode могут использовать `/skill truthmark-sync`.
+Удаление платформы останавливает будущие обновления для нее. Оно не удаляет ранее сгенерированные файлы.
+
+## Workflows для ИИ
+
+Эти workflows устанавливаются в поддерживаемые ИИ coding hosts.
+
+Они используются агентами или agent hosts во время работы с репозиторием. Это не shell-команды верхнего уровня.
+
+| Workflow | Направление | Когда использовать | Граница записи |
+| --- | --- | --- | --- |
+| Truth Structure | topology-first | Стандартный маршрут слишком широкий, владение охватывает несколько областей или файлы маршрутов все еще указывают на placeholders. | Создает или чинит routing и стартовые документы истины. |
+| Truth Document | implementation-first | Поведение уже есть в коде, но канонические документы истины отсутствуют или слабы. | Пишет только документы истины и routing. Функциональный код менять нельзя. |
+| Truth Sync | code-first | Функциональный код изменился, и сопоставленные документы истины могут потребовать обновления перед передачей. | Обновляет документы истины. Truth Sync не должен переписывать функциональный код. |
+| Truth Preview | read-only | Агенту нужно предварительно понять вероятный routing перед правками. | Только чтение. Не авторизует записи. |
+| Truth Realize | doc-first | Продуктовые или архитектурные документы истины ведут, и код нужно обновить под них. | Обновляет только код. Агент не должен редактировать документы истины, которые реализует. |
+| Truth Check | audit-first | Ревьюеру или агенту нужно проверить здоровье истины репозитория. | Аудитирует и сообщает. |
+
+### Важное различие
+
+Не путайте эти две поверхности:
+
+| Поверхность | Используется | Пример | Значение |
+| --- | --- | --- | --- |
+| CLI для людей | людьми, скриптами, CI-подобными проверками | `truthmark check` | Проверить артефакты истины репозитория из терминала. |
+| Workflow для ИИ | coding agents и agent hosts | `/truthmark-check` | Попросить агента выполнить установленный audit workflow. |
+
+Имена намеренно похожи, но поверхности разные.
+
+## Обычное изменение кода с помощью ИИ
+
+Большинству пользователей не нужно вручную вызывать Truth Sync каждый раз.
+
+Truth Sync — установленная финальная защита для изменений функционального кода.
+
+```text
+агент меняет функциональный код
+агент запускает или запрашивает релевантные тесты
+установленный workflow обнаруживает, что функциональный код изменился
+Truth Sync проверяет сопоставленные документы истины
+агент обновляет документы истины при необходимости
+человек проверяет diff кода + diff истины
+```
+
+Прямой вызов все равно полезен для отладки, принудительной ранней синхронизации или явной передачи работы:
 
 ```text
 /truthmark-sync синхронизируй истину репозитория прямо сейчас перед передачей
 ```
 
-### Doc-first изменения
+## Существующее поведение без docs
 
-Используйте этот путь, когда продуктовое или архитектурное решение начинается в документации:
+Используйте Truth Document, когда реализация уже существует, но истина репозитория неполна.
 
 ```text
-пользователь редактирует truth docs
-пользователь явно вызывает truth realize
-агент читает truth docs и связанный код
-агент обновляет только код
-запускаются релевантные тесты
-работа коммитится или передается дальше
+/truthmark-document задокументируй реализованное поведение session timeout в docs/truth/authentication
 ```
 
-Truth Realize — это ручной doc-first процесс: документы истины идут первыми, код следует за ними, и агент не должен редактировать документы истины, которые он реализует.
+Truth Document проверяет реализацию, тесты, файлы маршрутов и существующие docs как evidence.
+
+Он пишет только документы истины и routing.
 
-Codex, Claude Code и поддерживаемые IDE Copilot могут вызывать его через `/truthmark-realize`. Хосты в стиле OpenCode могут использовать `/skill truthmark-realize`.
+Он не должен менять функциональный код.
+
+## Doc-first изменения
+
+Используйте Truth Realize, когда продуктовое или архитектурное решение начинается в docs и код нужно обновить под него.
+
+```text
+/truthmark-realize реализуй docs/truth/authentication/session-timeout.md в коде
+```
+
+Truth Realize работает doc-first.
+
+Документы истины ведут. Код следует.
+
+Агент не должен редактировать документы истины, которые реализует.
+
+## Read-only preview маршрутизации
+
+Используйте Truth Preview перед изменением, когда агенту нужно понять вероятную маршрутизацию.
 
 ```text
-/truthmark-realize реализуй docs/truth/authentication/session-timeout.md в код
+/truthmark-preview покажи вероятный truth routing для изменений billing API
 ```
 
-## Что он устанавливает
+Truth Preview работает read-only.
 
-Truthmark держит постоянную рабочую поверхность маленькой и встроенной в репозиторий. После `truthmark init` сам репозиторий несет маршрутизацию, правила и установленные рабочие поверхности, поэтому команда не зависит только от локальной настройки одного человека.
+Это средство выбора и планирования, а не авторизация записи и не замена Truth Check.
 
-Truthmark устанавливает два разных интерфейса:
+## Аудит истины репозитория
 
-- CLI-команды для людей, которые запускают люди или CI, чтобы настроить репозиторий, обновить установленные файлы, проверить артефакты истины и при необходимости создать производный контекст для ревью
-- агентские рабочие поверхности, которые вызывают coding agents или агентские хосты во время реализации; это не дополнительные ежедневные терминальные команды для людей
+Используйте Truth Check, когда нужен audit workflow для агента.
 
-- `.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 Preview, Truth Realize и Truth Check
-- проектные проверяющие агенты Codex, Claude Code, GitHub Copilot и OpenCode в режиме только чтения, а также leased-агенты `truth-doc-writer` там, где хост поддерживает агентов, под `.codex/agents/`, `.claude/agents/`, `.github/agents/` и `.opencode/agents/` для аудитов, которыми владеет рабочий процесс, и для документных шардов, выданных родительским агентом
+```text
+/truthmark-check проверь routing и truth coverage перед review
+```
 
-Установленные рабочие поверхности и есть среда выполнения:
+Используйте CLI для людей, когда нужна terminal validation:
 
-- Truth Structure создает или исправляет маршрутизацию областей и стартовые документы истины.
-- Truth Document создает или исправляет документы истины для уже реализованного поведения.
-- Truth Sync поддерживает синхронизацию сопоставленных документов истины с функциональными изменениями.
-- Truth Preview предварительно показывает вероятную маршрутизацию рабочего процесса до правок без записи файлов.
-- Truth Realize обновляет код так, чтобы он соответствовал документам истины.
-- Truth Check аудитирует здоровье истины репозитория.
+```bash
+truthmark check
+```
 
-`README.md` функциональных разделов это индексы. Ожидается, что Truth Sync будет читать и обновлять ограниченные листовые документы для текущего поведения. Сгенерированные рабочие поверхности сохраняют приоритет правил репозитория, рассматривая код реализации и канонические документы истины как свидетельства текущего поведения.
+Оба варианта полезны. Это не одна и та же поверхность.
 
-Сгенерированные поверхности управляются Truthmark, содержат маркер версии и могут обновляться через `truthmark init`.
+## CLI-команды для людей
 
-## Команды
+Большинство мейнтейнеров начинают с трех команд.
 
-Truthmark V1 держит терминальный CLI сфокусированным. Большинству людей нужны только настройка, обновление и проверка:
+| Команда | Назначение |
+| --- | --- |
+| `truthmark config` | Создает `.truthmark/config.yml`. Пишет только этот файл, если не используется `--stdout`. |
+| `truthmark init` | Устанавливает или обновляет настроенные поверхности workflow из проверенной config. |
+| `truthmark check` | Валидирует config, authority, routing, документы с decisions, frontmatter, внутренние ссылки, branch scope, generated surfaces, freshness и coverage diagnostics. |
 
-| CLI-команда для людей | Назначение |
-| --------------------- | ---------- |
-| `truthmark config` | Создает `.truthmark/config.yml`; пишет только этот файл, если не используется `--stdout`. |
-| `truthmark init` | Устанавливает или обновляет локальные файлы рабочих процессов из проверенной конфигурации. |
-| `truthmark check` | Валидирует конфигурацию, полномочия, маршрутизацию, документы с решениями, frontmatter, внутренние ссылки, область действия ветки и диагностику покрытия. |
+Необязательные helpers repository-intelligence создают производный review context для активного checkout. Сгенерированные workflow skill packages также могут предоставлять helper manifests и helper policies, которые вызывают установленные CLI validators `truthmark validate ... --json`; эти helpers являются ускорителями, а не локальными скриптами, упакованными в репозиторий, и не источниками истины. Отдельные Copilot prompts и Gemini commands используют тот же CLI validator contract, когда установленный runner доступен; иначе они должны сообщать видимый skipped helper status и выполнять manual validation.
 
-Остальные CLI-команды - необязательные помощники репозиторной аналитики. Они создают производный контекст для ревью активного 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` рендерит его в читаемый человеком вид. |
+| `truthmark context --workflow <workflow> [--base <ref>]` | Генерирует ограниченный ContextPack для Truth Sync, Truth Document или Truth Realize. Используйте `--format markdown` для человекочитаемой версии. |
 
-Все CLI-команды выше поддерживают `--json`, когда структурированный вывод полезен для автоматизации.
+Структурированный вывод доступен с `--json` там, где поддерживается.
 
-Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize и Truth Check это установленные агентские рабочие процессы, а не повседневные CLI-команды верхнего уровня.
+## Конфигурация
 
-Они запускаются через настроенные поверхности хоста агента, например Codex/Claude/Copilot `/truthmark-*`, OpenCode `/skill truthmark-*` или Gemini `/truthmark:*`.
+Truthmark работает config-first.
 
-Эти вызовы выглядят как команды, потому что агентские хосты предоставляют skills через slash-команды. Относитесь к ним как к инструкциям для агента, а не как к терминальным командам, которые должен запускать человек.
+Главный config-файл:
 
 ```text
-/truthmark-check проверь маршрутизацию и покрытие truth перед review
+.truthmark/config.yml
 ```
 
-## Зачем он существует
+Новые репозитории должны выполнить:
 
-Большинство ИИ-процессов для разработки оптимизируют следующий ответ. Truthmark оптимизирует следующую передачу работы.
-Он исходит из того, что серьезным командам нужны:
+```bash
+truthmark config
+```
 
-- продуктовая истина, специфичная для ветки
-- долговечные архитектурные и API-решения
-- явная ответственность между документацией и кодом
-- безопасные границы записи для агентов
-- обычные Git diff, которые могут проверить люди
-- читаемый Markdown, который команда может просматривать без специальных инструментов
-- истина, которая путешествует вместе с веткой, а не живет в скрытом состоянии сессии
-- рабочие процессы, которые продолжают работать, даже если пакет не установлен глобально
+Затем проверить сгенерированную config перед запуском:
 
-## Статус проекта
+```bash
+truthmark init
+```
+
+Важные области config:
+
+| Область config | Назначение |
+| --- | --- |
+| `version` | Версия контракта config. |
+| `platforms` | Agent hosts, которые должны получить сгенерированные поверхности для платформы. |
+| `docs.layout` | Текущий режим layout документации. |
+| `docs.roots` | Именованные корни канонической документации. |
+| `docs.routing.root_index` | Путь к корневому индексу маршрутов. |
+| `docs.routing.area_files_root` | Директория для делегированных дочерних файлов маршрутов. |
+| `docs.routing.default_area` | Базовое имя начального scaffolded дочернего маршрута. |
+| `docs.routing.max_delegation_depth` | Текущая максимальная глубина делегирования routing. |
+| `authority` | Упорядоченные канонические docs и globs, используемые как authority истины репозитория. |
+| `instruction_targets` | Файлы, которые получают общие управляемые блоки инструкций, например `AGENTS.md`. |
+| `frontmatter.required` | Поля metadata, которые создают error diagnostics при отсутствии. |
+| `frontmatter.recommended` | Поля metadata, которые создают review diagnostics при отсутствии. |
+| `ignore` | Glob-паттерны, исключенные из релевантных checks и routing logic. |
+
+## Маршрутизация истины репозитория
+
+Truthmark сопоставляет code surfaces с документами истины.
+
+Основные файлы маршрутизации:
+
+```text
+docs/truthmark/areas.md
+docs/truthmark/areas/**/*.md
+```
+
+Маршрут сообщает агенту:
+
+- какая code surface принадлежит области
+- какие документы истины владеют этой областью
+- когда истину нужно обновлять
+- какой тип документа истины участвует
+
+Стандартный scaffold начинается широко. Существующие репозитории обычно должны разделить стандартный маршрут на реальные области владения.
+
+Пример:
+
+```text
+/truthmark-structure раздели широкий repository area на frontend, backend, billing и deployment
+```
+
+Хороший routing дает Truth Sync точные цели.
+
+Плохой routing заставляет агентов гадать.
+
+## Что устанавливает Truthmark
+
+Truthmark устанавливает компактный, встроенный в репозиторий слой истины.
+
+Он устанавливает четыре слоя:
+
+- config и routing для границ владения
+- канонические truth docs и стартовые шаблоны
+- компактные управляемые instruction blocks для repo-wide agent context
+- host-native workflow packages, commands, prompts и verifier agents для платформ, включённых в config
+
+Truthmark сохраняет ручной контент вне управляемых блоков инструкций.
+
+Сгенерированные поверхности workflow управляются Truthmark и могут обновляться повторным запуском:
+
+```bash
+truthmark init
+```
+
+## Subagents и ограниченные проверки evidence
+
+Там, где host поддерживает это, Truthmark может устанавливать project-scoped verifier agents и leased `truth-doc-writer`.
+
+Они помогают держать большие truth-задачи ограниченными:
+
+- route auditors проверяют владение маршрутами
+- claim verifiers проверяют, поддержаны ли claims документов evidence
+- doc reviewers проверяют качество truth docs
+- leased doc writers обрабатывают ограниченные shards записи truth docs
+
+Родительский workflow все еще владеет финальной интерпретацией, границами записи, проверкой diff и приемкой.
+
+Это важно: subagents помогают с ограниченной evidence work. Они не заменяют основной контракт workflow.
+
+## Цикл ревью
+
+Truthmark спроектирован для обычного Git review.
+
+Хорошая ИИ-ассистированная передача работы должна показывать:
+
+```text
+diff кода
+test evidence
+diff truth docs, если нужен
+изменения routing, если нужны
+отчет агента
+```
+
+Ревьюер должен уметь ответить:
+
+- Какой код изменился?
+- Какие документы истины владеют этим кодом?
+- Нужно ли было обновлять эти документы?
+- Если нет, почему?
+- Остался ли агент внутри границы записи workflow?
+- Приложена ли evidence тестов или проверки?
 
-Truthmark не является сервером памяти и не является MCP-сервером. Это репозиторная практика, упакованная как небольшой CLI-установщик и родные для агентов рабочие поверхности, которые превращают правила ИИ-процесса в инфраструктуру репозитория.
+## Примеры
 
-V1 сейчас предоставляет:
+### Инициализировать репозиторий
+
+```bash
+npm install -g truthmark
+truthmark config
+truthmark init
+truthmark check
+```
+
+### Удалить неиспользуемые платформы агентов
+
+Отредактируйте:
+
+```text
+.truthmark/config.yml
+```
+
+Затем снова выполните:
+
+```bash
+truthmark init
+truthmark check
+```
+
+### Разделить широкий routing
+
+```text
+/truthmark-structure раздели широкий repository area на auth, billing, notifications и deployment
+```
+
+### Документировать реализованное поведение
+
+```text
+/truthmark-document задокументируй реализованный password reset flow в docs/truth/authentication
+```
+
+### Синхронизировать после изменений кода
+
+```text
+/truthmark-sync синхронизируй истину репозитория прямо сейчас перед передачей
+```
+
+### Реализовать doc-first решение
+
+```text
+/truthmark-realize реализуй docs/truth/billing/invoice-retry-policy.md в коде
+```
+
+### Проверить здоровье истины из терминала
+
+```bash
+truthmark check
+```
+
+### Создать branch-impact context
+
+```bash
+truthmark impact --base main
+```
+
+### Создать workflow context
+
+```bash
+truthmark context --workflow truth-sync --base main --format markdown
+```
+
+## Статус проекта
+
+Truthmark V1 сейчас предоставляет:
 
 - `truthmark config`
 - `truthmark init`
@@ -296,39 +642,123 @@ V1 сейчас предоставляет:
 - `truthmark index`
 - `truthmark impact`
 - `truthmark context`
-- управляемые инструкции рабочих процессов в `AGENTS.md`
-- сгенерированные skill-поверхности Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize и Truth Check для настроенных агентских хостов
-- метаданные области ветки
-- диагностика конфигурации, полномочий, маршрутизации, структуры решений, frontmatter, ссылок и полиглотного покрытия
-- производные артефакты RepoIndex, RouteMap, ImpactSet и ContextPack для более быстрой локальной проверки, когда CLI доступен
+- branch-scope metadata
+- управляемые блоки инструкций
+- сгенерированные поверхности workflow Truth Structure
+- сгенерированные поверхности workflow Truth Document
+- сгенерированные поверхности workflow Truth Sync
+- сгенерированные поверхности workflow Truth Preview
+- сгенерированные поверхности workflow Truth Realize
+- сгенерированные поверхности workflow Truth Check
+- diagnostics для route, authority, decision-structure, frontmatter, links, freshness, generated-surface и coverage
+- производные артефакты RepoIndex, RouteMap, ImpactSet и ContextPack
+- host-specific поверхности для Codex, Claude Code, GitHub Copilot, OpenCode и Gemini CLI
+
+## Разработка
+
+Установить зависимости:
+
+```bash
+npm install
+```
+
+Запустить локальную development CLI:
+
+```bash
+npm run dev -- init
+npm run dev -- check
+```
+
+Запустить полный project check:
+
+```bash
+npm run check
+```
+
+Полезные scripts:
+
+| Script | Назначение |
+| --- | --- |
+| `npm run dev` | Запускает TypeScript CLI entry point через `tsx`. |
+| `npm run build` | Собирает package. |
+| `npm run lint` | Запускает ESLint. |
+| `npm run typecheck` | Запускает TypeScript checks. |
+| `npm run test` | Запускает tests. |
+| `npm run check` | Запускает lint, typecheck, tests и build. |
+| `npm run release:check` | Запускает release-oriented validation. |
+
+Когда меняете сам Truthmark, смотрите [CONTRIBUTORS.md](CONTRIBUTORS.md).
 
 ## Документация
 
-Корневой README предназначен для людей, которые оценивают и пробуют пакет. Подробные функциональные и бизнес-спецификации находятся в `docs/`:
+README — быстрый путь для оценки и настройки.
+
+Подробное текущее поведение живет в `docs/`:
 
 - [Индекс документации](docs/README.md)
 - [Обзор архитектуры](docs/architecture/overview.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)
+- [Установленные workflows](docs/truth/workflows/overview.md)
 - [Руководство по поддержанию истины репозитория](docs/standards/maintaining-repository-truth.md)
 
-Текущее поведение должно жить в каноническом дереве документации выше.
+## Границы дизайна
 
-## Не-цели
+Truthmark намеренно небольшой.
 
-Truthmark V1 не является:
+Он не является:
 
 - размещенным сервисом
 - MCP-сервером
 - векторной базой данных
 - генератором сайтов документации
-- продуктом принудительного контроля для CI или PR
-- заменой тестов, code review или технического лидерства
-- автономным движком для переписывания кода
+- CI- или PR-enforcement продуктом
+- заменой tests, code review или technical leadership
+- автономным движком переписывания кода
+- framework для model training или fine-tuning
+- скрытым слоем памяти
+
+Эти границы — часть продукта.
+
+Truthmark держит workflow локальным, зафиксированным, ограниченным веткой и проверяемым.
+
+## Безопасность и дисциплина ревью
+
+Truthmark помогает репозиторию оставаться честным. Он не доказывает, что код корректен.
+
+Команды все равно должны:
 
-Это легкий способ заставить локальных ИИ-агентов для разработки уважать истину, которую ваша команда хранит в Git.
+- запускать релевантные тесты
+- проверять изменения функционального кода
+- проверять изменения документов истины
+- держать secrets вне документации
+- держать специфичные для репозитория инструкции вне managed blocks
+- проверять diff сгенерированных workflow surfaces после upgrades
+- сохранять человеческое владение продуктовыми и архитектурными решениями
+
+Truthmark делает контекст агента видимым. Он не заменяет человеческое суждение.
+
+## Направление roadmap
+
+Текущее будущее направление делает акцент на:
+
+- более сильной evidence reporting в `truthmark check`
+- более ясных примерах adoption
+- примерных репозиториях, показывающих реальные циклы Truth Sync
+- migration guides для команд, уже использующих agent instruction files
+- conformance tests для generated host surfaces
+- route-aware подсказках о stale truth
+- ограниченных implementation checklists для doc-first work
+
+Центр тяжести остается прежним:
+
+```text
+истина репозитория
+agent-native workflows
+Git review
+контекст в пределах ветки
+```
 
 ## Лицензия