truthmark 2.2.7 → 2.3.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.
- package/README.md +119 -166
- package/dist/main.js +2156 -1914
- package/dist/main.js.map +1 -1
- package/docs/README.md +49 -37
- package/docs/assets/truthmark-workflow-mobile.svg +118 -0
- package/docs/assets/truthmark-workflow.svg +182 -0
- package/docs/readmes/README.ar.md +125 -160
- package/docs/readmes/README.de.md +127 -162
- package/docs/readmes/README.el.md +127 -162
- package/docs/readmes/README.es.md +125 -160
- package/docs/readmes/README.fr.md +125 -160
- package/docs/readmes/README.id.md +126 -161
- package/docs/readmes/README.it.md +125 -160
- package/docs/readmes/README.ja.md +126 -161
- package/docs/readmes/README.ko.md +127 -162
- package/docs/readmes/README.pl.md +125 -160
- package/docs/readmes/README.pt.md +126 -161
- package/docs/readmes/README.ru.md +124 -159
- package/docs/readmes/README.tr.md +125 -160
- package/docs/readmes/README.vi.md +126 -161
- package/docs/readmes/README.zh.md +128 -163
- package/package.json +3 -1
package/README.md
CHANGED
|
@@ -1,240 +1,193 @@
|
|
|
1
1
|
# Truthmark
|
|
2
2
|
|
|
3
|
-
**Your agents write code. Truthmark maintains human-facing, Git-reviewable documentation.**
|
|
3
|
+
**Your agents write code. Truthmark maintains the human-facing, Git-reviewable documentation.**
|
|
4
|
+
|
|
5
|
+
Truthmark installs Git-native workflows that let AI coding agents create new product and engineering documentation from existing code and tests, keep it current after every code change, and hand you ordinary Markdown diffs for review.
|
|
4
6
|
|
|
5
7
|
[](https://www.npmjs.com/package/truthmark)
|
|
6
8
|
[](https://github.com/merlinhu1/truthmark/actions/workflows/ci.yml)
|
|
7
9
|
[](LICENSE)
|
|
8
10
|
[](package.json)
|
|
9
11
|
|
|
10
|
-
[Website](https://merlinhu1.github.io/truthmark/)
|
|
12
|
+
[Get started](#quick-start-create-your-first-truth-document) · [Website](https://merlinhu1.github.io/truthmark/) · [User Guide](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md) · [GitHub](https://github.com/merlinhu1/truthmark)
|
|
13
|
+
|
|
14
|
+
<details>
|
|
15
|
+
<summary>Read this README in 16 languages</summary>
|
|
11
16
|
|
|
12
17
|
[🇺🇸 English](README.md) | [🇨🇳 简体中文](docs/readmes/README.zh.md) | [🇯🇵 日本語](docs/readmes/README.ja.md) | [🇰🇷 한국어](docs/readmes/README.ko.md) | [🇩🇪 Deutsch](docs/readmes/README.de.md) | [🇫🇷 Français](docs/readmes/README.fr.md) | [🇪🇸 Español](docs/readmes/README.es.md) | [🇧🇷 Português](docs/readmes/README.pt.md) | [🇷🇺 Русский](docs/readmes/README.ru.md) | [🇸🇦 العربية](docs/readmes/README.ar.md) | [🇮🇹 Italiano](docs/readmes/README.it.md) | [🇵🇱 Polski](docs/readmes/README.pl.md) | [🇹🇷 Türkçe](docs/readmes/README.tr.md) | [🇻🇳 Tiếng Việt](docs/readmes/README.vi.md) | [🇮🇩 Bahasa Indonesia](docs/readmes/README.id.md) | [🇬🇷 Ελληνικά](docs/readmes/README.el.md)
|
|
13
18
|
|
|
14
|
-
|
|
19
|
+
</details>
|
|
15
20
|
|
|
16
|
-
##
|
|
21
|
+
## Create the first docs. Keep them true.
|
|
17
22
|
|
|
18
|
-
|
|
23
|
+
Most documentation tools stop after generation. Truthmark gives agents a complete documentation lifecycle inside your repository:
|
|
19
24
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
+
- **Create new docs from working software.** Truth Document reads code and tests, then creates bounded product or engineering documentation.
|
|
26
|
+
- **Keep docs aligned automatically.** Truth Sync runs at agent handoff after functional code changes and updates repository truth before the work is finished.
|
|
27
|
+
- **Turn docs back into code.** Truth Realize implements approved truth docs while preserving a clean doc-first workflow.
|
|
28
|
+
- **Repair ownership as the codebase grows.** Truth Structure creates bounded routes and starter docs for new or overloaded areas.
|
|
29
|
+
- **Review everything in Git.** Code, decisions, contracts, architecture, operations, and behavior travel together with the branch.
|
|
25
30
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
- codex # or: claude-code, github-copilot, opencode, antigravity, cursor
|
|
32
|
-
truthmark:
|
|
33
|
-
workspace: docs/truthmark
|
|
34
|
-
generated:
|
|
35
|
-
portal:
|
|
36
|
-
enabled: false
|
|
37
|
-
```
|
|
31
|
+
No hosted knowledge base. No private agent memory. No documentation trapped in chat history.
|
|
32
|
+
|
|
33
|
+
## Quick Start: create your first truth document
|
|
34
|
+
|
|
35
|
+
**Requirements:** Node.js 24 or newer, a Git repository, and a supported AI coding host for agent workflows.
|
|
38
36
|
|
|
39
|
-
|
|
37
|
+
Run this inside the repository you want Truthmark to manage:
|
|
40
38
|
|
|
41
39
|
```bash
|
|
40
|
+
cd /path/to/your-repo
|
|
41
|
+
npm install -g truthmark
|
|
42
42
|
truthmark init
|
|
43
|
-
truthmark check
|
|
44
|
-
git diff
|
|
45
43
|
```
|
|
46
44
|
|
|
47
|
-
|
|
45
|
+
`truthmark init` lets you select Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor, or a host-neutral command-line interface setup.
|
|
46
|
+
|
|
47
|
+
Now ask your configured agent to document one real behavior:
|
|
48
48
|
|
|
49
49
|
```text
|
|
50
50
|
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
|
51
51
|
```
|
|
52
52
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
If you only want CLI validation and do not want host-specific AI workflows yet, leave `platforms` omitted and run `truthmark init && truthmark check`; you can add a platform later and rerun `truthmark init`.
|
|
56
|
-
|
|
57
|
-
## 💡 The Problem: The AI Documentation Gap
|
|
58
|
-
|
|
59
|
-
AI coding agents are incredible at writing code fast. But this speed creates a dangerous new failure mode: **the repository's story drifts from reality.**
|
|
60
|
-
|
|
61
|
-
* Behavior is lost in ephemeral chat histories.
|
|
62
|
-
* Architecture documents quickly fall behind.
|
|
63
|
-
* Product decisions vanish after handoff.
|
|
64
|
-
* Code reviewers are left examining raw code diffs without understanding the "why."
|
|
65
|
-
* Every new AI session is forced to rediscover your repository's truth from scratch.
|
|
53
|
+
Truth Document creates a new bounded truth doc when one does not exist, updates an existing owner when it does, and updates routing when needed. It does not change functional code.
|
|
66
54
|
|
|
67
|
-
|
|
55
|
+
Review the result:
|
|
68
56
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
### ✨ Why Truthmark is Unique
|
|
57
|
+
```bash
|
|
58
|
+
truthmark check
|
|
59
|
+
git status --short --untracked-files=all
|
|
60
|
+
git diff
|
|
61
|
+
```
|
|
76
62
|
|
|
77
|
-
|
|
63
|
+
You should now have:
|
|
78
64
|
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
* **✅ Trust Through Verification:** AI work becomes easier to trust because behavior-changing work includes a human-reviewable truth-doc decision or diff.
|
|
65
|
+
```text
|
|
66
|
+
docs/truthmark/engineering/behaviors/session-timeout.md
|
|
67
|
+
docs/truthmark/routes/areas/authentication.md
|
|
68
|
+
```
|
|
84
69
|
|
|
85
|
-
|
|
70
|
+
The exact paths follow your repository’s ownership structure. New files appear in `git status`; changes to tracked files appear in `git diff`.
|
|
86
71
|
|
|
87
|
-
|
|
72
|
+
Invocation varies by host. OpenCode uses `/skill truthmark-document`, Antigravity uses `@truthmark-document`, and other supported hosts use their native skill or slash-command surface. See the [platform table](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md#supported-agent-platforms) for exact commands.
|
|
88
73
|
|
|
89
|
-
|
|
90
|
-
2. 🧪 **Test:** Relevant tests are executed.
|
|
91
|
-
3. 🔍 **Check:** Truthmark checks mapped documentation as part of the installed finish-time review.
|
|
92
|
-
4. 📝 **Document:** Docs are updated by the agent when repository truth has changed.
|
|
93
|
-
5. 👀 **Review:** A human reviews the *code diff* + the *truth diff*.
|
|
74
|
+
For scripts and continuous integration, pass the selected platforms explicitly:
|
|
94
75
|
|
|
95
|
-
|
|
76
|
+
```bash
|
|
77
|
+
truthmark init --platform codex --platform cursor
|
|
78
|
+
truthmark init --json
|
|
79
|
+
```
|
|
96
80
|
|
|
97
|
-
|
|
81
|
+
Choose `none` interactively or run `truthmark init --clear-platforms` for a host-neutral repository. You can add agent platforms later by rerunning `truthmark init`.
|
|
98
82
|
|
|
99
|
-
|
|
83
|
+
For branch-relative freshness diagnostics, pass a Git base:
|
|
100
84
|
|
|
101
|
-
|
|
85
|
+
```bash
|
|
86
|
+
truthmark check --base <base-ref>
|
|
87
|
+
```
|
|
102
88
|
|
|
103
|
-
|
|
104
|
-
* `truthmark init` - install or refresh routing, truth-doc scaffolds, and AI-host instructions, reconciling safely recognized disabled-host surfaces.
|
|
105
|
-
* `truthmark check` - validate the repository truth from the terminal.
|
|
106
|
-
* `truthmark uninstall --dry-run|--apply` - preview or remove generated host surfaces while preserving authored truth and configuration.
|
|
89
|
+
## How Truthmark works
|
|
107
90
|
|
|
108
|
-
|
|
91
|
+
<picture>
|
|
92
|
+
<source media="(max-width: 700px)" srcset="docs/assets/truthmark-workflow-mobile.svg">
|
|
93
|
+
<img src="docs/assets/truthmark-workflow.svg" alt="How Truthmark works" width="1440">
|
|
94
|
+
</picture>
|
|
109
95
|
|
|
110
|
-
Truthmark installs
|
|
96
|
+
The Truthmark command-line interface installs and validates the repository contract. Your coding agent performs the evidence review and documentation work through the installed host-native workflows.
|
|
111
97
|
|
|
112
|
-
|
|
98
|
+
A normal code change follows one simple loop:
|
|
113
99
|
|
|
114
|
-
1.
|
|
115
|
-
2.
|
|
116
|
-
3.
|
|
100
|
+
1. The agent changes functional code.
|
|
101
|
+
2. Relevant tests run.
|
|
102
|
+
3. Truth Sync checks the mapped documentation.
|
|
103
|
+
4. The agent creates or updates docs and routing when repository truth changed.
|
|
104
|
+
5. You review the code diff and truth diff together.
|
|
117
105
|
|
|
118
|
-
|
|
106
|
+
## Workflows
|
|
119
107
|
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
108
|
+
| Workflow | Use it when | Result |
|
|
109
|
+
| -------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------- |
|
|
110
|
+
| **Truth Document** | Existing code needs documentation | Creates or updates evidence-backed product and engineering docs |
|
|
111
|
+
| **Truth Sync** | Functional code changed | Keeps mapped docs and routing aligned before handoff |
|
|
112
|
+
| **Truth Structure** | A new area needs ownership or existing docs are too broad | Creates bounded routes and skeletal starter docs |
|
|
113
|
+
| **Truth Realize** | An approved truth doc should become working software | Updates functional code from documentation |
|
|
114
|
+
| **Truth Check** | Repository truth needs an audit | Reports routing, ownership, evidence, and documentation issues |
|
|
115
|
+
| **Truthmark Portal** | The team wants a browsable documentation site | Generates a committed static HTML presentation from Markdown truth docs |
|
|
123
116
|
|
|
124
|
-
|
|
125
|
-
Truth Structure is not a day-to-day command; it repairs routing or ownership only when that blocks the work.
|
|
117
|
+
Truthmark installs these workflows as native repository surfaces for Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, and Cursor.
|
|
126
118
|
|
|
127
119
|
## What you get
|
|
128
120
|
|
|
129
|
-
|
|
130
|
-
| --- | --- |
|
|
131
|
-
| Git-native truth | Keeps repository truth in committed Markdown and config. |
|
|
132
|
-
| Branch-scoped documentation | Truth moves with the branch instead of living in a private session. |
|
|
133
|
-
| Human CLI | Gives maintainers setup, refresh, validation, and inspection commands. |
|
|
134
|
-
| Installed agent guidance | Tells coding agents when to document, test, sync truth, audit, or stop for review. |
|
|
135
|
-
| Explicit routing | Maps code areas to canonical truth docs. |
|
|
136
|
-
| Durable truth curation | Keeps docs bounded, evidence-backed, and reviewable instead of letting them grow into catch-all files. |
|
|
137
|
-
| Reviewable handoffs | Produces ordinary Git diffs for both code and truth docs. |
|
|
138
|
-
| Local-first operation | Requires no hosted service, daemon, database, or MCP server. |
|
|
139
|
-
| Safer write boundaries | Separates code-first, doc-first, read-only, and doc-only workflows. |
|
|
140
|
-
| Validation | Reports routing, authority, frontmatter, link, generated-surface, branch-scope, freshness, and coverage issues. |
|
|
141
|
-
| Optional Portal | Generates a committed static HTML presentation site from Markdown truth docs when explicitly enabled and requested. |
|
|
142
|
-
|
|
143
|
-
## Visual overview
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
**Features:** what Truthmark installs and how agents use repo-local instructions.
|
|
148
|
-
|
|
149
|
-
|
|
121
|
+
### Documentation that starts from reality
|
|
150
122
|
|
|
151
|
-
|
|
123
|
+
Truthmark can create documentation for product capabilities, implementation behavior, application programming interfaces, architecture, workflows, operations, and tests. Code and tests provide the evidence; bounded Markdown docs preserve the result.
|
|
152
124
|
|
|
153
|
-
|
|
125
|
+
### Documentation that survives the next change
|
|
154
126
|
|
|
155
|
-
|
|
127
|
+
Routes connect code areas to canonical docs. When agents change behavior, Truth Sync knows where the corresponding truth belongs and keeps the handoff reviewable.
|
|
156
128
|
|
|
157
|
-
|
|
129
|
+
### Product and engineering truth in separate lanes
|
|
158
130
|
|
|
159
|
-
|
|
131
|
+
Product truth captures user-facing promises, boundaries, decisions, and acceptance criteria. Engineering truth captures current behavior, contracts, architecture, workflows, operations, and test behavior.
|
|
160
132
|
|
|
161
|
-
|
|
133
|
+
### Git-native collaboration
|
|
162
134
|
|
|
163
|
-
|
|
135
|
+
Everything important lives in committed repository files. Truth follows the branch, works with ordinary pull requests, and remains visible to every maintainer and coding agent.
|
|
164
136
|
|
|
165
|
-
|
|
137
|
+
### Local-first operation
|
|
166
138
|
|
|
167
|
-
Truthmark
|
|
168
|
-
|
|
169
|
-
Most AI tools can draft documentation. Truthmark keeps repository truth curated after the draft, after the next code change, and after the doc starts getting too broad.
|
|
170
|
-
|
|
171
|
-
It is useful when you need:
|
|
172
|
-
|
|
173
|
-
- less documentation drift
|
|
174
|
-
- better handoffs
|
|
175
|
-
- branch-specific product truth
|
|
176
|
-
- durable architecture and API documentation
|
|
177
|
-
- explicit ownership between docs and code
|
|
178
|
-
- safer agent write boundaries
|
|
179
|
-
- reviewable documentation instead of hidden memory
|
|
180
|
-
- agent guidance that still works from committed repo files
|
|
139
|
+
Truthmark needs no hosted service, daemon, database, vector store, or Model Context Protocol server. The repository carries its own documentation workflow.
|
|
181
140
|
|
|
182
141
|
## Where Truthmark fits
|
|
183
142
|
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
|
189
|
-
|
|
|
190
|
-
|
|
|
191
|
-
|
|
|
192
|
-
| Plan-first feature work | Spec workflow |
|
|
193
|
-
| Branch-scoped truth that travels with code | Truthmark |
|
|
194
|
-
| Validating behavior correctness | Tests and review |
|
|
195
|
-
| Reviewing AI-assisted documentation changes | Truthmark plus Git review |
|
|
196
|
-
|
|
197
|
-
Truthmark’s lane is narrow by design:
|
|
198
|
-
|
|
199
|
-
```text
|
|
200
|
-
make repository truth explicit
|
|
201
|
-
route it to code
|
|
202
|
-
install agent guidance around it
|
|
203
|
-
keep the result reviewable in Git
|
|
204
|
-
```
|
|
205
|
-
|
|
206
|
-
## Go deeper
|
|
207
|
-
|
|
208
|
-
The README is the storefront: fast context, quick start, and the core mental model.
|
|
143
|
+
| Need | Best fit |
|
|
144
|
+
| -------------------------------------------------- | -------------------------- |
|
|
145
|
+
| Better output from one agent session | Better prompt |
|
|
146
|
+
| Personal or session-level continuity | Memory tool |
|
|
147
|
+
| Plan-first feature work | Specification workflow |
|
|
148
|
+
| Branch-scoped documentation that travels with code | **Truthmark** |
|
|
149
|
+
| Behavior correctness | Tests and code review |
|
|
150
|
+
| Reviewable AI-assisted documentation | **Truthmark + Git review** |
|
|
209
151
|
|
|
210
|
-
|
|
152
|
+
Truthmark is built for maintainers and engineering teams that already use AI coding agents and want the repository to keep telling the truth as fast as the code changes.
|
|
211
153
|
|
|
212
|
-
|
|
154
|
+
## Supported hosts and command line
|
|
213
155
|
|
|
214
|
-
|
|
156
|
+
Supported agent hosts:
|
|
215
157
|
|
|
216
|
-
|
|
158
|
+
- Codex
|
|
159
|
+
- Claude Code
|
|
160
|
+
- GitHub Copilot
|
|
161
|
+
- OpenCode
|
|
162
|
+
- Antigravity
|
|
163
|
+
- Cursor
|
|
217
164
|
|
|
218
|
-
|
|
219
|
-
-
|
|
220
|
-
- route, authority, frontmatter, link, freshness, generated-surface, branch-scope, and coverage diagnostics
|
|
221
|
-
- branch-scoped truth docs and derived repository-intelligence artifacts
|
|
165
|
+
<details>
|
|
166
|
+
<summary>Command-line reference</summary>
|
|
222
167
|
|
|
223
|
-
|
|
168
|
+
| Command | Purpose |
|
|
169
|
+
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------- |
|
|
170
|
+
| `truthmark init` | Create or refresh configuration, routing, templates, and selected host workflows |
|
|
171
|
+
| `truthmark check [--base <ref>]` | Validate repository truth and optionally run branch-freshness diagnostics |
|
|
172
|
+
| `truthmark index --json` | Inspect derived repository and routing metadata |
|
|
173
|
+
| `truthmark impact --base <ref> --json` | Map changed files to docs, owners, and nearby tests |
|
|
174
|
+
| `truthmark workflow status --workflow <id> [--base <ref>] --json` | Inspect workflow applicability and targets |
|
|
175
|
+
| `truthmark validate ...` | Validate workflow reports and write leases |
|
|
176
|
+
| `truthmark uninstall --dry-run` / `truthmark uninstall --apply` | Preview or remove generated host surfaces while preserving authored truth |
|
|
224
177
|
|
|
225
|
-
-
|
|
226
|
-
- [Docs index](docs/README.md)
|
|
227
|
-
- [Architecture overview](docs/truthmark/engineering/architecture/overview.md)
|
|
228
|
-
- [API and CLI contracts](docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
|
229
|
-
- [Repository truth maintenance guide](docs/standards/maintaining-repository-truth.md)
|
|
178
|
+
Structured JSON output is available throughout the command-line interface for scripts and continuous integration.
|
|
230
179
|
|
|
231
|
-
|
|
180
|
+
</details>
|
|
232
181
|
|
|
233
|
-
##
|
|
182
|
+
## Learn more
|
|
234
183
|
|
|
235
|
-
Truthmark
|
|
184
|
+
- [Truthmark User Guide](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md)
|
|
185
|
+
- [Documentation index](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
|
|
186
|
+
- [Architecture overview](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
|
|
187
|
+
- [Configuration, routing, and command contracts](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
|
188
|
+
- [Contributing](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
|
|
236
189
|
|
|
237
|
-
|
|
190
|
+
**Install Truthmark, select your coding host, and turn one real behavior into documentation today.**
|
|
238
191
|
|
|
239
192
|
## License
|
|
240
193
|
|