Publishing and discovery

A machine should find the representation before it starts guessing.

An ESFI standard is published as a contract that people can read and implementations can produce. The specification is the authoritative description of that contract; the machine-readable artifacts show it in use. This page describes what an MPF publisher puts online, how a machine finds it, and what each mechanism does and does not establish.

Every mechanism is marked Specification 0.7, Reference implementation or ESFI practice. The markers are explained in the Overview.

What a publisher puts online

Artifact	Audience	Role	Status
Specification page	People, implementers	The published contract for a format version	Specification 0.7
Page `.mpf` file	Machines	Machine representation of one human page	Specification 0.7
`llms.mpf`	Machines	MPF index of all indexed pages on the site	Specification 0.7
`llms.txt`	Machines, people	Lightweight entry point with an MPF section	Specification 0.7
`llms-full.txt`	Machines	Bodies of indexed pages in the default language, concatenated	Specification 0.7
`.sig` files	Machines	Signatures of MPF files, when the publisher signs	Specification 0.7
`/.well-known/mpf`	Machines	Site-level MPF declaration over HTTPS	ESFI practice
DNS TXT `_mpf.<domain>`	Machines	Site-level MPF declaration before any HTTP request	ESFI practice
`<link rel="alternate">`	Machines	Page-level pointer from HTML to its companion	ESFI practice

How a machine finds MPF

The mechanisms are layered from the cheapest signal to the most specific. A reader can start at any of them; they are designed to agree.

1. DNS TXT — before the first request

ESFI practice

A reader can learn that a domain publishes MPF, where its index lives and what its site-level scope is, with a single DNS query:

_mpf.example.org  TXT  "v=0.7;index=https://example.org/llms.mpf;scope=cite:1,summarize:1,train:0,index:1,relay:0;contact=mailto:web@example.org"

Parameter	Meaning
`v`	MPF version
`index`	Absolute URL of `llms.mpf`
`scope`	Site-level default `companion-scope`, as `flag:1` or `flag:0`
`contact`	Contact for machine readers

The record is short enough to fit in a single DNS response. The builder does not create it; the publisher adds it to the zone.

2. `/.well-known/mpf` — the same declaration over HTTPS

ESFI practice

The same string, served as plain text:

GET /.well-known/mpf
v=0.7;index=https://example.org/llms.mpf;scope=cite:1,summarize:1,train:0,index:1,relay:0;contact=mailto:web@example.org

Ship it as a static file (for example in public/.well-known/mpf) and make sure the server returns it as text/plain. The builder does not create it. mpf is not yet a registered well-known URI; ESFI uses the path as a convention.

3. `llms.txt` — the conventional entry point

Specification 0.7

The builder creates llms.txt if it does not exist, or replaces its MPF section while preserving everything else. The section always contains:

MPF: 0.7
MPF-spec: https://docs.esfi.eu/spec/mpf/0.7
MPF-index: /llms.mpf

## Pages
- [Page title](https://example.org/page/index.mpf): summary

MPF-spec appears when spec-url is configured, and lets a reader reach the canonical specification for the declared version without guessing. The introductory sentence the builder writes above these lines is Reference implementation wording.

4. `llms.mpf` — the site index

Specification 0.7

llms.mpf is itself an MPF document. Its body lists every page with index: true, sorted by MPF URL, each with its summary where one exists. Its frontmatter declares a fixed identity (<prefix>:page:llms), content-type: reference, and hidden, non-HTML parity, because it has no human page behind it.

5. The page itself

Specification 0.7 for the path and mpf-url; ESFI practice for the alternate link.

Every page carries its companion at the same path, with .mpf in place of .html:

/about/index.html   →   /about/index.mpf

Each MPF file is self-addressing through mpf-url, and points back to its human page through url.

An HTML page can also point to its companion from its <head>:

<link rel="alternate" type="text/mpf" href="/about/index.mpf" title="Machine Page Format">

text/mpf is not a registered media type; ESFI uses it as a convention so readers can recognise the link. The builder does not add the link; the site template does.

When site and page disagree

The DNS record and /.well-known/mpf state site-level defaults. A page’s frontmatter states what applies to that page, including any per-page override. ESFI practice: on ESFI sites all three state the same site-level values, and a reader should treat the page frontmatter as the declaration for that page. If a site-level declaration and a page disagree without an override explaining why, that is a publishing error, not a signal to choose between them.

Human canonical and machine companion

The human page and its MPF file are two representations of related content, not interchangeable authorities.

url identifies the canonical human page.
mpf-url identifies the machine representation.
content-parity states how the two relate.
source-hash identifies the exact HTML used to generate the MPF file.
mpf-id identifies the generated MPF file itself.

This separation lets a machine cite or process the machine representation without losing the address of the human source. For translations, language-variants lists the expected MPF addresses of the same logical content in other configured languages; the builder generates these addresses and does not check that the files exist.

Open format, ESFI reference practice

MPF is an open format. Anyone can produce and consume conforming MPF without being listed anywhere, without registering, and without using any ESFI service.

ESFI’s own sites are an inspectable reference practice: they emit MPF, publish the site indexes and the practice-level discovery declarations, and expose all of it for checking against the specification. The Implementation registry records emitters whose output has been verified. It is evidence of implementation, not permission to implement.

Specification, implementation and practice

The specification is the canonical human-readable contract for a published version. A published version remains reachable; corrections that do not change the contract are handled under the Versioning policy.
The reference implementation turns the specification into observable output. It is not a second specification. Where prose and implementation disagree for a published version, they are brought back into agreement; readers are not asked to infer a third contract from examples.
Practice is how ESFI deploys MPF beyond what the builder produces. It is documented so others can reproduce it. It becomes part of the contract only through a new specification version.

A draft, proposal or planned mechanism is not part of these conventions until it is published and verifiable.

What publication does not imply

Publishing a field or a declaration does not create a service behind it. Provenance, confidence, scope and language variants are descriptive unless the specification defines further behaviour. Discovery mechanisms help a reader find the publisher’s declarations; they do not make those declarations true, binding or enforced.

The specification defines the contract; the reference implementation demonstrates it; practice extends how it is found; published artifacts make all three inspectable.