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

# file Card

# File Cards

A file card represents an arbitrary file uploaded via the capture UI
(e.g. a PDF, text document, spreadsheet, archive).

Frontmatter:
- `filename:` — the attached file as a `{ref, captured, source, ...}`
  object. `ref:` is the path into the card's attach scope
  (e.g. `attach/{storedName}`). `captured:` is the upload timestamp,
  `source:` the origin (e.g. `disk`). Optional siblings:
  `original-name` (filename as uploaded), `mime-type` (browser-reported
  MIME), `size` (bytes).
- `description:` — short summary of what the file contains, filled in
  during processing. Doubles as the `contains:` fallback for search;
  set an explicit `contains:` only when it should differ.

Unlike image/audio cards, no built-in pipeline processes files yet —
they land in the capture session and are available for agent handling
(extraction into records, archival, etc.). Processors should set
`status: processed` when done, or `status: invalid` if the file
cannot be used.

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