saga-mcp 1.16.0 → 1.17.1

package/README.md

@@ -5,20 +5,21 @@
 [![license](https://img.shields.io/npm/l/saga-mcp)](https://github.com/spranab/saga-mcp/blob/master/LICENSE)
 [![IdeaCred](https://ideacred.com/api/badge/spranab/saga-mcp)](https://ideacred.com/profile/spranab)
 
-Your coding agent loses the plan between sessions. You come back tomorrow and
-it has no idea which of the five things you agreed on are done, which one is
-blocked on which, or why you rejected the second approach — because the plan
-lived in the context window, or in a `TODO.md` nobody updates.
+Your coding agent loses the plan between sessions. You come back tomorrow and it has no idea which
+of the five things you agreed on are done, which one is blocked on which, or why you rejected the
+second approach — because the plan lived in the context window, or in a `TODO.md` nobody updates.
 
-saga-mcp gives the agent a real tracker instead: a SQLite file in your project
-holding projects, epics, tasks, subtasks, dependencies, comments, notes and
-decisions, exposed as 41 MCP tools. The agent writes to it as it works and
-reads the dashboard when it comes back. No accounts, no external service, no
-network calls — the database is a file you own.
+saga-mcp gives the agent a real tracker instead: a SQLite file in your project holding projects,
+epics, tasks, subtasks, dependencies, comments, notes and decisions, exposed as 41 MCP tools. The
+agent writes to it as it works and reads it back when it returns. No accounts, no external service,
+no network calls — the database is a file you own.
 
-## Install (60 seconds)
+---
 
-Claude Code — add to your project's `.mcp.json`:
+## Install
+
+Add saga-mcp to your MCP client. The same block works for Claude Code (`.mcp.json` in your
+project), Claude Desktop (`claude_desktop_config.json`), and any other MCP client:
 
 ```json
 {
@@ -32,14 +33,30 @@ Claude Code — add to your project's `.mcp.json`:
 }
 ```
 
-Restart the client. `DB_PATH` is the only setting; the file and schema are
-created on first use.
+Restart the client. `DB_PATH` is the only required setting; the file and its schema are created on
+first use. Prefer a global install? `npm install -g saga-mcp`, then use `saga-mcp` as the command
+instead of `npx`.
+
+Tested on Node 20, 22 and 24, on Linux, macOS and Windows.
+
+### Settings
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `DB_PATH` | Yes | Path to the `.tracker.db` SQLite file. Created on first use. |
+| `SAGA_PROJECT` | No | Scope every tool to one project, by id or name. Set this per repo when several repos [share one database](#one-database-many-projects). |
+| `SAGA_DESCRIPTION_LOCK` | No | `on_progress` locks a task's description the moment work starts on it. Off by default. See [keeping agents on the rails](#keeping-agents-on-the-rails). |
+| `SAGA_TOOLS` | No | `full` (default) lists all 41 tools. `core` lists only the 13 an ordinary tracking session needs, saving ~4,300 tokens per session. See [token cost](#token-cost). |
+
+No API keys, no accounts, no external services.
+
+---
 
-## What it looks like
+## Your first session
 
 **You:** "Set up tracking for the e-commerce API and plan out auth."
 
-```
+```js
 tracker_init({ project_name: "E-Commerce API" })
 epic_create({ project_id: 1, name: "Authentication", priority: "high" })
 task_create({ epic_id: 1, title: "Design auth schema", priority: "critical" })
@@ -47,306 +64,308 @@ task_create({ epic_id: 1, title: "Implement JWT auth", depends_on: [1] })
 task_create({ epic_id: 1, title: "Add OAuth2 Google login", depends_on: [2] })
 ```
 
-Tasks 2 and 3 come back **blocked** — their dependencies aren't done. Finish
-task 1 and task 2 unblocks itself.
+Tasks 2 and 3 come back **blocked** — their dependencies aren't done. Finish task 1 and task 2
+unblocks itself.
 
 **Next session, you:** "Where were we?"
 
-```
-tracker_dashboard({})
-→ "E-Commerce API: 5 tasks across 2 epics. 40% complete.
-   Active: Authentication (2/3 done). Next up: Product Catalog (2 tasks).
-   1 blocked task(s)."
+```js
+tracker_next({})
+  -> Work on #1 'Design auth schema' — critical priority, in the active epic
+     'Authentication'. 2 other task(s) are blocked.
 ```
 
-Plus the structured data behind it: stats, epics, blocked and overdue tasks,
-recent activity, notes.
+One recommendation with the reason. For the whole picture instead, `tracker_dashboard({})` returns
+stats, epics, blocked and overdue tasks, recent activity and notes, with a summary on top.
 
-## Features
+And when you would rather look than ask, `saga-web` puts the same database in a browser:
 
-- **Full hierarchy**: Projects > Epics > Tasks > Subtasks
-- **Task dependencies**: Express sequencing with auto-block/unblock when deps are met
-- **Description lock**: Stop agents rewriting a task's spec when they meant to leave a comment
-- **Subtask ordering & dependencies**: Explicit order, and checklist items that wait on siblings
-- **Comments**: Threaded discussions on tasks — leave breadcrumbs across sessions, with reversible soft-delete
-- **Web UI**: `saga-web` serves a local dashboard for browsing *and* editing the same database
-- **Templates**: Reusable task sets with `{variable}` substitution
-- **Dashboard**: One tool call gives full overview with natural language summary
-- **SQLite**: Self-contained `.tracker.db` file per project — zero setup, no external database
-- **Activity log**: Every mutation is automatically tracked with old/new values
-- **Notes system**: Decisions, context, meeting notes, blockers — all searchable
-- **Batch operations**: Create multiple subtasks or update multiple tasks in one call
-- **41 focused tools**: With MCP safety annotations on every tool
-- **Import/export**: Full project backup and migration as JSON (with dependencies and comments)
-- **Source references**: Link tasks to specific code locations
-- **Auto time tracking**: Hours computed automatically from activity log
-- **Cross-platform**: Works on macOS, Windows, and Linux
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/spranab/saga-mcp/master/docs/screenshots/overview-dark.png">
+  <img alt="The saga-web overview: task counts, per-epic progress, blocked and overdue work" src="https://raw.githubusercontent.com/spranab/saga-mcp/master/docs/screenshots/overview-light.png">
+</picture>
 
-## Other clients
 
-### Claude Code
+---
 
-Add to your project's `.mcp.json`:
+## What you get
 
-```json
-{
-  "mcpServers": {
-    "saga": {
-      "command": "npx",
-      "args": ["-y", "saga-mcp"],
-      "env": {
-        "DB_PATH": "/absolute/path/to/your/project/.tracker.db"
-      }
-    }
-  }
-}
-```
+- **[The next thing to do](#asking-what-to-do-next)** — one recommendation with its reason, at a
+  third the cost of the dashboard
+- **[Real sequencing](#ordering-and-dependencies)** — dependencies that auto-block and auto-unblock,
+  a manual order the tools respect, and cycles refused rather than deadlocked
+- **[Guards against agent drift](#keeping-agents-on-the-rails)** — a lockable description, and
+  prerequisites enforced on write rather than merely reported
+- **[A web UI](#web-ui)** — `saga-web` serves the same database in a browser, read *and* write
+- **[Templates](#templates)** — reusable task sets with `{variable}` substitution, editable in place
+- **[Archiving and soft delete](#getting-old-work-out-of-the-way)** — get finished work out of the
+  context you pay for, reversibly
+- **[Forgiving input](#forgiving-input)** — a smaller model sending an array as a JSON string
+  doesn't silently collapse your batch into one record
+- **[One file, many projects](#one-database-many-projects)** — per-repo databases or one shared file
+- **A full audit trail** — every mutation logged with old and new values, and nothing an agent
+  removes is unrecoverable
+- **41 tools** with MCP safety annotations on every one, and a [tiered surface](#token-cost) when
+  you want a smaller context bill
 
-### With Claude Desktop
+---
 
-Add to your Claude Desktop config (`claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "saga": {
-      "command": "npx",
-      "args": ["-y", "saga-mcp"],
-      "env": {
-        "DB_PATH": "/absolute/path/to/your/project/.tracker.db"
-      }
-    }
-  }
-}
-```
+## Asking what to do next
 
-### Manual install
+`tracker_dashboard` hands an agent everything and leaves it to reason. `tracker_next` answers the
+question:
 
-```bash
-npm install -g saga-mcp
-DB_PATH=./my-project/.tracker.db saga-mcp
+```
+tracker_next()
+  -> Work on #12 'Write the adapter' — already in progress, high priority, in the
+     active epic 'Provider swap'. Next step: implement. Also overdue: #18 'Renew cert'.
+     3 other task(s) are blocked.
 ```
 
-## Configuration
-
-saga-mcp requires a single environment variable:
+One recommendation with the reason, the next unfinished subtask inside it, a couple of
+alternatives, and anything overdue or blocked. About a third the size of the dashboard.
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `DB_PATH` | Yes | Absolute path to the `.tracker.db` SQLite file. The file and schema are auto-created on first use. |
-| `SAGA_PROJECT` | No | Scope every tool to one project, by id or name. Set this per repo when several repos share one database. Unset, tools read across the whole file. |
-| `SAGA_TOOLS` | No | `full` (default) lists all 41 tools. `core` lists only the 13 an ordinary tracking session needs, cutting ~3,300 tokens of context per session. Tools left off the list still work if called by name. |
+The ordering rule worth knowing: **continuing beats starting.** A task already in progress outranks
+an untouched one that is overdue or higher priority, because abandoning work in flight just leaves
+two things unfinished — the overdue work is named in the summary instead. Blocked tasks are never
+recommended, archived epics and removed tasks are skipped, and subtask dependencies decide which
+step comes next inside the chosen task.
 
-No API keys, no accounts, no external services. Everything is stored locally in the SQLite file you specify.
+When nothing is actionable it says what to unblock rather than returning an empty answer:
 
-### Token cost
+```
+Nothing is actionable: all 4 remaining task(s) are blocked.
+Unblocking #7 'the keystone' would release 3 of them.
+```
 
-The tool list is context every session pays before any work happens, and list responses are
-context it pays again on every call. Both are kept deliberately small:
+---
 
-- Responses are compact JSON — no pretty-print indentation, which measured 20-27% of every response
-- `task_list` rows omit nulls and `metadata`, and truncate descriptions to 120 characters
-  (call `task_get` for a task's full text) — 19-39% smaller depending on how long your descriptions run
-- `activity_log` omits null columns and the row id (no tool takes one) — about 27% smaller
-- `tracker_search` returns previews rather than whole records — about 47% smaller; follow up with
-  `task_get` or `note_list` for the full text
-- `SAGA_TOOLS=core` drops the listed tool surface from ~6,000 to ~2,700 tokens
+## Ordering and dependencies
 
-`note_list` deliberately keeps full note content — it is the retrieval tool, not a preview.
+**A deliberate order wins over a guess.** `task_list` sorts by priority until someone arranges an
+epic, and from then on it follows the arrangement:
 
-Set `SAGA_TOOLS=core` when an agent only tracks work; leave it unset when you want templates,
-import/export, session diffs and the rest discoverable.
+```js
+task_reorder({ epic_id: 2, ordered_ids: [8, 5, 6] })
+task_list({ epic_id: 2 })                        // 8, 5, 6 — the plan, in order
+task_list({ epic_id: 2, sort_by: "priority" })   // priority, if that is what you want
+```
 
-## Tools
+Priority is a reasonable guess about what matters; a sequence someone wrote down is not a guess.
+An agent handed a plan should start at the beginning of it, not at whichever step happens to be
+marked critical.
 
-### Getting Started
+Nothing changes for epics nobody has arranged — those sort by priority exactly as before, and an
+explicit `sort_by` is always obeyed literally.
 
-| Tool | Description | Annotations |
-|------|-------------|-------------|
-| `tracker_init` | Initialize tracker and create first project | `readOnly: false`, `idempotent: true` |
-| `tracker_next` | What to work on next, with the reason and what is blocked | `readOnly: true` |
-| `tracker_dashboard` | Full project overview with natural language summary | `readOnly: true` |
+Anything omitted from `ordered_ids` keeps its relative position at the end. `sort_order` runs
+ascending — lower sorts first — and a task created *after* an arrangement has no place in it, so it
+lands at the end rather than the front. In the web UI you can drag tasks into place inside an epic.
 
-### Projects
+Task dependencies auto-block and auto-unblock:
 
-| Tool | Description | Annotations |
-|------|-------------|-------------|
-| `project_create` | Create a new project | `readOnly: false` |
-| `project_list` | List projects with completion stats | `readOnly: true` |
-| `project_update` | Update project (archive to soft-delete) | `readOnly: false`, `idempotent: true` |
+```js
+task_update({ id: 9, depends_on: [8] })   // 9 becomes blocked while 8 is open
+```
 
-### Epics
+Re-evaluation runs whenever a blocker's *doneness* changes in either direction, so reopening a
+finished blocker blocks its dependents again, and clearing the last dependency releases them.
+Circular dependencies are refused with the loop named, for tasks and subtasks alike — anything
+in a cycle would be blocked forever. The web UI shows a banner at the top of a blocked task naming
+what it waits on, with a picker to add or remove dependencies.
 
-| Tool | Description | Annotations |
-|------|-------------|-------------|
-| `epic_create` | Create an epic within a project | `readOnly: false` |
-| `epic_list` | List epics with task counts | `readOnly: true` |
-| `epic_archive` | Archive/unarchive an epic, hiding it and its tasks from listings | `readOnly: false`, `idempotent: true` |
-| `epic_update` | Update an epic | `readOnly: false`, `idempotent: true` |
+---
 
-### Tasks
+## Keeping agents on the rails
 
-| Tool | Description | Annotations |
-|------|-------------|-------------|
-| `task_create` | Create a task with optional dependencies | `readOnly: false` |
-| `task_list` | List/filter tasks with dependency info | `readOnly: true` |
-| `task_get` | Get task with subtasks, notes, comments, and dependencies | `readOnly: true` |
-| `task_update` | Update task (auto-logs, auto-blocks/unblocks) | `readOnly: false`, `idempotent: true` |
-| `task_lock_description` | Lock/unlock a description so agents can't rewrite it | `readOnly: false`, `idempotent: true` |
-| `task_reorder` | Set the order of an epic's tasks | `readOnly: false`, `idempotent: true` |
-| `task_delete` | Remove a `todo` task (soft delete, restorable) | `readOnly: false`, `idempotent: true` |
-| `task_restore` | Restore a removed task | `readOnly: false`, `idempotent: true` |
-| `task_batch_update` | Update multiple tasks at once | `readOnly: false`, `idempotent: true` |
+Two guards for the ways an agent goes wrong on a long task.
 
-### Subtasks
+**A locked description.** Agents sometimes rewrite a task's description to record progress, when
+they meant to add a comment — and the spec you agreed on is gone. Lock it and `task_update` refuses:
 
-| Tool | Description | Annotations |
-|------|-------------|-------------|
-| `subtask_create` | Create subtask(s) — supports batch | `readOnly: false` |
-| `subtask_update` | Update title/status/position; `depends_on` and `blocks` set ordering | `readOnly: false`, `idempotent: true` |
-| `subtask_reorder` | Set the order of a task's subtasks in one call | `readOnly: false`, `idempotent: true` |
-| `subtask_delete` | Delete subtask(s) — supports batch | `destructive: true`, `idempotent: true` |
+```js
+task_lock_description({ id: 12 })
+task_update({ id: 12, description: "..." })
+  -> Task 12's description is locked and was not changed. Record progress with
+     comment_add instead, or unlock it in the web UI if the description is genuinely wrong.
+```
 
-### Comments
+Everything else about the task stays editable — the point is to protect the spec, not freeze the
+task. The lock cannot be cleared as a side effect of an ordinary `task_update`; it takes a
+deliberate `task_lock_description` call or the lock toggle in the web UI, and both are logged.
 
-| Tool | Description | Annotations |
-|------|-------------|-------------|
-| `comment_add` | Add a comment to a task (threaded discussion) | `readOnly: false` |
-| `comment_list` | List comments on a task (removed ones hidden unless `include_deleted`) | `readOnly: true` |
-| `comment_delete` | Remove a comment — soft delete, row kept for audit | `readOnly: false`, `idempotent: true` |
-| `comment_restore` | Restore a removed comment | `readOnly: false`, `idempotent: true` |
+This is a guard against confusion, not an adversarial control: an agent that is told to unlock
+still can. It turns a silent overwrite into a visible, reversible decision.
 
-### Templates
+Locking each task by hand does not scale across a plan, so `SAGA_DESCRIPTION_LOCK=on_progress`
+does it for you: a task locks as work starts on it — when it moves to `in_progress`, `review` or
+`done`, or is created there. It is off unless you set it, since it changes what an agent is
+allowed to do.
 
-| Tool | Description | Annotations |
-|------|-------------|-------------|
-| `template_create` | Create a reusable task template with `{variable}` placeholders | `readOnly: false` |
-| `template_list` | List templates; `include_tasks` shows what each one creates | `readOnly: true` |
-| `template_update` | Edit a template in place — name, description or tasks | `readOnly: false`, `idempotent: true` |
-| `template_apply` | Apply template to create tasks with variable substitution | `readOnly: false` |
-| `template_delete` | Delete a template | `destructive: true`, `idempotent: true` |
+```json
+"env": { "DB_PATH": "…", "SAGA_DESCRIPTION_LOCK": "on_progress" }
+```
 
-### Notes
+It sets the same flag `task_lock_description` sets, rather than second-guessing every write. So
+one mechanism governs the field: unlock a task and it stays unlocked, whatever its status does
+next. `blocked` is not "started" — a task waiting on a dependency has not been worked on, and
+dependencies move tasks in and out of that status on their own.
 
-| Tool | Description | Annotations |
-|------|-------------|-------------|
-| `note_save` | Create or update a note (upsert) | `readOnly: false` |
-| `note_list` | List notes with filters | `readOnly: true` |
-| `note_search` | Full-text search across notes | `readOnly: true` |
-| `note_delete` | Delete a note | `destructive: true`, `idempotent: true` |
+**Subtask order and dependencies.** New subtasks are appended in order rather than all landing at
+position 0, `subtask_reorder` sets the order in one call (or drag them in the UI), and a subtask
+can wait on its siblings:
 
-### Intelligence
+```js
+subtask_update({ id: 8, depends_on: [5, 6] })    // 8 waits for 5 and 6
+subtask_update({ id: 4, blocks: [5, 6, 7, 8] })  // a bug that holds up the rest
+```
 
-| Tool | Description | Annotations |
-|------|-------------|-------------|
-| `tracker_search` | Cross-entity search (projects, epics, tasks, notes) | `readOnly: true` |
-| `activity_log` | View change history with filters | `readOnly: true` |
-| `tracker_session_diff` | Show what changed since a given timestamp — call at session start | `readOnly: true` |
+Reads carry `depends_on` and `blocked`, and the block is **enforced on write**: starting or
+finishing a subtask whose prerequisites are unmet is refused, and so is completing a task whose
+checklist is still open.
 
-### Import / Export
+```js
+subtask_update({ id: 8, status: "in_progress" })
+  -> Subtask 8 cannot be started — it waits on #5 'write the parser' (todo).
+     Finish those first, or pass force: true to override deliberately (the override is logged).
+```
 
-| Tool | Description | Annotations |
-|------|-------------|-------------|
-| `tracker_export` | Export full project as nested JSON (includes dependencies and comments) | `readOnly: true` |
-| `tracker_import` | Import project from JSON (matching export format) | `readOnly: false` |
+`force: true` is the way past, for when a person has decided the blocker no longer applies. It
+works on `subtask_update`, `task_update` and `task_batch_update`, and every override is written to
+the activity log naming what was skipped. The web UI asks for confirmation and then sends it.
 
-## Usage Examples
+The distinction that matters is between an agent quietly ignoring a blocker and someone choosing to
+override one. Dependencies stay within one task — a checklist item waiting on something under a
+*different* task is a task-level dependency, and `task_update depends_on` already models that.
 
-### Example 1: Starting a project with dependencies
+---
 
-**User prompt:** "Set up tracking for my new e-commerce API project"
+## Comments as a decision trail
 
-**Tool calls:**
-```
-tracker_init({ project_name: "E-Commerce API", project_description: "REST API for online store" })
-epic_create({ project_id: 1, name: "Authentication", priority: "high" })
-task_create({ epic_id: 1, title: "Design auth schema", priority: "critical" })
-task_create({ epic_id: 1, title: "Implement JWT auth", priority: "high", depends_on: [1] })
-task_create({ epic_id: 1, title: "Add OAuth2 Google login", priority: "medium", depends_on: [2] })
+```js
+comment_add({ task_id: 5, content: "Investigated root cause: CORS headers missing on preflight" })
+comment_add({ task_id: 5, content: "Fixed by adding OPTIONS handler. Tested with curl." })
+task_update({ id: 5, status: "done" })
 ```
 
-**Result:** Task 2 and 3 are auto-blocked because their dependencies aren't done yet. When task 1 is marked done, task 2 auto-unblocks.
+Comments persist across sessions — next time an agent calls `task_get(5)`, it sees the full thread.
 
-### Example 2: Resuming work with dashboard summary
+If a comment turns out to be wrong, retract it without losing the trail:
 
-**Tool calls:**
-```
-tracker_dashboard({})
+```js
+comment_delete({ id: 12, reason: "Root cause was wrong — it was a proxy timeout", deleted_by: "pranab" })
 ```
 
-**Response includes a natural language summary:**
-```
-"E-Commerce API: 5 tasks across 2 epics. 40% complete. Active: Authentication (2/3 done). Next up: Product Catalog (2 tasks). 1 blocked task(s)."
-```
+The row stays in the database and in the activity log. `comment_list` and `task_get` skip it,
+`comment_list({ task_id: 5, include_deleted: true })` shows it with its reason, and
+`comment_restore({ id: 12 })` brings it back. Nothing an agent removes is unrecoverable.
 
-Plus the full structured data (stats, epics, blocked tasks, overdue tasks, activity, notes).
+---
 
-### Example 3: Using templates for repeated workflows
+## Templates
 
-**Create a template:**
-```
+A reusable set of tasks with `{variable}` placeholders, filled in when applied:
+
+```js
 template_create({
   name: "feature_workflow",
-  description: "Standard feature implementation",
   tasks: [
-    { "title": "Design {feature} API", "priority": "critical", "estimated_hours": 2 },
-    { "title": "Implement {feature}", "priority": "high", "estimated_hours": 8 },
-    { "title": "Write tests for {feature}", "priority": "high", "estimated_hours": 4 },
-    { "title": "Document {feature}", "priority": "medium", "estimated_hours": 1 }
+    { title: "Design {feature} API",       priority: "critical", estimated_hours: 2 },
+    { title: "Implement {feature}",        priority: "high",     estimated_hours: 8 },
+    { title: "Write tests for {feature}",  priority: "high",     estimated_hours: 4 }
   ]
 })
-```
 
-**Apply it:**
-```
-template_apply({ template_id: 1, epic_id: 2, variables: { "feature": "user auth" } })
+template_apply({ template_id: 1, epic_id: 2, variables: { feature: "user auth" } })
+// -> "Design user auth API", "Implement user auth", "Write tests for user auth"
 ```
 
-Templates are editable in place, which matters because the id is what
-`template_apply` refers to:
+Templates are **editable in place**, which matters because the id is what `template_apply` refers
+to — recreating one breaks anything holding it:
 
 ```js
-// change just the name; the tasks are untouched
-template_update({ id: 1, name: "Feature rollout" })
+template_update({ id: 1, name: "Feature rollout" })                  // tasks untouched
+template_update({ id: 1, tasks: [{ title: "Design {feature}" }] })   // name untouched
+template_list({ include_tasks: true })                               // see what one creates
+```
+
+Task definitions are checked when written rather than when applied, so a bad priority or a missing
+title is refused up front instead of failing later against an epic you have already chosen.
+Templates live in the database as a whole, not inside one project.
+
+The Templates tab shows what each one creates, and the `{placeholders}` it will ask for:
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/spranab/saga-mcp/master/docs/screenshots/templates-dark.png">
+  <img alt="The templates tab, showing each template with the tasks it creates" src="https://raw.githubusercontent.com/spranab/saga-mcp/master/docs/screenshots/templates-light.png">
+</picture>
+
+
+---
+
+## Getting old work out of the way
 
-// or replace the task list wholesale
-template_update({ id: 1, tasks: [{ title: "Design {feature}", priority: "high" }] })
+An epic list that is mostly finished work, and tasks an agent created that should have been
+subtasks, are context you pay for on every call.
 
-// see what a template actually creates, rather than just how many tasks
-template_list({ include_tasks: true })
+```js
+epic_archive({ id: 4 })            // the epic and its tasks drop out of listings
+task_delete({ id: 12, reason: "should have been a subtask" })
 ```
 
-Creates 4 tasks: "Design user auth API", "Implement user auth", "Write tests for user auth", "Document user auth".
+Archiving is deliberately **not** the `cancelled` status: `cancelled` means "we decided not to do
+this", while most of what you want to archive is *completed*. Archived epics and their tasks
+disappear from `epic_list`, `tracker_dashboard`, `task_list` and `tracker_search` — including the
+statistics, not just the lists — and come back with `include_archived`. In the web UI both the
+Overview and the Epics tab archive an epic, hide archived ones by default, and share one
+show-archived switch.
 
-### Example 4: Task comments as decision trail
+Nothing vanishes silently. The dashboard says what it left out:
 
 ```
-comment_add({ task_id: 5, content: "Investigated root cause: CORS headers missing on preflight" })
-comment_add({ task_id: 5, content: "Fixed by adding OPTIONS handler. Tested with curl." })
-task_update({ id: 5, status: "done" })
+Hidden: 2 archived epic(s) and 1 removed task(s) — pass include_archived to include them.
 ```
 
-Comments persist across sessions — next time an agent calls `task_get(5)`, it sees the full discussion thread.
+`task_delete` is the same soft delete comments have, restricted to tasks still in `todo`: anything
+further along has comments, time tracking and an activity log that removing it would strand, and a
+task other tasks depend on is refused outright so nothing is left blocked forever. The row is kept,
+`task_restore` brings it back, and `tracker_export` includes archived and removed rows because a
+backup that omits things is not a backup.
 
-If a comment turns out to be wrong, retract it without losing the trail:
+---
 
-```
-comment_delete({ id: 12, reason: "Root cause was wrong — it was a proxy timeout", deleted_by: "pranab" })
+## Forgiving input
+
+Smaller models routinely send an array parameter as a *string* containing JSON. Every array-taking
+tool accepts that, so a batch does not silently collapse into one record:
+
+```js
+subtask_create({ task_id: 3, titles: '["Write it","Test it"]' })   // 2 subtasks
+subtask_create({ task_id: 3, titles: "- Write it\n- Test it" })    // 2 subtasks
+task_batch_update({ ids: "[4,5]", status: "done" })                // both tasks
+task_create({ epic_id: 1, title: "x", tags: "billing, urgent" })   // 2 tags
 ```
 
-The row stays in the database and in the activity log. `comment_list` and `task_get` skip it,
-`comment_list({ task_id: 5, include_deleted: true })` shows it with its reason, and
-`comment_restore({ id: 12 })` brings it back. Nothing an agent removes is unrecoverable.
+Coercion stops where intent becomes ambiguous. A comma inside a *title* is left alone —
+`"Design the API, then implement it"` is one subtask, not two — while a comma in a tag or an id
+list is a separator, because neither can contain one. Anything genuinely unusable is refused with a
+message naming what arrived and what was wanted, rather than a leaked `ids.map is not a function`.
+
+What comes back matches what went in. `tags`, `metadata` and `source_ref` live in JSON text
+columns, and every response decodes them at the boundary, so a tag list reads as `["billing",
+"urgent"]` rather than the escaped string `"[\"billing\",\"urgent\"]"` an agent cannot use.
+
+---
 
 ## One database, many projects
 
-saga-mcp works either way: a `.tracker.db` per repo (portable, keeps unrelated work apart),
-or one shared database that every repo points at.
+saga-mcp works either way: a `.tracker.db` per repo (portable, keeps unrelated work apart), or one
+shared database that every repo points at.
 
 The shared setup needs one extra thing. `projects` is the top-level table, so a shared file holds
-several projects — but `task_list`, `note_list`, `activity_log` and `tracker_search` read across
-the whole file unless told otherwise. An agent in repo B would see repo A's tasks. Set
-`SAGA_PROJECT` per repo and each agent sees only its own:
+several projects — but `task_list`, `note_list`, `activity_log` and `tracker_search` read across the
+whole file unless told otherwise. An agent in repo B would see repo A's tasks. Set `SAGA_PROJECT`
+per repo and each agent sees only its own:
 
 ```json
 {
@@ -380,219 +399,212 @@ project was a guess, rather than silently reporting on the wrong repo.
 The web UI is unaffected either way: its project switcher lists every project in the database, and
 each tab is scoped to the selected one.
 
-## Forgiving input
-
-Smaller models routinely send an array parameter as a *string* containing JSON.
-Every array-taking tool accepts that, so a batch does not silently collapse into one record:
-
-```
-subtask_create({ task_id: 3, titles: '["Write it","Test it"]' })   # 2 subtasks
-subtask_create({ task_id: 3, titles: "- Write it
-- Test it" })    # 2 subtasks
-task_batch_update({ ids: "[4,5]", status: "done" })               # both tasks
-task_create({ epic_id: 1, title: "x", tags: "billing, urgent" })  # 2 tags
-```
-
-Coercion stops where intent becomes ambiguous. A comma inside a *title* is left alone —
-`"Design the API, then implement it"` is one subtask, not two — while a comma in a tag or an id
-list is a separator, because neither can contain one. Anything genuinely unusable is refused with
-a message naming what arrived and what was wanted, rather than a leaked `ids.map is not a function`.
-
-## Asking what to do next
-
-`tracker_dashboard` hands an agent everything and leaves it to reason. `tracker_next` answers the
-question:
-
-```
-tracker_next()
-  -> Work on #12 'Write the adapter' — already in progress, high priority, in the
-     active epic 'Provider swap'. Next step: implement. Also overdue: #18 'Renew cert'.
-     3 other task(s) are blocked.
-```
-
-One recommendation with the reason, the next unfinished subtask inside it, a couple of
-alternatives, and anything overdue or blocked. About a third the size of the dashboard.
+---
 
-The ordering rule worth knowing: **continuing beats starting.** A task already in progress outranks
-an untouched one that is overdue or higher priority, because abandoning work in flight just leaves
-two things unfinished — the overdue work is named in the summary instead. Blocked tasks are never
-recommended, archived epics and removed tasks are skipped, and subtask dependencies decide which
-step comes next inside the chosen task.
+## Web UI
 
-When nothing is actionable it says what to unblock rather than returning an empty answer:
+Everything above is agent-facing. `saga-web` puts the same database in a browser — for the times
+when reviewing a spec an agent just wrote, or fixing one field by hand, is faster than another
+prompt.
 
+```bash
+npx -p saga-mcp saga-web ./.tracker.db --open
 ```
-Nothing is actionable: all 4 remaining task(s) are blocked.
-Unblocking #7 'the keystone' would release 3 of them.
-```
-
-## Ordering and dependencies
 
-**A deliberate order wins over a guess.** `task_list` sorts by priority until someone arranges an
-epic, and from then on it follows the arrangement:
+Or against a database you already point your MCP server at:
 
-```
-task_reorder({ epic_id: 2, ordered_ids: [8, 5, 6] })
-task_list({ epic_id: 2 })                        # 8, 5, 6 — the plan, in order
-task_list({ epic_id: 2, sort_by: "priority" })   # priority, if that is what you want
+```bash
+saga-web --db ~/saga/central.tracker.db --port 8080
 ```
 
-Priority is a reasonable guess about what matters; a sequence someone wrote down is not a guess.
-An agent handed a plan should start at the beginning of it, not at whichever step happens to be
-marked critical.
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--db <path>` | `$DB_PATH` | Database to open. A positional path works too. |
+| `--port <n>` | first free from `4319` | Omit it and saga-web takes the first free port, so one instance per project just works. `--port N` binds exactly N and fails if taken; `--port 0` lets the OS choose. Also `SAGA_WEB_PORT`. |
+| `--host <addr>` | `127.0.0.1` | Bind address. Local-only by default. |
+| `--read-only` | off | Serve the UI with every editing control removed. |
+| `--open` | off | Open the UI in your default browser. |
 
-Nothing changes for epics nobody has arranged — those sort by priority exactly as before, and an
-explicit `sort_by` is always obeyed literally.
+Six tabs:
 
-Anything omitted from `ordered_ids` keeps its relative position at the end. `sort_order` runs
-ascending — lower sorts first — and a task created *after* an arrangement has no place in it, so it
-lands at the end rather than the front. In the web UI you can drag tasks into place inside an epic,
-and finished ones are struck through.
+- **Overview** — stats, per-epic progress, blocked and overdue tasks
+- **Board** — kanban across the five task statuses; drag a card to change its status
 
-Task dependencies auto-block and auto-unblock:
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/spranab/saga-mcp/master/docs/screenshots/board-dark.png">
+  <img alt="The board: five columns, one per task status" src="https://raw.githubusercontent.com/spranab/saga-mcp/master/docs/screenshots/board-light.png">
+</picture>
+
+- **Epics** — the full Epic → Task → Subtask tree, which is the fastest way to review a spec an
+  agent just wrote. Blocked tasks carry a ⛔ naming what they wait on, finished ones are struck
+  through, and tasks drag into order. Epics read the same way — bold while in progress, struck
+  through once completed or cancelled — and each one archives from here as well as the Overview
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/spranab/saga-mcp/master/docs/screenshots/epics-dark.png">
+  <img alt="The epic tree, with epics and tasks struck through once finished and blocked tasks marked" src="https://raw.githubusercontent.com/spranab/saga-mcp/master/docs/screenshots/epics-light.png">
+</picture>
+
+- **Notes** — decisions, context and blockers
+- **Templates** — every template with the tasks it creates and the `{placeholders}` it uses; edit
+  the details, edit the task list, apply it to an epic, or delete it
+- **Activity** — the complete change history
+
+And throughout:
+
+- **Task drawer** — edit any field, comment, remove or restore a comment, lock the description,
+  drag subtasks into order, and set which subtasks wait on which. Each subtask has one control
+  carrying its whole state (todo / in progress / done, or blocked), and the drawer resizes by
+  dragging its edge. Its Refresh/Edit/Close row stays pinned to the top however far you scroll,
+  as a long form keeps its Save button in view
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/spranab/saga-mcp/master/docs/screenshots/task-dark.png">
+  <img alt="The task drawer: subtasks with their state, dependencies both ways, and the comment thread" src="https://raw.githubusercontent.com/spranab/saga-mcp/master/docs/screenshots/task-light.png">
+</picture>
+
+- **Markdown** — descriptions, comments and notes render headings, tables, lists, code and links.
+  Agent-written content is escaped before any markdown rule runs, so raw HTML can never reach the
+  page, and only http/https/mailto links are followed
+- **Project switcher** — every project in the database, so one central `.tracker.db` covers all
+  your repos; every tab, including Activity, is scoped to the selected project
+- **Shareable, refreshable URLs** — the open project, tab and task live in the address bar, so a
+  browser refresh puts you back where you were and back/forward move between tasks. A ⟳ button in
+  the task drawer re-reads that task without a page reload, for picking up what an agent just wrote
 
-```
-task_update({ id: 9, depends_on: [8] })   # 9 becomes blocked while 8 is open
-```
+Writes from the UI call the *same handlers* the MCP tools do, so edits you make by hand are
+validated identically and land in the same activity log as the agent's — an agent calling
+`tracker_dashboard` after you fix something sees the fix and how it happened.
 
-Re-evaluation runs whenever a blocker's *doneness* changes in either direction, so reopening a
-finished blocker blocks its dependents again, and clearing the last dependency releases them.
-Circular dependencies are refused with the loop named, for tasks and subtasks alike — anything
-in a cycle would be blocked forever. The web UI shows a banner at the top of a blocked task
-naming what it waits on, with a picker to add or remove dependencies.
+A few deliberate limits: it binds to `127.0.0.1` unless you ask otherwise, it has no authentication
+(don't put it on a shared network), and it will not create a database — point it at one your MCP
+server already uses. Separate `.tracker.db` files are not yet aggregated into one view; a single
+database with multiple projects is.
 
-## Getting old work out of the way
+---
 
-An epic list that is mostly finished work, and tasks an agent created that should have been
-subtasks, are context you pay for on every call.
+## Token cost
 
-```
-epic_archive({ id: 4 })            # the epic and its tasks drop out of listings
-task_delete({ id: 12, reason: "should have been a subtask" })
-```
+The tool list is context every session pays before any work happens, and list responses are context
+it pays again on every call. Both are kept deliberately small:
 
-Archiving is deliberately **not** the `cancelled` status: `cancelled` means "we decided not to do
-this", while most of what you want to archive is *completed*. Archived epics and their tasks
-disappear from `epic_list`, `tracker_dashboard`, `task_list` and `tracker_search` — including the
-statistics, not just the lists — and come back with `include_archived`.
+- Responses are compact JSON — no pretty-print indentation, which measured 20-27% of every response
+- `task_list` rows omit nulls and `metadata`, and truncate descriptions to 120 characters
+  (call `task_get` for a task's full text) — 19-39% smaller depending on how long your descriptions run
+- `activity_log` omits null columns and the row id (no tool takes one) — about 27% smaller
+- `tracker_search` returns previews rather than whole records — about 47% smaller; follow up with
+  `task_get` or `note_list` for the full text
+- `SAGA_TOOLS=core` drops the listed surface from ~7,200 tokens to ~2,900
 
-Nothing vanishes silently. The dashboard says what it left out:
+`note_list` deliberately keeps full note content — it is the retrieval tool, not a preview.
 
-```
-Hidden: 2 archived epic(s) and 1 removed task(s) — pass include_archived to include them.
-```
+Set `SAGA_TOOLS=core` when an agent only tracks work; leave it unset when you want templates,
+import/export, session diffs and the rest discoverable. **Tools left off the list still work when
+called by name** — `core` shrinks what is advertised, not what exists.
 
-`task_delete` is the same soft delete comments have, restricted to tasks still in `todo`:
-anything further along has comments, time tracking and an activity log that removing it would
-strand, and a task other tasks depend on is refused outright so nothing is left blocked forever.
-The row is kept, `task_restore` brings it back, and `tracker_export` includes archived and removed
-rows because a backup that omits things is not a backup.
+The core thirteen: `tracker_init`, `tracker_next`, `tracker_dashboard`, `project_list`,
+`epic_create`, `epic_list`, `task_create`, `task_list`, `task_get`, `task_update`, `subtask_create`,
+`note_save`, `comment_add`.
 
-## Keeping agents on the rails
+Every tool description is held to a byte budget in the test suite, so the surface cannot grow by
+accretion: adding a tool means trimming prose elsewhere or justifying the increase.
 
-Two guards for the ways an agent goes wrong on a long task.
+---
 
-**A locked description.** Agents sometimes rewrite a task's description to record progress, when
-they meant to add a comment — and the spec you agreed on is gone. Lock it and `task_update` refuses:
+## Tool reference
 
-```
-task_lock_description({ id: 12 })
-task_update({ id: 12, description: "..." })
-  -> Task 12's description is locked and was not changed. Record progress with
-     comment_add instead, or unlock it in the web UI if the description is genuinely wrong.
-```
+### Getting started
 
-Everything else about the task stays editable — the point is to protect the spec, not freeze the
-task. The lock cannot be cleared as a side effect of an ordinary `task_update`; it takes a
-deliberate `task_lock_description` call or the lock toggle in the web UI, and both are logged.
-
-This is a guard against confusion, not an adversarial control: an agent that is told to unlock
-still can. It turns a silent overwrite into a visible, reversible decision.
-
-**Subtask order and dependencies.** New subtasks are appended in order rather than all landing at
-position 0, `subtask_reorder` sets the order in one call (or drag them in the UI), and a subtask
-can wait on its siblings:
-
-```
-subtask_update({ id: 8, depends_on: [5, 6] })    # 8 waits for 5 and 6
-subtask_update({ id: 4, blocks: [5, 6, 7, 8] })  # a bug that holds up the rest
-```
+| Tool | Description | Annotations |
+|------|-------------|-------------|
+| `tracker_init` | Initialize tracker and create first project | `readOnly: false`, `idempotent: true` |
+| `tracker_next` | What to work on next, with the reason and what is blocked | `readOnly: true` |
+| `tracker_dashboard` | Full project overview with natural language summary | `readOnly: true` |
 
-Reads carry `depends_on` and `blocked`, and the block is **enforced on write**: starting or
-finishing a subtask whose prerequisites are unmet is refused, and so is completing a task whose
-checklist is still open.
+### Projects
 
-```
-subtask_update({ id: 8, status: "in_progress" })
-  -> Subtask 8 cannot be started — it waits on #5 'write the parser' (todo).
-     Finish those first, or pass force: true to override deliberately (the override is logged).
-```
+| Tool | Description | Annotations |
+|------|-------------|-------------|
+| `project_create` | Create a new project | `readOnly: false` |
+| `project_list` | List projects with completion stats | `readOnly: true` |
+| `project_update` | Update project (archive to soft-delete) | `readOnly: false`, `idempotent: true` |
 
-`force: true` is the way past, for when a person has decided the blocker no longer applies. It
-works on `subtask_update`, `task_update` and `task_batch_update`, and every override is written to
-the activity log naming what was skipped. The web UI asks for confirmation and then sends it.
+### Epics
 
-The distinction that matters is between an agent quietly ignoring a blocker and someone choosing
-to override one. Dependencies stay
-within one task — a checklist item waiting on something under a *different* task is a task-level
-dependency, and `task_update depends_on` already models that. Cycles are refused with the loop
-spelled out.
+| Tool | Description | Annotations |
+|------|-------------|-------------|
+| `epic_create` | Create an epic within a project | `readOnly: false` |
+| `epic_list` | List epics with task counts | `readOnly: true` |
+| `epic_update` | Update an epic | `readOnly: false`, `idempotent: true` |
+| `epic_archive` | Archive/unarchive an epic, hiding it and its tasks from listings | `readOnly: false`, `idempotent: true` |
 
-## Web UI
+### Tasks
 
-Everything above is agent-facing. `saga-web` puts the same database in a browser — for the times
-when reviewing a spec an agent just wrote, or fixing one field by hand, is faster than another prompt.
+| Tool | Description | Annotations |
+|------|-------------|-------------|
+| `task_create` | Create a task with optional dependencies | `readOnly: false` |
+| `task_list` | List/filter tasks; follows a manual arrangement when one exists | `readOnly: true` |
+| `task_get` | Get task with subtasks, notes, comments, and dependencies | `readOnly: true` |
+| `task_update` | Update task (auto-logs, auto-blocks/unblocks) | `readOnly: false`, `idempotent: true` |
+| `task_batch_update` | Update multiple tasks at once | `readOnly: false`, `idempotent: true` |
+| `task_reorder` | Set the order of an epic's tasks | `readOnly: false`, `idempotent: true` |
+| `task_lock_description` | Lock/unlock a description so agents can't rewrite it | `readOnly: false`, `idempotent: true` |
+| `task_delete` | Remove a `todo` task (soft delete, restorable) | `readOnly: false`, `idempotent: true` |
+| `task_restore` | Restore a removed task | `readOnly: false`, `idempotent: true` |
 
+### Subtasks
 
-The **Templates** tab lists every template with the tasks it will create, the
-`{placeholders}` it uses, and buttons to edit the details, edit the task list as
-JSON, apply it to an epic, or delete it. Templates live in the database as a
-whole rather than in one project, and the tab says so.
+| Tool | Description | Annotations |
+|------|-------------|-------------|
+| `subtask_create` | Create subtask(s) — supports batch | `readOnly: false` |
+| `subtask_update` | Update title/status/position; `depends_on` and `blocks` set ordering | `readOnly: false`, `idempotent: true` |
+| `subtask_reorder` | Set the order of a task's subtasks in one call | `readOnly: false`, `idempotent: true` |
+| `subtask_delete` | Delete subtask(s) — supports batch | `destructive: true`, `idempotent: true` |
 
-```bash
-npx -p saga-mcp saga-web ./.tracker.db --open
-```
+### Comments
 
-Or against a database you already point your MCP server at:
+| Tool | Description | Annotations |
+|------|-------------|-------------|
+| `comment_add` | Add a comment to a task (threaded discussion) | `readOnly: false` |
+| `comment_list` | List comments on a task (removed ones hidden unless `include_deleted`) | `readOnly: true` |
+| `comment_delete` | Remove a comment — soft delete, row kept for audit | `readOnly: false`, `idempotent: true` |
+| `comment_restore` | Restore a removed comment | `readOnly: false`, `idempotent: true` |
 
-```bash
-saga-web --db ~/saga/central.tracker.db --port 8080
-```
+### Templates
 
-| Option | Default | Description |
-|--------|---------|-------------|
-| `--db <path>` | `$DB_PATH` | Database to open. A positional path works too. |
-| `--port <n>` | first free from `4319` | Omit it and saga-web takes the first free port, so one instance per project just works. `--port N` binds exactly N and fails if taken; `--port 0` lets the OS choose. Also `SAGA_WEB_PORT`. |
-| `--host <addr>` | `127.0.0.1` | Bind address. Local-only by default. |
-| `--read-only` | off | Serve the UI with every editing control removed. |
-| `--open` | off | Open the UI in your default browser. |
+| Tool | Description | Annotations |
+|------|-------------|-------------|
+| `template_create` | Create a reusable task template with `{variable}` placeholders | `readOnly: false` |
+| `template_list` | List templates; `include_tasks` shows what each one creates | `readOnly: true` |
+| `template_update` | Edit a template in place — name, description or tasks | `readOnly: false`, `idempotent: true` |
+| `template_apply` | Apply template to create tasks with variable substitution | `readOnly: false` |
+| `template_delete` | Delete a template | `destructive: true`, `idempotent: true` |
 
-What you get:
+### Notes
 
-- **Overview** — stats, per-epic progress, blocked and overdue tasks
-- **Board** — kanban across the five task statuses; drag a card to change its status
-- **Epics** — the full Epic → Task → Subtask tree, which is the fastest way to review a spec an agent just wrote
-- **Notes** and **Activity** — decisions and the complete change history
-- **Markdown** — descriptions, comments and notes render headings, tables, lists, code and links. Agent-written content is escaped before any markdown rule runs, so raw HTML can never reach the page, and only http/https/mailto links are followed
-- **Archived section** — archived epics collapse below a divider, with a "show archived (N)" toggle
-- **Task drawer** — edit any field, comment, remove or restore a comment, lock the description, drag subtasks into order, and set which subtasks wait on which. Each subtask has one control carrying its whole state (todo / in progress / done, or blocked), and the drawer resizes by dragging its edge
-- **Project switcher** — every project in the database, so one central `.tracker.db` covers all your repos; every tab, including Activity, is scoped to the selected project
-- **Shareable, refreshable URLs** — the open project, tab and task live in the address bar, so a browser refresh puts you back where you were and back/forward move between tasks. A ⟳ button in the task drawer re-reads that task without a page reload, for picking up what an agent just wrote
+| Tool | Description | Annotations |
+|------|-------------|-------------|
+| `note_save` | Create or update a note (upsert) | `readOnly: false` |
+| `note_list` | List notes with filters | `readOnly: true` |
+| `note_search` | Full-text search across notes | `readOnly: true` |
+| `note_delete` | Delete a note | `destructive: true`, `idempotent: true` |
 
-Writes from the UI call the *same handlers* the MCP tools do, so edits you make by hand are
-validated identically and land in the same activity log as the agent's — an agent calling
-`tracker_dashboard` after you fix something sees the fix and how it happened.
+### Search, history and transfer
 
-A few deliberate limits: it binds to `127.0.0.1` unless you ask otherwise, it has no
-authentication (don't put it on a shared network), and it will not create a database — point it
-at one your MCP server already uses. Separate `.tracker.db` files are not yet aggregated into
-one view; a single database with multiple projects is.
+| Tool | Description | Annotations |
+|------|-------------|-------------|
+| `tracker_search` | Cross-entity search (projects, epics, tasks, notes) | `readOnly: true` |
+| `activity_log` | View change history with filters | `readOnly: true` |
+| `tracker_session_diff` | What changed since a timestamp — call at session start | `readOnly: true` |
+| `tracker_export` | Export full project as nested JSON (includes dependencies and comments) | `readOnly: true` |
+| `tracker_import` | Import project from JSON (matching export format) | `readOnly: false` |
 
-## How It Works
+---
 
-saga-mcp stores everything in a single SQLite file (`.tracker.db`) per project. The database is auto-created on first use with all tables and indexes — no migration step needed.
+## How it works
 
-### Hierarchy
+Everything lives in a single SQLite file. The schema is created on first use, and existing
+databases are migrated in place when you upgrade — there is no migration step to run.
 
 ```
 Project
@@ -603,14 +615,7 @@ Project
               └── Dependencies (blocked by other tasks)
 ```
 
-### Task Dependencies
-
-Tasks can depend on other tasks. When you set `depends_on: [2, 3]` on a task:
-- The task is auto-blocked if any dependency isn't `done`
-- When a dependency is marked `done`, downstream tasks are re-evaluated
-- If all dependencies are met, the blocked task auto-unblocks to `todo`
-
-### Note Types
+### Note types
 
 Notes replace scattered markdown files. Each note has a type:
 
@@ -625,9 +630,9 @@ Notes replace scattered markdown files. Each note has a type:
 | `progress` | Progress updates |
 | `release` | Release notes |
 
-### Activity Log
+### Activity log
 
-Every create, update, and delete is automatically recorded:
+Every create, update and delete is recorded, with the old and new value:
 
 ```json
 {
@@ -642,18 +647,21 @@ Every create, update, and delete is automatically recorded:
 }
 ```
 
-## Privacy Policy
+That log is what makes the soft deletes safe and the time tracking automatic — hours are computed
+from it rather than entered by hand.
+
+---
 
-saga-mcp is a fully local, offline tool. It does **not**:
+## Privacy
 
-- Collect any user data
-- Send any data to external servers
-- Require internet access after installation
-- Use analytics, telemetry, or tracking of any kind
+saga-mcp is a fully local, offline tool. It does **not** collect user data, send anything to
+external servers, require internet access after installation, or use analytics or telemetry of any
+kind.
 
-All data is stored exclusively in the local SQLite file specified by `DB_PATH`. You own your data completely. Uninstalling saga-mcp and deleting the `.tracker.db` file removes all traces.
+All data is stored exclusively in the local SQLite file specified by `DB_PATH`. Uninstalling
+saga-mcp and deleting the `.tracker.db` file removes all traces.
 
-For questions about privacy, open an issue at https://github.com/spranab/saga-mcp/issues.
+---
 
 ## Development
 
@@ -667,10 +675,14 @@ DB_PATH=./test.db npm start
 # the web UI against the same database
 node dist/web/index.js ./test.db --open
 
-npm test     # unit and integration, ~140 tests, no network
+npm test     # 359 unit and integration tests, no network
 npm run e2e  # release gate: packs a tarball, installs it, drives the real binaries
 ```
 
+`npm test` runs against the built output. `npm run e2e` is the gate that matters before a release:
+it packs the tarball that would actually be published, installs it somewhere else, and drives both
+binaries over real stdio — 106 checks, including an upgrade from an older database.
+
 ### Releasing
 
 Publishing to npm is irreversible — a version number can never be reused — so it is the *last*
@@ -679,41 +691,45 @@ step, and it is triggered by publishing a GitHub release, not by pushing a tag.
 ```bash
 # 1. bump the version in package.json, manifest.json and server.json, then merge
 # 2. tag it. Nothing is published yet.
-git tag -a v1.9.0 -m "v1.9.0 — ..." && git push origin v1.9.0
+git tag -a v1.17.1 -m "v1.17.1 — ..." && git push origin v1.17.1
 
 # 3. verify the tagged build: this packs the tarball that would be published
 #    and drives it end to end, including an upgrade from an older database.
 npm run e2e
 
 # 4. publish the release. This fires the publish workflow.
-gh release create v1.9.0 --notes-file notes.md
+gh release create v1.17.1 --notes-file notes.md
 ```
 
 The workflow re-runs the suite against the tagged commit, refuses a tag that does not match
 `package.json`, refuses a version already on npm, and sends a GitHub *pre-release* to the `next`
 dist-tag so it never becomes what `npm install saga-mcp` gives people. A failed publish can be
-retried against the same tag with `gh workflow run "Publish to npm" -f tag=v1.9.0`.
+retried against the same tag with `gh workflow run "Publish to npm" -f tag=v1.17.1`.
+
+---
 
 ## Support
 
 - **Issues**: https://github.com/spranab/saga-mcp/issues
 - **Repository**: https://github.com/spranab/saga-mcp
 
+Bug reports that come with a reproduction are worth a great deal here — several of the sharper
+behaviours above exist because someone reported that the obvious thing was wrong.
+
 ## Related projects
 
-Part of a set of agent infrastructure built by one person, meant to be used
-together:
-
-- [yantrikdb-mcp](https://github.com/yantrikos/yantrikdb-mcp) — persistent
-  cognitive memory for the same agent: what it learned, not what it planned.
-- [brainstorm-mcp](https://github.com/spranab/brainstorm-mcp) — multi-model
-  debate before you commit a plan to the tracker.
-- [swarmcode](https://github.com/spranab/swarmcode) — real-time channel
-  between Claude Code instances on different machines.
-- [truenas-mcp](https://github.com/spranab/truenas-mcp) — 278 TrueNAS SCALE
-  actions behind one hierarchical tool.
-- [mcpier](https://github.com/spranab/mcpier) — self-hosted MCP control plane
-  that keeps API keys off your clients.
+Part of a set of agent infrastructure built by one person, meant to be used together:
+
+- [yantrikdb-mcp](https://github.com/yantrikos/yantrikdb-mcp) — persistent cognitive memory for the
+  same agent: what it learned, not what it planned.
+- [brainstorm-mcp](https://github.com/spranab/brainstorm-mcp) — multi-model debate before you commit
+  a plan to the tracker.
+- [swarmcode](https://github.com/spranab/swarmcode) — real-time channel between Claude Code
+  instances on different machines.
+- [truenas-mcp](https://github.com/spranab/truenas-mcp) — 278 TrueNAS SCALE actions behind one
+  hierarchical tool.
+- [mcpier](https://github.com/spranab/mcpier) — self-hosted MCP control plane that keeps API keys
+  off your clients.
 
 ## License