Board data: planning and organising
How the features in the guide’s planning and organising pages are stored and enforced. Read it before you change one
of their tables, triggers or RPCs. Each table’s migrations are under db/migrations/. The user side is in
docs/guide/.
Saved views
views (20261103160834_saved_views.sql): owner_id null means shared; filter holds the filter bar’s query as
structured keys. packages/shared/src/views.ts is the one place the keys are defined. It parses and formats the
query, matches cards, groups and sorts, and the public API’s q parameter uses it too. Changes to shared views are
audited as view.create|update|delete; the permission is view.shared.
Without a view open, the filter bar and layout are kept in board_prefs, as are swimlanes (swimlanes, subLanes,
hideEmptyLanes, laneOrder, projectLaneOrder, collapsedLanes). Lanes are worked out in
apps/board/src/lib/swimlanes.ts.
Cycles and estimates
cycles (20261107202319_cycles_estimates.sql), on the root team of a tree; cards.cycle_id, cards.estimate.
| Column | Notes |
|---|---|
team_id |
the top team of a tree; sub-teams share their root’s cycles |
number, name |
numbered per team; the name defaults to “Cycle n” and can change after it closes |
starts_on, ends_on |
UTC days, at most 12 weeks; a team’s cycles never overlap |
state |
planned, active (at most one per team), done |
carried_over, summary |
written at close: the cards carried over and the cycle’s numbers |
- The hourly
cycles_tick(run byandon.run_due_tickson the server) keeps two cycles ahead for teams with a cadence, closes each cycle the day after it ends and starts the next. One team’s failure is logged as a Postgres warning and skipped. - Closing writes a
card.carry_overaudit row per carried card. When there is no next cycle and something is left to carry, one of the same length is made after it, or around today, past any cycle in its way. - The database lets members rename a cycle, and its maker, owners and admins delete an open one. The board offers neither.
- Estimates: points as the number, t-shirt sizes as 1 to 5, hours as the hours (
packages/shared/src/cycles.ts). Autopilot’s placement seesestimatein each card’s facts (placement_input).
Milestones
milestones: team_id, project_id, name (unique per project, case-insensitive), description (the board’s
Note), target_on, state (open, done, canceled), and external_provider/external_id for imported ones;
cards.milestone_id. Audited as milestone.create|update|delete. Imports find a
Linear milestone by its Linear id, and adopt a board milestone of the same name made by hand.
The timeline layout (apps/board/src/components/board/TimelineLayout.tsx) doesn’t draw cycles yet; the code
comment there marks where bands would go.
Custom fields
custom_fields (20261107204016_custom_fields.sql): team_id, name, key, kind, options, required,
position, show_on_face. Values live in cards.fields, checked by the cards_fields trigger on every write:
- A value for a field the card’s team doesn’t have, or that doesn’t fit the kind, is refused (SQLSTATE 22023).
- A value the card already had that no longer fits is dropped rather than refused. Adding, changing or deleting a field re-checks the cards that hold its key; moving a team re-checks its cards and its sub-teams’.
- A required value can change but not be cleared (23502). Cards are still made without one: imports, quick adds and agents don’t know a team’s fields.
- The owner rule applies to fields like any card change.
At launch the agent reads values with card_fields(p_card) (names, kinds, display text), for the {{fields}} and
{{fields.<key>}} prompt tags. Imported fields: apps/server/src/functions/shared/import-fields.ts and
tracker-import-job.ts.
Sub-tasks and relations
20261108171243_subtasks_relations.sql and 20261108200934_card_deps_into_relations.sql.
cards.parent_card_id: same org, same team tree, no loop, at most 3 levels.private.cards_workstream_guardenforces it, serialised per org; the board asksnestRefusal(packages/shared/src/subtasks.ts) first.cards.auto_advancemarks a workstream step; hand-added, template and dropped sub-tasks have it off.cards.done_with_childrenis the parent’s switch. A workstream’s card closes throughprivate.close_done_parent.card_relations(card_id, other_id, kind, source), kindblocks,duplicate_oforrelates_to. Ablocksrow reads “card_idblocksother_id”;sourceislinearorjirafor imported ones.card_depsis a view over theblocksrows with its old columns (card_idwaits fordepends_on_id), so the dispatch hold, workstream auto-advance, Autopilot planning, PR groups,card_board_vandattention_vread it unchanged. Inserting into it writes ablocksrow. New code reads and writescard_relations.teams.hold_blockedis Blocked cards wait (default true).- Autopilot leaves parents and sub-tasks out of its groups (
autopilot_card_ok,placement_enqueue) and starts an unpaused workstream on its own (autopilot_queue). - A
reportwithoutcome: parkedmay namewaiting_onkeys; they becomeblocksrows once the card is in the Backlog.
Templates and bulk edit
20261108141843_card_templates_bulk_edit.sql.
card_templates: org-wide (team_idnull) or a team’s, withtitle_pattern,notes,recipe_id,labels,priority,estimate,fieldsandsubtasks.card_apply_templatefills a card as the caller, so the owner rule applies.cards.templatesremembers which templates filled a card, so a status default applies once.cards_bulkmakes every Set and Archive one call: each card changes in its own savepoint under the same RLS, owner rule and checks as a one-card edit, and a refused card is skipped. It returns each changed card’s old values, andp_action: 'undo'sends them back. One audit row per batch:card.bulk_editorcard.bulk_undo.
Comments
20261108144947_card_comments.sql.
card_comments(id, org_id, card_id, author_id, parent_id, body, mentions uuid[], edited_at, deleted_at, deleted_by, machine_id, run_id, -- a run's agent left it (agent_comment) former_author_id, -- an imported comment's author who isn't a member external_provider, external_ref, external_url, external_author) -- brought from Linearcard_comment_reactions(org_id, comment_id, card_id, user_id, emoji) -- primary key (comment_id, user_id, emoji)notifications(id, org_id, user_id, kind 'mention', card_id, comment_id, actor_id, read_at)card_thread(card, limit) -- the run's {{comments}}: latest 20, each cut at 4000 charactersdelete_card_comment(comment)agent_comment(run, text, card?, reply_to?) -- the MCP tool `comment`- Whoever sees the card reads its comments and reactions (RLS through
visible_card_ids). Only the author edits; nobody hard-deletes. Deleting an author, machine or run only clears its id on the comment. private.comment_mentionskeeps only members who can see the card, never the author. Mention handles come frommentionHandleinpackages/shared/src/comments.ts, shared with the notes editor.agent_commentchecks that the run is the calling machine’s. The database clearsmachine_idandrun_idon a person’s comment, so nobody can pose as a machine.- Linear comments are written only by
import_issue_comments, once, when the card is made. - Realtime topics:
org:<orgId>:comments:<cardId>andorg:<orgId>:notifications:<userId>. A mention push goes only to that person’s devices (payload.user_idinpush-core.ts).
Activity, the archive and history
20261109010731_activity_archive_history.sql.
-
card_historykeeps one row per change to a tracked card field: before, after, who andvia. Notes keep their first 280 characters. Only the database writes it.viaWhen boarda person signed in (the board, the desktop app) clia machine’s andonCLI through/api/v1apian API token importa tracker import agenta machine acting through the data API (a run, the daemon) systemAndon’s own ticks and service writes -
archived_cardssearches archived cards by any key they have had, or by words in the title and notes. -
teams.auto_archive_daysis stored per team but set for the whole workspace;auto_archive_tick(the server’sauto-archivetick) runs hourly. Teams added by a machine or a tracker import start on Never. -
notifications_mark_readmarks Activity read.
The Dashboard
The Dashboard page (apps/board/src/pages/Dashboard.tsx) is the lamp in components/lamp/. Its count is the sidebar’s
(useAttention, needsHuman). The wake lock, pixel shift and night dim live in lib/hygiene.ts; the night dim is
kept in localStorage. Car mode’s pure logic (phrases, the decision queue, briefings) is lib/car-mode.ts, and each
spoken decision is logged with log_voice_action.
