Skip to content
Build Perch
Browse documentation

Lists panel basics

Short answer: The Lists panel is a card-based task board: each list holds cards that move through stages you define, and every card carries a title, notes, priority, category, deadline, flag, and optional attachments. You filter, sort, search, and reorder cards from the same screen, and you can send any list into a chat as context.

What is a list?

A list is a Kanban-style board: cards in columns you call stages. Lists are stored as JSON files in the workspace’s BuildPerch/cards/ folder, so they travel with the workspace the same way your files and chats do. A workspace can hold more than one list. Click the list-name pill at the top of the panel to open the list selector, which shows every list with its active-card count and last-modified time, and lets you create, rename, delete, or archive a list. Archiving hides a list from the Active tab without deleting it; it’s still readable under the Archived tab.

What’s on a card?

Every card has:

  • Title: required, capped at 500 characters.
  • Stage: which column it’s in.
  • Notes: free-form body text.
  • Priority: a number from 1 (critical) to 9 (minimal), color-coded. 1–3 reads as high priority, 4–6 medium, 7–9 low.
  • Category: a colored label (e.g. “Bug”, “Feature”); pick an existing one or create a new one, with its own color, from the same dropdown.
  • Deadline: a date.
  • 🚩 Flag: an on/off “needs attention” marker, independent of stage and priority.
  • Reference URLs: links you attach to the card.
  • Attached files: drag a file onto a card (from the Files panel or elsewhere) to attach it; the card shows its name.

Click a card to open the full editor for any of these fields, or press F2 on a selected card to rename its title inline without opening the editor.

How do stages work?

Every new list starts with three stages (To Do, In Progress, Done) and you can rename any of them. The last stage is pinned: it can’t be deleted (cards routed there are treated as the list’s completed cards and get a date-grouped view), but you can still rename it. Every other stage, including the first, can be added, renamed, reordered by dragging its tab, or deleted. Deleting a stage moves its cards to the stage before it; deleting the first stage moves them to the next stage. An All tab above the stage row shows every card regardless of stage.

Drag a card between stages, or between positions in the same stage, to reorder it. With a card focused, Alt+↑ / Alt+↓ moves it one position up or down within its stage. There’s no shortcut for moving a card to a different stage; change its Stage field in the card editor instead.

How do I filter, sort, and search cards?

The toolbar above the card list gives you:

  • Categories ▾: filter by category; the same popup has a ”+ New Category” row to add one, and right-clicking a category there lets you recolor, rename, or delete it.
  • Flagged-only: show only flagged cards; stacks with the category filter.
  • Sort ▾: sort the cards in the current stage.
  • 🔍 Search: a live keyword search over titles and notes; a “Searching: …” chip stays visible near the card list so it’s clear why the list looks short, with a one-click clear.
  • Expand/collapse all: toggle every card’s notes open or closed at once instead of expanding them one by one.

Large lists stay responsive: the panel only renders the cards currently in view.

Good to know

  • List and card data lives entirely in the workspace’s BuildPerch/cards/ folder as plain JSON; nothing is sent anywhere just by having a list open.
  • The Send List to Chat button (bottom of the panel) attaches a formatted, stage-grouped snapshot of the current list to your next chat message as context; see The AI working your board.
  • A card’s flag and its priority are separate concepts: flagging is a quick “look at this” marker you toggle per card, while priority is the 1–9 scale used for sorting.