tuiboard 0.8.3 → 0.9.0

package/.tuiboard/config.example.yaml

@@ -62,6 +62,15 @@ archive_column: Archive
 #   - "{cwd}"
 #   - "{sessionId}"
 
+# Optional: the command copied to your clipboard by `c` in the Agents zone — one
+# paste that cd's into the session's directory and resumes it, for when you want
+# to open the session yourself in a new tab/pane anywhere (no WezTerm needed).
+# The tokens {cwd} and {sessionId} are substituted. It's a plain string, so use
+# whatever chaining your shell wants. Default (works in bash/zsh/pwsh/cmd):
+#   copy_resume_command: 'cd "{cwd}" && claude --resume {sessionId}'
+# Nushell users typically want `;` instead of `&&`:
+# copy_resume_command: 'cd "{cwd}"; claude --resume {sessionId}'
+
 # Optional: overlay read-only calendar events on the Agenda (the 24h timeline).
 # Connect a provider with `tuiboard calendar-setup google` / `... microsoft`,
 # which opens the auth flow and prints the exact block to paste here. Bring your

package/CHANGELOG.md

@@ -5,6 +5,105 @@ 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.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
+- **`tuiboard summary` — JSON snapshot for status bars and scripts.** Totals, a
+  per-board breakdown, and `planner`: the same Today / Tomorrow / Overdue
+  aggregation the planner zone renders, built from `buildPlannerItems()` so a
+  bar widget and the dashboard can never disagree about what is due. `--pretty`
+  to read it, `--next N` to size (or drop) the per-board upcoming list.
+- **`tuiboard task` — headless mutations.** `done`, `undone`, `defer` and `add`
+  against a board file, matched **by title rather than index** so a task that
+  moved is a miss instead of the wrong task. `--dry-run` reports without
+  writing; an ambiguous title is refused rather than guessed at; exit 3 means
+  the board changed on disk since it was read.
+- **`undone` reopens a completed task**, dropping its `✅` date with the tick —
+  the exact inverse of `done`, and the same semantics as the TUI's Enter.
+- **`defer` moves the date the planner actually reads** (`scheduled`, else
+  `due`, else adds a `scheduled`), so the row really moves. Defaults to
+  tomorrow; `--days N` or `--to YYYY-MM-DD` for anything else, `--days 0` to
+  pull a task back to today.
+- **Planner entries in `summary` now report `done` and `doneDate`.** Today and
+  Tomorrow keep completed tasks — a day's plan is a record of the day — so
+  without this a consumer had no way to tell a ticked task from an open one.
+
+### Fixed
+- **Node's warnings no longer scribble on the dashboard.** OpenTUI registers one
+  `selection` listener per `<scrollbox>`, and a full dashboard keeps more than
+  ten alive (one per board column, plus planner, timeline and agents), tripping
+  Node's default `MaxListeners` cap of 10 — usually when `Tab` mounted a new
+  board's columns. The warning went to stderr, which is the alternate screen the
+  renderer believes it owns: two lines scrolled the buffer and every repaint
+  after that landed rows off, so the layout appeared to break on a keypress. The
+  cap is now sized for the real number of zones, and any remaining warning is
+  filed in `~/.cache/tuiboard/warnings.log` instead of on the screen.
+
+## [0.8.4] - 2026-07-31
+
+### Added
+- **Copy a session's resume command (`c` in the Agents zone).** Select a Claude
+  Code session and press `c` to copy a one-paste command that `cd`s into its
+  directory and resumes it — `cd "<cwd>" && claude --resume <id>` by default — so
+  you can drop it into any tab or pane, on any machine layout, without depending
+  on WezTerm (which `Enter` requires). The format is configurable via
+  `copy_resume_command` (tokens `{cwd}` / `{sessionId}`); Nushell users can swap
+  `&&` for `;`. The session detail view (`o`) now shows this exact command.
+
+### Fixed
+- **Modals now appear in zoom mode.** Opening a modal (new task, schedule, time
+  block, assign, edit, delete, search, new event…) while a zone was zoomed (`z`)
+  set the modal state but rendered nothing — the zoomed layout had no Agenda slot
+  to host it, so the dialog was invisible and you typed blind. The modal now
+  floats as a centered overlay on top of the zoomed view; closing it returns you
+  to the zoomed view exactly as you left it.
+
 ## [0.8.3] - 2026-06-04
 
 ### Added
@@ -174,6 +273,9 @@ 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
 [0.8.2]: https://github.com/NazzarenoGiannelli/tuiboard/releases/tag/v0.8.2
 [0.8.1]: https://github.com/NazzarenoGiannelli/tuiboard/releases/tag/v0.8.1

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
@@ -147,6 +160,12 @@ archive_column: Archive
 # path, NOT a shell builtin or Windows App Execution Alias). Defaults to
 # opening a WezTerm tab with `claude --resume <id>`. For a custom layout:
 # resume_command: ["nu", "C:/Users/you/.config/tuiboard/code-resume.nu", "{cwd}", "{sessionId}"]
+
+# Optional: the command `c` copies to the clipboard in the Agents zone — one
+# paste that cd's into the session dir and resumes it, so you can open it
+# yourself in any tab/pane (no WezTerm needed). {cwd}/{sessionId} substituted.
+# Default: 'cd "{cwd}" && claude --resume {sessionId}'. Nushell users:
+# copy_resume_command: 'cd "{cwd}"; claude --resume {sessionId}'
 ```
 
 ## Zones
@@ -356,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 |
@@ -367,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).
@@ -383,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) |
@@ -397,6 +420,15 @@ session (until the next terminal resize).
 | `j` / `k` | While armed: nudge the block ±15 min |
 | `+` / `-` | While armed: resize the block's end ±15 min |
 
+### Agents (agents zone)
+
+| Key | Action |
+|---|---|
+| `j` / `k` | Move the cursor down / up the session list |
+| `Enter` | Open (resume) the selected session in a new WezTerm tab |
+| `c` | Copy a one-paste `cd … && claude --resume <id>` command for the selected session — drop it into any tab/pane to land in the right dir and resume (no WezTerm needed; format is `copy_resume_command`) |
+| `o` | Session detail (cwd, branch, last prompts, resume command) |
+
 ### Task actions (work in board, planner, AND timeline zones)
 
 | Key | Action |
@@ -433,10 +465,79 @@ session (until the next terminal resize).
 | `?` | Help modal with the full reference |
 | `q` · `Ctrl-C` | Quit |
 
+## Headless commands
+
+Two subcommands run without the TUI, for status bars, widgets and scripts.
+Both reuse the same config loader and parser as the dashboard, so they can
+never disagree with it about what is on your board.
+
+### `tuiboard summary` — JSON snapshot
+
+```bash
+tuiboard summary                # compact JSON on stdout
+tuiboard summary --pretty       # indented, for reading
+tuiboard summary --next 8       # upcoming tasks per board (default 5, 0 = none)
+```
+
+Returns totals, a per-board breakdown, and `planner` — the same Today /
+Tomorrow / Overdue aggregation the planner zone renders, each entry carrying
+its title, board, column, bucket, priority, dates, time block, assignee, and
+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
+tuiboard task done   --board Personal --column Home --match "Bollette"
+tuiboard task undone --board Personal --column Home --match "Bollette"
+tuiboard task defer  --board Personal --column Home --match "Bollette" [--days N | --to YYYY-MM-DD]
+tuiboard task add    --board Personal --column Home --text "Nuova task 🔺 ⏳ 2026-09-01"
+```
+
+`--dry-run` reports what would change and writes nothing. `defer` defaults to
+one day and moves the date the planner actually reads (`scheduled`, else
+`due`, else adds a `scheduled`), so the row really moves; `--days 0` pulls a
+task back to today.
+
+Tasks are matched **by title, not by index**: a position is only valid inside
+one render pass, and a widget polling every couple of minutes holds a stale
+snapshot — matching on text makes a moved task a miss rather than a mistake.
+An ambiguous match is refused rather than guessed at.
+
+| Exit | Meaning |
+|---|---|
+| `0` | Done (including "already done" / "already open" — both are no-ops) |
+| `1` | No match, ambiguous match, or unknown board/column |
+| `2` | Bad arguments |
+| `3` | The board changed on disk since it was read — refresh and retry |
+
+Exit 3 is the mtime watermark: a write is refused rather than allowed to
+clobber an edit made in the TUI or another editor in the meantime.
+
 ## Status
 
 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.
@@ -451,6 +552,15 @@ See [CHANGELOG.md](CHANGELOG.md) for the full release history.
   responsive layout. Tested on Windows with WezTerm; Linux/macOS should
   work via the same OpenTUI binaries (untested).
 
+## Contributing
+
+Contributions are welcome — bugs, docs, fixes, features, or just trying it on a
+platform I haven't tested. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, the
+project layout, and the checks to run, and the [good first issues][gfi] for a
+place to start.
+
+[gfi]: https://github.com/NazzarenoGiannelli/tuiboard/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
+
 ## License
 
 MIT — see [LICENSE](LICENSE).

package/bin/tuiboard.ts

@@ -29,6 +29,18 @@ if (process.argv[2] === "calendar-setup") {
   const { runCalendarSetup } = await import("../src/calendar/setup.ts");
   process.exit(await runCalendarSetup(process.argv.slice(3)));
 }
+if (process.argv[2] === "summary") {
+  const { runSummary } = await import("../src/cli/summary.ts");
+  process.exit(await runSummary(process.argv.slice(3)));
+}
+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.3",
+  "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",
@@ -32,7 +32,10 @@
     "tb": "./bin/tuiboard.ts"
   },
   "files": [
+    "tsconfig.json",
     "src/",
+    "!src/**/*.test.ts",
+    "!src/scripts/",
     "bin/",
     ".tuiboard/config.example.yaml",
     "README.md",
@@ -47,6 +50,7 @@
     "typecheck": "tsc --noEmit",
     "test": "bun test",
     "agents:check": "bun run src/scripts/agents-check.ts",
+    "summary": "bun run src/cli/summary.ts",
     "prepublishOnly": "bun run typecheck && bun test"
   },
   "dependencies": {

package/src/app.tsx

@@ -16,6 +16,11 @@
 // (OpenTUI) and the ~600ms store build below run. See ui/splash-boot.ts.
 import "~/ui/splash-boot";
 
+import { EventEmitter } from "node:events";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
 import { createMemo } from "solid-js";
 import { render, useKeyboard } from "@opentui/solid";
 
@@ -35,22 +40,48 @@ import { Dashboard } from "~/views/Dashboard";
 import { TimelineOnly } from "~/views/TimelineOnly";
 import { AgentsOnly } from "~/views/AgentsOnly";
 
+// ─── Keep Node's own output off the screen ──────────────────────────────────
+//
+// OpenTUI registers one "selection" listener on the renderer per <scrollbox>,
+// and a dashboard keeps more than ten alive at once: one per board column,
+// plus planner, timeline and agents. That is a legitimate count, not a leak,
+// but it trips Node's default MaxListeners cap of 10 — and switching board
+// with Tab crosses the threshold as the new columns mount.
+EventEmitter.defaultMaxListeners = 64;
+
+// Whatever still warns must never reach the terminal. Node writes warnings to
+// stderr, which here means straight onto the alternate screen the renderer
+// believes it owns: the two extra lines scroll the buffer, and from then on
+// every absolutely-positioned repaint lands a couple of rows off — the layout
+// appears to "break" on the next keypress. Removing the default handler stops
+// Node printing them; ours files them where they can still be read.
+process.removeAllListeners("warning");
+process.on("warning", (w: Error) => {
+  try {
+    const dir = join(homedir(), ".cache", "tuiboard");
+    mkdirSync(dir, { recursive: true });
+    appendFileSync(
+      join(dir, "warnings.log"),
+      `${new Date().toISOString()} ${w.name}: ${w.message}\n${w.stack ?? ""}\n`,
+    );
+  } catch {
+    // A log we cannot write is not worth losing the screen over.
+  }
+});
+
 // ─── 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", () => {
@@ -76,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);
@@ -88,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");
+}