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.

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:

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

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: