tuiboard 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -5,7 +5,35 @@ All notable changes to **tuiboard** are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.11.0] - 2026-09-16
+
+### Fixed
+- **Zoomed column titles no longer truncate short of the available width.**
+  The zoomed `<TaskRow>` read a hardcoded `availableWidth` of `100` regardless
+  of the terminal's real size, and a separate 60-character cap on the title
+  never lifted for zoomed columns — together they clipped titles well before
+  the column's actual right edge, sometimes with a garbled double-truncation
+  (`walk t...gh backgro…`). The real measured viewport width now drives the
+  budget, the cap lifts when zoomed, and the width is re-measured on
+  zoom-toggle and terminal resize. Thanks @ArjunAnil2000.
+- **A board's configured display `name` no longer reverts to the filename on
+  an external edit.** `loadAll()` applied `config.boards[].name` on startup,
+  but the file-watcher's reload path re-parsed the board from disk without
+  reapplying it, so any edit made outside tuiboard (another editor, a sync
+  tool, a script) silently renamed the board back to its filename-derived
+  default. The reload path now reapplies the configured name, matched by
+  filepath, the same way the initial load already did. Thanks @ArjunAnil2000.
+
+### Changed
+- **Keyboard reference (`?`) restyle + scroll.** The help modal now groups
+  shortcuts under emoji section headers, color-codes the key (accent) vs. its
+  description (dim) with a dotted leader between them, and wraps long
+  descriptions into their own aligned column (no more continuation text running
+  under the keys). The whole reference now lives in a scrollbox so it never
+  clips on short terminals — `j`/`k` (or arrows) scroll it. Shortcut text is
+  unchanged, except that two entries missing from the rewrite (`+` New board,
+  `c` copy resume command in the Agents zone — both real, both still bound)
+  were restored during review. Thanks @k0-ba.
 
 ## [0.10.0] - 2026-09-09
 
@@ -77,6 +105,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   that folder's sync and versioning; the fallback is `~/.local/share/tuiboard/boards/`.
 
 ### Fixed
+- **A fresh install could crash on the `~/*` path alias**
+  (`Cannot find module '~/ui/splash-boot'`) — `tsconfig.json` wasn't in the
+  published `files` list yet. Fixed as a side effect of the packaging cleanup
+  below, but never called out on its own at the time; three users hit it on
+  0.8.3/0.8.4 and filed independent issues before this line existed. Noted
+  retroactively on 2026-09-16.
 - **The key hints no longer truncate mid-word on a narrow terminal.** The
   bottom bar is a 130-character line that truncates rather than wraps, so at 60
   columns it read `⏎ don…schedule`. In single-pane it keeps only the keys that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tuiboard",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Terminal kanban for markdown task boards, with optional Today/Tomorrow planner, 24h agenda + calendar overlay, and a live Claude Code agent view. Use only the panels you want.",
   "type": "module",
   "license": "MIT",

package/src/input/handleKey.ts

@@ -104,6 +104,12 @@ export function handleKey(
       store.closeModal();
       return;
     }
+    // Help modal: j/k (or arrows) scroll its keyboard reference.
+    if (ui.modal.kind === "help") {
+      if (key.name === "j" || key.name === "down") { store.setHelpScroll(ui.helpScroll + 1); return; }
+      if (key.name === "k" || key.name === "up")   { store.setHelpScroll(ui.helpScroll - 1); return; }
+      return;
+    }
     // New-event modal: step 1 typing goes to the <input>; step 2 (no input
     // focused) is the calendar picker, driven here.
     if (ui.modal.kind === "event") {

package/src/store/index.ts

@@ -243,6 +243,12 @@ export interface UIState {
    * entries and the calendar overlay. Changed with `[` / `]`; `\` resets to 0.
    */
   agendaOffset: number;
+  /**
+   * Vertical scroll position of the help modal, as a block index (0 = top).
+   * `?` opens the help at 0; `j`/`k` step it. The HelpModal component clamps
+   * the upper bound (it knows the block count) and scrolls that block into view.
+   */
+  helpScroll: number;
   view: ViewMode;
   /**
    * Tasks marked for bulk ops (`Space`). Key format:
@@ -339,6 +345,7 @@ export function createTuiStore({ config }: CreateStoreOptions) {
       grabbing: false,
       armMode: false,
       agendaOffset: 0,
+      helpScroll: 0,
       view: "kanban",
       marked: {},
       filter: "all",
@@ -379,6 +386,8 @@ export function createTuiStore({ config }: CreateStoreOptions) {
       // change — and spuriously flash "Reloaded after external edit". Skip.
       if (lastWrittenContent.get(filepath) === content) return;
       const { board } = parseBoard(content, { filepath });
+      const boardConfig = config.boards.find((cb) => cb.path === filepath);
+      if (boardConfig?.name) board.name = boardConfig.name;
       const mtimeMs = statMtime(filepath);
       setState(
         "boards",
@@ -1494,6 +1503,8 @@ export function createTuiStore({ config }: CreateStoreOptions) {
   }
 
   function openModal(m: ModalKind): void {
+    // Help always opens scrolled to the top.
+    if (m.kind === "help") setState("ui", "helpScroll", 0);
     setState("ui", "modal", m);
   }
 
@@ -1551,6 +1562,12 @@ export function createTuiStore({ config }: CreateStoreOptions) {
     if (cals.length === 1) void confirmEventPicker();
   }
 
+  /** Scroll the help modal by setting its block index (lower-clamped at 0; the
+   *  HelpModal component enforces the upper bound against its block count). */
+  function setHelpScroll(n: number): void {
+    setState("ui", "helpScroll", Math.max(0, n));
+  }
+
   /** Move the step-2 calendar selection (wraps). */
   function setEventSel(n: number): void {
     setState("ui", "eventPicker", produce((p: EventPicker | undefined) => {
@@ -1740,6 +1757,7 @@ export function createTuiStore({ config }: CreateStoreOptions) {
     closeModal,
     openEventModal,
     advanceEventToStep2,
+    setHelpScroll,
     setEventSel,
     confirmEventPicker,
     selectCalEvent,

package/src/ui/BoardView.tsx

@@ -8,7 +8,7 @@
  * board width.
  */
 
-import { For, Show, createEffect, createMemo, createSignal, onMount } from "solid-js";
+import { For, Show, createEffect, createMemo, createSignal, onCleanup, onMount } from "solid-js";
 
 import { isHiddenColumn } from "~/config/loader";
 import { isTask } from "~/parser/markdown";
@@ -122,6 +122,11 @@ export function BoardView(props: BoardViewProps) {
     const colIdx = ui().col;
     if (singlePane() || ui().activeZone === "planner") {
       setScrollX(0);
+      // Refresh viewportW too - the zoomed title budget depends on it.
+      setTimeout(() => {
+        const vw = viewportRef?.width ?? 0;
+        if (vw > 0) setViewportW(vw);
+      }, 0);
       return;
     }
     const cols = props.board.columns;
@@ -178,6 +183,18 @@ export function BoardView(props: BoardViewProps) {
     }, 0);
   });
 
+  // Re-measure on resize while zoomed (the scroll effect above only
+  // reruns on col/zoomed/activeZone changes, not plain resizes).
+  const onResize = () => {
+    // 50ms, not 0ms: give OpenTUI's layout pass time to catch up.
+    setTimeout(() => {
+      const vw = viewportRef?.width ?? 0;
+      if (vw > 0) setViewportW(vw);
+    }, 50);
+  };
+  process.stdout.on("resize", onResize);
+  onCleanup(() => process.stdout.off("resize", onResize));
+
   return (
     <box style={{ flexDirection: "column", flexGrow: 1 }}>
       {/* Clipping viewport: fills the board zone, hides overflow. */}
@@ -216,6 +233,7 @@ export function BoardView(props: BoardViewProps) {
                   zoomed={singlePane() && isActive()}
                   tasksVisible={columnTasksVisible(i())}
                   boxId={columnId(props.board.filepath, originalIndex)}
+                  viewportWidth={viewportW()}
                 />
               );
             }}
@@ -245,6 +263,9 @@ interface ColumnViewProps {
   tasksVisible?: boolean;
   /** Stable DOM-equivalent id used by `scrollChildIntoView`. */
   boxId: string;
+  /** Real measured board viewport width in cells, used to size the
+   * title budget for a zoomed column instead of a hardcoded guess. */
+  viewportWidth?: number;
 }
 
 /** Stable id for a task row inside a column, used by scrollChildIntoView. */
@@ -395,9 +416,19 @@ function ColumnView(props: ColumnViewProps) {
                       }
                       // Column inner cell width for a TaskRow: COL_WIDTH 42 −
                       // border 2 − col padding 2 − TaskRow padding 2 = 36 cols
-                      // (when not zoomed). Zoomed → column grows to fill, so
-                      // ~terminal width − some chrome.
-                      availableWidth={props.zoomed ? 100 : 36}
+                      // (when not zoomed). Zoomed: use the real measured
+                      // viewport width, same 6-cell overhead, plus a 2-cell
+                      // safety margin for width-measurement drift (fixes a
+                      // double-truncation glitch, e.g. "walk t...gh backgro...").
+                      availableWidth={
+                        props.zoomed
+                          ? Math.max(6, (props.viewportWidth ?? 42) - 8)
+                          : 36
+                      }
+                      // Default hardCap (60 chars) was clipping titles well
+                      // short of the zoomed column's real width. Let
+                      // availableWidth alone govern the budget when zoomed.
+                      titleMaxChars={props.zoomed ? 1000 : undefined}
                       onClick={() => {
                         props.store.setActiveZone("board");
                         props.store.setCursor(props.columnIndex, ri());

package/src/ui/Modal.tsx

@@ -11,7 +11,7 @@
  * checks `ui.modal` first and bails if set (only Escape passes through).
  */
 
-import { For, Show, createContext, createMemo, createSignal, useContext } from "solid-js";
+import { For, Show, createContext, createEffect, createMemo, createSignal, useContext } from "solid-js";
 
 import { isTask } from "~/parser/markdown";
 import {
@@ -19,7 +19,7 @@ import {
   parseQuickAdd,
   parseTimeBlockShortcut,
 } from "~/store/parsers";
-import { ATTR, T } from "~/ui/glyphs";
+import { ATTR, T, cellWidth } from "~/ui/glyphs";
 import { AGENDA_WIDTH } from "~/ui/layout";
 import { formatHm } from "~/store/timeline";
 import type { TuiStore } from "~/store/index";
@@ -1001,72 +1001,233 @@ function truncate(s: string, n: number): string {
 
 // ─── Help ────────────────────────────────────────────────────────────────────
 
+/**
+ * Width (cells) of the key column. The longest key label is 15 cells
+ * ("shift+click row"), so 16 leaves room for a one-cell separator and keeps
+ * every description starting at the same column. `cellWidth` (not `.length`)
+ * is used so wide arrow/emoji glyphs are budgeted correctly.
+ */
+const HELP_KEYW = 16;
+
+interface HelpSection {
+  emoji: string;
+  title: string;
+  /** Scope note shown dim under the header (kept verbatim from the original). */
+  note?: string;
+  /** [keyLabel, description] pairs — descriptions are verbatim. */
+  rows: [string, string][];
+}
+
+const HELP_SECTIONS: HelpSection[] = [
+  {
+    emoji: "🧭",
+    title: "Navigation",
+    rows: [
+      ["h j k l  ←↑↓→", "Move cursor inside the active zone"],
+      ["Tab", "Next board (kanban zone)"],
+      ["+", "New board — create one, or adopt files you have"],
+      ["1..9", "Jump to board N"],
+      ["v", "Toggle Today/Tomorrow planner panel focus"],
+      ["Shift-Tab", "Cycle active zone (planner → board → timeline → agents)"],
+      ["F1 / F2 / F3", "Toggle visibility of Planner / Timeline / Agents zones"],
+      ["z", "Zoom active zone (or column) to full screen"],
+      ["r", "Refresh everything (boards from disk, agents, agenda calendar)"],
+    ],
+  },
+  {
+    emoji: "⚙️",
+    title: "Task actions",
+    note: "work in board, planner, AND timeline zones",
+    rows: [
+      ["Enter", "Toggle done"],
+      ["o", "Open detail view"],
+      ["e", "Edit task text"],
+      ["s", "Schedule date modal (t/m/+N/lun/YYYY-MM-DD — same t/m as the board)"],
+      ["t", "Set scheduled = today"],
+      ["m", "Set scheduled = tomorrow"],
+      [".", "Schedule now — time block at next 15-min slot (30min)"],
+      ["b", "Set time block modal"],
+      ["p", "Cycle priority (none → 🔺 → ⏫ → 🔼 → 🔽 → ⏬ → none)"],
+      ["a", "Set assignee"],
+      ["d", "Delete task (with confirm)"],
+      ["X", "Archive task → moves to Archive column"],
+      ["C", "Copy task to clipboard (markdown line)"],
+    ],
+  },
+  {
+    emoji: "📅",
+    title: "Agenda — day navigation",
+    note: "works from any zone",
+    rows: [
+      ["[ / ]", "Previous / next day (tasks + calendar events)"],
+      ["\\", "Jump back to today"],
+    ],
+  },
+  {
+    emoji: "⏰",
+    title: "Agenda — scheduling",
+    rows: [
+      ["n / click slot", "New Google Calendar event (needs: calendar-setup google --write) append date+time: Lunch tomorrow 12-13 · Review 2026-06-10 15-16 · Holiday 25-12 allday"],
+      ["click an event", "Select an editable Google event — then e edit · d delete · Esc"],
+      ["c (any zone)", "Toggle ARM MODE — then click a task, click a slot, repeat"],
+      ["click empty row", "Place the armed task here (30-min block, or move if it has one)"],
+      ["click band", "Arm an existing block (or place the armed task at its start)"],
+      ["shift+click row", "While armed (existing block): resize end to that row"],
+      ["j / k", "While armed: nudge block ±15 min"],
+      ["+ / -", "While armed: resize block end ±15 min"],
+      ["Enter", "While armed: commit + jump to source task"],
+      ["Esc", "Disarm / exit arm mode"],
+    ],
+  },
+  {
+    emoji: "📋",
+    title: "Board-only actions",
+    rows: [
+      ["n", "New task in current column (quick-add syntax)"],
+      ["g", "Grab task — h/l then moves it between columns; g/Esc to drop"],
+      ["f", "Cycle board filter: all → today → overdue → tomorrow → followup"],
+      ["/", "Search task titles — jumps cursor to first match"],
+    ],
+  },
+  {
+    emoji: "🤖",
+    title: "Agents zone",
+    rows: [
+      ["Enter", "Open (resume) the selected session in a new WezTerm tab"],
+      ["c", "Copy a 'cd + claude --resume' command for the session"],
+      ["o", "Session detail (cwd, branch, last prompts, resume cmd)"],
+    ],
+  },
+  {
+    emoji: "☑️",
+    title: "Multi-select",
+    rows: [
+      ["Space", "Mark / unmark task (cursor stays — mark in any order) Every task action (done/schedule/time block/assign/priority/archive/delete) then applies to ALL marked"],
+      ["Esc", "Clear the selection (when no modal is open)"],
+    ],
+  },
+  {
+    emoji: "📦",
+    title: "Bulk",
+    rows: [["T", "Reset ALL overdue tasks (any board) to today"]],
+  },
+  {
+    emoji: "🌐",
+    title: "Global",
+    rows: [
+      ["Ctrl-Z", "Undo last mutation"],
+      ["?", "This help"],
+      ["q · Ctrl-C", "Quit"],
+    ],
+  },
+];
+
+/**
+ * Flattened render+scroll units: one "header" block per section (carrying its
+ * optional note) followed by one "row" block per shortcut. `ui.helpScroll` is
+ * an index into this list; `j`/`k` step it and the matching `<box id>` is
+ * scrolled into view.
+ */
+type HelpBlock =
+  | { kind: "header"; emoji: string; title: string; note?: string }
+  | { kind: "row"; keyLabel: string; desc: string };
+
+const HELP_BLOCKS: HelpBlock[] = HELP_SECTIONS.flatMap((s) => [
+  { kind: "header", emoji: s.emoji, title: s.title, note: s.note } as HelpBlock,
+  ...s.rows.map(([keyLabel, desc]) => ({ kind: "row", keyLabel, desc }) as HelpBlock),
+]);
+
+/** Dim dot leader that pads `key` out to the fixed key column (with one leading
+ *  separator space). Empty for keys that already fill the column. */
+function helpDots(key: string): string {
+  const n = HELP_KEYW - cellWidth(key) - 1;
+  return n > 0 ? "·".repeat(n) : "";
+}
+
+/** Minimal structural view of OpenTUI's <scrollbox> ref (mirrors TimelineView). */
+interface ScrollBoxLike {
+  scrollChildIntoView(id: string): void;
+}
+
+/**
+ * Keyboard reference.
+ *
+ * Each shortcut is a SINGLE full-width `<text wrapMode="word">` (key + dim dot
+ * leader + description as spans). A single full-width text manages its own
+ * wrapped height correctly; a wrapping `<text>` placed as a flex *sibling* in a
+ * row does NOT (the next row overpaints it — the "bleed-into-neighbor" glitch
+ * documented in TaskRow). When a description wraps it returns to column 0 in the
+ * dim description color, visually distinct from the accent key.
+ *
+ * The whole list lives in a `<scrollbox>` so it never clips on short terminals;
+ * `j`/`k` move `ui.helpScroll` and the focused block is scrolled into view.
+ */
 function HelpModal(props: { store: TuiStore }) {
-  void props;
+  let scrollBoxRef: ScrollBoxLike | undefined;
+
+  createEffect(() => {
+    const raw = props.store.state.ui.helpScroll;
+    const clamped = Math.max(0, Math.min(raw, HELP_BLOCKS.length - 1));
+    if (clamped !== raw) {
+      props.store.setHelpScroll(clamped);
+      return; // effect re-runs with the corrected value
+    }
+    scrollBoxRef?.scrollChildIntoView(`help-b${clamped}`);
+  });
+
   return (
-    <DialogShell title="tuiboard — keyboard reference" hint="Esc/? to close" width={92}>
-      <text>
-        <span style={{ fg: T.textDim }}>{"Navigation\n"}</span>
-        <span style={{ fg: T.text }}>{"  h j k l  ←↑↓→     Move cursor inside the active zone\n"}</span>
-        <span style={{ fg: T.text }}>{"  Tab               Next board (kanban zone)\n"}</span>
-        <span style={{ fg: T.text }}>{"  +                 New board — create one, or adopt files you have\n"}</span>
-        <span style={{ fg: T.text }}>{"  z                 Focus one pane (automatic below 100 columns)\n"}</span>
-        <span style={{ fg: T.text }}>{"  1..9              Jump to board N\n"}</span>
-        <span style={{ fg: T.text }}>{"  v                 Toggle Today/Tomorrow planner panel focus\n"}</span>
-        <span style={{ fg: T.text }}>{"  Shift-Tab         Cycle active zone (planner → board → timeline → agents)\n"}</span>
-        <span style={{ fg: T.text }}>{"  F1 / F2 / F3      Toggle visibility of Planner / Timeline / Agents zones\n"}</span>
-        <span style={{ fg: T.text }}>{"  z                 Zoom active zone (or column) to full screen\n"}</span>
-        <span style={{ fg: T.text }}>{"  r                 Refresh everything (boards from disk, agents, agenda calendar)\n"}</span>
-        <span style={{ fg: T.textDim }}>{"\nTask actions (work in board, planner, AND timeline zones)\n"}</span>
-        <span style={{ fg: T.text }}>{"  Enter             Toggle done\n"}</span>
-        <span style={{ fg: T.text }}>{"  o                 Open detail view\n"}</span>
-        <span style={{ fg: T.text }}>{"  e                 Edit task text\n"}</span>
-        <span style={{ fg: T.text }}>{"  s                 Schedule date modal (t/m/+N/lun/YYYY-MM-DD — same t/m as the board)\n"}</span>
-        <span style={{ fg: T.text }}>{"  t                 Set scheduled = today\n"}</span>
-        <span style={{ fg: T.text }}>{"  m                 Set scheduled = tomorrow\n"}</span>
-        <span style={{ fg: T.text }}>{"  .                 Schedule now — time block at next 15-min slot (30min)\n"}</span>
-        <span style={{ fg: T.text }}>{"  b                 Set time block modal\n"}</span>
-        <span style={{ fg: T.text }}>{"  p                 Cycle priority (none → 🔺 → ⏫ → 🔼 → 🔽 → ⏬ → none)\n"}</span>
-        <span style={{ fg: T.text }}>{"  a                 Set assignee\n"}</span>
-        <span style={{ fg: T.text }}>{"  d                 Delete task (with confirm)\n"}</span>
-        <span style={{ fg: T.text }}>{"  X                 Archive task → moves to Archive column\n"}</span>
-        <span style={{ fg: T.text }}>{"  C                 Copy task to clipboard (markdown line)\n"}</span>
-        <span style={{ fg: T.textDim }}>{"\nAgenda (timeline) day navigation — works from any zone\n"}</span>
-        <span style={{ fg: T.text }}>{"  [ / ]              Previous / next day (tasks + calendar events)\n"}</span>
-        <span style={{ fg: T.text }}>{"  \\                  Jump back to today\n"}</span>
-        <span style={{ fg: T.textDim }}>{"\nAgenda (timeline) scheduling\n"}</span>
-        <span style={{ fg: T.text }}>{"  n / click slot     New Google Calendar event (needs: calendar-setup google --write)\n"}</span>
-        <span style={{ fg: T.text }}>{"                     append date+time: Lunch tomorrow 12-13 · Review 2026-06-10 15-16 · Holiday 25-12 allday\n"}</span>
-        <span style={{ fg: T.text }}>{"  click an event     Select an editable Google event — then e edit · d delete · Esc\n"}</span>
-        <span style={{ fg: T.text }}>{"  c (any zone)       Toggle ARM MODE — then click a task, click a slot, repeat\n"}</span>
-        <span style={{ fg: T.text }}>{"  click empty row    Place the armed task here (30-min block, or move if it has one)\n"}</span>
-        <span style={{ fg: T.text }}>{"  click band         Arm an existing block (or place the armed task at its start)\n"}</span>
-        <span style={{ fg: T.text }}>{"  shift+click row    While armed (existing block): resize end to that row\n"}</span>
-        <span style={{ fg: T.text }}>{"  j / k              While armed: nudge block ±15 min\n"}</span>
-        <span style={{ fg: T.text }}>{"  + / -              While armed: resize block end ±15 min\n"}</span>
-        <span style={{ fg: T.text }}>{"  Enter              While armed: commit + jump to source task\n"}</span>
-        <span style={{ fg: T.text }}>{"  Esc                Disarm / exit arm mode\n"}</span>
-        <span style={{ fg: T.textDim }}>{"\nBoard-only actions\n"}</span>
-        <span style={{ fg: T.text }}>{"  n                 New task in current column (quick-add syntax)\n"}</span>
-        <span style={{ fg: T.text }}>{"  g                 Grab task — h/l then moves it between columns; g/Esc to drop\n"}</span>
-        <span style={{ fg: T.text }}>{"  f                 Cycle board filter: all → today → overdue → tomorrow → followup\n"}</span>
-        <span style={{ fg: T.text }}>{"  /                 Search task titles — jumps cursor to first match\n"}</span>
-        <span style={{ fg: T.textDim }}>{"\nAgents zone\n"}</span>
-        <span style={{ fg: T.text }}>{"  Enter             Open (resume) the selected session in a new WezTerm tab\n"}</span>
-        <span style={{ fg: T.text }}>{"  c                 Copy a 'cd + claude --resume' command for the session\n"}</span>
-        <span style={{ fg: T.text }}>{"  o                 Session detail (cwd, branch, last prompts, resume cmd)\n"}</span>
-        <span style={{ fg: T.textDim }}>{"\nMulti-select\n"}</span>
-        <span style={{ fg: T.text }}>{"  Space             Mark / unmark task (cursor stays — mark in any order)\n"}</span>
-        <span style={{ fg: T.text }}>{"                    Every task action (done/schedule/time block/assign/\n"}</span>
-        <span style={{ fg: T.text }}>{"                    priority/archive/delete) then applies to ALL marked\n"}</span>
-        <span style={{ fg: T.text }}>{"  Esc               Clear the selection (when no modal is open)\n"}</span>
-        <span style={{ fg: T.textDim }}>{"\nBulk\n"}</span>
-        <span style={{ fg: T.text }}>{"  T                 Reset ALL overdue tasks (any board) to today\n"}</span>
-        <span style={{ fg: T.textDim }}>{"\nGlobal\n"}</span>
-        <span style={{ fg: T.text }}>{"  Ctrl-Z            Undo last mutation\n"}</span>
-        <span style={{ fg: T.text }}>{"  ?                 This help\n"}</span>
-        <span style={{ fg: T.text }}>{"  q · Ctrl-C        Quit\n"}</span>
-      </text>
+    <DialogShell title="tuiboard — keyboard reference" hint="Esc/? close · j/k scroll" width={92}>
+      <scrollbox
+        ref={(r: ScrollBoxLike) => (scrollBoxRef = r)}
+        style={{
+          width: "100%",
+          flexGrow: 1,
+          scrollX: false,
+          scrollY: true,
+          rootOptions: {},
+          contentOptions: {},
+          scrollbarOptions: { visible: false },
+        }}
+      >
+        <For each={HELP_BLOCKS}>
+          {(block, i) => (
+            <box id={`help-b${i()}`} style={{ flexDirection: "column" }}>
+              <Show when={block.kind === "header"}>
+                {/* blank line above every section header except the first */}
+                <Show when={i() > 0}>
+                  <box style={{ height: 1 }} />
+                </Show>
+                <text wrapMode="none" truncate>
+                  <span style={{ fg: T.warm, attributes: ATTR.bold }}>
+                    {`${(block as { emoji: string }).emoji}  ${(block as { title: string }).title}`}
+                  </span>
+                </text>
+                {/* scope note on its own wrapping line, kept verbatim */}
+                <Show when={(block as { note?: string }).note}>
+                  <text wrapMode="word">
+                    <span style={{ fg: T.textDone, attributes: ATTR.italic }}>
+                      {(block as { note: string }).note}
+                    </span>
+                  </text>
+                </Show>
+              </Show>
+              <Show when={block.kind === "row"}>
+                <text wrapMode="word">
+                  <span style={{ fg: T.accent, attributes: ATTR.bold }}>
+                    {(block as { keyLabel: string }).keyLabel}
+                  </span>
+                  <span style={{ fg: T.border }}>
+                    {` ${helpDots((block as { keyLabel: string }).keyLabel)}`}
+                  </span>
+                  <span style={{ fg: T.textDim }}>
+                    {` ${(block as { desc: string }).desc}`}
+                  </span>
+                </text>
+              </Show>
+            </box>
+          )}
+        </For>
+      </scrollbox>
     </DialogShell>
   );
 }