@lovek4d/kickflip 0.0.0-stage → 0.3.1

package/CONTEXT.md

@@ -0,0 +1,513 @@
+# Kickflip hub and boards
+
+Pages on Love's tailnet that Claude sessions serve, so the owner can follow and steer their work from a phone. The hub lists the sites and sends pushes. A board is a site that shows a session's work as cards.
+
+## Language
+
+### Hub and sites
+
+**Kickflip folder**:
+The installed npm package or the owner's Git clone used through `npm link`, supplying the running app's code and linked into Claude Code's skills by init. It is separate from the live state in `~/.claude/kickflip/` ([0101](docs/adr/0101-kickflip-ships-as-a-minified-npm-package.md)). Init supplies kickflip's status line and hooks as well as the skill links, so setup is independent of the owner's dotfiles ([0080](docs/adr/0080-kickflip-installs-its-own-status-line-and-hooks.md)).
+_Avoid_: live skill folder
+
+**Doctor**:
+The hub setup check, `kickflip doctor`: each prerequisite, installed piece and site is ok, fixable by kickflip, the owner's to fix with the printed command, optional (Codex installed and logged in, or the mattpocock skills an **architecture review** follows, installed and current) or a note (a down site the hub restarts). `doctor --fix` runs the same setup as first-run `init` and checks again; another tool's status line stays the owner's choice ([0085](docs/adr/0085-doctor-checks-and-fixes-a-hub.md)).
+_Avoid_: status (the former CLI command)
+
+**Board repo**:
+A project's shared checkout in `<clone>/.repos/<owner>/<repo>` for a clone or `~/.claude/kickflip/repos/<owner>/<repo>` for an installed package, chosen from the GitHub list or a pasted GitHub link or `owner/name` when making a board ([0078](docs/adr/0078-a-pasted-github-link-picks-any-reachable-repo.md)). Another host's git link makes a board on that plain git remote, cloned in `.repos/<host>/<path…>`, whose cards finish as pushed branches instead of PRs ([0127](docs/adr/0127-a-board-can-work-on-any-git-remote.md)). Each board keeps its own branch, and its builders work in separate worktrees based on that branch ([0073](docs/adr/0073-a-new-board-chooses-a-repo-and-branch.md)). Before a session starts in it, the hub marks it trusted in Claude Code's `.claude.json`; the New board tap is the consent ([0113](docs/adr/0113-the-hub-trusts-the-clones-it-makes.md)).
+_Avoid_: repo folder (for the repo choice)
+
+**Local board**:
+A board whose builders branch from its repo's local `main` and land there, with nothing fetched: a board `kickflip join` made, marked `local: true`, on the folder it ran in, the hub board included; and a board with neither a GitHub repo nor a plain git remote, on its session's folder (`hub/boards.mjs` `buildsLocally`). Bare `kickflip join`, run in a git repo's folder, asks for the board name, records the folder's GitHub origin and branch, marks the folder trusted for Claude Code and starts the board's session, in the background or with `--hub` in the foreground in tmux, attached to that terminal ([0143](docs/adr/0143-kickflip-join-adds-the-current-repository-as-a-board.md), [0147](docs/adr/0147-boards-run-in-the-background-and-the-hub-board-in-tmux.md)).
+_Avoid_: joined board, folder board
+
+**Hub**:
+The one server on the host that answers the tailnet address, lists every site, forwards to each, checks GitHub for the open PRs on boards' cards, and sends pushes. Changes on the hub, boards and starter sites come from the app's own pages or non-browser clients; another site's page cannot act on them ([0069](docs/adr/0069-the-hub-starts-a-new-boards-session.md)).
+_Avoid_: portal, gateway
+
+**Host**:
+The machine the hub and its sessions run on, a Mac or a Linux machine. Its **hub service** keeps the hub running: a launchd login item on macOS, a systemd user unit on Linux, chosen by `shared/service.mjs` at init; init, doctor, land's restart and uninstall all go through it ([0093](docs/adr/0093-the-hub-runs-under-the-hosts-service-manager.md)).
+_Avoid_: the Mac, server (for the machine)
+
+**Sidebar**:
+The list of every site beside each board and hub page: New version with Reload when the hub’s code changed since the app loaded, else, on an npm install, Update available · Upgrade while npm has a newer kickflip, which runs `kickflip update` once no builder runs ([0161](docs/adr/0161-the-hub-offers-a-newer-kickflip-from-npm.md)), then Hub, then Turn on notifications when needed, then Pages (sites that aren't boards), then Boards with their status words, lane chips, waiting counts and **context window** (its owner session's last reported percent, e.g. “62% ctx”, from `~/.claude/kickflip/context/<session>.json`, which the status line writes; dimmed with its age once ten minutes old; none on cards or for subagents). The last row of Boards is **New board**, a + tile opening a sheet that chooses a GitHub repo from the list or a pasted GitHub link or `owner/name`, then its branch, Name, optional What it’s for and Tickets (Internal · INT by default); a line under the repo field points a repo already on the host at `kickflip join` in its folder. Start is the confirm: the hub starts the board’s session itself once the request passes its checks; a muted, non-link row reads **Cloning…**, then **Starting…** until its route joins. When claude fails to start, or after 15 minutes without a join, it keeps the board's name in red with **failed to start** under it ([0069](docs/adr/0069-the-hub-starts-a-new-boards-session.md)); tapping it opens a sheet with the clone or session error line, what the start used, Dismiss and **Retry**, which starts it again from the same record ([0130](docs/adr/0130-a-failed-start-retries-from-its-sheet.md)). Hub carries notification problems and the tools’ 5-hour usage bars under its sub line, and a moon after its name while pushes are held or snoozed, whose tooltip says until when; the whole row opens the hub page and stays selected on the hub page and its settings modals. Boards and Pages stay apart wherever sites are listed. The header's logo toggles it at every width; it carries no count, and shows a plain accent dot while a new version waits. From 900px it is a rail, which its own logo collapses out of sight until the header's logo brings it back; narrower, it is a drawer. Its header reads Kickflip. Below 900px every page header is a bottom bar, and the drawer header sits at its foot under New board; desktop headers stay at the top ([0070](docs/adr/0070-phone-headers-sit-at-the-bottom.md)). In the **app shell** it is mounted once, beside every view and framed page, and a site's row swaps the view in place. `/` opens this device's **last board**, which the app shell stores as each board opens, never a page ([0050](docs/adr/0050-a-sidebar-of-every-board-replaces-the-hub-home.md), [0055](docs/adr/0055-one-app-for-the-whole-hub.md)).
+_Avoid_: hub home, switcher, nav
+
+**Switch mode**:
+The sidebar showing each linked row's key after s is pressed twice outside a text field: the first nine boards' numbers on their tiles, and every linked row's letter from its name, in blue, while the Boards label reads "Boards – press a key to switch" over a bar that drains, and no row moves. The next key opens that row in place; Escape, a click or 3 seconds with no key ends it. Boards claim letters first, in the order they joined the hub, so a new board never takes another board's letter ([0056](docs/adr/0056-switch-mode-letters-come-from-names-in-join-order.md)).
+_Avoid_: shortcuts, hotkeys, jump mode
+
+**Shortcuts sheet**:
+The centred Keyboard shortcuts sheet over the dimmed page that h pressed twice within a second shows or hides, outside a text field and with no modifier, wherever the sidebar runs; Escape closes it. It lists every keyboard shortcut with its keys drawn as keycaps, from the one list in `ui-sidebar.js`. A device without a fine pointer that hovers, such as a phone, never shows it, and nothing else opens it.
+_Avoid_: help modal, cheat sheet
+
+**App shell**:
+The one page a browser's load of `/`, a hub page or any site's page gets, `board/public/app.html`: the sidebar, mounted once, beside one **view** at a time, and the hub's one stream, `/_hub/stream`. Following a link to a view swaps it in place, with no reload, and leaving one with an unsaved edit asks first. Every URL stays a real address. The board server answers a board's four view paths with the shell too, and the hub every load of `/_hub/`, `/_hub/settings` and `/_hub/settings/polling`, so curl and a frame get it; a frame's shell hands its URL to the app around it. While the host can't be reached, the hub's service worker opens the last shell the hub served, with its last sidebar, and each view shows its own offline state ([0055](docs/adr/0055-one-app-for-the-whole-hub.md)).
+_Avoid_: SPA, wrapper, frame
+
+**View**:
+One page's content in the app shell, mounted when its URL opens and unmounted, with every listener, timer and stream it added, when another takes its place. A board is a view, and so are its Waiting on you and Notes, and the **hub page**; hub settings open over Hub and Board Settings opens over its board as modals; a board left and opened again paints from its **last visit**, live when its stream sent no change since. Opened again in the same page, unless its link names a card, it also returns to where the owner left it: the page's scroll, its open threads' windows and edit boxes, and, with a mouse or trackpad, the box being typed in with its caret or selection; a phone keeps the keyboard shut. A reload starts fresh. Any other page, another site's or a board's prototype, is a **frame view**: the page in a frame beside the board header, or its own when it draws that header, with Open alone ↗ to load it by itself.
+_Avoid_: screen, tab, page (a page is its own document)
+
+**Page tree**:
+The levels back climbs in the app shell: a board, its Waiting on you, then a separately opened prototype page tied to one of its questions by `?q=`. On each, the back arrow, the browser's back and a swipe all go up one level: from a prototype to Waiting on you on its question, from there to the board, with the card still open when the owner left the board from that card's thread. However the owner arrives, by a push, a link or a reload, the levels above are written into history under the page first ([0058](docs/adr/0058-back-follows-the-page-tree.md)).
+_Avoid_: nav stack, breadcrumbs
+
+**Hub page**:
+The hub's status page, `/_hub/`, which the sidebar's Hub row opens: a pause or Keep going banner at the **pause line**, a banner while pushes are held or snoozed, with End snooze on a snooze, then **usage readings**, then the **pending prompts** of sessions that own no board, **Health**, whose Hub row reads the **hub status** and says Keeping awake and until when while Keep awake is on, **Integrations**, then **Boards** and **Pages** with each site's health and each board's hub links and watcher, and on each board a Restart that stops its session, restarts its server and resumes the session ([0121](docs/adr/0121-a-board-restarts-from-its-row-on-the-hub-page.md)), each session's remembered Always allow rules read-only under its board, polling status, then the **hub settings** summary rows ([0050](docs/adr/0050-a-sidebar-of-every-board-replaces-the-hub-home.md), [0060](docs/adr/0060-background-sessions-prompts-come-to-the-phone.md)).
+_Avoid_: dashboard, console, hub home
+
+**Hub status**:
+The word on the Hub row of the sidebar and the hub page's Health card: **Healthy** (green); **Degraded** (amber) while a board's hub link stays broken past its grace period or the hub runs older code than its files; "1 site down" (red) only while a site is down. Integrations that aren't set up don't count. On the hub page, tapping it jumps to Integrations. A board whose link fails reads "Degraded · listening" in amber, with the failing link named underneath ([0149](docs/adr/0149-the-hub-reads-healthy-degraded-or-a-site-down.md)).
+_Avoid_: broken, hub health
+
+**Integration readiness**:
+What each integration needs before its features can run: the Hub page’s Integrations section between Health and Boards lists GitHub, Codex, Linear, Slack, Tailscale and Notifications in that order. Ready says what passed; Not ready is orange and says what is missing, how to fix it and which features wait. A board session reports whether Claude’s Slack connector is available; the hub shares the same readiness and words with feature gates ([0108](docs/adr/0108-integrations-show-readiness-and-features-wait.md)).
+_Avoid_: integration health, availability
+
+**Usage reading**:
+The last reported Claude or Codex usage for its 5-hour and weekly windows, with reset times and when read. The sidebar’s Hub row shows each tool’s 5-hour bar and the hub page shows both windows with the **pause line** tick; a reading older than its window reads “last seen” with a grey striped bar, otherwise a window whose reset passed reads as reset. Claude appears after its status line reports usage. Codex's bars show only while the **Codex setting** in effect isn't Off; the hub page keeps Codex's block either way, opening with the setting's control ([0082](docs/adr/0082-the-sidebar-shows-claude-and-codex-usage-under-hub.md), [0086](docs/adr/0086-codex-share-sits-in-the-usage-card.md), [0092](docs/adr/0092-codex-share-follows-whether-codex-is-usable.md)).
+_Avoid_: quota, live usage
+
+**Pause line**:
+The Usage card's “Pause work at”, last in the group below Codex: `pauseAt` in `~/.claude/kickflip/settings.json`, 50–100 in steps of 5, default 90 (10% buffer); 100 reads Off. Either live Claude window at or over it pauses new work until that window resets. Running steps finish; builders and new agents wait, watchers hold the hub's work events, and owner messages get a brief “paused until <time>”. Keep going lifts that window's pause until its reset; Stop restores it. Codex hands work to Opus builders at the same line, without pausing. The Hub banner and sidebar and board header status slots show the pause, never the logo. `shared/usage-gate.mjs` owns it; `kickflip usage-gate` prints it ([0094](docs/adr/0094-work-pauses-at-the-pause-line.md)).
+_Avoid_: buffer threshold, quota guard
+
+**Claude model**:
+The Usage card's Opus · Auto · Sonnet control, opening Claude's block: `claudeModel` in `~/.claude/kickflip/settings.json`, default Auto. It decides which model builds a card Claude builds: Opus or Sonnet always, or under Auto the card's own `--model`, else Sonnet for a card `--size small` and Opus for the rest. `builder pick` prints it with why, and a build's `builder start` refuses a `--model` it rules out. Codex builds, prototypes and grills don't read it ([0162](docs/adr/0162-usage-picks-opus-auto-or-sonnet-for-claude-builders.md)).
+_Avoid_: Opus builders, allow Opus
+
+**Board registry**:
+`hub/boards.mjs`, the only hub code that reads a board's `board.json` and wave files. Every hub feature that serves boards (the GitHub check, wakes, rules, the handshake, the not-listening push) takes its boards from it, so a board over the waves and a board over its own file get the same links ([0040](docs/adr/0040-one-board-registry-for-every-hub-feature.md)).
+_Avoid_: board list, wave boards and file boards (as separate code paths)
+
+**Site**:
+A route on the hub (`/<route>`) served by one owning Claude session, or by none for a **plain page**.
+_Avoid_: app, page (a site has several pages)
+
+**Plain page**:
+A site joined with `kickflip join --name "<name>"` and `--port` (a server its session runs, which reads Down while nothing answers) or `--dir` (files the hub serves itself), without `--session`. It has no owning session, events, watcher or Needs you badge, and shows under Pages like any site that isn't a board. `--watch --session <id>` joins a site with all of those ([0087](docs/adr/0087-a-page-joins-without-a-session.md)). Every join's `--name` gives the site's title and route, the name hyphenated ([0143](docs/adr/0143-kickflip-join-adds-the-current-repository-as-a-board.md)).
+_Avoid_: minimal site, unwatched site
+
+**Owner**:
+Love, the person the sites serve. The word for the session that serves a site is **owning session**.
+_Avoid_: user, admin
+
+**Board session**:
+A board's owning session as the manifest records it in the site's owner: its id, its folder (`repo`, where `claude --resume` finds it) and an optional model. `kickflip start` launches one in the background; `kickflip resume` brings it back and records the id it comes back under. A rejoin keeps the label, model and folder it leaves out.
+_Avoid_: orchestrator process, agent
+
+**Hub session**:
+The owning session of the **hub board**, the one board whose manifest entry has `hub: true` (`kickflip set <route> --hub`, `kickflip join --hub`). It is the one board session that runs in the foreground, inside the tmux session `kickflip-<route>` the hub starts, which `kickflip hub` attaches the owner's terminal to; it gets the phone permission hook like a background session. Nothing else sets the hub board apart: it works on its own folder as a **local board**, closes and restarts like any board. Code finds it by the flag, never by its route. A hub board is optional, and no feature depends on its session ([0147](docs/adr/0147-boards-run-in-the-background-and-the-hub-board-in-tmux.md)).
+_Avoid_: hub server, permanent orchestrator
+
+**Live**:
+A session whose `~/.claude/sessions/<pid>.json` record names it and whose process still runs, started when the record says. A live session is never started or resumed again.
+
+**Listening**:
+A board is listening while its owner session is live and a watcher runs for it. A watcher outlives its session, so a watcher alone isn't listening. A board that isn't listening is waking, **asleep** or deaf. The board header, the sidebar, the events link and the not-listening push read that state, and the **session wake** uses this test ([0061](docs/adr/0061-a-boards-session-wakes-when-an-event-arrives.md)).
+
+**Asleep**:
+A board whose owner session isn't live but that the hub can wake on its next event or a tap on its page: a session and folder are recorded, and no **session wake** of this outage has failed or gone unanswered. It reads asleep in grey in the sidebar and the board header, its events link passes, and it gets no not-listening push. Once the hub resumed its session it is waking, and reads waking… in grey until it listens. A board that is neither listening, waking nor asleep is deaf and reads not listening in red ([0061](docs/adr/0061-a-boards-session-wakes-when-an-event-arrives.md), [0147](docs/adr/0147-boards-run-in-the-background-and-the-hub-board-in-tmux.md)).
+_Avoid_: idle, stopped, offline
+
+**Session wake**:
+The hub resuming a board session as soon as an event lands while that session isn't live, or the owner taps the board's page while it is **asleep** (the header's refresh or any other tap or send, through `/_hub/wake`), or, as a fallback, once its board hasn't been listening for 3 minutes with an event its session hasn't heard. Once per outage, then one push to the owner if the board still isn't listening 5 minutes later. A session that idles out with nothing waiting stays stopped. The hub board's session comes back in its tmux session ([0061](docs/adr/0061-a-boards-session-wakes-when-an-event-arrives.md), [0147](docs/adr/0147-boards-run-in-the-background-and-the-hub-board-in-tmux.md)).
+_Avoid_: auto-resume, respawn, wake (a daily wake is the morning `check-github`)
+
+**Push**:
+A notification from the hub, on the phone or a desktop browser, that opens a page. Each push has a kind, and `hub/push.mjs` `deliver()` refuses any other: `action` when a card's **Action needed** appears or changes, `prompt` for a **pending prompt**, `fault` for what only the owner can fix (a board not listening, a session that didn't come back, an urgent production problem) ([0006](docs/adr/0006-pushes-only-when-something-waits-on-the-owner.md)). Answers, merges, Stale and other news never push; the threads' unread marks and the board carry them. The board server sends each action push itself, under the card's tag or `topic-<id>` for a Needs you topic, when Action needed appears, changes kind or gains a question ([0133](docs/adr/0133-the-board-records-what-it-knows-and-commands-make-the-rule-calls.md)). Questions, steps and prototypes go at once; drafts on Ready and Merge go when their tick ends, and one under a card's tag replaces the last and alerts again ([0030](docs/adr/0030-pushes-go-by-kind-and-each-arrives-on-its-own.md)). When the queue goes out, a board with one queued push gets it as it is, and a board with several gets one summary of what waits on its Needs you then, tagged `summary:<route>` so the newest replaces the last, or nothing when nothing waits ([0120](docs/adr/0120-queued-pushes-go-as-one-summary-per-board.md)). Replies don't push; a push that goes out anyway says how many came since the last one. With notifications off every push is dropped; a snooze and Off on weekends hold pushes until they end, and urgent ones go through those holds ([0032](docs/adr/0032-notifications-can-be-off-snoozed-or-off-on-weekends.md)). While the owner is **at the host**, an action push goes to the host only ([0065](docs/adr/0065-pushes-go-to-the-mac-only-while-the-owner-is-at-it.md)).
+_Avoid_: alert, notification (for the act of sending)
+
+**At the host**:
+The owner's presence that keeps pushes off the phone: the host's screen is unlocked and a key or the pointer was used in the last 3 minutes, whatever app is in front (`hub/presence.mjs`). It is read from macOS `ioreg`, so on a Linux host the owner always reads away. Then an action push goes only to the desktop subscriptions, and the phone never gets it later; prompts, faults and urgent pushes still reach the phone, and with no desktop subscription every push does. Otherwise the owner is away and every push goes to every device ([0065](docs/adr/0065-pushes-go-to-the-mac-only-while-the-owner-is-at-it.md)).
+_Avoid_: at the Mac, active, online, desktop app active
+
+**Polling interval**:
+The hub's one schedule, a list of windows with their minutes: on each slot it checks GitHub, wakes a board's owning session with `github-change` when a PR on its cards changed, pushes once for each board that isn't listening, then sends the queued pushes. At each daily wake time it also sends each board one `check-github {reason: "morning"}`, changed or not. With hold pushes overnight on, pushes queued in the last window wait for the first window's start ([0025](docs/adr/0025-the-hub-polls-github-and-sends-pushes-on-one-interval.md)).
+_Avoid_: push schedule, send-at-once hours, cron
+
+**Hub settings**:
+The six summary rows below the **hub page**’s health and status: Notifications, Polling, Keep awake, Linear, Rules for every board and Closed boards. Each opens its controls in a centred modal with its own scroll area, including Polling’s schedule editor. Snooze and Keep awake share one duration picker: 1h, 3h, 6h, 1d, Forever and Custom. Keep awake has the hub run `caffeinate -ims` until its end, and is disabled on hosts other than macOS ([0112](docs/adr/0112-snooze-and-keep-awake-share-one-duration-picker.md)). Old Hub Settings links open the matching modal over Hub ([0075](docs/adr/0075-hub-settings-open-as-modals.md)).
+_Avoid_: Hub Settings page, preferences, hub config
+
+**Board Settings**:
+The centred modal opened from a board header’s gear, at every width, which scrolls inside on a phone. It contains only that board’s settings: repo and branch (Change uses the same list and GitHub link search as New board), ticket source, auto-merge, auto-build, auto-pull, auto-triage, reviewers, rules and Close board with typed-name confirmation. Closing returns to the same board and open card without another history entry ([0074](docs/adr/0074-hub-settings-expand-in-place-and-board-settings-open-in-a-modal.md)).
+_Avoid_: Settings page
+
+**Codex setting**:
+The one choice for every board, made in Codex’s block of the hub page’s Usage card ([0086](docs/adr/0086-codex-share-sits-in-the-usage-card.md)): Auto and Always on have Codex build and review, with Opus builders taking over while Codex is past the **pause line** until it resets; out of usage, Auto keeps Opus builders on and Always on pauses that work until a usage-reset check succeeds; Off means Opus builds and reviews. Unset means Auto. While Codex isn't usable, installed and logged in, the setting in effect is Off whatever is stored, and the control is greyed out; running out of usage doesn't make Codex unusable ([0092](docs/adr/0092-codex-share-follows-whether-codex-is-usable.md)). No session overrides it ([0105](docs/adr/0105-the-hubs-codex-share-is-the-only-codex-setting.md)).
+_Avoid_: Codex rule, board Codex toggle
+
+**Waiting count**:
+The badge on a site's row in the sidebar: how many things the site's `GET /_claude/needs` lists as waiting on the owner. It is unknown, with no badge, when the site doesn't answer. The Home Screen app's badge is the sum over every site.
+_Avoid_: unread count, inbox
+
+**Status word**:
+The coloured word that leads a site's sub line in the sidebar when something urgent holds, most urgent first: Paused while the **pause line** holds, otherwise Down, not listening (a board that is neither **listening**, waking nor **asleep**), Starting, Stopped (muted), "N need you", Working, waking… (muted), asleep (muted) or Building. Lane chips with the site's open-card counts follow it; a calm site shows only the chips ([0037](docs/adr/0037-the-hub-home-shows-status-not-descriptions.md), [0077](docs/adr/0077-need-you-outranks-working.md)).
+_Avoid_: activity line, subtitle
+
+### Boards
+
+**Board**:
+A site built from the board template that shows one or more waves as cards in lanes.
+_Avoid_: dashboard, kanban
+
+**Closed board**:
+A board whose session and server have stopped and whose sidebar row is gone, with its folder, cards, threads and notes kept on the host. The hub page lists it under Closed boards; Reopen restores it and resumes its recorded session. Open PRs stay on GitHub, and running builder records end with a note ([0072](docs/adr/0072-a-closed-board-keeps-its-folder-and-can-be-reopened.md)).
+_Avoid_: deleted board, archived board
+
+**Hub links**:
+What the hub owes a board, each passing or broken: GitHub polling (not on a board on a plain git remote), the repo fetch (on a board with a repo, the hub's last `git fetch` of it worked; when it failed, git's error line and the fix, such as `gh auth setup-git`, or `git ls-remote <link>` on a plain git remote), events (the board is **listening**), daily wakes and reviewer links; whether a device gets pushes is the Notifications integration, not a hub link ([0149](docs/adr/0149-the-hub-reads-healthy-degraded-or-a-site-down.md)). The hub link (the hub runs the code in its files) is the hub's own, shown in amber only on the sidebar's Hub row and the hub page's Health card ([0064](docs/adr/0064-every-builder-works-in-a-worktree.md)). The In Review header's GitHub mark, or on a plain git remote the branch mark beside its host/path, opens them as a sheet, red-dotted only while one stays broken past its grace period; until then it is **settling** ([0046](docs/adr/0046-hub-links-turn-red-only-after-a-grace-period.md)). A new board tests them with a **handshake**: a `hello` event the session's watcher answers itself, with a Connecting checklist on the board until the watcher answered and GitHub checks reach it, the GitHub step left out on a plain git remote ([0040](docs/adr/0040-one-board-registry-for-every-hub-feature.md)).
+_Avoid_: health, status, integrations
+
+**Change signal**:
+The board server's note on its `api/stream` that a file the board reads changed; the hub passes it on as `change {route}` on its one stream, and an open board reloads at once. The header's time counts from the last one that brought something new, or the last ↻ tap ([0031](docs/adr/0031-the-board-reloads-on-a-change-signal.md)).
+_Avoid_: push (a push is a notification from the hub), live update
+
+**Owner tap**:
+A button the owner taps on the board, sent as an event. The board's rule for taps: one whose result follows from the tap alone (a bump, Hold, Done, Build, an edit) is applied by the board server inside the POST, which answers with the board, and the page draws it at once, a bump, unbump, edit or delete even before the POST, taken back off with a toast if the POST fails. The event is a record for the session, never what the owner waits on; only judgment or outside tools (Grill, prototypes, a nudge, triage, a GitHub check) wait on the session. A tap reloads the board once, through the change signal ([0151](docs/adr/0151-every-owner-tap-the-server-can-apply-draws-at-once.md)).
+_Avoid_: action, click
+
+**Wave**:
+A set of work items built and reviewed together, with its reviewers.
+_Avoid_: batch, sprint, epic
+
+**Lineup**:
+What the owner calls a wave on a board: a named set of cards from one wave file, in build order, with a goal and a short note. Only the owner asks for one, with the +, or Claude proposes one as a board question when it spots a grouping in Todo. `board.mjs lineup create` makes each card blocked by the one before it and writes the note to `lineup-<slug>.md` beside the wave file; each card stays one PR and starts on its own as it unblocks. Its cards carry a grey chip with its name, in the row under their other chips. It is open until `lineup finish` or until all its cards are Done ([0109](docs/adr/0109-a-wave-the-owner-asks-for-is-a-lineup-of-cards.md)).
+_Avoid_: wave (in code and `board.mjs`, where a wave is a wave file), group, epic
+
+**Waves section**:
+The lane above In Review with one row per open **lineup**, then on a board over `~/.claude/waves` one per unfinished wave file: its name and "N of M merged", and for a lineup its Goal and Order lines and "Notes ↗ · Triage", while a wave file has Triage at the end of its name line. Notes opens the goal, order and note through `notes.html?wave=<slug>`. Tapping a row shows only its cards in the lanes, under "Showing <name> only · Show all" ([0109](docs/adr/0109-a-wave-the-owner-asks-for-is-a-lineup-of-cards.md)).
+_Avoid_: wave bars, wave filter, pills
+
+**Wave triage**:
+Claude reading the code for a lineup's unstarted cards and proposing to split, merge, add or close cards, as one open board question per change on topic `lineup:<slug>`, which Needs you shows as "<wave> · N questions". For a wave file, Claude checks each unfinished card's PR, CI, reviews and blockers, and whether a merged card already covers a Todo card, fixes what it can, and asks one question per card that needs the owner on topic `wave:<slug>`. The row's Triage confirms, sends `wave-triage {lineup}` or `wave-triage {wave}` and reads Triaging… in orange until the session replies to that event, then "Triage: N open questions" in grey while any is open or answered ([0109](docs/adr/0109-a-wave-the-owner-asks-for-is-a-lineup-of-cards.md)).
+_Avoid_: grooming, refinement
+
+**Architecture review**:
+Claude reviewing a board's repo, chosen by `hub/board-repo.mjs` `boardRepo`, with the mattpocock skills: the bulb between the board header's ↻ and gear opens a sheet with the last review and Run, which confirms. The board server makes a **lineup** "Architecture <date>", or on a board over `~/.claude/waves` a wave file of its own, whose first card is its audit card, and wakes the session with `arch-review`. The bulb glows orange while the audit card is open with no question yet. The audit card's Notes are the report, and it asks one question per finding, with possible solutions and Skip; each finding not skipped becomes a card after it. One review is open at a time, so Run while one is open opens its audit card. A board on the running kickflip clone, as the hub board is, has its review cover kickflip's code, the board template and the model, reading the live data only for its shapes. It waits, saying why, while a skill it follows isn't installed ([0125](docs/adr/0125-the-bulb-runs-an-architecture-review-of-the-boards-repo.md)).
+_Avoid_: improvements round, audit (for the whole review), bulb round
+
+**Reviewers**:
+The people who get a board's PR links once they are ready, and the weekday digest. Each board keeps its own in `board.json`, which its Settings modal lists, and a new wave copies them into its own `reviewers`. Kickflip owns the sent links in each item's `review_link_ts: {<name>: {ts, channel, reactions?}}`; one reader supplies the card, Stale age, hub Slack link and digest, with slack-bridge topic files only as a fallback. The session sends through Claude's Slack connector and records with `board.mjs review sent`, `review react` and `review digest sent`. Hub Slack identity lives in `~/.claude/kickflip/slack.json`, read or set by `board.mjs slack`; its timezone sets the weekday 09:00 digest date ([0104](docs/adr/0104-kickflip-owns-the-reviewer-record.md)).
+_Avoid_: approvers, watchers
+
+**Finished wave**:
+A wave with work items that are all merged, done or dropped. Done shows it as one row that opens to its cards, and it leaves the **Waves section** ([ADR 0012](docs/adr/0012-lists-never-cut-silently.md)).
+_Avoid_: closed wave, archived wave
+
+**Work item**:
+One unit of work in a wave, usually one PR. Its key is `<wave>/<id>`. It reads as its ticket when the ticket is from the board's source (`#27`, `ENG-12`, `INT-5`), else as its id, and `item add <wave>` takes its id from its ticket ([0132](docs/adr/0132-a-card-is-named-by-its-boards-ticket-source.md)).
+_Avoid_: task (a **new task** is the owner's), ticket (the identity of its work in the board’s ticket source)
+
+**Ticket**:
+The identity of a work item in its board’s **ticket source**, shown as a badge that opens the internal card, GitHub issue or Linear issue. A ticket id belongs to its source: one stored under another source shows as its own id, unlinked. An ask has no ticket; filing it as work creates or links one ([0081](docs/adr/0081-a-board-has-one-ticket-source.md)). A card moves its ticket one way, building to In Progress, a PR to In Review and done to Done, when the owner is assigned it or kickflip created it; a ticket never moves its card ([0088](docs/adr/0088-kickflip-reaches-linear-with-a-key-on-the-mac.md)).
+_Avoid_: card (the board’s work item), task
+
+**Ticket source**:
+The board’s one choice for every card’s tickets: Internal with a prefix (INT by default), GitHub issues in the board’s repo when it is on GitHub, or a Linear workspace, team and project, picked from dropdowns listed through Hub’s **Linear key**. New board and Board Settings share the choice ([0081](docs/adr/0081-a-board-has-one-ticket-source.md)), and pick Linear only while that key works: tapping Linear without one opens the key’s modal over them. Board Settings saves each change at once, and Done waits for a save in flight ([0117](docs/adr/0117-a-board-picks-linear-only-while-hubs-key-works.md)). A GitHub source can name the gh account its issue calls run as. The hub board’s repo is its entry’s `github`, its folder’s origin, so it can file its cards as GitHub issues ([0115](docs/adr/0115-the-hub-board-files-its-cards-as-github-issues.md)).
+_Avoid_: integration, tracker, GitHub project
+
+**Linear key**:
+The owner’s Linear personal API key, pasted in Hub settings and kept only on the host; pages learn only whether it is set, whether Linear refused it and its workspace. It saves and is checked with Linear on paste, with no Save button, and the hub remembers a refusal until a call with that key gets an answer ([0117](docs/adr/0117-a-board-picks-linear-only-while-hubs-key-works.md)). kickflip lists teams and projects, creates projects and issues, and moves tickets with it. The hub's poll uses the saved key's viewer as the owner and advances their Linear tickets from PR state, aggregating every carrying card across boards; without a key the poll moves none ([ADR 0107](docs/adr/0107-the-hubs-poll-moves-the-owners-linear-tickets.md)). Without a key, a board can’t pick Linear in Board Settings or New board, and `board.mjs` prints `ticket` lines and the board’s session does that work through its Linear MCP ([0088](docs/adr/0088-kickflip-reaches-linear-with-a-key-on-the-mac.md)).
+_Avoid_: Linear token, API secret
+
+**Internal item**:
+A work item about the sites themselves rather than the product. Its legacy ref `S<n>` reads `INT-<n>`, or the board’s internal prefix when set.
+_Avoid_: meta task, chore
+
+**Badge**:
+A chip on a card or page that shows a status, such as Install or a PR's state. It may link to what it is about: on a closed card, Install goes straight to the thing to act on (owner, question `badge-tap`). A card's badges are its ticket ID, wave chip, follow-up, risky, New on an unsorted ask, and PR and try-build state; held, blocked by and Action needed are orange words on its time line instead, and ready a green one, and a bump shows only as the filled bump icon ([0145](docs/adr/0145-build-on-a-blocked-card-queues-it.md)). A badge never acts on the board; a **button** does.
+_Avoid_: chip (in what the owner reads), tag, label
+
+**Button**:
+A control that acts: it sends something to the board, such as Merge, Hold or Grill, or opens a place to act, such as Open questions. The open card's workflow row holds Merge, Hold or Unhold, the **action button**, Serve or Build when the card has a build script and branch changes and Auto-build is off, and last **Implement** on a Todo card that can start (a held Todo card's Implement takes the place of its Unhold), below the details list whose final line holds Notes, Install and Review on GitHub links in that order ([0067](docs/adr/0067-a-cards-external-links-share-the-last-details-line.md)). A card that can be bumped, every Todo card (held or waiting on the owner included) and a running In Progress one that isn't held, carries its bump as an icon at its top right instead, closed or open, as a New card does (the empty icon always shows on a touch screen and with a mouse only while the card is hovered or has focus; a bumped card's filled one always shows) ([0019](docs/adr/0019-a-card-that-hasnt-started-can-be-bumped.md)). It sends with no confirm, and on a bumped card it is filled orange and unbumps (`card-unbump {key}`) ([0145](docs/adr/0145-build-on-a-blocked-card-queues-it.md)). The control that clears the card's **Action needed** is orange.
+_Avoid_: badge, pill (a pill is only a look)
+
+**Badge tone**:
+The color of a badge (a status chip on a card or page), picked from one fixed set by what the badge says, through `BoardUI.badge` in `board/public/ui.js`: quiet (gray), normal (blue), notice (orange), danger (red) or ready (green). Each tone takes its color from a **status color**, so a badge is one consumer of the colors, not their source. No badge has a look of its own, so the same tone looks the same everywhere. Buttons and links styled like chips, such as quick replies, **Implement** and "Review on GitHub →", aren't badges; the orange of the button that clears Action needed is the same notice color.
+_Avoid_: chip color, badge style, variant
+
+**Status color**:
+A color named by what it means, `--color-quiet`, `--color-info`, `--color-notice`, `--color-danger` or `--color-success`, in `shared/colors.css` beside the base palette, in light and dark. That file is the one set of colors for the hub and every board; no page's CSS defines a color of its own ([0033](docs/adr/0033-one-colour-constants-file-shared-by-the-hub-and-every-board.md)). Which one a meaning takes follows the **colour rule**; done or passing is success.
+_Avoid_: tone token, theme color, badge color
+
+**Colour rule**:
+A colour says whose turn it is: red (danger) for faults, such as failed, down, not listening or spending, and the sidebar's "N need you"; orange (notice) for attention and work, such as Action needed, the Needs you box, a New card, a Next line while it is someone's turn, a builder's line, Working or Starting; blue (info) only for review and notice, something for the owner to read or see, such as an unread review, a new version to reload or a changed line's flash; grey (quiet) for idle, such as ticket ids, a Todo or Done card's Next, the Done ring, Stopped or usage that is fine, which takes no other colour. Pick a new colour by it ([0096](docs/adr/0096-colour-says-whos-waiting.md)).
+_Avoid_: warning colour (for attention), action colour (for blue)
+
+**Follow-up**:
+A work item with a **Parent**: work spun out of another card. It is an ordinary card in every way and carries the quiet follow-up badge ([0156](docs/adr/0156-a-follow-up-is-a-work-card-with-a-parent.md)).
+_Avoid_: backlog item, todo, follow-up tag
+
+**Parent**:
+The one card a work item was spun out of, or none: set when a card is created from another card's conversation (its thread, a grill or an answer) with `item add --parent`, none for a card from the + or New task. The Parent lists it among its **Children**. The open card shows both as rows of card labels, with **Related to**, Blocked by and Waits on it, the mirror of Blocked by ([0156](docs/adr/0156-a-follow-up-is-a-work-card-with-a-parent.md)).
+_Avoid_: filed from, origin, epic
+
+**Related to**:
+Similar cards that should be cross-referenced, set by hand with `item set --related`, shown on both cards. It neither blocks nor orders anything; Blocked by does that ([0020](docs/adr/0020-cards-wait-on-explicit-blocked-by-links.md)).
+_Avoid_: sibling, link (alone)
+
+**Plan waves**:
+The Show more row at the foot of Todo, shown when two or more work cards there are neither held nor blocked. Confirming sends `plan-waves {keys}`, and the session triages those cards into one or more lineups and asks to confirm each as a board question ([0153](docs/adr/0153-plan-waves-plans-from-any-todo-cards.md)).
+_Avoid_: backlog item, todo
+
+**Lane**:
+Where a card sits (In Review, Stale, In Progress, Todo, Done, Asks), set by who acts next ([0045](docs/adr/0045-the-lane-follows-who-acts-next.md)). In Progress means a card is building: a running build agent, a **checking** item, or a PR whose CI is red or, on a draft, still running. A work card that has started building, with a build agent's record, running or finished, a building or fixing status, or a **queued build** ([0145](docs/adr/0145-build-on-a-blocked-card-queues-it.md)), never drops back to Todo unless held ([0138](docs/adr/0138-a-card-moves-to-in-progress-only-once-building-starts.md)). A running grill or prototype agent shows its status line but leaves the card where it is. In Review means finished work waits on a person: the reviewers, or the owner's Ready, Merge, manual steps or the Done of an ask (see **Action needed**), or of a reopened card. An owner message or a new question on a Done card that hasn't merged reopens it: In Progress until Claude answers, then In Review until the owner's Done, its next step "Tap Done once it is settled" ([0128](docs/adr/0128-a-message-or-question-on-a-done-card-reopens-it.md), [0136](docs/adr/0136-a-card-waiting-only-to-be-closed-has-no-action-needed.md)). A card waiting only on those moves there from In Progress; one Claude still works on stays in In Progress. Todo holds work that hasn't started building: the New cards, which wait on Claude ([0047](docs/adr/0047-the-plus-makes-a-new-card.md)), and every work card with no build yet, where its **Implement** shows. Discussion keeps a card there: open questions or a prototype pick, with Action needed, answered or resolved questions, grill and prototype agents, a working mark on a message in its thread and a prototype recorded for it ([0138](docs/adr/0138-a-card-moves-to-in-progress-only-once-building-starts.md)). A started card that gets a question keeps its lane ([0059](docs/adr/0059-an-unstarted-card-waits-on-its-questions-in-todo.md)). Each lane has one fixed order, with no sort menu ([0140](docs/adr/0140-each-lane-has-one-fixed-order.md)): Todo lists its New cards first, oldest first, then its bumped cards, the latest bump on top ([0019](docs/adr/0019-a-card-that-hasnt-started-can-be-bumped.md)), then the rest newest made first; In Progress, its bumped cards first, then by when each came into the lane, its reopening or its latest build agent's start, the newest arrival on top; In Review and Stale by when the PR was first sent to a reviewer, the newest on top; Done by when each card closed, the most recent on top; Asks, the answered asks in their own lane below Done, by when Claude answered, the newest on top. Done and Asks each show 10 cards, then a Show more, the thread's, that adds 10 and says how many are left; a card the owner has open stays shown ([0144](docs/adr/0144-answered-asks-have-their-own-section-below-done.md)). Every card, a New card included, ends with one muted line holding the time its lane sorts by: the time only today, the day too before today ("10/31, 2:49 PM"), and the year too past 365 days. A card with no such time has no time on that line.
+_Avoid_: column, status (status is the item's own field)
+
+**Checking**:
+The item status a site card's builder sets when it hands back finished work it couldn't land itself. The card sits in In Progress reading "Orchestrator review" while the owning session verifies and lands it. Only done, merged and dropped unblock dependents ([0022](docs/adr/0022-site-cards-build-in-parallel-when-their-files-dont-overlap.md), [0133](docs/adr/0133-the-board-records-what-it-knows-and-commands-make-the-rule-calls.md)).
+_Avoid_: verifying, in QA, review (review is the reviewers' part)
+
+**Stale**:
+A work item that has waited in review more than seven days since its first review link went out. Its card moves to the Stale lane ([0044](docs/adr/0044-a-pr-in-review-shows-its-age-and-goes-stale-after-seven-days.md)).
+_Avoid_: old, overdue
+
+**Next step**:
+Claude's next step on a card and what sets it off, such as "Next: merge when CI is green", kept in the item's `next` and cleared once done. A card waiting on its reviewers reads its next step from GitHub instead ([0002](docs/adr/0002-a-card-derives-its-lane-from-github.md)), and one waiting on the owner reads its action. It is orange while it is someone's turn and grey on a Todo, Done or held card. It shares its place under the title with the builder line, which takes it while a builder record is open, and an In Progress card with neither reads "Next: none set yet": the CLI refuses a `builder done` or `item set` that would leave one so without `--next` ([0142](docs/adr/0142-an-in-progress-card-always-has-a-builder-line-or-a-next.md)). A Next set while the card has an open question clears once a build starts on it, or once Claude's acting leaves none of its questions unresolved ([0157](docs/adr/0157-an-answer-stops-waiting-once-its-acted-on.md)).
+_Avoid_: plan, notes (**Notes** is the card's write-up), todo
+
+**Waits on**:
+Who the card is waiting for: the owning session's check, the owner's Ready, the owner's other action, the builder, the reviewers, the merge, or nobody.
+_Avoid_: blocked by, assignee
+
+**Card state**:
+What a card made from a **New task** does next, which its session picks and sets with `item set --state`: **ready** (its notes leave the owner nothing to decide, so it can be built; the plan lives only in the notes), **grilling** (questions on the card) or **prototyping** (takes on the card). The board enforces the three: `--state` refuses any other, and ready while the card has an open question. Until it has one, the card reads New beside its ticket id and is never pulled. A Ready card's time line reads a green "ready" in Action needed's place ("10:26 · held · ready · 2 new messages") while nothing blocks it and nothing waits on the owner, and the idle pull takes it like any settled card ([0154](docs/adr/0154-a-new-card-is-ready-grilling-or-prototyping.md)).
+_Avoid_: triage state, status (the wave entry's `status` is a different field)
+
+**Action needed**:
+The orange words last among the orange ones on a card's time line ("10:26 · held · blocked by #53 · Action needed"), on a card waiting on the owner, in any lane ([0145](docs/adr/0145-build-on-a-blocked-card-queues-it.md)): an open question or a prototype pick, a green draft's Ready, the Done of an ask, manual steps on an approved PR, or, with **auto-merge** off, an approved PR's Merge. It links to the thing to act on. Reviewer waits and held cards get none ([0045](docs/adr/0045-the-lane-follows-who-acts-next.md)), and so does a reopened card waiting only on the owner's Done, which is only waiting to be closed ([0136](docs/adr/0136-a-card-waiting-only-to-be-closed-has-no-action-needed.md)). An unstarted card with open questions carries it in Todo ([0059](docs/adr/0059-an-unstarted-card-waits-on-its-questions-in-todo.md)).
+_Avoid_: open items, needs you (Needs you is the box at the top of the board)
+
+**Action button**:
+The open card's one workflow button, which `board/domain.mjs` picks as the card's `actionButton`: **Open questions** (`openQuestions`) while it has open questions or a prototype pick, opening the first; **Mark as done** (`markDone`) on an ask waiting on the owner's Done, sending the same `ask-done` as the thread's Done; otherwise **Grill** (`grill`), which reads "Writing questions…", disabled, while a grill is under way: a Grill tap Claude hasn't answered, a running grill agent, or a **grilling** card with no questions posted yet ([0154](docs/adr/0154-a-new-card-is-ready-grilling-or-prototyping.md)). Open questions win over Mark as done. A Done card, and an ask with neither, has none ([0059](docs/adr/0059-an-unstarted-card-waits-on-its-questions-in-todo.md)).
+While the card carries **Action needed**, the button that clears it is orange, in the notice color: the card's `resolvedBy` from `board/domain.mjs`, by the action's kind. A question or a pick makes Open questions orange, the Done of an ask makes Mark as done and the thread's Done orange, a green draft's Ready or manual steps make Review on GitHub orange, and an approved PR's Merge makes Merge orange. A held card's Open questions, and Grill, stay plain. A reopened card waiting only on the owner's Done keeps Grill, and its thread's Done is primary, in the accent color ([0136](docs/adr/0136-a-card-waiting-only-to-be-closed-has-no-action-needed.md)).
+The button names (`BUTTON`: the action buttons, `github` and `merge`) and the action kinds (`ACTION_KIND`) are two frozen enums in `board/public/ui-enums.js`, which the page loads as a script and `board/domain.mjs` runs in a vm context; code compares against their members, never a bare string.
+_Avoid_: Open items, Action needed (the badge)
+
+**GitHub tick**:
+The session's steps for PR comments, CI, review, conflicts and merging, defined in SKILL.md. The hub polls GitHub with Node and gh, writes new owner and reviewer comments into each card's thread, closes a card whose PR merged, then wakes the board on a change ([0134](docs/adr/0134-the-hubs-poll-records-merges-and-pr-comments-on-the-card.md)); the tick reads each card with `board.mjs pr` and records the newest handled event with `item set --gh-since`. With Hub's Linear key set, the poll also moves the owner's Linear tickets from PR state, so the session leaves those moves to the hub; without a key the poll moves none ([ADR 0107](docs/adr/0107-the-hubs-poll-moves-the-owners-linear-tickets.md)). The owner's monitor skill is optional ([0103](docs/adr/0103-the-hub-reads-github-itself.md)).
+
+**Auto-merge**:
+A board setting, `auto_merge` in its `board.json`, off unless set: on, the session's GitHub tick merges a PR once it is approved, CI is green and its merge state is CLEAN; off, the card shows the owner Action needed and a Merge button, which reads "Merging…" until the PR merges or Claude says in the thread why it didn't. The board's Settings modal toggles it, and the watcher prints it with every wake as `setting auto-merge on|off`. A setting, not a **rule**, since the board itself acts on it ([0052](docs/adr/0052-auto-merge-is-a-board-setting-off-by-default.md)).
+_Avoid_: merge rule, merge policy
+
+**Review on GitHub**:
+The open card's link to its PR, on every card with an open PR, last on the details list's final line after Notes and Install when present. It reads "Review draft on GitHub ↗" on a draft and "Review on GitHub ↗" once ready, with no PR number, and is orange while a green draft's Ready or manual steps wait on the owner ([0067](docs/adr/0067-a-cards-external-links-share-the-last-details-line.md)).
+_Avoid_: Review #<n> on GitHub, PR link
+
+**Install**:
+The app card's one badge that opens its build on the owner's phone, or the badge on main's slim bar above the lanes. A ready card reads "Install ↗", or "Install (stale) ↗" when its build's sha differs from the current branch head. While a build runs it reads "Building…" with an inert spinner; a failed build reads "Build failed ↗" and opens its thread. The open card's badge sits between Notes and Review on GitHub. The workflow button starts a Build, or Retry after failure, while Auto-build is off and the card's branch has changes ([0124](docs/adr/0124-only-the-owner-or-auto-build-starts-a-card-run.md)). Main’s red Build failed button opens a bottom sheet with the last 40 lines of `data/try/main.log` and Retry at the recorded failed tip. Retry shows readiness refusals in the sheet, reads Building… in orange while running, refreshes the log after failure and closes with a toast when ready. A Done card has no try badge ([0099](docs/adr/0099-a-boards-build-script-serves-or-builds-each-card-and-main.md)).
+_Avoid_: download, TestFlight (a different channel), older build
+
+**Build script**:
+The repo's reviewed, executable `.kickflip/build`, run by the hub from each card's worktree and main's hub-owned detached worktree. The hub passes the key (or `main`) and worktree, plus `KICKFLIP_BOARD`. Websites serve at their root on their own Tailscale HTTPS port, without a path prefix or `KICKFLIP_BASE` ([0102](docs/adr/0102-a-try-build-serves-on-its-own-tailscale-port.md)). Printing `port <n>` and staying alive serves a website; exiting 0 without a port finishes an app build that publishes an install through the board CLI. The last finished run decides the board's kind. The hub writes try state and logs; failed card runs append one thread line, and successful runs none. There is no script path setting ([0099](docs/adr/0099-a-boards-build-script-serves-or-builds-each-card-and-main.md)).
+_Avoid_: install script, session install runner
+
+**Serve**:
+The workflow button after the **action button** for a website work card with a build script, last but for **Implement**, while Auto-build is off and the card's branch has changes ([0124](docs/adr/0124-only-the-owner-or-auto-build-starts-a-card-run.md)). It confirms before the hub runs the script. Its one badge reads "Serving…", "Visit ↗", "Visit (stale) ↗" or "Serve failed ↗". A served card opens at `https://<host>:<port>/`, with a port from 8500–8599 kept through re-serves. A loopback relay tracks visits; 30 idle minutes stops the card and releases its port. Main has a fixed port recorded per board, keeps its link across merges and restarts and never idles out. Its red Serve failed button opens the same log and Retry sheet as an app’s Build failed, reading Serving… in orange while retrying the recorded failed tip, even if origin has moved. Both open the server itself, outside the app shell ([0102](docs/adr/0102-a-try-build-serves-on-its-own-tailscale-port.md)).
+_Avoid_: preview site, separate page
+
+**Auto-build**:
+The board's `auto_build` setting, off by default. On, each card with commits beyond main builds or serves after each new head, and cards show no Serve or Build; off, cards wait for the owner's Serve or Build. A session starts a card run only to carry out the owner's words, quoting them with `build <key> --asked` ([0124](docs/adr/0124-only-the-owner-or-auto-build-starts-a-card-run.md)). Main always builds after every merge. The hub runs a nonoverlapping tick every 15 seconds and fetches other boards' origin branches on each GitHub polling slot. The Settings toggle saves immediately; `settings set auto-build on|off` sets it through the CLI.
+_Avoid_: auto-serve, build rule
+
+**Implement**:
+The orange Implement last in the open card's workflow row, on a work card still unstarted in Todo, held or not, blocked or not, that has no **Action needed**: the card's `buildable` from `board/domain.mjs`. Its confirm reads "Implement #92? Claude starts its implementer now with the notes as they stand." Owner-facing words call a card's agent an implementer and its `building` status implementing, so Build, Serve and Install only mean the package of a worktree or main; the code keeps `buildable`, `card-build`, the `building` status and builder records ([0166](docs/adr/0166-a-todo-cards-button-reads-implement.md)). On a blocked card it queues a **queued build**, its confirm "Implement #92 once #53 is done?" ([0145](docs/adr/0145-build-on-a-blocked-card-queues-it.md)). On a held card it reads "Unhold and implement" in its confirm and the board server clears the hold as Unhold does before the start; a held card outside Todo keeps Unhold ([0141](docs/adr/0141-a-held-todo-card-shows-build-in-place-of-unhold.md)). It confirms, sends `card-build {key}` and reads "Starting…" while the board server starts the build: the refusals, the builder pick, the worktree and the building mark that `builder start --kind build --worktree` makes. Started, the card is in In Progress reading **Waiting for orchestrator**, and the server wakes the session with `card-build {key, ref, kind, model, reason, worktree}` (`model` only for claude) to brief and launch the builder. Refused, the card stays in Todo showing **Couldn't start implementing** ([0122](docs/adr/0122-a-todo-card-that-nothing-blocks-has-build.md), [0139](docs/adr/0139-a-build-tap-starts-the-build-in-the-board-server.md)). It isn't an app's Build, which runs the **build script**.
+_Avoid_: card Build, go button, start button
+
+**Queued build**:
+An Implement the owner tapped on a card an unfinished dep blocks: `queued_at` on its wave entry, with no builder record or worktree, and the thread line "Implement queued: it starts once #53 is done." The card sits in In Progress, its time line reading "blocked by #53" in place of a builder line, and once nothing holds or blocks it the board server starts the build as the tap would, from the newest main, waking the session with `card-build`. `item set` prints `queued build starts: <key>` for it and sends no `card-unblocked`. A start that is refused or fails sends the card back to Todo with **Couldn't start implementing** ([0145](docs/adr/0145-build-on-a-blocked-card-queues-it.md)).
+_Avoid_: pending build, waiting build
+
+**Waiting for orchestrator**:
+A card's builder line while the builder record the owner's Implement tap made is still `tapped`: the board started the build, and the session hasn't launched its builder. The builder's own `builder start` takes the record up, and its first status line replaces it. It is never a builder status line and isn't written to the thread ([0139](docs/adr/0139-a-build-tap-starts-the-build-in-the-board-server.md)).
+_Avoid_: queued, pending build
+
+**Couldn't start implementing**:
+The thread line, of kind `build-refused`, the board server writes when it refuses an Implement tap, with the reason in the owner's words: paused, or a noted prototype pick that waits on its confirm, or why a **queued build** couldn't start. The Todo card shows it in its status line while it is the card's newest line other than a status line ([0139](docs/adr/0139-a-build-tap-starts-the-build-in-the-board-server.md)).
+_Avoid_: Couldn't start the build, build error, failed start
+
+**Auto-pull**:
+The board's `auto_pull` setting, off by default, which reads "Pull in Todo cards when idle" in Board settings' Todo section and turns on or off with no confirmation. On, while the board is idle (no builder runs and nothing waits in Orchestrator review), the board server's minute check sends `card-pull {key}` for the top **pullable** card, Ready cards first, then cards with no state, each in board order ([0170](docs/adr/0170-the-idle-pull-takes-ready-cards-first.md)): an unstarted Todo work card that nothing blocks or holds, with no questions, no grill under way and no message a session is working on ([0138](docs/adr/0138-a-card-moves-to-in-progress-only-once-building-starts.md)). A running build keeps the board from being idle; a running grill or prototype does not ([0167](docs/adr/0167-planners-and-implementers-are-two-kinds-of-agent.md)). New cards are never pulled, nor a card from an ask still New, grilling or prototyping; a Ready one is ([0154](docs/adr/0154-a-new-card-is-ready-grilling-or-prototyping.md)). It writes "Pulled in: the board was idle." in the card's thread, and pulls the next only once that card stops being pullable. The session takes the card's next step: a grill when its notes leave something open, else a build ([0123](docs/adr/0123-an-idle-board-pulls-in-its-top-todo-card.md)). With nothing pullable it sends `card-plan {key}` instead, one at a time, for the top Todo card not set Ready that isn't held, owes or awaits no answer and has no planner running, while no card is being grilled or prototyped; the session starts a grill, or a prototype for UI work, on it.
+_Avoid_: auto-start, idle pickup
+
+**Auto-triage**:
+The board's `auto_triage` setting, off by default, which reads "Triage Todo when idle" in Board settings' Todo section and turns on or off with no confirmation. On, while the board is idle as for **Auto-pull** and Todo changed since the last triage, at most once a host day and before any pull, the board server declares topic `todo-triage-<date>` ("Todo triage <date>") and sends `todo-triage {date, topic}`. The session looks for duplicates, cards a newer card covers, cards ready to close and stale deps: it links and merges clear duplicates itself, asks one question per other finding on that topic, and replies to the event, which lets the pull go ([0165](docs/adr/0165-an-idle-board-triages-its-todo-once-a-day.md)).
+_Avoid_: cleanup, grooming
+
+**Notes**:
+The owning session's understanding of a work item so far: what was asked, what is settled, what is open. A Markdown file in its wave's folder that the item names in `plan` (`item set --notes-file`), rewritten as the grill settles things, or with no file the item's short `notes` text. "Notes ↗" opens them as a page sized for the phone, first on the open card's final details line before Install and Review on GitHub; the board keeps no summary of them and a card with no notes omits the link. The thread keeps the short news ([0053](docs/adr/0053-notes-replace-the-full-plan-and-cards-start-on-their-own.md), [0062](docs/adr/0062-notes-is-a-link-in-the-details-list.md), [0067](docs/adr/0067-a-cards-external-links-share-the-last-details-line.md)).
+_Avoid_: full plan, plan, spec
+
+**Held**:
+A work card the owner paused with its Hold button, which opens the shared duration picker: Forever, until the owner taps Unhold, or until a time, its **pick-up time**. Hold and Unhold apply on the board at once, and the board server writes them to the wave file with the owner's thread line ([0131](docs/adr/0131-the-cli-and-board-server-do-the-boards-housekeeping.md)). It doesn't start, and the session stops work on a running one, until it is resumed (a held Todo card's Build resumes and starts it, [0141](docs/adr/0141-a-held-todo-card-shows-build-in-place-of-unhold.md)) ([0106](docs/adr/0106-the-board-applies-the-owners-hold-resume-and-done-at-once.md)). The card's last line reads "held" or "held until Wed 9:00 am" after its time. A card that leaves Todo is never still held: any write that takes it out (`item set --status building`, `fixing`, `checking`, `done`, `merged` or `dropped`, `--pr`, `--pushed`) clears the hold and its pick-up time, and the board shows held only on a Todo card. Every other action-row button, Unhold included, asks to confirm first, through `B.confirm` (`dialogs.js`).
+_Avoid_: paused, frozen, on hold (as a status name)
+
+**Pick-up time**:
+When a card held until a time resumes itself: `pick_up_at` in its wave file (`board.mjs item set --pick-up-at`), or the `until` of the owner's newer `card-hold`. Within a minute of it the board server resumes the card, writes a thread line, and sends `card-unblocked {key, until}` unless a dep is unfinished, so it starts on its own once nothing else blocks it ([0118](docs/adr/0118-a-card-can-be-held-until-a-time.md)). A bump doesn't skip it; resume the card or change the time to start early. It is separate from a Linear due date.
+_Avoid_: due date, reminder, snooze (for a card)
+
+**Builder**:
+An agent (Claude Opus, Claude Sonnet, Codex…) working on a work item, which owner-facing words call an implementer ([0166](docs/adr/0166-a-todo-cards-button-reads-implement.md)), with one builder record each (`board.mjs builder … --agent <name>`; the first is `main`). The record holds its label, kind (claude or codex; a record written as opus or sonnet reads as claude with that model), model (opus or sonnet for claude, set by `builder start --model`, which prints "model: Claude Sonnet"), start, ETA and finish, not its progress. Each progress line (`builder progress --phase <phase> "<detail>"`, which needs `--site`) goes only to the card's thread, as a **status line**: a phase, Reading, Building, Testing, Checking or Landing, and a detail of at most 80 characters, refused when longer ("Testing: fix for the scroll jump"; another agent's reads "Codex testing: …"), shown as one line with no bubble. Status lines written before phases stay as written ([0137](docs/adr/0137-a-builder-status-line-is-a-phase-and-a-short-detail.md)). The card's status line under its title is the thread's newest status line since its earliest running agent started, its phase first ("Testing · fix for the scroll jump · 3m ago"), or "Starting" before the first, with its age, behind a pulsing dot as Orchestrator review and Working on it have, and, once a status line has a phase, five bars at the end of the card's time row, after its unread count, finished phases filled and the current one pulsing, only on an In Progress card while a builder runs ([0160](docs/adr/0160-a-building-cards-phase-bars-end-its-time-row.md)), and an optional "ETA about 4:30 pm" line under that (owner ask on INT-76). In the thread every implementer's status line stays orange, dot included, whether its agent is working or done (owner, card INT-77). `builder done` marks the record done and keeps it; closing the card’s last open builder record clears its building or fixing status. Linking a PR clears either status too. The thread shows each record as **agent lines** among its messages, with no bubble: "Claude Opus implementer started" (or "Claude Sonnet implementer", "Codex implementer"; the model, not the label, names it, a label's builder reading implementer) at its start, always orange and with its ETA while the agent runs, and "Claude Opus implementer finished" at its finish, the only green one (owner, question `int42-agents-look`, option C; owner ask on INT-63). The session's own thread summary closes the work. A builder is a **planner** or an **implementer**: planners are the grill and prototype agents, which write no output code; every other kind is an implementer. A planner's model defaults to Sonnet for a prototype and Opus for a grill ("Claude Sonnet prototype started"); its status and started lines are the owner's blue (`--accent`, the one human blue, [0169](docs/adr/0169-one-human-blue.md)), on a Todo card too, never with phase bars; while a build runs, the build's line wins on the card; and a running planner leaves the board idle for the idle pull ([0167](docs/adr/0167-planners-and-implementers-are-two-kinds-of-agent.md)). The kind words are for code and ADRs; the screen says what each agent does.
+_Avoid_: worker, bot
+
+**Dispatched record**:
+A builder record the session opens with `builder start --dispatch` right before it launches an agent of any kind (build, prototype, grill), so the card's builder line reads "Starting" from the launch and not from the agent's own start. The agent's own `builder start` takes it up as it does a `tapped` record: the kind, a Claude model and the worktree stay, the record starts again at now and is no longer dispatched. The session never posts "a builder is working" itself ([0152](docs/adr/0152-the-session-opens-the-builder-record-when-it-dispatches-an-agent.md)).
+_Avoid_: pre-start, placeholder record
+
+**Judgment call**:
+A decision a builder makes that its brief didn't settle, recorded on its builder record as it makes it (`builder call <key> "<call>"`, one plain line), or a "Question: …" it asks the session before building. The thread shows a record's calls as one collapsed entry under its agent lines. The session checks them against the owner's words and the other cards and marks the record **verified** (`builder verified`); `land` refuses while a record on the card has a call after that mark. A builder start on a record with unverified calls resumes that build, calls and worktree kept ([0155](docs/adr/0155-a-builder-records-its-judgment-calls-and-the-session-verifies-them.md)).
+_Avoid_: guess, assumption, decision log
+
+**Stalled**:
+A builder still recorded as running whose last progress, or start before its first progress, was at least 30 minutes ago. Its card carries a red Stalled button until fresh progress or completion; silence calls for a check, without establishing that the process has failed.
+_Avoid_: stuck, hung, failed
+
+**Worktree**:
+The git worktree a builder works in, never the folder the session, a running app or the hub uses. A board's is `~/.claude/kickflip/worktrees/<card id>` on branch `<card id>` from its chosen repo branch, or from local main for a **local board**, of the board's own folder, the hub board's included (`hub/board-repo.mjs` decides which), made by `board.mjs builder start --worktree` and kept on the builder record; the owning session checks and commits there, then **lands** it (`board.mjs land`): rebased onto main, tested, fast-forwarded into the live folder's main, the hub or board servers restarted, the worktree and branch removed. A repo card's comes from wave-build ([0064](docs/adr/0064-every-builder-works-in-a-worktree.md)).
+_Avoid_: copy, checkout, live folder (for the builder's)
+
+### Talking with the owner
+
+**New task**:
+A free-form request or question the owner sends from the board's + button (or by pressing n twice). Code and events call it an **ask**: an `ask` event whose thread is `ask:<event id>`. It is a **New card** at the top of Todo, with no wave and no Action needed, until Claude sorts it one of three ways ([0047](docs/adr/0047-the-plus-makes-a-new-card.md)): files it under a wave as a work item, whose thread opens with it (`item set --from-ask`), and sets its **card state**; folds it into the card it's about, whose thread then holds the message marked Moved (`item relate-ask`, undone by `ask unfold`); or answers it, which puts it in the Asks lane below Done, named by when it was asked, whose thread takes the owner's later replies ([0144](docs/adr/0144-answered-asks-have-their-own-section-below-done.md)). An answer that leaves a question open on it keeps it in Todo with Action needed, never in Asks, until the owner answers and Claude replies, or it is closed; it stays in Todo while Claude takes up the answer ([0059](docs/adr/0059-an-unstarted-card-waits-on-its-questions-in-todo.md)). When another board fits it better, the owner can have it **moved there** (`ask move`): it becomes a New card on that board reading "Moved from <this board>", and here a Done card whose thread links to it. Folding is within one board; a move is between boards. An answer that waits on the owner, such as a choice only the owner can settle, keeps it in In Review with Action needed until the owner taps Mark as done or the Done in its thread ([0035](docs/adr/0035-an-ask-can-wait-in-progress-until-the-owner-marks-it-done.md)).
+_Avoid_: ask (in what the owner reads), message, prompt, Waiting for Claude strip
+
+**Thread**:
+The conversation on one work item: Claude's reports, builders' status lines, the owner's messages, mirrored GitHub comments, and answers to the item's questions. On a card not in Done, its reply form has a Done, left of Send, that closes the card ([0035](docs/adr/0035-an-ask-can-wait-in-progress-until-the-owner-marks-it-done.md)).
+An open card shows its thread's newest 3 messages as it opens, or from its oldest **unread message** when more than 3 messages follow it, at most 10, unread as of when the card opened. Messages that arrive while it is open add below, hiding none. Messages are the owner's, Claude's (replies included) and other people's; builder, status and ask-link lines show among the messages they sit between and don't count. "Show more · N previous messages" at the top adds the next 3 older messages each tap and goes when nothing older is left. The expansion lasts while the card stays open, through repaints and new messages, and closing the card puts it back to 3. A message being edited always shows, with every line after it; one waiting on Claude shows only where the window reaches it.
+An owner message Claude hasn't answered yet ends with **Waiting for Claude…**, or Working on it while Claude is on it. An answer to a question stops waiting once it's acted on: its question resolved after it, a later prototype round on it, or a build started on the card after it ([0157](docs/adr/0157-an-answer-stops-waiting-once-its-acted-on.md)). A batch of the owner's answers in a row in the same state carries it once, under the last answer.
+_Avoid_: comments, chat
+
+**Unread message**:
+A message in a card's thread from Claude (replies included) or GitHub, newer than when this browser last opened that thread. The owner's own lines, their copied-in answers included, other people's Slack lines, and builder, status and ask-link lines are never unread. The card's last line ends with their count in the accent colour, after any hold, as "3:00 PM · held until Wed 9:00 am · 3 new messages", until it is opened.
+_Avoid_: inbox, notification. "New" names it only in that count's "N new messages"; a New card is an unsorted ask.
+
+**Last visit**:
+The board and threads this device last showed, kept in its browser storage. The next visit paints it dimmed at first paint, readable at any age, with the controls that send held until the fresh board lands and replaces it in place, flashing a fading blue border round each lane count, Needs you line or thread message that changed ([0028](docs/adr/0028-the-board-opens-on-the-last-visit.md)); a card that changed shows its own sign ([0135](docs/adr/0135-an-updated-card-takes-a-brief-tint.md)). A board the app shell left fresh and comes back to with no change since paints it live instead ([0055](docs/adr/0055-one-app-for-the-whole-hub.md)). It paints only under the build that saved it, a hash of the shell's file versions (`hub/shell.mjs` `shellHtml`), so code that changed since never reads it; the page then waits for the fresh board. In code it is the snapshot.
+_Avoid_: cache, offline copy, stale board
+
+**Answer banner**:
+The one line at the top of a board, above Needs you, naming new tasks Claude answered without making work whose answer this browser hasn't seen: "1 answer · <ask>" or "2 answers · <newest> and 1 more". A tap opens the newest one's card; ✕ hides it on this device until a newer answer. No push goes for an answer ([0006](docs/adr/0006-pushes-only-when-something-waits-on-the-owner.md)).
+_Avoid_: notification, toast
+
+**Owner question**:
+A multiple-choice question Claude needs the owner to decide, attached to a topic. A builder's judgement call becomes one. One marked **urgent** blocks a build or a merge and shows alone; Claude resolves a question in the step that acts on its answer ([0043](docs/adr/0043-needs-you-gathers-what-waits-and-questions-answer-on-one-page.md)), except an answer with a note and no option, which resolves its question as it arrives ([0114](docs/adr/0114-a-pick-with-no-note-settles-a-prototype-round.md)), and recording a card's close in the wave file resolves each of its questions that has an answer; one with no answer yet stops that write unless forced. The owner's Done still moves the card on the board at once ([0106](docs/adr/0106-the-board-applies-the-owners-hold-resume-and-done-at-once.md)). Adding a question on the same card or setting its notes file resolves answered questions still waiting on Claude; once a card's Action needed is gone, the board server drops its queued push ([0133](docs/adr/0133-the-board-records-what-it-knows-and-commands-make-the-rule-calls.md)).
+_Avoid_: poll, decision card
+
+**Topic**:
+The group an owner question belongs to; an item's questions use the topic `item:<wave>/<id>`. A Done card's topic with no open question is resolved, so it never waits on Claude.
+_Avoid_: category, section
+
+**Needs you**:
+The orange box at the top of a board listing what waits on the owner, one line per work item, led by the board session's **pending prompts** ([0043](docs/adr/0043-needs-you-gathers-what-waits-and-questions-answer-on-one-page.md)).
+_Avoid_: inbox, digest
+
+**Pending prompt**:
+A permission prompt or `AskUserQuestion` from a background board session, which its hook hands to the hub and holds the session on until the owner answers in the board's Needs you, or the hub page for a session that owns no board: Allow once, Always allow or Deny, or the question's options. Always allow returns the session rule to Claude Code and keeps that same rule in the hub's `prompts.json`, keyed by session id. The hub remembers rules only with a reliable process start time and binds board rules to the current ownership's `owner.since`; ownership commands clear remembered rules and pending prompts for both the old and new sessions, including boardless entries, even while the hub is stopped. A later exact match on its command, absolute path, domain or bare tool name is allowed immediately, with no push or Needs you line; prefixes and globs never widen a match, and `AskUserQuestion` always asks. Rules end when the session stops or its board's owning session changes, and the hub page lists them read-only under the board. With no answer in 10 minutes the call is denied with a note to ask on the card instead ([0060](docs/adr/0060-background-sessions-prompts-come-to-the-phone.md)).
+_Avoid_: permission request, approval, dialog
+
+**Event**:
+A signal that wakes the owning session: something the owner did on a page (an ask, an answer, a button), or a board change such as `card-unblocked {key}` when a waiting card’s last unfinished dependency finishes ([0020](docs/adr/0020-cards-wait-on-explicit-blocked-by-links.md)), unless its build is a **queued build**, which the board server starts itself ([0145](docs/adr/0145-build-on-a-blocked-card-queues-it.md)).
+_Avoid_: action, request
+
+**Rule**:
+A standing instruction from the owner to the sessions that own boards, one line of text kept on Settings. Hub rules apply to every board; each board adds its own on top. The watcher prints both with every wake, and a save wakes each session to say what changes. One Claude codified on the owner's word reads "Added by Claude" ([0039](docs/adr/0039-rules-live-on-settings-at-hub-and-board-level.md)).
+_Avoid_: preference, setting, policy
+
+**Reply**:
+Claude's answer to one event, shown under it on the page.
+_Avoid_: response, comment
+
+**Pending message**:
+A New card's message, or the owner's message in a thread, that Claude hasn't answered yet: no reply, no later Claude line on its card other than a builder status line or agent line, no later reply to its card's ask, its ask not turned or folded into a card, and its card not closed since the watcher marked it. It reads "Working on it" once the watcher prints it to the session, and the owner can edit or delete it. While one goes unanswered, the watcher Stop hook keeps the owning session's turn from ending once, naming it ([0133](docs/adr/0133-the-board-records-what-it-knows-and-commands-make-the-rule-calls.md)).
+_Avoid_: unread, queued
+
+
+**Prototype**:
+A page that shows each option of one owner question as it would ship, built from the board's real components fed fake data. An agent records it with `board.mjs prototype add <topic>` in the site's `data/prototypes.json`, with its title, card and takes, and writes only the take files; the board serves `prototype-<topic>.html` from its one template, `board/public/prototype.html`. `question add` accepts a prototype url only for a recorded topic, with option ids a non-empty subset of its take keys in order, without repeats, and every take file written ([0089](docs/adr/0089-the-board-serves-every-prototype-from-one-template.md)).
+_Avoid_: mockup, demo page
+
+**Prototype round**:
+One set of takes for an owner question, numbered per topic: the question the session posts with `round_of` naming the question it answers. A topic's head shows its latest round, orange while being made, blue while back and grey "Round N closed · take X" once a pick settles it, with a note or none, the note being the build's guidance. An answer with a note and no take leaves the card unready to build until a take is picked; the eye on a round question, or such a note asking for another prototype, starts the next round ([0111](docs/adr/0111-a-prototype-round-ends-with-a-one-take-confirm.md), [0114](docs/adr/0114-a-pick-with-no-note-settles-a-prototype-round.md), [0150](docs/adr/0150-a-prototype-pick-is-the-builds-go.md)).
+_Avoid_: iteration, pass
+
+**Confirm**:
+The one-option "Is this it?" question on a take the owner picked with a note, which sessions opened with `question confirm` before a pick became the build's go. Confirms already on a board still render, and an answer to one settles its round; nothing opens new ones ([0116](docs/adr/0116-a-confirm-waits-for-claudes-update.md), [0150](docs/adr/0150-a-prototype-pick-is-the-builds-go.md)).
+_Avoid_: confirm round, re-grill, final check
+
+**Prototype request**:
+The owner asking, from a card's thread or with a question's eye on Waiting on you, for throwaway prototype pages to compare options. One from Waiting on you names its question, which reads Prototype requested, with answering off, until its round arrives ([0111](docs/adr/0111-a-prototype-round-ends-with-a-one-take-confirm.md), [0126](docs/adr/0126-each-question-has-its-own-prototype-eye.md)). Each prototype comes with an open question on its card, and the page's switcher can send the pick; until the owner picks, the card carries Action needed and keeps its lane, Todo while it hasn't started ([0015](docs/adr/0015-prototypes-come-on-request.md), [0059](docs/adr/0059-an-unstarted-card-waits-on-its-questions-in-todo.md)).
+_Avoid_: mockup request, preview
+
+**Take**:
+One option of an owner question shown as what it would be: a framed prototype, or a diagram of boxes and arrows with what it means in practice. A prototype's take is a key (one capital letter), a label and a file, `public/prototypes/<topic>/<KEY>.js`, whose `render(stage, kit)` draws it into the page's stage. Waiting on you keeps takes in option order with the recommended one tagged: small takes share a grid, while a question with a single take, or with any scrolling or full-screen prototype, shows a choice row above one full-width take, which a choice switches in place, followed by the note and Send ([0048](docs/adr/0048-a-questions-takes-show-inline.md), [0089](docs/adr/0089-the-board-serves-every-prototype-from-one-template.md)).
+_Avoid_: variant (the switcher's URL parameter, not the word), mockup
+
+**Kit**:
+What a prototype's take gets as `render`'s second argument, from `board/public/prototype-kit.js`: the real sidebar, Hub page, cards and a sheet drawn in the stage's flow, fake data, a toast and `kit.on`. Inside the stage a link or form only toasts, and the listeners and timers a take adds end when another take shows ([0089](docs/adr/0089-the-board-serves-every-prototype-from-one-template.md)).
+_Avoid_: harness, helpers
+
+## Board page files
+
+The board page's scripts in `board/public/` are plain scripts with no bundler, loaded in the order `app.html`, the app shell, lists them, from `/_hub/app/`. The `ui*.js` files hold pure renderers on the `BoardUI` global, which `ui.test.mjs` tests. `app.js` defines `BoardView`, and each `app-*.js` file after it registers one part of the board view with `BoardView.part((B) => …)`. `BoardView.create(root, site, opts)` gives each board its own `B` (state, `ClaudeSite.site`, store, and a `$` scoped to the view's root), and a part adds listeners, intervals, timers, watches and unmount steps only through `B.on`, `B.every`, `B.later`, `B.watch` and `B.atUnmount`, so `unmount()` leaves none behind; `view.test.mjs` checks that. Nothing waits while the owner types: a repaint patches the lanes and each thread in place, and a box being typed in keeps its text, cursor and focus ([0057](docs/adr/0057-a-repaint-patches-in-place-so-nothing-waits-while-you-type.md)). An open card moves to its new place at once and the page follows it: the box being typed in, else the open card's title row, stays where it was on screen ([0063](docs/adr/0063-an-open-card-moves-at-once-and-the-page-follows-it.md)); `view.test.mjs` checks both on a board mounted on `board/mini-dom.mjs`, a small DOM. The board's other views (`view-*.js`) get the same site, `$` and recorders from `BoardView.page(root, site, run)`. The view's state, such as `offline` and `data-board`, sits on its root (`.view-board`), not on `<body>`. A site card names the files it expects to touch from this table ([0022](docs/adr/0022-site-cards-build-in-parallel-when-their-files-dont-overlap.md)).
+
+Refs in text that Claude or the owner wrote are linked by the renderer, never by hand: pass the text through `ui-links.js` (`linkText`, or `linkHtml` for an HTML reply or line) with the item's `linkContext`. A card's ref (`INT-<n>`, `#n` for a GitHub ticket, or any `ref` on the board) or its id opens its card, a Linear id or PR opens its page, and a bare URL becomes a link. Write refs as plain text in thread lines, replies, questions and plans.
+
+| File | Owns |
+| --- | --- |
+| `../hub/try.mjs` | Hub-owned card and main runs, async git tick, branch fetches, proxy lookup, idle cleanup and atomic try state |
+| `../build-script.mjs` | Fixed build script file, ownership, permissions and executable checks |
+| `../shared/usage-gate.mjs` | The pause line, Keep going, Codex handoff and file reader shared by the hub, CLI, hooks, watcher and builder start |
+| `../shared/colors.css` | Every color, served as `colors.css` and linked before `style.css`; the hub serves it as `/_hub/colors.css` |
+| `ui.js` | Shared helpers: escaping, times, reply bodies, attachments, icons and message buttons, badges by tone, `setHTML`, which patches a region in place and keeps the focused field's focus when it moves, and `fetchJSON`, through which the side pages read the API and wait out a board restart |
+| `ui-links.js` | Linking refs, Linear ids, PRs and URLs in written text; load it right after `ui.js` |
+| `ui-enums.js` | `BoardUI.BUTTON` and `BoardUI.ACTION_KIND`, the **action button**'s enums, shared with `board/domain.mjs`, which runs it in a vm context; load it before `ui-threads.js` and `ui-cards.js`. `view.test.mjs` checks that every action kind makes one button orange and every action button draws |
+| `ui-order.js` | `BoardUI.laneOrder`, the board's order of its items ([0140](docs/adr/0140-each-lane-has-one-fixed-order.md)), shared with `board/domain.mjs`, which runs it in a vm context, so a tap the page draws at once lands where the server puts it |
+| `ui-cards.js` | A card's lines, in order: title with its ticket badge, or New chip on an unsorted ask (none once sorted); status with its ETA; Stalled when the builder is silent, then PR, review and other chips, then the try badge (Visit or Install, with running, failed and stale states); its lineup's grey wave chip; last the time its lane sorts by, its hold, blocked by, Action needed and its unread count; the Hold sheet's picker; and at its top right a New card's bump, edit and delete icons, or another bumpable card's bump icon, filled orange once bumped; and the action row's Merge and Serve/Build buttons, main's bar and build wording |
+| `ui-sidebar.js` | `BoardUI.sidebar`, the sidebar's markup from `/_hub/sidebar.json`, with the New version row from `updateRow`, Reload or the npm update's Upgrade, headed by `BoardUI.header` itself, with each row's key in **switch mode**; `switchKeys`, which row each key opens; `othersWaiting`, for the logo's label; and `shortcuts`, the **shortcuts sheet**'s content from the one list of shortcuts. Needs `ui-page-header.js` loaded before it: `hub/hub.mjs` renders the app shell's first sidebar with both in a vm context |
+| `sidebar.js` | Painting the sidebar from the copy written into the shell, else this device's last copy, then from each copy the hub's stream sends; this device's push subscription for its Turn on row; the logo's toggle, the drawer and its swipes, the rail's collapse, which this device keeps, and the logo's label; **switch mode**'s keys, from the document and a framed page, each row opened through the shell; the **shortcuts sheet**'s h h and Escape |
+| `app.html` | The app shell: the sidebar, the view's slot, and its scripts and CSS from `/_hub/app/`, with a board's loads started in its `<head>`; the hub serves it for a browser's load of `/` or a site's page outside try URLs, and every load of a hub page, with the sidebar and its data written in (`hub/shell.mjs` `pageOf`), and the board server for a board's four view paths without them (`shellHtml`) |
+| `router.js` | `AppRouter`: every hub URL as a view and each view as its URL (`ui.test.mjs` tests both), the views the shell mounts in place, framed pages included, and catching taps on links to them and back and forward, with `{idx}` in each history entry and `pushed` on one a push opened; a back arrow goes one step back by them. On the **page tree** each entry also carries `up`, how many of its parents sit under it, which the router writes on every way in, and the arrow goes up a level. It frames the paths `hub/shell.mjs` `pageOf` answers with the shell, which `hub/shell.test.mjs` checks |
+| `shell.js` | `AppShell`: the hub code check that shows New version with an owner-tapped Reload, the sidebar mounted once, one view at a time, asking before leaving an unsaved edit, `/`'s pick of a board, the hub's one stream and which left boards are unchanged, a framed page's URL and title copied to the top, a push tap from `hub/sw.js` or a framed page's view URL (`AppShell.open`) routed in place, and registering `hub/sw.js`, which opens the shell while the host is asleep |
+| `view-settings.js` | Board Settings as a modal over its board, which shell.js mounts: repo and branch (Change uses the same list and GitHub link search as New board), | `view-settings.js` | Board Settings as a modal over its board, which shell.js mounts: repo and branch (Change uses the same list and GitHub link search as New board), ticket source, auto-merge, auto-build, auto-pull, auto-triage, reviewers, rules and Close board with its typed-name sheet |
+| `view-questions.js` | Waiting on you as a view: a topic's questions, their takes framed with `?take=` in a fitting grid or a chooser above one full-width frame, which a choice switches in place through the frame's `PrototypeSwitcher.current`, each question's eye, which asks for a prototype of that question, and one Send, which stays while the topic has a question open and otherwise opens the next topic with one, or goes back to the board |
+| `view-notes.js` | One item's notes, or with `?wave=` a lineup's goal, order and note, as a view, from `GET /api/notes`; the server redirects `plan.html` to `notes.html` |
+| `view-hub.js` | The **hub page** as a view, from `/_hub/api/hub`, refreshed every 30 seconds while it shows; the Usage card, whose Claude model posts `/_hub/settings/claude-model`, Codex share posts `/_hub/settings/codex` and pause line posts `/_hub/settings/pause-at`, with Keep going and Stop banners posting `/_hub/settings/keep-going`, pending prompts of sessions with no board, Send now, then `view-hub-settings.js` below its status |
+| `view-hub-settings.js` | Summary rows opening **hub settings** modals over the hub page, from `/_hub/api/settings`: Notifications with Snooze and Keep awake with their one duration picker (`durationPicker`: chips and a native Custom picker), Polling, Linear (`linear-key.js`’s slot), Rules for every board and Closed boards with Reopen |
+| `linear-key.js` | `LinearKey`, Hub’s Linear key slot: the masked key or why it doesn’t work, the link to where keys are made, saving on paste, change or Enter with Remove, and the same slot as a modal over Board Settings or New board, which the Tickets control opens when Linear is tapped without a working key |
+| `view-polling.js` | The editor in Hub’s Polling modal, from `/_hub/api/polling`: the day bar, whose taps pick a window without asking the hub, each window's edits, the overnight hold, the daily wakes and Send now |
+| `ui-hub.js` | `HubUI`, the hub views' pure renderers: rows, tiles, the flash, the Now row, this device's row, pause banners and the Usage card with the pause line stepper and ticks |
+| `hub-kit.js` | `HubKit`, what the hub views share: `live` (load, the header's time and ↻, the 30-second refresh), `forms` (posting a hub form for JSON, and saving a toggle or time on change) and `device` (this device's push subscription) |
+| `view-frame.js` | Any other page as a frame view: the frame beside the board header with Open alone ↗, hiding that header for a page that draws its own, whose logo then toggles the sidebar; each load's URL and title to the shell, and taps on links to other views sent to it, a prototype's back arrow included, which the shell takes up the **page tree** before the page's own script can |
+| `sidebar.css` | The sidebar's rail, its collapse, the drawer and switch mode, plus the shared New board dialog and the shortcuts sheet; linked after `colors.css` |
+| `hub.css` | The hub views' CSS and the hub's down page's, every rule under `.hub-view`, the class on a hub view's root, on the down page's `<html>` and on the board's Hold sheet picker, which shares the duration picker's rules; the shell links it after `style.css`, whose header the hub views share, and the down page as `/_hub/hub.css` |
+| `ui-page-header.js` | `BoardUI.header`, every page's header: the logo (which toggles the sidebar), a back arrow where needed (beside a phone-only logo), the title, then the time and ↻, a board's bulb, and the gear, or a page's own trail. On a page of its own, the back arrow's own script goes one step back, or to its href after a push; in the app shell `router.js` does that. Needs nothing else: `server.mjs` renders each page's `<!--header {…}-->` with it, such as a prototype's, and `hub/hub.mjs` the shell's first sidebar, whose head is one too (`ui-sidebar.js`), each in a vm context |
+| `ui-header.js` | The header's time, or Paused until from the shell's pause state, and when it moves, the GitHub status line and its Hub links mark, the Hub links list, the setup checklist, when a refresh asks for a GitHub check, and which board header controls take taps |
+| `ui-threads.js` | Thread messages, with link, status and agent lines, the open card's window over them with its Show more, and the reply form's Done |
+| `ui-questions.js` | Owner question cards with their takes inline and diagrams, answer history, prototype status, a confirm's take link, the topic head's round chip and the Waiting on you topic row; `BoardUI.nextQuestion`, the pure move-on rule shared by Send and a prototype pick, and `sentNotice`, the Sent line the board reads on return |
+| `ui-markdown.js` | The Markdown subset `view-notes.js` renders a card's notes with |
+| `ui-snapshot.js` | The last visit's stored shape and size cap, which threads preload, which controls wait for the fresh board, which lines flash, and what counts as a card's update |
+| `attach.js` | Picking and uploading attachments, each to the site of the board view around its composer |
+| `prototype.html` | The one prototype page: the server fills in a recorded topic's title, header and takes; the stage that contains each take, and the pill's room below it |
+| `prototype-kit.js` | The **kit** and the take loader: each switch ends the last take's cleanup, listeners and timers, renders the next into a fresh stage at the same scroll position, and turns links and forms in the stage into toasts; `prototype-kit.test.mjs` tests it |
+| `prototype-switcher.js` | A prototype page's ‹ take › pill, its keys and `?variant=`, one take alone with `?take=`, `PrototypeSwitcher.current.go(key)` for an in-place switch from Waiting on you, and with `?q=` the pick and note that answer the card's question, then the next open question in its place as a Send moves on, or with none left the board, handed to the app shell when the page is framed in it, with the board’s Sent notice in that top window; uses the shell’s `BoardUI` or loads its question helpers when opened alone; `prototype-switcher.test.mjs` tests its controls and a pick through `mount`, while `ui.test.mjs` owns the move-on rule |
+| `app-core.js` | The view's shared helpers: drafts, seen marks, hiding, and `steady`, which runs a repaint keeping the box being typed in, else the open card's title row, still on screen, and its focus and cursor; where the owner left the board, its scroll and box, kept through `B.keep` and restored after its next first render in the page; re-exports `dialogs.js` as `B.confirm` and `notice` |
+| `dialogs.js` | `BoardDialogs.confirm` and `notice`, which every board page's dialogs go through, and `fitSheet`, the sheets’ shared phone keyboard handling, `repoSheet` for New board and Repo → Change, and `ticketsControl`, shared by New board and Board Settings, which opens `linear-key.js`’s modal for Linear without a working key; loaded on every page |
+| `rules-editor.js` | `RulesEditor`, the rules list on Board Settings and the Hub page, with its own CSS; `ui.test.mjs` tests its pure parts |
+| `app-threads.js` | Loading a thread, once at a time per card; an open card's thread, its reply box, quick replies and Done |
+| `app-cards.js` | Cards, their open detail with the details list ending in Notes ↗ · Visit/Install ↗ · Review on GitHub ↗ when present, and the workflow row: Merge, Hold, the **action button**, Serve/Build and rightmost **Implement**, each confirming but Hold, which opens its sheet with the duration picker; try requests, failure-thread links and main’s failed-build log and Retry sheet; the bump icon's bump and unbump, with no confirmation; an ask's detail shows only its action button; the thread's Done confirmation and send |
+| `app-lanes.js` | Lanes, Done's and Asks' Show more, Done's finished-wave folds, the **Waves section** with its filter and Triage, and Plan waves |
+| `app-asks.js` | The + sheet and its press-n-twice shortcut, and bump, edit and delete |
+| `app-needs.js` | The Needs you box, led by the board session's pending prompts |
+| `ui-prompts.js` | A pending prompt's Needs you line: its details, Allow once, Always allow and Deny, or a question's options, Skip and Send |
+| `prompts.js` | `PromptAnswers`, answering pending prompts from their lines on a board and the hub page: which taps send at once, Always allow's confirmation, and the picks a Send waits on |
+| `app-arch.js` | The header's bulb and its **architecture review** sheet: the last review, Run with its confirm, what a review waits on, and the bulb's glow while one runs |
+| `app-banner.js` | The answer banner, its tap and its ✕ |
+| `app-header.js` | The board's header controls and time, refresh, the offline state, the In Review header's GitHub line, the Hub links sheet and the setup checklist |
+| `app-snapshot.js` | Reading and saving the last visit, also as the view unmounts, keeping every board's within three at the cap, holding the controls that send while it shows, the flash when the fresh board lands, and each card's sign: the flash on a card that changed lanes or took a New task's place, and the tint on a card otherwise updated, unless the owner changed it from this page |
+| `app.js` | `BoardView`: each board's `B`, its state and per-board store, mount and unmount, what each part keeps through `B.keep` for the board's next mount in the page (`B.place`), and the view's markup for the app shell; rendering main's slim bar and the view from its parts, painting the last visit, live when the shell says nothing changed, loading the board with its open threads (taking over the loads `app.html` starts), `B.send`, which sends an **owner tap**, draws it at once and lands the board the POST answers with, and the bump icon's fade, preloading active cards' threads, the reload timers, and the change signal from the shell |