Metadata-Version: 2.4
Name: frontmattering
Version: 0.5.2
Summary: Governed frontmatter, freshness tethers, and validate-only runtime gates for agent-facing Markdown
Author: Lasse T.
License-Expression: LicenseRef-FRONTMATTERING-Individual-Use-1.2
Project-URL: Homepage, https://frontmattering.com
Project-URL: Repository, https://github.com/frontmattering/frontmattering
Project-URL: Issues, https://github.com/frontmattering/frontmattering/issues
Project-URL: Commercial, https://github.com/frontmattering/frontmattering/blob/main/COMMERCIAL_LICENSE_REQUIRED.md
Project-URL: License, https://github.com/frontmattering/frontmattering/blob/main/LICENSE.md
Keywords: markdown,frontmatter,documentation,governance,ai-agents,validation
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
License-File: COMMERCIAL_LICENSE_REQUIRED.md
License-File: NOTICE
License-File: THIRD_PARTY_NOTICES.md
License-File: TRADEMARKS.md
Requires-Dist: PyYAML>=6.0
Requires-Dist: markdown-it-py>=4.0.0
Provides-Extra: markdown-plugins
Requires-Dist: mdit-py-plugins>=0.4.0; extra == "markdown-plugins"
Dynamic: license-file

# Frontmattering

Frontmattering makes Markdown safer for agents.

It adds governed frontmatter, task routing, body/frontmatter freshness tethers, and a vendorable validate-only runtime gate so an agent can consume a compact brief without silently relying on stale documentation.

## Install

```bash
python -m pip install frontmattering
frontmattering --version
frontmattering doctor
```

## First-hour path

`frontmattering init .` scaffolds a starter router under `docs/`, and `frontmattering new` creates governed documents. This block runs verbatim in an empty directory (it is executed as a release gate in CI):

```bash
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 .
frontmattering brief .
```

Already have Markdown under `docs/`? Add governance to a file you already have with `promote` (one file per call):

```bash
frontmattering promote docs/YOUR_GUIDE.md --profile guide --in-place
```

Promoting a file outside the selected corpus fails before the file is touched (`FRONTMATTERING-AUTHORING-TARGET-OUTSIDE-CORPUS`).

For strict freshness enforcement, set `validation_profile: trust` in `.frontmattering/project.yaml`, then re-run `frontmattering validate .` and `frontmattering brief .`.

## Runtime gate

```bash
frontmattering runtime pack --out frontmattering-runtime.pyz
python frontmattering-runtime.pyz validate docs --format json
```

The runtime artifact is validate-only. It does not expose init, promote, new, index, tether update, or authoring surfaces.

## Prompt pack

The validator proves your frontmatter is valid, current, scoped, and tethered. It does not prove the frontmatter is *good* — a GO document can still carry a copied summary or a generic deepest intention. The governed prompt pack closes that gap: it makes authoring excellent, body-grounded frontmatter repeatable.

```bash
frontmattering prompt list
frontmattering prompt inspect author-category-frontmatter
frontmattering prompt render \
  --task author-category-frontmatter \
  --category self_protection_layer \
  --support-profile frontmattering_only \
  --corpus-root docs \
  --output rendered_prompt.md --receipt-out render_receipt.yaml
```

`prompt render` is deterministic: it composes the prompt from a packaged task template, a structured category profile, a support profile, and shared fragments, and binds the rendered bytes to every input's digest — including the authorizing manifest, renderer source, distribution, and serializer identity. **The core CLI never executes an LLM** — a rendered prompt proves only that the bytes were deterministically composed, not that a model ran or that an authoring result is semantically correct.

Run `frontmattering prompt verify` (also a `doctor` step) to confirm the packaged pack renders cleanly, reproduces its worked example, and conforms to its own shipped JSON schemas. Run `frontmattering prompt verify-rendered --prompt rendered_prompt.md --receipt render_receipt.yaml --request render_request.yaml` to verify a rendered prompt: it re-renders the canonical prompt from the request against the installed pack and compares byte-for-byte, rejecting a non-canonical or re-sealed prompt (`FRONTMATTERING-PROMPT-NOT-CANONICAL`) and any unauthorized task/category/profile.

This establishes **reproducibility** — the prompt is the canonical render of that request on this installed pack. It is not, on its own, **provenance** that the request was authorized: a producer who controls the request and re-renders honestly produces a valid prompt. Hostile-producer provenance requires signing the request/receipt under an independent authority (tracked as deferred in `docs/DEFERRED_ITEMS_LEDGER.md`).

## License

Frontmattering is source-available. It is free for individual personal use within the scope of `LICENSE.md`. Professional, organizational, employer, client, CI/CD, hosted, managed-service, platform, consulting, or revenue-connected use is permitted for a 30-day evaluation period under `LICENSE.md`; continued use after the evaluation requires a paid commercial license.

Frontmattering is not open-source software under the Open Source Definition because professional and organizational use is restricted without a commercial license.

Runtime dependency status is recorded in `THIRD_PARTY_NOTICES.md`; project notices are recorded in `NOTICE`.

## Claim boundary

A `FRESH` brief means the current body bytes and canonical trust-bearing frontmatter fields match their mechanical tether. It does not prove semantic summary correctness, human approval, external adoption, or production suitability.

A `STALE` or `UNTETHERED` summary must not be relied on without reading the body.


## Publication status

This v0.5.2 package makes the prompt-evidence layer verify by **canonical re-rendering**: `prompt verify-rendered --request` re-renders the prompt from its request against the installed pack and compares byte-for-byte, so a re-sealed prompt+receipt and unauthorized task/category/profile identities are rejected (0.5.1 compared a prompt only against its own self-authored receipt). Schema enforcement now catches `minItems`/`uniqueItems` and rejects unsupported keywords; the index-ownership guard is exact; and prompt+receipt writes are transactional. It establishes prompt *reproducibility*, not hostile-producer *provenance* (which needs signing). It makes no validator trust-semantics, frontmatter-schema, or canonical-model (`v0.1.5`) changes. Operation-wide mutation transactions, a hermetic runtime, an execution-record verifier, and other items are deliberately deferred and tracked in `docs/DEFERRED_ITEMS_LEDGER.md`. Custom license text should still receive legal review before paid commercial sales.
