truthmark 2.2.2 → 2.2.5

package/README.md

@@ -2,194 +2,116 @@
 
 **Your agents write code. Truthmark maintains human-facing, Git-reviewable documentation.**
 
-English | [Deutsch](README.de.md) | [中文](README.zh.md) | [Español](README.es.md) | [Русский](README.ru.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)
 
-AI coding agents can change a repository faster than humans can keep its documentation aligned.
+## 🚀 Quick Start: running locally in five minutes
 
-Truthmark fixes the part that usually breaks after the code is written: the repository truth.
+Run this inside the Git repository you want Truthmark to manage:
 
-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.
-
-No hosted service.
-
-No database.
-
-No hidden memory layer.
-
-No extra server to operate.
-
-Just repository truth that moves with the branch.
-
-## The problem
-
-AI coding agents are good at producing code. That creates a new failure mode.
-
-The implementation changes, but the repository story drifts:
-
-- behavior lives in chat history
-- architecture docs fall behind
-- product decisions disappear after handoff
-- reviewers see code diffs without the related truth diffs
-- branches quietly develop different versions of “what is true”
-- each agent session has to rediscover repository truth from scratch
-
-Truthmark turns that fragile repository truth into committed repository infrastructure.
-
-Instead of relying on every human and every agent to remember the right documentation habit, Truthmark installs the habit into the repository.
-
-## The promise
-
-When an agent changes functional code, the work should not end with only a code diff.
-
-The normal Truthmark path is:
-
-```text
-agent changes functional code
-relevant tests run
-Truth Sync checks mapped truth docs
-truth docs update when needed
-human reviews code diff + truth diff
-commit or hand off
+```bash
+cd /path/to/your-repo
+npm install -g truthmark
+truthmark config
 ```
 
-That is the core value: **AI work becomes easier to trust because the repository stays legible.**
+Enable the AI host you actually use. Fresh configs are host-neutral, so add a top-level `platforms` list to `.truthmark/config.yml` before initialization:
 
-## Two surfaces, one truth system
-
-Truthmark is not just a CLI.
-
-It has two distinct surfaces, and the distinction matters.
-
-### 1. Human-facing CLI
-
-The CLI is for maintainers, reviewers, and automation.
+```yaml
+version: 2
+platforms:
+  - codex        # or: claude-code, github-copilot, opencode, antigravity, cursor
+truthmark:
+  workspace: docs/truthmark
+  generated:
+    portal:
+      enabled: false
+```
 
-Use it to configure a repository, install or refresh workflow files, validate truth artifacts, and generate optional review material.
+Then install the repo-local truth docs, routing, and AI-host instructions:
 
 ```bash
-truthmark config
 truthmark init
 truthmark check
+git diff
 ```
 
-The CLI prepares and validates the repository environment.
-
-It is not the AI workflow runtime.
-
-### 2. AI-facing workflow surfaces
-
-The AI-facing surfaces are for coding agents.
-
-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.
-
-Examples:
-
-```text
-/truthmark-sync
-/truthmark-document
-/truthmark-structure
-/truthmark-realize
-/truthmark-preview
-/truthmark-check
-```
-
-These look like commands because agent hosts expose workflows through slash commands, prompts, skills, or project commands.
-
-They are not shell commands.
-
-They are AI-facing workflow entrypoints.
-
-The split is the product:
+Now try the most common adoption path: document one existing behavior from code and tests. In your AI coding host, ask the installed workflow:
 
 ```text
-humans own the repository contract
-Truthmark installs the contract into the repo
-agents operate inside that contract
-truth updates appear as Git diffs
-humans review the result
+/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
 ```
 
-## Quick start
-
-### Requirements
-
-- Node.js `>=20`
-- npm
-- a Git repository
-
-### Install Truthmark
+After that, users should not normally invoke Truth Sync directly. Keep coding through your AI host; the installed repository instructions tell the agent to run relevant tests and perform the Truth Sync review before handoff when functional code changes. You review the resulting code diff plus truth-doc diff.
 
-Run this inside the repository you want to initialize:
-
-```bash
-cd /path/to/your-repo
-npm install -g truthmark
-```
+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`.
 
-### Create the repository truth contract
+## 💡 The Problem: The AI Documentation Gap
 
-```bash
-truthmark config
-```
+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.**
 
-This creates:
+* Behavior is lost in ephemeral chat histories.
+* Architecture documents quickly fall behind.
+* Product decisions vanish after handoff.
+* Code reviewers are left examining raw code diffs without understanding the "why."
+* Every new AI session is forced to rediscover your repository's truth from scratch.
 
-```text
-.truthmark/config.yml
-```
+## 🎯 The Solution: Truthmark
 
-Review this file before continuing. It defines the committed hierarchy contract for the repository.
+**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.
 
-### Install the workflow surfaces
+Instead of hoping humans and AI agents remember to update docs, Truthmark makes documentation a systematic, reviewable habit right inside your repo.
 
-```bash
-truthmark init
-```
+### ✨ Why Truthmark is Unique
 
-This installs or refreshes:
+Truthmark isn't just another documentation tool. It is deeply integrated into the AI workflow:
 
-- route files
-- truth-doc scaffolding
-- managed instruction blocks
-- AI-facing workflow surfaces for configured platforms
+* **🚫 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.
+* **✅ Trust Through Verification:** AI work becomes easier to trust because behavior-changing work includes a human-reviewable truth-doc decision or diff.
 
-Default truth-doc templates are justified in [Template Standards](docs/standards/template-standards.md), which maps them to recognized software engineering references such as ISO/IEC/IEEE 42010, ISO/IEC/IEEE 29148, ISO/IEC/IEEE 12207, ISO/IEC 25010, C4, arc42, OpenAPI, SemVer, Google SRE, and Diátaxis.
+## 🔄 How It Works
 
-### Validate the setup
+When an AI agent modifies your code, the job isn't finished. Truthmark installs a finish-time workflow guard that agents follow before handoff:
 
-```bash
-truthmark check
-```
+1. 💻 **Code:** Agent modifies functional code.
+2. 🧪 **Test:** Relevant tests are executed.
+3. 🔍 **Check:** Truthmark checks mapped documentation as part of the installed finish-time review.
+4. 📝 **Document:** Docs are updated by the agent when repository truth has changed.
+5. 👀 **Review:** A human reviews the *code diff* + the *truth diff*.
 
-Then review the generated files before committing.
+## 🛠 How you interact with Truthmark
 
-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.
+Truthmark has one repo-local contract with two ways to use it.
 
-## First real use
+### Humans install and validate the contract
 
-Most repositories need one cleanup pass after initialization.
+Maintainers and CI use the CLI:
 
-The default scaffold starts with a provisional broad `repository` bootstrap area. Before normal syncing on real code, split that bootstrap route into precise routing.
+* `truthmark config` - create the initial configuration.
+* `truthmark init` - install or refresh routing, truth-doc scaffolds, and AI-host instructions.
+* `truthmark check` - validate the repository truth from the terminal.
 
-Ask your agent to split the broad route into actual product, service, domain, or ownership areas:
+### Agents follow the contract while coding
 
-```text
-/truthmark-structure split the broad repository area into auth, billing, and notifications
-```
+Truthmark installs repo-local instructions for supported AI coding hosts such as Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, and Cursor.
 
-If the project already has implemented features but missing or weak truth docs, ask the installed Truth Document workflow to document a focused scope:
+The normal loop is simple:
 
-```text
-/truthmark-document document the implemented payment retry behavior in src/billing/retry.ts and related tests
-```
+1. Ask your agent for a code change, or ask it to document existing behavior.
+2. The installed instructions tell the agent when to test, when to update truth docs, and when to stop for human review.
+3. You review ordinary Git diffs: code plus any truth-doc changes.
 
-Truth Document is the common first workflow for existing projects. It inspects implementation, tests, routes, and existing docs, then creates or repairs truth docs and routing without changing functional code.
+The user-started agent requests are intentionally few:
 
-After that, use your AI coding agent normally.
+* `/truthmark-document` - document existing implemented behavior from code and tests.
+* `/truthmark-realize` - implement code from existing truth docs.
+* `/truthmark-check` - audit repository truth.
 
-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.
+Truth Sync is not the usual way to start work; it is the finish-time review after functional code changes.
+Truth Structure is not a day-to-day command; it repairs routing or ownership only when that blocks the work.
 
 ## What you get
 
@@ -198,7 +120,7 @@ When the agent changes functional code, Truth Sync acts as the finish-time guard
 | Git-native truth | Keeps repository truth in committed Markdown and config. |
 | Branch-scoped documentation | Truth moves with the branch instead of living in a private session. |
 | Human CLI | Gives maintainers setup, refresh, validation, and inspection commands. |
-| AI-facing workflows | Gives agents host-native workflows for sync, documentation, structure, preview, realization, and audit. |
+| 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. |
 | Reviewable handoffs | Produces ordinary Git diffs for both code and truth docs. |
 | Local-first operation | Requires no hosted service, daemon, database, or MCP server. |
@@ -210,7 +132,7 @@ When the agent changes functional code, Truth Sync acts as the finish-time guard
 
 ![Truthmark features](docs/assets/truthmark-features.png)
 
-**Features:** what Truthmark installs and how the workflow surface is split.
+**Features:** what Truthmark installs and how agents use repo-local instructions.
 
 ![Truthmark position](docs/assets/truthmark-position.png)
 
@@ -241,7 +163,7 @@ It is useful when you need:
 - explicit ownership between docs and code
 - safer agent write boundaries
 - reviewable documentation instead of hidden memory
-- AI workflows that still work from committed repo files
+- agent guidance that still works from committed repo files
 
 ## Where Truthmark fits
 
@@ -263,561 +185,40 @@ Truthmark’s lane is narrow by design:
 ```text
 make repository truth explicit
 route it to code
-install agent workflows around it
+install agent guidance around it
 keep the result reviewable in Git
 ```
 
-## How Truthmark runs
-
-Truthmark runs locally against the active Git worktree.
-
-The human-facing CLI reads and writes repository files, then exits.
-
-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.
-
-The layers fit together like this:
-
-```mermaid
-flowchart LR
-  Human["Human / CI"] --> CLI["Truthmark CLI"]
-  CLI --> Config["Config and route map"]
-  CLI --> Truth["Canonical truth docs"]
-  CLI --> Surfaces["Generated host-native workflows"]
-  Surfaces --> Hosts["Codex / Claude Code / Copilot / OpenCode / Gemini"]
-  Hosts --> Worktree["Active Git worktree"]
-  Hosts -->|"helper checks / validate / index"| CLI
-  Worktree --> Truth
-```
-
-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.
-
-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.
-
-Generated workflow surfaces include Truthmark version markers. After upgrading Truthmark, rerun:
-
-```bash
-truthmark init
-```
-
-Then review the generated diffs.
-
-## Supported agent platforms
-
-The default config includes every supported platform.
-
-Remove platforms you do not use from `.truthmark/config.yml`, then rerun:
-
-```bash
-truthmark init
-```
-
-| Platform config name | Generated surface | Invocation shape |
-| --- | --- | --- |
-| `codex` | Skill packages and verifier agents | `/truthmark-*` or `$truthmark-*` |
-| `claude-code` | Project skills, verifier agents, and managed instructions | `/truthmark-*` |
-| `github-copilot` | Agent skills, prompt commands, custom agents, and managed instructions | `/truthmark-*` in supported Copilot IDEs; `@truth-*` custom agents in Copilot CLI |
-| `opencode` | Skill packages and verifier agents | `/skill truthmark-*` |
-| `gemini-cli` | Agent skills, slash commands, subagents, and managed instructions | `/truthmark:*` |
-
-Unknown platform names are config errors.
-
-Removing a platform stops future refreshes for that platform. It does not delete previously generated files.
-
-## AI-facing workflows
-
-These workflows are installed into supported AI coding hosts.
-
-They are used by agents or agent hosts during repository work. They are not top-level shell commands.
-
-| Workflow | Direction | Use it when | Write boundary |
-| --- | --- | --- | --- |
-| 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. |
-| 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. |
-| 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. |
-| Truth Preview | read-only | The agent needs to preview likely routing before edits. | Reads only. Does not authorize writes. |
-| 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. |
-| Truth Check | audit-first | A reviewer or agent needs to audit repository truth health. | Audits and reports. |
-| 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 fixed Portal output directory. |
-
-### Important distinction
-
-Do not confuse these two surfaces:
-
-| Surface | Used by | Example | Meaning |
-| --- | --- | --- | --- |
-| Human CLI | humans, scripts, CI-like checks | `truthmark check` | Validate repository truth artifacts from the terminal. |
-| AI-facing workflow | coding agents and agent hosts | `/truthmark-check` | Ask an agent to run the installed audit workflow. |
-
-The names are intentionally related, but the surfaces are different.
-
-## Normal AI-assisted code change
-
-Most users should not need to invoke Truth Sync manually every time.
-
-Truth Sync is the installed finish-time guard for functional code changes.
-
-```text
-agent changes functional code
-agent runs or asks for relevant tests
-installed workflow detects that functional code changed
-Truth Sync checks mapped truth docs
-agent updates truth docs if needed
-human reviews code diff + truth diff
-```
-
-Direct invocation is still useful for troubleshooting, forcing an early sync, or making the handoff explicit:
-
-```text
-/truthmark-sync sync the repository truth now before handoff
-```
-
-## Existing behavior without docs
-
-Use Truth Document when the implementation already exists but the repository truth is incomplete. This is the normal path for established repositories adopting Truthmark after the codebase already exists.
-
-```text
-/truthmark-document document the implemented session timeout behavior across src/auth/session.ts, src/auth/middleware.ts, and tests/auth/session.test.ts
-```
-
-Give it the feature name, code paths, test paths, or desired truth-doc area. On OpenCode-style hosts, call the same workflow as `/skill truthmark-document ...`; on Gemini CLI, use `/truthmark:document ...`.
-
-For a large repo that still has one broad placeholder route, run Truth Structure first, then invoke Truth Document for one bounded feature or area at a time.
-
-Truth Document inspects implementation, tests, route files, and existing docs as evidence.
-
-It writes truth docs and routing only.
-
-It must not change functional code.
-
-## Doc-first changes
-
-Use Truth Realize when a product or architecture decision starts in docs and code should be updated to match.
-
-```text
-/truthmark-realize realize docs/truthmark/product/capabilities/session-timeout.md into code
-```
-
-Truth Realize is doc-first.
-
-The truth docs lead. The code follows.
-
-The agent must not edit the truth docs it is realizing.
-
-## Read-only routing preview
-
-Use Truth Preview before a change when the agent needs to understand likely routing.
-
-```text
-/truthmark-preview preview the likely truth routing for changes to the billing API
-```
-
-Truth Preview is read-only.
-
-It is a selector and planning aid, not write authorization and not a replacement for Truth Check.
-
-## Repository truth audit
-
-Use Truth Check when you want an agent-facing audit workflow.
-
-```text
-/truthmark-check audit routing and truth coverage before review
-```
-
-Use the human-facing CLI when you want terminal validation:
-
-```bash
-truthmark check
-```
-
-Both are useful. They are not the same surface.
-
-## Human-facing CLI commands
-
-Most maintainers start with three commands.
-
-| Command | Purpose |
-| --- | --- |
-| `truthmark config` | Create `.truthmark/config.yml`. Writes only that file unless `--stdout` is used. |
-| `truthmark init` | Install or refresh configured workflow surfaces from the reviewed config. |
-| `truthmark check` | Validate configuration, authority, routing, decision-bearing docs, frontmatter, internal links, branch scope, generated surfaces, freshness, and coverage diagnostics. |
-
-Optional repository-intelligence helpers generate derived review material for the active checkout, such as RepoIndex, RouteMap, ImpactSet, and compact WorkflowState/action-context JSON. 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.
-
-They are not sources of truth.
-
-| Command | Purpose |
-| --- | --- |
-| `truthmark index` | Build RepoIndex and RouteMap JSON for the active checkout. |
-| `truthmark impact --base <ref>` | Map changed files to routed truth docs, owning routes, nearby tests, and public symbols. |
-| `truthmark workflow status --workflow <workflow> [--base <ref>] --json` | Return workflow applicability, write boundaries, target truth docs, checks, helper commands, and compact affected-test guidance. |
-
-Structured output is available with `--json` where supported.
-
-## Truthmark Portal
-
-Truthmark Portal is an optional presentation workflow for teams that want a human-readable site over their committed truth docs.
-
-It is deliberately separate from the core truth workflow:
-
-- Markdown truth docs remain canonical.
-- Generated Portal HTML is presentation only.
-- Portal is manual-only; it does not run as a completion review, Truth Sync step, `truthmark check` step, or automatic post-change hook.
-- Portal writes stay inside the fixed Truthmark-derived output directory.
-- Generated pages should use local assets, source provenance, and a visible Markdown-canonical disclaimer.
-
-Enable it with the namespaced config block:
-
-```yaml
-truthmark:
-  generated:
-    portal:
-      enabled: true
-```
-
-Then rerun:
-
-```bash
-truthmark init
-```
-
-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.
-
-## Configuration
-
-Truthmark is config-first.
-
-The main config file is:
-
-```text
-.truthmark/config.yml
-```
-
-New repositories should run:
-
-```bash
-truthmark config
-```
-
-Then review the generated config before running:
-
-```bash
-truthmark init
-```
-
-Important config areas include:
-
-| Config area | Purpose |
-| --- | --- |
-| `version` | Config contract version. |
-| `platforms` | Agent hosts that should receive platform-specific generated surfaces. |
-| `truthmark.workspace` | Truthmark-owned workspace for routes, truth docs, templates, and generated presentation output. |
-| Fixed routes | Routes live under `routes/areas.md` and `routes/areas/` inside `truthmark.workspace`; the default area is `repository` and delegation depth is `1`. |
-| Fixed truth lanes | Product truth lives under `product/` and engineering truth under `engineering/` inside `truthmark.workspace`. |
-| Fixed templates | Truth-doc templates live under `templates/` inside `truthmark.workspace`. |
-| `truthmark.generated.portal` | Optional manual presentation workflow enablement: `enabled`. |
-| `instruction_targets` | Files that receive shared managed instruction blocks, such as `AGENTS.md`. |
-| `frontmatter.required` | Metadata fields that produce error diagnostics when missing. |
-| `frontmatter.recommended` | Metadata fields that produce review diagnostics when missing. |
-| `ignore` | Glob patterns excluded from relevant checks and routing logic. |
-
-## Repository truth routing
-
-Truthmark maps code surfaces to truth docs.
-
-The main routing files are:
-
-```text
-docs/truthmark/routes/areas.md
-docs/truthmark/routes/areas/**/*.md
-```
-
-A route tells the agent:
-
-- which code surface belongs to an area
-- which truth docs own that area
-- when truth should be updated
-- what kind of truth doc is involved
-
-The default scaffold starts with a provisional broad bootstrap route so a fresh repository is routeable. When real code is touched, split that bootstrap route into real product, service, domain, or ownership areas before normal Truth Sync; do not turn the bootstrap handoff into a catch-all behavior doc.
-
-Example:
-
-```text
-/truthmark-structure split the broad repository area into frontend, backend, billing, and deployment
-```
-
-Good routing gives Truth Sync precise destinations.
-
-Bad routing makes agents guess.
-
-## What Truthmark installs
-
-Truthmark installs a compact repository-native truth layer.
-
-It does this in four layers:
-
-- configuration and routing for ownership boundaries
-- canonical truth docs and starter templates
-- compact managed instruction blocks for repository-wide agent instructions
-- host-native workflow packages, commands, prompts, and verifier agents for the platforms enabled in config
-
-Truthmark preserves manual content outside managed instruction blocks.
-
-Generated workflow surfaces are managed by Truthmark and may be refreshed by rerunning:
-
-```bash
-truthmark init
-```
-
-## Subagents and bounded evidence checks
-
-Where supported by the host, Truthmark can install project-scoped verifier agents and a leased `truth-doc-writer`.
-
-These help keep large truth tasks bounded:
-
-- route auditors inspect route ownership
-- claim verifiers check whether doc claims are supported by evidence
-- doc reviewers inspect truth-doc quality
-- leased doc writers handle bounded truth-doc writing shards
-
-The parent workflow still owns final interpretation, write boundaries, diff validation, and acceptance.
-
-This is important: subagents help with bounded evidence work. They do not replace the main workflow contract.
-
-## Review loop
-
-Truthmark is designed for ordinary Git review.
-
-A good AI-assisted handoff should show:
-
-```text
-code diff
-test evidence
-truth-doc diff, if needed
-routing changes, if needed
-agent report
-```
-
-The reviewer should be able to answer:
-
-- What code changed?
-- Which truth docs own that code?
-- Did those docs need updates?
-- If not, why not?
-- Did the agent stay inside the workflow write boundary?
-- Are tests or verification evidence included?
-
-## Examples
-
-### Initialize a repository
-
-```bash
-npm install -g truthmark
-truthmark config
-truthmark init
-truthmark check
-```
-
-### Remove unused agent platforms
+## Go deeper
 
-Edit:
+The README is the storefront: fast context, quick start, and the core mental model.
 
-```text
-.truthmark/config.yml
-```
-
-Then rerun:
-
-```bash
-truthmark init
-truthmark check
-```
-
-### Split broad routing
-
-```text
-/truthmark-structure split the broad repository area into auth, billing, notifications, and deployment
-```
-
-### Document implemented behavior
-
-```text
-/truthmark-document document the implemented password reset flow under docs/truthmark/engineering/behaviors/authentication
-```
-
-### Sync after code changes
-
-```text
-/truthmark-sync sync the repository truth now before handoff
-```
-
-### Realize a doc-first decision
-
-```text
-/truthmark-realize realize docs/truthmark/product/capabilities/invoice-retry-policy.md into code
-```
-
-### Audit truth health from the terminal
-
-```bash
-truthmark check
-```
-
-### Generate branch-impact summary
-
-```bash
-truthmark impact --base main
-```
-
-### Inspect workflow status
-
-```bash
-truthmark workflow status --workflow truthmark-sync --base main --json
-```
-
-### Enable the optional Portal workflow
-
-```yaml
-truthmark:
-  generated:
-    portal:
-      enabled: true
-```
-
-```bash
-truthmark init
-```
-
-Then explicitly ask the agent host to run the installed Portal workflow when you want the static presentation site generated or refreshed.
+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
 
-Truthmark V1 currently provides:
-
-- `truthmark config`
-- `truthmark init`
-- `truthmark check`
-- `truthmark index`
-- `truthmark impact`
-- `truthmark workflow status`
-- branch-scope metadata
-- managed instruction blocks
-- generated Truth Structure workflow surfaces
-- generated Truth Document workflow surfaces
-- generated Truth Sync workflow surfaces
-- generated Truth Preview workflow surfaces
-- generated Truth Realize workflow surfaces
-- generated Truth Check workflow surfaces
-- optional generated Truthmark Portal workflow surfaces
-- route, authority, decision-structure, frontmatter, link, freshness, generated-surface, and coverage diagnostics
-- derived RepoIndex, RouteMap, ImpactSet, and WorkflowState artifacts
-- host-specific surfaces for Codex, Claude Code, GitHub Copilot, OpenCode, and Gemini CLI
-
-## Development
-
-Install dependencies:
-
-```bash
-npm install
-```
-
-Run the local development CLI:
-
-```bash
-npm run dev -- init
-npm run dev -- check
-```
-
-Run the full project check:
+The current release provides:
 
-```bash
-npm run check
-```
-
-Useful scripts:
-
-| Script | Purpose |
-| --- | --- |
-| `npm run dev` | Run the TypeScript CLI entry point with `tsx`. |
-| `npm run build` | Build the package. |
-| `npm run lint` | Run ESLint. |
-| `npm run typecheck` | Run TypeScript checks. |
-| `npm run test` | Run tests. |
-| `npm run check` | Run lint, typecheck, tests, and build. |
-| `npm run release:check` | Run release-oriented validation. |
-
-When changing Truthmark itself, see [CONTRIBUTING.md](CONTRIBUTING.md).
+- local CLI commands for config, init, check, index, impact, and workflow status
+- generated repo-local agent instructions for Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, and Cursor
+- route, authority, frontmatter, link, freshness, generated-surface, branch-scope, and coverage diagnostics
+- branch-scoped truth docs and derived repository-intelligence artifacts
 
 ## Documentation
 
-The README is the fast path for evaluation and setup.
-
-Detailed current behavior lives under `docs/`:
-
+- [User guide](docs/user-guide.md)
 - [Docs index](docs/README.md)
 - [Architecture overview](docs/truthmark/engineering/architecture/overview.md)
 - [API and CLI contracts](docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
-- [Init and scaffold behavior](docs/truthmark/engineering/behaviors/init-and-scaffold.md)
-- [Check diagnostics](docs/truthmark/engineering/behaviors/check-diagnostics.md)
-- [Installed workflows](docs/truthmark/engineering/workflows/installed-workflow-runtime.md)
 - [Repository truth maintenance guide](docs/standards/maintaining-repository-truth.md)
 
-## Design boundaries
-
-Truthmark is intentionally small.
-
-It is not:
-
-- a hosted service
-- an MCP server
-- a vector database
-- a canonical documentation website generator or hosted docs platform
-- a CI or PR enforcement product
-- a replacement for tests, code review, or technical leadership
-- an autonomous code rewrite engine
-- a model-training or fine-tuning framework
-- a hidden memory layer
-
-Those boundaries are part of the product.
-
-Truthmark keeps the workflow local, committed, branch-scoped, and reviewable.
-
-## Safety and review discipline
+For local development and contribution commands, see [CONTRIBUTING.md](CONTRIBUTING.md).
 
-Truthmark helps the repository stay honest. It does not prove the code is correct.
-
-Teams should still:
-
-- run relevant tests
-- review functional code changes
-- review truth-doc changes
-- keep secrets out of docs
-- keep repository-specific instructions outside managed blocks
-- review generated workflow-surface diffs after upgrades
-- keep human ownership over product and architecture decisions
-
-Truthmark makes agent-facing repository truth visible. It does not replace human judgment.
-
-## Roadmap direction
-
-The current future direction emphasizes:
-
-- stronger `truthmark check` evidence reporting
-- clearer adoption examples
-- example repositories showing real Truth Sync cycles
-- migration guides for teams already using agent instruction files
-- conformance tests for generated host surfaces
-- route-aware stale-truth hints
-- bounded implementation checklists for doc-first work
+## Design boundaries
 
-The center of gravity stays the same:
+Truthmark is intentionally small: local, committed, branch-scoped, and reviewable.
 
-```text
-repository truth
-agent-native workflows
-Git review
-branch-scoped documentation
-```
+It is not a hosted service, MCP server, vector database, hidden memory layer, CI enforcement product, or autonomous code rewrite engine. It helps repository truth stay visible; it does not replace tests, code review, or human judgment.
 
 ## License