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:

the exact span the user selected

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.