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

# commentary Card

# Commentary Cards

A commentary card holds the boxholder's anchored remarks about a **host card**.
It is **attach-only**: it lives in the host's `.attach/` scope
(`<host-basename>.attach/<name>.commentary.card`) and the host's view surfaces
the remarks inline. The host is whatever the commentary annotates:

- an **`extfile`** card — to comment on a live external file (repo docs/source,
  across worktrees). This is the way to review an out-of-box file: make an
  `extfile` pointer, then attach the commentary to it.
- a **`webpage`** card — to comment on a captured page.
- an in-box **`doc`** — to comment on a box document.

A commentary card carries **no target of its own** — no `defaultHref`,
`defaultRef`, or `targets`. The containing host card *is* the target, and bare
`{% source %}` anchors point at it.

## Body — anchor-then-remark

Each comment is a `{% source %}` anchor (the span being commented on) followed
by your remark as ordinary prose:

```
{% source pos="body; heading: Track A (#track-a); ~line 210"
          version="sha256:9f3a1c2b git:7ffeae4" %}the exact span the user selected{% /source %}

This overstates it — placement is composer-only, so it isn't a clean superset.
```

The `{% source %}` **body** holds the selected span, verbatim (escaped to valid
Markdoc — see below). Your comment is the prose *after* the tag, outside it. Do
**not** wrap the span in `{% quote %}`: that tag is reserved for the *user's own
words* (THE LAW OF QUOTING), not a document excerpt you're pointing at.

## Turning a `<user-selection>` into an anchor

When the boxholder selects text in a rendered target and sends it (a
`<user-selection ref|href="…" pos="…">…</user-selection>` in their message),
append a `{% source %}` block:

- **Body** = the selected span, **escaped to valid Markdown/Markdoc** —
  code-wrap `<…>`, escape a stray ` `` `, `{%`, or `%}` so a span that
  contains markup neither breaks the tag nor renders wrong. This is faithful
  rendering of what was shown, not paraphrase.
- Target: leave the anchor **ref-free** — a bare `{% source %}` points at the
  containing host card (the `extfile`/`webpage`/`doc` this commentary is
  attached to). Add an explicit `ref`/`href` only in the rare case the
  selection was against a *different* card. Always write `version` markers
  measured from the file (`sha256:` content hash, plus `git:` when tracked).
- Copy `pos` (and `placement`, if present) from the selection.

Your own framing stays *outside* the tag, as prose. One commentary card per
host.

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