tuiboard 0.8.5 → 0.9.0

package/CHANGELOG.md

@@ -7,6 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-09-08
+
+### Added
+- **Single-pane mode for narrow terminals.** Below 100 columns tuiboard used to
+  drop every zone but the kanban — the least readable thing at that width, and
+  the only one that cannot be hidden — leaving the planner and agenda
+  unreachable. Now the zones queue instead of disappearing: one on screen at a
+  time, `h`/`l` walking a ring (planner → each board column → agenda → agents,
+  wrapping), `Shift-Tab` jumping whole zones, and the top bar showing where you
+  are (`⤢ Today / Tomorrow ‹ 1/8 ›`). `z` still enters and leaves it by hand at
+  any width. Resizing no longer moves your focus.
+- **`tuiboard --view=planner`** — open on Today/Tomorrow alone, for a vertical
+  strip beside other work.
+- **Boards can be created from inside tuiboard.** A `+` chip at the end of the
+  board tabs — clickable, or the `+` key — opens a wizard that either creates a
+  new markdown board or scans a folder and adopts the boards already in it.
+- **First run onboards instead of failing.** Launching with no config used to
+  print `No boards found` and exit, sending the user to write a file they had
+  never seen. The same wizard now opens, writes the config, and opens the board.
+- **`tuiboard board add|scan|list`** — the same operations headless, for scripts
+  and widgets. Adding a board edits the config **by insertion**: comments,
+  calendars, `resume_command` and formatting survive because they are never
+  rewritten.
+- New boards are proposed next to the boards you already have, so they inherit
+  that folder's sync and versioning; the fallback is `~/.local/share/tuiboard/boards/`.
+
+### Fixed
+- **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
+  matter with one pane on screen; the full sheet is one `?` away.
+- **A board without a `%% kanban:settings %%` trailer grew a blank line on every
+  save.** The final newline of the file was parsed as a blank line and written
+  back as one, plus a new terminator. Boards with the trailer were unaffected,
+  which is why it went unseen — but the demo boards in `examples/` were failing
+  the round-trip check, and any board tuiboard creates itself would have too.
+
+### Changed
+- **Slimmer published package.** The `files` field shipped `src/` whole, so the
+  tarball carried the test suite and the dev check scripts to every install.
+  53 files → 42, 453 kB → 406 kB unpacked. Nothing that runs was removed:
+  verified by installing the tarball into a clean project and running both
+  headless commands from it.
+
 ## [0.8.5] - 2026-08-31
 
 ### Added
@@ -229,6 +273,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.9.0]: https://github.com/NazzarenoGiannelli/tuiboard/releases/tag/v0.9.0
 [0.8.5]: https://github.com/NazzarenoGiannelli/tuiboard/releases/tag/v0.8.5
 [0.8.4]: https://github.com/NazzarenoGiannelli/tuiboard/releases/tag/v0.8.4
 [0.8.3]: https://github.com/NazzarenoGiannelli/tuiboard/releases/tag/v0.8.3

package/README.md

@@ -116,6 +116,19 @@ https://github.com/NazzarenoGiannelli/tuiboard). Set it up for me from scratch:
 Confirm the directory and file names with me before writing any files.
 ```
 
+## First run
+
+Launch `tuiboard` with nothing set up and it opens its own onboarding rather
+than an error: point it at a folder and adopt the markdown files already in it,
+or give a name and get a new board. Either way it writes the config for you and
+opens the board. The same screen is behind the `+` in the top bar, so adding a
+board later is the gesture you already learned.
+
+New boards are created next to the boards you already have — usually a vault,
+so they inherit whatever sync and versioning it has — falling back to
+`~/.local/share/tuiboard/boards/` when there is nothing to learn from. The path
+is always shown and editable before anything is written.
+
 ## Configure
 
 Copy `.tuiboard/config.example.yaml` to a config location and edit the
@@ -362,6 +375,7 @@ Launch `tuiboard` with no flag for the default dashboard (every enabled zone).
 | Flag | View | Use case |
 |---|---|---|
 | (none) | **Dashboard** — every enabled zone | Default; your configured layout |
+| `--view=planner` | Today/Tomorrow alone, full width | A narrow vertical strip beside other work |
 | `--view=board` | Kanban + planner panel only | Focus mode, or a single WezTerm pane |
 | `--view=timeline` | Timeline fullscreen | Wall-mounted "what's now" |
 | `--view=agents` | Agent view fullscreen | Cross-machine session monitor |
@@ -373,7 +387,7 @@ The dashboard auto-collapses optional zones on narrow terminals:
 | ≥ 150 cols | planner + board + timeline + agents |
 | 120–149 | planner + board + agents |
 | 100–119 | planner + board |
-| < 100 | board only |
+| < 100 | **single-pane**: one zone at a time, `h`/`l` to walk them, `Shift-Tab` to jump |
 
 `F1` / `F2` / `F3` toggles override the auto-collapse for the current
 session (until the next terminal resize).
@@ -389,6 +403,9 @@ session (until the next terminal resize).
 | `1`..`9` | Jump to board N |
 | `v` | Toggle Today/Tomorrow planner panel focus |
 | `Shift-Tab` | Cycle active zone (planner → board → timeline → agents) |
+| `+` | New board — create one, or adopt markdown files you already have (also the `+` chip in the top bar) |
+| `z` | Focus one pane (single-pane mode) — automatic below 100 columns |
+| `h` / `l` | In single-pane, walk the ring: planner → each column → agenda → agents, wrapping |
 | `F1` / `F2` / `F3` | Toggle visibility of Planner / Timeline / Agents zones |
 | `z` | Zoom active zone to full screen |
 | `r` | Refresh everything — reload boards from disk, rescan agents, force-refetch the agenda calendar (bypasses the 30-min cache) |
@@ -469,6 +486,21 @@ whether it is already `done` (with `doneDate`). Today and Tomorrow keep
 completed tasks, as the panel does: a day's plan is a record of the day, not
 only of what is left.
 
+### `tuiboard board` — create, adopt, list
+
+```bash
+tuiboard board add --path ~/vault/Work.md --name Work   # adopt it if it exists, create it if not
+tuiboard board add --path ~/vault/New.md --columns "Todo,Doing,Done"
+tuiboard board scan ~/vault                             # which files there are boards
+tuiboard board list                                     # what is configured, and where new boards would go
+```
+
+The same operations the `+` button performs in the dashboard, over the same
+code. `add` writes the board file when it is missing and registers it in your
+config either way — the config is edited by insertion, never rewritten, so
+comments and every other setting survive untouched. A duplicate name or path
+is refused rather than guessed at, and `--dry-run` reports without writing.
+
 ### `tuiboard task` — mutations
 
 ```bash
@@ -502,6 +534,10 @@ clobber an edit made in the TUI or another editor in the meantime.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full release history.
 
+- **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
+  of clipped kanban columns.
 - **v0.8** — write to Google Calendar from the Agenda: create, edit, and delete
   events (opt-in), set their date and time in the modal, plus all-day events in
   the top strip, consistent `t`/`m` date shortcuts, and a boot splash.

package/bin/tuiboard.ts

@@ -37,6 +37,10 @@ if (process.argv[2] === "task") {
   const { runTask } = await import("../src/cli/task.ts");
   process.exit(await runTask(process.argv.slice(3)));
 }
+if (process.argv[2] === "board") {
+  const { runBoard } = await import("../src/cli/board.ts");
+  process.exit(await runBoard(process.argv.slice(3)));
+}
 const preload = fileURLToPath(import.meta.resolve("@opentui/solid/preload"));
 
 // Paint the splash from the (already-running) launcher and animate its booting

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tuiboard",
-  "version": "0.8.5",
+  "version": "0.9.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",
@@ -34,6 +34,8 @@
   "files": [
     "tsconfig.json",
     "src/",
+    "!src/**/*.test.ts",
+    "!src/scripts/",
     "bin/",
     ".tuiboard/config.example.yaml",
     "README.md",

package/src/app.tsx

@@ -72,19 +72,16 @@ process.on("warning", (w: Error) => {
 // ─── Bootstrap ──────────────────────────────────────────────────────────────
 
 const config = loadConfig();
-if (config.boards.length === 0) {
-  console.error(
-    "No boards found. Create `.tuiboard/config.yaml` with a `boards:` list," +
-      " or run from a directory containing markdown files with `- [ ]` tasks.",
-  );
-  process.exit(1);
-}
-
 const store = createTuiStore({ config });
 
-if (store.state.boards.length === 0) {
-  console.error("All boards failed to load. Check paths in .tuiboard/config.yaml.");
-  process.exit(1);
+// No boards — a fresh install, or a config whose files have all gone. Rather
+// than printing an error and exiting, which sends the user off to read
+// documentation about a file they have never seen, tuiboard opens on its own
+// onboarding: point it at markdown you already have, or make a board here.
+// The same screen the `+` chip opens, so the first run teaches the gesture.
+const needsOnboarding = store.state.boards.length === 0;
+if (needsOnboarding) {
+  store.openBoardNew(true);
 }
 
 process.on("SIGINT", () => {
@@ -110,11 +107,20 @@ function applyResponsiveLayout(): void {
   // Report which zones FIT at this width. The store ANDs this with each zone's
   // enabled flag and the user's desired visibility, so a disabled or
   // intentionally-hidden zone is never force-shown just because there's room.
-  store.applyResponsiveFits({
-    planner: width >= 100,
-    timeline: width >= 150,
-    agents: width >= 120,
-  });
+  // `narrow` travels with the fits, in one call: below the planner's own
+  // breakpoint there is no room for two zones side by side, so rather than
+  // dropping every zone but the kanban — the least readable at that width, and
+  // the only one that cannot be hidden — the zones queue and are shown one at
+  // a time. Same threshold as the planner's, opposite effect: "does not fit"
+  // now means "not simultaneously", not "unreachable".
+  store.applyResponsiveFits(
+    {
+      planner: width >= 100,
+      timeline: width >= 150,
+      agents: width >= 120,
+    },
+    { narrow: width < 100 },
+  );
 }
 applyResponsiveLayout();
 process.stdout.on("resize", applyResponsiveLayout);
@@ -122,16 +128,29 @@ process.stdout.on("resize", applyResponsiveLayout);
 // Land on the Today/Tomorrow panel by default — for a daily-planning tool the
 // first question is "what's on my plate today", and that panel answers it. On
 // a narrow terminal where the panel auto-hides, fall back to the board.
-if (store.state.ui.visibleZones.planner) {
+if (!needsOnboarding && store.state.ui.visibleZones.planner) {
   store.setActiveZone("planner");
 }
 
+
 const { view } = parseArgs(process.argv.slice(2));
+// `--view=planner`: open on the Today/Tomorrow panel alone. The flag beats the
+// `zones:` config — someone typing it is asking for that zone — and it is a
+// starting state, not a cage: Shift-Tab still walks to the other zones.
+if (view === "planner") {
+  store.setZoneVisible("planner", true);
+  store.setActiveZone("planner");
+  store.setZoomed(true);
+}
 
 // ─── App shell ──────────────────────────────────────────────────────────────
 
 function rootViewFor(v: ViewKind | undefined, s: TuiStore) {
   switch (v) {
+    // `planner` is BoardOnly with the planner focused and single-pane forced:
+    // in that state BoardOnly already renders the panel alone, so a vertical
+    // strip needs a launch flag, not a new view.
+    case "planner":  return <BoardOnly store={s} />;
     case "board":    return <BoardOnly store={s} />;
     case "timeline": return <TimelineOnly store={s} />;
     case "agents":   return <AgentsOnly store={s} />;

package/src/boards/config-writer.ts

@@ -0,0 +1,191 @@
+/**
+ * Register a board in the user's config.
+ *
+ * This is the only place in tuiboard that edits a file the user wrote by
+ * hand — one that carries comments, calendar credentials, resume commands and
+ * whatever formatting its author preferred. So it does NOT read the YAML,
+ * modify an object and serialize it back: `js-yaml` does not preserve
+ * comments, and that round trip would hand back a reformatted, stripped
+ * document every time a board is added.
+ *
+ * Instead the only mutation needed — appending an entry to `boards:` — is done
+ * as a text insertion. Everything else in the file survives because it is
+ * never touched, rather than because someone remembered to copy it across.
+ *
+ * The YAML parser is still used, twice, as a judge: once to refuse a file that
+ * does not parse (guessing where to insert into a broken document is how a
+ * config gets destroyed), and once on the result, to abandon the write if the
+ * board did not land where it should. A failed addition beats a corrupt file.
+ */
+
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { basename, dirname, extname, isAbsolute, resolve } from "node:path";
+import * as YAML from "js-yaml";
+
+import { findConfigPath } from "~/config/loader";
+import { writeBoardFile } from "~/io/writer";
+
+export interface BoardEntry {
+  /** Path to the board file. Relative paths are made absolute before writing. */
+  path: string;
+  /** Display name. Defaults to the filename without extension. */
+  name?: string;
+}
+
+export interface AddBoardResult {
+  /** The config file written. */
+  configPath: string;
+  /** True when the config did not exist and was created by this call. */
+  created: boolean;
+  /** The name the board was registered under. */
+  name: string;
+}
+
+interface RawBoards {
+  boards?: Array<string | { path?: string; name?: string }>;
+}
+
+export function addBoardToConfig(entry: BoardEntry): AddBoardResult {
+  const path = resolve(entry.path);
+  const name = (entry.name ?? basename(path, extname(path))).trim();
+  if (!name) throw new Error("a board needs a name");
+
+  const { path: configPath, exists } = findConfigPath();
+
+  if (!exists) {
+    mkdirSync(dirname(configPath), { recursive: true });
+    writeBoardFile(configPath, renderFreshConfig(path, name));
+    return { configPath, created: true, name };
+  }
+
+  const original = readFileSync(configPath, "utf-8");
+
+  let parsed: RawBoards;
+  try {
+    parsed = (YAML.load(original) ?? {}) as RawBoards;
+  } catch (e) {
+    throw new Error(`${configPath} is not valid YAML: ${(e as Error).message}`);
+  }
+  if (typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`${configPath} does not hold a YAML mapping`);
+  }
+
+  assertNotRegistered(parsed, configPath, path, name);
+
+  const updated = insertBoard(original, path, name);
+
+  // Judge the result before it reaches the disk.
+  let after: RawBoards;
+  try {
+    after = (YAML.load(updated) ?? {}) as RawBoards;
+  } catch (e) {
+    throw new Error(`refusing to write: the result would not parse (${(e as Error).message})`);
+  }
+  const landed = (after.boards ?? []).some(
+    (b) => typeof b === "object" && b !== null && resolve(String(b.path ?? "")) === path,
+  );
+  if (!landed) {
+    throw new Error("refusing to write: the board did not land in `boards:` as expected");
+  }
+
+  writeBoardFile(configPath, updated);
+  return { configPath, created: false, name };
+}
+
+/**
+ * Both checks protect the same thing: `tuiboard task --board <name>` resolves
+ * by name, and the bar widget calls it. Two boards sharing a name — or one
+ * file registered twice — would make that command ambiguous.
+ */
+function assertNotRegistered(
+  parsed: RawBoards,
+  configPath: string,
+  path: string,
+  name: string,
+): void {
+  for (const b of parsed.boards ?? []) {
+    const existingPath = typeof b === "string" ? b : (b?.path ?? "");
+    const existingName =
+      typeof b === "string"
+        ? basename(b, extname(b))
+        : (b?.name ?? basename(existingPath, extname(existingPath)));
+
+    if (existingPath && resolve(existingPath) === path) {
+      throw new Error(`${path} is already registered in ${configPath}`);
+    }
+    if (existingName.toLowerCase() === name.toLowerCase()) {
+      throw new Error(`a board named "${existingName}" is already registered in ${configPath}`);
+    }
+  }
+}
+
+/** A config file for someone who had none: only what is needed, plus a pointer. */
+function renderFreshConfig(path: string, name: string): string {
+  return [
+    "# tuiboard config — https://github.com/NazzarenoGiannelli/tuiboard",
+    "# Boards are plain markdown files; add more with `+` in the board zone.",
+    "boards:",
+    ...renderEntry(path, name, "  "),
+    "",
+  ].join("\n");
+}
+
+function renderEntry(path: string, name: string, indent: string): string[] {
+  return [`${indent}- path: ${quote(path)}`, `${indent}  name: ${quote(name)}`];
+}
+
+/** Quote only when the value could be misread as YAML syntax. */
+function quote(value: string): string {
+  return /^[A-Za-z0-9_][A-Za-z0-9 _.\-]*$/.test(value) ? value : JSON.stringify(value);
+}
+
+/**
+ * The three shapes a real config presents:
+ *
+ *   boards:            → block list; append after its last entry
+ *     - path: …
+ *   boards: []         → inline empty list; replace with a block list
+ *   (no boards key)    → prepend the key
+ *
+ * Anything else inline (`boards: [{path: …}]`) is refused: rewriting flow
+ * style safely means re-serializing, which is exactly what this module exists
+ * to avoid.
+ */
+function insertBoard(original: string, path: string, name: string): string {
+  const lines = original.split("\n");
+  const keyIndex = lines.findIndex((l) => /^boards:\s*(#.*)?$/.test(l) || /^boards:\s*\S/.test(l));
+
+  if (keyIndex < 0) {
+    const block = ["boards:", ...renderEntry(path, name, "  "), ""];
+    return [...block, ...lines].join("\n");
+  }
+
+  const value = lines[keyIndex]!.replace(/^boards:\s*/, "").replace(/\s*#.*$/, "").trim();
+
+  if (value === "[]") {
+    lines.splice(keyIndex, 1, "boards:", ...renderEntry(path, name, "  "));
+    return lines.join("\n");
+  }
+  if (value !== "") {
+    throw new Error(
+      `refusing to edit \`boards: ${value}\` — rewrite it as a block list first`,
+    );
+  }
+
+  // Block list: walk to the last line belonging to it. Indented lines are part
+  // of the block; blank lines are only part of it if something indented
+  // follows, so a trailing blank line before the next key stays where it is.
+  let end = keyIndex;
+  let indent = "  ";
+  for (let i = keyIndex + 1; i < lines.length; i++) {
+    const line = lines[i]!;
+    if (line.trim() === "") continue;
+    if (!/^\s/.test(line)) break;
+    const dash = line.match(/^(\s*)- /);
+    if (dash) indent = dash[1]!;
+    end = i;
+  }
+
+  lines.splice(end + 1, 0, ...renderEntry(path, name, indent));
+  return lines.join("\n");
+}

package/src/boards/create.ts

@@ -0,0 +1,57 @@
+/**
+ * Write a new board file.
+ *
+ * The file is a plain Obsidian Kanban board: YAML frontmatter carrying
+ * `kanban-plugin: board`, then one `## Column` heading per column. Those two
+ * frontmatter lines are what make Obsidian render the file as a board instead
+ * of as a wall of text — which matters because these files are read on a
+ * phone as often as in this program.
+ *
+ * No `%% kanban:settings %%` trailer is written. Obsidian adds its own on the
+ * first setting change, and inventing one here would mean guessing at a
+ * format this project does not control.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+export interface CreateBoardOptions {
+  /** Column headings, in order. At least one.  */
+  columns: readonly string[];
+}
+
+/** Columns offered when the caller has no opinion. */
+export const DEFAULT_COLUMNS = ["Todo", "Doing", "Done"] as const;
+
+export function createBoardFile(path: string, { columns }: CreateBoardOptions): void {
+  const names = columns.map((c) => c.trim()).filter(Boolean);
+  if (names.length === 0) {
+    // A board with no columns has nowhere to put a task, and the TUI cannot
+    // yet add one. Refusing here beats handing back something unusable.
+    throw new Error("a board needs at least one column");
+  }
+
+  // Never overwrite: the target may be a file someone else wrote, and the
+  // caller's next best move — adopting it instead — is only possible if it
+  // still exists.
+  if (existsSync(path)) {
+    throw new Error(`${path} already exists`);
+  }
+
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, render(names), "utf-8");
+}
+
+/**
+ * The blank-line placement matches what Obsidian Kanban itself writes, so a
+ * board created here and one created there are the same document.
+ */
+function render(columns: readonly string[]): string {
+  const frontmatter = ["---", "", "kanban-plugin: board", "", "---", ""].join("\n");
+  const body = columns.map((name) => `\n## ${name}\n`).join("");
+  // The trailing blank line is what `serializeBoard` produces for a board
+  // whose last column is empty. Matching it means a file created here and the
+  // same file after tuiboard writes to it are byte-identical — so a fresh
+  // board never shows up as a spurious diff in the vault's git history.
+  return `${frontmatter}${body}\n`;
+}

package/src/boards/scan.ts

@@ -0,0 +1,95 @@
+/**
+ * Find the boards already sitting in a directory.
+ *
+ * This is what the "I already have files" path of onboarding offers: point at
+ * a folder, and see which of its markdown files are actually task boards.
+ *
+ * The recognition rule is deliberately the same one `loadConfig()` uses for
+ * its zero-config fallback — a `.md` file containing a `- [ ]` or `- [x]`
+ * line. Two rules would mean a file adopted by one path and ignored by the
+ * other, so the loader delegates here rather than keeping its own copy.
+ */
+
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, extname, join, resolve } from "node:path";
+
+/** How much of a file is read to decide whether it is a board. */
+const SNIFF_BYTES = 4096;
+
+const RE_TASK = /^- \[[ xX]\] /m;
+const RE_TASK_GLOBAL = /^- \[[ xX]\] /gm;
+/** Obsidian Kanban's marker — what tuiboard itself writes into a new board. */
+const RE_KANBAN = /^kanban-plugin:\s*board\s*$/m;
+
+export interface BoardCandidate {
+  /** Absolute path to the markdown file. */
+  path: string;
+  /** Filename without extension — what the board would be called. */
+  suggestedName: string;
+  /** Tasks found in the file, open and done. */
+  taskCount: number;
+  /** True when this file is already registered as a board. */
+  alreadyInConfig: boolean;
+}
+
+export interface ScanOptions {
+  /** Board paths already registered, so candidates can be marked. */
+  existingPaths?: readonly string[];
+}
+
+/**
+ * True when the file looks like a task board.
+ *
+ * Two ways to qualify, and the second is not optional: a board tuiboard has
+ * just created holds no tasks yet, so a checkbox-only rule would make the
+ * program blind to its own output until someone typed into it. The Kanban
+ * frontmatter marker settles those.
+ */
+export function isBoardFile(path: string): boolean {
+  if (extname(path).toLowerCase() !== ".md") return false;
+  try {
+    if (!statSync(path).isFile()) return false;
+    const head = readFileSync(path, "utf-8").slice(0, SNIFF_BYTES);
+    return RE_TASK.test(head) || RE_KANBAN.test(head);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * List the board files in `dir`, sorted by name.
+ *
+ * A missing or unreadable directory yields an empty list rather than an
+ * error: onboarding asks the user to type a path, and a typo should redraw
+ * the screen with "nothing here", not end the session.
+ */
+export function scanDirectory(dir: string, { existingPaths = [] }: ScanOptions = {}): BoardCandidate[] {
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return [];
+  }
+
+  const known = new Set(existingPaths.map((p) => resolve(p)));
+
+  return entries
+    .map((name) => join(dir, name))
+    .filter(isBoardFile)
+    .sort()
+    .map((path) => ({
+      path,
+      suggestedName: basename(path, extname(path)),
+      taskCount: countTasks(path),
+      alreadyInConfig: known.has(resolve(path)),
+    }));
+}
+
+/** Tasks in the whole file — the sniff window is only for recognition. */
+function countTasks(path: string): number {
+  try {
+    return readFileSync(path, "utf-8").match(RE_TASK_GLOBAL)?.length ?? 0;
+  } catch {
+    return 0;
+  }
+}

package/src/boards/suggest.ts

@@ -0,0 +1,34 @@
+/**
+ * Where a new board file should be born.
+ *
+ * The answer that serves the user best is "next to the boards you already
+ * have": that is usually a synced, versioned folder — a vault — so a board
+ * created here inherits replication, git history and Obsidian rendering
+ * without anyone configuring anything.
+ *
+ * When there is nothing to learn from — no boards yet, or boards scattered
+ * across unrelated folders — the fallback is an XDG data directory the app
+ * owns. Someone who installed tuiboard five minutes ago and has no vault
+ * still gets a working board.
+ *
+ * This only ever produces a *proposal*. The path is shown and editable before
+ * anything is written, so a wrong guess costs a keystroke, not a lost file.
+ */
+
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+import type { Config } from "~/config/loader";
+
+/** The app-owned directory, honouring XDG_DATA_HOME when set. */
+export function defaultBoardsDir(): string {
+  const xdg = process.env.XDG_DATA_HOME;
+  const base = xdg && xdg.trim() ? xdg : join(homedir(), ".local", "share");
+  return join(base, "tuiboard", "boards");
+}
+
+export function suggestBoardsDir(config: Pick<Config, "boards">): string {
+  const dirs = new Set((config.boards ?? []).map((b) => dirname(resolve(b.path))));
+  if (dirs.size === 1) return [...dirs][0]!;
+  return defaultBoardsDir();
+}

package/src/cli/args.ts

@@ -4,9 +4,9 @@
  * value flags) would warrant a real CLI library — YAGNI here.
  */
 
-export type ViewKind = "board" | "timeline" | "agents";
+export type ViewKind = "board" | "planner" | "timeline" | "agents";
 
-const VALID_VIEWS: readonly ViewKind[] = ["board", "timeline", "agents"];
+const VALID_VIEWS: readonly ViewKind[] = ["board", "planner", "timeline", "agents"];
 
 export interface ParsedArgs {
   /** Undefined means: render the default Dashboard (all 4 zones). */