extfile Card

Extfile Cards

An extfile card is an in-box pointer to a live external file — like a webpage card stands in for a web page, but with no snapshot: no body, no frozen copy, no extracted text. The view fetches the file fresh each render and shows it through the renderer for its type (.md → markdown, .ts/source → plaintext, …).

Frontmatter

• href: — required. The full file: URL of the external file, e.g. file:/Users/you/src/project/src/foo.ts. The path must resolve under one of the box's externalRoots (_config/box.json). Use a single-slash file:/abs form. Untracked by bbx mv (it points outside the box).
• version: / size: / mtime: — stamped metadata; do not hand-edit. version is sha256:<hex> git:<rev>; its sha256 is what drift detection compares against the live file. Stamp them with bbx extfile sync <path> — never edit them by hand, and they are never auto-refreshed (a silent refresh would erase the drift signal that is the whole point).

Body

None. An extfile card is a pointer, not a document — leave the body empty. The live file is the content; if you want a stored copy, use a webpage card instead.

Commentary

Remarks about the file are not in this card. They live in a .commentary.card inside this card's attach scope (<basename>.attach/), and the extfile view surfaces them inline. A bare {% source %} anchor (no ref/href) points at this card's live file — the pointer is the default target.

Layout on disk

_content/reviews/Foo_Source.extfile.card                  # the pointer + stamped metadata
_content/reviews/Foo_Source.attach/Foo_Source.commentary.card   # remarks (optional)

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.