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

# doc Card

# Doc Cards

A doc card is a generic typed document with a title and a markdown body.

**Use `.doc.card` instead of `.md` by default.** Plain markdown files
are still allowed for things like READMEs, generated docs, or
attachments, but a fresh document an agent creates for design notes,
plans, reference material, scratch work, or any prose worth keeping
should be a doc card. The card form gives the document a title field
separate from the filename, lets it participate in card-wide tooling
(`bbx validate`, the file browser, refs), and keeps the box's content
typed.

## Frontmatter

- `title:` — required, free-form. The display title; can differ from
  the filename.

## Body

The doc's body lives **inline in the .doc.card file itself**, after
the closing `---` of the frontmatter. Plain markdown. Headings,
lists, code blocks, links, etc. — anything markdown supports. Don't
put the body in a separate `.md` file beside the card; the card *is*
the document.

A minimal doc card on disk:

```
---
title: Trip Report
---
# Trip Report

We drove down on Friday...
```

References to other cards use the standard ref form (frontmatter
`{ref: "..."}` or inline markdown links to card paths).

## Embedding images and other files

Files the doc references — images, attachments, supporting media — go
in the card's attach scope (`<basename>.attach/`), referenced from the
body as `attach/<filename>` — see the agent guide's ABOUT_CARDS.
Never a top-level or shared `images/` directory.

## When NOT to use a doc card

- A synced Google Doc — use `.gdoc.card` (managed by the drive
  connector).
- A captured note or voice memo — use `.memo.card`.
- A structured record extracted from something — use `.record.card`.
- An ad-hoc README that lives next to code/config rather than being
  content in its own right — plain `.md` is fine.

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

### doc

A generic typed document — use instead of .md when an agent creates a new document

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

Template: doc
Description: A generic typed document — use instead of .md when an agent creates a new document
Card types: doc

Arguments:
  title: Display title for the document
  body (optional): Initial markdown body content