@loicngr/kobo 1.6.1 → 1.6.3

package/README.md

@@ -2,12 +2,8 @@
 
 > **Kōbō** (工房) — Japanese for *workshop*. A multi-workspace agent manager for [Claude Code](https://claude.com/claude-code).
 
-> [!WARNING]
-> 🚧 **Work in progress** — This project is under active development. Breaking changes may occur at any time.
-> ⚠️ **Planned refactor with potential data loss** — A major refactor is planned and may require database/schema changes that can cause data loss.
-> ❌ **Do not use in production** until this refactor is complete and a stable migration path is documented.
->
-> **Engine refactor in progress.** The legacy `agent-manager.ts` has been split into an agent engine abstraction (`src/server/services/agent/`) with a pluggable `AgentEngine` contract, a shared `Orchestrator`, and a normalised `AgentEvent` stream. The Claude Code CLI is now one engine among potentially several (`src/server/services/agent/engines/claude-code/`). A runtime migration (`content-migration-service.ts`) converts legacy `ws_events` into the new normalised form on first boot after upgrade; **a timestamped copy of `kobo.db` is written alongside it before the migration runs**, so you can roll back by restoring the backup if anything goes sideways. Expect continued churn until the WebSocket event surface and UI stream reducers stabilise.
+> [!NOTE]
+> 🚧 **Active development** — breaking changes may still land on `develop`. The database layer ships with forward-only migrations and a timestamped pre-migration backup of `kobo.db` before any schema change, so upgrades preserve your data even across invasive refactors.
 
 Kōbō lets you delegate multiple coding missions to Claude Code agents in parallel. Each workspace lives in its own isolated git worktree with its own branch, its own Claude session, optionally its own dev server, and a custom MCP tools server the agent uses to track progress. A Vue 3 dashboard shows live agent output, tasks, acceptance criteria, and git state across every workspace.
 
@@ -16,25 +12,31 @@ Think of it as an apprentice's hall: you hand out missions, each apprentice sets
 ## Features
 
 - **Isolated git worktrees** — every workspace runs on its own branch in its own directory, so concurrent Claude sessions never step on each other
-- **Live agent output** — stream `stdout`/`stderr` from Claude Code to the browser via WebSocket, with persisted event replay on reconnect
+- **Pluggable agent engine** — Kōbō talks to agents through an `AgentEngine` contract with a normalised `AgentEvent` stream (`src/server/services/agent/engines/`). Claude Code is the first engine; dropping in another runtime (e.g. the Claude Agent SDK) only requires a new adapter, not a rewrite of the UI or orchestration layer
+- **Rich chat feed** — live streaming text, thinking blocks, inline tool calls with expandable diffs for Edit/Write, per-turn session cards, markdown rendering, jump-to-previous-user-message button, and infinite scroll-up over persisted history
 - **Task & acceptance criteria tracking** — the agent reports progress through a dedicated MCP server (`kobo-tasks`) that reads and updates tasks directly from the SQLite database
+- **Documents panel** — tree view in the right drawer that surfaces every AI-generated markdown file under `docs/plans/`, `docs/superpowers/`, and `.ai/thoughts/`. Paths mentioned in chat messages are auto-detected against the catalogue and become one-click deep-links into the panel
+- **Git panel with inline diff viewer** — Monaco-powered side-by-side / inline diff of the working branch against its source, with file tree (same q-tree as Documents), inline rebase/merge conflict resolution, and a clean action bar: `Sync` split-button (pull / rebase / merge), `Push`, `Diff`, `Create PR`
 - **Notion integration** — pull workspace missions straight from Notion pages, extract markdown, and use it as the source of truth for acceptance criteria
 - **Sentry integration** — paste a Sentry issue URL to spin up a dedicated "fix workspace" with the stacktrace, tags, and offending spans written to `.ai/thoughts/SENTRY-<id>.md`; the agent is primed with a TDD fix workflow and has access to the Sentry MCP tools for deeper digging
 - **Per-workspace dev servers** — start/stop Docker or Node dev servers scoped to each branch, with log streaming
 - **Conventional-commit enforcement** — project-level git conventions are written to `.ai/.git-conventions.md` inside every workspace so Claude follows them during commits
-- **Pull request automation** — one-click `push`, `pull`, and `open-pr` endpoints integrate with the GitHub CLI, using a configurable prompt template
+- **Pull request automation** — one-click `push`, `pull`, `open-pr`, and "change PR base" endpoints integrate with the GitHub CLI, using a configurable prompt template
 - **Multi-session support** — create multiple Claude agent sessions per workspace, each with its own chat history; resume completed sessions via `--resume`; sessions are named and persisted in localStorage
 - **Prompt templates** — personal library of reusable prompts with variable substitution (`{working_branch}`, `{commit_count}`, etc.), insertable from the chat input via `/` autocomplete; editable in Settings > Templates
-- **Plan browser** — read-only viewer for markdown plan files produced by agents, rendered directly in the right-side panel
+- **Favorites and tags** — pin workspaces to the top via right-click favourite, organise with per-workspace tags filterable from the sidebar; a global tag catalogue keeps colours consistent across workspaces
+- **Health panel + config export/import** — inspect backend health (agent sessions, migration state, dev servers, DB size) and roundtrip your Kōbō config (settings, templates, skills) between machines via JSON
+- **Usage tracking** — rolling input/output token counts and cost estimates per workspace, aggregated across sessions and live-updated from `usage` events
+- **Resizable right drawer** — drag-to-resize horizontally and vertically, with tab state and split ratio persisted to localStorage
 - **Soft interrupt** — pause an agent mid-execution (SIGINT, like pressing Escape in Claude Code) without killing the process; the agent stops the current tool and waits for the next message
 - **Archive instead of delete** — soft-remove workspaces without losing the worktree, branches, or history; unarchive restores the exact pre-archive state
 
 ## Tech stack
 
 - **Backend** — Node.js ≥ 20, [Hono](https://hono.dev/), [better-sqlite3](https://github.com/WiseLibs/better-sqlite3), [ws](https://github.com/websockets/ws), [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk)
-- **Frontend** — [Vue 3](https://vuejs.org/), [Quasar 2](https://quasar.dev/), [Pinia](https://pinia.vuejs.org/), `vue-router`
+- **Frontend** — [Vue 3](https://vuejs.org/), [Quasar 2](https://quasar.dev/), [Pinia](https://pinia.vuejs.org/), `vue-router`, [Monaco Editor](https://microsoft.github.io/monaco-editor/) (git diff viewer), `marked` + `dompurify` (markdown rendering)
 - **Tooling** — TypeScript, [Vitest](https://vitest.dev/), [Biome](https://biomejs.dev/) (lint + format), `tsx` for dev
-- **Storage** — single SQLite file (`~/.config/kobo/kobo.db` by default, overridable via `KOBO_HOME`) with WAL mode
+- **Storage** — single SQLite file (`~/.config/kobo/kobo.db` by default, overridable via `KOBO_HOME`) with WAL mode and forward-only migrations
 
 ## Quick start
 
@@ -51,7 +53,7 @@ Think of it as an apprentice's hall: you hand out missions, each apprentice sets
 ### Run via `npx` (recommended)
 
 ```bash
-PORT=9999 npx @loicngr/kobo@latest
+SERVER_PORT=9998 PORT=9999 npx @loicngr/kobo@latest
 ```
 
 That's it. npm downloads the package, installs dependencies, starts the Kōbō server on the port you specified, and serves the web UI at `http://localhost:9999`. Data is persisted to `~/.config/kobo/` (overridable via `KOBO_HOME`).
@@ -244,10 +246,10 @@ See [`AGENTS.md`](./AGENTS.md) for a deeper dive into conventions, data model, W
 
 | Table | Purpose |
 |---|---|
-| `workspaces` | the unit of work — branch, status, Notion link, model, `archived_at`, … |
+| `workspaces` | the unit of work — branch, status, model, engine, `archived_at`, `favorited_at`, `tags`, Notion link, … |
 | `tasks` | workspace sub-items — tasks and acceptance criteria |
-| `agent_sessions` | Claude Code CLI invocations — `claude_session_id`, pid, lifecycle |
-| `ws_events` | persisted WebSocket events for replay on reconnect |
+| `agent_sessions` | agent runs — pid, `engine_session_id`, lifecycle |
+| `ws_events` | persisted WebSocket events (chat history, `agent:event` stream, user messages) for replay on reconnect |
 
 ## MCP server
 
@@ -274,7 +276,6 @@ This is a personal tool, but PRs and issues are welcome. Before submitting:
 1. Read [`AGENTS.md`](./AGENTS.md) — it covers the commit rules, branching model, and code conventions
 2. Run `npm run lint`, `npx tsc --noEmit`, and `npm test` locally
 3. Base your branch on `develop` (not `main`); PRs target `develop`
-4. **Do not add `Co-Authored-By` trailers** in commits, even for AI-assisted work
 
 CI runs lint + type check + tests on every PR to `develop`.
 

package/dist/mcp-server/kobo-tasks-handlers.js

@@ -183,3 +183,148 @@ export function listWorkspaceImagesHandler(worktreePath) {
         };
     });
 }
+// ── Documents ────────────────────────────────────────────────────────────────
+/** Directories (relative to the worktree root) scanned for AI-generated docs. */
+export const DOCUMENT_DIRS = ['docs/plans', 'docs/superpowers', '.ai/thoughts'];
+/** Depth cap to keep recursion bounded even on pathological symlink loops. */
+const DOC_MAX_DEPTH = 8;
+function walkMarkdownFiles(rootAbs, rootRel, out, depth = 0) {
+    if (depth > DOC_MAX_DEPTH)
+        return;
+    let entries;
+    try {
+        entries = fs.readdirSync(rootAbs);
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.startsWith('.') && entry !== '.ai')
+            continue;
+        const absEntry = path.join(rootAbs, entry);
+        const relEntry = `${rootRel}/${entry}`;
+        let stat;
+        try {
+            stat = fs.statSync(absEntry);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isDirectory()) {
+            walkMarkdownFiles(absEntry, relEntry, out, depth + 1);
+        }
+        else if (stat.isFile() && entry.endsWith('.md')) {
+            out.push({ path: relEntry, name: entry, modifiedAt: stat.mtime.toISOString() });
+        }
+    }
+}
+/**
+ * Recursively list every `.md` file under `docs/plans/`, `docs/superpowers/`,
+ * and `.ai/thoughts/` inside the given worktree. Sorted by modifiedAt desc.
+ */
+export function listDocumentsHandler(worktreePath) {
+    const documents = [];
+    for (const dir of DOCUMENT_DIRS) {
+        const absDir = path.join(worktreePath, dir);
+        if (!fs.existsSync(absDir))
+            continue;
+        walkMarkdownFiles(absDir, dir, documents);
+    }
+    documents.sort((a, b) => new Date(b.modifiedAt).getTime() - new Date(a.modifiedAt).getTime());
+    return documents;
+}
+/**
+ * Read a single document. The caller-supplied path must be relative to the
+ * worktree root and live under one of the allowed DOCUMENT_DIRS; `.md` only;
+ * traversal (`..`) is rejected.
+ */
+export function readDocumentHandler(worktreePath, relPath) {
+    if (!relPath)
+        throw new Error('path is required');
+    const normalized = path.normalize(relPath);
+    if (normalized.includes('..') ||
+        !DOCUMENT_DIRS.some((dir) => normalized.startsWith(`${dir}/`) || normalized === dir)) {
+        throw new Error(`Invalid path: must be under ${DOCUMENT_DIRS.map((d) => `${d}/`).join(', ')}`);
+    }
+    if (!normalized.endsWith('.md')) {
+        throw new Error('Only .md files can be read');
+    }
+    const abs = path.join(worktreePath, normalized);
+    if (!fs.existsSync(abs)) {
+        throw new Error(`Document not found: ${normalized}`);
+    }
+    return { path: normalized, content: fs.readFileSync(abs, 'utf-8') };
+}
+/**
+ * Append a thought / decision / note to `.ai/thoughts/<YYYY-MM-DD>-<slug>.md`.
+ * Creates the directory if missing. Returns the path (worktree-relative) of
+ * the file actually written — useful for the agent to reference it in chat.
+ */
+export function logThoughtHandler(worktreePath, data) {
+    const title = data.title?.trim();
+    if (!title)
+        throw new Error('title is required');
+    const content = data.content?.trim();
+    if (!content)
+        throw new Error('content is required');
+    const thoughtsDir = path.join(worktreePath, '.ai', 'thoughts');
+    fs.mkdirSync(thoughtsDir, { recursive: true });
+    const date = new Date().toISOString().slice(0, 10);
+    const slug = title
+        .toLowerCase()
+        .normalize('NFKD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 60) || 'note';
+    const tagSuffix = data.tag ? `-${data.tag.replace(/[^a-z0-9]+/gi, '-').toLowerCase()}` : '';
+    const filename = `${date}-${slug}${tagSuffix}.md`;
+    const abs = path.join(thoughtsDir, filename);
+    const relPath = `.ai/thoughts/${filename}`;
+    const header = `# ${title}\n\n_${new Date().toISOString()}_${data.tag ? ` · tag: \`${data.tag}\`` : ''}\n\n`;
+    fs.writeFileSync(abs, header + content + (content.endsWith('\n') ? '' : '\n'), 'utf-8');
+    return { path: relPath };
+}
+/**
+ * Aggregate `usage` events from `ws_events` to report how many tokens and
+ * dollars the workspace has consumed — both in total and for the currently
+ * running agent_session (if any). Silently skips rows whose payload is not
+ * valid JSON or not a usage event.
+ */
+export function getSessionUsageHandler(db, workspaceId) {
+    const runningSession = db
+        .prepare("SELECT id FROM agent_sessions WHERE workspace_id = ? AND status = 'running' ORDER BY started_at DESC LIMIT 1")
+        .get(workspaceId);
+    const currentSessionId = runningSession?.id ?? null;
+    const rows = db
+        .prepare("SELECT payload, session_id FROM ws_events WHERE workspace_id = ? AND type = 'agent:event'")
+        .all(workspaceId);
+    const totals = { inputTokens: 0, outputTokens: 0, costUsd: 0 };
+    const current = { inputTokens: 0, outputTokens: 0, costUsd: 0 };
+    for (const row of rows) {
+        let parsed;
+        try {
+            parsed = JSON.parse(row.payload);
+        }
+        catch {
+            continue;
+        }
+        if (parsed.kind !== 'usage')
+            continue;
+        const input = typeof parsed.inputTokens === 'number' ? parsed.inputTokens : 0;
+        const output = typeof parsed.outputTokens === 'number' ? parsed.outputTokens : 0;
+        const cost = typeof parsed.costUsd === 'number' ? parsed.costUsd : 0;
+        totals.inputTokens += input;
+        totals.outputTokens += output;
+        totals.costUsd += cost;
+        if (currentSessionId && row.session_id === currentSessionId) {
+            current.inputTokens += input;
+            current.outputTokens += output;
+            current.costUsd += cost;
+        }
+    }
+    return {
+        workspaceTotals: totals,
+        currentSession: { sessionId: currentSessionId, ...current },
+    };
+}

package/dist/mcp-server/kobo-tasks-server.js

@@ -5,7 +5,7 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import Database from 'better-sqlite3';
-import { createTaskHandler, deleteTaskHandler, getDevServerStatusHandler, getSettingsHandler, getWorkspaceInfoHandler, listTasksHandler, listWorkspaceImagesHandler, markTaskDoneHandler, updateTaskHandler, } from './kobo-tasks-handlers.js';
+import { createTaskHandler, deleteTaskHandler, getDevServerStatusHandler, getSessionUsageHandler, getSettingsHandler, getWorkspaceInfoHandler, listDocumentsHandler, listTasksHandler, listWorkspaceImagesHandler, logThoughtHandler, markTaskDoneHandler, readDocumentHandler, updateTaskHandler, } from './kobo-tasks-handlers.js';
 const workspaceId = process.env.KOBO_WORKSPACE_ID;
 const dbPath = process.env.KOBO_DB_PATH;
 const settingsPath = process.env.KOBO_SETTINGS_PATH;
@@ -73,37 +73,30 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
         {
             name: 'list_tasks',
-            description: 'List all tasks and acceptance criteria for the current workspace with their IDs and current status. Call this first to discover task IDs before calling mark_task_done / update_task / delete_task.',
-            inputSchema: {
-                type: 'object',
-                properties: {},
-                required: [],
-            },
+            description: 'CALL FIRST on any non-trivial turn to know what the user wants done and what is already completed. Returns every task and acceptance criterion for the current workspace with its id and status. Re-call periodically (before marking something done, or after the user asks for a status) to stay in sync with user-added or external updates.',
+            inputSchema: { type: 'object', properties: {}, required: [] },
         },
         {
             name: 'mark_task_done',
-            description: 'Mark a task or acceptance criterion as done. Use this when you have completed the work for a criterion and validated it.',
+            description: 'CALL AS SOON AS a task or acceptance criterion is finished AND verified (tests pass, feature works, diff committed). Do not wait for the end of the turn — the user watches progress live and marking each item as it completes is the primary signal Kōbō uses to track you.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    task_id: {
-                        type: 'string',
-                        description: 'The ID of the task to mark as done (obtained from list_tasks)',
-                    },
+                    task_id: { type: 'string', description: 'Task id from list_tasks.' },
                 },
                 required: ['task_id'],
             },
         },
         {
             name: 'create_task',
-            description: 'Create a new task or acceptance criterion for the current workspace. Appended at the end of the list.',
+            description: 'CALL WHEN you discover follow-up work that was not in the original list and needs to stick around (e.g. "refactor this helper later", "add a test for edge case"). Appends at the end of the list. Do not use it for ephemeral internal notes — prefer log_thought for those.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    title: { type: 'string', description: 'Task title' },
+                    title: { type: 'string', description: 'Short, imperative title (e.g. "Add retry to fetchUser").' },
                     is_acceptance_criterion: {
                         type: 'boolean',
-                        description: 'Whether this is an acceptance criterion (default: false)',
+                        description: 'Mark as acceptance criterion rather than a task (default: false).',
                     },
                 },
                 required: ['title'],
@@ -111,20 +104,20 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: 'update_task',
-            description: 'Update an existing task — change title, status, or is_acceptance_criterion flag. At least one field is required.',
+            description: 'CALL WHEN you need to refine a task — rewording for clarity, flipping status to `in_progress` as you start it, or promoting a task to acceptance criterion. At least one mutable field is required.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    task_id: { type: 'string', description: 'The ID of the task to update' },
-                    title: { type: 'string', description: 'New title (optional)' },
+                    task_id: { type: 'string', description: 'Task id from list_tasks.' },
+                    title: { type: 'string', description: 'New title (optional).' },
                     status: {
                         type: 'string',
                         enum: ['pending', 'in_progress', 'done'],
-                        description: 'New status (optional)',
+                        description: 'New status (optional).',
                     },
                     is_acceptance_criterion: {
                         type: 'boolean',
-                        description: 'Toggle acceptance criterion flag (optional)',
+                        description: 'Toggle acceptance criterion flag (optional).',
                     },
                 },
                 required: ['task_id'],
@@ -132,95 +125,150 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: 'delete_task',
-            description: 'Delete a task from the current workspace permanently.',
+            description: 'CALL ONLY when a task was created in error or became truly irrelevant (scope change validated by user). Prefer marking done or in_progress over deleting.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    task_id: { type: 'string', description: 'The ID of the task to delete' },
+                    task_id: { type: 'string', description: 'Task id from list_tasks.' },
                 },
                 required: ['task_id'],
             },
         },
         {
-            name: 'get_settings',
-            description: 'Read Kōbō settings (global + projects). Optionally filter to a specific project by path to get both global and that project override.',
+            name: 'get_workspace_info',
+            description: 'CALL EARLY in a session to confirm project path, working/source branch, worktree path, model, and notion link. Cheap read — useful when the user refers to "this workspace" or when you need the worktree path to locate files.',
+            inputSchema: { type: 'object', properties: {}, required: [] },
+        },
+        {
+            name: 'get_git_info',
+            description: 'CALL BEFORE creating a PR, committing in batches, or reporting progress to the user. Returns commit count ahead of source, files changed, insertions/deletions, and existing PR URL if any.',
+            inputSchema: { type: 'object', properties: {}, required: [] },
+        },
+        {
+            name: 'set_workspace_status',
+            description: 'CALL WHEN you believe the mission is done (`completed`), blocked beyond recovery (`error`), or explicitly idle awaiting user input (`idle`). Transitions are validated by the backend — invalid ones are rejected.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    project_path: {
+                    status: {
                         type: 'string',
-                        description: 'Optional project path to resolve a specific project entry',
+                        enum: ['idle', 'completed', 'error'],
+                        description: 'Target status.',
                     },
                 },
-                required: [],
+                required: ['status'],
             },
         },
         {
-            name: 'get_dev_server_status',
-            description: 'Get the live dev server status for the current workspace. Returns status (running/stopped/starting/error/unknown), URL, HTTP port, instance name, project name, and running container names.',
-            inputSchema: {
-                type: 'object',
-                properties: {},
-                required: [],
-            },
+            name: 'get_notion_ticket',
+            description: 'CALL when the user references "the ticket", "the Notion page", or when you need the source-of-truth text for the mission. Returns the Notion URL + locally-extracted ticket content from .ai/thoughts/.',
+            inputSchema: { type: 'object', properties: {}, required: [] },
         },
         {
-            name: 'get_workspace_info',
-            description: 'Get all metadata about the current workspace (name, project path, branches, model, notion URL, worktree path, status).',
+            name: 'get_dev_server_status',
+            description: 'CALL BEFORE asking the user whether the app is running, or when your change is dev-server-sensitive. Returns running/stopped/starting/error + URL, port, container names.',
             inputSchema: { type: 'object', properties: {}, required: [] },
         },
         {
             name: 'start_dev_server',
-            description: 'Start the dev server configured for the current workspace.',
+            description: 'CALL WHEN the user asks you to test the running app and the dev server is stopped.',
             inputSchema: { type: 'object', properties: {}, required: [] },
         },
         {
             name: 'stop_dev_server',
-            description: 'Stop the dev server of the current workspace.',
+            description: 'CALL WHEN the user explicitly asks to stop the dev server, or before destructive operations that require a clean boot.',
             inputSchema: { type: 'object', properties: {}, required: [] },
         },
         {
             name: 'get_dev_server_logs',
-            description: 'Fetch the last N lines of the dev server logs for the current workspace.',
+            description: 'CALL WHEN debugging a runtime issue the user describes as happening in the running app. Returns the last N lines of logs (default 200). Cheaper than asking the user to paste them.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    tail: {
-                        type: 'number',
-                        description: 'Number of lines to fetch from the end (default: 200)',
-                    },
+                    tail: { type: 'number', description: 'Number of lines from the end (default: 200).' },
                 },
                 required: [],
             },
         },
         {
             name: 'list_workspace_images',
-            description: 'List all images uploaded to the current workspace (from .ai/images/index.json). Returns uid, originalName, relativePath and createdAt for each image.',
+            description: 'CALL WHEN the user mentions "the screenshot", "the attached image", or when you need to reference a previously-uploaded image. Returns uid, originalName, relativePath, createdAt for every image in .ai/images/.',
             inputSchema: { type: 'object', properties: {}, required: [] },
         },
         {
-            name: 'get_git_info',
-            description: 'Get git stats for the current workspace (commit count, files changed, insertions, deletions, PR URL if any).',
+            name: 'get_settings',
+            description: 'CALL WHEN you need to confirm configured models, PR prompt templates, git conventions, or dev-server commands before acting on them. Pass project_path to merge global + project-specific entries.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    project_path: {
+                        type: 'string',
+                        description: 'Project path to resolve a specific project entry (optional).',
+                    },
+                },
+                required: [],
+            },
+        },
+        // ── Knowledge / context tools ─────────────────────────────────────────────
+        {
+            name: 'list_documents',
+            description: 'CALL EARLY on a new session to discover plans, specs, and thoughts previously written for this workspace. Recursively lists every .md under docs/plans/, docs/superpowers/, and .ai/thoughts/. Before writing a new plan, check if one already exists.',
             inputSchema: { type: 'object', properties: {}, required: [] },
         },
         {
-            name: 'set_workspace_status',
-            description: 'Update the current workspace status. Valid values: idle, completed, error. Transitions are validated by the backend.',
+            name: 'read_document',
+            description: 'CALL AFTER list_documents when a file title looks relevant to the current task. Returns the full markdown content. Scoped to docs/plans/, docs/superpowers/, .ai/thoughts/ — reject anything else.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    status: {
+                    path: {
                         type: 'string',
-                        enum: ['idle', 'completed', 'error'],
-                        description: 'New status (e.g. idle, completed)',
+                        description: 'Worktree-relative path from list_documents (e.g. "docs/superpowers/plans/2026-04-17-foo.md").',
                     },
                 },
-                required: ['status'],
+                required: ['path'],
             },
         },
         {
-            name: 'get_notion_ticket',
-            description: 'Get the Notion ticket info for the current workspace. Returns the Notion URL and the extracted ticket content (from .ai/thoughts/) if available.',
+            name: 'log_thought',
+            description: 'CALL WHEN you make a decision worth remembering — architecture choice, trade-off taken, dead-end avoided, pattern discovered. Appends a dated markdown file to .ai/thoughts/. Keep entries short and focused; one decision per call. Use create_task for actionable follow-ups instead.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    title: { type: 'string', description: 'Short, descriptive title (becomes the filename slug and the # H1).' },
+                    content: { type: 'string', description: 'Markdown body explaining the decision and its reasoning.' },
+                    tag: {
+                        type: 'string',
+                        description: 'Optional short tag appended to filename (e.g. "arch", "bug", "perf").',
+                    },
+                },
+                required: ['title', 'content'],
+            },
+        },
+        {
+            name: 'search_codebase',
+            description: 'CALL WHEN you need to recall prior chat history across workspaces — past decisions, prior user requests, an agent message you remember but can’t locate. Full-text search over user messages + agent outputs persisted in Kōbō. Use the local Grep tool for searching source code; this tool searches CONVERSATIONS.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: 'Search phrase. Plain text; no regex.' },
+                    include_archived: {
+                        type: 'boolean',
+                        description: 'Include archived workspaces in the search (default: false).',
+                    },
+                    scope: {
+                        type: 'string',
+                        enum: ['workspace', 'all'],
+                        description: 'Restrict to this workspace only (default) or search across every workspace.',
+                    },
+                    limit: { type: 'number', description: 'Max results to return (default 30, max 100).' },
+                },
+                required: ['query'],
+            },
+        },
+        {
+            name: 'get_session_usage',
+            description: 'CALL when you need to self-regulate on long missions — returns token/cost totals for the workspace lifetime and for the currently running agent_session. Useful before spawning heavy subagents or deep reasoning on already-expensive sessions.',
             inputSchema: { type: 'object', properties: {}, required: [] },
         },
     ],
@@ -339,6 +387,48 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const result = await backendRequest('PATCH', `/api/workspaces/${workspaceId}`, { status });
             return ok(result);
         }
+        if (name === 'list_documents') {
+            const info = getWorkspaceInfoHandler(db, workspaceId);
+            return ok(listDocumentsHandler(info.worktreePath));
+        }
+        if (name === 'read_document') {
+            const docPath = a.path;
+            if (!docPath)
+                return fail('path parameter is required');
+            const info = getWorkspaceInfoHandler(db, workspaceId);
+            return ok(readDocumentHandler(info.worktreePath, docPath));
+        }
+        if (name === 'log_thought') {
+            const title = a.title;
+            const content = a.content;
+            if (!title)
+                return fail('title parameter is required');
+            if (!content)
+                return fail('content parameter is required');
+            const info = getWorkspaceInfoHandler(db, workspaceId);
+            return ok(logThoughtHandler(info.worktreePath, {
+                title,
+                content,
+                tag: a.tag,
+            }));
+        }
+        if (name === 'get_session_usage') {
+            return ok(getSessionUsageHandler(db, workspaceId));
+        }
+        if (name === 'search_codebase') {
+            const query = a.query;
+            if (!query)
+                return fail('query parameter is required');
+            const scope = a.scope ?? 'workspace';
+            const includeArchived = a.include_archived === true;
+            const limit = Math.min(Math.max(1, a.limit ?? 30), 100);
+            const qs = new URLSearchParams({ q: query, limit: String(limit) });
+            if (includeArchived)
+                qs.set('includeArchived', 'true');
+            const raw = (await backendRequest('GET', `/api/search?${qs.toString()}`));
+            const results = scope === 'all' ? raw : raw.filter((r) => r.workspaceId === workspaceId);
+            return ok({ query, scope, total: results.length, results });
+        }
         return fail(`Unknown tool: ${name}`);
     }
     catch (err) {

package/dist/server/index.js

@@ -8,13 +8,13 @@ import WebSocket, { WebSocketServer } from 'ws';
 import { closeDb, getDb } from './db/index.js';
 import { runMigrations } from './db/migrations.js';
 import devServerRouter from './routes/dev-server.js';
+import documentsRouter from './routes/documents.js';
 import { enginesRouter } from './routes/engines.js';
 import gitRouter from './routes/git.js';
 import healthRouter from './routes/health.js';
 import imagesRouter from './routes/images.js';
 import { migrationRouter } from './routes/migration.js';
 import notionRouter from './routes/notion.js';
-import plansRouter from './routes/plans.js';
 import searchRouter from './routes/search.js';
 import sentryRouter from './routes/sentry.js';
 import settingsRouter from './routes/settings.js';
@@ -71,7 +71,7 @@ app.route('/api/git', gitRouter);
 app.route('/api/settings', settingsRouter);
 app.route('/api/dev-server', devServerRouter);
 app.route('/api/templates', templatesRouter);
-app.route('/api/workspaces', plansRouter);
+app.route('/api/workspaces', documentsRouter);
 app.route('/api/search', searchRouter);
 app.route('/api/health', healthRouter);
 app.route('/api/engines', enginesRouter);