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.