Use the README for the fast evaluation path: what Truthmark is, why it matters, and how to get started. Use this guide when you want command-by-command details, supported platform surfaces, workflow boundaries, configuration, routing, Portal, and examples.
The agent-run 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.
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.
It presents a numbered, comma-separated multi-select. Choose zero or more platforms, enter `none` for host-neutral CLI-only setup, or enter `q` to cancel without writing repository files. On rerun, saved platforms are marked as selected; pressing Enter keeps that selection.
For automation, repeat `--platform <id>`. Explicit values replace the complete saved platform set and are normalized into the supported-platform order:
```bash
truthmark init --platform codex --platform cursor
```
Use `truthmark init --clear-platforms` to return the repository to host-neutral setup.
`truthmark init --json` never prompts. On a first noninteractive run with no `--platform`, it creates a host-neutral repository with no host-specific surfaces. A later noninteractive no-flag rerun uses the saved selection. Truthmark never detects and silently selects the current host.
Rerun interactive init and omit a previously selected platform, or use `--clear-platforms`, to stop rendering host-specific surfaces. `truthmark init` reconciles the selected surface set and removes only recognized managed artifacts; review generated-surface diffs intentionally.
Instruction files are derived from platforms: Claude Code uses `CLAUDE.md`; shared-contract hosts use the deduplicated `AGENTS.md`; host-specific canonical instructions remain renderer-owned.
If the config's `platforms` field is omitted, no platform is active. `truthmark init` reconciles recognized renderer-owned generated files and managed instruction blocks away; authored content outside valid managed markers is preserved, and only a block-only file can become absent.
Before leaving Truthmark, run `truthmark uninstall --dry-run`, review the exact-path `truthmark-lifecycle/v0` plan, then run `truthmark uninstall --apply`. Uninstall preserves `.truthmark/config.yml`, routes, truth documents, editable templates, Portal presentation output, unrelated host-directory files, and content outside managed markers. Remove preserved files manually only after review. A globally installed npm package is separate; remove it with your package manager if desired.
Human-only means user-invoked, not agent-automatic. Sync is the normal automatic finish-time workflow after functional code changes. Structure may also run inside Document or Sync when routing blocks the requested work.
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 Antigravity, use `@truthmark-document ...`; in Cursor, use `/truthmark-document ...` or let the Agent Skill be selected by description.
Optional repository-intelligence helpers generate derived review material for the active checkout, such as RepoIndex, RouteMap, ImpactSet, and compact WorkflowState/action-context JSON. Validation helpers are exposed as optional workflow metadata and explicit `truthmark validate ... --json` commands; they are accelerators, not bundled repo-local helper manifest or policy files and not sources of truth. Standalone Copilot prompts, Antigravity rules, and Cursor Agent Skills use the same CLI validator contract when the installed runner is available, and otherwise report a visible skipped helper status with manual validation.
| `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.
Init creates a version-2 config when none exists. Existing valid version-2 configs remain valid: init changes only top-level platform ownership when the selection changes, while preserving other supported values and YAML comments. Invalid existing config remains fail-closed and is not overwritten.
| `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`. |
| `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
Do not start normal work by calling Truth Sync yourself. Ask the agent for the code change; the installed repository instructions tell it to run relevant tests and perform Sync review before handoff.
