Bee Box documentation · directory: https://beebox.run/docs/reference/cards/ · index: https://beebox.run/docs/reference/cards/index.md · root: https://beebox.run/llms.txt

# 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.