kandown 0.11.2 → 0.13.0

package/bin/kandown.js

@@ -19,7 +19,10 @@
  *  → resolveKandownBin — resolves the global kandown binary path for respawn
  *  → semverGt — compares two semver strings
  *  → checkForUpdate — non-blocking auto-updater with lock file and graceful fallback
- *  → cmdInit — installs `.kandown`
+ *  → getProjectRoot — returns the project root (parent of .kandown/)
+ *  → getTasksDir — returns the project-root tasks/ path
+ *  → migrateTasksToTopLevel — silently moves legacy .kandown/tasks/ → ./tasks/
+ *  → cmdInit — installs `.kandown` and top-level `tasks/`
  *  → cmdUpdate — refreshes installed kandown.html
  *  → injectServerRoot — injects the CLI server root into single-file HTML
  *  → createServeServer — creates the local zero-dependency HTTP server
@@ -57,6 +60,7 @@ import {
   statSync,
   unlinkSync,
   renameSync,
+  rmdirSync,
 } from 'node:fs';
 import { spawnSync, spawn, execSync } from 'node:child_process';
 
@@ -298,6 +302,7 @@ ${c.bold}Commands:${c.reset}
   ${c.cyan}settings${c.reset}    Open the settings TUI
   ${c.cyan}daemon${c.reset}      Manage the per-project web daemon (start|stop|status)
   ${c.cyan}update${c.reset}      Update kandown.html to the latest version
+  ${c.cyan}shell${c.reset}       Run shellable task commands (list/show/create/move/assign/commit)
   ${c.cyan}help${c.reset}        Show this help
 
 ${c.bold}Options:${c.reset}
@@ -311,6 +316,9 @@ ${c.bold}Examples:${c.reset}
   ${c.dim}$${c.reset} npx kandown init
   ${c.dim}$${c.reset} npx kandown init --path docs/kanban
   ${c.dim}$${c.reset} npx kandown init --no-agents
+  ${c.dim}$${c.reset} npx kandown shell list --json
+  ${c.dim}$${c.reset} npx kandown shell create "Refactor auth" -p P1
+  ${c.dim}$${c.reset} npx kandown shell commit -m "tasks: refactor auth"
 `);
 }
 
@@ -355,8 +363,8 @@ ${marker}
 **IMPORTANT:** Before touching any task files, you MUST read \`${kandownPath}/AGENT_KANDOWN.md\`.
 
 This project uses a file-based kanban:
-- **Tasks live in \`${kandownPath}/tasks/t-xxx.md\`** — each task file owns its status
-- **Columns live in \`${kandownPath}/kandown.json\`** under \`board.columns\`
+- **Tasks live in \`./tasks/t-xxx.md\`** at the project root — each task file owns its status
+- **Config lives in \`${kandownPath}/kandown.json\`** (columns, appearance, agent settings)
 - **Completion workflow:** set task frontmatter \`status: Done\` + write the completion report
 `;
 
@@ -376,8 +384,8 @@ function createAgentsFileIfMissing(cwd, kandownPath) {
 **IMPORTANT:** Before touching any task files, you MUST read \`AGENT_KANDOWN.md\`.
 
 This project uses a file-based kandown:
-- **Tasks live in \`${kandownPath}/tasks/t-xxx.md\`** — each task file owns its status
-- **Columns live in \`${kandownPath}/kandown.json\`** under \`board.columns\`
+- **Tasks live in \`./tasks/t-xxx.md\`** at the project root — each task file owns its status
+- **Config lives in \`${kandownPath}/kandown.json\`** (columns, appearance, agent settings)
 - **Completion workflow:** set task frontmatter \`status: Done\` + write the completion report
 `;
   writeFileSync(agentsPath, content, 'utf8');
@@ -396,9 +404,130 @@ function parseArgs(argv) {
   return args;
 }
 
+/**
+ * 📖 Returns the absolute path of the project root (parent of the kandown
+ * config dir). Tasks live at the project root in `./tasks/`, not inside
+ * `.kandown/tasks/`. Used by every code path that touches task files.
+ * @param {string} kandownDir absolute path to the kandown config dir
+ * @returns {string} absolute path to the project root
+ */
+function getProjectRoot(kandownDir) {
+  return dirname(kandownDir);
+}
+
+/**
+ * 📖 Returns the absolute path of the tasks directory at the project root.
+ * Mirrors the File System Access layout: `./tasks/` is a sibling of `.kandown/`.
+ * @param {string} kandownDir absolute path to the kandown config dir
+ * @returns {string} absolute path to `./tasks/`
+ */
+function getTasksDir(kandownDir) {
+  return join(getProjectRoot(kandownDir), 'tasks');
+}
+
+/**
+ * 📖 Silently migrates task files from the legacy `.kandown/tasks/` location
+ * to the new top-level `./tasks/` location. Idempotent: returns
+ * `{ moved, cleanedUp }` describing what was done (or nothing).
+ *
+ * Rules:
+ *  - If `./tasks/*.md` already exists, never move anything (avoid clobbering).
+ *  - If `.kandown/tasks/` doesn't exist or has no .md files, no-op.
+ *  - Move every `.md` file (including those in `archive/`) to `./tasks/`.
+ *  - Delete `.kandown/tasks/` only if it's now empty (preserves any non-md
+ *    files like `.scratch/` notes the user may have stashed there).
+ *  - Never throw — failures are logged and skipped so a single bad file
+ *    doesn't block the rest of the migration.
+ *
+ * @param {string} kandownDir absolute path to the kandown config dir
+ * @returns {{ moved: number, cleanedUp: boolean, skipped: boolean }}
+ */
+function migrateTasksToTopLevel(kandownDir) {
+  const projectRoot = getProjectRoot(kandownDir);
+  const oldDir = join(kandownDir, 'tasks');
+  const newDir = getTasksDir(kandownDir);
+  const result = { moved: 0, cleanedUp: false, skipped: false };
+
+  if (!existsSync(oldDir)) return result;
+  if (!existsSync(newDir)) mkdirSync(newDir, { recursive: true });
+
+  // 📖 If the new location already has any .md file, don't touch anything.
+  // The user is in a hybrid state and we should not clobber their work.
+  const existingNew = existsSync(newDir)
+    ? readdirSync(newDir).filter(n => n.endsWith('.md'))
+    : [];
+  if (existingNew.length > 0) {
+    result.skipped = true;
+    return result;
+  }
+
+  // 📖 If the old location has no .md files either, no migration needed.
+  const oldMdFiles = readdirSync(oldDir, { withFileTypes: true })
+    .filter(e => e.isFile() && e.name.endsWith('.md'));
+  if (oldMdFiles.length === 0) {
+    // Still try the archive subfolder.
+    return migrateArchive(kandownDir, result);
+  }
+
+  for (const entry of oldMdFiles) {
+    try {
+      renameSync(join(oldDir, entry.name), join(newDir, entry.name));
+      result.moved += 1;
+    } catch (e) {
+      warn(`migrate: could not move ${entry.name} (${e.code ?? e.message})`);
+    }
+  }
+
+  return migrateArchive(kandownDir, result);
+}
+
+/**
+ * 📖 Helper that moves the legacy `archive/` subfolder to the new location.
+ * Called from migrateTasksToTopLevel after the active files have been moved.
+ */
+function migrateArchive(kandownDir, result) {
+  const oldArchive = join(kandownDir, 'tasks', 'archive');
+  const newArchive = join(getTasksDir(kandownDir), 'archive');
+  if (!existsSync(oldArchive)) return cleanupLegacyTasksDir(kandownDir, result);
+
+  if (!existsSync(newArchive)) mkdirSync(newArchive, { recursive: true });
+  for (const entry of readdirSync(oldArchive, { withFileTypes: true })) {
+    if (entry.isFile() && entry.name.endsWith('.md')) {
+      try {
+        renameSync(join(oldArchive, entry.name), join(newArchive, entry.name));
+        result.moved += 1;
+      } catch (e) {
+        warn(`migrate: could not move archive/${entry.name} (${e.code ?? e.message})`);
+      }
+    }
+  }
+
+  return cleanupLegacyTasksDir(kandownDir, result);
+}
+
+/**
+ * 📖 Removes the legacy `.kandown/tasks/` directory only if it is empty.
+ * Preserves any leftover non-md files (e.g. `.scratch/` notes) so we never
+ * delete user data the migration didn't move.
+ */
+function cleanupLegacyTasksDir(kandownDir, result) {
+  const oldDir = join(kandownDir, 'tasks');
+  if (!existsSync(oldDir)) return result;
+  const remaining = readdirSync(oldDir);
+  if (remaining.length === 0) {
+    try {
+      rmdirSync(oldDir);
+      result.cleanedUp = true;
+    } catch { /* directory not empty or platform limitation — leave it */ }
+  }
+  return result;
+}
+
 /**
  * @returns {{ kandownDir: string, alreadyExisted: boolean }} — resolves the
  * kandown directory and auto-inits it if it doesn't exist (no prompt, silent init).
+ * Also performs a one-time silent migration of tasks from `.kandown/tasks/` to
+ * the project root `./tasks/` on first access of a legacy project.
  */
 function ensureKandownDir(rawArgs) {
   const args = parseArgs(rawArgs);
@@ -406,7 +535,18 @@ function ensureKandownDir(rawArgs) {
   const explicitPath = rawArgs.includes('--path') || rawArgs.includes('-p');
   const kandownDir = resolve(cwd, args.path);
 
-  if (existsSync(kandownDir)) return { kandownDir, alreadyExisted: true };
+  if (existsSync(kandownDir)) {
+    // 📖 Silent one-time migration: move any legacy `.kandown/tasks/*.md` to
+    // the project-root `./tasks/`. Idempotent — safe to call on every startup.
+    const migration = migrateTasksToTopLevel(kandownDir);
+    if (migration.moved > 0) {
+      success(`Migrated ${migration.moved} task${migration.moved === 1 ? '' : 's'} from .kandown/tasks/ to ./tasks/`);
+      if (migration.cleanedUp) info('Removed empty .kandown/tasks/ folder');
+    } else if (migration.skipped) {
+      info('Both .kandown/tasks/ and ./tasks/ have files — leaving both in place');
+    }
+    return { kandownDir, alreadyExisted: true };
+  }
 
   log('');
   info(`No .kandown/ found — auto-installing...`);
@@ -440,13 +580,16 @@ function doInit(args, cwd, kandownPath, kandownDir) {
     success('README.md');
   }
 
+  // 📖 Tasks live at the project root in `./tasks/`, not inside `.kandown/`.
+  // This keeps config separate from data and follows the user-facing convention.
   const tasksSrc = join(templatesDir, 'tasks');
-  const tasksDest = join(kandownDir, 'tasks');
+  const tasksDest = getTasksDir(kandownDir);
   if (!existsSync(tasksDest)) {
+    mkdirSync(tasksDest, { recursive: true });
     copyRecursive(tasksSrc, tasksDest);
-    success('tasks/ (with welcome example)');
+    success('./tasks/ (with welcome example)');
   } else {
-    info('tasks/ already exists (kept)');
+    info('./tasks/ already exists (kept)');
   }
 
   if (!existsSync(join(kandownDir, 'kandown.json'))) {
@@ -512,9 +655,13 @@ function cmdInit(rawArgs) {
   log('');
   log(`${c.green}${c.bold}Done.${c.reset}`);
   log('');
+  log(`  ${c.dim}Layout:${c.reset}`);
+  log(`  ${c.dim}└─${c.reset} ${c.bold}.kandown/${c.reset}     — config, web UI, agent docs`);
+  log(`  ${c.dim}└─${c.reset} ${c.bold}tasks/${c.reset}          — task files (source of truth)`);
+  log('');
   log(`  ${c.dim}Next steps:${c.reset}`);
   log(`  ${c.cyan}1.${c.reset} Open ${c.bold}${kandownPath}/kandown.html${c.reset} in Chrome/Edge/Brave`);
-  log(`  ${c.cyan}2.${c.reset} Select the ${c.bold}${kandownPath}/${c.reset} folder when prompted`);
+  log(`  ${c.cyan}2.${c.reset} Select the ${c.bold}project root${c.reset} (the parent of ${c.bold}${kandownPath}/${c.reset})`);
   log(`  ${c.cyan}3.${c.reset} Start creating tasks. Press ${c.cyan}⌘K${c.reset} for the command palette`);
   log('');
   log(`  ${c.dim}macOS:${c.reset}   open ${kandownPath}/kandown.html`);
@@ -544,6 +691,476 @@ function cmdUpdate(rawArgs) {
   success(`Updated ${args.path}/kandown.html`);
 }
 
+/* ═════════════ Shellable task commands ═════════════ */
+/**
+ * 📖 Self-contained minimal YAML frontmatter parser/writer for the CLI shell
+ * commands. The web app uses a richer schema (parseSimpleYaml) in the
+ * browser; the CLI keeps its own because it can't import the browser bundle
+ * and these commands only need to round-trip a known small set of scalar
+ * fields (status, priority, assignee, tags, ownerType, depends_on, etc.).
+ *
+ * Quirk: tags and depends_on are emitted as inline YAML arrays
+ * `[a, b, c]` because list-as-block-scalar is harder to round-trip cleanly
+ * and shell tools downstream (jq, awk, grep) parse the inline form
+ * trivially.
+ */
+
+function parseFrontmatter(content) {
+  const out = { frontmatter: {}, body: content || '' };
+  if (!content || !content.startsWith('---\n')) return out;
+  const end = content.indexOf('\n---\n', 4);
+  if (end === -1) {
+    out.body = content;
+    return out;
+  }
+  const yaml = content.slice(4, end);
+  out.body = content.slice(end + 5).replace(/^\n+/, '');
+  for (const line of yaml.split('\n')) {
+    if (!line.trim() || line.trim().startsWith('#')) continue;
+    const m = line.match(/^([a-zA-Z_][\w-]*)\s*:\s*(.*)$/);
+    if (!m) continue;
+    const key = m[1];
+    let val = (m[2] || '').trim();
+    if (val.startsWith('[') && val.endsWith(']')) {
+      val = val.slice(1, -1).split(',').map(s => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+    } else if (val === 'true' || val === 'false') {
+      val = val === 'true';
+    } else if (val === 'null' || val === '') {
+      val = null;
+    } else if (/^-?\d+(\.\d+)?$/.test(val)) {
+      val = Number(val);
+    } else {
+      val = val.replace(/^["']|["']$/g, '');
+    }
+    out.frontmatter[key] = val;
+  }
+  return out;
+}
+
+function serializeFrontmatter(fm, body) {
+  const lines = ['---'];
+  for (const [k, v] of Object.entries(fm || {})) {
+    if (v === null || v === undefined || v === '') continue;
+    if (Array.isArray(v)) {
+      if (v.length === 0) continue;
+      lines.push(`${k}: [${v.join(', ')}]`);
+    } else if (typeof v === 'string' && v.includes('\n')) {
+      lines.push(`${k}: |`);
+      lines.push(...v.split('\n').map(l => (l === '' ? '' : `  ${l}`)));
+    } else {
+      lines.push(`${k}: ${v}`);
+    }
+  }
+  lines.push('---', '', (body || '').replace(/^\n+/, '').replace(/\n+$/, '') + '\n');
+  return lines.join('\n');
+}
+
+function readKandownConfig(kandownDir) {
+  const configPath = join(kandownDir, 'kandown.json');
+  if (!existsSync(configPath)) return null;
+  try {
+    return JSON.parse(readFileSync(configPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function findTaskFile(kandownDir, id) {
+  if (!/^[a-zA-Z0-9_-]+$/.test(id)) return null;
+  const tasksDir = getTasksDir(kandownDir);
+  const inTasks = join(tasksDir, `${id}.md`);
+  if (existsSync(inTasks)) return inTasks;
+  const inArchive = join(tasksDir, 'archive', `${id}.md`);
+  if (existsSync(inArchive)) return inArchive;
+  return null;
+}
+
+function listAllTaskIds(kandownDir) {
+  const tasksDir = getTasksDir(kandownDir);
+  const ids = new Set();
+  if (existsSync(tasksDir)) {
+    for (const f of readdirSync(tasksDir).filter(f => f.endsWith('.md'))) {
+      ids.add(f.replace(/\.md$/, ''));
+    }
+    const archive = join(tasksDir, 'archive');
+    if (existsSync(archive)) {
+      for (const f of readdirSync(archive).filter(f => f.endsWith('.md'))) {
+        ids.add(f.replace(/\.md$/, ''));
+      }
+    }
+  }
+  return [...ids].sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
+}
+
+function nextTaskId(kandownDir) {
+  const ids = listAllTaskIds(kandownDir);
+  let maxN = 0;
+  for (const id of ids) {
+    const m = id.match(/^t(\d+)$/i);
+    if (m) {
+      const n = parseInt(m[1], 10);
+      if (Number.isFinite(n) && n > maxN) maxN = n;
+    }
+  }
+  return 't' + (maxN + 1);
+}
+
+function shellPad(str, len) {
+  const s = String(str);
+  if (s.length >= len) return s.slice(0, Math.max(0, len - 1)) + (s.length > len ? '…' : '');
+  return s + ' '.repeat(len - s.length);
+}
+
+function shellParseArgs(argv) {
+  // 📖 Minimal flag parser for the shell subcommands. Stops at the first
+  // positional arg so `kandown create "Some title with -dash"` works.
+  const out = { positional: [], flags: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') out.flags.json = true;
+    else if (a === '--archived') out.flags.archived = true;
+    else if (a === '-s' || a === '--status') out.flags.status = argv[++i];
+    else if (a === '-a' || a === '--assignee') out.flags.assignee = argv[++i];
+    else if (a === '-p' || a === '--priority') out.flags.priority = argv[++i];
+    else if (a === '-t' || a === '--tag') out.flags.tags = (out.flags.tags || []).concat([argv[++i]]);
+    else if (a === '-d' || a === '--depends-on') out.flags.dependsOn = (out.flags.dependsOn || []).concat([argv[++i]]);
+    else if (a === '-m' || a === '--message') out.flags.message = argv[++i];
+    else if (a === '--to') out.flags.to = argv[++i];
+    else if (a === '--id') out.flags.id = argv[++i];
+    else out.positional.push(a);
+  }
+  return out;
+}
+
+function shellResolveStatus(config, status) {
+  // 📖 Status can be a configured column name OR the reserved `archived`
+  // sentinel. Match is case-insensitive to keep shell usage forgiving.
+  if (!status) return null;
+  const lower = status.toLowerCase();
+  if (lower === 'archived') return 'archived';
+  const columns = (config && config.board && config.board.columns) || [];
+  for (const c of columns) {
+    if (c.toLowerCase() === lower) return c;
+  }
+  return null;
+}
+
+function shellList(rawArgs) {
+  const { kandownDir } = ensureKandownDir(rawArgs);
+  const args = shellParseArgs(rawArgs);
+  const config = readKandownConfig(kandownDir);
+  const statusFilter = args.flags.status ? shellResolveStatus(config, args.flags.status) : null;
+  if (args.flags.status && !statusFilter) {
+    err(`Unknown status: ${args.flags.status}`);
+    process.exit(1);
+  }
+  if (statusFilter && statusFilter !== 'archived' && config && !(config.board.columns || []).map(c => c.toLowerCase()).includes(statusFilter.toLowerCase())) {
+    err(`Status not in board columns: ${statusFilter}`);
+    process.exit(1);
+  }
+
+  const ids = listAllTaskIds(kandownDir);
+  const rows = [];
+  for (const id of ids) {
+    const path = findTaskFile(kandownDir, id);
+    if (!path) continue;
+    const parsed = parseFrontmatter(readFileSync(path, 'utf8'));
+    const fm = parsed.frontmatter;
+    const isArchived = fm.archived === true || fm.archived === 'true' || path.includes('/archive/');
+    if (args.flags.archived ? !isArchived : isArchived) continue;
+    if (statusFilter && statusFilter !== 'archived' && (fm.status || '').toLowerCase() !== statusFilter.toLowerCase()) continue;
+    if (args.flags.assignee && fm.assignee !== args.flags.assignee) continue;
+    if (args.flags.priority && (fm.priority || '').toLowerCase() !== args.flags.priority.toLowerCase()) continue;
+    if (args.flags.tags && args.flags.tags.length > 0) {
+      const taskTags = Array.isArray(fm.tags) ? fm.tags : [];
+      const wanted = new Set(args.flags.tags);
+      let ok = true;
+      for (const t of wanted) { if (!taskTags.includes(t)) { ok = false; break; } }
+      if (!ok) continue;
+    }
+    rows.push({ id, fm, body: parsed.body });
+  }
+
+  if (args.flags.json) {
+    process.stdout.write(JSON.stringify(rows.map(r => ({
+      id: r.id, ...r.fm, archived: r.fm.archived === true || r.fm.archived === 'true',
+    })), null, 2) + '\n');
+    return;
+  }
+
+  if (rows.length === 0) {
+    log(c.dim + '(no tasks)' + c.reset);
+    return;
+  }
+
+  const idW = Math.max(2, ...rows.map(r => r.id.length));
+  log(`${c.dim}${shellPad('ID', idW)}  ${shellPad('STATUS', 14)}  ${shellPad('PRI', 4)}  ${shellPad('ASSIGNEE', 12)}  TITLE${c.reset}`);
+  for (const r of rows) {
+    const status = (r.fm.status || 'Backlog') + (r.fm.archived === true || r.fm.archived === 'true' ? ' (archived)' : '');
+    const pri = r.fm.priority || '';
+    const assignee = r.fm.assignee || '';
+    const title = (r.fm.title || '(untitled)').replace(/\n/g, ' ');
+    log(`${shellPad(r.id, idW)}  ${shellPad(status, 14)}  ${shellPad(pri, 4)}  ${shellPad(assignee, 12)}  ${title}`);
+  }
+}
+
+function shellShow(rawArgs) {
+  const { kandownDir } = ensureKandownDir(rawArgs);
+  const args = shellParseArgs(rawArgs);
+  const id = args.positional[0];
+  if (!id) {
+    err('Usage: kandown show <id>');
+    process.exit(1);
+  }
+  const path = findTaskFile(kandownDir, id);
+  if (!path) {
+    err(`Task not found: ${id}`);
+    process.exit(1);
+  }
+  process.stdout.write(readFileSync(path, 'utf8'));
+}
+
+/**
+ * 📖 Resolves a task id to whether it is in a "blocking" state (i.e. still
+ * pending). Used by the move gate. Mirrors the web store's logic: a dep is
+ * resolved when it lives in the terminal column OR is archived. Unknown
+ * ids and self-references never block.
+ */
+function shellTaskIsResolved(kandownDir, id, terminalLower) {
+  if (!/^[a-zA-Z0-9_-]+$/.test(id)) return true; // unknown / invalid → don't block
+  const path = findTaskFile(kandownDir, id);
+  if (!path) return true; // unknown id → don't block
+  const parsed = parseFrontmatter(readFileSync(path, 'utf8'));
+  const isArch = parsed.frontmatter.archived === true || parsed.frontmatter.archived === 'true';
+  return isArch || (parsed.frontmatter.status || '').toLowerCase() === terminalLower;
+}
+
+function shellCreate(rawArgs) {
+  const { kandownDir } = ensureKandownDir(rawArgs);
+  const args = shellParseArgs(rawArgs);
+  const title = args.positional.join(' ').trim();
+  if (!title) {
+    err('Usage: kandown create "title" [-p priority] [-a assignee] [-t tag] [--to status]');
+    process.exit(1);
+  }
+  const config = readKandownConfig(kandownDir);
+  const defaultStatus = (config && config.board && config.board.columns && config.board.columns[0]) || 'Backlog';
+  const targetStatus = args.flags.to ? shellResolveStatus(config, args.flags.to) : defaultStatus;
+  if (args.flags.to && !targetStatus) {
+    err(`Unknown status: ${args.flags.to}`);
+    process.exit(1);
+  }
+  const id = args.flags.id || nextTaskId(kandownDir);
+  if (!/^[a-zA-Z0-9_-]+$/.test(id)) {
+    err(`Invalid task id: ${id}`);
+    process.exit(1);
+  }
+  const tasksDir = getTasksDir(kandownDir);
+  if (!existsSync(tasksDir)) mkdirSync(tasksDir, { recursive: true });
+  const targetPath = join(tasksDir, `${id}.md`);
+  if (existsSync(targetPath)) {
+    err(`Task already exists: ${id}`);
+    process.exit(1);
+  }
+  const fm = {
+    id,
+    title,
+    status: targetStatus,
+    created: new Date().toISOString().slice(0, 10),
+  };
+  if (args.flags.priority) fm.priority = args.flags.priority;
+  if (args.flags.assignee) fm.assignee = args.flags.assignee;
+  if (args.flags.tags && args.flags.tags.length > 0) fm.tags = args.flags.tags;
+  if (args.flags.dependsOn && args.flags.dependsOn.length > 0) fm.depends_on = args.flags.dependsOn;
+  const content = serializeFrontmatter(fm, '');
+  writeFileSync(targetPath, content, 'utf8');
+  log(`${c.green}✓${c.reset} Created ${c.bold}${id}${c.reset} → ${targetStatus}`);
+  if (args.flags.json) {
+    process.stdout.write(JSON.stringify({ id, ...fm }, null, 2) + '\n');
+  } else {
+    // 📖 Print the id on stdout (last line) so scripts can do
+    // `ID=$(kandown create "...")` without parsing the colored status line.
+    process.stdout.write(id + '\n');
+  }
+}
+
+function shellMove(rawArgs) {
+  const { kandownDir } = ensureKandownDir(rawArgs);
+  const args = shellParseArgs(rawArgs);
+  const [id, rawStatus] = args.positional;
+  const targetStatus = rawStatus || args.flags.to;
+  if (!id || !targetStatus) {
+    err('Usage: kandown move <id> <status>');
+    process.exit(1);
+  }
+  const config = readKandownConfig(kandownDir);
+  const resolved = shellResolveStatus(config, targetStatus);
+  if (!resolved) {
+    err(`Unknown status: ${targetStatus}`);
+    process.exit(1);
+  }
+  const path = findTaskFile(kandownDir, id);
+  if (!path) {
+    err(`Task not found: ${id}`);
+    process.exit(1);
+  }
+  // 📖 Terminal-status gate: if the target is the configured terminal column
+  // (default: last entry of `board.columns`, "Done"), refuse the move while
+  // any `depends_on` is not yet resolved. Mirrors the web store + TUI gate.
+  if (config && Array.isArray(config.board.columns) && config.board.columns.length > 0) {
+    const terminalLower = (config.board.columns[config.board.columns.length - 1]).toLowerCase();
+    if (resolved.toLowerCase() === terminalLower) {
+      const parsed = parseFrontmatter(readFileSync(path, 'utf8'));
+      const deps = Array.isArray(parsed.frontmatter.depends_on) ? parsed.frontmatter.depends_on : [];
+      const blocked = [];
+      for (const dep of deps) {
+        if (typeof dep !== 'string' || !dep.trim() || dep === id) continue;
+        if (!shellTaskIsResolved(kandownDir, dep, terminalLower)) blocked.push(dep);
+      }
+      if (blocked.length > 0) {
+        const list = blocked.length === 1 ? blocked[0] : `${blocked.slice(0, -1).join(', ')} and ${blocked[blocked.length - 1]}`;
+        err(`Cannot move ${id} to ${resolved}: blocked by ${list}`);
+        process.exit(1);
+      }
+    }
+  }
+  const parsed = parseFrontmatter(readFileSync(path, 'utf8'));
+  parsed.frontmatter.status = resolved;
+  if (resolved === 'archived') parsed.frontmatter.archived = true;
+  else delete parsed.frontmatter.archived;
+  // 📖 When archiving, move the file to tasks/archive/ to match what the
+  // web UI does. Mirrors src/lib/filesystem.ts#archiveTaskFile.
+  if (resolved === 'archived') {
+    const archiveDir = join(getTasksDir(kandownDir), 'archive');
+    if (!existsSync(archiveDir)) mkdirSync(archiveDir, { recursive: true });
+    writeFileSync(join(archiveDir, `${id}.md`), serializeFrontmatter(parsed.frontmatter, parsed.body), 'utf8');
+    try { unlinkSync(path); } catch { /* already absent */ }
+  } else {
+    writeFileSync(path, serializeFrontmatter(parsed.frontmatter, parsed.body), 'utf8');
+  }
+  log(`${c.green}✓${c.reset} ${c.bold}${id}${c.reset} → ${resolved}`);
+}
+
+function shellAssign(rawArgs) {
+  const { kandownDir } = ensureKandownDir(rawArgs);
+  const args = shellParseArgs(rawArgs);
+  const [id, name] = args.positional;
+  if (!id) {
+    err('Usage: kandown assign <id> [name]   (omit name to unassign)');
+    process.exit(1);
+  }
+  const path = findTaskFile(kandownDir, id);
+  if (!path) {
+    err(`Task not found: ${id}`);
+    process.exit(1);
+  }
+  const parsed = parseFrontmatter(readFileSync(path, 'utf8'));
+  if (name) parsed.frontmatter.assignee = name;
+  else delete parsed.frontmatter.assignee;
+  writeFileSync(path, serializeFrontmatter(parsed.frontmatter, parsed.body), 'utf8');
+  log(`${c.green}✓${c.reset} ${c.bold}${id}${c.reset} → ${name ? c.cyan + name : c.dim + '(unassigned)'}${c.reset}`);
+}
+
+function shellCommit(rawArgs) {
+  const { kandownDir } = ensureKandownDir(rawArgs);
+  const args = shellParseArgs(rawArgs);
+  const projectRoot = getProjectRoot(kandownDir);
+  // 📖 Refuse to commit if not inside a git repo — silently failing here would
+  // let the user believe they versioned their tasks when they didn't.
+  try {
+    execSync('git rev-parse --is-inside-work-tree', { cwd: projectRoot, stdio: 'pipe' });
+  } catch {
+    err('Not a git repository — kandown commit only stages and commits in a git repo.');
+    err('  Run `git init` first or commit manually.');
+    process.exit(1);
+  }
+  const tasksRel = 'tasks';
+  const configRel = '.kandown/kandown.json';
+  const staged = [];
+  for (const rel of [tasksRel, configRel]) {
+    const abs = join(projectRoot, rel);
+    if (!existsSync(abs)) continue;
+    try {
+      execSync(`git add -A -- "${rel}"`, { cwd: projectRoot, stdio: 'pipe' });
+      staged.push(rel);
+    } catch (e) {
+      err(`git add failed for ${rel}: ${e.message}`);
+      process.exit(1);
+    }
+  }
+  if (staged.length === 0) {
+    log(c.dim + 'Nothing to commit.' + c.reset);
+    return;
+  }
+  const message = args.flags.message || `chore(kandown): update tasks`;
+  try {
+    execSync(`git commit -m ${JSON.stringify(message)}`, { cwd: projectRoot, stdio: 'inherit' });
+    success(`Committed ${staged.length} path${staged.length === 1 ? '' : 's'}: ${staged.join(', ')}`);
+  } catch (e) {
+    // 📖 git commit exits non-zero when there's nothing to commit (after the
+    // add). Treat that as a no-op so the user doesn't think they broke
+    // anything.
+    if (e && e.status === 1) {
+      log(c.dim + 'Nothing to commit (working tree clean).' + c.reset);
+      return;
+    }
+    err(`git commit failed: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+function cmdShell(subcmd, rawArgs) {
+  switch (subcmd) {
+    case 'list':
+    case 'ls':
+      shellList(rawArgs);
+      return;
+    case 'show':
+      shellShow(rawArgs);
+      return;
+    case 'create':
+    case 'new':
+      shellCreate(rawArgs);
+      return;
+    case 'move':
+      shellMove(rawArgs);
+      return;
+    case 'assign':
+      shellAssign(rawArgs);
+      return;
+    case 'commit':
+      shellCommit(rawArgs);
+      return;
+    case undefined:
+    case 'help':
+    case '--help':
+    case '-h':
+      log(`
+${c.bold}kandown shell${c.reset} ${c.dim}· task commands (one-shot, scriptable)${c.reset}
+
+${c.bold}Commands:${c.reset}
+  ${c.cyan}list${c.reset}   [-s status] [-a assignee] [-t tag] [-p priority] [--archived] [--json]
+  ${c.cyan}show${c.reset}    <id>
+  ${c.cyan}create${c.reset}  "title" [-p priority] [-a assignee] [-t tag ...] [--to status] [--id custom-id] [--json]
+  ${c.cyan}move${c.reset}    <id> <status>     (status is a column name or "archived")
+  ${c.cyan}assign${c.reset}  <id> [name]       (omit name to unassign)
+  ${c.cyan}commit${c.reset}  [-m "message"]   (git add tasks/ + .kandown/kandown.json + git commit)
+
+${c.bold}Examples:${c.reset}
+  ${c.dim}$${c.reset} kandown list --json | jq '.[] | select(.priority=="P1")'
+  ${c.dim}$${c.reset} kandown create "Refactor auth middleware" -p P1 -t backend
+  ${c.dim}$${c.reset} kandown move t42 Done
+  ${c.dim}$${c.reset} kandown assign t42 alice
+  ${c.dim}$${c.reset} kandown commit -m "tasks: add auth refactor"
+`);
+      return;
+    default:
+      err(`Unknown shell command: ${subcmd}`);
+      log(`  Run ${c.cyan}kandown shell help${c.reset} for the list.`);
+      process.exit(1);
+  }
+}
+
 function parsePort(value) {
   if (value === null) return null;
   const port = Number(value);
@@ -733,6 +1350,105 @@ function readBody(req) {
   });
 }
 
+/**
+ * 📖 Resolves the agent hook configuration from environment variables.
+ *
+ * Strictly opt-in: if KANDOWN_AGENT_HOOK_URL is not set, returns null and no
+ * agent-related UI surfaces in the web app. This is the only check the UI
+ * uses to decide whether to show the "Send to Agent" button.
+ *
+ * Env vars (all optional except URL):
+ *   - KANDOWN_AGENT_HOOK_URL      target URL (POST receives `{action, task, context}`)
+ *   - KANDOWN_AGENT_HOOK_LABEL    button label (default: "Agent")
+ *   - KANDOWN_AGENT_HOOK_HEADERS  JSON object of extra headers (default: {})
+ *
+ * Malformed HEADERS are silently ignored so a typo never disables the hook.
+ */
+function loadAgentHook() {
+  const url = process.env.KANDOWN_AGENT_HOOK_URL;
+  if (!url) return null;
+  const label = process.env.KANDOWN_AGENT_HOOK_LABEL || 'Agent';
+  const headers = {};
+  const raw = process.env.KANDOWN_AGENT_HOOK_HEADERS;
+  if (raw) {
+    try {
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        for (const [k, v] of Object.entries(parsed)) {
+          if (typeof v === 'string') headers[k] = v;
+        }
+      }
+    } catch {
+      // Malformed JSON — ignore and ship with the default empty headers.
+    }
+  }
+  return { url, label, headers };
+}
+
+/**
+ * 📖 Forwards a task to the configured agent hook. Returns a status object
+ * the HTTP handler converts to a JSON response. Failures (network, non-2xx,
+ * timeout) are surfaced as 502 so the UI can show a useful error.
+ */
+async function postAgentTask(hook, taskMarkdown, id, kandownDir) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 8000);
+  try {
+    const res = await fetch(hook.url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...hook.headers,
+      },
+      body: JSON.stringify({
+        action: 'agent',
+        task: { id, content: taskMarkdown },
+        context: {
+          tasksDir: getTasksDir(kandownDir),
+          cwd: getProjectRoot(kandownDir),
+          schema: 'kandown',
+        },
+      }),
+      signal: controller.signal,
+    });
+    const body = await res.text().catch(() => '');
+    return { ok: res.ok, status: res.status, body };
+  } catch (e) {
+    const message = e && e.name === 'AbortError' ? 'agent hook timed out (8s)' : `agent hook failed: ${e.message}`;
+    return { ok: false, status: 502, body: message };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function postTaskToAgent(req, res, kandownDir, id) {
+  if (!isValidTaskId(id)) {
+    return writeText(res, 400, 'Invalid task id');
+  }
+  const hook = loadAgentHook();
+  if (!hook) {
+    return writeJson(res, 501, { error: 'agent hook not configured (set KANDOWN_AGENT_HOOK_URL)' });
+  }
+  const taskPath = findTaskPath(kandownDir, id);
+  if (!taskPath) {
+    return writeJson(res, 404, { error: 'task not found' });
+  }
+  let taskMarkdown;
+  try {
+    taskMarkdown = readFileSync(taskPath, 'utf8');
+  } catch (e) {
+    return writeJson(res, 500, { error: `failed to read task: ${e.message}` });
+  }
+  postAgentTask(hook, taskMarkdown, id, kandownDir).then(result => {
+    if (!result.ok) {
+      return writeJson(res, 502, { error: result.body || `agent hook returned ${result.status}` });
+    }
+    return writeJson(res, 200, { ok: true });
+  }).catch(e => {
+    writeJson(res, 500, { error: e.message });
+  });
+}
+
 function isValidTaskId(id) {
   return /^[a-zA-Z0-9_-]+$/.test(id);
 }
@@ -796,17 +1512,21 @@ function putBoard(req, res, kandownDir) {
  * first, then the archive subfolder. Returns null when the id exists in
  * neither location. Used by every CRUD handler so archived tasks stay
  * reachable at their real location.
+ *
+ * Tasks live at the project root in `./tasks/` (sibling of `.kandown/`),
+ * not inside `.kandown/tasks/`.
  */
 function findTaskPath(kandownDir, id) {
-  const inTasks = join(kandownDir, 'tasks', `${id}.md`);
+  const tasksDir = getTasksDir(kandownDir);
+  const inTasks = join(tasksDir, `${id}.md`);
   if (existsSync(inTasks)) return inTasks;
-  const inArchive = join(kandownDir, 'tasks', 'archive', `${id}.md`);
+  const inArchive = join(tasksDir, 'archive', `${id}.md`);
   if (existsSync(inArchive)) return inArchive;
   return null;
 }
 
 function getTasks(res, kandownDir) {
-  const tasksDir = join(kandownDir, 'tasks');
+  const tasksDir = getTasksDir(kandownDir);
   const archiveDir = join(tasksDir, 'archive');
   const ids = new Set();
   try {
@@ -853,7 +1573,7 @@ function putTask(req, res, kandownDir, id) {
     return;
   }
   readBody(req).then(body => {
-    const tasksDir = join(kandownDir, 'tasks');
+    const tasksDir = getTasksDir(kandownDir);
     if (!existsSync(tasksDir)) mkdirSync(tasksDir, { recursive: true });
     // 📖 Write in place: keep an archived task inside archive/ on save so the
     // file location never drifts from its archived flag.
@@ -887,6 +1607,66 @@ function deleteTask(res, kandownDir, id) {
   }
 }
 
+/**
+ * 📖 Archives a task: writes the (already flag-updated) content into
+ * `tasks/archive/<id>.md` and removes the active `tasks/<id>.md` copy.
+ * The body comes pre-flagged from the web client (which knows frontmatter).
+ */
+function archiveTask(req, res, kandownDir, id) {
+  if (!isValidTaskId(id)) {
+    writeText(res, 400, 'Invalid task id');
+    return;
+  }
+  readBody(req).then(body => {
+    const tasksDir = getTasksDir(kandownDir);
+    const archiveDir = join(tasksDir, 'archive');
+    if (!existsSync(archiveDir)) mkdirSync(archiveDir, { recursive: true });
+    writeFileSync(join(archiveDir, `${id}.md`), body, 'utf8');
+    try {
+      unlinkSync(join(tasksDir, `${id}.md`));
+    } catch { /* already absent */ }
+    writeJson(res, 200, { ok: true });
+  }).catch(e => {
+    writeJson(res, 500, { error: `Failed to archive task: ${e.message}` });
+  });
+}
+
+/**
+ * 📖 Unarchives a task: writes the content back into `tasks/<id>.md` and
+ * removes the archived copy. Mirror of archiveTask.
+ */
+function unarchiveTask(req, res, kandownDir, id) {
+  if (!isValidTaskId(id)) {
+    writeText(res, 400, 'Invalid task id');
+    return;
+  }
+  readBody(req).then(body => {
+    const tasksDir = getTasksDir(kandownDir);
+    writeFileSync(join(tasksDir, `${id}.md`), body, 'utf8');
+    try {
+      unlinkSync(join(tasksDir, 'archive', `${id}.md`));
+    } catch { /* already absent */ }
+    writeJson(res, 200, { ok: true });
+  }).catch(e => {
+    writeJson(res, 500, { error: `Failed to unarchive task: ${e.message}` });
+  });
+}
+
+/**
+ * 📖 REST endpoint to trigger the silent one-time task migration. The web
+ * client (server mode) can call this on startup to perform the same
+ * `.kandown/tasks/` → `./tasks/` move the CLI does on first access.
+ * Safe to call multiple times — idempotent.
+ */
+function postMigrateTasks(res, kandownDir) {
+  try {
+    const result = migrateTasksToTopLevel(kandownDir);
+    writeJson(res, 200, { ok: true, ...result });
+  } catch (e) {
+    writeJson(res, 500, { error: `Migration failed: ${e.message}` });
+  }
+}
+
 /**
  * 📖 The single-file Vite bundle can contain literal strings such as
  * `</head>` from HTML parser libraries. Use the last closing head tag so the
@@ -910,12 +1690,14 @@ function handleApi(req, res, url, kandownDir) {
 
   if (resource === 'daemon') {
     if (req.method === 'GET') {
+      const hook = loadAgentHook();
       return writeJson(res, 200, {
         ok: true,
         pid: process.pid,
         kandownDir,
         version: getCurrentVersion(),
         startedAt: daemonStartedAt,
+        agentHook: hook ? { enabled: true, label: hook.label } : null,
       });
     }
   }
@@ -939,6 +1721,12 @@ function handleApi(req, res, url, kandownDir) {
     // the full task file content with the archived flag already toggled.
     if (req.method === 'POST' && id && parts[2] === 'archive') return archiveTask(req, res, kandownDir, id);
     if (req.method === 'POST' && id && parts[2] === 'unarchive') return unarchiveTask(req, res, kandownDir, id);
+    if (req.method === 'POST' && id && parts[2] === 'agent') return postTaskToAgent(req, res, kandownDir, id);
+  }
+
+  // 📖 Migration endpoint: `POST /api/migrate-tasks` with no id. Idempotent.
+  if (resource === 'migrate-tasks' && req.method === 'POST' && !id) {
+    return postMigrateTasks(res, kandownDir);
   }
 
   writeJson(res, 404, { error: 'Not found' });
@@ -1307,6 +2095,14 @@ switch (cmd) {
     cmdUpdate(rest);
     break;
 
+  case 'shell': {
+    // 📖 Two-level command: `kandown shell <subcmd> [...args]`. Pull the
+    // first non-flag arg as the subcommand and forward the rest.
+    const [shellSubcmd, ...shellRest] = rest;
+    cmdShell(shellSubcmd, shellRest);
+    break;
+  }
+
   case 'help':
   case '--help':
   case '-h':