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

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