truthmark 2.3.0 → 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.
Files changed (22) hide show
  1. package/README.md +119 -157
  2. package/dist/main.js +198 -44
  3. package/dist/main.js.map +1 -1
  4. package/docs/README.md +45 -33
  5. package/docs/assets/truthmark-workflow-mobile.svg +118 -0
  6. package/docs/assets/truthmark-workflow.svg +182 -0
  7. package/docs/readmes/README.ar.md +125 -151
  8. package/docs/readmes/README.de.md +127 -153
  9. package/docs/readmes/README.el.md +127 -153
  10. package/docs/readmes/README.es.md +125 -151
  11. package/docs/readmes/README.fr.md +125 -151
  12. package/docs/readmes/README.id.md +126 -152
  13. package/docs/readmes/README.it.md +125 -151
  14. package/docs/readmes/README.ja.md +126 -152
  15. package/docs/readmes/README.ko.md +127 -153
  16. package/docs/readmes/README.pl.md +125 -151
  17. package/docs/readmes/README.pt.md +126 -152
  18. package/docs/readmes/README.ru.md +124 -150
  19. package/docs/readmes/README.tr.md +125 -151
  20. package/docs/readmes/README.vi.md +126 -152
  21. package/docs/readmes/README.zh.md +128 -154
  22. package/package.json +3 -1
package/docs/README.md CHANGED
@@ -1,9 +1,9 @@
1
1
  ---
2
2
  status: active
3
3
  doc_type: index
4
- last_reviewed: 2026-07-30
4
+ last_reviewed: 2026-08-23
5
5
  source_of_truth:
6
- - docs/ai/repo-rules.md
6
+ - docs/repo/ai/repo-rules.md
7
7
  - ../.truthmark/config.yml
8
8
  ---
9
9
 
@@ -13,7 +13,14 @@ source_of_truth:
13
13
 
14
14
  `docs/` is Truthmark's repository documentation tree. It keeps repository-wide agent rules, reusable standards, current architecture, current lane-separated truth docs, and non-canonical research notes separate from onboarding copy.
15
15
 
16
- `AGENTS.md` is the agent entry point, but it delegates repository-wide rules to [docs/ai/repo-rules.md](ai/repo-rules.md). [README.md](../README.md) remains the human onboarding and product entry point. [docs/user-guide.md](user-guide.md) owns detailed human-facing command, workflow, and configuration guidance. `.truthmark/config.yml` defines the committed hierarchy contract.
16
+ The first thing to establish about any doc here is its **scope**:
17
+
18
+ - **repo-local** (`docs/repo/**`): policy for developing Truthmark itself. It is not a downstream scaffold, generated surface, or required artifact for repositories that install Truthmark. Nothing under `docs/repo/` ships, and `src/` never references it.
19
+ - **product surface** (everything else under `docs/`): documentation of the product Truthmark installs into other repositories. `docs/truthmark/**` is this repository dogfooding the same truth schema that `truthmark init` scaffolds downstream.
20
+
21
+ Do not cite a repo-local doc as evidence about the product's behavior, schema, or installed surfaces. Every doc under `docs/repo/` declares `scope: repo-local` in frontmatter, and `tests/doc-scope.test.ts` enforces the boundary.
22
+
23
+ `AGENTS.md` is the agent entry point, but it delegates repository-wide rules to [docs/repo/ai/repo-rules.md](repo/ai/repo-rules.md). [README.md](../README.md) remains the human onboarding and product entry point. [docs/user-guide.md](user-guide.md) owns detailed human-facing command, workflow, and configuration guidance. `.truthmark/config.yml` defines the committed hierarchy contract.
17
24
 
18
25
  ## Scope
19
26
 
@@ -21,42 +28,44 @@ This doc defines the current structure, navigation map, and maintenance expectat
21
28
 
22
29
  ## Authority Source
23
30
 
24
- Repository-wide conflict order and completion policy live in [docs/ai/repo-rules.md](ai/repo-rules.md). Use this index for navigation and document-class guidance; it does not restate the full authority hierarchy.
31
+ Repository-wide conflict order and completion policy live in [docs/repo/ai/repo-rules.md](repo/ai/repo-rules.md). Use this index for navigation and document-class guidance; it does not restate the full authority hierarchy.
25
32
 
26
33
  [README.md](../README.md) may help with onboarding and positioning, but it must not override current-state docs or repository-wide agent rules.
27
34
 
28
- ## Audience Split
35
+ ## Scope Split
29
36
 
30
- ### Agent-centric docs
37
+ ### Repo-local docs (`scope: repo-local`, ships to nobody)
38
+
39
+ - `docs/repo/ai/` for repository rules and agent onboarding
40
+ - `docs/repo/standards/` for reusable constraints and completion rules
41
+ - `docs/repo/architecture/` for repository-specific architecture guardrails
42
+ - `docs/repo/research/` for non-canonical research evidence, evaluations, and comparisons
43
+
44
+ ### Product-surface docs
31
45
 
32
- - `docs/ai/` for repository rules and agent onboarding
33
- - `docs/truthmark/routes/` for routing metadata
34
- - `docs/standards/` for reusable constraints and completion rules
35
46
  - `docs/truthmark/product/` for product capability promises, boundaries, and acceptance criteria
36
47
  - `docs/truthmark/engineering/` for current implementation behavior, architecture, contracts, workflows, and operations
37
- - `docs/architecture/` for repository-specific architecture guardrails
38
- - `docs/research/` for non-canonical research evidence, evaluations, and comparisons
39
- - `docs/truthmark/templates/` for editable scaffold templates used to create new docs
40
48
  - `docs/truthmark/engineering/contracts/` for stable contracts the CLI exposes
41
-
42
- ### Human-centric docs
43
-
49
+ - `docs/truthmark/routes/` for routing metadata
50
+ - `docs/truthmark/templates/` for editable scaffold templates used to create new docs
44
51
  - [README.md](../README.md) for onboarding and positioning
45
52
  - [docs/user-guide.md](user-guide.md) for detailed usage, command, workflow, configuration, routing, Portal, and example guidance
46
53
 
47
54
  ## Directory Map
48
55
 
49
- | Path | Type | Primary audience | Purpose |
50
- | ----------------------------- | ----------------- | ---------------- | ------------------------------------------------------------------------------------- |
51
- | `docs/ai/` | agent rules | agent | Repository-wide rules and fast onboarding |
52
- | `docs/truthmark/routes/` | routing | both | Truth-routing metadata such as `areas.md` and `areas/**/*.md` |
53
- | `docs/standards/` | standard | agent | Reusable constraints, verification rules, completion gates |
54
- | `docs/truthmark/product/` | product truth | agent | Product capability promises, boundaries, decisions, and acceptance criteria |
55
- | `docs/truthmark/engineering/` | engineering truth | agent | Current implementation behavior for init, check, contracts, workflows, and operations |
56
- | `docs/architecture/` | architecture | agent | Repository-specific architecture guardrails |
57
- | `docs/research/` | research | human | Non-canonical research evidence, evaluations, and comparisons |
58
- | `docs/truthmark/templates/` | template | both | Editable templates for scaffolded docs; templates are not Truth Sync targets |
59
- | `docs/user-guide.md` | guide | human | Detailed usage guide kept out of the root README so onboarding stays concise |
56
+ | Path | Type | Scope | Purpose |
57
+ | ----------------------------- | ----------------- | --------------- | ------------------------------------------------------------------------------------- |
58
+ | `docs/repo/ai/` | agent rules | repo-local | Repository-wide rules and fast onboarding for developing Truthmark itself |
59
+ | `docs/repo/standards/` | standard | repo-local | Reusable constraints, verification rules, completion gates |
60
+ | `docs/repo/architecture/` | architecture | repo-local | Repository-specific architecture guardrails |
61
+ | `docs/repo/research/` | research | repo-local | Non-canonical research evidence, evaluations, and comparisons |
62
+ | `docs/truthmark/product/` | product truth | product surface | Product capability promises, boundaries, decisions, and acceptance criteria |
63
+ | `docs/truthmark/engineering/` | engineering truth | product surface | Current implementation behavior for init, check, contracts, workflows, and operations |
64
+ | `docs/truthmark/routes/` | routing | product surface | Truth-routing metadata such as `areas.md` and `areas/**/*.md` |
65
+ | `docs/truthmark/templates/` | template | product surface | Editable templates for scaffolded docs; templates are not Truth Sync targets |
66
+ | `docs/user-guide.md` | guide | product surface | Detailed usage guide kept out of the root README so onboarding stays concise |
67
+
68
+ `docs/truthmark/**` carries `truth_kind` (the schema `truthmark init` scaffolds downstream); `docs/repo/**` carries `doc_type` and never `truth_kind`.
60
69
 
61
70
  ## Frontmatter Policy
62
71
 
@@ -67,12 +76,14 @@ Canonical docs should include frontmatter and keep these fields current:
67
76
  - `last_reviewed`
68
77
  - `source_of_truth`
69
78
 
79
+ Every doc under `docs/repo/` must also declare `scope: repo-local`.
80
+
70
81
  ## Update Rules
71
82
 
72
- - When repository-wide agent policy changes, update [docs/ai/repo-rules.md](ai/repo-rules.md).
83
+ - When repository-wide agent policy changes, update [docs/repo/ai/repo-rules.md](repo/ai/repo-rules.md).
73
84
  - When code-to-doc routing changes, update [docs/truthmark/routes/areas.md](truthmark/routes/areas.md) in the same change.
74
- - When package versions or release/version policy change, apply [docs/standards/versioning.md](standards/versioning.md) before accepting the version.
75
- - When PR or release source text is needed, write a `changes/` note using [docs/standards/change-notes.md](standards/change-notes.md).
85
+ - When package versions or release/version policy change, apply [docs/repo/standards/versioning.md](repo/standards/versioning.md) before accepting the version.
86
+ - When PR or release source text is needed, write a `changes/` note using [docs/repo/standards/change-notes.md](repo/standards/change-notes.md).
76
87
  - When `truthmark init` or scaffolded files change, update the relevant truth or architecture doc, not only [README.md](../README.md).
77
88
  - When `truthmark check` changes what it validates or how it reports diagnostics, update both the current truth doc and the contract doc.
78
89
  - When major product, onboarding, install, command, positioning, or workflow behavior changes, review the root [README.md](../README.md) and update it if the human entry point would otherwise be stale.
@@ -91,14 +102,14 @@ Canonical docs should include frontmatter and keep these fields current:
91
102
  1. [README.md](../README.md)
92
103
  2. [docs/user-guide.md](user-guide.md), when command or workflow detail is needed
93
104
  3. [.truthmark/config.yml](../.truthmark/config.yml)
94
- 4. [docs/ai/repo-rules.md](ai/repo-rules.md)
105
+ 4. [docs/repo/ai/repo-rules.md](repo/ai/repo-rules.md)
95
106
  5. [docs/truthmark/engineering/architecture/overview.md](truthmark/engineering/architecture/overview.md)
96
107
  6. the relevant product, engineering, or standard doc for the area being changed
97
108
 
98
109
  ### For agents
99
110
 
100
- 1. [docs/ai/repo-rules.md](ai/repo-rules.md)
101
- 2. [docs/ai/agent-onboarding.md](ai/agent-onboarding.md), when routing is unclear or cross-area
111
+ 1. [docs/repo/ai/repo-rules.md](repo/ai/repo-rules.md)
112
+ 2. [docs/repo/ai/agent-onboarding.md](repo/ai/agent-onboarding.md), when routing is unclear or cross-area
102
113
  3. [docs/truthmark/routes/areas.md](truthmark/routes/areas.md), when mapping code to canonical truth
103
114
  4. [docs/truthmark/engineering/architecture/overview.md](truthmark/engineering/architecture/overview.md), when changing module boundaries
104
115
  5. the relevant standard, product truth, and engineering truth docs for the task
@@ -111,8 +122,9 @@ The canonical tree should stay small, explicit, and current. Git history provide
111
122
 
112
123
  ## Product Decisions
113
124
 
114
- - Decision (2026-05-15): The docs index owns navigation and document-class guidance for the canonical tree, while [docs/ai/repo-rules.md](ai/repo-rules.md) owns repository-wide authority order and completion policy.
125
+ - Decision (2026-05-15): The docs index owns navigation and document-class guidance for the canonical tree, while [docs/repo/ai/repo-rules.md](repo/ai/repo-rules.md) owns repository-wide authority order and completion policy.
115
126
  - Decision (2026-06-20): The root README is the concise human storefront. Detailed human-facing command, workflow, configuration, routing, Portal, and example material belongs in [docs/user-guide.md](user-guide.md).
127
+ - Decision (2026-08-23): Repo-local policy lives under `docs/repo/` so the repo-local versus product-surface boundary is visible in every path, not only in prose. Agents reason from paths constantly and read prose once, so the boundary is encoded in the directory name, in `scope: repo-local` frontmatter, and in `tests/doc-scope.test.ts`. The enforcing test is repo-local because `truthmark check` runs in downstream repositories, which do not have this boundary.
116
128
 
117
129
  ## Rationale
118
130
 
package/docs/assets/truthmark-workflow-mobile.svg ADDED
@@ -0,0 +1,118 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="720" height="1600" viewBox="0 0 720 1600" role="img" aria-labelledby="title desc">
2
+ <title id="title">How Truthmark works</title>
3
+ <desc id="desc">Truthmark creates documentation from code and tests, keeps documentation current as code changes, and turns approved truth documents back into working code. Every path ends in one reviewable Git diff.</desc>
4
+ <defs>
5
+ <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#090D1A"/><stop offset="0.55" stop-color="#10162B"/><stop offset="1" stop-color="#0B1220"/></linearGradient>
6
+ <radialGradient id="glow" cx="0.2" cy="0.15" r="0.7"><stop offset="0" stop-color="#8B5CF6" stop-opacity="0.24"/><stop offset="1" stop-color="#8B5CF6" stop-opacity="0"/></radialGradient>
7
+ <linearGradient id="purple" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#A78BFA"/><stop offset="1" stop-color="#7C3AED"/></linearGradient>
8
+ <linearGradient id="cyan" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#67E8F9"/><stop offset="1" stop-color="#0891B2"/></linearGradient>
9
+ <linearGradient id="amber" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#FCD34D"/><stop offset="1" stop-color="#D97706"/></linearGradient>
10
+ <linearGradient id="review" x1="0" y1="0" x2="1" y2="0"><stop offset="0" stop-color="#16A34A"/><stop offset="0.55" stop-color="#22C55E"/><stop offset="1" stop-color="#0D9488"/></linearGradient>
11
+ <filter id="shadow" x="-20%" y="-20%" width="140%" height="160%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#000814" flood-opacity="0.42"/></filter>
12
+ <pattern id="grid" width="32" height="32" patternUnits="userSpaceOnUse"><path d="M32 0H0V32" fill="none" stroke="#94A3B8" stroke-opacity="0.045"/></pattern>
13
+ <marker id="purpleArrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10Z" fill="#A78BFA"/></marker>
14
+ <marker id="cyanArrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10Z" fill="#67E8F9"/></marker>
15
+ <marker id="amberArrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10Z" fill="#FCD34D"/></marker>
16
+ <style>
17
+ .ui { font-family: Inter, ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
18
+ .brand { font-size: 16px; font-weight: 780; letter-spacing: 2.5px; fill: #C4B5FD; }
19
+ .headline { font-size: 42px; font-weight: 790; letter-spacing: -0.8px; fill: #F8FAFC; }
20
+ .subhead { font-size: 20px; font-weight: 460; fill: #94A3B8; }
21
+ .eyebrow { font-size: 17px; font-weight: 780; letter-spacing: 2px; }
22
+ .cardTitle { font-size: 29px; font-weight: 770; fill: #F8FAFC; }
23
+ .label { font-size: 22px; font-weight: 670; fill: #E2E8F0; }
24
+ .muted { font-size: 17px; font-weight: 490; fill: #94A3B8; }
25
+ .pill { font-size: 21px; font-weight: 770; fill: #FFFFFF; }
26
+ .reviewTitle { font-size: 26px; font-weight: 830; fill: #FFFFFF; }
27
+ .reviewSub { font-size: 17px; font-weight: 560; fill: #DCFCE7; }
28
+ </style>
29
+ </defs>
30
+
31
+ <rect width="720" height="1600" rx="30" fill="url(#bg)"/>
32
+ <rect width="720" height="1600" rx="30" fill="url(#grid)"/>
33
+ <rect width="720" height="1600" rx="30" fill="url(#glow)"/>
34
+
35
+ <g class="ui">
36
+ <g transform="translate(48 42)">
37
+ <rect width="158" height="36" rx="18" fill="#8B5CF6" fill-opacity="0.16" stroke="#A78BFA" stroke-opacity="0.45"/>
38
+ <circle cx="20" cy="18" r="5" fill="#A78BFA"/>
39
+ <text x="37" y="23" class="brand">TRUTHMARK</text>
40
+ <text x="0" y="82" class="headline">Create. Sync. Realize.</text>
41
+ <text x="0" y="115" class="subhead">Documentation that moves with your code.</text>
42
+ </g>
43
+
44
+ <!-- Create -->
45
+ <g transform="translate(48 184)" filter="url(#shadow)">
46
+ <rect width="624" height="350" rx="26" fill="#141A2F" stroke="#8B5CF6" stroke-opacity="0.52" stroke-width="1.5"/>
47
+ <rect width="624" height="7" rx="3.5" fill="url(#purple)"/>
48
+ <g transform="translate(27 27)">
49
+ <rect width="58" height="58" rx="17" fill="#8B5CF6" fill-opacity="0.15" stroke="#A78BFA" stroke-opacity="0.45"/>
50
+ <path d="M19 21L11 29L19 37M39 21L47 29L39 37M34 15L24 43" fill="none" stroke="#C4B5FD" stroke-width="3.2" stroke-linecap="round" stroke-linejoin="round"/>
51
+ </g>
52
+ <text x="105" y="49" class="eyebrow" fill="#A78BFA">01 · CREATE</text>
53
+ <text x="105" y="79" class="cardTitle">Create from code</text>
54
+ <rect x="28" y="106" width="568" height="62" rx="16" fill="#0C1224" stroke="#334155"/>
55
+ <text x="52" y="133" class="label">Code + tests</text><text x="52" y="156" class="muted">Evidence from working software</text>
56
+ <path d="M312 176V197" fill="none" stroke="#A78BFA" stroke-width="2.5" marker-end="url(#purpleArrow)"/>
57
+ <rect x="186" y="202" width="252" height="58" rx="29" fill="url(#purple)"/>
58
+ <text x="312" y="238" class="pill" text-anchor="middle">Truth Document</text>
59
+ <path d="M312 268V289" fill="none" stroke="#A78BFA" stroke-width="2.5" marker-end="url(#purpleArrow)"/>
60
+ <rect x="28" y="294" width="568" height="42" rx="14" fill="#21153E" stroke="#8B5CF6" stroke-opacity="0.55"/>
61
+ <text x="52" y="322" class="label">New product + engineering docs</text>
62
+ </g>
63
+
64
+ <!-- Sync -->
65
+ <g transform="translate(48 558)" filter="url(#shadow)">
66
+ <rect width="624" height="350" rx="26" fill="#141A2F" stroke="#22D3EE" stroke-opacity="0.52" stroke-width="1.5"/>
67
+ <rect width="624" height="7" rx="3.5" fill="url(#cyan)"/>
68
+ <g transform="translate(27 27)">
69
+ <rect width="58" height="58" rx="17" fill="#06B6D4" fill-opacity="0.14" stroke="#67E8F9" stroke-opacity="0.45"/>
70
+ <path d="M17 23A15 15 0 0 1 43 20L47 24M42 13L43 20L36 21M42 36A15 15 0 0 1 16 39L12 35M17 46L16 39L23 38" fill="none" stroke="#A5F3FC" stroke-width="3.1" stroke-linecap="round" stroke-linejoin="round"/>
71
+ </g>
72
+ <text x="105" y="49" class="eyebrow" fill="#67E8F9">02 · SYNC</text>
73
+ <text x="105" y="79" class="cardTitle">Stay current</text>
74
+ <rect x="28" y="106" width="568" height="62" rx="16" fill="#0C1224" stroke="#334155"/>
75
+ <text x="52" y="133" class="label">Agent changes code</text><text x="52" y="156" class="muted">Tests prove the behavior</text>
76
+ <path d="M312 176V197" fill="none" stroke="#67E8F9" stroke-width="2.5" marker-end="url(#cyanArrow)"/>
77
+ <rect x="204" y="202" width="216" height="58" rx="29" fill="url(#cyan)"/>
78
+ <text x="312" y="238" class="pill" text-anchor="middle">Truth Sync</text>
79
+ <path d="M312 268V289" fill="none" stroke="#67E8F9" stroke-width="2.5" marker-end="url(#cyanArrow)"/>
80
+ <rect x="28" y="294" width="568" height="42" rx="14" fill="#0B2C36" stroke="#22D3EE" stroke-opacity="0.55"/>
81
+ <text x="52" y="322" class="label">Docs stay current before handoff</text>
82
+ </g>
83
+
84
+ <!-- Realize -->
85
+ <g transform="translate(48 932)" filter="url(#shadow)">
86
+ <rect width="624" height="350" rx="26" fill="#141A2F" stroke="#F59E0B" stroke-opacity="0.52" stroke-width="1.5"/>
87
+ <rect width="624" height="7" rx="3.5" fill="url(#amber)"/>
88
+ <g transform="translate(27 27)">
89
+ <rect width="58" height="58" rx="17" fill="#F59E0B" fill-opacity="0.13" stroke="#FCD34D" stroke-opacity="0.45"/>
90
+ <path d="M31 12L16 32H28L25 47L42 25H30Z" fill="#FDE68A" stroke="#FCD34D" stroke-width="1.4" stroke-linejoin="round"/>
91
+ </g>
92
+ <text x="105" y="49" class="eyebrow" fill="#FCD34D">03 · REALIZE</text>
93
+ <text x="105" y="79" class="cardTitle">Build from truth</text>
94
+ <rect x="28" y="106" width="568" height="62" rx="16" fill="#0C1224" stroke="#334155"/>
95
+ <text x="52" y="133" class="label">Approved truth docs</text><text x="52" y="156" class="muted">The repository contract</text>
96
+ <path d="M312 176V197" fill="none" stroke="#FCD34D" stroke-width="2.5" marker-end="url(#amberArrow)"/>
97
+ <rect x="193" y="202" width="238" height="58" rx="29" fill="url(#amber)"/>
98
+ <text x="312" y="238" class="pill" text-anchor="middle">Truth Realize</text>
99
+ <path d="M312 268V289" fill="none" stroke="#FCD34D" stroke-width="2.5" marker-end="url(#amberArrow)"/>
100
+ <rect x="28" y="294" width="568" height="42" rx="14" fill="#33230A" stroke="#F59E0B" stroke-opacity="0.55"/>
101
+ <text x="52" y="322" class="label">Working code implemented from truth</text>
102
+ </g>
103
+
104
+ <!-- Review -->
105
+ <path d="M360 1282V1329" stroke="#22C55E" stroke-width="3"/>
106
+ <g transform="translate(48 1329)" filter="url(#shadow)">
107
+ <rect width="624" height="190" rx="28" fill="url(#review)"/>
108
+ <g transform="translate(34 38)" fill="none" stroke="#FFFFFF" stroke-width="3.2" stroke-linecap="round" stroke-linejoin="round">
109
+ <circle cx="10" cy="8" r="6"/><circle cx="10" cy="48" r="6"/><circle cx="52" cy="8" r="6"/><path d="M10 14V42M16 8H34Q46 8 46 22V34Q46 48 30 48H16"/>
110
+ </g>
111
+ <text x="113" y="59" class="reviewTitle">ONE REVIEWABLE GIT DIFF</text>
112
+ <text x="34" y="111" class="reviewSub">Code and documentation move together</text>
113
+ <text x="34" y="136" class="reviewSub">with the branch.</text>
114
+ <rect x="500" y="111" width="86" height="45" rx="22.5" fill="#FFFFFF" fill-opacity="0.16" stroke="#FFFFFF" stroke-opacity="0.35"/>
115
+ <path d="M523 133H562M553 124L562 133L553 142" fill="none" stroke="#FFFFFF" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
116
+ </g>
117
+ </g>
118
+ </svg>
package/docs/assets/truthmark-workflow.svg ADDED
@@ -0,0 +1,182 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="1440" height="820" viewBox="0 0 1440 820" role="img" aria-labelledby="title desc">
2
+ <title id="title">How Truthmark works</title>
3
+ <desc id="desc">Truthmark creates documentation from code and tests, keeps documentation current as code changes, and turns approved truth documents back into working code. Every path ends in one reviewable Git diff.</desc>
4
+ <defs>
5
+ <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
6
+ <stop offset="0" stop-color="#090D1A"/>
7
+ <stop offset="0.55" stop-color="#10162B"/>
8
+ <stop offset="1" stop-color="#0B1220"/>
9
+ </linearGradient>
10
+ <radialGradient id="glowPurple" cx="0.2" cy="0.25" r="0.55">
11
+ <stop offset="0" stop-color="#8B5CF6" stop-opacity="0.22"/>
12
+ <stop offset="1" stop-color="#8B5CF6" stop-opacity="0"/>
13
+ </radialGradient>
14
+ <radialGradient id="glowCyan" cx="0.75" cy="0.3" r="0.55">
15
+ <stop offset="0" stop-color="#22D3EE" stop-opacity="0.16"/>
16
+ <stop offset="1" stop-color="#22D3EE" stop-opacity="0"/>
17
+ </radialGradient>
18
+ <linearGradient id="purple" x1="0" y1="0" x2="1" y2="1">
19
+ <stop offset="0" stop-color="#A78BFA"/>
20
+ <stop offset="1" stop-color="#7C3AED"/>
21
+ </linearGradient>
22
+ <linearGradient id="cyan" x1="0" y1="0" x2="1" y2="1">
23
+ <stop offset="0" stop-color="#67E8F9"/>
24
+ <stop offset="1" stop-color="#0891B2"/>
25
+ </linearGradient>
26
+ <linearGradient id="amber" x1="0" y1="0" x2="1" y2="1">
27
+ <stop offset="0" stop-color="#FCD34D"/>
28
+ <stop offset="1" stop-color="#D97706"/>
29
+ </linearGradient>
30
+ <linearGradient id="review" x1="0" y1="0" x2="1" y2="0">
31
+ <stop offset="0" stop-color="#16A34A"/>
32
+ <stop offset="0.5" stop-color="#22C55E"/>
33
+ <stop offset="1" stop-color="#0D9488"/>
34
+ </linearGradient>
35
+ <filter id="shadow" x="-20%" y="-20%" width="140%" height="160%">
36
+ <feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#000814" flood-opacity="0.45"/>
37
+ </filter>
38
+ <filter id="softGlow" x="-40%" y="-40%" width="180%" height="180%">
39
+ <feGaussianBlur stdDeviation="7" result="blur"/>
40
+ <feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>
41
+ </filter>
42
+ <pattern id="grid" width="36" height="36" patternUnits="userSpaceOnUse">
43
+ <path d="M36 0H0V36" fill="none" stroke="#94A3B8" stroke-opacity="0.045" stroke-width="1"/>
44
+ </pattern>
45
+ <marker id="arrowPurple" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0 0L10 5L0 10Z" fill="#A78BFA"/></marker>
46
+ <marker id="arrowCyan" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0 0L10 5L0 10Z" fill="#67E8F9"/></marker>
47
+ <marker id="arrowAmber" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0 0L10 5L0 10Z" fill="#FCD34D"/></marker>
48
+ <style>
49
+ .ui { font-family: Inter, ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
50
+ .eyebrow { font-size: 15px; font-weight: 750; letter-spacing: 2.6px; }
51
+ .headline { font-size: 42px; font-weight: 780; letter-spacing: -1px; fill: #F8FAFC; }
52
+ .subhead { font-size: 19px; font-weight: 450; fill: #94A3B8; }
53
+ .cardTitle { font-size: 30px; font-weight: 760; letter-spacing: -0.45px; fill: #F8FAFC; }
54
+ .label { font-size: 19px; font-weight: 620; fill: #E2E8F0; }
55
+ .muted { font-size: 16px; font-weight: 480; fill: #94A3B8; }
56
+ .pill { font-size: 18px; font-weight: 760; fill: #FFFFFF; }
57
+ .reviewTitle { font-size: 25px; font-weight: 820; letter-spacing: 0.2px; fill: #FFFFFF; }
58
+ .reviewSub { font-size: 17px; font-weight: 560; fill: #DCFCE7; }
59
+ </style>
60
+ </defs>
61
+
62
+ <rect width="1440" height="820" rx="28" fill="url(#bg)"/>
63
+ <rect width="1440" height="820" rx="28" fill="url(#grid)"/>
64
+ <rect width="1440" height="820" rx="28" fill="url(#glowPurple)"/>
65
+ <rect width="1440" height="820" rx="28" fill="url(#glowCyan)"/>
66
+
67
+ <g class="ui">
68
+ <g transform="translate(62 48)">
69
+ <rect x="0" y="0" width="154" height="34" rx="17" fill="#8B5CF6" fill-opacity="0.16" stroke="#A78BFA" stroke-opacity="0.45"/>
70
+ <circle cx="20" cy="17" r="5" fill="#A78BFA" filter="url(#softGlow)"/>
71
+ <text x="36" y="22" class="eyebrow" fill="#C4B5FD">TRUTHMARK</text>
72
+ <text x="0" y="78" class="headline">Create docs. Keep them true. Build from truth.</text>
73
+ <text x="0" y="112" class="subhead">A complete documentation lifecycle inside your repository.</text>
74
+ </g>
75
+
76
+ <!-- Create card -->
77
+ <g transform="translate(60 195)" filter="url(#shadow)">
78
+ <rect width="400" height="420" rx="26" fill="#141A2F" stroke="#8B5CF6" stroke-opacity="0.5" stroke-width="1.5"/>
79
+ <rect width="400" height="7" rx="3.5" fill="url(#purple)"/>
80
+ <g transform="translate(30 31)">
81
+ <rect width="62" height="62" rx="18" fill="#8B5CF6" fill-opacity="0.15" stroke="#A78BFA" stroke-opacity="0.45"/>
82
+ <path d="M20 23L12 31L20 39M42 23L50 31L42 39M36 16L26 46" fill="none" stroke="#C4B5FD" stroke-width="3.4" stroke-linecap="round" stroke-linejoin="round"/>
83
+ </g>
84
+ <text x="112" y="55" class="eyebrow" fill="#A78BFA">01 · CREATE</text>
85
+ <text x="112" y="84" class="cardTitle">Create from code</text>
86
+
87
+ <rect x="30" y="126" width="340" height="63" rx="16" fill="#0C1224" stroke="#334155"/>
88
+ <text x="54" y="153" class="label">Code + tests</text>
89
+ <text x="54" y="176" class="muted">Evidence from working software</text>
90
+
91
+ <path d="M200 197V225" fill="none" stroke="#A78BFA" stroke-width="2.5" marker-end="url(#arrowPurple)"/>
92
+ <rect x="84" y="229" width="232" height="58" rx="29" fill="url(#purple)"/>
93
+ <text x="200" y="265" class="pill" text-anchor="middle">Truth Document</text>
94
+ <path d="M200 296V324" fill="none" stroke="#A78BFA" stroke-width="2.5" marker-end="url(#arrowPurple)"/>
95
+
96
+ <rect x="30" y="328" width="340" height="63" rx="16" fill="#21153E" stroke="#8B5CF6" stroke-opacity="0.55"/>
97
+ <g transform="translate(49 344)" fill="none" stroke="#C4B5FD" stroke-width="2.2">
98
+ <rect x="6" y="0" width="24" height="29" rx="3"/><path d="M11 8H25M11 14H25M11 20H21"/>
99
+ <rect x="0" y="6" width="24" height="29" rx="3" opacity="0.6"/>
100
+ </g>
101
+ <text x="101" y="355" class="label">New truth docs</text>
102
+ <text x="101" y="378" class="muted">Product + engineering</text>
103
+ </g>
104
+
105
+ <!-- Sync card -->
106
+ <g transform="translate(520 195)" filter="url(#shadow)">
107
+ <rect width="400" height="420" rx="26" fill="#141A2F" stroke="#22D3EE" stroke-opacity="0.5" stroke-width="1.5"/>
108
+ <rect width="400" height="7" rx="3.5" fill="url(#cyan)"/>
109
+ <g transform="translate(30 31)">
110
+ <rect width="62" height="62" rx="18" fill="#06B6D4" fill-opacity="0.14" stroke="#67E8F9" stroke-opacity="0.45"/>
111
+ <path d="M18 24A16 16 0 0 1 45 21L49 25M44 14L45 21L38 22M44 38A16 16 0 0 1 17 41L13 37M18 48L17 41L24 40" fill="none" stroke="#A5F3FC" stroke-width="3.2" stroke-linecap="round" stroke-linejoin="round"/>
112
+ </g>
113
+ <text x="112" y="55" class="eyebrow" fill="#67E8F9">02 · SYNC</text>
114
+ <text x="112" y="84" class="cardTitle">Stay current</text>
115
+
116
+ <rect x="30" y="126" width="340" height="63" rx="16" fill="#0C1224" stroke="#334155"/>
117
+ <text x="54" y="153" class="label">Agent changes code</text>
118
+ <text x="54" y="176" class="muted">Tests prove the behavior</text>
119
+
120
+ <path d="M200 197V225" fill="none" stroke="#67E8F9" stroke-width="2.5" marker-end="url(#arrowCyan)"/>
121
+ <rect x="101" y="229" width="198" height="58" rx="29" fill="url(#cyan)"/>
122
+ <text x="200" y="265" class="pill" text-anchor="middle">Truth Sync</text>
123
+ <path d="M200 296V324" fill="none" stroke="#67E8F9" stroke-width="2.5" marker-end="url(#arrowCyan)"/>
124
+
125
+ <rect x="30" y="328" width="340" height="63" rx="16" fill="#0B2C36" stroke="#22D3EE" stroke-opacity="0.55"/>
126
+ <g transform="translate(49 344)" fill="none" stroke="#A5F3FC" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round">
127
+ <path d="M2 17L11 26L30 5"/>
128
+ <rect x="0" y="0" width="35" height="35" rx="8" opacity="0.5"/>
129
+ </g>
130
+ <text x="101" y="355" class="label">Docs stay current</text>
131
+ <text x="101" y="378" class="muted">Before the agent hands off</text>
132
+ </g>
133
+
134
+ <!-- Realize card -->
135
+ <g transform="translate(980 195)" filter="url(#shadow)">
136
+ <rect width="400" height="420" rx="26" fill="#141A2F" stroke="#F59E0B" stroke-opacity="0.52" stroke-width="1.5"/>
137
+ <rect width="400" height="7" rx="3.5" fill="url(#amber)"/>
138
+ <g transform="translate(30 31)">
139
+ <rect width="62" height="62" rx="18" fill="#F59E0B" fill-opacity="0.13" stroke="#FCD34D" stroke-opacity="0.45"/>
140
+ <path d="M34 13L18 34H31L27 50L45 27H32Z" fill="#FDE68A" stroke="#FCD34D" stroke-width="1.5" stroke-linejoin="round"/>
141
+ </g>
142
+ <text x="112" y="55" class="eyebrow" fill="#FCD34D">03 · REALIZE</text>
143
+ <text x="112" y="84" class="cardTitle">Build from truth</text>
144
+
145
+ <rect x="30" y="126" width="340" height="63" rx="16" fill="#0C1224" stroke="#334155"/>
146
+ <text x="54" y="153" class="label">Approved truth docs</text>
147
+ <text x="54" y="176" class="muted">The repository contract</text>
148
+
149
+ <path d="M200 197V225" fill="none" stroke="#FCD34D" stroke-width="2.5" marker-end="url(#arrowAmber)"/>
150
+ <rect x="91" y="229" width="218" height="58" rx="29" fill="url(#amber)"/>
151
+ <text x="200" y="265" class="pill" text-anchor="middle">Truth Realize</text>
152
+ <path d="M200 296V324" fill="none" stroke="#FCD34D" stroke-width="2.5" marker-end="url(#arrowAmber)"/>
153
+
154
+ <rect x="30" y="328" width="340" height="63" rx="16" fill="#33230A" stroke="#F59E0B" stroke-opacity="0.55"/>
155
+ <g transform="translate(49 344)" fill="none" stroke="#FDE68A" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
156
+ <rect x="0" y="0" width="38" height="35" rx="7"/><path d="M0 9H38M8 21L13 26L8 31M19 29H30"/>
157
+ </g>
158
+ <text x="101" y="355" class="label">Working code</text>
159
+ <text x="101" y="378" class="muted">Implemented from truth</text>
160
+ </g>
161
+
162
+ <!-- Merge lines -->
163
+ <path d="M260 615V649Q260 666 278 666H630" fill="none" stroke="#8B5CF6" stroke-opacity="0.65" stroke-width="2.3"/>
164
+ <path d="M720 615V666" fill="none" stroke="#22D3EE" stroke-opacity="0.7" stroke-width="2.3"/>
165
+ <path d="M1180 615V649Q1180 666 1162 666H810" fill="none" stroke="#F59E0B" stroke-opacity="0.65" stroke-width="2.3"/>
166
+
167
+ <!-- Git review bar -->
168
+ <g transform="translate(236 666)" filter="url(#shadow)">
169
+ <rect width="968" height="108" rx="28" fill="url(#review)"/>
170
+ <g transform="translate(35 28)" fill="none" stroke="#FFFFFF" stroke-width="3" stroke-linecap="round" stroke-linejoin="round">
171
+ <circle cx="10" cy="8" r="6"/><circle cx="10" cy="44" r="6"/><circle cx="49" cy="8" r="6"/>
172
+ <path d="M10 14V38M16 8H29Q43 8 43 22V30Q43 44 29 44H16"/>
173
+ </g>
174
+ <text x="111" y="48" class="reviewTitle">ONE REVIEWABLE GIT DIFF</text>
175
+ <text x="111" y="76" class="reviewSub">Code and documentation move together with the branch.</text>
176
+ <g transform="translate(815 29)">
177
+ <rect width="114" height="50" rx="25" fill="#FFFFFF" fill-opacity="0.16" stroke="#FFFFFF" stroke-opacity="0.35"/>
178
+ <path d="M28 25H78M69 16L78 25L69 34" fill="none" stroke="#FFFFFF" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
179
+ </g>
180
+ </g>
181
+ </g>
182
+ </svg>