tuiboard 0.9.2 → 0.11.0

package/CHANGELOG.md

@@ -5,7 +5,53 @@ 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
+
+### Added
+- **A task's note is readable inside tuiboard.** When a task's title is a link —
+  `[[Nome nota|Titolo]]` or `[Titolo](Tasks/Nome.md)` — the detail view (`o`)
+  shows that note's text, scrollable, instead of pointing at Obsidian. Both link
+  forms work, so the convention stands on its own: a board written in plain
+  markdown gets the feature too. Links *inside* a sentence stay mentions and are
+  listed as before — a task that mentions a person is not documented by that
+  person's page. A missing note says which name it looked for; two notes sharing
+  a name resolve to the nearest and the shadowed one is named.
+
+### Fixed
+- **Markdown links no longer show as raw syntax in task titles.** `displayTitle`
+  stripped wikilinks but not `[text](path.md)`, so a board written without
+  Obsidian showed the whole link as its title — in the board, the planner and
+  the bar widget.
 
 ## [0.9.2] - 2026-09-08
 
@@ -59,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
@@ -298,6 +350,7 @@ First public release on npm. This entry captures the full feature set at launch.
 
 Built with [OpenTUI](https://opentui.com) + SolidJS on Bun.
 
+[0.10.0]: https://github.com/NazzarenoGiannelli/tuiboard/releases/tag/v0.10.0
 [0.9.2]: https://github.com/NazzarenoGiannelli/tuiboard/releases/tag/v0.9.2
 [0.9.1]: https://github.com/NazzarenoGiannelli/tuiboard/releases/tag/v0.9.1
 [0.9.0]: https://github.com/NazzarenoGiannelli/tuiboard/releases/tag/v0.9.0

package/README.md

@@ -534,6 +534,9 @@ clobber an edit made in the TUI or another editor in the meantime.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full release history.
 
+- **v0.10** — a task's note, read inside tuiboard: when a task's title is a
+  link, `o` shows that note's text instead of pointing at Obsidian. Works with
+  plain markdown links too, so the convention needs no vault.
 - **v0.9** — tuiboard makes its own boards: a `+` that creates or adopts them,
   onboarding on first run instead of an error, `tuiboard board` headless, and
   single-pane mode so a narrow vertical panel shows one zone at a time instead

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tuiboard",
-  "version": "0.9.2",
+  "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/notes/index.ts

@@ -0,0 +1,144 @@
+/**
+ * Task notes: finding the file a task's link points at, and reading it.
+ *
+ * The convention is tuiboard's own, not Obsidian's: a task's note is the link
+ * that wraps its title, written either way —
+ *
+ *     - [ ] [[Nome nota|Titolo mostrato]]        wiki style
+ *     - [ ] [Titolo mostrato](Tasks/Nome.md)     plain markdown
+ *
+ * The second form is how any markdown document links another, so a board that
+ * has never heard of wikilinks gets the feature too. The parser decides which
+ * link qualifies (see `titleNoteLink`); this module only turns it into a file.
+ *
+ * Pure except for the filesystem reads it exists to perform: no store, no
+ * renderer, testable against a temp directory.
+ */
+
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, dirname, extname, join, resolve, sep } from "node:path";
+
+import type { TaskNoteLink } from "~/types";
+
+/** Directories never worth walking for notes. */
+const SKIP_DIRS = new Set([".git", ".obsidian", "node_modules", ".trash", ".stversions"]);
+
+/** How deep the scan goes. Deeper than any sane note layout, shallow enough to end. */
+const MAX_DEPTH = 8;
+
+/** Note name (lowercased, without extension) → every file carrying that name. */
+export type NoteIndex = Record<string, string[]>;
+
+export interface ResolvedNote {
+  path: string;
+  /** Same-named files that lost to the winner, nearest-first. Absent when unique. */
+  shadowed?: string[];
+}
+
+export interface MissingNote {
+  missing: string;
+}
+
+/**
+ * Index every markdown file under `root`, by name.
+ *
+ * Obsidian resolves `[[Name]]` by name rather than by path, and notes written
+ * by hand rely on that, so tuiboard does the same instead of demanding paths.
+ * A missing or unreadable directory yields an empty index rather than an
+ * error: a broken note link must never stop the board from opening.
+ */
+export function buildNoteIndex(root: string): NoteIndex {
+  const index: NoteIndex = {};
+
+  const walk = (dir: string, depth: number): void => {
+    if (depth > MAX_DEPTH) return;
+    let entries: string[];
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.startsWith(".") && SKIP_DIRS.has(entry)) continue;
+      if (SKIP_DIRS.has(entry)) continue;
+      const full = join(dir, entry);
+      let isDir = false;
+      try {
+        isDir = statSync(full).isDirectory();
+      } catch {
+        continue;
+      }
+      if (isDir) {
+        walk(full, depth + 1);
+      } else if (extname(entry).toLowerCase() === ".md") {
+        const key = noteKey(entry);
+        (index[key] ??= []).push(full);
+      }
+    }
+  };
+
+  walk(resolve(root), 0);
+  return index;
+}
+
+/** The name a link and a filename are compared by: no extension, no case. */
+function noteKey(name: string): string {
+  return basename(name, extname(name)).trim().toLowerCase();
+}
+
+/**
+ * Turn a task's link into a file.
+ *
+ * A `path` link is a real path and resolves against the board that carries the
+ * task — the same way a relative link works in any markdown document. A
+ * `wikilink` is only a name, so it goes through the index.
+ *
+ * When several files share a name the nearest to the board wins, and the ones
+ * it shadowed are returned: proximity is a guess, and a guess should be
+ * visible rather than silently applied.
+ */
+export function resolveNote(
+  link: TaskNoteLink,
+  { index, boardPath }: { index: NoteIndex; boardPath: string },
+): ResolvedNote | MissingNote {
+  const boardDir = dirname(resolve(boardPath));
+
+  if (link.kind === "path") {
+    const path = resolve(boardDir, link.target);
+    try {
+      if (statSync(path).isFile()) return { path };
+    } catch {
+      /* fall through to missing */
+    }
+    return { missing: link.target };
+  }
+
+  const hits = index[noteKey(link.target)];
+  if (!hits || hits.length === 0) return { missing: link.target };
+
+  const ranked = [...hits].sort((a, b) => distanceFrom(boardDir, a) - distanceFrom(boardDir, b));
+  const [winner, ...rest] = ranked;
+  return rest.length > 0 ? { path: winner!, shadowed: rest } : { path: winner! };
+}
+
+/** How far a file sits from a directory, in path segments. Lower is nearer. */
+function distanceFrom(dir: string, file: string): number {
+  const from = dir.split(sep).filter(Boolean);
+  const to = dirname(file).split(sep).filter(Boolean);
+  let common = 0;
+  while (common < from.length && common < to.length && from[common] === to[common]) common++;
+  return from.length - common + (to.length - common);
+}
+
+/**
+ * The note's text, without its frontmatter — that is configuration, and the
+ * detail view is showing context.
+ *
+ * Throws when the file cannot be read: the caller has a frame to put the
+ * message in, and swallowing it would show an empty note instead of a reason.
+ */
+export function readNoteBody(path: string): string {
+  const raw = readFileSync(path, "utf-8");
+  const withoutFrontmatter = raw.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "");
+  return withoutFrontmatter.trim();
+}

package/src/parser/markdown.ts

@@ -26,6 +26,7 @@ import type {
   RawOther,
   SectionBreak,
   Task,
+  TaskNoteLink,
   TimeBlock,
   TimeBlockSource,
 } from "~/types";
@@ -268,6 +269,12 @@ function parseTask(input: ParseTaskInput): Task {
   // Wikilinks — capture displayed text (alias if present, target otherwise)
   const wikilinks = Array.from(body.matchAll(RE_WIKILINK), (m) => m[2] ?? m[1]!);
 
+  // The task's note: a link that WRAPS the title, i.e. opens the line. A link
+  // in the middle of a sentence is a mention — `Mandare materiale a [[Lisa]]`
+  // is not a task documented by Lisa's page. Trailing metadata (dates, tags)
+  // does not disqualify it, only text before the link does.
+  const note = titleNoteLink(body);
+
   // Priority
   let priority: PriorityLevel = "none";
   for (const [emoji, level] of PRIORITY_EMOJI) {
@@ -290,6 +297,7 @@ function parseTask(input: ParseTaskInput): Task {
     assignee: am?.[1],
     tags,
     wikilinks,
+    note,
     scheduled: sched?.[1],
     due: due?.[1],
     start: start?.[1],
@@ -324,6 +332,10 @@ function buildDisplayTitle(
   t = t.replace(RE_TAG, "");
   // Replace wikilinks with their displayed text (alias or target)
   t = t.replace(RE_WIKILINK, (_m, target: string, alias?: string) => alias ?? target);
+  // Same for markdown links: show the text, drop the target. Without this a
+  // board written in plain markdown — the form that needs no Obsidian — shows
+  // `[Titolo](Tasks/Nota.md)` as its title everywhere, widget included.
+  t = t.replace(RE_MDLINK, (_m, text: string) => text);
   // Strip priority and decorative emoji
   for (const [emoji] of PRIORITY_EMOJI) t = t.replaceAll(emoji, "");
   for (const emoji of DECORATIVE_EMOJI) t = t.replaceAll(emoji, "");
@@ -332,6 +344,45 @@ function buildDisplayTitle(
   return t;
 }
 
+/** `[[Target|shown]]` or `[shown](path.md)` at the very start of the line. */
+/** `[shown](target)` anywhere in the line — for display only. */
+const RE_MDLINK = /\[([^\]]*)\]\(([^)]+)\)/g;
+
+const RE_TITLE_WIKILINK = /^\s*\[\[([^\]|]+?)(?:\|[^\]]+)?\]\]/;
+const RE_TITLE_MDLINK = /^\s*\[[^\]]*\]\(([^)]+)\)/;
+
+/**
+ * What can sit between the checkbox and the title without being the title:
+ * priority and decorative emoji, and markdown emphasis. `- [ ] 🔥 [[Nota]]`
+ * is still a task whose title is a link.
+ */
+function stripTitleDecorations(body: string): string {
+  let t = body;
+  let changed = true;
+  while (changed) {
+    const before = t;
+    t = t.trimStart().replace(/^[*_~]+/, "");
+    for (const [emoji] of PRIORITY_EMOJI) if (t.startsWith(emoji)) t = t.slice(emoji.length);
+    for (const emoji of DECORATIVE_EMOJI) if (t.startsWith(emoji)) t = t.slice(emoji.length);
+    changed = t !== before;
+  }
+  return t;
+}
+
+function titleNoteLink(rawBody: string): TaskNoteLink | undefined {
+  const body = stripTitleDecorations(rawBody);
+  const wiki = body.match(RE_TITLE_WIKILINK);
+  if (wiki) return { target: wiki[1]!.trim(), kind: "wikilink" };
+  const md = body.match(RE_TITLE_MDLINK);
+  if (md) {
+    const target = md[1]!.trim();
+    // A URL is not a note. Nothing to read from the filesystem.
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(target)) return undefined;
+    return { target, kind: "path" };
+  }
+  return undefined;
+}
+
 function extractBoardName(frontmatter: string, filepath: string): string {
   const m = frontmatter.match(/^name:\s*(.+?)\s*$/m);
   if (m) return m[1]!;

package/src/store/index.ts

@@ -46,6 +46,7 @@ import { createBoardFile } from "~/boards/create";
 import { scanDirectory, type BoardCandidate } from "~/boards/scan";
 import { suggestBoardsDir } from "~/boards/suggest";
 import { isTask, parseBoard } from "~/parser/markdown";
+import { buildNoteIndex, readNoteBody, resolveNote, type NoteIndex } from "~/notes/index";
 import { buildRing, ringPosition, samePane, stepRing, type Pane } from "~/ui/pane-ring";
 import { serializeBoard } from "~/parser/serialize";
 import type {
@@ -122,6 +123,18 @@ export interface BoardNew {
   error?: string;
 }
 
+/** What the detail view needs to show a task's note, or to explain its absence. */
+export interface TaskNoteView {
+  path?: string;
+  body?: string;
+  /** Same-named notes that lost to this one. */
+  shadowed?: string[];
+  /** The link pointed at something that is not there. */
+  missing?: string;
+  /** The file exists but could not be read. */
+  error?: string;
+}
+
 export interface EventPicker {
   step: 1 | 2;
   /** Selection index into `cals` (step 2). */
@@ -230,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:
@@ -326,6 +345,7 @@ export function createTuiStore({ config }: CreateStoreOptions) {
       grabbing: false,
       armMode: false,
       agendaOffset: 0,
+      helpScroll: 0,
       view: "kanban",
       marked: {},
       filter: "all",
@@ -366,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",
@@ -1295,11 +1317,49 @@ export function createTuiStore({ config }: CreateStoreOptions) {
   function refreshAll(): void {
     setState("boards", loadAll(config));
     setState("rev", (r) => r + 1);
+    noteIndex = undefined; // rebuilt on the next note opened
     agentsStore.refresh();
     calendarStore.refresh(true);
     flashBanner("info", "Refreshed boards · agents · agenda");
   }
 
+  // ─── Task notes ──────────────────────────────────────────────────────────
+  // The index is built the first time a note is opened and thrown away by `r`.
+  // Watching the tree instead would cost a second chokidar over a thousand
+  // files to save a keystroke the user already has.
+  let noteIndex: NoteIndex | undefined;
+
+  /**
+   * The note behind the task at `ref`, ready to render: its text, where it came
+   * from, or why it could not be read. `undefined` means the task has no note —
+   * which is most tasks, and must produce no message at all.
+   */
+  function taskNote(ref: TaskRef): TaskNoteView | undefined {
+    const task = getTask(ref);
+    if (!task?.note) return undefined;
+
+    noteIndex ??= buildNoteIndex(suggestBoardsDir(config));
+    const found = resolveNote(task.note, { index: noteIndex, boardPath: ref.boardPath });
+    if ("missing" in found) return { missing: found.missing };
+
+    // Shown from the boards' own root: an absolute path is noise, and the
+    // config's root is the config's directory, not where the notes live.
+    const root = suggestBoardsDir(config);
+    const shown = found.path.startsWith(root)
+      ? found.path.slice(root.length).replace(/^[/\\]/, "")
+      : found.path;
+
+    try {
+      return {
+        path: shown,
+        body: readNoteBody(found.path),
+        shadowed: found.shadowed?.map((p) => (p.startsWith(root) ? p.slice(root.length + 1) : p)),
+      };
+    } catch (e) {
+      return { path: shown, error: (e as Error).message };
+    }
+  }
+
   // ─── Multi-select ────────────────────────────────────────────────────────
 
   function markKey(ref: TaskRef): string {
@@ -1443,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);
   }
 
@@ -1500,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) => {
@@ -1643,6 +1711,8 @@ export function createTuiStore({ config }: CreateStoreOptions) {
     addTask,
     deleteTask,
     moveTaskWithinBoard,
+    // notes
+    taskNote,
     // boards
     addBoard,
     openBoardNew,
@@ -1687,6 +1757,7 @@ export function createTuiStore({ config }: CreateStoreOptions) {
     closeModal,
     openEventModal,
     advanceEventToStep2,
+    setHelpScroll,
     setEventSel,
     confirmEventPicker,
     selectCalEvent,

package/src/types.ts

@@ -20,6 +20,12 @@ export interface TimeBlock {
 /** Where the time block was found in the source — drives writer behavior. */
 export type TimeBlockSource = "legacy-prefix" | "watch-emoji";
 
+/** Where a task's note lives: a note name (wiki style) or a path. */
+export interface TaskNoteLink {
+  target: string;
+  kind: "wikilink" | "path";
+}
+
 export interface Task {
   /** Stable identity within a board: `${columnIndex}:${indexInColumn}`. */
   id: string;
@@ -38,6 +44,14 @@ export interface Task {
   tags: string[];
   /** Wikilinks: alias if present, otherwise target. */
   wikilinks: string[];
+  /**
+   * The link that wraps the title, when there is one: this task's note.
+   *
+   * Distinct from `wikilinks`, which lists every link in the line. A link in
+   * the middle of a sentence is a mention — showing a person's page as a
+   * task's context would be worse than showing nothing.
+   */
+  note?: TaskNoteLink;
   scheduled?: ISODate;
   due?: ISODate;
   start?: ISODate;

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";
@@ -720,8 +720,9 @@ function DetailModal(props: { store: TuiStore; modal: Extract<NonNullable<TuiSto
   if (!task) {
     return <DialogShell title="Task not found" hint="Esc to close" width={50}><text>{" "}</text></DialogShell>;
   }
+  const note = createMemo(() => props.store.taskNote(props.modal.ref));
   return (
-    <DialogShell title="Detail" hint="Esc to close" width={90}>
+    <DialogShell title="Detail" hint="j/k scroll the note · Esc to close" width={90}>
       <text wrapMode="word">
         <span style={{ fg: T.text, attributes: ATTR.bold }}>{task.displayTitle}</span>
       </text>
@@ -774,6 +775,48 @@ function DetailModal(props: { store: TuiStore; modal: Extract<NonNullable<TuiSto
           <span style={{ fg: T.tag }}>{task.tags.map((t) => "#" + t).join(" ")}</span>
         </text>
       </Show>
+      {/* The task's note, when its title is a link. Most tasks have none, and
+          for those nothing is drawn at all: silence is the correct output. */}
+      <Show when={note()}>
+        {(n: () => NonNullable<ReturnType<typeof note>>) => (
+          <box style={{ flexDirection: "column", flexGrow: 1, minHeight: 0 }}>
+            <box style={{ height: 1 }} />
+            <Show when={n().path}>
+              <text wrapMode="word">
+                <span style={{ fg: T.textDim }}>Note: </span>
+                <span style={{ fg: T.tag }}>{n().path}</span>
+              </text>
+            </Show>
+            <Show when={n().missing}>
+              <text wrapMode="word">
+                <span style={{ fg: T.overdue }}>{"Note not found: " + n().missing}</span>
+              </text>
+            </Show>
+            <Show when={n().error}>
+              <text wrapMode="word">
+                <span style={{ fg: T.overdue }}>{"Note unreadable: " + n().error}</span>
+              </text>
+            </Show>
+            <Show when={n().shadowed?.length}>
+              <text wrapMode="word">
+                <span style={{ fg: T.textDim }}>
+                  {"Another note shares this name: " + (n().shadowed ?? []).join(", ")}
+                </span>
+              </text>
+            </Show>
+            <Show when={n().body !== undefined}>
+              <box style={{ height: 1 }} />
+              <scrollbox style={{ flexGrow: 1, minHeight: 0 }}>
+                <text wrapMode="word">
+                  <span style={{ fg: T.text }}>
+                    {n().body === "" ? "(the note is empty)" : n().body}
+                  </span>
+                </text>
+              </scrollbox>
+            </Show>
+          </box>
+        )}
+      </Show>
       <Show when={task.wikilinks.length > 0}>
         <box style={{ height: 1 }} />
         <text>
@@ -958,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>
   );
 }