Bee Box documentation · directory: https://beebox.run/docs/reference/ · index: https://beebox.run/docs/reference/index.md · root: https://beebox.run/llms.txt

# Prominence

`prominence:` says who the card is for, and whether the box puts it in front of
a reader who is looking around rather than looking for it. When to write one
at all is in the agent guide's ABOUT_CARDS; this doc is the three written
values and how they meet landmarks.

## The three written values

- `entry-point` — *where a reader starts.* A card whose main job is to
  orient a reader to this directory or area and send them onward: an index,
  an overview, a dashboard, a roster, a gallery, a collection view. Not a
  card that is merely important; a recipe is never an entry point, the
  recipe index is. A landmark card is not one either: it marks a place, and
  the place's entry point is a visitable card inside it. Ask: *would a
  newcomer open this first to understand what is here?* Usually one per
  directory.
- `primary` — *the thing itself.* The card a reader came to this directory
  for, as opposed to material toward it or about it: a project's plan is
  primary; its research notes, quotes, drafts, and call logs are not. Not
  "because it is good" but "because it is the thing." Ask: *is this the
  thing itself, or material toward it?* One piece of work produces one
  primary card. If everything here is the thing (forty recipes), mark
  nothing and give the directory an entry point instead; the one or two the
  boxholder has singled out (the bread they bake every week) are the
  exception and are `primary`.
- `background` — *for you, not the reader.* Material you use but did not
  write for the boxholder to look at: logs, state, imports, scratch,
  generated intermediates, and anything already embedded in another card
  (an image that appears inside a primary document is background on its
  own; the document is where a reader sees it). Cards the box writes for
  itself (jobs, runs, chat threads and chat logs, capture and upload
  staging) and landmark cards are background by type. On a landmark card, `prominence: background` is the one value to
  write: it marks the whole place as housekeeping and folds everything
  under it. Never write `entry-point` or `primary` on a landmark.

## Prominence, status, and landmark links

`prominence` is not `status`: `status` is lifecycle, `prominence` is who
the card is for. `bbx validate` warns at a third entry point or an eighth
primary card in one directory. To surface a card in a place that is not
its own directory, or with a contextual label or a fixed position, use
that place's landmark `links:` — the card cannot say that about itself.
`bbx ls --format "{prominence} {title}" <dir>` shows what a directory has
declared.