pdf Card

PDF Cards

A pdf card is a document whose text has been extracted — the rendered markdown is the card body, and the original bytes stay attached beside it. It is what bbx scan-import writes for a scanned PDF that already carries a text layer (a scanner's own OCR, or a born-digital PDF).

Where the bytes live

Everything is inside the card's own attach scope, so refs are attach/…:

• attach/source.pdf (or whatever filename.ref names) — the original file, unmodified. Read this when the body is not enough: the exact layout, a signature, a stamp, a scan artifact.
• attach/docling.json.gz (docling.ref) — the canonical extraction: layout, reading order, bounding boxes, table structure. Gzipped JSON. Read it only when you need structure the markdown body dropped (e.g. cell-level table data or where on the page something sits).
• attach/text-layer.txt — the document's raw text layer, verbatim, as the file itself carries it (no layout analysis, no rewriting). Read it when you need the exact characters rather than the rendered body. Absent when the document carries no extractable text.
• attach/page-001.avif, page-002.avif, … — one rendered image per page, in page order. Use these when you want to look at a page.
• attach/figure-001.avif, … — figures/images pulled out of the document. The body references them inline.

Frontmatter

• status — new | analyzed | invalid.
  • analyzed: extraction succeeded. An empty body is a valid analyzed result — it means the document had no readable text, not that something broke.
  • new with an error: field: extraction failed. The original file is still attached and is the only asset; there is no docling JSON, no page renders, and the body is empty. Nothing is lost — re-run extraction with bbx pdf reanalyze <card> (add --force-ocr when the text layer itself is junk), or read the attached original directly, or set status: invalid if the file is unusable.
  • invalid: you judged the document unusable (corrupt, junk, empty scan).
• format — the source document type, e.g. pdf. format: records what the file was, distinct from the card type itself.
• filename — provenance for the original: ref into the attach scope, plus captured, source, and optionally original-name, mime-type, size.
• docling — ref to the gzipped extraction JSON, plus the version of the extractor that produced it.
• metadata — pages, title, author read from the document itself. Any of them may be missing; a scanner rarely sets title/author.
• description — a short summary of what the document is. Deliberately empty at intake; fill it in when you process the card.

Body

The rendered markdown of the document — headings, paragraphs, and tables as markdown tables. Figures appear as inline image references into the attach scope. Treat it as a faithful-but-lossy view: it is the right thing to read, search, and quote, and the original plus the page renders are there when it is not enough.

The contains: field

Give this card a one-sentence contains: — the prime retrieval field for bbx search and listings. How to write a good one (carry the information when it's concise, never a list of parts, under 200 characters) is in the agent guide's ABOUT_CARDS section.