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

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