Reference

The veri/ on-disk format. Everything here is plain markdown with YAML frontmatter — readable raw, diffable, and owned by your repo, not by Veri.

Directory layout

your-project/
├── .mcp.json            ← agent connection config (written by the app)
└── veri/
    ├── format           ← format version marker (currently "1")
    ├── workflow.md      ← WF-001, the project workflow
    ├── requirements/    ← REQ-001-….md
    ├── decisions/       ← DEC-001-….md
    ├── work-orders/     ← WO-001-….md
    ├── sources/         ← SRC-001-….md
    └── templates/       ← seed bodies for new documents

The format file holds a single integer. Veri reads it before parsing anything: a project needing a newer Veri is stated as such (never misparsed), an older-format project is offered an explicit migration (veri migrate), and a directory created before the marker existed is treated as the oldest format, not rejected.

Document types and statuses

Type	Id prefix	Statuses	Notes
requirement	`REQ-`	`draft` → `accepted` → `retired`	`accepted` requires an `approved:` date — the user's stamp.
decision	`DEC-`	`proposed` → `active` → `superseded`	`active` requires `approved:`; `superseded` must name its successor in `superseded_by:`.
work-order	`WO-`	`backlog` → `in-progress` → `done`	`done` requires every acceptance box checked and at least one receipt.
source	`SRC-`	`imported`	External evidence; one status, no lifecycle.
workflow	`WF-`	`draft` → `accepted` → `retired`	One per project; scaffolded projects ship theirs pre-accepted.

Frontmatter

---
id: WO-002
type: work-order
title: PDF export pipeline
status: in-progress
created: 2026-07-30
updated: 2026-08-06
links:
  - id: REQ-002
    rel: implements
  - id: DEC-005
    rel: constrained-by
---

id — type prefix plus a number of three or more digits, zero-padded to three below 1000 (REQ-001, REQ-1000). The prefix must match type. Ids are assigned by the app/CLI as the next free number and never reused.
created / updated / approved — YYYY-MM-DD dates. approved appears only when the user promotes a document.
approved_by — the display name of the maintainer who stamped the approval. Written by veri approve --as; required (and validated against the workflow's maintainers: list) only in projects that declare one — see the team workflow.
links — outbound edges: a target id and a rel. Inbound links are derived, never stored.
Unknown keys are preserved — Veri round-trips frontmatter it doesn't recognize, so your own fields are safe.

Links and rels

In document bodies, [[REQ-001]] references any document by id (the app autocompletes on [[); broken references are flagged by veri check. In frontmatter, rel is free text — use what reads truthfully — but these are the conventions in use:

rel	Meaning (A → B)
`implements`	A delivers what B requires (work order → requirement).
`constrained-by` / `constrains`	B binds choices inside A (work order ↔ decision).
`informed-by`	B is evidence behind A (anything → source).
`depends-on`	A needs B to exist or hold first.
`extends` / `refines` / `builds-on` / `follows-from`	A continues or narrows B (decision lineages, requirement families).
`designed-by`	B is the design artifact for A. Load-bearing when a project enforces a design gate: work orders touching UI must carry one.

Templates

veri/templates/ holds the seed body for each type; veri new and the app's New-document flow start from them, and veri check expects each document to keep its template's ## sections. The defaults:

requirement — description, then ## Acceptance criteria
decision — ## Choice, ## Rejected alternatives, ## Rationale
work-order — ## Summary, ## In scope, ## Out of scope, ## Requirements, ## Acceptance tests, ## Receipts
source — free-form imported material

Edit the templates and your project's new documents start your way; context packages include them so agents file documents in your shape too.

`veri check` rules

Zero issues is the bar — the app surfaces these live, and veri check exits non-zero in CI when any fire:

Rule	Fires when
`duplicate-id`	Two files claim the same id — the merge-collision case; the error names every claimant and the `veri renumber` resolution (see teams).
`broken-link`	A frontmatter link, `superseded_by`, or inline `[[ref]]` targets an id no document has.
`wo-without-requirement`	A work order links no requirement — unjustified work.
`gated-wo`	A work order moved forward while depending on a document still awaiting approval — approve the dependency first.
`missing-approval`	A document sits in a promoted status (`accepted`, `active`) without the user's `approved:` stamp.
`unknown-approver`	(Maintainers projects) `approved_by` names someone not on the workflow's `maintainers:` list. A promoted document missing `approved_by` only warns — pre-team stamps are grandfathered as an advisory.
`done-wo-violation`	A work order is `done` with unchecked acceptance boxes or no receipt.
`ui-wo-without-design`	(Design-gated projects) a UI work order has no resolvable `designed-by` link.
`missing-section`	A document lost a `##` section its type's template expects.
`format-mismatch`	The `veri/format` marker doesn't match what this Veri reads — migrate, or update Veri.

Softer signals ship as advisories — shown greyed in the app, never failing the check.

The CLI

veri init [--demo]         scaffold a veri/ directory (--demo: the sample project)
veri new <type> "<title>"  create a document with the next free id
veri check                 report knowledge-base issues (exit 1 if any)
veri approve <id> [--as <maintainer>]
                           approve a pending document (stamps approved: today,
                           and approved_by: in maintainers projects)
veri renumber <id> [--to <new-id>] [--file <path>] [--refs <path,path>]
                           move a document to a new id, rewriting the filename
                           and inbound links in one atomic pass (collision
                           resolution: see the team workflow page)
veri migrate               bring veri/ to the current on-disk format
veri import                print the kickoff prompt for mining this repo into proposals
veri list [type]           list documents: id, status, title
veri open [dir]            open the project in the Veri desktop app

The CLI and the desktop app read and write the same files; everything above works identically from either.

The MCP server's tools

The stdio MCP server (@veri/mcp) serves one project and exposes ten tools. Reads return documents exactly as on disk; writes can only produce pending documents — nothing an agent files becomes binding without your approval.

Tool	What it does
`get_context(id)`	Context package for a work order: the project workflow first, then the work order, its linked requirements and decisions (2 hops), pending proposals labeled non-binding, source excerpts, and the project's document templates, with per-document and total token estimates. Superseded decisions are named as already rejected, bodies omitted; when the neighborhood is too large to inline, its outer ring arrives as a context map to retrieve from instead of full bodies. The same package `veri context <WO-id>` prints in a terminal.
`search(query)`	Case-insensitive substring match over id, title, and body.
`get_document(id)`	One document in full, exactly as on disk.
`get_neighbors(id)`	A document's outbound links and backlinks, with relations.
`file_decision(title, choice, …)`	Record a decision with the next free DEC id, `status: proposed` (awaiting your approval).
`file_work_order(title, summary, …)`	Propose a unit of work with the next free WO id, `status: backlog`.
`file_requirement(title, body, …)`	Draft a requirement with the next free REQ id, `status: draft` (awaiting your acceptance).
`file_source(title, body, …)`	File a source document: imported evidence with the paths, commit refs, and excerpts it rests on.
`file_receipt(work_order_id, commit, files, summary)`	Append a work-session receipt to a work order — or to an import manifest as an import's completion signal. Receipts accumulate, never overwrite.
`get_import_instructions()`	The brownfield import instruction package: what to mine from an existing repo, the filing rules, and a census of what the knowledge base already holds.

Where next: the workflow guide for the method these formats carry, or troubleshooting for when a check or connection misbehaves.