Card
A card is a folder named with a lowercase UUID inside a lane folder, and the card itself is the index.md inside it. The body of that file is the card’s content. Attachments and comments live in folders next to it.
---schema: 1kind: cardtitle: "Fix: logo is blurry on retina screens"order: 3072icon: {glyph: ladybug}labels: - {text: bug, kind: {type: text, text: Text, icon: {glyph: tag}}}due: 2026-08-25hero: 3f2a8c14-7d6e-4b90-a1c2-5e8f9b0d1a23created: {at: 2026-07-24T18:00:00Z, by: {name: claude, kind: agent, model: opus-5}}modified: {at: 2026-07-24T18:00:00Z, by: {name: claude, kind: agent, model: opus-5}}---
The header logo looks soft on high-density displays.
Steps to reproduce: open the home page on a retina Mac.| Key | Type | Description |
|---|---|---|
schema | integer | Always 1. Optional in a card; a missing value is read as 1. |
title | text, one line | The card's display name. Put quotes around a title that contains a colon. |
kind | text | Write card. The app adds it when the card is created. |
created | stamp | A stamp recording when the card was created and by whom. |
modified | stamp | A stamp recording the last time the app rewrote this file's content and who did it. Moving a card to another lane updates it; reordering within a lane does not. |
icon | icon | The card's SF Symbol and its tint, as {glyph, color}. |
order | number | A number ranking the card within its lane, lowest first, top to bottom. Decimals are fine. A card without a usable order goes to the bottom. |
background | background | The card's background colour, written as {color: …}. It is drawn as a stripe down the card's left side. |
labels | list of labels | The card's labels, a list of self-contained entries shown as chips on the card. Each entry carries its own text and kind, and optionally rank, color and icon. |
due | timestamp | The card's due date. A bare date such as 2026-08-25 means that day wherever the reader is. A full timestamp is read as the day it falls on locally. |
hero | text | The uuid of one of the card's own attachments, drawn as a banner across the top of the card. It is an identity, never a path: a value containing / draws nothing. |
waiting | waiting | Marks the card as blocked until a human replies, written as {for, since, comment}. An agent sets it; the app removes it once a human comments later than since or replies to the comment. |
start | timestamp | Not read by the app yet. A start date in the same format as due. |
end | timestamp | Not read by the app yet. An end date in the same format as due. |
cite-as | text, one line | Proposed, not yet read by the app. The short name people cite the card by, such as FR123, on a single line. It is a name only, never an identity: a reference to the card still uses its uuid. |
Creating a card by hand
Section titled “Creating a card by hand”- Pick the lane folder.
- Make a folder inside it named a fresh lowercase UUID, for example with
uuidgen | tr 'A-Z' 'a-z'. - Write an
index.mdin that folder: frontmatter between two---lines, then the body.
The smallest legal card is a title and nothing else:
---title: "Short imperative card title"---
The card's content.It lands at the bottom of its lane, and the app fills in the missing keys the next time it rewrites the file. Better is to write schema, kind, order and both stamps, so that other tools and the activity log know who made the card. Never rename the folder afterwards: the UUID is the card’s permanent identity.
Quote a title that contains a colon, or any value that contains : or starts with #, [, { or a quote. Otherwise the YAML is invalid and the card will not load.
order places the card within its lane, lowest first, top to bottom. It is a number and decimals are fine. To work out a value, read the order of the cards already in the lane:
| Where | Value |
|---|---|
| Bottom of the lane | highest existing order plus 1024 |
| Top of the lane | lowest existing order minus 1024 |
| Between two cards | the midpoint of their two values |
| Empty lane | any number, conventionally 1024 |
Cards with no order go after those that have one, and equal values are placed by folder name. Reordering a card inside its lane changes only its order; modified is left alone.
due is most naturally a bare date such as 2026-08-25. A bare date means that day wherever the reader is. A full timestamp such as 2026-08-25T17:00:00Z also works and is read as the day it falls on in the reader’s time zone. See Timestamp for the accepted forms.
The card shows a due chip next to its labels. The chip turns amber as the day approaches and red once it has passed. A value that is not a date draws no chip and does no harm.
hero is the uuid of one of the card’s own attachments, which the app draws as a banner across the top of the card. It is an identity, never a path: the value names a folder inside the card’s attachments/ folder, so a value containing / draws nothing.
A uuid that matches no attachment, or an attachment that is missing or not an image, draws no banner and is otherwise harmless. A hero set before its file arrives starts working once the file does.
labels
Section titled “labels”labels is a list of label entries, each carrying its own text and kind so that a card copied to another board keeps its meaning.
labels: - {text: bug, kind: {type: text, text: Text, icon: {glyph: tag}}}Priority and component are labels of kind priority and component, never keys of their own on the card. The full entry shape, kinds and ranks are on the Labels page.
waiting
Section titled “waiting”waiting marks a card as blocked until a human replies. An agent sets it, and the app removes it once a human has answered. The shape and the rules are on the Waiting page.
start, end and cite-as
Section titled “start, end and cite-as”These three keys are proposed and not read by the app yet. Lanework keeps them if they are in a file, but they have no effect.
start and end take the same value as due. cite-as is the short name people would cite the card by, such as FR123. It is a name only, never an identity.
To link one card to another, use a Relation.
The body is ordinary Markdown and is the point of the card. Tag a fenced code block with its language, such as swift, sh, yaml, json or diff, and the preview colours it by syntax. A block with no tag or another tag stays plain monospaced text.
Stamps, icons and backgrounds
Section titled “Stamps, icons and backgrounds”created and modified are stamps, icon is described under icon, and background under background. A card’s background is drawn as a stripe down its left side.