truthmark 1.4.0 → 1.5.0

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 +623 -193
  2. package/README.es.md +624 -194
  3. package/README.md +614 -191
  4. package/README.ru.md +631 -201
  5. package/README.zh.md +630 -198
  6. package/dist/main.js +846 -39
  7. package/dist/main.js.map +1 -1
  8. package/package.json +1 -1
package/README.md CHANGED
@@ -1,301 +1,640 @@
1
1
  # Truthmark
2
2
 
3
- **Truthmark installs repository truth workflows for AI software development.**
3
+ **Your agents write code. Truthmark makes their context reviewable in Git.**
4
4
 
5
5
  English | [Deutsch](README.de.md) | [中文](README.zh.md) | [Español](README.es.md) | [Русский](README.ru.md)
6
6
 
7
- <img src="docs/assets/truthmark-banner.png" alt="Truthmark banner" width="100%" />
7
+ ![Truthmark banner](docs/assets/truthmark-banner.png)
8
8
 
9
- AI coding agents already write code fast. The expensive part is keeping repository truth aligned with what changed.
9
+ AI coding agents can change a repository faster than humans can keep its context aligned.
10
10
 
11
- Truthmark adds a finish-time workflow guard to that workflow. The normal path is simple:
11
+ Truthmark fixes the part that usually breaks after the code is written: the repository truth.
12
12
 
13
- - agent changes functional code
14
- - run relevant tests
15
- - the installed Truth Sync workflow updates mapped truth docs before the agent finishes
16
- - review the truth-doc diff if one was produced
13
+ It installs a Git-native, branch-scoped workflow layer that helps AI coding agents update the right docs, respect ownership boundaries, and leave humans with normal diffs they can review.
17
14
 
18
- Most tools ask teams to adopt a habit. Truthmark turns the habit into repository workflow infrastructure.
15
+ No hosted service.
19
16
 
20
- 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.
17
+ No database.
21
18
 
22
- That matters because the workflow lives with the branch. Once a repository is initialized, the rules, routing, and installed workflow surfaces travel in-repo, so collaboration and handoffs are less dependent on one person's machine setup.
19
+ No hidden memory layer.
23
20
 
24
- For teams who already know agents can generate code, Truthmark answers the next problem: how to keep the repository itself legible, reviewable, and governable as AI-assisted work scales.
21
+ No extra server to operate.
25
22
 
26
- ## Visual overview
23
+ Just repository truth that moves with the branch.
27
24
 
28
- <table>
29
- <tr>
30
- <td align="center" width="50%">
31
- <img src="docs/assets/truthmark-features.png" alt="Truthmark features" width="100%" />
32
- <br><strong>Features</strong><br>
33
- What Truthmark installs and how the workflow surface is split.
34
- </td>
35
- <td align="center" width="50%">
36
- <img src="docs/assets/truthmark-position.png" alt="Truthmark position" width="100%" />
37
- <br><strong>Position</strong><br>
38
- Where Truthmark fits relative to prompts, memory, and spec workflows.
39
- </td>
40
- </tr>
41
- <tr>
42
- <td align="center" colspan="2">
43
- <img src="docs/assets/truthmark-syncflow.png" alt="Truthmark sync flow" width="100%" />
44
- <br><strong>Sync flow</strong><br>
45
- How Truth Sync closes out normal code changes before handoff.
46
- </td>
47
- </tr>
48
- </table>
25
+ ## The problem
49
26
 
50
- ## Why teams adopt it
27
+ AI coding agents are good at producing code. That creates a new failure mode.
51
28
 
52
- Truthmark is not trying to make agents sound smarter. It is trying to make AI-assisted repository change easier to trust.
29
+ The implementation changes, but the repository story drifts:
53
30
 
54
- - Installed Truth Sync after code changes turns documentation maintenance into a workflow safeguard instead of a team habit.
55
- - Branch-scoped truth moves with the code, so reviewers can inspect current truth in ordinary Git diffs.
56
- - Repository-native workflow surfaces make rollout lighter and handoffs more resilient than per-user setup alone.
57
- - Explicit routing in `docs/truthmark/areas.md` and delegated child route files gives agents ownership boundaries and safer write paths.
58
- - Local-first operation avoids a daemon, database, remote service, or MCP dependency.
59
- - The routing model is language-agnostic, with coverage diagnostics for common JavaScript, TypeScript, Go, Python, C#, and Java code surfaces.
31
+ - behavior lives in chat history
32
+ - architecture docs fall behind
33
+ - product decisions disappear after handoff
34
+ - reviewers see code diffs without the related truth diffs
35
+ - branches quietly develop different versions of “what is true”
36
+ - each agent session has to rediscover context from scratch
60
37
 
61
- 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.
38
+ Truthmark turns that fragile context into committed repository infrastructure.
62
39
 
63
- ## Where Truthmark fits
40
+ Instead of relying on every human and every agent to remember the right documentation habit, Truthmark installs the habit into the repository.
64
41
 
65
- Truthmark is not a general AI productivity suite. It occupies a specific layer of the stack: branch-scoped, reviewable repository truth that stays aligned with implementation.
42
+ ## The promise
66
43
 
67
- | If you need | Best fit |
68
- | --------------------------------------------------------------------- | --------------------------------------- |
69
- | Better results from a single coding session | Better prompts and tighter task framing |
70
- | Convenience across sessions for one agent or one operator | Memory tools |
71
- | Spec-first planning for new features | Spec tools such as Spec Kit |
72
- | Branch-scoped, reviewable repository truth that travels with the code | Truthmark |
44
+ When an agent changes functional code, the work should not end with only a code diff.
73
45
 
74
- 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.
46
+ The normal Truthmark path is:
75
47
 
76
- ## Table of Contents
48
+ ```text
49
+ agent changes functional code
50
+ relevant tests run
51
+ Truth Sync checks mapped truth docs
52
+ truth docs update when needed
53
+ human reviews code diff + truth diff
54
+ commit or hand off
55
+ ```
77
56
 
78
- - [Why teams adopt it](#why-teams-adopt-it)
79
- - [What Truthmark solves](#what-truthmark-solves)
80
- - [Where Truthmark fits](#where-truthmark-fits)
81
- - [Get started](#get-started)
82
- - [How it runs](#how-it-runs)
83
- - [What it installs](#what-it-installs)
84
- - [Commands](#commands)
85
- - [Why it exists](#why-it-exists)
86
- - [Project status](#project-status)
87
- - [Documentation](#documentation)
88
- - [Non-goals](#non-goals)
89
- - [License](#license)
57
+ That is the core value: **AI work becomes easier to trust because the repository stays legible.**
90
58
 
91
- ## What Truthmark solves
59
+ ## Two surfaces, one truth system
92
60
 
93
- Truthmark turns repository truth into an explicit workflow surface for agents:
61
+ Truthmark is not just a CLI.
94
62
 
95
- - `.truthmark/config.yml` defines the committed hierarchy contract.
96
- - `docs/truthmark/areas.md` and delegated child route files map code areas to the docs that own them.
97
- - Truth Document generates or repairs canonical truth docs for existing implemented behavior when no code change is needed.
98
- - Truth Sync keeps mapped truth docs aligned with functional changes.
99
- - Truth Preview previews likely workflow routing before edits without authorizing writes.
100
- - Truth Realize gives doc-first changes a bounded code-update path.
101
- - `truthmark check` validates the resulting truth artifacts.
102
- - The whole model stays local-first and Git-native.
63
+ It has two distinct surfaces, and the distinction matters.
103
64
 
104
- This is the core promise: agent context becomes committed repository state instead of a private session artifact.
65
+ ### 1. Human-facing CLI
105
66
 
106
- ## Get started
67
+ The CLI is for maintainers, reviewers, and automation.
107
68
 
108
- Install Truthmark in the repository you want to initialize:
69
+ Use it to configure a repository, install or refresh workflow files, validate truth artifacts, and generate optional review context.
109
70
 
110
71
  ```bash
111
- cd /path/to/your-repo
112
- npm install -g truthmark
113
72
  truthmark config
114
73
  truthmark init
115
74
  truthmark check
116
75
  ```
117
76
 
118
- If you want to try unreleased changes from a source checkout instead:
77
+ The CLI prepares and validates the repository environment.
119
78
 
120
- ```bash
121
- cd /path/to/truthmark
122
- npm install
123
- npm run build
79
+ It is not the AI workflow runtime.
80
+
81
+ ### 2. AI-facing workflow surfaces
82
+
83
+ The AI-facing surfaces are for coding agents.
84
+
85
+ Truthmark installs host-native skills, prompts, commands, managed instruction blocks, and supported subagent surfaces so AI agents can follow repository-specific truth workflows inside their normal coding tools.
86
+
87
+ Examples:
88
+
89
+ ```text
90
+ /truthmark-sync
91
+ /truthmark-document
92
+ /truthmark-structure
93
+ /truthmark-realize
94
+ /truthmark-preview
95
+ /truthmark-check
96
+ ```
97
+
98
+ These look like commands because agent hosts expose workflows through slash commands, prompts, skills, or project commands.
99
+
100
+ They are not shell commands.
101
+
102
+ They are AI-facing workflow entrypoints.
103
+
104
+ The split is the product:
105
+
106
+ ```text
107
+ humans own the repository contract
108
+ Truthmark installs the contract into the repo
109
+ agents operate inside that contract
110
+ truth updates appear as Git diffs
111
+ humans review the result
112
+ ```
113
+
114
+ ## Quick start
124
115
 
116
+ ### Requirements
117
+
118
+ - Node.js `>=20`
119
+ - npm
120
+ - a Git repository
121
+
122
+ ### Install Truthmark
123
+
124
+ Run this inside the repository you want to initialize:
125
+
126
+ ```bash
125
127
  cd /path/to/your-repo
126
- node /path/to/truthmark/dist/main.js config
127
- node /path/to/truthmark/dist/main.js init
128
- node /path/to/truthmark/dist/main.js check
128
+ npm install -g truthmark
129
129
  ```
130
130
 
131
- Review `.truthmark/config.yml` before `init`; it is the committed hierarchy contract. After `init`, review the generated workflow surface and route files so the routed docs match the docs that actually own your code:
131
+ ### Create the repository truth contract
132
+
133
+ ```bash
134
+ truthmark config
135
+ ```
136
+
137
+ This creates:
132
138
 
133
139
  ```text
134
140
  .truthmark/config.yml
135
- docs/truthmark/areas.md
136
- docs/truthmark/areas/repository.md
137
- docs/templates/behavior-doc.md
138
- docs/truth/README.md
139
- docs/truth/repository/README.md
140
- docs/truth/repository/overview.md
141
- AGENTS.md
142
- CLAUDE.md
143
- GEMINI.md
144
141
  ```
145
142
 
146
- 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`.
143
+ Review this file before continuing. It defines the committed hierarchy contract for the repository.
144
+
145
+ ### Install the workflow surfaces
146
+
147
+ ```bash
148
+ truthmark init
149
+ ```
150
+
151
+ This installs or refreshes:
152
+
153
+ - route files
154
+ - truth-doc scaffolding
155
+ - managed instruction blocks
156
+ - AI-facing workflow surfaces for configured platforms
157
+
158
+ ### Validate the setup
159
+
160
+ ```bash
161
+ truthmark check
162
+ ```
163
+
164
+ Then review the generated files before committing.
147
165
 
148
- 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`.
166
+ The exact files depend on `.truthmark/config.yml`, but the install always has the same shape: routing, truth scaffolding, compact managed instructions, and host-native workflow surfaces for the enabled platforms.
149
167
 
150
- 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`.
168
+ ## First real use
169
+
170
+ Most repositories need one cleanup pass after initialization.
171
+
172
+ The default scaffold starts with a broad `repository` area. Real repositories usually need more precise routing.
173
+
174
+ Ask your agent to split the broad route into actual product, service, domain, or ownership areas:
151
175
 
152
176
  ```text
153
177
  /truthmark-structure split the broad repository area into auth, billing, and notifications
154
178
  ```
155
179
 
156
- ## How it runs
180
+ After that, use your AI coding agent normally.
181
+
182
+ When the agent changes functional code, Truth Sync acts as the finish-time guard that checks whether mapped truth docs need to change before handoff.
183
+
184
+ ## What you get
185
+
186
+ | Capability | What it does |
187
+ | --- | --- |
188
+ | Git-native truth | Keeps repository truth in committed Markdown and config. |
189
+ | Branch-scoped context | Truth moves with the branch instead of living in a private session. |
190
+ | Human CLI | Gives maintainers setup, refresh, validation, and inspection commands. |
191
+ | AI-facing workflows | Gives agents host-native workflows for sync, documentation, structure, preview, realization, and audit. |
192
+ | Explicit routing | Maps code areas to canonical truth docs. |
193
+ | Reviewable handoffs | Produces ordinary Git diffs for both code and truth docs. |
194
+ | Local-first operation | Requires no hosted service, daemon, database, or MCP server. |
195
+ | Safer write boundaries | Separates code-first, doc-first, read-only, and doc-only workflows. |
196
+ | Validation | Reports routing, authority, frontmatter, link, generated-surface, branch-scope, freshness, and coverage issues. |
197
+
198
+ ## Visual overview
199
+
200
+ ![Truthmark features](docs/assets/truthmark-features.png)
201
+
202
+ **Features:** what Truthmark installs and how the workflow surface is split.
203
+
204
+ ![Truthmark position](docs/assets/truthmark-position.png)
205
+
206
+ **Position:** where Truthmark fits relative to prompts, memory, and spec workflows.
207
+
208
+ ![Truthmark sync flow](docs/assets/truthmark-syncflow.png)
209
+
210
+ **Sync flow:** how Truth Sync closes out normal code changes before handoff.
211
+
212
+ ## Why teams adopt it
157
213
 
158
- Truthmark is strongest on the default path, not as a pile of manual commands. The acting agent and host environment decide whether to delegate or run the installed workflow inline.
214
+ Truthmark is for teams that already know AI agents can generate code.
159
215
 
160
- ### Existing behavior without docs
216
+ The next problem is governance.
161
217
 
162
- Use this when implementation already exists but the canonical truth docs are missing or weak:
218
+ Not governance as ceremony. Governance as a simple question:
219
+
220
+ > After this AI-assisted change, does the repository still tell the truth?
221
+
222
+ Truthmark helps teams answer that with committed files, explicit routing, and reviewable diffs.
223
+
224
+ It is useful when you need:
225
+
226
+ - less documentation drift
227
+ - better handoffs
228
+ - branch-specific product truth
229
+ - durable architecture and API context
230
+ - explicit ownership between docs and code
231
+ - safer agent write boundaries
232
+ - reviewable context instead of hidden memory
233
+ - AI workflows that still work from committed repo files
234
+
235
+ ## Where Truthmark fits
236
+
237
+ Truthmark does not replace prompts, memory, specs, tests, or code review.
238
+
239
+ It gives those workflows a durable place to land in Git.
240
+
241
+ | Need | Better fit |
242
+ | --- | --- |
243
+ | Better output from one agent session | Better prompt |
244
+ | Personal or session-level continuity | Memory tool |
245
+ | Plan-first feature work | Spec workflow |
246
+ | Branch-scoped truth that travels with code | Truthmark |
247
+ | Validating behavior correctness | Tests and review |
248
+ | Reviewing AI-assisted context changes | Truthmark plus Git review |
249
+
250
+ Truthmark’s lane is narrow by design:
163
251
 
164
252
  ```text
165
- user identifies an implemented behavior or API endpoint
166
- user explicitly invokes Truth Document
167
- agent reads implementation, tests, routing, and existing docs
168
- agent writes truth docs and routing only
169
- review the truth-doc diff
253
+ make repository truth explicit
254
+ route it to code
255
+ install agent workflows around it
256
+ keep the result reviewable in Git
170
257
  ```
171
258
 
172
- 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`.
259
+ ## How Truthmark runs
173
260
 
174
- ```text
175
- /truthmark-document document the implemented session timeout behavior under docs/truth/authentication
261
+ Truthmark runs locally against the active Git worktree.
262
+
263
+ The human-facing CLI reads and writes repository files, then exits.
264
+
265
+ The AI-facing workflow surfaces are committed files that agent hosts can load later. That means agents can follow the installed workflow from repository state instead of depending on a background Truthmark process.
266
+
267
+ The layers fit together like this:
268
+
269
+ ```mermaid
270
+ flowchart LR
271
+ Human["Human / CI"] --> CLI["Truthmark CLI"]
272
+ CLI --> Config["Config and route map"]
273
+ CLI --> Truth["Canonical truth docs"]
274
+ CLI --> Surfaces["Generated host-native workflows"]
275
+ Surfaces --> Hosts["Codex / Claude Code / Copilot / OpenCode / Gemini"]
276
+ Hosts --> Worktree["Active Git worktree"]
277
+ Hosts -->|"helper checks / validate / index"| CLI
278
+ Worktree --> Truth
279
+ ```
280
+
281
+ Agents do not talk to a Truthmark daemon, but they can run the installed Truthmark CLI when a workflow asks for validation, indexing, or helper checks.
282
+
283
+ Truthmark owns the generated workflow surfaces it creates, but the important contract is architectural: repo-local config and routing point agents at canonical truth docs, while host-native workflows give each supported agent a way to run the same Truthmark procedures.
284
+
285
+ Generated workflow surfaces include Truthmark version markers. After upgrading Truthmark, rerun:
286
+
287
+ ```bash
288
+ truthmark init
289
+ ```
290
+
291
+ Then review the generated diffs.
292
+
293
+ ## Supported agent platforms
294
+
295
+ The default config includes every supported platform.
296
+
297
+ Remove platforms you do not use from `.truthmark/config.yml`, then rerun:
298
+
299
+ ```bash
300
+ truthmark init
176
301
  ```
177
302
 
178
- ### Normal code changes
303
+ | Platform config name | Generated surface | Invocation shape |
304
+ | --- | --- | --- |
305
+ | `codex` | Skill packages and verifier agents | `/truthmark-*` or `$truthmark-*` |
306
+ | `claude-code` | Project skills, verifier agents, and managed instructions | `/truthmark-*` |
307
+ | `github-copilot` | Agent skills, prompt commands, custom agents, and managed instructions | `/truthmark-*` in supported Copilot IDEs; `@truth-*` custom agents in Copilot CLI |
308
+ | `opencode` | Skill packages and verifier agents | `/skill truthmark-*` |
309
+ | `gemini-cli` | Agent skills, slash commands, subagents, and managed instructions | `/truthmark:*` |
179
310
 
180
- 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:
311
+ Unknown platform names are config errors.
312
+
313
+ Removing a platform stops future refreshes for that platform. It does not delete previously generated files.
314
+
315
+ ## AI-facing workflows
316
+
317
+ These workflows are installed into supported AI coding hosts.
318
+
319
+ They are used by agents or agent hosts during repository work. They are not top-level shell commands.
320
+
321
+ | Workflow | Direction | Use it when | Write boundary |
322
+ | --- | --- | --- | --- |
323
+ | Truth Structure | topology-first | The default route is too broad, ownership spans multiple areas, or route files still point at placeholders. | Creates or repairs routing and starter truth docs. |
324
+ | Truth Document | implementation-first | Behavior already exists in code, but canonical truth docs are missing or weak. | Writes truth docs and routing only. Functional code must not change. |
325
+ | Truth Sync | code-first | Functional code changed and mapped truth docs may need to be updated before handoff. | Updates truth docs. Functional code must not be rewritten by Truth Sync. |
326
+ | Truth Preview | read-only | The agent needs to preview likely routing before edits. | Reads only. Does not authorize writes. |
327
+ | Truth Realize | doc-first | Product or architecture truth docs lead and code should be updated to match. | Updates code only. The agent must not edit the truth docs it is realizing. |
328
+ | Truth Check | audit-first | A reviewer or agent needs to audit repository truth health. | Audits and reports. |
329
+
330
+ ### Important distinction
331
+
332
+ Do not confuse these two surfaces:
333
+
334
+ | Surface | Used by | Example | Meaning |
335
+ | --- | --- | --- | --- |
336
+ | Human CLI | humans, scripts, CI-like checks | `truthmark check` | Validate repository truth artifacts from the terminal. |
337
+ | AI-facing workflow | coding agents and agent hosts | `/truthmark-check` | Ask an agent to run the installed audit workflow. |
338
+
339
+ The names are intentionally related, but the surfaces are different.
340
+
341
+ ## Normal AI-assisted code change
342
+
343
+ Most users should not need to invoke Truth Sync manually every time.
344
+
345
+ Truth Sync is the installed finish-time guard for functional code changes.
181
346
 
182
347
  ```text
183
348
  agent changes functional code
184
- run relevant tests
185
- the installed Truth Sync workflow runs before the agent finishes
186
- review the truth-doc diff if one was produced
187
- commit or hand off the work
349
+ agent runs or asks for relevant tests
350
+ installed workflow detects that functional code changed
351
+ Truth Sync checks mapped truth docs
352
+ agent updates truth docs if needed
353
+ human reviews code diff + truth diff
188
354
  ```
189
355
 
190
- 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.
191
-
192
- Codex, Claude Code, and supported Copilot IDEs can invoke it with `/truthmark-sync`. OpenCode-style hosts can invoke `/skill truthmark-sync`.
356
+ Direct invocation is still useful for troubleshooting, forcing an early sync, or making the handoff explicit:
193
357
 
194
358
  ```text
195
359
  /truthmark-sync sync the repository truth now before handoff
196
360
  ```
197
361
 
198
- ### Doc-first changes
362
+ ## Existing behavior without docs
199
363
 
200
- Use this when a product or architecture decision starts in docs:
364
+ Use Truth Document when the implementation already exists but the repository truth is incomplete.
201
365
 
202
366
  ```text
203
- user edits truth docs
204
- user explicitly invokes Truth Realize
205
- agent reads truth docs and relevant code
206
- agent updates code only
207
- run relevant tests
208
- commit or hand off the work
367
+ /truthmark-document document the implemented session timeout behavior under docs/truth/authentication
209
368
  ```
210
369
 
211
- Truth Realize is manual and doc-first: truth docs lead, code follows, and the agent must not edit the truth docs it is realizing.
370
+ Truth Document inspects implementation, tests, route files, and existing docs as evidence.
371
+
372
+ It writes truth docs and routing only.
373
+
374
+ It must not change functional code.
375
+
376
+ ## Doc-first changes
212
377
 
213
- Codex, Claude Code, and supported Copilot IDEs can invoke it with `/truthmark-realize`. OpenCode-style hosts can invoke `/skill truthmark-realize`.
378
+ Use Truth Realize when a product or architecture decision starts in docs and code should be updated to match.
214
379
 
215
380
  ```text
216
381
  /truthmark-realize realize docs/truth/authentication/session-timeout.md into code
217
382
  ```
218
383
 
219
- ## What it installs
384
+ Truth Realize is doc-first.
220
385
 
221
- 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.
386
+ The truth docs lead. The code follows.
222
387
 
223
- Truthmark installs two distinct surfaces:
388
+ The agent must not edit the truth docs it is realizing.
224
389
 
225
- - 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
226
- - agent workflow surfaces, invoked by coding agents or agent hosts during implementation workflows; they are not extra daily terminal commands for humans
390
+ ## Read-only routing preview
227
391
 
228
- - `.truthmark/config.yml` for the machine-readable committed hierarchy contract
229
- - `docs/truthmark/areas.md` for the root route index
230
- - `docs/truthmark/areas/**/*.md` for delegated child route files
231
- - `docs/templates/behavior-doc.md` plus the other kind-specific templates under `docs/templates/` for the editable truth-doc standards used by generated workflows
232
- - managed instruction blocks for configured platforms such as `AGENTS.md`, `CLAUDE.md`, Copilot instructions, and `GEMINI.md`
233
- - host-native skills, prompts, or commands for Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize, and Truth Check
234
- - 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
392
+ Use Truth Preview before a change when the agent needs to understand likely routing.
235
393
 
236
- The installed workflow surfaces are the runtime:
394
+ ```text
395
+ /truthmark-preview preview the likely truth routing for changes to the billing API
396
+ ```
397
+
398
+ Truth Preview is read-only.
399
+
400
+ It is a selector and planning aid, not write authorization and not a replacement for Truth Check.
401
+
402
+ ## Repository truth audit
403
+
404
+ Use Truth Check when you want an agent-facing audit workflow.
405
+
406
+ ```text
407
+ /truthmark-check audit routing and truth coverage before review
408
+ ```
237
409
 
238
- - Truth Structure creates or repairs area routing and starter truth docs.
239
- - Truth Document creates or repairs truth docs for existing implemented behavior.
240
- - Truth Sync keeps mapped truth docs aligned with functional changes.
241
- - Truth Preview previews likely workflow routing before edits without writing files.
242
- - Truth Realize updates code to match truth docs.
243
- - Truth Check audits repository truth health.
410
+ Use the human-facing CLI when you want terminal validation:
411
+
412
+ ```bash
413
+ truthmark check
414
+ ```
244
415
 
245
- 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.
416
+ Both are useful. They are not the same surface.
246
417
 
247
- Generated surfaces are managed by Truthmark, include a version marker, and may be refreshed by `truthmark init`.
418
+ ## Human-facing CLI commands
248
419
 
249
- ## Commands
420
+ Most maintainers start with three commands.
250
421
 
251
- Truthmark V1 keeps the terminal CLI focused. Most human users only need setup, refresh, and validation:
422
+ | Command | Purpose |
423
+ | --- | --- |
424
+ | `truthmark config` | Create `.truthmark/config.yml`. Writes only that file unless `--stdout` is used. |
425
+ | `truthmark init` | Install or refresh configured workflow surfaces from the reviewed config. |
426
+ | `truthmark check` | Validate configuration, authority, routing, decision-bearing docs, frontmatter, internal links, branch scope, generated surfaces, freshness, and coverage diagnostics. |
252
427
 
253
- | Human-facing CLI | Use |
254
- | ---------------- | --- |
255
- | `truthmark config` | Create `.truthmark/config.yml`; writes only that file unless `--stdout` is used. |
256
- | `truthmark init` | Install or refresh local workflow files from the reviewed config. |
257
- | `truthmark check` | Validate configuration, authority, routing, decision-bearing docs, frontmatter, internal links, branch scope, and coverage diagnostics. |
428
+ Optional repository-intelligence helpers generate derived review context for the active checkout. Generated workflow skill packages may also expose helper manifests and helper policies that call installed `truthmark validate ... --json` CLI validators; those helpers are accelerators, not bundled repo-local scripts or sources of truth. Standalone Copilot prompts and Gemini commands use the same CLI validator contract when the installed runner is available, and otherwise report a visible skipped helper status with manual validation.
258
429
 
259
- The remaining CLI commands are optional repository-intelligence helpers. They generate derived review context for the active checkout; they are not sources of truth:
430
+ They are not sources of truth.
260
431
 
261
- | Optional CLI | Use |
262
- | ------------ | --- |
432
+ | Command | Purpose |
433
+ | --- | --- |
263
434
  | `truthmark index` | Build RepoIndex and RouteMap JSON for the active checkout. |
264
435
  | `truthmark impact --base <ref>` | Map changed files to routed truth docs, owning routes, nearby tests, and public symbols. |
265
- | `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. |
436
+ | `truthmark context --workflow <workflow> [--base <ref>]` | Generate a bounded ContextPack for Truth Sync, Truth Document, or Truth Realize. Use `--format markdown` for a human-readable pack. |
266
437
 
267
- All CLI commands above support `--json` where structured output is useful for automation.
438
+ Structured output is available with `--json` where supported.
268
439
 
269
- Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize, and Truth Check are installed agent workflows, not top-level daily CLI commands.
440
+ ## Configuration
270
441
 
271
- They run through the configured agent host surfaces, for example Codex/Claude/Copilot `/truthmark-*`, OpenCode `/skill truthmark-*`, or Gemini `/truthmark:*`.
442
+ Truthmark is config-first.
272
443
 
273
- 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.
444
+ The main config file is:
274
445
 
275
446
  ```text
276
- /truthmark-check audit routing and truth coverage before review
447
+ .truthmark/config.yml
277
448
  ```
278
449
 
279
- ## Why it exists
450
+ New repositories should run:
280
451
 
281
- Most AI coding workflows optimize for the next answer. Truthmark optimizes for the next handoff.
452
+ ```bash
453
+ truthmark config
454
+ ```
282
455
 
283
- It assumes serious teams need:
456
+ Then review the generated config before running:
284
457
 
285
- - branch-specific product truth
286
- - durable architecture and API decisions
287
- - explicit ownership between docs and code
288
- - safe write boundaries for agents
289
- - ordinary Git diffs that humans can review
290
- - readable Markdown that teammates can inspect without special tooling
291
- - truth that travels with the branch instead of living in hidden session state
292
- - workflows that still work when the package is not installed globally
458
+ ```bash
459
+ truthmark init
460
+ ```
461
+
462
+ Important config areas include:
463
+
464
+ | Config area | Purpose |
465
+ | --- | --- |
466
+ | `version` | Config contract version. |
467
+ | `platforms` | Agent hosts that should receive platform-specific generated surfaces. |
468
+ | `docs.layout` | Current docs layout mode. |
469
+ | `docs.roots` | Named canonical documentation roots. |
470
+ | `docs.routing.root_index` | Root route index path. |
471
+ | `docs.routing.area_files_root` | Directory for delegated child route files. |
472
+ | `docs.routing.default_area` | Initial scaffolded child route basename. |
473
+ | `docs.routing.max_delegation_depth` | Current maximum route delegation depth. |
474
+ | `authority` | Ordered canonical docs and globs used as repository truth authority. |
475
+ | `instruction_targets` | Files that receive shared managed instruction blocks, such as `AGENTS.md`. |
476
+ | `frontmatter.required` | Metadata fields that produce error diagnostics when missing. |
477
+ | `frontmatter.recommended` | Metadata fields that produce review diagnostics when missing. |
478
+ | `ignore` | Glob patterns excluded from relevant checks and routing logic. |
479
+
480
+ ## Repository truth routing
481
+
482
+ Truthmark maps code surfaces to truth docs.
483
+
484
+ The main routing files are:
485
+
486
+ ```text
487
+ docs/truthmark/areas.md
488
+ docs/truthmark/areas/**/*.md
489
+ ```
490
+
491
+ A route tells the agent:
492
+
493
+ - which code surface belongs to an area
494
+ - which truth docs own that area
495
+ - when truth should be updated
496
+ - what kind of truth doc is involved
497
+
498
+ The default scaffold starts broad. Existing repositories should usually split the default route into real ownership areas.
499
+
500
+ Example:
501
+
502
+ ```text
503
+ /truthmark-structure split the broad repository area into frontend, backend, billing, and deployment
504
+ ```
505
+
506
+ Good routing gives Truth Sync precise destinations.
507
+
508
+ Bad routing makes agents guess.
509
+
510
+ ## What Truthmark installs
511
+
512
+ Truthmark installs a compact repository-native truth layer.
513
+
514
+ It does this in four layers:
515
+
516
+ - configuration and routing for ownership boundaries
517
+ - canonical truth docs and starter templates
518
+ - compact managed instruction blocks for repository-wide agent context
519
+ - host-native workflow packages, commands, prompts, and verifier agents for the platforms enabled in config
520
+
521
+ Truthmark preserves manual content outside managed instruction blocks.
522
+
523
+ Generated workflow surfaces are managed by Truthmark and may be refreshed by rerunning:
524
+
525
+ ```bash
526
+ truthmark init
527
+ ```
528
+
529
+ ## Subagents and bounded evidence checks
530
+
531
+ Where supported by the host, Truthmark can install project-scoped verifier agents and a leased `truth-doc-writer`.
532
+
533
+ These help keep large truth tasks bounded:
534
+
535
+ - route auditors inspect route ownership
536
+ - claim verifiers check whether doc claims are supported by evidence
537
+ - doc reviewers inspect truth-doc quality
538
+ - leased doc writers handle bounded truth-doc writing shards
539
+
540
+ The parent workflow still owns final interpretation, write boundaries, diff validation, and acceptance.
541
+
542
+ This is important: subagents help with bounded evidence work. They do not replace the main workflow contract.
543
+
544
+ ## Review loop
545
+
546
+ Truthmark is designed for ordinary Git review.
547
+
548
+ A good AI-assisted handoff should show:
549
+
550
+ ```text
551
+ code diff
552
+ test evidence
553
+ truth-doc diff, if needed
554
+ routing changes, if needed
555
+ agent report
556
+ ```
557
+
558
+ The reviewer should be able to answer:
559
+
560
+ - What code changed?
561
+ - Which truth docs own that code?
562
+ - Did those docs need updates?
563
+ - If not, why not?
564
+ - Did the agent stay inside the workflow write boundary?
565
+ - Are tests or verification evidence included?
566
+
567
+ ## Examples
568
+
569
+ ### Initialize a repository
570
+
571
+ ```bash
572
+ npm install -g truthmark
573
+ truthmark config
574
+ truthmark init
575
+ truthmark check
576
+ ```
577
+
578
+ ### Remove unused agent platforms
579
+
580
+ Edit:
581
+
582
+ ```text
583
+ .truthmark/config.yml
584
+ ```
585
+
586
+ Then rerun:
293
587
 
294
- Truthmark is not a memory server and it is not an MCP server. It is a repository practice packaged as a small CLI installer plus agent-native workflow surfaces that turn AI workflow rules into repo infrastructure.
588
+ ```bash
589
+ truthmark init
590
+ truthmark check
591
+ ```
592
+
593
+ ### Split broad routing
594
+
595
+ ```text
596
+ /truthmark-structure split the broad repository area into auth, billing, notifications, and deployment
597
+ ```
598
+
599
+ ### Document implemented behavior
600
+
601
+ ```text
602
+ /truthmark-document document the implemented password reset flow under docs/truth/authentication
603
+ ```
604
+
605
+ ### Sync after code changes
606
+
607
+ ```text
608
+ /truthmark-sync sync the repository truth now before handoff
609
+ ```
610
+
611
+ ### Realize a doc-first decision
612
+
613
+ ```text
614
+ /truthmark-realize realize docs/truth/billing/invoice-retry-policy.md into code
615
+ ```
616
+
617
+ ### Audit truth health from the terminal
618
+
619
+ ```bash
620
+ truthmark check
621
+ ```
622
+
623
+ ### Generate branch-impact context
624
+
625
+ ```bash
626
+ truthmark impact --base main
627
+ ```
628
+
629
+ ### Generate workflow context
630
+
631
+ ```bash
632
+ truthmark context --workflow truth-sync --base main --format markdown
633
+ ```
295
634
 
296
635
  ## Project status
297
636
 
298
- V1 currently provides:
637
+ Truthmark V1 currently provides:
299
638
 
300
639
  - `truthmark config`
301
640
  - `truthmark init`
@@ -303,15 +642,58 @@ V1 currently provides:
303
642
  - `truthmark index`
304
643
  - `truthmark impact`
305
644
  - `truthmark context`
306
- - managed `AGENTS.md` workflow instructions
307
- - generated Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize, and Truth Check skill surfaces for configured agent hosts
308
645
  - branch-scope metadata
309
- - config, authority, routing, decision-structure, frontmatter, link, freshness, and polyglot coverage diagnostics
310
- - derived RepoIndex, RouteMap, ImpactSet, and ContextPack artifacts for faster local review when the CLI is available
646
+ - managed instruction blocks
647
+ - generated Truth Structure workflow surfaces
648
+ - generated Truth Document workflow surfaces
649
+ - generated Truth Sync workflow surfaces
650
+ - generated Truth Preview workflow surfaces
651
+ - generated Truth Realize workflow surfaces
652
+ - generated Truth Check workflow surfaces
653
+ - route, authority, decision-structure, frontmatter, link, freshness, generated-surface, and coverage diagnostics
654
+ - derived RepoIndex, RouteMap, ImpactSet, and ContextPack artifacts
655
+ - host-specific surfaces for Codex, Claude Code, GitHub Copilot, OpenCode, and Gemini CLI
656
+
657
+ ## Development
658
+
659
+ Install dependencies:
660
+
661
+ ```bash
662
+ npm install
663
+ ```
664
+
665
+ Run the local development CLI:
666
+
667
+ ```bash
668
+ npm run dev -- init
669
+ npm run dev -- check
670
+ ```
671
+
672
+ Run the full project check:
673
+
674
+ ```bash
675
+ npm run check
676
+ ```
677
+
678
+ Useful scripts:
679
+
680
+ | Script | Purpose |
681
+ | --- | --- |
682
+ | `npm run dev` | Run the TypeScript CLI entry point with `tsx`. |
683
+ | `npm run build` | Build the package. |
684
+ | `npm run lint` | Run ESLint. |
685
+ | `npm run typecheck` | Run TypeScript checks. |
686
+ | `npm run test` | Run tests. |
687
+ | `npm run check` | Run lint, typecheck, tests, and build. |
688
+ | `npm run release:check` | Run release-oriented validation. |
689
+
690
+ When changing Truthmark itself, see [CONTRIBUTORS.md](CONTRIBUTORS.md).
311
691
 
312
692
  ## Documentation
313
693
 
314
- The root README is for people evaluating and trying the package. Detailed functional and business specifications live under `docs/`:
694
+ The README is the fast path for evaluation and setup.
695
+
696
+ Detailed current behavior lives under `docs/`:
315
697
 
316
698
  - [Docs index](docs/README.md)
317
699
  - [Architecture overview](docs/architecture/overview.md)
@@ -321,11 +703,11 @@ The root README is for people evaluating and trying the package. Detailed functi
321
703
  - [Installed workflows](docs/truth/workflows/overview.md)
322
704
  - [Repository truth maintenance guide](docs/standards/maintaining-repository-truth.md)
323
705
 
324
- Current behavior belongs in the canonical docs tree above.
706
+ ## Design boundaries
325
707
 
326
- ## Non-goals
708
+ Truthmark is intentionally small.
327
709
 
328
- Truthmark V1 is not:
710
+ It is not:
329
711
 
330
712
  - a hosted service
331
713
  - an MCP server
@@ -334,8 +716,49 @@ Truthmark V1 is not:
334
716
  - a CI or PR enforcement product
335
717
  - a replacement for tests, code review, or technical leadership
336
718
  - an autonomous code rewrite engine
719
+ - a model-training or fine-tuning framework
720
+ - a hidden memory layer
721
+
722
+ Those boundaries are part of the product.
723
+
724
+ Truthmark keeps the workflow local, committed, branch-scoped, and reviewable.
725
+
726
+ ## Safety and review discipline
727
+
728
+ Truthmark helps the repository stay honest. It does not prove the code is correct.
729
+
730
+ Teams should still:
731
+
732
+ - run relevant tests
733
+ - review functional code changes
734
+ - review truth-doc changes
735
+ - keep secrets out of docs
736
+ - keep repository-specific instructions outside managed blocks
737
+ - review generated workflow-surface diffs after upgrades
738
+ - keep human ownership over product and architecture decisions
739
+
740
+ Truthmark makes agent context visible. It does not replace human judgment.
741
+
742
+ ## Roadmap direction
743
+
744
+ The current future direction emphasizes:
337
745
 
338
- It is a lightweight way to make local AI coding agents respect the truth your team keeps in Git.
746
+ - stronger `truthmark check` evidence reporting
747
+ - clearer adoption examples
748
+ - example repositories showing real Truth Sync cycles
749
+ - migration guides for teams already using agent instruction files
750
+ - conformance tests for generated host surfaces
751
+ - route-aware stale-truth hints
752
+ - bounded implementation checklists for doc-first work
753
+
754
+ The center of gravity stays the same:
755
+
756
+ ```text
757
+ repository truth
758
+ agent-native workflows
759
+ Git review
760
+ branch-scoped context
761
+ ```
339
762
 
340
763
  ## License
341
764