Update stale documentation (DEW-0009)

- index.md: rewrite architecture section to reflect DewToolCommand mixin, CommandRegistry, and per-package config extension pattern - config.md: update default columns to backlog/doing/done - features/mcp.md: replace McpToolProvider references with DewToolCommand, add all 12 tools to the table, add link types table - features/kanban.md: replace stub with full docs covering storage layout, ticket format, CLI command reference, link types, and config Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-04-23 19:56:08 -04:00 · 2026-04-23 19:56:08 -04:00 · 198d65b7e2
commit 198d65b7e2
parent a25411d4fa
5 changed files with 166 additions and 22 deletions
--- a/.project/kanban/backlog/DEW-0009.md
+++ b/.project/kanban/backlog/DEW-0009.md
--- a/docs/config.md
+++ b/docs/config.md
@ -34,11 +34,11 @@ dew:
        name: "Spike"

    columns:            # Ordered list of columns on your Kanban board
-      - id: "todo"
-        name: "To Do"
+      - id: "backlog"
+        name: "Backlog"
        color: "blue"
-      - id: "in-progress"
-        name: "In Progress"
+      - id: "doing"
+        name: "Doing"
        color: "yellow"
      - id: "done"
        name: "Done"
--- a/docs/features/kanban.md
+++ b/docs/features/kanban.md
@ -1,5 +1,105 @@
 # Dew Kanban Board

-The Dew Kanban Board is a feature that allows you to visualize your tasks and their progress. You can create columns for different stages of your workflow (e.g., To Do, In Progress, Done) and move tasks between them as you work on them.
+The Dew Kanban Board lets you create and manage tickets across a set of configurable columns. Every command is also registered as an MCP tool, so AI agents can interact with the board using the same operations as the CLI.

-The Kanban board is implemented in the `packages/kanban` package, which provides the necessary functionality to manage and display the board. You can customize the board's behavior and appearance through the `dew.yaml` configuration file.
+## Storage layout
+
+Tickets live inside the `.project/kanban/` directory. Each column has its own subdirectory, and attachments are stored separately by ticket ID so they survive column moves:
+
+```text
+.project/
+└── kanban/
+    ├── backlog/
+    │   └── DEW-0001.md
+    ├── doing/
+    │   └── DEW-0002.md
+    ├── done/
+    │   └── DEW-0003.md
+    ├── archive/            ← soft-deleted tickets (future)
+    └── attachments/
+        └── DEW-0001/       ← per-ticket attachment directory
+            └── screenshot.png
+```
+
+## Ticket format
+
+Each ticket is a Markdown file with a YAML frontmatter block. The column is derived from the containing directory and is not stored redundantly in the file.
+
+```markdown
+---
+id: DEW-0001
+title: "My ticket"
+type: story
+created: 2026-04-23T19:00:00.000Z
+links:
+  - id: DEW-0002
+    type: blocks
+---
+
+Body text goes here.
+
+---
+
+First comment.
+
+---
+
+Second comment.
+```
+
+## CLI commands
+
+All commands are available under `dew kanban <subcommand>`.
+
+| Subcommand | Description                                                     |
+| ---------- | --------------------------------------------------------------- |
+| `create`   | Create a new ticket (`--title`, `--type`, `--column`, `--body`) |
+| `list`     | List tickets (`--column`, `--type`)                             |
+| `get`      | Get a ticket by ID (`--id`)                                     |
+| `update`   | Update fields on a ticket (`--id`, `--title`, `--type`, `--column`, `--body`) |
+| `delete`   | Delete a ticket permanently (`--id`)                            |
+| `move`     | Move a ticket to a different column (`--id`, `--column`)        |
+| `search`   | Full-text search across all ticket content (`--query`)          |
+| `comment`  | Append a comment to a ticket (`--id`, `--comment`)              |
+| `config`   | Print the current kanban configuration                          |
+| `stats`    | Show ticket counts by column and type                           |
+| `link`     | Link two tickets with a typed relationship (`--id`, `--target`, `--type`) |
+| `unlink`   | Remove a link between two tickets (`--id`, `--target`)          |
+
+## Ticket links
+
+Links are typed and bidirectional — writing one side automatically writes the inverse on the target.
+
+| Type              | Inverse            | Use case                          |
+| ----------------- | ------------------ | --------------------------------- |
+| `blocks`          | `is_blocked_by`    | Dependency between tickets        |
+| `relates_to`      | `relates_to`       | General relationship (symmetric)  |
+| `duplicates`      | `is_duplicated_by` | Duplicate ticket tracking         |
+| `parent_of`       | `child_of`         | Epic → story → task hierarchy     |
+
+## Configuration
+
+Columns, ticket types, and the ticket ID prefix are configured in `.project/dew.yaml`:
+
+```yaml
+dew:
+  kanban:
+    prefix: "DEW"
+    ticket_types:
+      - id: epic
+        name: Epic
+      - id: story
+        name: Story
+    columns:
+      - id: backlog
+        name: Backlog
+        color: blue
+      - id: doing
+        name: Doing
+        color: yellow
+      - id: done
+        name: Done
+        color: green
+```
+
+See the [Configuration documentation](../config.md) for the full schema reference.
--- a/docs/features/mcp.md
+++ b/docs/features/mcp.md
@ -6,8 +6,12 @@ The Dew Model Context Protocol (MCP) Server is a feature that allows AI agents t

 The MCP feature is split across two packages to keep concerns separate:

- **`packages/core`** defines the `McpToolProvider` interface. Any feature package that wants to expose tools to AI agents implements this interface — without needing to depend on the MCP server itself.
- **`packages/mcp`** implements the actual server. It collects all registered `McpToolProvider` implementations and serves them over stdio using the [dart\_mcp](https://pub.dev/packages/dart_mcp) package. Only the `cli` package depends on `packages/mcp`; feature packages like `kanban` remain decoupled from the transport layer.
+- **`packages/core`** defines the `DewToolCommand` mixin. Any command that mixes it in is automatically
+  registered as an MCP tool — the mixin derives the tool's JSON Schema directly from the command's own
+  `ArgParser`, so tools and CLI commands share a single definition.
+- **`packages/mcp`** implements the actual server. It reads the list of tools from `CommandRegistry` and
+  serves them over stdio using the [dart\_mcp](https://pub.dev/packages/dart_mcp) package. Only the `cli`
+  package depends on `packages/mcp`; feature packages like `kanban` remain decoupled from the transport layer.

 ## Configuration

@ -55,10 +59,32 @@ The server logs its startup message to **stderr** so it never interferes with th

 The following tools are registered by the `kanban` package:

-| Tool                      | Description                                              |
-| ------------------------- | -------------------------------------------------------- |
-| `kanban_create_ticket`    | Create a new kanban ticket                               |
-| `kanban_list_tickets`     | List tickets, optionally filtered by column or type      |
-| `kanban_get_ticket`       | Get a ticket by ID                                       |
-| `kanban_update_ticket`    | Update one or more fields on an existing ticket          |
-| `kanban_delete_ticket`    | Delete a ticket by ID                                    |
+| Tool                      | Description                                                             |
+| ------------------------- | ----------------------------------------------------------------------- |
+| `kanban_create_ticket`    | Create a new kanban ticket                                              |
+| `kanban_list_tickets`     | List tickets, optionally filtered by column or type                     |
+| `kanban_get_ticket`       | Get details of a specific ticket by ID                                  |
+| `kanban_update_ticket`    | Update one or more fields on an existing ticket                         |
+| `kanban_delete_ticket`    | Delete a ticket permanently (also removes its attachment directory)     |
+| `kanban_move_ticket`      | Move a ticket to a different column                                     |
+| `kanban_search_tickets`   | Full-text search across ticket titles, bodies, and comments             |
+| `kanban_add_comment`      | Append a comment to a ticket                                            |
+| `kanban_get_config`       | Return the current kanban config (columns, types, prefix)               |
+| `kanban_stats`            | Show ticket counts grouped by column and type                           |
+| `kanban_link_tickets`     | Link two tickets with a typed relationship (bidirectional)              |
+| `kanban_unlink_tickets`   | Remove a link between two tickets (both sides)                          |
+
+### Link types
+
+`kanban_link_tickets` requires a `--type` argument. The inverse is written automatically on the target ticket.
+
+| Type              | Inverse           | Symmetric? |
+| ----------------- | ----------------- | ---------- |
+| `blocks`          | `is_blocked_by`   | No         |
+| `is_blocked_by`   | `blocks`          | No         |
+| `relates_to`      | `relates_to`      | Yes        |
+| `duplicates`      | `is_duplicated_by`| No         |
+| `is_duplicated_by`| `duplicates`      | No         |
+| `parent_of`       | `child_of`        | No         |
+| `child_of`        | `parent_of`       | No         |
+
--- a/docs/index.md
+++ b/docs/index.md
@ -15,11 +15,29 @@ Welcome to the documentation for the Dew project management tool!

 Dew is structured as a Dart workspace with the following packages:

-| Package           | Description                                                                                |
-| ----------------- | ------------------------------------------------------------------------------------------ |
-| `packages/cli`    | The `dew` command-line tool. Wires all packages together at startup.                       |
-| `packages/core`   | Shared types (tickets, columns, config) and the `McpToolProvider` interface.               |
-| `packages/kanban` | Kanban board logic. Implements `McpToolProvider` to expose its tools to the MCP server.    |
-| `packages/mcp`    | The MCP server. Depends on `core`; collects and serves registered tools from all packages. |
+| Package           | Description                                                                                     |
+| ----------------- | ----------------------------------------------------------------------------------------------- |
+| `packages/cli`    | The `dew` command-line tool. Wires all packages together at startup.                            |
+| `packages/core`   | Shared foundation: `DewCommand`, `DewToolCommand` mixin, `CommandRegistry`, and `DewConfig`.    |
+| `packages/kanban` | Kanban board logic. Each command automatically registers itself as an MCP tool.                 |
+| `packages/mcp`    | The MCP server. Collects tools from `CommandRegistry` and serves them over stdio.               |

-`kanban` (and future feature packages) depend only on `core` — not on `mcp` — keeping them usable independently of the AI integration layer. The `cli` package is the only one that depends on `mcp` and is responsible for starting the server and registering all providers.
+### How commands become MCP tools
+
+Every CLI command that mixes in `DewToolCommand` is automatically registered as an MCP tool — no separate registration needed. The mixin derives the JSON Schema for the tool's input from the command's own `ArgParser`, so argument definitions are written exactly once.
+
+```
+ArgParser definition
+      │
+      ├─► dew kanban create   (human CLI)
+      └─► kanban_create_ticket (MCP tool with schema)
+```
+
+### Config architecture
+
+`DewConfig` in `core` is a thin wrapper around the raw YAML map. Feature packages add typed accessors via Dart extensions:
+
+- `dew_kanban` defines `KanbanDewConfig` — exposes `context.config.kanban`
+- `dew_mcp` defines `McpDewConfig` — exposes `context.config.mcp`
+
+This keeps feature-specific config classes out of `core` while leaving all call sites unchanged.