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's YAML frontmatter carries one or more roles; at least one should be present. Its markdown body is the place summary.

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"
  openers:                  # optional one-line first moves for a chat here
    - What can I cook tonight?

Openers. navigation.openers are one-line first moves, phrased from the person's side, shown as buttons on an unstarted chat in this place (and on the place's page); clicking one sends it as their message. Each is a single non-blank line of at most 120 characters. A place with no openers shows none; it does not inherit the root's. When you build a place for a recurring job, you may add up to three for its standing first moves ("Log a new loan"). The root landmark's onboarding openers fade as the box is used: remove them once the person knows what the box is for, and in the same edit write its place summary (the body): two or three sentences in the person's words about what the box is for and what is in it. Openers never go on a briefing card.

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; where things stand goes in the place summary.

Place summary (the body)

The place page shows the body first, above the place's cards. It says where things stand, in a few lines, with a link to the card behind each claim: who has what, what is next, what is unfinished. Keep it under about eight lines and don't re-list the cards; they are listed below it. For "where things stand", prefer this body over a separate entry-point doc.

It is for the person. The briefing is guidance for agents; contains: is a search sentence. Write the body when you make a place, and update it in the same turn as any change to the place's cards that makes it untrue.

Keep the person's words: link and quote their cards. A sentence the person wrote stays; ask before removing one.

destinations (agent-facing filing targets)

An optional todo-question asks a yes/no question about each routed item. A yes adds an ordinary agent-assigned todo for the scheduled todo review; omit it for filing only. This does not authorize extra actions or run an agent immediately.

For triage, destination rules explain scope and boundaries; _config/intake.guide.card governs decision policy. To repair a rule and test regressions, read node_modules/beebox/box-docs/triage-instructions.md.

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 stands for its place, not for a file in it — 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.