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

# briefing Card

# Briefing Cards

A briefing card captures the core situational context for a box (or a
directory within a box). It's the primary place for information that
every agent needs to know.

One briefing per directory, at `briefing.briefing.card`. The root
briefing describes the whole box. Directory briefings explain what
that directory contains.

A briefing has two parts: **structured records in frontmatter** and a
**prose body**.

**Frontmatter records:**

- `key-people:` — a list of the people central to the box's purpose.
  Each entry is `{ref?, called?, role?, notes?}`. `ref` points at the
  person card (auto-tracked by `bbx validate` and `bbx mv`); `called`
  is the alias the boxholder uses; `role` describes the relationship;
  `notes` is a free-form description.
- `properties:` — a list of physical properties tied to the box
  (ledger, household, business). Each entry is
  `{name?, address?, address-uncertain?, notes?}`; set
  `address-uncertain: true` if the address isn't confirmed.
- `openers:` — a list of plain strings: the suggested opening
  questions shown on an empty chat for this directory. Each must be a
  single non-blank line of at most 120 characters — a longer or
  multi-line entry fails validation. See "Openers" below.

```yaml
key-people:
  - ref: /people/Dana_Lee.person.card
    called: Dad
    role: Ledger subject
    notes: Primary account holder; defer to the sibling group on decisions.
properties:
  - name: The lake house
    address: 12 Shore Rd
    notes: In probate; taxes paid through 2026.
openers:
  - Let me tell you what this box is for.
  - What can you do?
```

**Openers are yours to maintain.** Each string in `openers:` is a
suggestion the person sees on an empty chat bound to this directory —
clicking one sends it as their message. A new box ships with two stock
openers; they are a starting point, not a fixture.

- Rewrite them as the box's use becomes clear, toward things the
  person has **not** yet tried.
- Phrase them from the person's side, so you are never asked something
  you cannot answer yet.
- Keep them short — one line each, 120 characters at most.
- Remove them once the box is in regular use. **An empty set is the
  normal end state, not a regression** — an established box shows no
  openers at all.

When the purpose is still the stock stub (`What this box is for.`)
and the person opens with "let me tell you what this box is for", ask
them, then write their answer into `{% purpose %}`.

**Body tags** (free-text material; use as block tags):

- `{% purpose %}` — what this box (or directory) is for. Required at
  the box root; optional in directory briefings if the directory
  doesn't need its own purpose statement.
- `{% correction %}` — an instruction that overrides default agent
  behaviour, added in response to an observed mistake. Optional
  `test` attribute describing how to verify the correction is being
  followed.

For prose sections like "Legal" or "Finances" (which were always
free-form anyway), use plain markdown headings:

```markdown
## Legal

The ledger is in probate. Settled creditors include...
```

**When to edit a briefing:**

- You learn something that changes how any agent should understand
  this box.
- A new key person is identified: add a `key-people:` entry and create
  the person card (`people/First_Last.person.card`).
- An agent repeatedly makes a mistake that a correction would
  prevent.

**Do NOT put here:**

- Individual items (those are record/memo cards).
- Processing rules (those go in guide cards).
- Communication style preferences (those go in the personality card).

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

### briefing

A briefing card — core situational context for a box or directory

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

Template: briefing
Description: A briefing card — core situational context for a box or directory
Card types: briefing

Arguments: