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

# todo-view Card

# Todo View Cards

A `todo-view` card IS a todos display surface — not a list you fill in by
hand, but a live query over every `{% todo %}` tag and frontmatter `todos:`
entry the box's collector finds. Its frontmatter fields are the query; the
renderer runs it every time the card is opened.

## Fields

- `glob:` — which cards to scan, relative to the box root (e.g.
  `"_content/projects/kitchen-remodel/**"`). **Omit it** to scope the view to
  this card's own directory subtree — that's the common case for a
  project-local plate. The box-wide instance
  (`_content/plate.todo-view.card`) sets `glob: "**"` explicitly.
- `status:` — restrict to specific statuses (`open`, `done`, `dropped`,
  `parked`). **Omit** to see `open` + `parked` — every plate-state group
  (escalated / on-plate / quiet / parked); `done`/`dropped` stay out of
  the default view. List them explicitly to include them.
- `assigned:` — restrict to todos with a matching `assigned` attribute
  (exact match, e.g. `"agent"`).

## When to create one

Drop a `todo-view` card in a project directory to give that project its own
plate — every todo captured anywhere under that directory shows up there,
subtree-scoped by the omitted-`glob` rule above. Link to it like any other
card (a plain card ref — chat, another card's body, a landmark). Tend these
freely: create one when a directory's todos deserve their own surface,
rename/move it with the directory, delete it when the project's done. There
is exactly one box-wide instance (the stock `_content/plate.todo-view.card`,
"The plate") — everything else is as many project-local instances as are
useful.

## Rendering

Read-only in v1 — no click-to-done. Todos group by plate-state (escalated /
on plate / quiet / parked, per `todo-model.ts`'s truth table), each item
linking to its source card at card granularity (no line-anchored deep links
yet). Cards the collector couldn't read (parse/validate/load failures) show
in their own muted section rather than silently vanishing — the same
"never hide a failure" rule the collector and `bbx todos` follow.

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

## Templates

### todo-view

A todos display surface — the box-wide plate, or a project-local subtree instance

```bash
bbx create <path>.todo-view.card -t todo-view
```

Template: todo-view
Description: A todos display surface — the box-wide plate, or a project-local subtree instance
Card types: todo-view

Arguments:
  title (optional): Display title for the view
  glob (optional): Glob scoping which cards to scan (default: this card's own directory subtree)
  status (array — repeat key or use JSON: key='["a","b"]') (optional): Restrict to specific statuses (default: all)
  assigned (optional): Restrict to todos with this exact `assigned` value