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

# image Card

# Image Cards

An image card represents a photo, typically from a capture session.
The image file itself lives in the card's attach scope, pointed to by
`filename.ref:` (attach scope: see ABOUT_CARDS).

Frontmatter fields:
- `filename:` — `{ref, captured, source}` for the attached image
  file. `captured` is the acquisition timestamp supplied by the
  capture/upload/import flow (for example, camera shutter time,
  gallery selection time, or import-session start). It is not
  derived from EXIF.
- `description:` — one sentence describing what the image *looks
  like* (filled during analysis) — the visual field, used as alt text.
- `contains:` — one sentence stating what someone could *learn* from
  this image — the retrieval field (also filled during analysis; when
  absent, search falls back to `description`). Carry the fact when
  it's concise ("Boiler serial number K-44210"), don't point at it.
- `creation:` — optional free-text notes on how the image came to
  be. Only include when there's something worth recording. For
  AI-generated images (`source: generated`), use `model: {modelId}\nprompt: {prompt text}`.
- `text:` — array of `{source?, content}` entries with transcribed
  text content from the image, if any. `source` describes what the
  text is on ("whiteboard", "business card", "printed page",
  "screen").
- `exif:` — EXIF metadata extracted from the image file. Put the
  camera's original photographic timestamp in `exif.date` when
  available; it may differ from `filename.captured`.
- `subject-bbox:` — bounding box of the main subject on a 0-1000
  scale (`{y1, x1, y2, x2}`). Present when the subject doesn't fill
  the entire frame.
- `document:` — present when the image is a photograph of a document
  (bill, letter, form, receipt, statement, …). `kind` is a short
  free-text category ("utility bill", "lab results"), `from` is the
  issuer/sender, `dates` is an array of `{label, value}` entries.
  Date values are kept as they appear in the document; normalization
  happens downstream.
- `has-text` — true if the image contains readable text, false
  otherwise. Always true when a `document:` field is present.
- `rotation` — degrees clockwise the image needs to be rotated to
  appear upright: `"0"`, `"90"`, `"180"`, or `"270"`.

For an image that arrived as part of a capture, analysis is your
job: OCR any text and write a description via a subagent that reads
the actual image file (don't infer content from the transcript
alone), then fill in the fields above and set `status: analyzed`.
For an image dropped by `bbx scan-import`, analysis already ran
(Gemini) at import time — treat those fields as authoritative unless
something looks wrong.

Status: new (unanalyzed) → analyzed (description filled in) → invalid
(accidental capture, too blurry, not useful).

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