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)

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)

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.