local-kanban 1.6.3

package/README.ru.md

@@ -0,0 +1,144 @@
+# local-kanban
+
+[![tests](https://github.com/lamaohub/local-kanban/actions/workflows/test.yml/badge.svg)](https://github.com/lamaohub/local-kanban/actions/workflows/test.yml)
+
+Локальная канбан-доска для работы **в паре с Claude Code**: человек планирует и принимает задачи, Claude берёт их из очереди, делает и отчитывается — через токен-экономный CLI `kb`. Опционально зеркалит всё в GitHub (issues + Projects v2).
+
+English version — [README.md](README.md).
+
+![Доска](docs/screenshot-board.png)
+
+![Дашборд](docs/screenshot-dashboard.png)
+
+## Зачем
+
+- **Очередь для Claude, а не просто доска.** Статусы повторяют реальный цикл: `бэклог → сделать → подготовка → делаю → деплою → проверяю → готово`. Claude берёт следующую задачу через `kb take`, работает и останавливается на «Проверяю» — принимает всегда человек.
+- **Локально прежде всего.** Всё живёт в одном SQLite-файле на твоей машине. GitHub-синк опционален и выключен, пока не настроишь.
+- **Честные метрики.** Время считается только пока Claude реально работает; дашборд показывает streak, цикл задачи и что ждёт тебя.
+
+## Модель безопасности — прочитай сначала
+
+Сервер слушает **только 127.0.0.1**, авторизации **нет**. Доска строго локальная: граница доверия — твоя машина. **Никогда не выставляй порт наружу** (никаких reverse proxy, `0.0.0.0`, проброса портов). Сторонние интеграции запускаются на той же машине и ходят на `127.0.0.1` (см. [docs/API.md](docs/API.md)).
+
+## Требования
+
+- **Node.js ≥ 22** (macOS или Linux) — у большинства стоит 24 LTS или новее
+- Опционально, только для GitHub-синка: [`gh` CLI](https://cli.github.com/) с правом `project`:
+  `gh auth login && gh auth refresh -s project`
+
+## Установка
+
+```bash
+npm install -g local-kanban
+local-kanban            # мастер настройки
+local-kanban start      # доска на http://localhost:3100
+```
+
+Мастер спросит порт, папку данных, нужен ли GitHub-синк и ставить ли в `~/.claude/skills` два скилла для Claude Code — скилл самой доски и деплой-скилл. У каждого вопроса есть ответ по умолчанию, поэтому Enter-Enter-Enter достаточно. Он же создаст `ecosystem.config.cjs` для автозапуска через [pm2](https://pm2.keymetrics.io/).
+
+У `local-kanban start` есть `--port <N>` и `--data <путь>`. Данные по умолчанию лежат в `~/.local-kanban`, вне каталога пакета, поэтому обновление пакета никогда не трогает доску.
+
+Из исходников:
+
+```bash
+git clone <адрес-репозитория> local-kanban && cd local-kanban
+npm install
+npx local-kanban     # мастер настройки (необязательно)
+npm start            # доска на http://localhost:3100
+```
+
+Команда `kb` глобально: `npm link` (или `npm install -g .`).
+
+Первый запуск покажет пустой дашборд с предложением создать **демо-проект** — один клик создаёт, один удаляет.
+
+### Настройку может довести сам Claude
+
+На последнем шаге мастера первого запуска показывается готовый промпт (на языке доски). Вставь его
+в Claude Code — он проверит, что работает `kb`, спросит, нужно ли зеркало в GitHub, заведёт первые
+проекты с их путями и деплоем и покажет результат. Тот же промпт лежит в **Настройки → О доске**,
+чтобы к нему можно было вернуться.
+
+### Скиллы Claude Code
+
+В `skills/` лежат два скилла:
+
+- `skills/kanban` — учит Claude рабочему циклу задач (`kb take` → работа → `kb review`);
+- `skills/deploy` — универсальный деплой от данных реестра проектов (`kb info`).
+
+Установка — симлинк или копия:
+
+```bash
+ln -s "$(pwd)/skills/kanban" ~/.claude/skills/kanban
+ln -s "$(pwd)/skills/deploy" ~/.claude/skills/deploy
+```
+
+## GitHub-синк (опционально)
+
+Укажи owner и репозиторий для issues в **Настройки → Синхронизация** (или env `KB_GH_OWNER` / `KB_GH_REPO`). Без них доска работает в local-only режиме: без очереди и предупреждений. С ними каждая задача становится issue, а каждый проект получает GitHub Project `kb: <slug>` с теми же колонками. Синк односторонний (доска → GitHub), фоновый.
+
+## Обновление
+
+Установка из npm:
+
+```bash
+npm install -g local-kanban@latest
+local-kanban skills          # обновить скиллы Claude Code — они копия, а не ссылка
+```
+
+Клон репозитория:
+
+```bash
+npm run update   # git pull + npm install + pm2 restart (если применимо)
+```
+
+Обновления не трогают данные: `data/` в .gitignore, миграции схемы прогоняются на старте автоматически — **со снапшотом до миграции** в `data/backups/pre-migrate/`.
+
+**Откат:** останови сервер, восстанови свежий файл из `data/backups/` (суточные) или `data/backups/pre-migrate/` поверх `data/kanban.db`, затем `git checkout <предыдущий тег>` и запусти снова.
+
+Релизы живут в `main` (стабильное, с тегами); ежедневная разработка — в `dev`.
+
+## Переменные окружения
+
+| Переменная | Дефолт | Смысл |
+|---|---|---|
+| `PORT` | `3100` | HTTP-порт (привязан к 127.0.0.1) |
+| `KB_DATA_DIR` | `./data` | папка данных (SQLite, вложения, бэкапы) |
+| `KB_LOCAL_ROOT` | `~/claude-projects` | корень локальных проектов-папок |
+| `KB_URL` | `http://127.0.0.1:3100` | адрес доски для CLI `kb` |
+| `KB_GH_OWNER` / `KB_GH_REPO` | — | цель GitHub-синка; пусто = синк выключен (можно задать и в Настройках) |
+| `KB_PANEL_URL` | — | свой HTTP-источник статусов сервисов; пусто = локальный `pm2 jlist` |
+| `KB_PANEL_INFO` | — | опциональный info.json внешней панели для синка категорий |
+| `KB_SSE_MAX` | `20` | потолок одновременных SSE-соединений |
+| `KB_SKILLS_EXTRA` | — | дополнительные корни скиллов через `:` |
+
+Старые имена `PANEL_URL` и `PANEL_INFO` (без префикса) продолжают работать как запасные.
+
+## Метрики и метка `noclaude`
+
+Задачи, сделанные **руками** (без Claude), помечаются меткой `noclaude` — они считаются на дашборде отдельно и не подмешиваются в метрики Claude (время работы, цикл, доведено %), которые иначе исказились бы нулевым временем. Метка необязательна, можно ставить позже. Ручным задачам разрешён прямой переход в «Проверяю»/«Готово».
+
+## Расширение
+
+Полный HTTP API и SSE-поток событий — официальная точка расширения: боты, статистика и интеграции пишутся отдельными программами, без плагинов внутри страницы. См. [docs/API.md](docs/API.md).
+
+## Разработка
+
+```bash
+node --test   # БД изолируется через KB_DATA_DIR
+```
+
+Дев-окружение, флоу веток и правило миграций — в [CONTRIBUTING.md](CONTRIBUTING.md). Архитектура — в [ARCHITECTURE.md](ARCHITECTURE.md), что менялось между версиями — в [CHANGELOG.md](CHANGELOG.md).
+
+## Язык интерфейса
+
+Исходный язык интерфейса — английский, русский приходит переводом. Доска следует языку системы и переключается в **Настройки → Основные**; строка без перевода остаётся английской, а не утекает в чужую локаль.
+
+## Использование в работе
+
+Доска под лицензией MIT и бесплатна для всех: ничего не отключено и нечего активировать. Если она
+зарабатывает тебе деньги — в компании или на платных заказах — $12 в год за человека помогают её
+поддерживать. Это просьба, а не правило: [docs/COMMERCIAL.md](docs/COMMERCIAL.md).
+
+## Лицензия
+
+[MIT](LICENSE).

package/bin/kb

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+// kb — the token-efficient CLI for the kanban board (localhost:3100).
+// Tasks are addressed by key (TIC-3) or by global id. One line of output per action.
+
+import { parsePm2Services } from '../src/pm2-services.js';
+
+const BASE = process.env.KB_URL || 'http://127.0.0.1:3100';
+const PRI = { 0: '', 1: 'p1', 2: 'p2', 3: 'p3' };
+const PRI_BY_NAME = { none: 0, low: 1, med: 2, medium: 2, high: 3, p0: 0, p1: 1, p2: 2, p3: 3 };
+const ST_ALIAS = {
+  b: 'backlog', backlog: 'backlog', t: 'todo', todo: 'todo',
+  pp: 'prep', prep: 'prep', d: 'doing', doing: 'doing',
+  dp: 'deploy', deploy: 'deploy', r: 'review', review: 'review', dn: 'done', done: 'done',
+  c: 'cancelled', cancelled: 'cancelled', cancel: 'cancelled',
+};
+
+// Exit codes are a contract for automation (scripts gate their moves on them):
+// 0 — success, 1 — the board is not responding, 2 — the request was rejected (4xx or an
+// unknown command), 3 — kb itself broke, 4 — the board answered, but with a failure of its
+// own (5xx) or with something that is not JSON. Previously an exception exited with 1 as well,
+// so "the board is down" was indistinguishable from "kb is broken".
+// Code 4 exists because 2 was answering two different questions at once. A live board that
+// answers with an honest 500 (a broken row in the database) used to exit with the SAME code as
+// a lawful refusal of a transition — there was no way to tell "the board falls over on my
+// request" from "you are not allowed to do that". Worse, a 200 whose body is not JSON made
+// `kb mv` print "undefined undefined" and exit 0: it reported a move that never happened, and
+// that is exactly what someone whose KB_URL points at a different port would see (several
+// ports are live on this machine).
+const EXIT = { DOWN: 1, REJECTED: 2, INTERNAL: 3, BOARD_ERROR: 4 };
+
+function die(msg, code = EXIT.REJECTED) { process.stderr.write(msg + '\n'); process.exit(code); }
+
+async function api(method, path, body) {
+  let res;
+  try {
+    res = await fetch(BASE + path, {
+      method,
+      headers: body ? { 'Content-Type': 'application/json' } : undefined,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+  } catch {
+    die('kb: board is not responding — pm2 restart kanban', EXIT.DOWN);
+  }
+  if (res.status === 204) return null;
+  const text = await res.text();
+  let data = null;
+  let parsed = false;
+  try { data = JSON.parse(text); parsed = true; } catch { /* not JSON — see below */ }
+  if (!res.ok) {
+    const detail = parsed ? (data?.error || res.status) : `${res.status} ${text.slice(0, 200)}`;
+    // 5xx is the board failing on us, not us asking for something forbidden — its own code.
+    die(`kb: ${detail}`, res.status >= 500 ? EXIT.BOARD_ERROR : EXIT.REJECTED);
+  }
+  if (!parsed) {
+    die(`kb: the board answered ${res.status} with something that is not JSON — is KB_URL (${BASE}) the board?`, EXIT.BOARD_ERROR);
+  }
+  return data;
+}
+
+function taskLine(t) {
+  const flags = [t.blocked ? '!' : '', PRI[t.priority] || ''].filter(Boolean).join(' ');
+  const labels = (t.labels || []).length ? ` [${t.labels.join(',')}]` : '';
+  return `${t.key} ${t.status}${flags ? ' ' + flags : ''} ${t.title}${labels}`;
+}
+
+const [cmd, ...args] = process.argv.slice(2);
+
+const commands = {
+  async p() {
+    const ps = await api('GET', '/api/projects');
+    if (!ps.length) return console.log('no projects');
+    for (const p of ps) {
+      console.log(`${p.slug} (${p.prefix}) b${p.c_backlog || 0} t${p.c_todo || 0} pp${p.c_prep || 0} d${p.c_doing || 0} dp${p.c_deploy || 0} r${p.c_review || 0} ✓${p.c_done || 0}${p.c_blocked ? ` !${p.c_blocked}` : ''}`);
+    }
+  },
+
+  async ls() {
+    const [proj] = args.filter((a) => !a.startsWith('-'));
+    if (!proj) die('kb ls <project> [-s status] [-a]');
+    const si = args.indexOf('-s');
+    const q = new URLSearchParams({ project: proj });
+    if (si >= 0) q.set('status', ST_ALIAS[args[si + 1]] || args[si + 1]);
+    if (args.includes('-a')) q.set('all', '1');
+    const ts = await api('GET', `/api/tasks?${q}`);
+    if (!ts.length) return console.log('empty');
+    for (const t of ts) console.log(taskLine(t));
+  },
+
+  async next() {
+    const [proj] = args;
+    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');
+  },
+
+  // 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.
+  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');
+    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}`);
+  },
+
+  // leave a note and move to review in one command
+  async review() {
+    const [id, note] = args;
+    if (!id || !note) die('kb review <key> "note"');
+    await api('POST', `/api/tasks/${id}/comments`, { body: note, author: 'claude' });
+    const t = await api('PATCH', `/api/tasks/${id}`, { status: 'review' });
+    console.log(`${t.key} review 📝`);
+  },
+
+  async show() {
+    const [id] = args;
+    if (!id) die('kb show <key>');
+    const t = await api('GET', `/api/tasks/${id}`);
+    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}`);
+    }
+  },
+
+  async add() {
+    const flagVals = new Set();
+    ['-d', '-p', '-s'].forEach((f) => { const i = args.indexOf(f); if (i >= 0) flagVals.add(i + 1); });
+    const pos = args.filter((a, i) => !a.startsWith('-') && !flagVals.has(i));
+    const [proj, title] = pos;
+    if (!proj || !title) die('kb add <project> "title" [-d "description"] [-p high|med|low] [-s todo]');
+    const di = args.indexOf('-d');
+    const pi = args.indexOf('-p');
+    const si = args.indexOf('-s');
+    const body = { project: proj, title };
+    if (di >= 0) body.description = args[di + 1] || '';
+    if (pi >= 0) {
+      const pr = PRI_BY_NAME[args[pi + 1]];
+      if (pr === undefined) die('kb: priority high|med|low|none');
+      body.priority = pr;
+    }
+    if (si >= 0) {
+      body.status = ST_ALIAS[args[si + 1]];
+      if (!body.status) die('kb: status backlog|todo|prep|doing|deploy|review|done');
+    }
+    const t = await api('POST', '/api/tasks', body);
+    console.log(`${t.key} ${t.status} ${t.project}`);
+  },
+
+  async mv() {
+    const [id, st] = args;
+    const status = ST_ALIAS[st];
+    if (!id || !status) die('kb mv <key> backlog|todo|prep|doing|deploy|review|done|cancelled');
+    const t = await api('PATCH', `/api/tasks/${id}`, { status });
+    console.log(`${t.key} ${t.status}`);
+  },
+
+  async done() {
+    const [id] = args;
+    if (!id) die('kb done <key>');
+    const t = await api('PATCH', `/api/tasks/${id}`, { status: 'done' });
+    console.log(`${t.key} done`);
+  },
+
+  async cancel() {
+    const [id] = args;
+    if (!id) die('kb cancel <key>');
+    const t = await api('PATCH', `/api/tasks/${id}`, { status: 'cancelled' });
+    console.log(`${t.key} cancelled`);
+  },
+
+  async pri() {
+    const [id, p] = args;
+    const pr = PRI_BY_NAME[p];
+    if (!id || pr === undefined) die('kb pri <key> high|med|low|none');
+    const t = await api('PATCH', `/api/tasks/${id}`, { priority: pr });
+    console.log(`${t.key} ${PRI[t.priority] || 'p0'}`);
+  },
+
+  async lbl() {
+    const [id, ...ops] = args;
+    if (!id || !ops.length) die('kb lbl <key> +bug -ui  (+ to add, - to remove)');
+    const t = await api('GET', `/api/tasks/${id}`);
+    const labels = new Set(t.labels);
+    for (const op of ops) {
+      if (op.startsWith('+')) labels.add(op.slice(1));
+      else if (op.startsWith('-')) labels.delete(op.slice(1));
+    }
+    const fresh = await api('PATCH', `/api/tasks/${id}`, { labels: [...labels] });
+    console.log(`${fresh.key} [${fresh.labels.join(',')}]`);
+  },
+
+  async desc() {
+    const [id, text] = args;
+    if (!id || text === undefined) die('kb desc <key> "description"  (set or overwrite the description)');
+    const t = await api('PATCH', `/api/tasks/${id}`, { description: text });
+    console.log(`${t.key} 📝 description updated`);
+  },
+
+  async note() {
+    const [id, body] = args;
+    if (!id || !body) die('kb note <key> "text"');
+    await api('POST', `/api/tasks/${id}/comments`, { body, author: 'claude' });
+    const t = await api('GET', `/api/tasks/${id}`);
+    console.log(`${t.key} 📝`);
+  },
+
+  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(', ') || '—'}`);
+  },
+
+  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(', ') || '—'}`);
+  },
+
+  async block() {
+    const [id, reason] = args;
+    if (!id) die('kb block <key> ["reason"]');
+    const t = await api('PATCH', `/api/tasks/${id}`, { blocked: true, blocked_reason: reason || '' });
+    console.log(`${t.key} blocked${t.blocked_reason ? ': ' + t.blocked_reason : ''}`);
+  },
+
+  async unblock() {
+    const [id] = args;
+    if (!id) die('kb unblock <key>');
+    const t = await api('PATCH', `/api/tasks/${id}`, { blocked: false });
+    console.log(`${t.key} unblocked`);
+  },
+
+  async rm() {
+    const [id] = args;
+    if (!id) die('kb rm <key>');
+    await api('DELETE', `/api/tasks/${id}`);
+    console.log(`${id} deleted`);
+  },
+
+  async info() {
+    const [proj] = args;
+    if (!proj) die('kb info <project>');
+    const p = await api('GET', `/api/projects/${proj}`);
+    const out = [`${p.slug} (${p.prefix}): ${p.name}`];
+    if (p.path) out.push(`path: ${p.path}`);
+    if (p.deploy_skill) out.push(`deploy_skill: ${p.deploy_skill}${p.deploy_skill_path ? ` (${p.deploy_skill_path})` : ''}`);
+    if (p.server) out.push(`server: ${p.server}${p.server_path ? ':' + p.server_path : ''}`);
+    const services = parsePm2Services(p.pm2_services);
+    if (services.length) out.push(`pm2: ${services.join(', ')}`);
+    if (p.domain) out.push(`domain: ${p.domain}`);
+    console.log(out.join('\n'));
+  },
+
+  async svc() {
+    const [proj] = args;
+    if (!proj) die('kb svc <project>');
+    const list = await api('GET', `/api/projects/${proj}/status`);
+    for (const s of list) {
+      if (s.status === 'not found') { console.log(`${s.name}: not found in pm2`); continue; }
+      console.log(`${s.name}: ${s.status} | up ${s.uptime_h}h | rst ${s.restarts} | ${s.mem_mb}MB | cpu ${s.cpu}%`);
+    }
+  },
+
+  async sync() {
+    const s = await api('GET', '/api/sync');
+    if (s.configured === false) { console.log('sync is off (local-only) — set owner/repo in the board settings or via KB_GH_OWNER/KB_GH_REPO'); return; }
+    let line = `queue:${s.pending}`;
+    if (s.failed.length) line += ` failed:${s.failed.length} (${s.failed[0].op}: ${(s.failed[0].last_error || '').slice(0, 80)})`;
+    if (s.gh === false) line += ' [gh unavailable: gh auth login && gh auth refresh -s project]';
+    console.log(line);
+  },
+
+  async retry() {
+    await api('POST', '/api/sync/retry');
+    console.log('ok');
+  },
+};
+
+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');
+}
+commands[cmd]().catch((e) => {
+  // die() inside a command already exited the process — only real exceptions reach here.
+  if (process.env.KB_DEBUG) process.stderr.write((e && e.stack) || String(e));
+  die(`kb: internal error — ${(e && e.message) || e} (stack trace: KB_DEBUG=1)`, EXIT.INTERNAL);
+});

package/bin/local-kanban

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+// The install and setup wizard. `npx local-kanban` is the only command a newcomer needs to
+// know: Enter-Enter-Enter and the board is running on http://localhost:3100.
+// Principles:
+//  - zero dependencies (the project has three in total; pulling in a prompts library for a
+//    wizard is not worth it);
+//  - EVERY question has a default, so the wizard can be walked through blind;
+//  - without a TTY (a pipe, CI, `npx … < /dev/null`) no questions are asked at all and the
+//    defaults are used — otherwise the install would silently hang waiting for an answer;
+//  - nothing happens quietly: every step prints what it wrote and where.
+import { createInterface } from 'node:readline/promises';
+import { execFileSync } from 'node:child_process';
+import { existsSync, lstatSync, rmSync, writeFileSync, mkdirSync, symlinkSync, cpSync, readFileSync } from 'node:fs';
+import { join, dirname, resolve, sep } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { homedir } from 'node:os';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+// The binary has subcommands. Without one it runs the wizard; `start` runs the board.
+// `npm start` is unavailable from an installed package — package.json scripts only exist in a
+// clone of the repository — yet the wizard used to recommend exactly that, which left nothing
+// to start the board with after `npx local-kanban`.
+const argv = process.argv.slice(2).filter((a) => a !== '--yes');
+const cmd = argv[0] && !argv[0].startsWith('-') ? argv[0] : '';
+const flag = (name) => {
+  const i = argv.indexOf(`--${name}`);
+  if (i >= 0 && argv[i + 1] && !argv[i + 1].startsWith('-')) return argv[i + 1];
+  const eq = argv.find((a) => a.startsWith(`--${name}=`));
+  return eq ? eq.slice(name.length + 3) : '';
+};
+
+// code inside node_modules means an npm/npx install: no package.json scripts and no git there,
+// so the advice at the end of the wizard has to be different
+const packaged = ROOT.split(sep).includes('node_modules');
+
+const interactive = process.stdin.isTTY && process.stdout.isTTY && !process.argv.includes('--yes') && !cmd;
+const rl = interactive ? createInterface({ input: process.stdin, output: process.stdout }) : null;
+
+const say = (s = '') => process.stdout.write(s + '\n');
+const done = (s) => say(`  ✓ ${s}`);
+const skip = (s) => say(`  · ${s}`);
+
+async function ask(question, def) {
+  if (!interactive) return def;
+  const a = (await rl.question(`${question} [${def}]: `)).trim();
+  return a || def;
+}
+async function confirm(question, def = true) {
+  if (!interactive) return def;
+  const a = (await rl.question(`${question} [${def ? 'Y/n' : 'y/N'}]: `)).trim().toLowerCase();
+  if (!a) return def;
+  return ['y', 'yes'].includes(a);
+}
+
+function ghReady() {
+  // the sync needs more than authentication: without the project scope create_issue succeeds
+  // but the card never lands on the Projects v2 board, and the user hunts for the cause
+  try {
+    const out = execFileSync('gh', ['auth', 'status'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    return { ok: true, project: /\bproject\b/.test(out) };
+  } catch {
+    return { ok: false, project: false };
+  }
+}
+
+const usage = () => say(`
+  local-kanban            install and setup wizard
+  local-kanban start      run the board
+      --port <N>          port (defaults to 3100, or PORT)
+      --data <dir>        data directory (defaults to whatever the board resolves on its own)
+  local-kanban skills     refresh the Claude Code skills in ~/.claude/skills
+  local-kanban help       this help
+`);
+
+function installSkills({ force = false, quiet = false } = {}) {
+  const skillsDir = join(homedir(), '.claude', 'skills');
+  mkdirSync(skillsDir, { recursive: true });
+  for (const name of ['kanban', 'deploy']) {
+    const target = join(skillsDir, name);
+    const source = join(ROOT, 'skills', name);
+    const linked = existsSync(target) && lstatSync(target).isSymbolicLink();
+    if (existsSync(target) && !force) { if (!quiet) skip(`${target} already exists — leaving it alone`); continue; }
+    // A clone links, so edits to the skill apply immediately and there is nothing to refresh.
+    if (linked) { if (!quiet) skip(`${target} is a symlink — nothing to refresh`); continue; }
+    try {
+      // from a package this is a COPY. A symlink would point inside node_modules, and updating or
+      // removing the package would silently take the skill away from Claude.
+      if (packaged || force) {
+        rmSync(target, { recursive: true, force: true });
+        cpSync(source, target, { recursive: true });
+        if (!quiet) done(`${target} (copy)`);
+      } else { symlinkSync(source, target); if (!quiet) done(`${target} → skills/${name}`); }
+    } catch (e) { skip(`could not install the skill ${target}: ${e.message}`); }
+  }
+}
+
+if (cmd === 'skills') {
+  installSkills({ force: true });
+  say('\n  The skills in ~/.claude/skills now match this version of the package.');
+  process.exit(0);
+}
+
+if (cmd === 'start') {
+  if (flag('port')) process.env.PORT = flag('port');
+  if (flag('data')) process.env.KB_DATA_DIR = resolve(flag('data'));
+  // the server prints its address and backup path itself; the data directory is resolved by config.js
+  await import(pathToFileURL(join(ROOT, 'src', 'server.js')).href);
+  // the wizard follows below and must not run under `start`; the listening socket holds the process
+  await new Promise(() => {});
+}
+
+if (cmd === 'help' || argv.includes('--help') || argv.includes('-h')) { usage(); process.exit(0); }
+if (cmd && cmd !== 'setup') {
+  say(`\n  unknown command: ${cmd}`);
+  usage();
+  process.exit(2);
+}
+
+say('\n  local-kanban — install\n');
+
+/* ── 1. port and data directory ─────────────────────────────────────────── */
+// imported here rather than at the top: a static import would run BEFORE the `start` branch,
+// which sets KB_DATA_DIR from --data, and the server would receive a stale cached value
+const { DATA_DIR, expandPath } = await import(pathToFileURL(join(ROOT, 'src', 'config.js')).href);
+const port = await ask('Board port (listens on 127.0.0.1 only)', '3100');
+// the default comes from config.js, the single place that decides where data lives — otherwise
+// the wizard would offer a directory inside the package and the board would open a different one
+// A tilde or a relative path is expanded here, and the result is shown back: the shell only
+// expands `~` when it is unquoted, and nothing expands it inside a pm2 config file. Writing the
+// answer down verbatim used to create a real directory named `~` next to wherever the board was
+// started from, and the board then died with a raw stack from @fastify/static.
+const dataAnswer = await ask('Data directory (SQLite, attachments, backups)', DATA_DIR);
+const dataDir = expandPath(dataAnswer);
+if (dataDir !== dataAnswer) say(`  → ${dataDir}`);
+
+/* ── 2. GitHub sync ─────────────────────────────────────────────────────── */
+let ghOwner = '';
+let ghRepo = '';
+say('\n  GitHub sync is optional: without it the board is fully functional, just local-only.');
+if (await confirm('  Mirror tasks to GitHub?', false)) {
+  const gh = ghReady();
+  if (!gh.ok) {
+    skip('gh is not authenticated — skipping. Later: gh auth login && gh auth refresh -s project,');
+    skip('  then set owner/repo under Settings → Sync on the board');
+  } else {
+    if (!gh.project) skip('the token has no project scope — run: gh auth refresh -s project');
+    ghOwner = await ask('  GitHub owner', '');
+    ghRepo = await ask('  Repository for issues (owner/repo)', ghOwner ? `${ghOwner}/tasks` : '');
+  }
+}
+
+/* ── 3. pm2 config ──────────────────────────────────────────────────────── */
+// for an npm install the package directory belongs to the package manager, so a config written
+// there lives until the first update. Keep it next to the data, which does survive updates.
+const cfgDir = packaged ? dataDir : ROOT;
+const cfgPath = join(cfgDir, 'ecosystem.config.cjs');
+say('');
+if (existsSync(cfgPath)) {
+  skip(`${cfgPath} already exists — leaving it alone`);
+} else if (await confirm('Create ecosystem.config.cjs for autostart under pm2?', true)) {
+  mkdirSync(cfgDir, { recursive: true });
+  const env = [
+    `        PORT: '${port}',`,
+    "        NODE_ENV: 'production',",
+    `        KB_DATA_DIR: '${dataDir}',`,
+    ghOwner ? `        KB_GH_OWNER: '${ghOwner}',` : null,
+    ghRepo ? `        KB_GH_REPO: '${ghRepo}',` : null,
+  ].filter(Boolean).join('\n');
+  writeFileSync(cfgPath, `// Created by the local-kanban wizard. Git-ignored, so local paths never leave your machine.
+module.exports = {
+  apps: [
+    {
+      name: 'kanban',
+      script: 'src/server.js',
+      cwd: '${ROOT}',
+      env: {
+${env}
+      },
+      max_memory_restart: '200M',
+      merge_logs: true,
+    },
+  ],
+};
+`);
+  done(`wrote ${cfgPath}`);
+  say(`    start it:  pm2 start ${cfgPath} && pm2 save`);
+  say('    start on login:  pm2 startup  (prints a command you then have to run)');
+} else {
+  skip(`without pm2 — start it manually: ${packaged ? 'local-kanban start' : 'npm start'}`);
+}
+
+/* ── 4. Claude Code skills ──────────────────────────────────────────────── */
+say('');
+if (await confirm('Install the Claude Code skills (kanban, deploy) into ~/.claude/skills?', true)) {
+  installSkills();
+  if (packaged) say('    after an update, refresh them:  local-kanban skills');
+} else {
+  skip('skills not installed — later: ln -s "$(pwd)/skills/kanban" ~/.claude/skills/kanban');
+}
+
+/* ── 5. the kb command ──────────────────────────────────────────────────── */
+say('');
+say(packaged
+  ? '  The kb command (the one Claude calls) is already installed with the package.'
+  : '  The kb command (the one Claude calls): npm link  — or npm install -g .');
+if (port !== '3100') say(`  Non-default port, so kb needs the address: export KB_URL=http://127.0.0.1:${port}`);
+
+/* ── 6. first run ───────────────────────────────────────────────────────── */
+say('');
+say(`  Done. The board will be at http://localhost:${port}`);
+say('  The first run shows a wizard: language, sync, demo project.');
+  // the most useful thing at the end is not a list of commands but a ready prompt for Claude;
+  // worth mentioning before the user even opens the browser
+  say('  It ends with a ready prompt for Claude — it finishes the setup and asks what it needs.');
+say(`  Start it now:  ${packaged ? 'local-kanban start' : 'npm start'}\n`);
+rl?.close();