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.

The person reads the briefing as their own page, and agents read it as the person talking to them, so write it in the person's voice: "I'm cataloguing my tools", never "the user" or "the boxholder".

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.

Chat openers live on the place's landmark (navigation.openers), not on the briefing.

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.

When the purpose is still the stock stub (What this box is for.) and the person tells you what the box is for (a new box asks them in its first chat), write their answer into the purpose: frontmatter field.

When you record the box's purpose, also edit the root landmark, _content/Box.landmark.card: remove its stock onboarding opener ("Tell me about talking instead of typing.") from navigation.openers or replace them with openers for that purpose, and write its place summary (the body, the text the person sees first on the Box page): two or three sentences in the person's words about what this box is for and what is in it; keep any sentence they wrote.

Purpose — the purpose: frontmatter field: one sentence or a short paragraph saying 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.

Corrections — a ## Corrections section in the body, one bullet per instruction that overrides default agent behaviour, added in response to an observed mistake. When there is a way to check that the correction is being followed, say so in the same bullet.

## Corrections

- Read an item through before archiving it. Check: no archive commit
  touches a card the session never opened.

For prose sections like "Legal" or "Finances", 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/doc 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: