@gzmagyari/kanbanboard 1.0.0

package/API.md

@@ -0,0 +1,1256 @@
+# Kanban Dashboard — API Reference
+
+Base URL: `http://127.0.0.1:3000`
+
+All endpoints return JSON. All timestamps are Unix milliseconds.
+
+---
+
+## Table of Contents
+
+- [Health & Config](#health--config)
+- [Projects](#projects)
+- [Tasks](#tasks)
+- [Task Hierarchy](#task-hierarchy)
+- [Next Sub-ticket](#next-sub-ticket)
+- [Comments & Progress Updates](#comments--progress-updates)
+- [Automation Tasks](#automation-tasks)
+- [Automation Helpers](#automation-helpers)
+- [AI: Task Merge](#ai-task-merge)
+- [AI: Project Init](#ai-project-init)
+- [AI: Evolve Hierarchy](#ai-evolve-hierarchy)
+- [AI: Remove Concept](#ai-remove-concept)
+- [Error Handling](#error-handling)
+- [Object Schemas](#object-schemas)
+
+---
+
+## Health & Config
+
+### `GET /api/health`
+
+Basic liveness check.
+
+**Response** `200`
+```json
+{ "ok": true }
+```
+
+---
+
+### `GET /api/columns`
+
+Returns the valid status columns for tasks and automation tasks.
+
+**Response** `200`
+```json
+{
+  "taskColumns": [
+    { "key": "ideas", "name": "Ideas" },
+    { "key": "todo", "name": "To do" },
+    { "key": "in_progress", "name": "In Progress" },
+    { "key": "review", "name": "Review" },
+    { "key": "testing", "name": "Testing" },
+    { "key": "done", "name": "Done" }
+  ],
+  "autoColumns": [
+    { "key": "ideas", "name": "Ideas" },
+    { "key": "active", "name": "Active" }
+  ]
+}
+```
+
+---
+
+### `GET /api/ai/health`
+
+Returns LLM configuration status. No API key required.
+
+**Response** `200`
+```json
+{
+  "enabled": true,
+  "base_url": "https://openrouter.ai/api/v1",
+  "model": "google/gemini-3-pro-preview",
+  "api_key_required": false,
+  "rate_limit_per_min": 60
+}
+```
+
+---
+
+## Projects
+
+### `GET /api/projects`
+
+Lists all projects with task and automation counts.
+
+**Response** `200`
+```json
+{
+  "projects": [
+    {
+      "id": "default",
+      "name": "Default",
+      "scope_text": "",
+      "created_at": 1770500000000,
+      "updated_at": 1770500000000,
+      "task_count": 42,
+      "automation_count": 2
+    }
+  ]
+}
+```
+
+---
+
+### `POST /api/projects`
+
+Creates a new project.
+
+**Request**
+```json
+{
+  "name": "My Project",
+  "scope_text": "A web application for managing widgets."
+}
+```
+
+| Field | Type | Required | Default |
+|-------|------|----------|---------|
+| `name` | string | yes | — |
+| `scope_text` | string | no | `""` |
+
+**Response** `201`
+```json
+{
+  "project": {
+    "id": "pH1ZSGuW5i",
+    "name": "My Project",
+    "scope_text": "A web application for managing widgets.",
+    "created_at": 1770572000000,
+    "updated_at": 1770572000000
+  }
+}
+```
+
+**Errors**
+- `400` — `name` is missing or empty
+
+---
+
+### `GET /api/projects/:id`
+
+Returns a single project.
+
+**Example** `GET /api/projects/pH1ZSGuW5i`
+
+**Response** `200`
+```json
+{
+  "project": {
+    "id": "pH1ZSGuW5i",
+    "name": "My Project",
+    "scope_text": "A web application for managing widgets.",
+    "created_at": 1770572000000,
+    "updated_at": 1770572000000
+  }
+}
+```
+
+**Errors**
+- `404` — project not found
+
+---
+
+### `PATCH /api/projects/:id`
+
+Updates a project's name and/or scope.
+
+**Request**
+```json
+{
+  "name": "Renamed Project",
+  "scope_text": "Updated scope description."
+}
+```
+
+All fields are optional. Only provided fields are updated.
+
+**Response** `200` — same shape as GET
+
+**Errors**
+- `404` — project not found
+- `400` — name is empty string
+
+---
+
+### `DELETE /api/projects/:id`
+
+Deletes a project. All tasks in the project are reassigned to the `default` project first.
+
+**Response** `200`
+```json
+{ "ok": true }
+```
+
+**Errors**
+- `400` — cannot delete the default project
+- `404` — project not found
+
+---
+
+## Tasks
+
+### `GET /api/tasks`
+
+Lists tasks with optional filters.
+
+**Query Parameters**
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `status` | string | Filter by status (e.g. `todo`, `in_progress`) |
+| `project_id` | string | Filter by project |
+| `parent_id` | string | Filter by parent. Use `null` or empty for root tasks |
+| `include_deleted` | boolean | Include soft-deleted tasks. Default `false` |
+
+**Example** `GET /api/tasks?project_id=pH1ZSGuW5i&status=todo`
+
+**Response** `200`
+```json
+{
+  "tasks": [
+    {
+      "id": "bY0pcKdSUx",
+      "title": "Root Task",
+      "description": "A root-level task",
+      "status": "todo",
+      "detail_text": "",
+      "created_at": 1770572611089,
+      "updated_at": 1770572611089,
+      "project_id": "pH1ZSGuW5i",
+      "parent_id": null,
+      "deleted_at": null
+    }
+  ]
+}
+```
+
+**Errors**
+- `400` — invalid status or project_id
+
+---
+
+### `POST /api/tasks`
+
+Creates a new task.
+
+**Request**
+```json
+{
+  "title": "Implement login page",
+  "description": "Build the login form with email/password fields",
+  "status": "todo",
+  "detail_text": "Use Vuetify form components...",
+  "project_id": "pH1ZSGuW5i",
+  "parent_id": "bY0pcKdSUx"
+}
+```
+
+| Field | Type | Required | Default |
+|-------|------|----------|---------|
+| `title` | string | yes | — |
+| `description` | string | no | `""` |
+| `status` | string | no | `"todo"` |
+| `detail_text` | string | no | `""` |
+| `project_id` | string | no | `"default"` |
+| `parent_id` | string | no | `null` |
+
+**Response** `201`
+```json
+{
+  "task": {
+    "id": "OnXAVEF7D1",
+    "title": "Implement login page",
+    "description": "Build the login form with email/password fields",
+    "status": "todo",
+    "detail_text": "Use Vuetify form components...",
+    "created_at": 1770572617938,
+    "updated_at": 1770572617938,
+    "project_id": "pH1ZSGuW5i",
+    "parent_id": "bY0pcKdSUx",
+    "deleted_at": null
+  }
+}
+```
+
+**Side effects**
+- Parent task's `updated_at` is bumped when `parent_id` is set
+
+**Errors**
+- `400` — missing title, invalid status, project not found, parent not found or in different project
+
+---
+
+### `GET /api/tasks/:id`
+
+Returns a task with its comments and progress updates.
+
+**Example** `GET /api/tasks/bY0pcKdSUx`
+
+**Response** `200`
+```json
+{
+  "task": { "...": "task object" },
+  "comments": [
+    {
+      "id": 4,
+      "entity_type": "task",
+      "entity_id": "bY0pcKdSUx",
+      "author": "Gabor",
+      "text": "This is a test comment",
+      "created_at": 1770572931850
+    }
+  ],
+  "updates": [
+    {
+      "id": 299,
+      "entity_type": "task",
+      "entity_id": "bY0pcKdSUx",
+      "author": "Jarvis",
+      "text": "Progress: 50% complete",
+      "created_at": 1770572935085
+    }
+  ]
+}
+```
+
+Updates are capped at 50 most recent, ordered newest first.
+
+**Errors**
+- `404` — task not found or soft-deleted
+
+---
+
+### `PATCH /api/tasks/:id`
+
+Updates a task. Only provided fields are changed.
+
+**Request**
+```json
+{
+  "title": "Updated title",
+  "status": "in_progress",
+  "parent_id": "bY0pcKdSUx",
+  "project_id": "pH1ZSGuW5i"
+}
+```
+
+All fields are optional.
+
+**Validation rules**
+- `parent_id` cannot be the task itself (`400`)
+- `parent_id` cannot create a cycle — i.e. cannot set parent to own descendant (`400`)
+- `parent_id` must be in the same project (`400`)
+- Changing `project_id` detaches the task from its parent (sets `parent_id = null`)
+
+**Response** `200` — returns updated task object
+
+**Errors**
+- `404` — task not found
+- `400` — invalid status, self-referencing parent, cycle detected, project mismatch
+
+---
+
+### `DELETE /api/tasks/:id`
+
+Hard-deletes a task and its entire subtree (all descendants, comments, and updates).
+
+**Example** `DELETE /api/tasks/tRYxSsybNq`
+
+**Response** `200`
+```json
+{ "ok": true }
+```
+
+**Errors**
+- `404` — task not found
+
+---
+
+## Task Hierarchy
+
+### `GET /api/tasks/:id/ancestors`
+
+Returns the ancestor path from root down to (optionally including) the task.
+
+**Query Parameters**
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `include_self` | boolean | `false` | Include the task itself at the end of the path |
+
+**Example** `GET /api/tasks/dzUFSKZQRr/ancestors?include_self=1`
+
+**Response** `200`
+```json
+{
+  "path": [
+    {
+      "id": "bY0pcKdSUx",
+      "title": "Root Task",
+      "status": "in_progress",
+      "parent_id": null,
+      "depth": 2,
+      "...": "other task fields"
+    },
+    {
+      "id": "OnXAVEF7D1",
+      "title": "Child Task",
+      "parent_id": "bY0pcKdSUx",
+      "depth": 1,
+      "...": "..."
+    },
+    {
+      "id": "dzUFSKZQRr",
+      "title": "Grandchild Task",
+      "parent_id": "OnXAVEF7D1",
+      "depth": 0,
+      "...": "..."
+    }
+  ]
+}
+```
+
+Path is ordered root → leaf. `depth` counts distance from the target task (0 = self).
+
+**Errors**
+- `404` — task not found
+
+---
+
+### `GET /api/tasks/:id/descendants`
+
+Returns all descendants of a task.
+
+**Query Parameters**
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `mode` | string | `"flat"` | `"flat"` for a flat list, `"tree"` for nested structure |
+| `include_self` | boolean | `false` | Include the root task itself |
+
+**Example (flat)** `GET /api/tasks/bY0pcKdSUx/descendants?mode=flat`
+
+**Response** `200`
+```json
+{
+  "descendants": [
+    {
+      "id": "OnXAVEF7D1",
+      "title": "Child Task",
+      "parent_id": "bY0pcKdSUx",
+      "depth": 1,
+      "...": "..."
+    },
+    {
+      "id": "dzUFSKZQRr",
+      "title": "Grandchild Task",
+      "parent_id": "OnXAVEF7D1",
+      "depth": 2,
+      "...": "..."
+    }
+  ]
+}
+```
+
+**Example (tree)** `GET /api/tasks/bY0pcKdSUx/descendants?mode=tree`
+
+**Response** `200`
+```json
+{
+  "tree": {
+    "task": { "id": "bY0pcKdSUx", "title": "Root Task", "...": "..." },
+    "depth": 0,
+    "children": [
+      {
+        "task": { "id": "OnXAVEF7D1", "title": "Child Task", "...": "..." },
+        "depth": 1,
+        "children": [
+          {
+            "task": { "id": "dzUFSKZQRr", "title": "Grandchild Task", "...": "..." },
+            "depth": 2,
+            "children": []
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Errors**
+- `404` — task not found
+
+---
+
+### `GET /api/tasks/:id/context`
+
+Returns a full context bundle for a task: project info, ancestor path, children, and a rendered text summary suitable for LLM consumption.
+
+**Example** `GET /api/tasks/OnXAVEF7D1/context`
+
+**Response** `200`
+```json
+{
+  "project": { "id": "pH1ZSGuW5i", "name": "My Project", "...": "..." },
+  "path": [
+    { "id": "bY0pcKdSUx", "title": "Root Task", "depth": 1, "...": "..." }
+  ],
+  "task": { "id": "OnXAVEF7D1", "title": "Child Task", "...": "..." },
+  "children": [
+    { "id": "dzUFSKZQRr", "title": "Grandchild Task", "...": "..." }
+  ],
+  "agent_instructions": "Project: My Project (#pH1ZSGuW5i)\n\nProject scope:\n...\n\nTicket path (root -> selected):\n- [in_progress] Root Task (#bY0pcKdSUx)\n\nSelected ticket details:\nTitle: Child Task\n..."
+}
+```
+
+**Errors**
+- `404` — task not found
+
+---
+
+## Next Sub-ticket
+
+### `POST /api/tasks/:id/next`
+
+Picks the next best leaf sub-ticket to work on. Supports heuristic (local sort) or LLM-powered selection.
+
+**Request**
+```json
+{
+  "strategy": "auto",
+  "exclude_status": ["done"],
+  "prefer_status": ["in_progress", "todo", "review", "testing", "ideas"],
+  "max_candidates": 40
+}
+```
+
+| Field | Type | Required | Default |
+|-------|------|----------|---------|
+| `strategy` | string | no | `"auto"` — uses LLM if available, falls back to heuristic |
+| `exclude_status` | string or string[] | no | `["done"]` |
+| `prefer_status` | string or string[] | no | `["in_progress","todo","review","testing","ideas"]` |
+| `max_candidates` | number | no | `40` |
+
+**Strategy options**
+- `"auto"` — tries LLM first, falls back to heuristic on failure
+- `"llm"` — always uses LLM (fails if LLM unavailable)
+- `"heuristic"` — never uses LLM; sorts by prefer_status order then oldest first
+
+**Response** `200` (task found)
+```json
+{
+  "selected": {
+    "id": "dzUFSKZQRr",
+    "title": "Grandchild Task",
+    "status": "todo",
+    "...": "..."
+  },
+  "strategy": "llm",
+  "rationale": "The database schema is the foundational dependency...",
+  "llm_run_id": "abc123",
+  "candidate_count": 5,
+  "context": {
+    "project": { "...": "..." },
+    "path": [ "..." ],
+    "task": { "...": "..." },
+    "children": [ "..." ],
+    "agent_instructions": "..."
+  }
+}
+```
+
+**Response** `200` (no candidates)
+```json
+{
+  "selected": null,
+  "strategy": "none",
+  "rationale": "No leaf sub-tickets found...",
+  "candidate_count": 0
+}
+```
+
+**Errors**
+- `404` — task not found
+
+---
+
+## Comments & Progress Updates
+
+### `POST /api/tasks/:id/comments`
+
+Adds a comment to a task.
+
+**Request**
+```json
+{
+  "text": "Need to clarify requirements with stakeholder",
+  "author": "Gabor"
+}
+```
+
+| Field | Type | Required | Default |
+|-------|------|----------|---------|
+| `text` | string | yes | — |
+| `author` | string | no | `"Gabor"` |
+
+**Response** `201`
+```json
+{
+  "comment": {
+    "id": 4,
+    "entity_type": "task",
+    "entity_id": "bY0pcKdSUx",
+    "author": "Gabor",
+    "text": "Need to clarify requirements with stakeholder",
+    "created_at": 1770572931850
+  }
+}
+```
+
+**Side effects** — bumps the task's `updated_at`
+
+**Errors**
+- `404` — task not found
+- `400` — `text` is missing
+
+---
+
+### `POST /api/tasks/:id/updates`
+
+Adds a progress update to a task.
+
+**Request**
+```json
+{
+  "text": "Completed the database schema migration",
+  "author": "Jarvis"
+}
+```
+
+| Field | Type | Required | Default |
+|-------|------|----------|---------|
+| `text` | string | yes | — |
+| `author` | string | no | `"Jarvis"` |
+
+**Response** `201`
+```json
+{
+  "update": {
+    "id": 299,
+    "entity_type": "task",
+    "entity_id": "bY0pcKdSUx",
+    "author": "Jarvis",
+    "text": "Completed the database schema migration",
+    "created_at": 1770572935085
+  }
+}
+```
+
+**Side effects** — bumps the task's `updated_at`
+
+**Errors**
+- `404` — task not found
+- `400` — `text` is missing
+
+---
+
+## Automation Tasks
+
+Automation tasks come in two types: `recurring` (cron-based) and `scheduled` (one-shot at a specific time).
+
+### `GET /api/automation/:type`
+
+Lists automation tasks of a given type.
+
+**URL parameters** — `:type` is `recurring` or `scheduled`
+
+**Query Parameters**
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `status` | string | Filter by status (`ideas` or `active`) |
+| `project_id` | string | Filter by project |
+
+**Example** `GET /api/automation/recurring?status=active`
+
+**Response** `200`
+```json
+{
+  "tasks": [
+    {
+      "id": "44d4003vU2",
+      "type": "recurring",
+      "title": "Weekly Review",
+      "description": "Review all tasks weekly",
+      "status": "active",
+      "detail_text": "",
+      "project_id": "pH1ZSGuW5i",
+      "schedule_kind": "cron",
+      "expr": "0 9 * * 1",
+      "tz": "America/New_York",
+      "at_iso": null,
+      "cron_job_id": null,
+      "cron_enabled": 1,
+      "last_synced_at": null,
+      "last_sync_error": null,
+      "created_at": 1770572993713,
+      "updated_at": 1770573019024
+    }
+  ]
+}
+```
+
+---
+
+### `POST /api/automation/:type`
+
+Creates a new automation task.
+
+**URL parameters** — `:type` is `recurring` or `scheduled`
+
+**Request (recurring/cron)**
+```json
+{
+  "title": "Weekly Review",
+  "description": "Review all tasks weekly",
+  "schedule_kind": "cron",
+  "expr": "0 9 * * 1",
+  "tz": "America/New_York",
+  "project_id": "pH1ZSGuW5i"
+}
+```
+
+**Request (scheduled/at)**
+```json
+{
+  "title": "Deploy Release",
+  "description": "Deploy v2.0 release",
+  "schedule_kind": "at",
+  "at_iso": "2026-03-01T10:00:00Z",
+  "project_id": "pH1ZSGuW5i"
+}
+```
+
+| Field | Type | Required | Default | Notes |
+|-------|------|----------|---------|-------|
+| `title` | string | yes | — | |
+| `description` | string | no | `""` | |
+| `status` | string | no | `"ideas"` | Must be `ideas` or `active` |
+| `detail_text` | string | no | `""` | |
+| `project_id` | string | no | `"default"` | |
+| `schedule_kind` | string | yes | — | `"cron"` or `"at"` |
+| `expr` | string | if cron | — | Cron expression (e.g. `0 9 * * 1`) |
+| `tz` | string | if cron | — | Timezone (e.g. `America/New_York`) |
+| `at_iso` | string | if at | — | ISO 8601 datetime |
+
+**Constraints**
+- Recurring tasks must use `schedule_kind: "cron"` (cannot use `"at"`)
+
+**Response** `201` — returns the automation task object
+
+**Errors**
+- `400` — missing required fields, invalid schedule_kind, recurring with `at` kind
+
+---
+
+### `GET /api/automation/:type/:id`
+
+Returns an automation task with its comments and updates.
+
+**Example** `GET /api/automation/recurring/44d4003vU2`
+
+**Response** `200`
+```json
+{
+  "task": { "...": "automation task object" },
+  "comments": [ "..." ],
+  "updates": [ "..." ]
+}
+```
+
+**Errors**
+- `404` — task not found
+- `400` — invalid type
+
+---
+
+### `PATCH /api/automation/:type/:id`
+
+Updates an automation task. Only provided fields are changed.
+
+**Request**
+```json
+{
+  "title": "Updated Weekly Review",
+  "status": "active",
+  "expr": "0 10 * * 1"
+}
+```
+
+All fields are optional. Schedule fields (`schedule_kind`, `expr`, `tz`, `at_iso`) are re-validated together when any of them change.
+
+**Special behavior**
+- Setting `status: "ideas"` automatically sets `cron_enabled: 0`
+- Setting `status: "active"` automatically sets `cron_enabled: 1`
+
+**Additional fields** (for sync agent use)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `cron_job_id` | string | External cron service job ID |
+| `cron_enabled` | boolean | Whether cron is enabled |
+| `last_synced_at` | number | Last sync timestamp (ms) |
+| `last_sync_error` | string | Last sync error message |
+
+**Response** `200` — returns updated automation task object
+
+**Errors**
+- `404` — task not found
+- `400` — invalid type, status, or schedule
+
+---
+
+### `DELETE /api/automation/:type/:id`
+
+Deletes an automation task and its comments/updates.
+
+**Response** `200`
+```json
+{ "ok": true }
+```
+
+**Errors**
+- `404` — task not found
+- `400` — invalid type
+
+---
+
+### `POST /api/automation/:type/:id/comments`
+
+Adds a comment to an automation task. Same interface as task comments.
+
+**Request**
+```json
+{
+  "text": "Adjusted schedule to run at 10am",
+  "author": "Gabor"
+}
+```
+
+**Response** `201` — comment object with `entity_type` set to `"recurring"` or `"scheduled"`
+
+---
+
+### `POST /api/automation/:type/:id/updates`
+
+Adds a progress update to an automation task. Same interface as task updates.
+
+**Request**
+```json
+{
+  "text": "Synced with cron-job.org successfully",
+  "author": "Jarvis"
+}
+```
+
+**Response** `201` — update object with `entity_type` set to `"recurring"` or `"scheduled"`
+
+---
+
+## Automation Helpers
+
+These endpoints are designed for the external sync agent.
+
+### `GET /api/automation-active`
+
+Returns all automation tasks with `status = 'active'` (both recurring and scheduled).
+
+**Response** `200`
+```json
+{
+  "tasks": [ "...automation task objects..." ]
+}
+```
+
+---
+
+### `GET /api/automation-sync-snapshot`
+
+Returns all automation tasks (regardless of status) for full sync.
+
+**Response** `200`
+```json
+{
+  "tasks": [ "...automation task objects..." ]
+}
+```
+
+---
+
+## AI: Task Merge
+
+### `POST /api/ai/tasks/merge`
+
+Creates a new task from a natural-language description. The LLM enhances the title/description and optionally breaks it down into sub-tasks.
+
+**Request**
+```json
+{
+  "text": "Implement user authentication with login, registration, and password reset",
+  "project_id": "pH1ZSGuW5i",
+  "breakdown": true,
+  "max_depth": 2,
+  "status": "todo",
+  "parent_id": "bY0pcKdSUx",
+  "apply": true
+}
+```
+
+| Field | Type | Required | Default | Notes |
+|-------|------|----------|---------|-------|
+| `text` | string | yes | — | Natural-language task description |
+| `project_id` | string | no | `"default"` | |
+| `breakdown` | boolean | no | `false` | Create sub-tasks |
+| `max_depth` | number | no | `3` | Max nesting depth (1–6) |
+| `status` | string | no | `"todo"` | Root task status |
+| `parent_id` | string | no | `null` | Attach under existing task |
+| `apply` | boolean | no | `true` | `false` for dry-run |
+
+**Response (apply=true)** `200`
+```json
+{
+  "plan_id": "QyOvX8gckSoR",
+  "llm_run_id": "abc123def456",
+  "applied": true,
+  "rationale": "Created task with 6 sub-tasks covering backend and frontend...",
+  "root_task": {
+    "id": "LkpwlcsGpj",
+    "title": "Implement User Authentication System",
+    "description": "Full authentication system with login, registration...",
+    "status": "todo",
+    "parent_id": null,
+    "project_id": "pH1ZSGuW5i",
+    "...": "..."
+  },
+  "created_tasks": [
+    { "id": "LkpwlcsGpj", "title": "Implement User Authentication System", "parent_id": null, "...": "..." },
+    { "id": "6eQIP0ar3U", "title": "Backend: User Database Schema", "parent_id": "LkpwlcsGpj", "...": "..." },
+    { "id": "xUGDlxxdnP", "title": "Backend: Auth API Endpoints", "parent_id": "LkpwlcsGpj", "...": "..." }
+  ]
+}
+```
+
+**Response (apply=false, dry-run)** `200`
+```json
+{
+  "plan_id": "vdZScM0uu4It",
+  "llm_run_id": "abc123def456",
+  "applied": false,
+  "plan": {
+    "actions": [
+      {
+        "type": "create_task",
+        "temp_id": "t0",
+        "title": "Implement Dark Mode Support",
+        "description": "Add a global dark mode toggle...",
+        "detail_text": "",
+        "status": "todo",
+        "parent_id": null,
+        "parent_temp_id": null
+      },
+      {
+        "type": "create_task",
+        "temp_id": "t1",
+        "title": "Theme Configuration Store",
+        "parent_temp_id": "t0",
+        "...": "..."
+      }
+    ],
+    "root_temp_id": "t0",
+    "rationale": "Breaking down into theme store, component updates, and toggle UI..."
+  }
+}
+```
+
+**Errors**
+- `400` — missing `text`, invalid status/project/parent, LLM not enabled
+- `502` — LLM response parsing failure
+
+---
+
+## AI: Project Init
+
+### `POST /api/ai/projects/:id/init`
+
+Scans a local repository and generates a project scope description. Optionally creates seed tasks.
+
+**Request**
+```json
+{
+  "path": "c:/xampp/htdocs/KanbanDashboard",
+  "create_seed_tasks": true,
+  "max_depth": 3,
+  "apply": true
+}
+```
+
+| Field | Type | Required | Default | Notes |
+|-------|------|----------|---------|-------|
+| `path` | string | yes | — | Local filesystem path to scan |
+| `create_seed_tasks` | boolean | no | `false` | Generate initial tasks |
+| `max_depth` | number | no | `3` | Max task nesting (1–6) |
+| `apply` | boolean | no | `true` | `false` for dry-run |
+
+**Path restrictions** — controlled by environment variables:
+- `AI_INIT_ALLOWED_ROOTS` — comma-separated list of allowed root paths
+- `AI_INIT_ALLOW_ANY=1` — allow any path (for development)
+
+**Response (apply=true)** `200`
+```json
+{
+  "plan_id": "abc123",
+  "llm_run_id": "def456",
+  "applied": true,
+  "project": {
+    "id": "pH1ZSGuW5i",
+    "name": "My Project",
+    "scope_text": "# Jarvis Kanban Dashboard\n\nAn intelligent task management system...",
+    "...": "..."
+  },
+  "scope_text": "# Jarvis Kanban Dashboard\n\nAn intelligent task management system...",
+  "created_tasks": [
+    { "id": "J8ijTp_Mr_", "title": "Implement Cron Sync Agent", "parent_id": null, "...": "..." },
+    { "id": "WUNcgBsi5r", "title": "Add Frontend Tests", "parent_id": null, "...": "..." }
+  ]
+}
+```
+
+The project's `scope_text` is updated in the database when `apply=true`.
+
+**Errors**
+- `404` — project not found
+- `400` — path not allowed, LLM not enabled
+- `502` — LLM response parsing failure
+
+---
+
+## AI: Evolve Hierarchy
+
+### `POST /api/ai/projects/:id/evolve`
+
+Proposes and optionally creates new tasks to advance a project toward a goal.
+
+**Request**
+```json
+{
+  "goal": "Add comprehensive error handling and logging across all API endpoints",
+  "max_depth": 3,
+  "max_new_tasks": 15,
+  "apply": true
+}
+```
+
+| Field | Type | Required | Default | Notes |
+|-------|------|----------|---------|-------|
+| `goal` | string | no | `""` | Direction for evolution |
+| `max_depth` | number | no | `3` | Max nesting (1–6) |
+| `max_new_tasks` | number | no | `15` | Max tasks to create (1–50) |
+| `apply` | boolean | no | `true` | `false` for dry-run |
+
+**Response (apply=true)** `200`
+```json
+{
+  "plan_id": "j527T-MwDM2a",
+  "llm_run_id": "abc123",
+  "applied": true,
+  "rationale": "Created error handling epic with 5 sub-tasks...",
+  "created_tasks": [
+    { "id": "3ACdJSHHJx", "title": "Implement Comprehensive Error Handling", "parent_id": null, "...": "..." },
+    { "id": "ePdlgfl6Ex", "title": "Backend: Integrate Structured Logger", "parent_id": "3ACdJSHHJx", "...": "..." }
+  ]
+}
+```
+
+New tasks default to `status: "ideas"`.
+
+**Response (apply=false)** `200`
+```json
+{
+  "plan_id": "qr-yO9eaQhGT",
+  "llm_run_id": "abc123",
+  "applied": false,
+  "plan": {
+    "actions": [ "...create_task actions..." ],
+    "rationale": "..."
+  }
+}
+```
+
+**Errors**
+- `404` — project not found
+- `400` — LLM not enabled
+- `502` — LLM response parsing failure
+
+---
+
+## AI: Remove Concept
+
+### `POST /api/ai/projects/:id/remove-concept`
+
+Uses the LLM to identify tasks related to a concept and either soft-deletes them or moves them to the Ideas column.
+
+**Request**
+```json
+{
+  "concept": "CI/CD pipeline",
+  "mode": "soft_delete",
+  "apply": true
+}
+```
+
+| Field | Type | Required | Default | Notes |
+|-------|------|----------|---------|-------|
+| `concept` | string | yes | — | The concept to remove |
+| `mode` | string | no | `"soft_delete"` | `"soft_delete"` or `"move_to_ideas"` |
+| `apply` | boolean | no | `true` | `false` for dry-run |
+
+**Response (apply=true)** `200`
+```json
+{
+  "plan_id": "cLO1xMRFvlKn",
+  "llm_run_id": "c_9np7nnEVBC",
+  "applied": true,
+  "rationale": "Removing the CI/CD task as requested...",
+  "affected_ids": ["8yNV7C0S4K"],
+  "affected_count": 1
+}
+```
+
+**Mode behavior**
+- `soft_delete` — sets `deleted_at` on matched tasks; they no longer appear in listings
+- `move_to_ideas` — sets `status = 'ideas'` on matched tasks
+
+**Errors**
+- `404` — project not found
+- `400` — missing concept, LLM not enabled
+- `502` — LLM response parsing failure
+
+---
+
+## Error Handling
+
+All errors return JSON:
+
+```json
+{ "error": "description of the error" }
+```
+
+**Status codes**
+
+| Code | Meaning |
+|------|---------|
+| `400` | Bad request — validation error, missing required field |
+| `401` | Unauthorized — invalid or missing `X-API-Key` (AI endpoints only, when configured) |
+| `404` | Not found — resource doesn't exist or is soft-deleted |
+| `429` | Rate limited — AI endpoint rate limit exceeded |
+| `502` | Bad gateway — LLM returned unparseable or invalid response |
+
+**API route guard** — any `GET /api/*` route that doesn't match a defined endpoint returns `404` JSON (not the SPA HTML fallback). Non-API routes serve the frontend.
+
+---
+
+## Object Schemas
+
+### Task
+
+```typescript
+{
+  id: string,           // nanoid
+  title: string,
+  description: string,
+  status: string,       // "ideas" | "todo" | "in_progress" | "review" | "testing" | "done"
+  detail_text: string,
+  project_id: string,
+  parent_id: string | null,
+  deleted_at: number | null,  // soft-delete timestamp (ms) or null
+  created_at: number,         // Unix ms
+  updated_at: number          // Unix ms
+}
+```
+
+### Automation Task
+
+```typescript
+{
+  id: string,
+  type: "recurring" | "scheduled",
+  title: string,
+  description: string,
+  status: string,                  // "ideas" | "active"
+  detail_text: string,
+  project_id: string,
+  schedule_kind: "cron" | "at",
+  expr: string | null,             // cron expression
+  tz: string | null,               // timezone
+  at_iso: string | null,           // ISO 8601 datetime
+  cron_job_id: string | null,      // external cron service ID
+  cron_enabled: 0 | 1,
+  last_synced_at: number | null,
+  last_sync_error: string | null,
+  created_at: number,
+  updated_at: number
+}
+```
+
+### Project
+
+```typescript
+{
+  id: string,
+  name: string,
+  scope_text: string,
+  created_at: number,
+  updated_at: number,
+  task_count?: number,        // only in GET /api/projects list
+  automation_count?: number   // only in GET /api/projects list
+}
+```
+
+### Comment
+
+```typescript
+{
+  id: number,
+  entity_type: "task" | "recurring" | "scheduled",
+  entity_id: string,
+  author: string,
+  text: string,
+  created_at: number
+}
+```
+
+### Progress Update
+
+```typescript
+{
+  id: number,
+  entity_type: "task" | "recurring" | "scheduled",
+  entity_id: string,
+  author: string,
+  text: string,
+  created_at: number
+}
+```