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, or deleted; right-click a stage to reach those options. Deleting a stage moves its cards to the stage before it; deleting the first stage moves them to the next stage.

How the stages are laid out follows the panel’s width. Give the panel room and it becomes a side-by-side board, one column per stage, showing as many as fit with arrows in the header to page through the rest. Narrow it and the columns collapse to a single stage with a tab strip above it.

How do I move a card between stages?

Three ways, whichever suits what you’re doing:

  • Drag it. On the multi-column board, drag a card straight into another stage’s column. Within one column, drag it up or down to reorder.
  • Use the card’s menu. Each card’s menu lists the stages you can send it to, which is the quickest route when the target stage isn’t on screen.
  • Edit the card. Open it and change its Stage field.

With a card focused, Alt+↑ / Alt+↓ moves it one position within its stage, and keyboard focus carries across columns so you can work the whole board without the mouse. Moving a card into the final stage marks it complete and plays a short confetti flourish.

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. It spans every stage, not just the one you’re looking at, so a match in another stage still surfaces (grouped in stage order). 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.