Skip to content

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: 1
kind: card
title: "Fix: logo is blurry on retina screens"
order: 3072
icon: {glyph: ladybug}
labels:
- {text: bug, kind: {type: text, text: Text, icon: {glyph: tag}}}
due: 2026-08-25
hero: 3f2a8c14-7d6e-4b90-a1c2-5e8f9b0d1a23
created: {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.
KeyTypeDescription
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.
  1. Pick the lane folder.
  2. Make a folder inside it named a fresh lowercase UUID, for example with uuidgen | tr 'A-Z' 'a-z'.
  3. Write an index.md in 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:

WhereValue
Bottom of the lanehighest existing order plus 1024
Top of the lanelowest existing order minus 1024
Between two cardsthe midpoint of their two values
Empty laneany 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 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 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.

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.

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.