truthmark 1.4.0 → 1.6.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 +672 -194
  2. package/README.es.md +673 -195
  3. package/README.md +663 -192
  4. package/README.ru.md +680 -202
  5. package/README.zh.md +679 -199
  6. package/dist/main.js +1307 -145
  7. package/dist/main.js.map +1 -1
  8. package/package.json +1 -2
package/README.md CHANGED
@@ -1,301 +1,687 @@
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
+ ```
124
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
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.
165
+
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.
167
+
168
+ ## First real use
169
+
170
+ Most repositories need one cleanup pass after initialization.
147
171
 
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`.
172
+ The default scaffold starts with a broad `repository` area. Real repositories usually need more precise routing.
149
173
 
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`.
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
+ | Optional Portal | Generates a committed static HTML presentation site from Markdown truth docs when explicitly enabled and requested. |
198
+
199
+ ## Visual overview
200
+
201
+ ![Truthmark features](docs/assets/truthmark-features.png)
202
+
203
+ **Features:** what Truthmark installs and how the workflow surface is split.
204
+
205
+ ![Truthmark position](docs/assets/truthmark-position.png)
206
+
207
+ **Position:** where Truthmark fits relative to prompts, memory, and spec workflows.
208
+
209
+ ![Truthmark sync flow](docs/assets/truthmark-syncflow.png)
210
+
211
+ **Sync flow:** how Truth Sync closes out normal code changes before handoff.
212
+
213
+ ## Why teams adopt it
214
+
215
+ Truthmark is for teams that already know AI agents can generate code.
216
+
217
+ The next problem is governance.
218
+
219
+ Not governance as ceremony. Governance as a simple question:
220
+
221
+ > After this AI-assisted change, does the repository still tell the truth?
157
222
 
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.
223
+ Truthmark helps teams answer that with committed files, explicit routing, and reviewable diffs.
159
224
 
160
- ### Existing behavior without docs
225
+ It is useful when you need:
161
226
 
162
- Use this when implementation already exists but the canonical truth docs are missing or weak:
227
+ - less documentation drift
228
+ - better handoffs
229
+ - branch-specific product truth
230
+ - durable architecture and API context
231
+ - explicit ownership between docs and code
232
+ - safer agent write boundaries
233
+ - reviewable context instead of hidden memory
234
+ - AI workflows that still work from committed repo files
235
+
236
+ ## Where Truthmark fits
237
+
238
+ Truthmark does not replace prompts, memory, specs, tests, or code review.
239
+
240
+ It gives those workflows a durable place to land in Git.
241
+
242
+ | Need | Better fit |
243
+ | --- | --- |
244
+ | Better output from one agent session | Better prompt |
245
+ | Personal or session-level continuity | Memory tool |
246
+ | Plan-first feature work | Spec workflow |
247
+ | Branch-scoped truth that travels with code | Truthmark |
248
+ | Validating behavior correctness | Tests and review |
249
+ | Reviewing AI-assisted context changes | Truthmark plus Git review |
250
+
251
+ Truthmark’s lane is narrow by design:
163
252
 
164
253
  ```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
254
+ make repository truth explicit
255
+ route it to code
256
+ install agent workflows around it
257
+ keep the result reviewable in Git
170
258
  ```
171
259
 
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`.
260
+ ## How Truthmark runs
173
261
 
174
- ```text
175
- /truthmark-document document the implemented session timeout behavior under docs/truth/authentication
262
+ Truthmark runs locally against the active Git worktree.
263
+
264
+ The human-facing CLI reads and writes repository files, then exits.
265
+
266
+ 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.
267
+
268
+ The layers fit together like this:
269
+
270
+ ```mermaid
271
+ flowchart LR
272
+ Human["Human / CI"] --> CLI["Truthmark CLI"]
273
+ CLI --> Config["Config and route map"]
274
+ CLI --> Truth["Canonical truth docs"]
275
+ CLI --> Surfaces["Generated host-native workflows"]
276
+ Surfaces --> Hosts["Codex / Claude Code / Copilot / OpenCode / Gemini"]
277
+ Hosts --> Worktree["Active Git worktree"]
278
+ Hosts -->|"helper checks / validate / index"| CLI
279
+ Worktree --> Truth
280
+ ```
281
+
282
+ 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.
283
+
284
+ 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.
285
+
286
+ Generated workflow surfaces include Truthmark version markers. After upgrading Truthmark, rerun:
287
+
288
+ ```bash
289
+ truthmark init
290
+ ```
291
+
292
+ Then review the generated diffs.
293
+
294
+ ## Supported agent platforms
295
+
296
+ The default config includes every supported platform.
297
+
298
+ Remove platforms you do not use from `.truthmark/config.yml`, then rerun:
299
+
300
+ ```bash
301
+ truthmark init
176
302
  ```
177
303
 
178
- ### Normal code changes
304
+ | Platform config name | Generated surface | Invocation shape |
305
+ | --- | --- | --- |
306
+ | `codex` | Skill packages and verifier agents | `/truthmark-*` or `$truthmark-*` |
307
+ | `claude-code` | Project skills, verifier agents, and managed instructions | `/truthmark-*` |
308
+ | `github-copilot` | Agent skills, prompt commands, custom agents, and managed instructions | `/truthmark-*` in supported Copilot IDEs; `@truth-*` custom agents in Copilot CLI |
309
+ | `opencode` | Skill packages and verifier agents | `/skill truthmark-*` |
310
+ | `gemini-cli` | Agent skills, slash commands, subagents, and managed instructions | `/truthmark:*` |
311
+
312
+ Unknown platform names are config errors.
313
+
314
+ Removing a platform stops future refreshes for that platform. It does not delete previously generated files.
315
+
316
+ ## AI-facing workflows
317
+
318
+ These workflows are installed into supported AI coding hosts.
319
+
320
+ They are used by agents or agent hosts during repository work. They are not top-level shell commands.
321
+
322
+ | Workflow | Direction | Use it when | Write boundary |
323
+ | --- | --- | --- | --- |
324
+ | 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. |
325
+ | 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. |
326
+ | 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. |
327
+ | Truth Preview | read-only | The agent needs to preview likely routing before edits. | Reads only. Does not authorize writes. |
328
+ | 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. |
329
+ | Truth Check | audit-first | A reviewer or agent needs to audit repository truth health. | Audits and reports. |
330
+ | Truthmark Portal | presentation-only | A human explicitly asks for a browsable static HTML Portal over repository truth docs. | Writes generated non-canonical static files only under the configured Portal output directory. |
331
+
332
+ ### Important distinction
179
333
 
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:
334
+ Do not confuse these two surfaces:
335
+
336
+ | Surface | Used by | Example | Meaning |
337
+ | --- | --- | --- | --- |
338
+ | Human CLI | humans, scripts, CI-like checks | `truthmark check` | Validate repository truth artifacts from the terminal. |
339
+ | AI-facing workflow | coding agents and agent hosts | `/truthmark-check` | Ask an agent to run the installed audit workflow. |
340
+
341
+ The names are intentionally related, but the surfaces are different.
342
+
343
+ ## Normal AI-assisted code change
344
+
345
+ Most users should not need to invoke Truth Sync manually every time.
346
+
347
+ Truth Sync is the installed finish-time guard for functional code changes.
181
348
 
182
349
  ```text
183
350
  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
351
+ agent runs or asks for relevant tests
352
+ installed workflow detects that functional code changed
353
+ Truth Sync checks mapped truth docs
354
+ agent updates truth docs if needed
355
+ human reviews code diff + truth diff
188
356
  ```
189
357
 
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`.
358
+ Direct invocation is still useful for troubleshooting, forcing an early sync, or making the handoff explicit:
193
359
 
194
360
  ```text
195
361
  /truthmark-sync sync the repository truth now before handoff
196
362
  ```
197
363
 
198
- ### Doc-first changes
364
+ ## Existing behavior without docs
199
365
 
200
- Use this when a product or architecture decision starts in docs:
366
+ Use Truth Document when the implementation already exists but the repository truth is incomplete.
201
367
 
202
368
  ```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
369
+ /truthmark-document document the implemented session timeout behavior under docs/truth/authentication
209
370
  ```
210
371
 
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.
372
+ Truth Document inspects implementation, tests, route files, and existing docs as evidence.
373
+
374
+ It writes truth docs and routing only.
375
+
376
+ It must not change functional code.
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
+ ## Doc-first changes
379
+
380
+ Use Truth Realize when a product or architecture decision starts in docs and code should be updated to match.
214
381
 
215
382
  ```text
216
383
  /truthmark-realize realize docs/truth/authentication/session-timeout.md into code
217
384
  ```
218
385
 
219
- ## What it installs
386
+ Truth Realize is doc-first.
220
387
 
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.
388
+ The truth docs lead. The code follows.
222
389
 
223
- Truthmark installs two distinct surfaces:
390
+ The agent must not edit the truth docs it is realizing.
224
391
 
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
392
+ ## Read-only routing preview
227
393
 
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
394
+ Use Truth Preview before a change when the agent needs to understand likely routing.
235
395
 
236
- The installed workflow surfaces are the runtime:
396
+ ```text
397
+ /truthmark-preview preview the likely truth routing for changes to the billing API
398
+ ```
237
399
 
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.
400
+ Truth Preview is read-only.
244
401
 
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.
402
+ It is a selector and planning aid, not write authorization and not a replacement for Truth Check.
246
403
 
247
- Generated surfaces are managed by Truthmark, include a version marker, and may be refreshed by `truthmark init`.
404
+ ## Repository truth audit
248
405
 
249
- ## Commands
406
+ Use Truth Check when you want an agent-facing audit workflow.
250
407
 
251
- Truthmark V1 keeps the terminal CLI focused. Most human users only need setup, refresh, and validation:
408
+ ```text
409
+ /truthmark-check audit routing and truth coverage before review
410
+ ```
252
411
 
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. |
412
+ Use the human-facing CLI when you want terminal validation:
258
413
 
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:
414
+ ```bash
415
+ truthmark check
416
+ ```
260
417
 
261
- | Optional CLI | Use |
262
- | ------------ | --- |
418
+ Both are useful. They are not the same surface.
419
+
420
+ ## Human-facing CLI commands
421
+
422
+ Most maintainers start with three commands.
423
+
424
+ | Command | Purpose |
425
+ | --- | --- |
426
+ | `truthmark config` | Create `.truthmark/config.yml`. Writes only that file unless `--stdout` is used. |
427
+ | `truthmark init` | Install or refresh configured workflow surfaces from the reviewed config. |
428
+ | `truthmark check` | Validate configuration, authority, routing, decision-bearing docs, frontmatter, internal links, branch scope, generated surfaces, freshness, and coverage diagnostics. |
429
+
430
+ 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.
431
+
432
+ They are not sources of truth.
433
+
434
+ | Command | Purpose |
435
+ | --- | --- |
263
436
  | `truthmark index` | Build RepoIndex and RouteMap JSON for the active checkout. |
264
437
  | `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. |
438
+ | `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. |
439
+
440
+ Structured output is available with `--json` where supported.
441
+
442
+ ## Truthmark Portal
443
+
444
+ Truthmark Portal is an optional presentation workflow for teams that want a human-readable site over their committed truth docs.
445
+
446
+ It is deliberately separate from the core truth workflow:
447
+
448
+ - Markdown truth docs remain canonical.
449
+ - Generated Portal HTML is presentation only.
450
+ - Portal is manual-only; it does not run as a completion gate, Truth Sync step, `truthmark check` step, or automatic post-change hook.
451
+ - Portal writes stay inside the configured output directory unless the user explicitly changes scope.
452
+ - Generated pages should use local assets, source provenance, and a visible Markdown-canonical disclaimer.
453
+
454
+ Enable it with the namespaced config block:
455
+
456
+ ```yaml
457
+ truthmark-portal:
458
+ enabled: true
459
+ output: docs/truthmark-portal
460
+ template: default
461
+ ```
462
+
463
+ Then rerun:
464
+
465
+ ```bash
466
+ truthmark init
467
+ ```
266
468
 
267
- All CLI commands above support `--json` where structured output is useful for automation.
469
+ When enabled, Truthmark installs host-native Portal workflow surfaces for the configured platforms, such as `/truthmark-portal` or `/truthmark:portal` depending on the agent host.
268
470
 
269
- Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize, and Truth Check are installed agent workflows, not top-level daily CLI commands.
471
+ ## Configuration
270
472
 
271
- They run through the configured agent host surfaces, for example Codex/Claude/Copilot `/truthmark-*`, OpenCode `/skill truthmark-*`, or Gemini `/truthmark:*`.
473
+ Truthmark is config-first.
272
474
 
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.
475
+ The main config file is:
274
476
 
275
477
  ```text
276
- /truthmark-check audit routing and truth coverage before review
478
+ .truthmark/config.yml
277
479
  ```
278
480
 
279
- ## Why it exists
481
+ New repositories should run:
280
482
 
281
- Most AI coding workflows optimize for the next answer. Truthmark optimizes for the next handoff.
483
+ ```bash
484
+ truthmark config
485
+ ```
282
486
 
283
- It assumes serious teams need:
487
+ Then review the generated config before running:
284
488
 
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
489
+ ```bash
490
+ truthmark init
491
+ ```
492
+
493
+ Important config areas include:
494
+
495
+ | Config area | Purpose |
496
+ | --- | --- |
497
+ | `version` | Config contract version. |
498
+ | `platforms` | Agent hosts that should receive platform-specific generated surfaces. |
499
+ | `docs.layout` | Current docs layout mode. |
500
+ | `docs.roots` | Named canonical documentation roots. |
501
+ | `docs.routing.root_index` | Root route index path. |
502
+ | `docs.routing.area_files_root` | Directory for delegated child route files. |
503
+ | `docs.routing.default_area` | Initial scaffolded child route basename. |
504
+ | `docs.routing.max_delegation_depth` | Current maximum route delegation depth. |
505
+ | `truthmark-portal` | Optional manual presentation workflow settings: `enabled`, `output`, and `template`. |
506
+ | `authority` | Ordered canonical docs and globs used as repository truth authority. |
507
+ | `instruction_targets` | Files that receive shared managed instruction blocks, such as `AGENTS.md`. |
508
+ | `frontmatter.required` | Metadata fields that produce error diagnostics when missing. |
509
+ | `frontmatter.recommended` | Metadata fields that produce review diagnostics when missing. |
510
+ | `ignore` | Glob patterns excluded from relevant checks and routing logic. |
511
+
512
+ ## Repository truth routing
513
+
514
+ Truthmark maps code surfaces to truth docs.
515
+
516
+ The main routing files are:
517
+
518
+ ```text
519
+ docs/truthmark/areas.md
520
+ docs/truthmark/areas/**/*.md
521
+ ```
522
+
523
+ A route tells the agent:
524
+
525
+ - which code surface belongs to an area
526
+ - which truth docs own that area
527
+ - when truth should be updated
528
+ - what kind of truth doc is involved
529
+
530
+ The default scaffold starts broad. Existing repositories should usually split the default route into real ownership areas.
531
+
532
+ Example:
533
+
534
+ ```text
535
+ /truthmark-structure split the broad repository area into frontend, backend, billing, and deployment
536
+ ```
537
+
538
+ Good routing gives Truth Sync precise destinations.
539
+
540
+ Bad routing makes agents guess.
541
+
542
+ ## What Truthmark installs
543
+
544
+ Truthmark installs a compact repository-native truth layer.
545
+
546
+ It does this in four layers:
547
+
548
+ - configuration and routing for ownership boundaries
549
+ - canonical truth docs and starter templates
550
+ - compact managed instruction blocks for repository-wide agent context
551
+ - host-native workflow packages, commands, prompts, and verifier agents for the platforms enabled in config
552
+
553
+ Truthmark preserves manual content outside managed instruction blocks.
554
+
555
+ Generated workflow surfaces are managed by Truthmark and may be refreshed by rerunning:
556
+
557
+ ```bash
558
+ truthmark init
559
+ ```
560
+
561
+ ## Subagents and bounded evidence checks
562
+
563
+ Where supported by the host, Truthmark can install project-scoped verifier agents and a leased `truth-doc-writer`.
564
+
565
+ These help keep large truth tasks bounded:
566
+
567
+ - route auditors inspect route ownership
568
+ - claim verifiers check whether doc claims are supported by evidence
569
+ - doc reviewers inspect truth-doc quality
570
+ - leased doc writers handle bounded truth-doc writing shards
571
+
572
+ The parent workflow still owns final interpretation, write boundaries, diff validation, and acceptance.
573
+
574
+ This is important: subagents help with bounded evidence work. They do not replace the main workflow contract.
575
+
576
+ ## Review loop
577
+
578
+ Truthmark is designed for ordinary Git review.
579
+
580
+ A good AI-assisted handoff should show:
581
+
582
+ ```text
583
+ code diff
584
+ test evidence
585
+ truth-doc diff, if needed
586
+ routing changes, if needed
587
+ agent report
588
+ ```
589
+
590
+ The reviewer should be able to answer:
591
+
592
+ - What code changed?
593
+ - Which truth docs own that code?
594
+ - Did those docs need updates?
595
+ - If not, why not?
596
+ - Did the agent stay inside the workflow write boundary?
597
+ - Are tests or verification evidence included?
598
+
599
+ ## Examples
600
+
601
+ ### Initialize a repository
602
+
603
+ ```bash
604
+ npm install -g truthmark
605
+ truthmark config
606
+ truthmark init
607
+ truthmark check
608
+ ```
609
+
610
+ ### Remove unused agent platforms
611
+
612
+ Edit:
613
+
614
+ ```text
615
+ .truthmark/config.yml
616
+ ```
617
+
618
+ Then rerun:
619
+
620
+ ```bash
621
+ truthmark init
622
+ truthmark check
623
+ ```
624
+
625
+ ### Split broad routing
626
+
627
+ ```text
628
+ /truthmark-structure split the broad repository area into auth, billing, notifications, and deployment
629
+ ```
630
+
631
+ ### Document implemented behavior
632
+
633
+ ```text
634
+ /truthmark-document document the implemented password reset flow under docs/truth/authentication
635
+ ```
636
+
637
+ ### Sync after code changes
638
+
639
+ ```text
640
+ /truthmark-sync sync the repository truth now before handoff
641
+ ```
642
+
643
+ ### Realize a doc-first decision
293
644
 
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.
645
+ ```text
646
+ /truthmark-realize realize docs/truth/billing/invoice-retry-policy.md into code
647
+ ```
648
+
649
+ ### Audit truth health from the terminal
650
+
651
+ ```bash
652
+ truthmark check
653
+ ```
654
+
655
+ ### Generate branch-impact context
656
+
657
+ ```bash
658
+ truthmark impact --base main
659
+ ```
660
+
661
+ ### Generate workflow context
662
+
663
+ ```bash
664
+ truthmark context --workflow truth-sync --base main --format markdown
665
+ ```
666
+
667
+ ### Enable the optional Portal workflow
668
+
669
+ ```yaml
670
+ truthmark-portal:
671
+ enabled: true
672
+ output: docs/truthmark-portal
673
+ template: default
674
+ ```
675
+
676
+ ```bash
677
+ truthmark init
678
+ ```
679
+
680
+ Then explicitly ask the agent host to run the installed Portal workflow when you want the static presentation site generated or refreshed.
295
681
 
296
682
  ## Project status
297
683
 
298
- V1 currently provides:
684
+ Truthmark V1 currently provides:
299
685
 
300
686
  - `truthmark config`
301
687
  - `truthmark init`
@@ -303,15 +689,59 @@ V1 currently provides:
303
689
  - `truthmark index`
304
690
  - `truthmark impact`
305
691
  - `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
692
  - 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
693
+ - managed instruction blocks
694
+ - generated Truth Structure workflow surfaces
695
+ - generated Truth Document workflow surfaces
696
+ - generated Truth Sync workflow surfaces
697
+ - generated Truth Preview workflow surfaces
698
+ - generated Truth Realize workflow surfaces
699
+ - generated Truth Check workflow surfaces
700
+ - optional generated Truthmark Portal workflow surfaces
701
+ - route, authority, decision-structure, frontmatter, link, freshness, generated-surface, and coverage diagnostics
702
+ - derived RepoIndex, RouteMap, ImpactSet, and ContextPack artifacts
703
+ - host-specific surfaces for Codex, Claude Code, GitHub Copilot, OpenCode, and Gemini CLI
704
+
705
+ ## Development
706
+
707
+ Install dependencies:
708
+
709
+ ```bash
710
+ npm install
711
+ ```
712
+
713
+ Run the local development CLI:
714
+
715
+ ```bash
716
+ npm run dev -- init
717
+ npm run dev -- check
718
+ ```
719
+
720
+ Run the full project check:
721
+
722
+ ```bash
723
+ npm run check
724
+ ```
725
+
726
+ Useful scripts:
727
+
728
+ | Script | Purpose |
729
+ | --- | --- |
730
+ | `npm run dev` | Run the TypeScript CLI entry point with `tsx`. |
731
+ | `npm run build` | Build the package. |
732
+ | `npm run lint` | Run ESLint. |
733
+ | `npm run typecheck` | Run TypeScript checks. |
734
+ | `npm run test` | Run tests. |
735
+ | `npm run check` | Run lint, typecheck, tests, and build. |
736
+ | `npm run release:check` | Run release-oriented validation. |
737
+
738
+ When changing Truthmark itself, see [CONTRIBUTORS.md](CONTRIBUTORS.md).
311
739
 
312
740
  ## Documentation
313
741
 
314
- The root README is for people evaluating and trying the package. Detailed functional and business specifications live under `docs/`:
742
+ The README is the fast path for evaluation and setup.
743
+
744
+ Detailed current behavior lives under `docs/`:
315
745
 
316
746
  - [Docs index](docs/README.md)
317
747
  - [Architecture overview](docs/architecture/overview.md)
@@ -321,21 +751,62 @@ The root README is for people evaluating and trying the package. Detailed functi
321
751
  - [Installed workflows](docs/truth/workflows/overview.md)
322
752
  - [Repository truth maintenance guide](docs/standards/maintaining-repository-truth.md)
323
753
 
324
- Current behavior belongs in the canonical docs tree above.
754
+ ## Design boundaries
325
755
 
326
- ## Non-goals
756
+ Truthmark is intentionally small.
327
757
 
328
- Truthmark V1 is not:
758
+ It is not:
329
759
 
330
760
  - a hosted service
331
761
  - an MCP server
332
762
  - a vector database
333
- - a documentation website generator
763
+ - a canonical documentation website generator or hosted docs platform
334
764
  - a CI or PR enforcement product
335
765
  - a replacement for tests, code review, or technical leadership
336
766
  - an autonomous code rewrite engine
767
+ - a model-training or fine-tuning framework
768
+ - a hidden memory layer
769
+
770
+ Those boundaries are part of the product.
771
+
772
+ Truthmark keeps the workflow local, committed, branch-scoped, and reviewable.
337
773
 
338
- It is a lightweight way to make local AI coding agents respect the truth your team keeps in Git.
774
+ ## Safety and review discipline
775
+
776
+ Truthmark helps the repository stay honest. It does not prove the code is correct.
777
+
778
+ Teams should still:
779
+
780
+ - run relevant tests
781
+ - review functional code changes
782
+ - review truth-doc changes
783
+ - keep secrets out of docs
784
+ - keep repository-specific instructions outside managed blocks
785
+ - review generated workflow-surface diffs after upgrades
786
+ - keep human ownership over product and architecture decisions
787
+
788
+ Truthmark makes agent context visible. It does not replace human judgment.
789
+
790
+ ## Roadmap direction
791
+
792
+ The current future direction emphasizes:
793
+
794
+ - stronger `truthmark check` evidence reporting
795
+ - clearer adoption examples
796
+ - example repositories showing real Truth Sync cycles
797
+ - migration guides for teams already using agent instruction files
798
+ - conformance tests for generated host surfaces
799
+ - route-aware stale-truth hints
800
+ - bounded implementation checklists for doc-first work
801
+
802
+ The center of gravity stays the same:
803
+
804
+ ```text
805
+ repository truth
806
+ agent-native workflows
807
+ Git review
808
+ branch-scoped context
809
+ ```
339
810
 
340
811
  ## License
341
812