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

# landmark Card

# Landmark Cards

A landmark marks a directory as a notable spot in the box — a hand-curated bookmark that can also be a triage destination. One per directory; the file lives inside the directory it describes, e.g. `_content/recipes/Recipes.landmark.card`. Directories without a landmark are invisible to the Landmarks page and to triage.

A landmark is pure YAML frontmatter (no body) with one or more roles. At least one role should be present.

An optional top-level `system-theme` selects the app chrome while this landmark is active. Use only the theme and stock identifiers documented in `node_modules/beebox/box-docs/card-themes.md`.

## `navigation` (human-facing surface)

```yaml
symbol:                     # the card's mark — every card may carry one
  glyph: 🍳                 # emoji or a letter or two; OR src: /_content/recipes/images/portrait.webp for an image
navigation:
  label: Recipes            # short bookmark name; treat like a tab name, not a sentence
  links:                    # optional curated links to other cards
    - ref: /_content/recipes/Bread.recipe.card  # box path (leading /); validated
      label: the bread        # optional; falls back to the target's filename title
  expand:                   # optional templated fan-out
    - query: "*.recipe.card"  # glob, like bbx ls
      order: modified-desc    # alphabetical (default) | modified-desc | modified-asc
    - query: "**/*.image.card"
      group: Images           # optional: render matches as a collapsible submenu titled "Images"
  chat-app:                 # optional chat-feature seed for chats opened here
    narration: "on"
    prose: "off"
```

An older landmark may carry its mark nested as `navigation.symbol` (a bare string, or `{ src }`) — the shape before the mark became a field every card can have. That form is still read, so a card written that way is not a mistake and does not need fixing by hand; the `landmark-symbol` migration moves it. Write new marks at the top level, as above.

`ref` and `symbol.src` are **box paths — write them with a leading `/`, from the box root**. A path relative to the landmark's directory still resolves (older landmarks are written that way), but new ones use the box path. `expand` `query` globs are the exception: they are queries, not refs, and always run relative to the landmark's directory.

In an `expand`, `template-ref` / `template-label` are placeholder strings substituted per match: `${path}` is the matched card's path relative to the landmark's directory, any other `${field}` reads that field from the matched card's frontmatter. When omitted, `template-ref` defaults to the match's box path. (`template-ref` is a `${…}` substitution *pattern*, not a card ref — it is not stored under a `ref` key.)

Add `group: <title>` to an `expand` to keep its matches grouped as a **collapsible submenu** instead of flattening them into the flat link list. Collapsed, the group shows its title and a child count; expanded, it reveals the matched links. Use this for "all the X" globs (e.g. `group: Images` over `**/*.image.card`) that would otherwise flood the flat list. An expand without `group` flattens inline as before. Group children dedup within the group only — they are independent of the flat list and of other groups.

**Don't add a description or purpose field.** A bookmark seen many times shouldn't carry a paragraph explaining itself. If a landmark genuinely needs prose, write a doc card and link to it.

## `destinations` (agent-facing filing targets)

```yaml
destinations:
  - for: [triage]           # kinds: triage, commentary, and/or share
    rules: "Recipes — anything describing how to cook a dish."  # read by the triage agent
    procedure:                # handler run at the handle stage; a card ref ({ ref: <box path> })
      ref: /_config/procedures/archive-recipe.procedure.card
  - for: [commentary]       # a commentary-only spot needs neither rules nor procedure
  - for: [share]            # appears under "Save in" in the native iOS share sheet
```

A pure routing target (an archive humans don't browse) can have only `destinations`; a pure bookmark can have only `navigation`.

**Dedup**: a card appearing in both a hand-listed `links` entry and an `expand` result shows once — hand-listed links come first.

## Derived links, and `prominence`

Most of a landmark's list is **derived**, not listed: every card under its directory carrying `prominence: entry-point` or `prominence: primary` appears automatically (entry points first, then primary cards, then nested landmarks, then `expand` results), and the walk stops at any subdirectory with its own landmark. So the way to surface a card in its own place is to mark the card, not to edit the landmark. `links:` is for what a card cannot say about itself: a target outside this directory, a contextual label, or a fixed position. A `links:` entry that duplicates a marked in-directory card is harmless (it shows once, listed first) and `bbx validate` notes it as a trim candidate.

A landmark card is a place marker, not a visitable file — it is `background` by type and never needs `prominence` written to be on the Landmarks page. The one value that means something on a landmark is `prominence: background`: the place is housekeeping (logs, imports, machinery), it leaves the Landmarks page and the place menu, and everything under it folds in Browse. `entry-point` or `primary` on a landmark is a lint warning; the place's entry point is a visitable card inside it.