local-kanban 1.12.0 → 1.14.0

package/CHANGELOG.md

@@ -3,6 +3,73 @@
 Notable changes, newest first. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and the project uses [semantic versioning](https://semver.org/).
 
+Anything not shipped yet is collected under **Unreleased**; releasing renames that section to the
+version it goes out as and opens an empty one again. Released sections are history and stay as they are.
+
+## [Unreleased]
+
+## [1.14.0]
+
+### Added
+
+- **`kb` shows how tasks are linked, and can make a sub-task.** The board keeps parents, sub-tasks and
+  related tasks, but `kb show` and `kb take` printed none of them, so Claude could not know that two
+  tasks were meant to go together. Both commands now print one line per link: `↑ parent`,
+  `↓ subtask`, `↔ related`, with the key, title and status. `kb link A B child` makes B a sub-task
+  of A, `kb link A B parent` makes it A's parent; without a third word the link is related, as before.
+- **`kb info` prints the project's description and its documents.** The description is where owners
+  keep the context for work, and it never reached Claude. A `docs:` line now lists the documents to
+  read before a task (`CLAUDE.md`, `README.md`, `ARCHITECTURE.md` …) and says so plainly when there is
+  no `CLAUDE.md` or the project folder is not on this machine.
+- **`kb check <key> <n>` / `kb uncheck` tick checklist items from the CLI.** Claude could read the
+  checklist but not tick it, so at acceptance every box was empty and the human could not tell what
+  of the list was done. The item is addressed by its number in the order `kb show` prints it.
+- **`KB_GH_BIN` points the board at `gh` when it lives somewhere unusual.** The board looks for `gh`
+  in the usual install locations (Homebrew, `/usr/bin`, `~/.local/bin`) and then on `PATH`; a copy
+  anywhere else can now be named explicitly.
+
+### Fixed
+
+- **`kb` no longer loses what the human wrote in a card.** `kb take` printed only the latest note
+  from the human, so a send-back followed by a second note lost the first; `kb show` printed the last
+  five comments of any author, and Claude's own notes plus the commit stats pushed the human's note
+  out without a word. Both now print every note the human left since Claude's last report, each
+  comment carries its date and time, and anything left out is counted ("… 3 more comments not
+  printed") instead of dropped silently.
+- **A commit stat is no longer printed as the human speaking.** `kb show` marked everything that was
+  not Claude's with 👤, including the commit stat the board attaches on its own. It is marked ⎇ now.
+- **`kb take` tells a blocked To do from an empty one.** When every card in To do was blocked it
+  answered a bare `empty`, and Claude reported an empty column while the human could see cards in
+  it. It now says `empty (2 blocked)`; `kb next` does the same.
+- **`kb take` and `kb show` print the issue the same way** — `issue: #42 <link>`. One printed the
+  number and the other the link.
+- **The checklist now reaches Claude.** A card's checklist is shown on the board right under the
+  description, but `kb show` and `kb take` printed everything about the task except it — the CLI is
+  the only channel Claude has, so the items simply did not exist for it: a card with three checklist
+  items and an empty description arrived as a bare title. Both commands now print the items as
+  `- [ ]` / `- [x]` lines, in the board's order, right after the description.
+
+## [1.13.0]
+
+### Added
+
+- **The board tells you what's new.** The changelog was written for every release and shown nowhere:
+  the only place to read it was the package page on npm. The About screen now has a "What's new"
+  block. For the version you are running it reads the `CHANGELOG.md` that ships next to the code, so
+  it needs no network at all. When an update is waiting, it shows the notes of the version you do
+  *not* have yet, read from that release's page on GitHub — the decision to update is made on what
+  actually changed, not on a version number. Releases now get such a page: publishing puts the
+  changelog section for that version into it, which also gives the npm page real releases to link to.
+
+### Fixed
+
+- **A folder the board is not allowed to read is no longer reported as missing.** The Check button
+  next to the project folder answered every refusal the same way — "no such folder on this computer" —
+  whether the folder was absent, was a file, or simply could not be read. For a folder without
+  permissions that is plainly untrue: it is there, the board was not let in, and the answer sent you
+  off to fix a path that was already correct. Each case now says what actually happened, and a check
+  that could not reach the server says so instead of blaming the path.
+
 ## [1.12.0]
 
 ### Added

package/README.md

@@ -142,6 +142,7 @@ Releases live in `main` (stable, tagged); day-to-day development happens in `dev
 | `KB_PANEL_INFO` | — | optional path to an external panel's info.json for category sync |
 | `KB_SSE_MAX` | `20` | cap on concurrent SSE connections |
 | `KB_SKILLS_EXTRA` | — | extra skill root directories, `:`-separated |
+| `KB_GH_BIN` | — | path to the `gh` binary when it is not in a usual place (Homebrew, `/usr/bin`, `~/.local/bin`) |
 
 The legacy names `PANEL_URL` and `PANEL_INFO` (without the prefix) still work as a fallback.
 

package/README.ru.md

@@ -141,6 +141,7 @@ npm run update   # git pull + npm install + pm2 restart (если примени
 | `KB_PANEL_INFO` | — | опциональный info.json внешней панели для синка категорий |
 | `KB_SSE_MAX` | `20` | потолок одновременных SSE-соединений |
 | `KB_SKILLS_EXTRA` | — | дополнительные корни скиллов через `:` |
+| `KB_GH_BIN` | — | путь к `gh`, если он лежит не в обычном месте (Homebrew, `/usr/bin`, `~/.local/bin`) |
 
 Старые имена `PANEL_URL` и `PANEL_INFO` (без префикса) продолжают работать как запасные.
 

package/bin/kb

@@ -63,8 +63,96 @@ function taskLine(t) {
   return `${t.key} ${t.status}${flags ? ' ' + flags : ''} ${t.title}${labels}`;
 }
 
+// The checklist is part of the task's spec: the board shows it right under the description, and
+// this CLI is the only channel Claude has — an item that is not printed here does not exist for
+// Claude. Markdown task-list lines, `- [ ]` open and `- [x]` done, in the board's order.
+function printChecklist(t) {
+  for (const c of (t.checklist || [])) console.log(`- [${c.done ? 'x' : ' '}] ${c.text}`);
+}
+
+// here, and the skill's rule "related tasks solved together are taken together" cannot be followed
+// without knowing they are related. `rel` is relative to this task: 'parent' — the other task is
+// this one's parent, 'child' — the other task is a sub-task of this one, 'related' — symmetric.
+const REL = { parent: ['↑', 'parent'], child: ['↓', 'subtask'], related: ['↔', 'related'] };
+function printLinks(t) {
+  for (const l of (t.links || [])) {
+    const [arrow, word] = REL[l.rel] || REL.related;
+    console.log(`${arrow} ${word} ${l.key} ${l.title} (${l.status})`);
+  }
+}
+const linksLine = (id, links) => `${id} ${links.map((l) => (REL[l.rel] || REL.related)[0] + l.key).join(' ') || '—'}`;
+
+// the skill had to explain two formats. The number goes into commit messages, the link is for eyes.
+function printIssue(t) {
+  if (t.gh_issue_number) console.log(`issue: #${t.gh_issue_number}${t.gh_issue_url ? ' ' + t.gh_issue_url : ''}`);
+  else if (t.gh_issue_url) console.log(`issue: ${t.gh_issue_url}`);
+}
+
+// sees cards in the column, and a bare "empty" made Claude report that there was nothing there.
+function emptyLine(todo) {
+  const blocked = todo.filter((t) => t.blocked).length;
+  return blocked ? `empty (${blocked} blocked)` : 'empty';
+}
+
+function printAttachments(t) {
+  for (const a of (t.attachments || [])) console.log(`📎 screenshot (open it with Read): ${a.path}`);
+}
+
+// Comments. Three authors: the human ('me'), Claude, and 'git' — the commit stat the board attaches
+// by itself on the move to review. Each gets its own mark: a commit printed as 👤 read as the human
+const WHO = { claude: '🤖', git: '⎇' };
+
+// The database keeps UTC ('YYYY-MM-DD HH:MM:SS'); print local time, to the minute — enough to tell
+function when(c) {
+  const d = new Date(String(c.created_at || '').replace(' ', 'T') + 'Z');
+  if (Number.isNaN(d.getTime())) return '';
+  const p = (n) => String(n).padStart(2, '0');
+  return `[${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}] `;
+}
+
+function printComment(c) {
+  const at = when(c);
+  if (c.body) console.log(`> ${WHO[c.author] || '👤'} ${at}${c.author === 'git' ? 'commit ' : ''}${c.body}`);
+  if (c.image_path) console.log(`📎 image from a comment ${at}(open it with Read): ${c.image_path}`);
+}
+
+// Claude's last report — not just the latest one (a send-back plus a follow-up note lost the first)
+// and not whatever happens to fit a window of the last few (Claude's own notes and commit stats
+// pushed the human out of it). Those are always printed; `window` adds the last N comments of any
+// author on top, and the latest images stay too — they are usually the correction itself. When the
+// human has said nothing since the last report, the last thing they did say is printed, dated, so
+// it can be told apart from a fresh one. Whatever is left out is counted, never dropped silently.
+function printComments(cs, window) {
+  const keep = new Set();
+  let lastReport = -1;
+  cs.forEach((c, i) => { if (c.author === 'claude') lastReport = i; });
+  const human = (c) => c.author !== 'claude' && c.author !== 'git';
+  cs.forEach((c, i) => { if (i > lastReport && human(c)) keep.add(i); });
+  if (!keep.size) {
+    const i = cs.findLastIndex((c) => human(c) && c.body);
+    if (i >= 0) keep.add(i);
+  }
+  for (let i = Math.max(0, cs.length - window); i < cs.length; i++) keep.add(i);
+  cs.map((c, i) => (c.image_path ? i : -1)).filter((i) => i >= 0).slice(-3).forEach((i) => keep.add(i));
+  const hidden = cs.length - keep.size;
+  if (hidden > 0) console.log(`… ${hidden} more comment${hidden === 1 ? '' : 's'} not printed — the board has them all`);
+  cs.forEach((c, i) => { if (keep.has(i)) printComment(c); });
+}
+
 const [cmd, ...args] = process.argv.slice(2);
 
+async function tick(done) {
+  const [id, n] = args;
+  const no = Number(n);
+  if (!id || !Number.isInteger(no) || no < 1) die(`kb ${done ? 'check' : 'uncheck'} <key> <n>  (n = the item number, from 1, in the order kb show prints them)`);
+  const t = await api('GET', `/api/tasks/${id}`);
+  const items = t.checklist || [];
+  if (no > items.length) die(`kb: ${t.key} has ${items.length ? `only ${items.length} checklist item${items.length === 1 ? '' : 's'}` : 'no checklist'}`);
+  const item = await api('PATCH', `/api/tasks/${id}/checklist/${items[no - 1].id}`, { done });
+  const open = items.filter((c, i) => (i === no - 1 ? !item.done : !c.done)).length;
+  console.log(`${t.key} - [${item.done ? 'x' : ' '}] ${item.text} (${open} open)`);
+}
+
 const commands = {
   async p() {
     const ps = await api('GET', '/api/projects');
@@ -91,28 +179,27 @@ const commands = {
     if (!proj) die('kb next <project>');
     const ts = await api('GET', `/api/tasks?${new URLSearchParams({ project: proj, status: 'todo' })}`);
     const free = ts.filter((t) => !t.blocked);
-    console.log(free.length ? taskLine(free[0]) : 'empty');
+    console.log(free.length ? taskLine(free[0]) : emptyLine(ts));
   },
 
-  // take the next task and put it straight into prep (study before code); prints the last
-  // comment from the human (notes from a send-back). Writing code → kb mv <key> doing.
+  // take the next task and put it straight into prep (study before code); prints what the human
+  // wrote since Claude's last report (notes from a send-back). Writing code → kb mv <key> doing.
   async take() {
     const [proj] = args;
     if (!proj) die('kb take <project>');
     const ts = await api('GET', `/api/tasks?${new URLSearchParams({ project: proj, status: 'todo' })}`);
     const free = ts.filter((t) => !t.blocked);
-    if (!free.length) return console.log('empty');
+    if (!free.length) return console.log(emptyLine(ts));
     const t = await api('PATCH', `/api/tasks/${free[0].id}`, { status: 'prep' });
     console.log(taskLine({ ...t, labels: t.labels }));
     if (t.description) console.log(t.description);
-    if (t.gh_issue_number) console.log(`issue: ${t.gh_issue_number}`);
-    const atts = await api('GET', `/api/tasks/${t.id}/attachments`);
-    for (const a of atts) console.log(`📎 screenshot (open it with Read): ${a.path}`);
-    const cs = await api('GET', `/api/tasks/${t.id}/comments`);
-    const lastHuman = cs.filter((c) => c.author === 'me' && c.body).pop();
-    if (lastHuman) console.log(`> 👤 ${lastHuman.body}`);
-    // comments often carry corrections — print the paths of the latest images so they get opened
-    for (const c of cs.filter((c) => c.image_path).slice(-3)) console.log(`📎 image from a comment (open it with Read): ${c.image_path}`);
+    // PATCH answers with the bare row; the checklist and the attachments live on the full card
+    const full = await api('GET', `/api/tasks/${t.id}`);
+    printChecklist(full);
+    printLinks(full);
+    printIssue(full);
+    printAttachments(full);
+    printComments(await api('GET', `/api/tasks/${t.id}/comments`), 0);
   },
 
   // leave a note and move to review in one command
@@ -131,13 +218,11 @@ const commands = {
     console.log(`${t.key} ${t.project} ${t.status}${t.blocked ? ` blocked: ${t.blocked_reason || ''}` : ''}${PRI[t.priority] ? ' ' + PRI[t.priority] : ''}${t.labels.length ? ' [' + t.labels.join(',') + ']' : ''}`);
     console.log(t.title);
     if (t.description) console.log(t.description);
-    if (t.gh_issue_url) console.log(`issue: ${t.gh_issue_url}`);
-    for (const a of (t.attachments || [])) console.log(`📎 screenshot (open it with Read): ${a.path}`);
-    const cs = await api('GET', `/api/tasks/${id}/comments`);
-    for (const c of cs.slice(-5)) {
-      if (c.body) console.log(`> ${c.author === 'claude' ? '🤖' : '👤'} ${c.body}`);
-      if (c.image_path) console.log(`📎 image from a comment (open it with Read): ${c.image_path}`);
-    }
+    printChecklist(t);
+    printLinks(t);
+    printIssue(t);
+    printAttachments(t);
+    printComments(await api('GET', `/api/tasks/${id}/comments`), 5);
   },
 
   async add() {
@@ -222,20 +307,28 @@ const commands = {
     console.log(`${t.key} 📝`);
   },
 
+  // kb link A B [child|parent|related] — `child`: B becomes a sub-task of A, `parent`: B becomes
+  // A's parent. Without a third word the link is plain `related`, as it always was. A pair holds
+  // one link, so linking again with another word re-types it.
   async link() {
-    const [id, other] = args;
-    if (!id || !other) die('kb link <key> <key>  (link two tasks)');
-    const links = await api('POST', `/api/tasks/${id}/links`, { key: other });
-    console.log(`${id} ↔ ${links.map((l) => l.key).join(', ') || '—'}`);
+    const [id, other, rel = 'related'] = args;
+    if (!id || !other || !REL[rel]) die('kb link <key> <key> [child|parent|related]  (child: the second task becomes a sub-task of the first)');
+    const links = await api('POST', `/api/tasks/${id}/links`, { key: other, rel });
+    console.log(linksLine(id, links));
   },
 
   async unlink() {
     const [id, other] = args;
     if (!id || !other) die('kb unlink <key> <key>');
     const links = await api('DELETE', `/api/tasks/${id}/links/${other}`);
-    console.log(`${id} ↔ ${links.map((l) => l.key).join(', ') || '—'}`);
+    console.log(linksLine(id, links));
   },
 
+  // empty and could not tell what of the list was done. The item is addressed by its number — the
+  // position in which show/take print it (the board's order), counting from 1.
+  async check() { await tick(true); },
+  async uncheck() { await tick(false); },
+
   async block() {
     const [id, reason] = args;
     if (!id) die('kb block <key> ["reason"]');
@@ -268,6 +361,17 @@ const commands = {
     const services = parsePm2Services(p.pm2_services);
     if (services.length) out.push(`pm2: ${services.join(', ')}`);
     if (p.domain) out.push(`domain: ${p.domain}`);
+    // CLAUDE.md", "deployed by skill X", DNS facts) — info printed everything but it
+    if (p.description) out.push(`description: ${p.description}`);
+    // page; without this line Claude went looking by itself and sometimes missed. A missing
+    // CLAUDE.md is said out loud — it is a signal (the task starts without architecture notes).
+    if (p.path) {
+      const d = await api('GET', `/api/projects/${encodeURIComponent(p.slug)}/docs`);
+      const found = (d.docs || []).filter((x) => x.exists).map((x) => x.name);
+      if (!d.path_exists) out.push('docs: — the project folder does not exist on this machine');
+      else if (!found.includes('CLAUDE.md')) out.push(`docs: no CLAUDE.md${found.length ? ` — read ${found.join(', ')} instead` : ', and no README.md / ARCHITECTURE.md either'}`);
+      else out.push(`docs: ${found.join(', ')}`);
+    }
     console.log(out.join('\n'));
   },
 
@@ -297,7 +401,7 @@ const commands = {
 };
 
 if (!cmd || !commands[cmd]) {
-  die('kb p|ls|next|take|show|add|mv|review|done|cancel|pri|lbl|desc|note|link|unlink|block|unblock|rm|info|svc|sync|retry');
+  die('kb p|ls|next|take|show|add|mv|review|done|cancel|pri|lbl|desc|note|link|unlink|check|uncheck|block|unblock|rm|info|svc|sync|retry');
 }
 commands[cmd]().catch((e) => {
   // die() inside a command already exited the process — only real exceptions reach here.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "local-kanban",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "license": "MIT",
   "author": "Dannylamao",
   "repository": {

package/public/js/core.js

@@ -375,9 +375,11 @@ const I18N_RU = {
   'Claude moves these columns itself': 'эти колонки двигает сам Claude',
   'no file': 'файла нет',
   'no folders inside': 'внутри нет папок',
+  'no notes for this version': 'для этой версии заметок нет',
   'no such folder on this computer': 'такой папки на этом компьютере нет',
   'not deleted': 'не удалено',
   'not installed': 'не установлен',
+  'not installed yet': 'ещё не установлена',
   'not set': 'не задан',
   'not set — no deploy': 'не задан — деплоя нет',
   'not there': 'нет файла',
@@ -425,11 +427,13 @@ const I18N_RU = {
   'subfolders': 'подпапок',
   'key is free': 'ключ свободен',
   'task prefix': 'префикс задач',
+  'the folder is there, but the board cannot read it — check its permissions': 'папка есть, но доска не может её прочитать — посмотри права доступа',
   'this key is already taken by': 'этот ключ уже занят проектом',
   'no such host — check the name, or add it to your ~/.ssh/config': 'такого хоста нет — проверь имя или добавь его в свой ~/.ssh/config',
   'the server refused the key — a password will not help here, the key has to be authorized': 'сервер не принял ключ — пароль тут не поможет, ключ надо разрешить на сервере',
   'the host key is unknown — connect once from your terminal and confirm the fingerprint': 'ключ хоста неизвестен — подключись разок из терминала и подтверди отпечаток',
   'the server did not answer — wrong address, wrong port, or it is down': 'сервер не ответил — не тот адрес, не тот порт или он лежит',
+  'could not check the folder': 'не удалось проверить папку',
   'could not connect': 'подключиться не вышло',
   'on create, git clone puts it on THIS computer at': 'при создании git clone положит его на ЭТОТ компьютер в',
   'An existing folder is refused, not overwritten. Git credentials are not asked here — access comes from your own git and ssh setup.': 'Если папка уже есть — откажет, а не перезапишет. Логин git тут не спрашивается: доступ берётся из твоих git-настроек и ssh-ключей.',
@@ -535,6 +539,7 @@ const I18N_RU = {
   'recovered on retry': 'починилось повторной попыткой',
   'related': 'связана',
   'Read': 'Открыть',
+  'release page': 'страница релиза',
   'Reload now': 'Обновить сейчас',
   'Reload the page': 'Обновить страницу',
   'remove': 'убрать',
@@ -636,6 +641,7 @@ const I18N_RU = {
   'The board could not reach the server — the change was not saved': 'доска не достучалась до сервера — правка не сохранена',
   'capped: the task sat in a working column too long': 'урезано: задача слишком долго лежала в рабочей колонке',
   'To do': 'Сделать',
+  'this path is not a folder': 'по этому пути не папка',
   'Today': 'Сегодня',
   'Top projects': 'Топ проектов',
   'Tue': 'Вт',
@@ -657,6 +663,7 @@ const I18N_RU = {
   'waiting for the board to come back…': 'жду, пока доска поднимется…',
   'Waiting for you': 'Ждёт тебя',
   'Wed': 'Ср',
+  "What's new": 'Что нового',
   'Week': 'Неделя',
   'Weeks': 'Недели',
   'Welcome!': 'Добро пожаловать!',

package/public/js/settings.js

@@ -6,6 +6,35 @@ import { checkVersion, pendingReload } from './init.js';
 import { loadProjects, popLayer, pushLayer, setupPromptBlockHTML, styledAlert, styledConfirm, styledPrompt, wireSetupPrompt } from './sidebar.js';
 import { SHORT_MONTHS, SOUND_LIB, STATUS_LABELS, audioCtx, lastMissedAt, lastSseAt, missedSounds, pageLoadedAt, playNamedSound, refresh, relTime, titleOr, updateSoundBadge } from './sse.js';
 
+function mdInline(text) {
+  return esc(text)
+    .replace(/`([^`]+)`/g, '<code>$1</code>')
+    .replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
+    .replace(/\*([^*\n]+)\*/g, '<em>$1</em>')
+    .replace(/\[([^\]]+)\]\((https?:\/\/[^)\s]+)\)/g, '<a href="$2" target="_blank" rel="noopener noreferrer">$1</a>');
+}
+export function mdLite(md) {
+  const out = [];
+  let list = false;
+  const closeList = () => { if (list) { out.push('</ul>'); list = false; } };
+  for (const block of String(md || '').split(/\n\s*\n/).map((b) => b.trim()).filter(Boolean)) {
+    const flat = block.split('\n').map((l) => l.trim()).join(' ');
+    const head = flat.match(/^#{1,6}\s+(.*)$/);
+    if (head) { closeList(); out.push(`<h4>${mdInline(head[1])}</h4>`); continue; }
+    if (/^[-*]\s+/.test(block)) {
+      if (!list) { out.push('<ul>'); list = true; }
+      for (const item of block.split(/\n(?=[-*]\s)/)) {
+        out.push(`<li>${mdInline(item.replace(/^[-*]\s+/, '').split('\n').map((l) => l.trim()).join(' '))}</li>`);
+      }
+      continue;
+    }
+    closeList();
+    out.push(`<p>${mdInline(flat)}</p>`);
+  }
+  closeList();
+  return out.join('');
+}
+
 const SETTINGS_DEFAULTS = { sound: true, soundReview: 'ding', soundDone: 'click', startScreen: 'dashboard', dashRange: 'week', theme: 'system', keepDrawer: false, notifyReview: false, compactCards: false, linkLines: true, keymap: {} };
 export function getSetting(k) {
   const v = localStorage.getItem('kb.set.' + k);
@@ -424,6 +453,7 @@ async function renderSection(sec) {
       + `<div class="set-col hidden" id="about-upd-fail"><span class="set-lab">${tr('Run it yourself')}<small>${tr('the board is not allowed to do this — the command is the same one it just tried')}</small></span>`
       + '<pre class="onb-code" id="about-upd-cmd"></pre></div>'
       + `<div class="set-row hidden" id="about-dev-row"><span class="set-lab">${tr('dev branch')}<small id="about-dev-sub">…</small></span><span class="about-fresh" id="about-dev"></span></div>`
+      + `<div class="set-col"><span class="set-lab">${tr("What's new")}<small id="about-news-sub">…</small></span><div class="about-news" id="about-news">…</div></div>`
       + `<div class="set-row"><span class="set-lab">${tr('Check for updates')}<small id="about-recheck-sub">${tr('re-read branch state from GitHub')}</small></span><button class="btn-ghost" id="about-recheck">${tr('Check')}</button></div>`
       + `<div class="set-row"><span class="set-lab">${tr('Reload the page')}<small>${tr('re-read the board code right now')}</small></span><button class="btn-ghost" id="about-reload">${tr('Reload now')}</button></div>`
       + `<div class="set-row"><span class="set-lab">${tr('Using the board at work')}<small>${tr('free for everyone, nothing switched off — if it earns you money, $12 a year per person keeps it maintained')}</small></span>`
@@ -475,8 +505,21 @@ async function renderSection(sec) {
         ? `${u.dev.sha}${u.dev.date ? ` ${tr('at')} ${fmtDbTime(u.dev.date.slice(0, 19).replace('T', ' '))}` : ''}${u.dev.message ? ` · ${u.dev.message}` : ''}`
         : tr('dev has no commits beyond main');
     };
+    const loadNews = async (upd, forced) => {
+      const box = $('about-news'); const sub = $('about-news-sub');
+      if (!box || !sub) return;
+      try {
+        const remote = upd?.update_available === true ? `?remote=1${forced ? '&refresh=1' : ''}` : '';
+        const n = await api('GET', `/api/whats-new${remote}`, null, { quiet: true });
+        box.innerHTML = n?.notes ? mdLite(n.notes) : `<p class="muted">${esc(tr('no notes for this version'))}</p>`;
+        const ver = n?.version ? `${tr('version')} ${n.version}${n.source === 'github' ? ` · ${tr('not installed yet')}` : ''}` : '';
+        const link = /^https:\/\//.test(n?.url || '')
+          ? ` · <a href="${esc(n.url)}" target="_blank" rel="noopener noreferrer">${esc(tr('release page'))}</a>` : '';
+        sub.innerHTML = esc(ver) + link;
+      } catch { box.textContent = '—'; sub.textContent = ''; }
+    };
     api('GET', '/api/about').catch(() => null).then((a) => { about = a; })
-      .then(() => api('GET', '/api/update-check')).then(renderUpd)
+      .then(() => api('GET', '/api/update-check')).then((u) => { renderUpd(u); return loadNews(u); })
       .catch(() => { const s = $('about-upd-sub'); if (s) s.textContent = '—'; });
     const showFailCmd = (cmd) => {
       const wrap = $('about-upd-fail');
@@ -531,7 +574,7 @@ async function renderSection(sec) {
     $('about-recheck').onclick = async () => {
       const btn = $('about-recheck');
       btn.disabled = true; $('about-upd-sub').textContent = tr('checking…');
-      try { renderUpd(await api('GET', '/api/update-check?refresh=1')); }
+      try { const u = await api('GET', '/api/update-check?refresh=1'); renderUpd(u); await loadNews(u, true); }
       catch { $('about-upd-sub').textContent = '—'; }
       btn.disabled = false;
     };

package/public/js/sidebar.js

@@ -374,7 +374,10 @@ export async function checkPath(path) {
     setState('wiz-path-state', `${tr('the folder is there')} · ${r.dirs.length} ${tr('subfolders')}`, 'ok');
     return true;
   } catch (e) {
-    setState('wiz-path-state', `${tr('no such folder on this computer')}: ${e.message || path}`, 'bad');
+    const said = { 404: tr('no such folder on this computer'),
+      400: tr('this path is not a folder'),
+      403: tr('the folder is there, but the board cannot read it — check its permissions') }[e.status];
+    setState('wiz-path-state', said || `${tr('could not check the folder')}: ${e.message || path}`, 'bad');
     return false;
   }
 }

package/public/style.css

@@ -995,6 +995,19 @@ body.dragging-board .col-add-ghost { display: none; }
 .theme-opt { border: none; background: var(--panel); color: var(--muted); font: inherit; font-size: 12.5px; padding: 6px 12px; cursor: pointer; }
 .theme-opt + .theme-opt { border-left: 1px solid var(--border); }
 .theme-opt.active { background: var(--accent); color: #fff; }
+.about-news {
+  max-height: 260px; overflow-y: auto; font-size: 12.5px; line-height: 1.5;
+  border: 1px solid var(--border-soft); border-radius: 8px; padding: 10px 12px; background: var(--panel);
+}
+.about-news h4 { font-size: 12.5px; font-weight: 600; margin: 12px 0 6px; color: var(--muted); }
+.about-news h4:first-child { margin-top: 0; }
+.about-news p { margin: 0 0 8px; }
+.about-news ul { margin: 0 0 8px; padding-left: 18px; }
+.about-news li { margin-bottom: 7px; }
+.about-news li:last-child, .about-news p:last-child { margin-bottom: 0; }
+.about-news code { font-size: 11.5px; background: var(--border-soft); border-radius: 4px; padding: 1px 4px; }
+.about-news a { color: var(--accent); }
+
 .bk-list { display: flex; flex-direction: column; gap: 0; margin-top: 6px; }
 .bk-row { display: flex; justify-content: space-between; gap: 12px; font-size: 12.5px; padding: 7px 0; border-top: 1px solid var(--border-soft); }
 .bk-row:first-child { border-top: none; }

package/skills/kanban/SKILL.md

@@ -15,10 +15,14 @@ Statuses: `backlog` → `todo` → `prep` → `doing` → `deploy` → `review`
 
 ```
 kb take <proj>                # take the next task from todo → prep; prints the description,
-                              # the issue number (for commit messages), the last note from the
-                              # human (if the task was sent back, act on it!) and the paths of
-                              # attached screenshots as "📎 <path>" — OPEN those with Read,
-                              # they are context for the task.
+                              # the checklist as "- [ ] item" / "- [x] item" lines (that IS the
+                              # spec — do every open item, and verify them one by one before
+                              # review), the issue as "issue: #N <link>" (#N goes into commit
+                              # messages; kb show prints the same line), EVERY note the
+                              # human left since your last report, dated — "> 👤 [2026-09-02 11:30]
+                              # …" (if the task was sent back, act on them!) and the paths of
+                              # attached screenshots as "📎 <path>" — OPEN those with Read, they
+                              # are context for the task.
                               # started writing code → kb mv <key> doing.
 kb review <key> "note"        # leave a note and move to review. NOT atomic: the note is stored
                               # EVEN IF the move is rejected (backlog and todo cannot go straight
@@ -27,7 +31,11 @@ kb review <key> "note"        # leave a note and move to review. NOT atomic: the
                               # never went through doing.
 kb p                          # projects: slug (PREFIX) b0 t2 pp0 d1 dp0 r1 ✓5 !1  (pp = prep)
 kb ls <proj> [-s st] [-a]     # tasks (without -a, backlog/done/cancelled are hidden)
-kb show <key>                 # details + issue + latest comments
+kb show <key>                 # details + checklist + issue + comments: the last five plus every
+                              # human note since your last report. Marks: 🤖 yours, 👤 the
+                              # human's, ⎇ a commit stat the board attached by itself (not the
+                              # human speaking). "… N more comments not printed" = the rest are
+                              # on the board — nothing is dropped silently.
 kb add <proj> "title" [-d "desc"] [-p high|med|low] [-s todo]   # goes to backlog by default!
 kb mv <key> todo|prep|doing|deploy|review|done|cancelled
 kb done <key> · kb cancel <key> · kb pri <key> high|med|low|none
@@ -40,9 +48,16 @@ kb lbl <key> +bug -ui         # labels: bug docs duplicate enhancement ui featur
                               #    label goes into the LABELS palette first, and into this file.
 kb desc <key> "description"   # set or overwrite a task description (used when grooming the backlog)
 kb note <key> "text"          # a standalone comment (rarely needed — kb review covers it)
-kb link <key> <key>           # link two tasks (the board draws a line) · kb unlink to unlink
+kb check <key> <n>            # tick checklist item n (from 1, in the order show/take print them)
+                              # · kb uncheck <key> <n> clears it. Answers "- [x] item (2 open)"
+kb link <key> <key> [child|parent]   # link two tasks (the board draws a line); `child` makes the
+                              # second task a sub-task of the first, `parent` its parent, no word
+                              # = plain related · kb unlink to unlink
 kb block <key> "why" · kb unblock <key>
-kb info <proj>                # path, deploy_skill, server, pm2, domain
+kb info <proj>                # path, deploy_skill, server, pm2, domain, the project's description
+                              # (the owner's context for work — read it) and "docs: CLAUDE.md,
+                              # README.md" — the documents to read before the task; "docs: no
+                              # CLAUDE.md — read README.md instead" is a signal, not an empty line
 kb svc <proj>                 # live status of the project's services (local pm2 or your own PANEL_URL)
 kb sync                       # state of the sync queue (or "sync is off" in local-only mode)
 ```
@@ -92,15 +107,18 @@ Claude takes a task as far as *review* and stops. Only the user moves anything t
 **When the prompt lists specific keys** (the 📋 button on the "To do" column produces them) those
 are SPECIFIC tasks, not a queue. Take each one with `kb show <key>` (NOT `kb take`, which pulls
 ONE next task from the project's `todo`) and **move it to prep right away: `kb mv <key> prep`** —
-`kb show` does not change the status. If `kb show` printed `> 👤 Send back: …`, the task was
-returned: open the `📎` screenshots with Read and act on that note FIRST. Then follow steps 2–6
+`kb show` does not change the status. If `kb show` printed `> 👤 [date] Send back: …`, the task was
+returned — the date tells a fresh send-back from an old one you already answered: open the `📎` screenshots with Read and act on that note FIRST. Then follow steps 2–6
 for each. Use `kb take X` only when asked to "work through project X" without specific keys.
 
 1. `kb take X` — take a task (lands in prep; description and issue are already in the output).
-   "empty" → report it and stop. `> 👤 …` is a note from a send-back, act on it first.
+   "empty" → report it and stop. "empty (N blocked)" is NOT an empty column: every card in To do
+   is blocked — list them (`kb ls X -s todo`) and report that, not "nothing to do". `> 👤 …` lines are what the human wrote since your last report
+   (a send-back and its follow-ups) — act on all of them first.
    `📎 <path>` — open the screenshot with Read.
 2. **HARD RULE — starting a task (never skip, even for a one-line change).** `kb info X` → go to
-   `path`. Before any code you MUST read: (a) the project's `CLAUDE.md` if it has one — **and if
+   `path`; its `description:` and `docs:` lines say what the owner wants you to know and which
+   documents the project has. Before any code you MUST read: (a) the project's `CLAUDE.md` if it has one — **and if
    it does not, find where the project keeps its architecture or research document (`README.md`,
    `EXPERIMENTS.md`, `docs/`) and read that; apply the "doc in the same commit" rule to it**;
    (b) the deploy skill at `deploy_skill_path` from `kb info`, if one is set. The matching commit
@@ -126,7 +144,9 @@ for each. Use `kb take X` only when asked to "work through project X" without sp
    The generic `deploy` skill ships with the board (`skills/deploy/`) and works purely off
    `kb info` data. Production commands (ssh/rsync) will ask for confirmation — that is expected.
 5. `kb review <key> "<two plain sentences: 1) what the problem was 2) how you solved it>"` → take
-   the next one.
+   the next one. **If the task has a checklist, tick each item as you finish it (`kb check <key>
+   <n>`).** Before review every item is either ticked or named in the note as not done — the human
+   accepts the task by those boxes, and an unticked done item reads as undone.
 6. Stuck, or the decision is the human's → `kb block <key> "reason"` and move on.
 7. At the end, a one-line summary: how many in review, how many blocked.
 
@@ -161,7 +181,9 @@ One line of summary at the end.
 - **You found an unrelated problem along the way** → do not fix it silently. Create a task
   (`kb add <proj> "..." -d "..."`) and ask in chat: do it now, defer it, or is it for the human.
 - **Related tasks solved together** → take both at once (both in doing), fix them in one pass and
-  link them with `kb link`.
+  link them with `kb link`. `kb show`/`kb take` print a task's links as `↑ parent KEY title
+  (status)`, `↓ subtask …`, `↔ related …` — look at them before you start: a linked task in To do
+  is usually meant to go together with this one, and a parent explains why the task exists.
 - **A discussion or question task** (no code): study it in `prep`, put the full answer in
   `kb note <key> "..."`, then `kb mv <key> review`. You write no code and do not move it to done.
 - A "check whether the service is alive" task → `kb svc <proj>` (one line per service, no ssh).

package/src/config.js

@@ -38,3 +38,4 @@ export const allowedHosts = () => env('KB_ALLOWED_HOSTS').split(',').map((s) =>
 export const langOverride = () => env('KB_LANG');
 export const ghOwnerEnv = () => env('KB_GH_OWNER');
 export const ghRepoEnv = () => env('KB_GH_REPO');
+export const ghBinEnv = () => expandPath(env('KB_GH_BIN'));

package/src/routes/system.js

@@ -20,8 +20,8 @@ let selfPkgCache;
 function selfPkg() {
   if (selfPkgCache === undefined) {
     try {
-      const { name, version } = JSON.parse(readFileSync(join(ROOT_DIR, 'package.json'), 'utf8'));
-      selfPkgCache = name && version ? { name, version } : null;
+      const { name, version, repository } = JSON.parse(readFileSync(join(ROOT_DIR, 'package.json'), 'utf8'));
+      selfPkgCache = name && version ? { name, version, repository: repository?.url || repository || null } : null;
     } catch { selfPkgCache = null; }
   }
   return selfPkgCache;
@@ -82,6 +82,32 @@ export async function registryCheck() {
   } catch { return null; }
 }
 
+export async function ghApi(path) {
+  try {
+    const res = await fetch(`https://api.github.com/${path}`, {
+      headers: { 'User-Agent': 'local-kanban', Accept: 'application/vnd.github+json' },
+      signal: AbortSignal.timeout(8000),
+    });
+    if (res.ok) return await res.json();
+  } catch {  }
+  try { return JSON.parse(await ghCli(['api', path], { timeout: 10000 })); }
+  catch { return null; }
+}
+
+export function changelogSection(text, version) {
+  const head = new RegExp(`^##\\s*\\[?${String(version).replace(/\./g, '\\.')}\\]?`, 'm');
+  const m = head.exec(String(text || ''));
+  if (!m) return null;
+  const rest = text.slice(m.index + m[0].length);
+  const end = rest.search(/^## /m);
+  return (end === -1 ? rest : rest.slice(0, end)).trim() || null;
+}
+
+export function repoSlug(url) {
+  const m = String(url || '').match(/github\.com[:/]([\w.-]+)\/([\w.-]+?)(?:\.git)?(?:#.*)?$/);
+  return m ? `${m[1]}/${m[2]}` : null;
+}
+
 const UPLOAD_FLOOR = 64 * 1024 * 1024;
 function uploadLimit() {
   try { return Math.max(UPLOAD_FLOOR, statSync(join(DATA_DIR, 'kanban.db')).size * 4); } catch { return UPLOAD_FLOOR; }
@@ -255,17 +281,6 @@ export default async function systemRoutes(app) {
     const git = (args) => new Promise((resolve) => {
       execFile('git', args, { cwd: ROOT, timeout: 8000 }, (err, out) => resolve(err ? null : out.trim()));
     });
-    const ghApi = async (path) => {
-      try {
-        const res = await fetch(`https://api.github.com/${path}`, {
-          headers: { 'User-Agent': 'local-kanban', Accept: 'application/vnd.github+json' },
-          signal: AbortSignal.timeout(8000),
-        });
-        if (res.ok) return await res.json();
-      } catch {  }
-      try { return JSON.parse(await ghCli(['api', path], { timeout: 10000 })); }
-      catch { return null; }
-    };
     let data = { update_available: null, local: null, remote: null, branch: null, tag: null, dev: null };
     try {
       const [local, branch, origin, tag] = await Promise.all([
@@ -300,6 +315,30 @@ export default async function systemRoutes(app) {
     return data;
   });
 
+  const NEWS_OK_MS = 3600000;
+  const NEWS_FAIL_MS = 60000;
+  let newsCache = { at: 0, ttl: 0, data: null };
+  app.get('/api/whats-new', async (req) => {
+    const version = selfPkg()?.version || null;
+    const own = () => {
+      let text = null;
+      try { text = readFileSync(join(ROOT_DIR, 'CHANGELOG.md'), 'utf8'); } catch {  }
+      return { version, notes: (text && version) ? changelogSection(text, version) : null, source: 'changelog', url: null };
+    };
+    if (!req.query?.remote) return own();
+    if (!req.query?.refresh && newsCache.data && Date.now() - newsCache.at < newsCache.ttl) return newsCache.data;
+    const repo = repoSlug(selfPkg()?.repository);
+    const rel = repo ? await ghApi(`repos/${repo}/releases/latest`) : null;
+    const tag = String(rel?.tag_name || '').replace(/^v/, '');
+    const body = String(rel?.body || '').trim();
+    const got = Boolean(tag && body);
+    const data = got
+      ? { version: tag, notes: body, source: 'github', url: rel.html_url || null }
+      : own();
+    newsCache = { at: Date.now(), ttl: got ? NEWS_OK_MS : NEWS_FAIL_MS, data };
+    return data;
+  });
+
   let updateRunning = null;
   app.post('/api/update', async (req, reply) => {
     if (updateRunning) return reply.code(409).send({ error: 'an update is already running' });

package/src/sync/github.js

@@ -1,11 +1,13 @@
 import { execFile } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { db, ghOwner, ghRepo, uiLang } from '../db.js';
+import { ghBinEnv } from '../config.js';
 const GH_CANDIDATES = [
   '/opt/homebrew/bin/gh', '/usr/local/bin/gh', '/usr/bin/gh',
   '/home/linuxbrew/.linuxbrew/bin/gh', `${process.env.HOME}/.local/bin/gh`,
 ];
-const GH = GH_CANDIDATES.find((p) => existsSync(p)) || 'gh';
+const GH_FOUND = GH_CANDIDATES.find((p) => existsSync(p)) || 'gh';
+const ghBin = () => ghBinEnv() || GH_FOUND;
 
 const PERMANENT = [
   /validation failed/i,
@@ -19,7 +21,7 @@ export function isPermanent(stderr) {
 
 export function gh(args, { timeout = 60000 } = {}) {
   return new Promise((resolve, reject) => {
-    execFile(GH, args, { timeout, maxBuffer: 4 * 1024 * 1024 }, (err, stdout, stderr) => {
+    execFile(ghBin(), args, { timeout, maxBuffer: 4 * 1024 * 1024 }, (err, stdout, stderr) => {
       if (err) {
         const e = new Error((stderr || err.message || '').trim().slice(0, 500));
         e.permanent = isPermanent(String(stderr));