kanbango 3.0.2 → 3.2.0

package/.ai/lessons.jsonl

@@ -2,3 +2,4 @@
 {"id":"260729-1ur","ts":"2026-07-29","scope":"proj","tags":["javascript","objects"],"rule":"DON'T Use empty object fallbacks in spreads like `...(obj || {})` since spreading falsy is safe","when":"object spread","sev":2,"hits":1}
 {"id":"260729-5eo","ts":"2026-07-29","scope":"proj","tags":["processes","mcp","ownership"],"rule":"DO Track process ownership before stopping or cleaning up discovered services","when":"gui-process management","sev":2,"hits":1}
 {"id":"260729-1ch","ts":"2026-07-29","scope":"proj","tags":["gui","process","mcp"],"rule":"DO GUI/MCP stop must only SIGTERM processes spawned by the current process; treat port-file PIDs as external_running","when":"gui-process management","sev":2,"hits":1}
+{"id":"260731-o6g","ts":"2026-07-31","scope":"proj","tags":["kanban","epics","mcp"],"rule":"DO Default list/list_epics hide done+archived; hard-delete cascades epic children; archive is reversible flag","when":"kanban cleanup context","sev":2,"hits":1}

package/.ai/retro/last-run.json

@@ -1 +1 @@
-{"ts":"2026-07-29T10:38:42.184Z","sessionID":"ses_052c1be3fffeNPoV7VO6z40X2I","added":["260729-1ch"],"bumped":[]}
+{"ts":"2026-07-31T13:58:00.629Z","sessionID":"ses_04792cf77ffec14LhSNoSJReg9","added":["260731-o6g"],"bumped":[]}

package/AGENTS.md

@@ -6,10 +6,15 @@ This document provides build commands, testing procedures, and code style guidel
 
 Source of truth: `agent-playbook.js` (also MCP tool descriptions + `kanban_read` `operation=help`).
 
+- hierarchy: epic (context) → task (work+plan) → subtasks (steps)
 - list: `col` filter, `view=summary`; keep `task_id`s; no full-board re-list after every write
+- list_epics default = live only (hides done + archived); `include_archived` / `status` to widen
+- list tasks default hides tasks under done/archived epics; show/show_epic by id always works
 - show: `view=execution` while coding; `full` only if needed
+- epic_create with description/goals; create tasks with `epic=E001` (prefer id)
 - create once with `description`, `specs`, `in_scope`, `out_of_scope`, `acceptance_criteria`
-- move/update: `return=none`; subtasks = full array replace (no toggle)
+- move/update/delete: `return=none`; subtasks = full array replace (no toggle)
+- cleanup: `delete` (task), `epic_delete` (cascade), `epic_archive` / `epic_unarchive`
 - non-trivial work: `plan_create` → `plan_advance` → `plan_evidence` (real tests, truncated logs) → `plan_done`
 - gui: `status` before `start`; `stop` only owned; `external_running` = do not kill
 

package/CHANGELOG.md

@@ -5,6 +5,42 @@ All notable changes to kanbango will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [3.2.0] - 2026-07-31
+
+### Added
+- GUI project label: browser tab title, header, port file, and `kanban_gui` start/status include `project` (basename of cwd; override with `KANBANGO_PROJECT_NAME`)
+- Epic field `archived` + status `archived` (overrides derived child rollup)
+- Hard delete: MCP `delete` / `epic_delete` (cascade child tasks), CLI `kanban rm` / `kanban epic rm`, HTTP `DELETE`
+- Archive: MCP `epic_archive` / `epic_unarchive`, CLI `kanban epic archive|unarchive`, HTTP `POST .../archive|unarchive`
+- `list_epics` default live-only (empty|planned|active); `include_archived`, `include_done`, `status` filters
+- Task `list` hides tasks under done/archived epics unless `include_archived`/`include_done` (explicit `epic=` filter still shows them)
+- GUI: Archive/Unarchive/Delete on epic swimlane, Delete on task card, Show archived toggle
+- Tests: `tests/delete-archive.test.js`
+
+### Changed
+- Agent playbook documents cleanup + live-only epic discovery
+- `show` / `show_epic` by id still return archived items (explicit lookup)
+
+## [3.1.0] - 2026-07-30
+
+### Added
+- First-class epic containers under `backlog/epics/E00N.json` (description, goals, in/out scope, notes)
+- Task field `epic_id` with denormalized `epic_group` title for lists/GUI
+- Derived epic status/progress from child task columns (no epic board column)
+- MCP: `list_epics`, `show_epic`, `epic_create`, `epic_update`
+- CLI: `kanban epic list|show|add|update`
+- HTTP: `GET/POST /api/epics` for real epics; `POST /api/tasks` for tasks (legacy `/api/epics` + `column` still creates tasks)
+- Auto-migration of legacy `epic_group` string labels into epic entities
+- GUI swimlanes group by `epic_id` and show epic context
+- Regression tests in `tests/epics.test.js`
+
+### Changed
+- Hierarchy documented for agents: epic → task → subtasks
+- Task summary view includes `epic_id`
+- Agent playbook includes epic discovery/create rules
+
 ## [3.0.2] - 2026-07-29
 
 ### Added

package/LLM_AGENTS.md

@@ -249,7 +249,7 @@ Control the web GUI server: start, stop, or check status.
 2. Else `KANBANGO_GUI_PORT` env
 3. Else stable hash of project cwd in range `5510–5999`
 
-If the preferred port is busy, the server picks the next free port. Always trust the returned `url` / `port` (also written to `backlog/.kanbango-gui.json`).
+If the preferred port is busy, the server picks the next free port. Always trust the returned `url` / `port` (also written to `backlog/.kanbango-gui.json`). Responses also include `project` (basename of project cwd, or `KANBANGO_PROJECT_NAME`) so agents and humans can tell boards apart; the GUI tab title and header show the same label.
 
 **Auto-start with MCP:** set `KANBANGO_AUTO_GUI=1` in the MCP server env. GUI starts when MCP starts; use `status` to read the URL.
 

package/README.md

@@ -31,8 +31,20 @@ kanban serve
 # List all tasks
 kanban list --json
 
-# Add a task
-kanban add "My task" --col planned --epic "Phase 1"
+# Add an epic (initiative container), then a task under it
+kanban epic add "Phase 1" --description "Why this initiative" --goals "Ship X"
+kanban add "My task" --col planned --epic E001
+
+# List epics / show epic with child rollup (default: live only)
+kanban epic list --json
+kanban epic list --all --json
+kanban epic show E001
+
+# Archive or delete (epic_delete cascades child tasks)
+kanban epic archive E001
+kanban epic unarchive E001
+kanban epic rm E001
+kanban rm 001
 
 # Show details
 kanban show 001
@@ -44,6 +56,16 @@ kanban move 001 active
 kanban update 001 '{"subtasks":[{"done":true,"text":"Research"},{"done":false,"text":"Implementation"}]}'
 ```
 
+### Hierarchy
+
+| Level | What | Storage |
+|-------|------|---------|
+| **Epic** | Initiative context (description, goals) | `backlog/epics/E001.json` |
+| **Task** | Kanban card (column, AC, plan) | `backlog/{col}/001.json` |
+| **Subtask** | Checklist / plan steps | `subtasks[]` on task |
+
+Epic status is **derived** from child task columns (not a board column).
+
 ### Columns
 
 | Column | Purpose |
@@ -115,7 +137,7 @@ Auto-start the web GUI with MCP (opt-in):
 }
 ```
 
-Optional: pin the port with `KANBANGO_GUI_PORT` (e.g. `"5821"`). Without it, each project gets a stable port in `5510–5999` derived from the project path. The real URL is always available via `kanban_gui` → `status` (and written to `backlog/.kanbango-gui.json` while the GUI runs).
+Optional: pin the port with `KANBANGO_GUI_PORT` (e.g. `"5821"`). Without it, each project gets a stable port in `5510–5999` derived from the project path. The real URL is always available via `kanban_gui` → `status` (and written to `backlog/.kanbango-gui.json` while the GUI runs). The browser tab title, GUI header, and `kanban_gui` responses include `project` (folder name of the project cwd; override with `KANBANGO_PROJECT_NAME`).
 
 Or generate the config files automatically:
 
@@ -163,7 +185,7 @@ kanban serve
 
 ```js
 const kanban = require('kanbango');
-const tasks = await kanban.allEpics();
+const tasks = await kanban.allTasks();
 ```
 
 ## Requirements

package/agent-playbook.js

@@ -6,10 +6,15 @@
 
 const DROP_IN_RULE = [
   'Kanbango MCP — token rules:',
+  '- hierarchy: epic (context) → task (work+plan) → subtasks (steps)',
   '- list: col filter, view=summary; keep task_ids; no full-board re-list after writes',
+  '- list_epics default = live only (hides done + archived); include_archived / status to widen',
+  '- list tasks default hides tasks under done/archived epics; show/show_epic by id always works',
   '- show: view=execution while coding; full only if needed',
+  '- epic_create with description/goals; create tasks with epic=E001 (prefer id)',
   '- create once with description,specs,in_scope,out_of_scope,acceptance_criteria',
-  '- move/update: return=none; subtasks=full array replace',
+  '- move/update/delete: return=none; subtasks=full array replace',
+  '- cleanup: delete (task), epic_delete (cascade tasks), epic_archive / epic_unarchive',
   '- non-trivial: plan_create → plan_advance → plan_evidence (real tests, truncated logs) → plan_done',
   '- gui: status before start; stop only owned; external_running = do not kill'
 ].join('\n');
@@ -17,21 +22,29 @@ const DROP_IN_RULE = [
 const TOOL_DESCRIPTIONS = {
   kanban_read: [
     'Read board. TOKEN RULES: list defaults to view=summary (id/title/col/progress only).',
+    'Hierarchy: epic (container/context) → task (work) → subtasks (steps).',
     'Always pass col when possible. Prefer show+view=execution over full.',
+    'list_epics default live only (empty|planned|active; hides done+archived).',
+    'Pass include_archived=true or status=done|archived to see closed initiatives.',
+    'list hides tasks under done/archived epics unless include_archived/include_done; show/show_epic by id always works.',
     'Do not re-list the whole board after every write — keep task_id from create/move.',
-    'IDs are numeric ("014" or "14"). views: summary|planning|execution|full; fields[] overrides view.',
+    'Task IDs numeric ("014"); epic IDs "E001". views: summary|planning|execution|full; fields[] overrides view.',
     'operation=help returns this playbook as short text (no board I/O).'
   ].join(' '),
 
   kanban_manage: [
     'Write board / plan. TOKEN RULES: one create with all planning fields beats many updates;',
     'after write use return=none (or summary). Do not dump full task unless needed.',
-    'Actions: create|move|update (daily); plan_create→plan_advance→plan_evidence→plan_done (non-trivial only).',
+    'Actions: create|move|update|delete (daily); epic_create|epic_update|epic_archive|epic_unarchive|epic_delete;',
+    'plan_create→plan_advance→plan_evidence→plan_done (non-trivial only).',
+    'epic_create: title + description/goals/in_scope/out_of_scope. Link tasks via epic=E001.',
+    'delete: task_id (hard remove). epic_delete: epic_id, always cascades child tasks.',
+    'epic_archive/epic_unarchive: epic_id — hide/restore initiative without deleting history.',
     'create/plan_create: title required; also send description,specs,in_scope,out_of_scope,acceptance_criteria',
     '(missing → warnings, not failure). move: task_id+column. update: task_id + fields or subtasks[] full list',
     '(no toggle). plan_evidence needs real test run: diff,test_command,stdout,stderr,exit_code — truncate logs.',
-    'Example create: {"action":"create","title":"Ship image","description":"...","specs":"...","in_scope":["CLI"],',
-    '"out_of_scope":["GUI"],"acceptance_criteria":["npm test passes"],"col":"planned"}'
+    'Example create: {"action":"create","title":"Ship image","epic":"E001","description":"...","specs":"...",',
+    '"in_scope":["CLI"],"out_of_scope":["GUI"],"acceptance_criteria":["npm test passes"],"col":"planned"}'
   ].join(' '),
 
   kanban_gui: [
@@ -47,7 +60,10 @@ const MUST_CONTAIN = [
   'return=none',
   'plan_create',
   'external_running',
-  'subtasks'
+  'subtasks',
+  'epic_create',
+  'epic_archive',
+  'epic_delete'
 ];
 
 function playbookHelpPayload() {

package/bin/kanban.js

@@ -99,7 +99,8 @@ async function cliInit() {
         + '- `active/`  — w trakcie (max 1-2)\n'
         + '- `planned/` — zaplanowane\n'
         + '- `icebox/`  — zamrozone / nice-to-have\n'
-        + '- `done/`    — ukonczone\n',
+        + '- `done/`    — ukonczone\n'
+        + '- `epics/`   — first-class epic containers (context for initiatives)\n',
       'utf-8'
     );
   }
@@ -144,14 +145,18 @@ async function cliMcpInit(options) {
   }
 }
 
-async function cliList(colFilter, epicFilter, asJson) {
-  let tasks = await kanban.allEpics();
+async function cliList(colFilter, epicFilter, asJson, listOptions = {}) {
+  await kanban.migrateEpicGroups();
+  const epics = await kanban.listEpicEntities();
+  let tasks = await kanban.allTasks();
 
   if (colFilter) {
     tasks = tasks.filter((task) => task.column === colFilter);
   }
   if (epicFilter) {
-    tasks = tasks.filter((task) => task.epic_group === epicFilter);
+    tasks = tasks.filter((task) => kanban.taskMatchesEpicFilter(task, epicFilter));
+  } else {
+    tasks = kanban.filterTasksForList(tasks, epics, listOptions);
   }
 
   if (asJson) {
@@ -168,8 +173,11 @@ async function cliList(colFilter, epicFilter, asJson) {
     const progress = kanban.getProgress(task);
     const prog = progress.total ? `${progress.done}/${progress.total}` : '—';
     const title = displayTitle(task).substring(0, 42);
+    const epicLabel = task.epic_id
+      ? `${task.epic_id}:${task.epic_group}`
+      : task.epic_group;
     console.log(
-      `  ${task.column.padEnd(8)}  ${shortId(task.id).padEnd(8)}  ${title.padEnd(43)}  ${prog.padStart(5)}  [${task.epic_group}]`
+      `  ${task.column.padEnd(8)}  ${shortId(task.id).padEnd(8)}  ${title.padEnd(43)}  ${prog.padStart(5)}  [${epicLabel}]`
     );
   }
 }
@@ -181,7 +189,7 @@ async function cliShow(taskId) {
     console.log(`Plik:    ${taskFilePath(task)}`);
     console.log(`Tytuł:   ${displayTitle(task)}`);
     console.log(`Kolumna: ${task.column}`);
-    console.log(`Epik:    ${task.epic_group}`);
+    console.log(`Epik:    ${task.epic_id ? `${task.epic_id} (${task.epic_group})` : task.epic_group}`);
     console.log(`Worzono: ${task.created || '—'}`);
 
     if (task.description) {
@@ -202,6 +210,100 @@ async function cliShow(taskId) {
   }
 }
 
+async function cliEpicList(asJson, listOptions = {}) {
+  await kanban.migrateEpicGroups();
+  const tasks = await kanban.allTasks();
+  const epics = await kanban.listEpicEntities();
+  const shaped = kanban.filterShapedEpics(
+    epics.map((epic) => kanban.shapeEpic(epic, tasks, { view: 'summary' })),
+    listOptions
+  );
+
+  if (asJson) {
+    console.log(JSON.stringify(shaped, null, 2));
+    return;
+  }
+
+  if (shaped.length === 0) {
+    console.log('(brak epików)');
+    return;
+  }
+
+  for (const epic of shaped) {
+    const p = epic.progress || {};
+    const flag = epic.archived ? ' [archived]' : '';
+    console.log(
+      `  ${epic.id.padEnd(6)}  ${epic.status.padEnd(8)}  ${String(epic.title).substring(0, 40).padEnd(40)}  ${p.tasks_done || 0}/${p.tasks_total || 0} tasks${flag}`
+    );
+  }
+}
+
+async function cliEpicShow(epicId) {
+  try {
+    await kanban.migrateEpicGroups();
+    const link = await kanban.resolveEpicRef(epicId, { createIfMissing: false });
+    const epic = await kanban.getEpicEntity(link.epic_id);
+    const tasks = await kanban.allTasks();
+    const shaped = kanban.shapeEpic(epic, tasks, { view: 'full' });
+    console.log(JSON.stringify(shaped, null, 2));
+  } catch (error) {
+    console.error(`✗ ${error.message}`);
+    process.exit(1);
+  }
+}
+
+async function cliEpicAdd(title, options = {}) {
+  try {
+    const epic = await kanban.doCreateEpic(title, options);
+    console.log(`✓ Epic ${epic.id}: ${epic.title}`);
+  } catch (error) {
+    console.error(`✗ ${error.message}`);
+    process.exit(1);
+  }
+}
+
+async function cliEpicUpdate(epicId, patch) {
+  try {
+    const epic = await kanban.updateEpicEntity(epicId, patch);
+    console.log(`✓ Epic ${epic.id} updated`);
+  } catch (error) {
+    console.error(`✗ ${error.message}`);
+    process.exit(1);
+  }
+}
+
+async function cliEpicArchive(epicId, archived) {
+  try {
+    const epic = archived
+      ? await kanban.archiveEpic(epicId)
+      : await kanban.unarchiveEpic(epicId);
+    console.log(`✓ Epic ${epic.id} ${archived ? 'archived' : 'unarchived'}`);
+  } catch (error) {
+    console.error(`✗ ${error.message}`);
+    process.exit(1);
+  }
+}
+
+async function cliEpicDelete(epicId) {
+  try {
+    const result = await kanban.deleteEpic(epicId);
+    console.log(`✓ Deleted epic ${result.epic_id} (+${result.deleted_task_count} tasks)`);
+  } catch (error) {
+    console.error(`✗ ${error.message}`);
+    process.exit(1);
+  }
+}
+
+async function cliDelete(taskId) {
+  try {
+    const result = await kanban.deleteTask(taskId);
+    console.log(`✓ Deleted task ${shortId(result.task_id)}: ${result.title}`);
+  } catch (error) {
+    console.error(`✗ ${error.message}`);
+    process.exit(1);
+  }
+}
+
 async function cliMove(taskId, column) {
   const success = await kanban.doMove(taskId, column);
   if (success) {
@@ -223,8 +325,21 @@ async function cliAdd(title, column, epicGroup) {
   }
 }
 
+function injectProjectIntoHtml(html, project) {
+  const safe = String(project)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+  return html
+    .replace(/<title>[^<]*<\/title>/, `<title>${safe} · Kanban</title>`)
+    .replace(/<h1>Donna Kanban<\/h1>/, `<h1>${safe}</h1>`);
+}
+
 async function serveWeb(port) {
-  const html = fs.readFileSync(path.join(__dirname, '..', 'index.html'), 'utf-8');
+  const htmlTemplate = fs.readFileSync(path.join(__dirname, '..', 'index.html'), 'utf-8');
+  const project = guiRegistry.projectLabel();
+  const html = injectProjectIntoHtml(htmlTemplate, project);
 
   const server = http.createServer(async (req, res) => {
     const url = new URL(req.url, `http://localhost:${port}`);
@@ -238,29 +353,129 @@ async function serveWeb(port) {
       }
 
       if (requestPath === '/api/board') {
-        const tasks = await kanban.allEpics();
+        await kanban.migrateEpicGroups();
+        const includeArchived = url.searchParams.get('include_archived') === 'true';
+        const epics = await kanban.listEpicEntities();
+        // GUI: show done-epic tasks; only hide archived unless toggled
+        const tasks = kanban.filterTasksForList(await kanban.allTasks(), epics, {
+          live_only: false,
+          include_archived: includeArchived
+        });
         sendJson(res, 200, tasks);
         return;
       }
 
+      if (requestPath === '/api/epics' && req.method === 'GET') {
+        await kanban.migrateEpicGroups();
+        const tasks = await kanban.allTasks();
+        const epics = await kanban.listEpicEntities();
+        const shaped = epics.map((epic) => kanban.shapeEpic(epic, tasks, { view: 'full' }));
+        const includeArchived = url.searchParams.get('include_archived') === 'true';
+        const includeDone = url.searchParams.get('include_done') === 'true';
+        const status = url.searchParams.get('status') || undefined;
+        // GUI default: all non-archived (live + done). Agents use MCP live-only.
+        const liveOnly = url.searchParams.get('live_only') === 'true';
+        const filtered = kanban.filterShapedEpics(shaped, liveOnly
+          ? { include_archived: includeArchived, include_done: includeDone, status }
+          : { live_only: false, include_archived: includeArchived, status });
+        sendJson(res, 200, filtered);
+        return;
+      }
+
       if (requestPath === '/api/epics' && req.method === 'POST') {
         const body = await readBody(req);
-        const task = await kanban.doCreate(body.title || '', body.column || 'planned', body.epic_group || '—', {
-          description: body.description,
-          specs: body.specs,
-          in_scope: body.in_scope,
-          out_of_scope: body.out_of_scope,
-          acceptance_criteria: body.acceptance_criteria,
-          test_cases: body.test_cases,
-          subtasks: body.subtasks,
-          notes: body.notes
-        });
+        // Real epic container when no task column is provided.
+        if (body.column === undefined && body.as_task !== true) {
+          const epic = await kanban.doCreateEpic(body.title || '', {
+            description: body.description,
+            goals: body.goals,
+            in_scope: body.in_scope,
+            out_of_scope: body.out_of_scope,
+            notes: body.notes
+          });
+          sendJson(res, 201, kanban.shapeEpic(epic, [], { view: 'full' }));
+          return;
+        }
+
+        const task = await kanban.doCreate(
+          body.title || '',
+          body.column || 'planned',
+          body.epic_id || body.epic || body.epic_group || '—',
+          {
+            description: body.description,
+            specs: body.specs,
+            in_scope: body.in_scope,
+            out_of_scope: body.out_of_scope,
+            acceptance_criteria: body.acceptance_criteria,
+            test_cases: body.test_cases,
+            subtasks: body.subtasks,
+            notes: body.notes
+          }
+        );
+        sendJson(res, 201, task);
+        return;
+      }
+
+      if (requestPath === '/api/tasks' && req.method === 'POST') {
+        const body = await readBody(req);
+        const task = await kanban.doCreate(
+          body.title || '',
+          body.column || 'planned',
+          body.epic_id || body.epic || body.epic_group || '—',
+          {
+            description: body.description,
+            specs: body.specs,
+            in_scope: body.in_scope,
+            out_of_scope: body.out_of_scope,
+            acceptance_criteria: body.acceptance_criteria,
+            test_cases: body.test_cases,
+            subtasks: body.subtasks,
+            notes: body.notes
+          }
+        );
         sendJson(res, 201, task);
         return;
       }
 
+      if (req.method === 'DELETE') {
+        const epicDeleteMatch = requestPath.match(/^\/api\/epic-entities\/([^/]+)$/);
+        if (epicDeleteMatch) {
+          const result = await kanban.deleteEpic(epicDeleteMatch[1]);
+          sendJson(res, 200, result);
+          return;
+        }
+
+        const taskDeleteMatch = requestPath.match(/^\/api\/(?:epics|tasks)\/([^/]+)$/);
+        if (taskDeleteMatch) {
+          const result = await kanban.deleteTask(taskDeleteMatch[1]);
+          sendJson(res, 200, result);
+          return;
+        }
+      }
+
+      if (req.method === 'POST') {
+        const epicArchiveMatch = requestPath.match(/^\/api\/epic-entities\/([^/]+)\/(archive|unarchive)$/);
+        if (epicArchiveMatch) {
+          const epic = epicArchiveMatch[2] === 'archive'
+            ? await kanban.archiveEpic(epicArchiveMatch[1])
+            : await kanban.unarchiveEpic(epicArchiveMatch[1]);
+          sendJson(res, 200, kanban.shapeEpic(epic, await kanban.allTasks(), { view: 'full' }));
+          return;
+        }
+      }
+
       if (req.method === 'PATCH') {
-        const moveMatch = requestPath.match(/^\/api\/epics\/([^/]+)\/move$/);
+        const epicUpdateMatch = requestPath.match(/^\/api\/epic-entities\/([^/]+)$/);
+        if (epicUpdateMatch) {
+          const body = await readBody(req);
+          const patch = body.patch ? { ...body.patch } : { ...body };
+          delete patch.patch;
+          const epic = await kanban.updateEpicEntity(epicUpdateMatch[1], patch);
+          sendJson(res, 200, kanban.shapeEpic(epic, await kanban.allTasks(), { view: 'full' }));
+          return;
+        }
+
+        const moveMatch = requestPath.match(/^\/api\/(?:epics|tasks)\/([^/]+)\/move$/);
         if (moveMatch) {
           const taskId = moveMatch[1];
           const body = await readBody(req);
@@ -269,7 +484,7 @@ async function serveWeb(port) {
           return;
         }
 
-        const toggleMatch = requestPath.match(/^\/api\/epics\/([^/]+)\/tasks\/(\d+)$/);
+        const toggleMatch = requestPath.match(/^\/api\/(?:epics|tasks)\/([^/]+)\/tasks\/(\d+)$/);
         if (toggleMatch) {
           const taskId = toggleMatch[1];
           const idx = parseInt(toggleMatch[2], 10);
@@ -294,7 +509,7 @@ async function serveWeb(port) {
           return;
         }
 
-        const updateMatch = requestPath.match(/^\/api\/epics\/([^/]+)$/);
+        const updateMatch = requestPath.match(/^\/api\/(?:epics|tasks)\/([^/]+)$/);
         if (updateMatch) {
           const taskId = updateMatch[1];
           const body = await readBody(req);
@@ -309,7 +524,9 @@ async function serveWeb(port) {
           if (body.test_cases !== undefined) patch.test_cases = body.test_cases;
           if (body.subtasks !== undefined) patch.subtasks = body.subtasks;
           if (body.notes !== undefined) patch.notes = body.notes;
-          if (body.epic_group !== undefined) patch.epic_group = body.epic_group;
+          if (body.epic_id !== undefined) patch.epic_id = body.epic_id;
+          else if (body.epic !== undefined) patch.epic = body.epic;
+          else if (body.epic_group !== undefined) patch.epic_group = body.epic_group;
 
           const task = await kanban.updateTask(taskId, patch);
           sendJson(res, 200, task);
@@ -381,6 +598,7 @@ async function serveWeb(port) {
   });
 
   console.log(`\x1b[1;32m→ Kanban GUI: ${portInfo.url}\x1b[0m`);
+  console.log(`  Project:   ${portInfo.project || project}`);
   console.log(`  Backlog:   ${BACKLOG}`);
   console.log('  Ctrl+C żeby zamknąć');
 }
@@ -494,6 +712,7 @@ async function main() {
     let colFilter = null;
     let epicFilter = null;
     let asJson = false;
+    let includeArchived = false;
 
     for (let i = 1; i < args.length; i++) {
       if (args[i] === '--col' && args[i + 1]) {
@@ -502,12 +721,57 @@ async function main() {
         epicFilter = args[++i];
       } else if (args[i] === '--json') {
         asJson = true;
+      } else if (args[i] === '--include-archived') {
+        includeArchived = true;
       }
     }
 
-    await cliList(colFilter, epicFilter, asJson);
+    await cliList(colFilter, epicFilter, asJson, { include_archived: includeArchived });
+  } else if (cmd === 'epic') {
+    const sub = args[1];
+    if (sub === 'list') {
+      let includeArchived = false;
+      let includeDone = false;
+      let status;
+      for (let i = 2; i < args.length; i++) {
+        if (args[i] === '--include-archived') includeArchived = true;
+        else if (args[i] === '--include-done') includeDone = true;
+        else if (args[i] === '--all') {
+          includeArchived = true;
+          includeDone = true;
+        } else if (args[i] === '--status' && args[i + 1]) status = args[++i];
+      }
+      await cliEpicList(args.includes('--json'), {
+        include_archived: includeArchived,
+        include_done: includeDone,
+        status
+      });
+    } else if (sub === 'show' && args[2]) {
+      await cliEpicShow(args[2]);
+    } else if (sub === 'add' && args[2]) {
+      let description = '';
+      let goals = '';
+      for (let i = 3; i < args.length; i++) {
+        if (args[i] === '--description' && args[i + 1]) description = args[++i];
+        else if (args[i] === '--goals' && args[i + 1]) goals = args[++i];
+      }
+      await cliEpicAdd(args[2], { description, goals });
+    } else if (sub === 'update' && args[2] && args[3]) {
+      await cliEpicUpdate(args[2], parseJsonPayload(args[3]));
+    } else if (sub === 'archive' && args[2]) {
+      await cliEpicArchive(args[2], true);
+    } else if (sub === 'unarchive' && args[2]) {
+      await cliEpicArchive(args[2], false);
+    } else if ((sub === 'rm' || sub === 'delete') && args[2]) {
+      await cliEpicDelete(args[2]);
+    } else {
+      console.error('Usage: kanban epic list|show|add|update|archive|unarchive|rm ...');
+      process.exit(1);
+    }
   } else if (cmd === 'show' && args[1]) {
     await cliShow(args[1]);
+  } else if ((cmd === 'rm' || cmd === 'delete') && args[1]) {
+    await cliDelete(args[1]);
   } else if (cmd === 'move' && args[1] && args[2]) {
     await cliMove(args[1], args[2]);
   } else if (cmd === 'add' && args[1]) {

package/gui-registry.js

@@ -21,6 +21,15 @@ function guiPortFilePath() {
   return path.join(BACKLOG, GUI_PORT_FILE);
 }
 
+function projectLabel(cwd = process.cwd()) {
+  const fromEnv = process.env.KANBANGO_PROJECT_NAME;
+  if (fromEnv !== undefined && fromEnv !== null && String(fromEnv).trim()) {
+    return String(fromEnv).trim();
+  }
+  const base = path.basename(String(cwd || '').replace(/[/\\]+$/, ''));
+  return base || 'kanban';
+}
+
 function hashCwdToPort(cwd = process.cwd()) {
   let hash = 0;
   const input = String(cwd);
@@ -79,11 +88,13 @@ async function writeGuiPortFile({ port, pid = process.pid } = {}) {
   }
 
   await ensureBacklogDir();
+  const cwd = process.cwd();
   const data = {
     port: normalizedPort,
     pid,
     url: `http://localhost:${normalizedPort}`,
-    cwd: process.cwd(),
+    cwd,
+    project: projectLabel(cwd),
     started_at: new Date().toISOString()
   };
   await fs.writeFile(guiPortFilePath(), JSON.stringify(data, null, 2), 'utf-8');
@@ -129,11 +140,13 @@ async function discoverRunningGui() {
     pid: info.pid,
     url: info.url || `http://localhost:${info.port}`,
     cwd: info.cwd,
+    project: info.project || projectLabel(info.cwd),
     started_at: info.started_at
   };
 }
 
 module.exports = {
+  projectLabel,
   hashCwdToPort,
   normalizeGuiPort,
   resolvePreferredGuiPort,