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, via} for the attached image file. via says how the image came into the box:
  • channel — camera-user, camera-environment, gallery, import, screenshot, download, scan, or generated.
  • at — 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.
  • original (optional) — the date of the original, when it is known and differs from at: a scanned 1970s photo gets original: "1974" (YYYY, YYYY-MM, or YYYY-MM-DD).
  • note (optional) — how or why it was acquired, in prose.
• 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 (filename.via.channel: generated), use model: {modelId}\nprompt: {prompt text}.
• text: — array of {surface?, content} entries with transcribed text content from the image, if any. surface 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.via.at.
• 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 (evidence, not ISO dates); a card that records a normalized date uses a date entry.
• 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".
• unusable: true — set when the image is not useful (accidental capture, too blurry). The capture's timeline leaves it out.

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. For an image dropped by bbx scan-import, analysis already ran (Gemini) at import time — treat those fields as authoritative unless something looks wrong. An image with no description: has not been analyzed yet.

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.