pdf-frontmatter0.1 · the carrier

i

A convention, not a product

An index card, bound inside the PDF.

When an agent opens a PDF today it reads the entire document just to learn what it is. pdf-frontmatter puts a one-kilobyte YAML card in the file itself. The PDF stays a PDF. It looks the same. The card never gets orphaned when someone forwards it.

Try it on a PDFRead the spec

ii

The race

Same question. Same file.

An 8-page supply agreement. The left desk reads every page. The right desk reads the bound card. Token counts are from the real file, four characters to a token.

“What is the liability cap, and on which page?”

i · as circulated

Naked PDF

Eight pages, no card. An agent has to ingest the lot.

ii · with a preface

Enriched PDF

The same bytes, plus a 1 KB card named agent-frontmatter.yaml.

Press “Ask both desks”. The enriched side answers before the naked side finishes reading.

Estimate, not a billed API call. The ingest is paced so you can watch it; the token numbers are measured from the sample.

iii

How the card is bound

  1. i

    A reserved attachment

    The card is a standard PDF embedded file named agent-frontmatter.yaml. Viewers that list attachments show it. Typical overhead is under a kilobyte.

  2. ii

    Hints, never ground truth

    Title, sections, entities, a short summary. If the hash of the extracted text no longer matches, the card is stale and must be ignored.

  3. iii

    A carrier, not a format

    DocLang is the representation. This is where that representation — or a pointer to it — lives so it cannot be separated from the file that circulates.

For developers

Five lines to read a card

import { readManifest } from "pdf-frontmatter";

const card = await readManifest(bytes);
if (card.manifest) {
  console.log(card.manifest.title);
}
Full quickstart

The open lane

Pro-PDF, on purpose

Sidecars get lost. App intelligence stays behind a subscription. Replacement formats ask the world to change formats. This convention asks for an attachment the PDF spec has supported since 2001.

Complementary to DocLang. The derived key is the bridge.

The archive desk

Make a whole archive self-describing.

A batch API is next: point it at a folder of PDFs, get the same cards back. Leave an email. Nothing else is stored.

Documents bound
—
Tokens not spent
—

Estimate. Four characters to a token.