governed frontmatter for agent-readable Markdown

Make Markdown safe for agents.

Frontmattering validates document frontmatter, tethers summaries to exact body bytes, and produces a freshness-aware brief an agent can rely on when it is FRESH — and reject when it is STALE.

Buy commercial license Install from PyPI Agent surface

source-available free personal use 30-day evaluation offline validation

frontmattering brief docs/

$ pip install frontmattering
$ frontmattering init . --set-id MYDOCS --title "My docs"
$ frontmattering new docs/10_GUIDE.md --profile guide --title "My guide"
$ frontmattering tether update --add .
$ frontmattering validate .
VERDICT: GO
$ echo "edit" >> docs/10_GUIDE.md
$ frontmattering brief .
FRESH x1 | STALE x1
summary_trust: do_not_rely_without_reading_body

what gets added

You keep your Markdown. This governs the frontmatter.

Not a generic frontmatter parser — a governance and freshness layer for Markdown corpora. Bodies are untouched, byte for byte; the governed block sits above them.

governed Markdown

---
ai_document_contract:
  schema_version: frontmattering_fm/v0_1_5
  document_id: PYTHON-TO-RUST-ENGINE
  document_role: authoring_guide
routing:
  agent_summary: Build a tested engine first.
  load_order: 20
  read_when_tags: [engine, implementation]
body_tether:
  schema_version: frontmattering_body_tether/v1
  body_sha256: "9b41…"
  tethered_fields_sha256: "c07d…"
---
# Engine implementation
…your Markdown, unchanged…

trust states

Three words, strictly defined.

FRESH

Body bytes and trust-bearing frontmatter fields match the declared digests.

summary_trust=fresh_tether_declared

STALE

Something drifted since the tether was declared. The brief marks it where an agent would have trusted it.

summary_trust=do_not_rely_without_reading_body

UNTETHERED

No tether declared. Fine for orientation, but blocking under the strict trust profile.

summary_trust=orientation_only

workflow

Five operations. No schema reading.

The validator is the tutorial: every finding names the field, the line, and the fix.

init

Create the project — one closed schema, no fallbacks, no permissive mode.

new / promote

Create governed docs or govern Markdown you already have while preserving body bytes.

tether update

Digest exact body bytes and trust fields. Drift becomes a finding, not a surprise.

validate / brief

Emit GO or VIOLATED and a compact brief with inline freshness state.

claim boundary

What the tether verifies

The frontmatter was bound to exact body bytes.
The body has, or has not, changed since.
Trust-bearing fields cannot change without re-declaration.
The validate-only runtime can be parity-swept against the kernel.

What it never verifies

That the summary is semantically true.
That the author wrote a good summary.
That a human reviewed anything.
That your project is release-ready.