truthmark 1.2.0 → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.de.md +21 -7
  2. package/README.es.md +21 -7
  3. package/README.md +31 -13
  4. package/README.ru.md +22 -8
  5. package/README.zh.md +21 -7
  6. package/dist/main.js +70 -52
  7. package/dist/main.js.map +1 -1
  8. package/package.json +1 -1
package/README.de.md CHANGED
@@ -66,7 +66,17 @@ Das ist das Kernversprechen: Agentenkontext wird zu festgeschriebenem Repository
66
66
 
67
67
  ## Erste Schritte
68
68
 
69
- Wenn du Truthmark zunächst gegen ein anderes lokales Repository ausprobieren willst, bevor das Paket anderswo veröffentlicht ist:
69
+ Installiere Truthmark in dem Repository, das du initialisieren möchtest:
70
+
71
+ ```bash
72
+ cd /path/to/your-repo
73
+ npm install -g truthmark
74
+ truthmark config
75
+ truthmark init
76
+ truthmark check
77
+ ```
78
+
79
+ Wenn du stattdessen unveröffentlichte Änderungen aus einem Source-Checkout ausprobieren möchtest:
70
80
 
71
81
  ```bash
72
82
  cd /path/to/truthmark
@@ -90,15 +100,21 @@ docs/features/repository/README.md
90
100
  docs/features/repository/overview.md
91
101
  AGENTS.md
92
102
  CLAUDE.md
93
- skills/truthmark-structure/SKILL.md
94
- skills/truthmark-sync/SKILL.md
95
- skills/truthmark-realize/SKILL.md
96
- skills/truthmark-check/SKILL.md
103
+ .codex/skills/truthmark-structure/SKILL.md
104
+ .codex/skills/truthmark-sync/SKILL.md
105
+ .codex/skills/truthmark-realize/SKILL.md
106
+ .codex/skills/truthmark-check/SKILL.md
107
+ .opencode/skills/truthmark-structure/SKILL.md
108
+ .opencode/skills/truthmark-sync/SKILL.md
109
+ .opencode/skills/truthmark-realize/SKILL.md
110
+ .opencode/skills/truthmark-check/SKILL.md
97
111
  ```
98
112
 
99
113
  Wenn du zusätzliche Plattformen in `.truthmark/config.yml` aktivierst, aktualisiert Truthmark die entsprechenden verwalteten Flächen beim nächsten `init`.
100
114
  Die standardmäßig erzeugte Struktur verwendet `README.md`-Dateien von Features als Indizes und beginnt die Wahrheit über aktuelles Verhalten in begrenzten Blattdokumenten wie `docs/features/repository/overview.md`.
101
115
 
116
+ Bestehende Repositories brauchen nach `init` meist einen Aufräumschritt: Führe den installierten Truth-Structure-Workflow aus, wenn die erzeugte `repository`-Route zu breit ist, Ownership mehrere Produkte oder Services umfasst oder Routendateien noch auf Platzhalterdokumente zeigen. Truth Structure teilt breite Routings auf, erstellt oder repariert erste kanonische Wahrheitsdokumente und gibt Truth Sync präzise Ziele, bevor funktionale Codearbeit beginnt. Codex-Nutzer können ihn mit `/truthmark-structure` oder `$truthmark-structure` aufrufen; Hosts im OpenCode-Stil können `/skill truthmark-structure` verwenden.
117
+
102
118
  ## Wie es läuft
103
119
 
104
120
  Truthmark legt nicht fest, welcher Subagent Truth Sync ausführen soll. Der handelnde Agent und die Host-Umgebung entscheiden, ob delegiert oder der Workflow inline ausgeführt wird.
@@ -194,8 +210,6 @@ V1 bietet derzeit:
194
210
  - Branch-Scope-Metadaten
195
211
  - Diagnostik für Konfiguration, Autorität, Routing, Entscheidungsstruktur, Frontmatter, Links und polyglotte Abdeckung
196
212
 
197
- Es wird nicht angenommen, dass das ungescopte Paket `truthmark` bereits veröffentlicht ist.
198
-
199
213
  ## Dokumentation
200
214
 
201
215
  Die Root-README ist für Menschen gedacht, die das Paket evaluieren und ausprobieren. Detaillierte funktionale und geschäftliche Spezifikationen liegen unter `docs/`:
package/README.es.md CHANGED
@@ -66,7 +66,17 @@ Esta es la promesa central: el contexto del agente pasa a ser estado confirmado
66
66
 
67
67
  ## Primeros pasos
68
68
 
69
- Para probar Truthmark contra otro repositorio local antes de que el paquete se publique en otro lugar:
69
+ Instala Truthmark en el repositorio que quieras inicializar:
70
+
71
+ ```bash
72
+ cd /path/to/your-repo
73
+ npm install -g truthmark
74
+ truthmark config
75
+ truthmark init
76
+ truthmark check
77
+ ```
78
+
79
+ Si quieres probar cambios aún no publicados desde un checkout del código fuente:
70
80
 
71
81
  ```bash
72
82
  cd /path/to/truthmark
@@ -90,15 +100,21 @@ docs/features/repository/README.md
90
100
  docs/features/repository/overview.md
91
101
  AGENTS.md
92
102
  CLAUDE.md
93
- skills/truthmark-structure/SKILL.md
94
- skills/truthmark-sync/SKILL.md
95
- skills/truthmark-realize/SKILL.md
96
- skills/truthmark-check/SKILL.md
103
+ .codex/skills/truthmark-structure/SKILL.md
104
+ .codex/skills/truthmark-sync/SKILL.md
105
+ .codex/skills/truthmark-realize/SKILL.md
106
+ .codex/skills/truthmark-check/SKILL.md
107
+ .opencode/skills/truthmark-structure/SKILL.md
108
+ .opencode/skills/truthmark-sync/SKILL.md
109
+ .opencode/skills/truthmark-realize/SKILL.md
110
+ .opencode/skills/truthmark-check/SKILL.md
97
111
  ```
98
112
 
99
113
  Si habilitas plataformas adicionales en `.truthmark/config.yml`, Truthmark actualizará las superficies administradas correspondientes en el siguiente `init`.
100
114
  La estructura generada por defecto usa los `README.md` de funciones como índices y empieza la verdad sobre el comportamiento actual en documentos hoja acotados, como `docs/features/repository/overview.md`.
101
115
 
116
+ Los repositorios existentes suelen necesitar una pasada de limpieza después de `init`: ejecuta el flujo instalado Truth Structure cuando la ruta `repository` generada sea demasiado amplia, la propiedad abarque varios productos o servicios, o los archivos de rutas sigan apuntando a documentos de marcador de posición. Truth Structure divide rutas amplias, crea o repara documentos de verdad canónica iniciales y da a Truth Sync destinos precisos antes de que empiece el trabajo de código funcional. Los usuarios de Codex pueden invocarlo con `/truthmark-structure` o `$truthmark-structure`; los hosts de estilo OpenCode pueden usar `/skill truthmark-structure`.
117
+
102
118
  ## Cómo se ejecuta
103
119
 
104
120
  Truthmark no especifica qué subagente debe ejecutar Truth Sync. El agente que actúa y el entorno anfitrión deciden si delegan o ejecutan el flujo en línea.
@@ -194,8 +210,6 @@ V1 actualmente ofrece:
194
210
  - metadatos de alcance de rama
195
211
  - diagnósticos de configuración, autoridad, enrutamiento, estructura de decisiones, frontmatter, enlaces y cobertura políglota
196
212
 
197
- No se debe asumir que el paquete sin scope `truthmark` ya está publicado.
198
-
199
213
  ## Documentación
200
214
 
201
215
  El README raíz es para personas que evalúan y prueban el paquete. Las especificaciones funcionales y de negocio detalladas viven en `docs/`:
package/README.md CHANGED
@@ -4,6 +4,8 @@
4
4
 
5
5
  English | [Deutsch](README.de.md) | [中文](README.zh.md) | [Español](README.es.md) | [Русский](README.ru.md)
6
6
 
7
+ ![Truthmark overview](docs/assets/truthmark-overview.png)
8
+
7
9
  AI coding agents are already good at writing code. They are still bad at reliably reconstructing product intent, architecture boundaries, and repository ownership from stale docs, scattered chats, and ephemeral tool memory.
8
10
 
9
11
  Truthmark fixes that by turning branch-local repository truth into a first-class runtime surface for agents. It installs a Git-native, branch-scoped truth layer directly inside the repo, gives agents explicit routing and workflow boundaries, and makes that truth move with the code that actually ships.
@@ -34,12 +36,12 @@ For tech leads, the value is governance without theater: tests, code review, and
34
36
 
35
37
  Truthmark is not trying to replace every other AI workflow tool. It sits in a specific layer of the stack:
36
38
 
37
- | If you need | Best fit |
38
- | --- | --- |
39
- | Better results from a single coding session | Better prompts and tighter task framing |
40
- | Convenience across sessions for one agent or one operator | Memory tools |
41
- | Spec-first planning for new features | Spec tools such as Spec Kit |
42
- | Branch-scoped, reviewable repository truth that travels with the code | Truthmark |
39
+ | If you need | Best fit |
40
+ | --------------------------------------------------------------------- | --------------------------------------- |
41
+ | Better results from a single coding session | Better prompts and tighter task framing |
42
+ | Convenience across sessions for one agent or one operator | Memory tools |
43
+ | Spec-first planning for new features | Spec tools such as Spec Kit |
44
+ | Branch-scoped, reviewable repository truth that travels with the code | Truthmark |
43
45
 
44
46
  The point is not that prompts, memory, or specs are useless. The point is that none of them, by themselves, turn repository truth into a committed, inspectable asset that survives handoffs, review, and branch divergence.
45
47
 
@@ -72,7 +74,17 @@ This is the core promise: agent context becomes committed repository state inste
72
74
 
73
75
  ## Get started
74
76
 
75
- To try Truthmark from a source checkout instead of the published npm package:
77
+ Install Truthmark in the repository you want to initialize:
78
+
79
+ ```bash
80
+ cd /path/to/your-repo
81
+ npm install -g truthmark
82
+ truthmark config
83
+ truthmark init
84
+ truthmark check
85
+ ```
86
+
87
+ If you want to try unreleased changes from a source checkout instead:
76
88
 
77
89
  ```bash
78
90
  cd /path/to/truthmark
@@ -97,20 +109,26 @@ docs/features/repository/README.md
97
109
  docs/features/repository/overview.md
98
110
  AGENTS.md
99
111
  CLAUDE.md
100
- skills/truthmark-structure/SKILL.md
101
- skills/truthmark-sync/SKILL.md
102
- skills/truthmark-realize/SKILL.md
103
- skills/truthmark-check/SKILL.md
112
+ .codex/skills/truthmark-structure/SKILL.md
113
+ .codex/skills/truthmark-sync/SKILL.md
114
+ .codex/skills/truthmark-realize/SKILL.md
115
+ .codex/skills/truthmark-check/SKILL.md
116
+ .opencode/skills/truthmark-structure/SKILL.md
117
+ .opencode/skills/truthmark-sync/SKILL.md
118
+ .opencode/skills/truthmark-realize/SKILL.md
119
+ .opencode/skills/truthmark-check/SKILL.md
104
120
  ```
105
121
 
106
122
  If you enable additional platforms in `.truthmark/config.yml`, Truthmark refreshes the corresponding managed surfaces on the next `init`.
107
123
 
108
124
  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`.
109
125
 
110
- Truthmark does not specify which subagent should run Truth Sync. The acting agent and host environment decide whether to delegate or run the workflow inline.
126
+ 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 users can invoke it with `/truthmark-structure` or `$truthmark-structure`; OpenCode-style hosts can invoke `/skill truthmark-structure`.
111
127
 
112
128
  ## How it runs
113
129
 
130
+ Truthmark does not specify which subagent should run Truth Sync. The acting agent and host environment decide whether to delegate or run the workflow inline.
131
+
114
132
  ### Normal code changes
115
133
 
116
134
  Most users should not need to invoke Truth Sync directly. The normal path is:
@@ -153,7 +171,7 @@ Truthmark keeps the durable workflow surface small:
153
171
  - `docs/truthmark/areas.md` for the root route index
154
172
  - `docs/truthmark/areas/**/*.md` for delegated child route files
155
173
  - managed instruction blocks for configured platforms such as `AGENTS.md`, `CLAUDE.md`, Cursor rules, Copilot instructions, and `GEMINI.md`
156
- - Codex and repo-local skills for Truth Structure, Truth Sync, Truth Realize, and Truth Check
174
+ - Codex and OpenCode skills for Truth Structure, Truth Sync, Truth Realize, and Truth Check
157
175
 
158
176
  The installed workflow surfaces are the runtime:
159
177
 
package/README.ru.md CHANGED
@@ -66,7 +66,17 @@ Truthmark превращает истину репозитория в явную
66
66
 
67
67
  ## Начало работы
68
68
 
69
- Чтобы попробовать Truthmark на другом локальном репозитории до публикации пакета где-либо еще:
69
+ Установите Truthmark в репозитории, который хотите инициализировать:
70
+
71
+ ```bash
72
+ cd /path/to/your-repo
73
+ npm install -g truthmark
74
+ truthmark config
75
+ truthmark init
76
+ truthmark check
77
+ ```
78
+
79
+ Если вы хотите попробовать еще не выпущенные изменения из исходного checkout:
70
80
 
71
81
  ```bash
72
82
  cd /path/to/truthmark
@@ -90,15 +100,21 @@ docs/features/repository/README.md
90
100
  docs/features/repository/overview.md
91
101
  AGENTS.md
92
102
  CLAUDE.md
93
- skills/truthmark-structure/SKILL.md
94
- skills/truthmark-sync/SKILL.md
95
- skills/truthmark-realize/SKILL.md
96
- skills/truthmark-check/SKILL.md
103
+ .codex/skills/truthmark-structure/SKILL.md
104
+ .codex/skills/truthmark-sync/SKILL.md
105
+ .codex/skills/truthmark-realize/SKILL.md
106
+ .codex/skills/truthmark-check/SKILL.md
107
+ .opencode/skills/truthmark-structure/SKILL.md
108
+ .opencode/skills/truthmark-sync/SKILL.md
109
+ .opencode/skills/truthmark-realize/SKILL.md
110
+ .opencode/skills/truthmark-check/SKILL.md
97
111
  ```
98
112
 
99
113
  Если вы включите дополнительные платформы в `.truthmark/config.yml`, Truthmark обновит соответствующие управляемые поверхности при следующем `init`.
100
114
  Стандартная шаблонная структура использует `README.md` функциональных разделов как индексы и начинает описывать истину текущего поведения в ограниченных листовых документах, например `docs/features/repository/overview.md`.
101
115
 
116
+ Существующим репозиториям обычно нужен один этап очистки после `init`: запустите установленный рабочий процесс Truth Structure, если созданный маршрут `repository` слишком широкий, владение охватывает несколько продуктов или сервисов, либо файлы маршрутов все еще указывают на документы-заглушки. Truth Structure разделяет широкие маршруты, создает или исправляет начальные канонические документы истины и дает Truth Sync точные цели до начала работы с функциональным кодом. Пользователи Codex могут вызвать его через `/truthmark-structure` или `$truthmark-structure`; хосты в стиле OpenCode могут использовать `/skill truthmark-structure`.
117
+
102
118
  ## Как он работает
103
119
 
104
120
  Truthmark не задает, какой именно подагент должен запускать Truth Sync. Действующий агент и среда хоста сами решают, делегировать работу или выполнить процесс на месте.
@@ -137,7 +153,7 @@ Truthmark намеренно держит постоянную рабочую п
137
153
  - `docs/truthmark/areas.md` для корневого индекса маршрутов
138
154
  - `docs/truthmark/areas/**/*.md` для делегированных дочерних файлов маршрутов
139
155
  - управляемые блоки инструкций для настроенных платформ, таких как `AGENTS.md`, `CLAUDE.md`, правила Cursor, инструкции Copilot и `GEMINI.md`
140
- - Codex- и repo-local skills для Truth Structure, Truth Sync, Truth Realize и Truth Check
156
+ - Codex- и OpenCode skills для Truth Structure, Truth Sync, Truth Realize и Truth Check
141
157
 
142
158
  Установленные рабочие поверхности и есть среда выполнения:
143
159
 
@@ -194,8 +210,6 @@ V1 сейчас предоставляет:
194
210
  - метаданные области ветки
195
211
  - диагностика конфигурации, полномочий, маршрутизации, структуры решений, frontmatter, ссылок и полиглотного покрытия
196
212
 
197
- Не следует считать, что пакет `truthmark` без scope уже опубликован.
198
-
199
213
  ## Документация
200
214
 
201
215
  Корневой README предназначен для людей, которые оценивают и пробуют пакет. Подробные функциональные и бизнес-спецификации находятся в `docs/`:
package/README.zh.md CHANGED
@@ -66,7 +66,17 @@ Truthmark 把仓库事实变成代理可见的显式工作流载体：
66
66
 
67
67
  ## 快速开始
68
68
 
69
- 如果想在包发布到其他地方之前，先在另一个本地仓库试用 Truthmark：
69
+ 在你想初始化的仓库中安装 Truthmark：
70
+
71
+ ```bash
72
+ cd /path/to/your-repo
73
+ npm install -g truthmark
74
+ truthmark config
75
+ truthmark init
76
+ truthmark check
77
+ ```
78
+
79
+ 如果你想从源码检出中试用尚未发布的变更：
70
80
 
71
81
  ```bash
72
82
  cd /path/to/truthmark
@@ -90,15 +100,21 @@ docs/features/repository/README.md
90
100
  docs/features/repository/overview.md
91
101
  AGENTS.md
92
102
  CLAUDE.md
93
- skills/truthmark-structure/SKILL.md
94
- skills/truthmark-sync/SKILL.md
95
- skills/truthmark-realize/SKILL.md
96
- skills/truthmark-check/SKILL.md
103
+ .codex/skills/truthmark-structure/SKILL.md
104
+ .codex/skills/truthmark-sync/SKILL.md
105
+ .codex/skills/truthmark-realize/SKILL.md
106
+ .codex/skills/truthmark-check/SKILL.md
107
+ .opencode/skills/truthmark-structure/SKILL.md
108
+ .opencode/skills/truthmark-sync/SKILL.md
109
+ .opencode/skills/truthmark-realize/SKILL.md
110
+ .opencode/skills/truthmark-check/SKILL.md
97
111
  ```
98
112
 
99
113
  如果你在 `.truthmark/config.yml` 中启用更多平台，Truthmark 会在下一次 `init` 时刷新对应的受管载体。
100
114
  默认脚手架把功能 `README.md` 作为索引，并把当前行为事实放在有边界的叶子文档中，例如 `docs/features/repository/overview.md`。
101
115
 
116
+ 现有仓库通常需要在 `init` 之后做一次清理：当生成的 `repository` 路由过宽、所有权跨越多个产品或服务，或路由文件仍指向占位文档时，运行已安装的 Truth Structure 工作流。Truth Structure 会拆分过宽的路由，创建或修复初始的规范事实文档，并在功能代码工作开始前为 Truth Sync 提供精确目标。Codex 用户可以用 `/truthmark-structure` 或 `$truthmark-structure` 调用它；OpenCode 风格的宿主可以用 `/skill truthmark-structure` 调用它。
117
+
102
118
  ## 它如何运行
103
119
 
104
120
  Truthmark 不规定应该由哪个子代理运行 Truth Sync。由实际执行的代理和宿主环境决定是委托执行，还是内联运行工作流。
@@ -194,8 +210,6 @@ V1 目前提供：
194
210
  - 分支范围元数据
195
211
  - 配置、权限边界、路由、决策结构、frontmatter、链接和多语言覆盖率诊断
196
212
 
197
- 不要假定未带 scope 的 `truthmark` 包已经发布。
198
-
199
213
  ## 文档
200
214
 
201
215
  根 README 面向评估和试用这个包的人。详细的功能和业务规范位于 `docs/` 下：