truthmark 2.2.5 → 2.2.6

package/README.md

@@ -2,6 +2,13 @@
 
 **Your agents write code. Truthmark maintains human-facing, Git-reviewable documentation.**
 
+[![npm version](https://img.shields.io/npm/v/truthmark?color=cb3837&label=npm)](https://www.npmjs.com/package/truthmark)
+[![CI](https://github.com/merlinhu1/truthmark/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/merlinhu1/truthmark/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js >=24](https://img.shields.io/badge/node-%3E%3D24-339933?logo=node.js&logoColor=white)](package.json)
+
+[Website](https://merlinhu1.github.io/truthmark/) | [GitHub](https://github.com/merlinhu1/truthmark) | [User Guide](docs/user-guide.md)
+
 [🇺🇸 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)
 
 ![Truthmark banner](docs/assets/truthmark-banner.png)
@@ -59,10 +66,12 @@ AI coding agents are incredible at writing code fast. But this speed creates a d
 
 ## 🎯 The Solution: Truthmark
 
-**Truthmark** installs a Git-native workflow layer into your repository. It fixes the part of AI development that usually breaks: helping the documentation stay aligned with the code.
+**Truthmark** installs a Git-native workflow layer into your repository. It fixes the part of AI development that usually breaks: keeping documentation aligned with code after the first draft.
 
 Instead of hoping humans and AI agents remember to update docs, Truthmark makes documentation a systematic, reviewable habit right inside your repo.
 
+Truthmark is not a one-shot docs generator. It is an ongoing truth-doc curation loop that keeps human-facing docs small, owned, evidence-backed, and reviewable as agents keep changing code.
+
 ### ✨ Why Truthmark is Unique
 
 Truthmark isn't just another documentation tool. It is deeply integrated into the AI workflow:
@@ -70,6 +79,7 @@ Truthmark isn't just another documentation tool. It is deeply integrated into th
 * **🚫 Zero Vendor Lock-in:** No hosted services, no hidden databases, no extra servers to operate.
 * **🌳 100% Git-Native:** Everything lives in your repository. The truth moves with your branch.
 * **🤝 Human-owned, agent-followed contract:** Maintainers own the repo contract; agents follow the installed instructions while coding.
+* **🧭 Ongoing truth curation:** Broad or messy docs are routed toward Structure instead of becoming giant catch-all files.
 * **✅ Trust Through Verification:** AI work becomes easier to trust because behavior-changing work includes a human-reviewable truth-doc decision or diff.
 
 ## 🔄 How It Works
@@ -122,6 +132,7 @@ Truth Structure is not a day-to-day command; it repairs routing or ownership onl
 | Human CLI | Gives maintainers setup, refresh, validation, and inspection commands. |
 | Installed agent guidance | Tells coding agents when to document, test, sync truth, audit, or stop for review. |
 | Explicit routing | Maps code areas to canonical truth docs. |
+| Durable truth curation | Keeps docs bounded, evidence-backed, and reviewable instead of letting them grow into catch-all files. |
 | Reviewable handoffs | Produces ordinary Git diffs for both code and truth docs. |
 | Local-first operation | Requires no hosted service, daemon, database, or MCP server. |
 | Safer write boundaries | Separates code-first, doc-first, read-only, and doc-only workflows. |
@@ -154,6 +165,8 @@ Not governance as ceremony. Governance as a simple question:
 
 Truthmark helps teams answer that with committed files, explicit routing, and reviewable diffs.
 
+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.
+
 It is useful when you need:
 
 - less documentation drift
@@ -193,6 +206,8 @@ keep the result reviewable in Git
 
 The README is the storefront: fast context, quick start, and the core mental model.
 
+The [static website](https://merlinhu1.github.io/truthmark/) is the concise public introduction for GitHub Pages.
+
 For command-by-command usage, surface comparisons, supported platform details, configuration, routing, Portal, and examples, read the [Truthmark User Guide](docs/user-guide.md).
 
 ## Project status

package/dist/main.js

@@ -1235,6 +1235,16 @@ var renderBehaviorDocTemplateFile = () => {
     "",
     "{{core_rules}}",
     "",
+    "## Behavior Scenarios",
+    "",
+    "<!--",
+    "Use compact scenario blocks only where they clarify normal, fallback, or compatibility-critical behavior.",
+    "Write scenarios as current truth, not desired requirements: `#### Scenario: <implemented case>` followed by `- **GIVEN** ...`, `- **WHEN** ...`, `- **THEN** ...`, and optional `- **AND** ...` bullets.",
+    "Keep each bullet evidence-backed and observable; do not force a scenario for every rule.",
+    "-->",
+    "",
+    "{{behavior_scenarios}}",
+    "",
     "## Flows And States",
     "",
     "<!--",
@@ -2118,7 +2128,14 @@ var FEATURE_DOC_TEMPLATE_INSTRUCTIONS = [
   "If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.",
   "Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards."
 ].join("\n");
-var TRUTH_DOC_AUTHORING_STYLE_INSTRUCTIONS = "Prefer diff-friendly Markdown: one durable claim per bullet or line, paragraphs no longer than one or two short sentences, and bullets or tables for rules, criteria, fields, files, and lists.";
+var TRUTH_DOC_AUTHORING_STYLE_INSTRUCTIONS = [
+  "Truth-doc prose style:",
+  "- Use professional, plain technical prose. Prefer specific current-state claims over promotional, symbolic, or generic significance language.",
+  "- Avoid common AI-writing tells: pivotal, crucial, underscores, serves as, stands as, showcases, landscape, vague expert attributions, and generic upbeat conclusions.",
+  "- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences.",
+  "- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone.",
+  "- Rewrite dense or formulaic prose only when it improves readability without removing scope, evidence, decisions, or source references."
+].join("\n");
 var renderTruthDocOwnershipGateSection = (subject, outcome) => {
   return [
     "Truth-doc ownership review:",
@@ -3224,6 +3241,7 @@ ${renderTruthSyncProductDecisionRuleBlock(config)}
    - No-update-needed rationale: why mapped truth is already current when no truth doc should change
    - Blockers: missing routing, ambiguous ownership, failed verification, unavailable evidence, or off-boundary write needs
 11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, repair topology first when the repair is safe and in scope, otherwise stop and recommend Truth Structure instead of guessing.
+${TRUTH_DOC_AUTHORING_STYLE_INSTRUCTIONS}
 ${subagentMode}Topology review and repair:
 - before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner
 - if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when topology repair is safe and in scope