docs: update tool count 58 → 67, add epic documentation across all docs

Update tool counts across ~40 files for 9 new tools (8 epic tools +
tasks_reorder). Add epic tool reference, concepts guide, in-app help,
and prompt builder support. Update architecture docs, REST API docs,
site docs, and UI help content.

Author: prih

CLAUDE.md

@@ -4,7 +4,7 @@
 
 MCP server that builds a semantic graph memory from a project directory — indexing
 markdown docs, TypeScript/JavaScript source code, and all project files into six
-interconnected graphs. Exposes 58 MCP tools + REST API + Web UI.
+interconnected graphs. Exposes 67 MCP tools + REST API + Web UI.
 
 **Full documentation**: see [docs/](docs/README.md)
 

README.md

@@ -7,7 +7,7 @@
 
 An MCP server that builds a **semantic graph memory** from a project directory.
 Indexes markdown docs, TypeScript/JavaScript source code, and all project files into graph structures,
-then exposes them as **58 MCP tools** + **REST API** + **Web UI**.
+then exposes them as **67 MCP tools** + **REST API** + **Web UI**.
 
 ![graphmemory dashboard](docs/img/dashboard-dark.png)
 
@@ -131,7 +131,7 @@ See [docs/docker.md](docs/docker.md) for details.
 | **Workspaces** | Share knowledge/tasks/skills across related projects |
 | **Auth & ACL** | Password login (JWT), API keys, OAuth 2.0 (PKCE), 4-level access control |
 
-## 58 MCP tools
+## 67 MCP tools
 
 | Group | Tools |
 |-------|-------|
@@ -140,7 +140,8 @@ See [docs/docker.md](docs/docker.md) for details.
 | **Code** | `code_list_files`, `code_get_file_symbols`, `code_search`, `code_get_symbol`, `code_search_files` |
 | **Files** | `files_list`, `files_search`, `files_get_info` |
 | **Knowledge** | `notes_create`, `notes_update`, `notes_delete`, `notes_get`, `notes_list`, `notes_search`, `notes_create_link`, `notes_delete_link`, `notes_list_links`, `notes_find_linked`, `notes_add_attachment`, `notes_remove_attachment` |
-| **Tasks** | `tasks_create`, `tasks_update`, `tasks_delete`, `tasks_get`, `tasks_list`, `tasks_search`, `tasks_move`, `tasks_link`, `tasks_create_link`, `tasks_delete_link`, `tasks_find_linked`, `tasks_add_attachment`, `tasks_remove_attachment` |
+| **Tasks** | `tasks_create`, `tasks_update`, `tasks_delete`, `tasks_get`, `tasks_list`, `tasks_search`, `tasks_move`, `tasks_reorder`, `tasks_link`, `tasks_create_link`, `tasks_delete_link`, `tasks_find_linked`, `tasks_add_attachment`, `tasks_remove_attachment` |
+| **Epics** | `epics_create`, `epics_update`, `epics_delete`, `epics_get`, `epics_list`, `epics_search`, `epics_link_task`, `epics_unlink_task` |
 | **Skills** | `skills_create`, `skills_update`, `skills_delete`, `skills_get`, `skills_list`, `skills_search`, `skills_recall`, `skills_bump_usage`, `skills_link`, `skills_create_link`, `skills_delete_link`, `skills_find_linked`, `skills_add_attachment`, `skills_remove_attachment` |
 
 ## Web UI

SPEC.md

@@ -22,7 +22,7 @@ access control, and real-time updates.
 
 See [docs/graphs-overview.md](docs/graphs-overview.md) for data models, node IDs, and edge types.
 
-## 58 MCP tools
+## 67 MCP tools
 
 | Group | Count | Condition |
 |-------|-------|-----------|
@@ -31,7 +31,8 @@ See [docs/graphs-overview.md](docs/graphs-overview.md) for data models, node IDs
 | Code | 5 | code enabled |
 | File index | 3 | always |
 | Knowledge | 12 | always |
-| Tasks | 13 | always |
+| Tasks | 14 | always |
+| Epics | 8 | task graph enabled |
 | Skills | 14 | always |
 
 See [docs/api-mcp.md](docs/api-mcp.md) for schemas and [docs/mcp-tools-guide.md](docs/mcp-tools-guide.md) for usage guide.

docs/README.md

@@ -43,7 +43,7 @@
 
 - [REST API](api-rest.md) — full endpoint reference
 - [REST API Patterns](api-patterns.md) — middleware chain, validation, auth, error handling, mutation serialization
-- [MCP Tools Reference](api-mcp.md) — all 58 MCP tools with input/output schemas
+- [MCP Tools Reference](api-mcp.md) — all 67 MCP tools with input/output schemas
 - [MCP Tools Guide](mcp-tools-guide.md) — detailed descriptions, when to use, best practices
 - [WebSocket](api-websocket.md) — real-time event types and format
 

docs/api-mcp.md

@@ -2,7 +2,7 @@
 
 **Files**: `src/api/index.ts`, `src/api/tools/`
 
-58 MCP tools exposed via HTTP transport.
+67 MCP tools exposed via HTTP transport.
 
 ## Authentication
 
@@ -33,7 +33,8 @@ The set of tools registered for an MCP session depends on:
 | Code | 5 | code graph enabled | `tools/code/` |
 | File index | 3 | file index enabled | `tools/file-index/` |
 | Knowledge | 12 | knowledge graph enabled | `tools/knowledge/` |
-| Tasks | 13 | task graph enabled | `tools/tasks/` |
+| Tasks | 14 | task graph enabled | `tools/tasks/` |
+| Epics | 8 | task graph enabled | `tools/epics/` |
 | Skills | 14 | skill graph enabled | `tools/skills/` |
 
 ## Context tool
@@ -121,6 +122,22 @@ Requires both DocGraph and CodeGraph to be enabled. Bridges code definitions wit
 | `tasks_find_linked` | `targetId`, `targetGraph` + optional `kind`, `projectId` | `[{ taskId, title, kind, status, priority, tags }]` |
 | `tasks_add_attachment` | `taskId`, `filePath` (absolute path on disk) | `{ filename, mimeType, size, addedAt }` |
 | `tasks_remove_attachment` | `taskId`, `filename` | `{ deleted: filename }` |
+| `tasks_reorder` | `taskId`, `beforeId?`, `afterId?` | `{ taskId, order }` |
+
+## Epic tools
+
+Epics use the TaskGraph with a `nodeType: "epic"` discriminator. They group tasks via `belongs_to` edges.
+
+| Tool | Input | Output |
+|------|-------|--------|
+| `epics_create` | `title`, `description` + optional `status`, `priority`, `tags` | `{ epicId }` |
+| `epics_update` | `epicId` + optional `title`, `description`, `status`, `priority`, `tags`, `expectedVersion` | `{ epicId, updated }` |
+| `epics_delete` | `epicId` | `{ epicId, deleted }` |
+| `epics_get` | `epicId` | `{ id, title, description, status, priority, tags, tasks, createdAt, updatedAt }` |
+| `epics_list` | optional `status`, `priority`, `tag`, `filter`, `limit` | `[{ id, title, description, status, priority, tags, taskCount, createdAt, updatedAt }]` |
+| `epics_search` | `query` + optional `topK`, `maxResults`, `minScore`, `searchMode` | `[{ id, title, description, status, priority, tags, score }]` |
+| `epics_link_task` | `epicId`, `taskId` | `{ epicId, taskId, linked }` |
+| `epics_unlink_task` | `epicId`, `taskId` | `{ epicId, taskId, unlinked }` |
 
 ## Skill tools
 

docs/api-rest.md

@@ -83,6 +83,10 @@ See [Authentication](authentication.md) for details on auth middleware.
 | PUT | `/api/projects/:id/tasks/:taskId` | Update task (partial) |
 | DELETE | `/api/projects/:id/tasks/:taskId` | Delete task (204) |
 | POST | `/api/projects/:id/tasks/:taskId/move` | Move task status (body: `status`) |
+| POST | `/api/projects/:id/tasks/:taskId/reorder` | Reorder task (body: `beforeId?`, `afterId?`) |
+| POST | `/api/projects/:id/tasks/bulk/move` | Bulk move tasks (body: `taskIds`, `status`) |
+| POST | `/api/projects/:id/tasks/bulk/priority` | Bulk set priority (body: `taskIds`, `priority`) |
+| POST | `/api/projects/:id/tasks/bulk/delete` | Bulk delete tasks (body: `taskIds`) |
 | GET | `/api/projects/:id/tasks/search?q=...` | Search tasks |
 | POST | `/api/projects/:id/tasks/links` | Create task link |
 | DELETE | `/api/projects/:id/tasks/links` | Delete task link |
@@ -93,6 +97,20 @@ See [Authentication](authentication.md) for details on auth middleware.
 | GET | `/api/projects/:id/tasks/:taskId/attachments/:filename` | Download attachment |
 | DELETE | `/api/projects/:id/tasks/:taskId/attachments/:filename` | Delete attachment |
 
+## Epic endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/projects/:id/epics` | List epics (query: `status`, `priority`, `tag`, `filter`, `limit`) |
+| POST | `/api/projects/:id/epics` | Create epic (body: `title`, `description`, `priority`, `status`, `tags`) |
+| GET | `/api/projects/:id/epics/search?q=...` | Search epics |
+| GET | `/api/projects/:id/epics/:epicId` | Get epic (includes linked tasks) |
+| PUT | `/api/projects/:id/epics/:epicId` | Update epic (partial) |
+| DELETE | `/api/projects/:id/epics/:epicId` | Delete epic (204) |
+| POST | `/api/projects/:id/epics/:epicId/link` | Link task to epic (body: `taskId`) |
+| DELETE | `/api/projects/:id/epics/:epicId/link` | Unlink task from epic (body: `taskId`) |
+| GET | `/api/projects/:id/epics/:epicId/tasks` | List tasks belonging to epic |
+
 ## Skill endpoints
 
 | Method | Path | Description |

docs/architecture.md

@@ -57,7 +57,7 @@
      ┌────────┐   ┌──────────┐   ┌──────────┐
      │  MCP   │   │ REST API │   │    UI    │
      │ Tools  │   │ Express  │   │  React   │
-     │ (58)   │   │ + WS     │   │  + Vite  │
+     │ (67)   │   │ + WS     │   │  + Vite  │
      └────────┘   └──────────┘   └──────────┘
 ```
 
@@ -91,7 +91,7 @@ Entry point: `src/cli/index.ts` (Commander.js). Three main commands (`index`, `m
 
 Three interfaces to the graph layer:
 
-- **MCP Tools** (`src/api/tools/`) — 58 tools exposed via MCP protocol (HTTP)
+- **MCP Tools** (`src/api/tools/`) — 67 tools exposed via MCP protocol (HTTP)
 - **REST API** (`src/api/rest/`) — Express routes for CRUD + search
 - **WebSocket** (`src/api/rest/websocket.ts`) — real-time event push
 
@@ -165,7 +165,8 @@ src/
       docs/                  # 10 MCP doc tools
       code/                  # 5 MCP code tools
       knowledge/             # 12 MCP knowledge tools
-      tasks/                 # 13 MCP task tools
+      tasks/                 # 14 MCP task tools
+      epics/                 # 8 MCP epic tools
       skills/                # 14 MCP skill tools
       file-index/            # 3 MCP file index tools
       context/               # 1 MCP context tool

docs/concepts-tasks.md

@@ -156,6 +156,29 @@ Graph Memory tasks aren't meant to replace your project management tool. They se
 
 Think of them as **working memory** for the AI-human collaboration, not as a permanent project management system.
 
+## Task ordering
+
+Tasks support an `order` field for manual positioning within a status column. The ordering system uses **gap-based integers** — new tasks are assigned order values with large gaps (e.g. 1000, 2000, 3000) so that inserting between two tasks just picks the midpoint without renumbering siblings.
+
+The `tasks_reorder` tool repositions a task by specifying `beforeId` and/or `afterId` anchors. When gaps become too small, the system automatically renumbers all tasks in the column.
+
+## Epics and hierarchy
+
+Epics are higher-level groupings that organize related tasks into initiatives or milestones. They live in the same TaskGraph as tasks, distinguished by a `nodeType: "epic"` field.
+
+Tasks are linked to epics via `belongs_to` edges:
+
+```
+"implement-auth" → [belongs_to] → "q4-security-epic"
+"fix-session-bug" → [belongs_to] → "q4-security-epic"
+```
+
+Key properties:
+- A task can belong to at most one epic
+- Deleting an epic removes the `belongs_to` edges but does not delete the tasks
+- Epics have the same status and priority fields as tasks
+- `epics_get` returns the epic with its full task list
+
 ## Configuration
 
 ```yaml

docs/graph-tasks.md

@@ -24,6 +24,8 @@ Task tracking with kanban workflow, priorities, due dates, estimates, assignees,
 | `createdAt` | number | Epoch ms |
 | `updatedAt` | number | Epoch ms |
 | `createdBy` | string | Author |
+| `nodeType` | `"task"` \| `"epic"` | Discriminator (default `"task"`) |
+| `order` | number \| null | Manual sort position (gap-based integers) |
 | `updatedBy` | string | Author |
 | `proxyFor` | object | Present only on phantom proxy nodes |
 
@@ -52,6 +54,7 @@ Slug from title: `"implement-auth"`. Duplicates get `"implement-auth::2"`.
 | `subtask_of` | task → parent task |
 | `blocks` | task → blocked task |
 | `related_to` | free-form relation |
+| `belongs_to` | task → epic |
 
 ### Cross-graph links
 
@@ -123,6 +126,7 @@ See [File Mirror](file-mirror.md) for details.
 | `listTasks(opts)` | List with filters (status, priority, tag, assignee) |
 | `searchTasks(query, opts)` | Hybrid search with BFS expansion |
 | `moveTask(taskId, status)` | Change status, manage completedAt |
+| `reorderTask(taskId, opts)` | Reposition task (beforeId/afterId anchors) |
 
 ### Link operations
 
@@ -140,6 +144,19 @@ See [File Mirror](file-mirror.md) for details.
 | `addAttachment(taskId, filename, content)` | Add file attachment |
 | `removeAttachment(taskId, filename)` | Remove file attachment |
 
+### Epic operations
+
+| Method | Description |
+|--------|-------------|
+| `createEpic(fields)` | Create epic (nodeType: "epic"), embed, mirror |
+| `updateEpic(epicId, fields)` | Partial update, re-embed |
+| `deleteEpic(epicId)` | Delete epic and belongs_to edges (tasks preserved) |
+| `getEpic(epicId)` | Fetch epic with linked tasks list |
+| `listEpics(opts)` | List epics with filters |
+| `searchEpics(query, opts)` | Hybrid search over epics |
+| `linkTaskToEpic(epicId, taskId)` | Create belongs_to edge |
+| `unlinkTaskFromEpic(epicId, taskId)` | Remove belongs_to edge |
+
 ## Persistence
 
 Stored as `tasks.json` in the `graphMemory` directory. In workspaces, shared across member projects.

docs/graphs-overview.md

@@ -10,7 +10,7 @@ The system maintains multiple graph types, all built on **Graphology** (in-memor
 | **CodeGraph** | `code.json` | `CodeGraphManager` | AST symbols from TS/JS source |
 | **KnowledgeGraph** | `knowledge.json` | `KnowledgeGraphManager` | User/LLM-created notes and facts |
 | **FileIndexGraph** | `file-index.json` | `FileIndexGraphManager` | All project files and directories |
-| **TaskGraph** | `tasks.json` | `TaskGraphManager` | Tasks with kanban workflow |
+| **TaskGraph** | `tasks.json` | `TaskGraphManager` | Tasks and epics with kanban workflow |
 | **SkillGraph** | `skills.json` | `SkillGraphManager` | Reusable recipes and procedures |
 
 See individual graph pages for detailed documentation:
@@ -36,7 +36,7 @@ These graphs are populated automatically by the indexer scanning project files:
 These graphs are populated manually (by users or LLMs) via MCP tools or REST API:
 
 - **KnowledgeGraph** — notes, facts, decisions
-- **TaskGraph** — tasks, kanban boards
+- **TaskGraph** — tasks, epics, kanban boards
 - **SkillGraph** — recipes, procedures
 
 CRUD-only graphs also feature:
@@ -135,7 +135,7 @@ In workspaces, cross-graph links between projects use project-scoped proxy IDs:
 | CodeGraph | `"fileId"`, `"fileId::Symbol"`, `"fileId::Class::method"` | `"src/auth.ts"`, `"src/auth.ts::loginUser"` |
 | KnowledgeGraph | `"slug-from-title"`, `"slug::2"` | `"auth-uses-jwt"`, `"auth-uses-jwt::2"` |
 | FileIndexGraph | file path, dir path, `"."` | `"src/lib/config.ts"`, `"src/lib"`, `"."` |
-| TaskGraph | `"slug-from-title"`, `"slug::2"` | `"implement-auth"`, `"implement-auth::2"` |
+| TaskGraph | `"slug-from-title"`, `"slug::2"` (tasks and epics share IDs) | `"implement-auth"`, `"q4-auth-epic"` |
 | SkillGraph | `"slug-from-title"`, `"slug::2"` | `"add-rest-endpoint"`, `"add-rest-endpoint::2"` |
 
 Slug generation uses `slugify()` — lowercase, replace non-alphanumeric with hyphens, trim, deduplicate with `::2`, `::3`, etc.
@@ -148,6 +148,15 @@ The tokenizer splits on whitespace, punctuation, and camelCase (`getUserById` 
 
 See [Search](search.md) for the hybrid search algorithm.
 
+## Epics in TaskGraph
+
+Epics are stored in the same TaskGraph alongside tasks, distinguished by a `nodeType` field:
+
+- **Tasks** have `nodeType: "task"` (default)
+- **Epics** have `nodeType: "epic"`
+
+Tasks are linked to epics via `belongs_to` edges. Epics support an `order` field for positioning, using gap-based integers for efficient reordering without renumbering siblings. This shared-graph approach avoids a separate persistence file while keeping epics and tasks queryable together.
+
 ## Enabled/disabled graphs
 
 Each graph can be disabled in the config: