Skip to content

Shared values

Several value shapes appear in every kind of file: stamps, identities, timestamps, uuids, icons and colours. This page describes each one once.

created: {at: 2026-07-24T18:00:00Z, by: {name: claude, kind: agent, model: opus-5}}
icon: {glyph: hammer.fill, color: fern}
background: {color: coral}

A stamp says when something happened and who did it. created and modified are stamps, and both are mappings, not bare timestamps.

created: {at: 2026-07-24T18:00:00Z, by: {name: claude, kind: agent, model: opus-5}}
modified: {at: 2026-07-25T09:12:04Z, by: {name: claude, kind: agent, model: opus-5}}
KeyTypeDescription
at timestamp When it happened, as an ISO-8601 timestamp with a timezone, such as 2026-07-24T18:00:00Z.
by identity Who did it, as an identity mapping. If by is missing, the board's owner is taken to have done it.

Write the whole mapping. A bare timestamp is read as just at, and a bare name as just name, but that is meant for people typing by hand.

Stamp by on every write, and again after you move something, since a plain folder move rewrites no file. A missing by means the board’s owner wrote the file, so leaving it off signs your work as theirs.

at and by go together: set both in the same edit. created is set once when the item is filed and never changes. A move into another lane, another board or .trash/ counts as a change and stamps modified. Reordering within the same lane changes only order, and leaves modified alone.

An identity says who acted. It is the value of by.

by: {name: claude, kind: agent, model: opus-5, roster-ref: 3f2a8c14-0000-4000-8000-000000000000}
KeyTypeDescription
name text The display name shown for this person or agent, and the handle other people can mention.
kind text human or agent.
model text For an agent, its model name or level, such as opus-5. Leave it off for a human.
roster-ref UUID The bare uuid of the agent's card on an agent roster board, if it has one. Never a path.

Any other subkey you add, such as a session id or tool name, is kept as written. Two names are reserved for the app and its automation: shortcuts and healer. Read them, but do not write them as your own.

A timestamp is ISO-8601 with a timezone, in UTC for anything you write, for example 2026-07-24T18:00:00Z. On a Mac or Linux shell, date -u +%FT%TZ prints the current one. The zone letter Z must be uppercase. A time needs its seconds.

A UUID is eight, four, four, four and twelve hexadecimal digits separated by hyphens. The app writes lowercase, and folder names are lowercase UUIDs that never change. A reference to another item, such as hero, in-reply-to or waiting.comment, is the bare uuid and never a path.

A lanework:// link points at an item on a board by identity: lanework://<board-id>[/<item-id>[/<sub-item-id>]]. The board id comes first, then optionally a lane or card on that board, then optionally a comment, attachment or relation under that card.

lanework://0f3c2a9e-1b7d-4c55-9a40-6d2e8b1f7a13/9b47e2d1-3c80-4f6a-8e15-2a7d0c9b5e64

Each segment is a whole uuid or its first eight or more hex digits. Write the whole uuid. A relation uses a link as its to.

An icon is a mapping. It is available on boards, lanes, cards, labels and label kinds.

icon: {glyph: hammer.fill, color: fern}
KeyTypeDescription
glyph text An SF Symbol name, such as hammer.fill. A name this Mac does not have draws the default symbol instead.
color text The tint for the glyph: a palette name or a #RRGGBB or #RRGGBBAA hex colour. Leave it off unless the tint means something.

Both subkeys are optional, and either can stand alone. An absent one means the default for that level. On a label or label kind there is no default symbol, so an absent glyph draws nothing, and an absent color takes the colour of the label or kind that holds it. When you edit an icon, change one subkey and leave the others alone.

Use a tint sparingly. A lane of multi-coloured icons reads loud, so leave color off unless the colour says something the symbol cannot.

A colour is either a palette name or a hex value: #RRGGBB or #RRGGBBAA. Hex draws exactly as written in light and dark mode. Each palette name has one value for light mode and one for dark, and the app picks the one that fits.

The lists are fixed and names are matched exactly. A name that is not in a list draws nothing and is left as written. A name from either list works in either field.

Icon tint palette: obsidian, aluminum, soapstone, chalk, carnation, rich-grapefruit, smokey-tangerine, rich-lime, fern, light-jade, light-teal, deep-sky-blue, rich-indigo, pale-violet, rich-magenta, deep-cool-granite.

Background palette: shale, fog, coral, salmon, apricot, straw, pear, clover, seafoam, mint, aqua, cornflower, periwinkle, lavender, orchid, slate.

background is a mapping with one subkey. It applies to lanes and cards, not to the board.

background: {color: coral}
KeyTypeDescription
color text The fill colour: a palette name from the background list or a #RRGGBB or #RRGGBBAA hex colour. If absent, nothing is painted.

A bare background: coral is not valid and paints nothing.

The app reads values forgivingly. This is what it accepts.

  • Text: any plain value reads as the text you typed. A list or mapping where text is expected is not read.
  • Whole numbers: a whole number, a number written with no fraction, or a numeric string such as "3". A value with a fraction is not read.
  • Order: order is a number. Anything else is read as missing, which sorts the item after every item that has one.
  • Booleans: true and false, plus the words yes, no, on, off, y and n in any casing.
  • Schema version: schema must be the integer 1. Nothing is converted.

Frontmatter is YAML, and a broken line can stop the whole file being read.

  • Double-quote any value that contains : or starts with #, [, { or a quote. title: "Fix: the thing" is valid, title: Fix: the thing is not. When in doubt, quote.
  • Keep every value on one line, including long titles. A quote left open across a line break swallows every key below it.
  • A title never contains a line break.