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

# record Card

# Record Cards

Records are generic extracted units — discrete things pulled from
capture sessions or other sources. A record might be a home inventory
item, an archived document, a recipe, a contact, or any other
identifiable thing.

## Frontmatter fields

- `name:` — Always present. A short identifying label for this
  record (e.g., "Brown Leather Couch", "Grandma's Cookie Recipe",
  "2019 Tax Return").
- `description:` — About the thing — context, what it is, its
  condition, why it matters. This describes the record; it doesn't
  contain the content itself.
- `sources:` — Array of `{ref | href, time?, note?}` pointing at where this
  record was extracted from — usually a capture-session card elsewhere
  in the box, so a box-root-absolute `ref` (leading `/`) reads clearest
  here. The optional `time` pinpoints a moment in a transcript; the
  `note` explains why this source is relevant.
- `dates:` — Array of `{value, note?}`. Parseable date strings
  with context ("Year purchased", "Date of letter").
- `persons:` — Array of `{name, ref?, role?, notes?, note?}`.
  People relevant to this record. `role` is the person's role in
  this record (e.g. "Sender", "Recipient", "Manager"); `notes` or
  `note` is freeform context.
- `location:` — `{text?, ref?}`. Where the thing is, was, or
  relates to.
- `quantity:` — `{value, note?}` (a single value, not a list). **How
  much or how many of it there is** — the answer to "how many do I
  have": `"3 items"`, `"roughly 15–20"`, `"10 ounces"`, `"4 sticks"`.
  Natural language with number and unit together. Whenever you know a
  count or amount, put it here, not in prose — a count in
  `description:` can't be summed, sorted, or updated as a field edit.
- `measurements:` — Array of `{value, note?}`. Facts about the thing
  itself — how big, how heavy, what it cost: `"2 pages"`, `"7 feet"`,
  `"45 pounds"`, `"1200 USD"`. Same natural-language shape. The line
  between the two: `quantity` is how much you *have*; `measurements`
  describe the thing. ("10 ounces" of flour on hand is a quantity; the
  ladder weighing "45 pounds" is a measurement.)
- `language:` — Only include when notable.
- `triage:` — Only used when a triage procedure is active.
- `notes:` — Anything that doesn't fit elsewhere — observations,
  caveats, follow-up items.

## Body (markdown)

The actual textual content of the record — a document body, recipe
instructions, letter text, etc. Empty when the record represents
something with no textual content.

## Guidelines

Use only fields that are appropriate for the domain. A home inventory
item needs `location` and `quantity` but probably no body. A
document archive entry needs a body and `dates` but maybe no
`measurements`.

Status lifecycle:
- `draft` — Freshly extracted, may need human review.
- `reviewed` — Human has verified the record is accurate.
- `archived` — Record is finalized and stored long-term.

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

## Templates

### record

A record card — generic extracted unit from capture sessions

```bash
bbx create <path>.record.card -t record
```

Template: record
Description: A record card — generic extracted unit from capture sessions
Card types: record

Arguments:
  name: Short identifying label for the record
  description (optional): Description of the thing